Unreviewed, fix iOS build with recent SDKs.
[WebKit-https.git] / Source / WebKit / UIProcess / API / Cocoa / WKWebView.h
1 /*
2  * Copyright (C) 2014 Apple Inc. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * 1. Redistributions of source code must retain the above copyright
8  *    notice, this list of conditions and the following disclaimer.
9  * 2. Redistributions in binary form must reproduce the above copyright
10  *    notice, this list of conditions and the following disclaimer in the
11  *    documentation and/or other materials provided with the distribution.
12  *
13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
14  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
15  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
17  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
19  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
20  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
21  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
22  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
23  * THE POSSIBILITY OF SUCH DAMAGE.
24  */
25
26 #import <WebKit/WKFoundation.h>
27
28 #if TARGET_OS_IPHONE
29 #import <UIKit/UIKit.h>
30 #else
31 #import <AppKit/AppKit.h>
32 #endif
33
34 NS_ASSUME_NONNULL_BEGIN
35
36 @class WKBackForwardList;
37 @class WKBackForwardListItem;
38 @class WKNavigation;
39 @class WKSnapshotConfiguration;
40 @class WKWebViewConfiguration;
41
42 @protocol WKNavigationDelegate;
43 @protocol WKUIDelegate;
44
45 /*!
46  A WKWebView object displays interactive Web content.
47  @helperclass @link WKWebViewConfiguration @/link
48  Used to configure @link WKWebView @/link instances.
49  */
50 #if TARGET_OS_IPHONE
51 WK_CLASS_AVAILABLE(macos(10.10), ios(8.0))
52 @interface WKWebView : UIView
53 #else
54 WK_CLASS_AVAILABLE(macos(10.10), ios(8.0))
55 @interface WKWebView : NSView
56 #endif
57
58 /*! @abstract A copy of the configuration with which the web view was
59  initialized. */
60 @property (nonatomic, readonly, copy) WKWebViewConfiguration *configuration;
61
62 /*! @abstract The web view's navigation delegate. */
63 @property (nullable, nonatomic, weak) id <WKNavigationDelegate> navigationDelegate;
64
65 /*! @abstract The web view's user interface delegate. */
66 @property (nullable, nonatomic, weak) id <WKUIDelegate> UIDelegate;
67
68 /*! @abstract The web view's back-forward list. */
69 @property (nonatomic, readonly, strong) WKBackForwardList *backForwardList;
70
71 /*! @abstract Returns a web view initialized with a specified frame and
72  configuration.
73  @param frame The frame for the new web view.
74  @param configuration The configuration for the new web view.
75  @result An initialized web view, or nil if the object could not be
76  initialized.
77  @discussion This is a designated initializer. You can use
78  @link -initWithFrame: @/link to initialize an instance with the default
79  configuration. The initializer copies the specified configuration, so
80  mutating the configuration after invoking the initializer has no effect
81  on the web view.
82  */
83 - (instancetype)initWithFrame:(CGRect)frame configuration:(WKWebViewConfiguration *)configuration NS_DESIGNATED_INITIALIZER;
84
85 - (nullable instancetype)initWithCoder:(NSCoder *)coder NS_DESIGNATED_INITIALIZER;
86
87 /*! @abstract Navigates to a requested URL.
88  @param request The request specifying the URL to which to navigate.
89  @result A new navigation for the given request.
90  */
91 - (nullable WKNavigation *)loadRequest:(NSURLRequest *)request;
92
93 /*! @abstract Navigates to the requested file URL on the filesystem.
94  @param URL The file URL to which to navigate.
95  @param readAccessURL The URL to allow read access to.
96  @discussion If readAccessURL references a single file, only that file may be loaded by WebKit.
97  If readAccessURL references a directory, files inside that file may be loaded by WebKit.
98  @result A new navigation for the given file URL.
99  */
100 - (nullable WKNavigation *)loadFileURL:(NSURL *)URL allowingReadAccessToURL:(NSURL *)readAccessURL WK_API_AVAILABLE(macos(10.11), ios(9.0));
101
102 /*! @abstract Sets the webpage contents and base URL.
103  @param string The string to use as the contents of the webpage.
104  @param baseURL A URL that is used to resolve relative URLs within the document.
105  @result A new navigation.
106  */
107 - (nullable WKNavigation *)loadHTMLString:(NSString *)string baseURL:(nullable NSURL *)baseURL;
108
109 /*! @abstract Sets the webpage contents and base URL.
110  @param data The data to use as the contents of the webpage.
111  @param MIMEType The MIME type of the data.
112  @param characterEncodingName The data's character encoding name.
113  @param baseURL A URL that is used to resolve relative URLs within the document.
114  @result A new navigation.
115  */
116 - (nullable WKNavigation *)loadData:(NSData *)data MIMEType:(NSString *)MIMEType characterEncodingName:(NSString *)characterEncodingName baseURL:(NSURL *)baseURL WK_API_AVAILABLE(macos(10.11), ios(9.0));
117
118 /*! @abstract Navigates to an item from the back-forward list and sets it
119  as the current item.
120  @param item The item to which to navigate. Must be one of the items in the
121  web view's back-forward list.
122  @result A new navigation to the requested item, or nil if it is already
123  the current item or is not part of the web view's back-forward list.
124  @seealso backForwardList
125  */
126 - (nullable WKNavigation *)goToBackForwardListItem:(WKBackForwardListItem *)item;
127
128 /*! @abstract The page title.
129  @discussion @link WKWebView @/link is key-value observing (KVO) compliant
130  for this property.
131  */
132 @property (nullable, nonatomic, readonly, copy) NSString *title;
133
134 /*! @abstract The active URL.
135  @discussion This is the URL that should be reflected in the user
136  interface.
137  @link WKWebView @/link is key-value observing (KVO) compliant for this
138  property.
139  */
140 @property (nullable, nonatomic, readonly, copy) NSURL *URL;
141
142 /*! @abstract A Boolean value indicating whether the view is currently
143  loading content.
144  @discussion @link WKWebView @/link is key-value observing (KVO) compliant
145  for this property.
146  */
147 @property (nonatomic, readonly, getter=isLoading) BOOL loading;
148
149 /*! @abstract An estimate of what fraction of the current navigation has been completed.
150  @discussion This value ranges from 0.0 to 1.0 based on the total number of
151  bytes expected to be received, including the main document and all of its
152  potential subresources. After a navigation completes, the value remains at 1.0
153  until a new navigation starts, at which point it is reset to 0.0.
154  @link WKWebView @/link is key-value observing (KVO) compliant for this
155  property.
156  */
157 @property (nonatomic, readonly) double estimatedProgress;
158
159 /*! @abstract A Boolean value indicating whether all resources on the page
160  have been loaded over securely encrypted connections.
161  @discussion @link WKWebView @/link is key-value observing (KVO) compliant
162  for this property.
163  */
164 @property (nonatomic, readonly) BOOL hasOnlySecureContent;
165
166 /*! @abstract A SecTrustRef for the currently committed navigation.
167  @discussion @link WKWebView @/link is key-value observing (KVO) compliant 
168  for this property.
169  */
170 @property (nonatomic, readonly, nullable) SecTrustRef serverTrust WK_API_AVAILABLE(macos(10.12), ios(10.0));
171
172 /*! @abstract A Boolean value indicating whether there is a back item in
173  the back-forward list that can be navigated to.
174  @discussion @link WKWebView @/link is key-value observing (KVO) compliant
175  for this property.
176  @seealso backForwardList.
177  */
178 @property (nonatomic, readonly) BOOL canGoBack;
179
180 /*! @abstract A Boolean value indicating whether there is a forward item in
181  the back-forward list that can be navigated to.
182  @discussion @link WKWebView @/link is key-value observing (KVO) compliant
183  for this property.
184  @seealso backForwardList.
185  */
186 @property (nonatomic, readonly) BOOL canGoForward;
187
188 /*! @abstract Navigates to the back item in the back-forward list.
189  @result A new navigation to the requested item, or nil if there is no back
190  item in the back-forward list.
191  */
192 - (nullable WKNavigation *)goBack;
193
194 /*! @abstract Navigates to the forward item in the back-forward list.
195  @result A new navigation to the requested item, or nil if there is no
196  forward item in the back-forward list.
197  */
198 - (nullable WKNavigation *)goForward;
199
200 /*! @abstract Reloads the current page.
201  @result A new navigation representing the reload.
202  */
203 - (nullable WKNavigation *)reload;
204
205 /*! @abstract Reloads the current page, performing end-to-end revalidation
206  using cache-validating conditionals if possible.
207  @result A new navigation representing the reload.
208  */
209 - (nullable WKNavigation *)reloadFromOrigin;
210
211 /*! @abstract Stops loading all resources on the current page.
212  */
213 - (void)stopLoading;
214
215 /* @abstract Evaluates the given JavaScript string.
216  @param javaScriptString The JavaScript string to evaluate.
217  @param completionHandler A block to invoke when script evaluation completes or fails.
218  @discussion The completionHandler is passed the result of the script evaluation or an error.
219 */
220 - (void)evaluateJavaScript:(NSString *)javaScriptString completionHandler:(void (^ _Nullable)(_Nullable id, NSError * _Nullable error))completionHandler;
221
222 /*! @abstract Get a snapshot for the visible viewport of WKWebView.
223  @param snapshotConfiguration An object that specifies how the snapshot is configured.
224  @param completionHandler A block to invoke when the snapshot is ready.
225  @discussion If the WKSnapshotConfiguration is nil, the method will snapshot the bounds of the 
226  WKWebView and create an image that is the width of the bounds of the WKWebView and scaled to the 
227  device scale. The completionHandler is passed the image of the viewport contents or an error.
228  */
229 #if TARGET_OS_IPHONE
230 - (void)takeSnapshotWithConfiguration:(nullable WKSnapshotConfiguration *)snapshotConfiguration completionHandler:(void (^)(UIImage * _Nullable snapshotImage, NSError * _Nullable error))completionHandler WK_API_AVAILABLE(ios(11.0));
231 #else
232 - (void)takeSnapshotWithConfiguration:(nullable WKSnapshotConfiguration *)snapshotConfiguration completionHandler:(void (^)(NSImage * _Nullable snapshotImage, NSError * _Nullable error))completionHandler WK_API_AVAILABLE(macos(10.13));
233 #endif
234
235 /*! @abstract A Boolean value indicating whether horizontal swipe gestures
236  will trigger back-forward list navigations.
237  @discussion The default value is NO.
238  */
239 @property (nonatomic) BOOL allowsBackForwardNavigationGestures;
240
241 /*! @abstract The custom user agent string or nil if no custom user agent string has been set.
242 */
243 @property (nullable, nonatomic, copy) NSString *customUserAgent WK_API_AVAILABLE(macos(10.11), ios(9.0));
244
245 /*! @abstract A Boolean value indicating whether link preview is allowed for any
246  links inside this WKWebView.
247  @discussion The default value is YES on Mac and iOS.
248  */
249 @property (nonatomic) BOOL allowsLinkPreview WK_API_AVAILABLE(macos(10.11), ios(9.0));
250
251 #if TARGET_OS_IPHONE
252 /*! @abstract The scroll view associated with the web view.
253  */
254 @property (nonatomic, readonly, strong) UIScrollView *scrollView;
255 #endif
256
257 #if !TARGET_OS_IPHONE
258 /* @abstract A Boolean value indicating whether magnify gestures will
259  change the web view's magnification.
260  @discussion It is possible to set the magnification property even if
261  allowsMagnification is set to NO.
262  The default value is NO.
263  */
264 @property (nonatomic) BOOL allowsMagnification;
265
266 /* @abstract The factor by which the page content is currently scaled.
267  @discussion The default value is 1.0.
268  */
269 @property (nonatomic) CGFloat magnification;
270
271 /* @abstract Scales the page content by a specified factor and centers the
272  result on a specified point.
273  * @param magnification The factor by which to scale the content.
274  * @param point The point (in view space) on which to center magnification.
275  */
276 - (void)setMagnification:(CGFloat)magnification centeredAtPoint:(CGPoint)point;
277
278 #endif
279
280 /* @abstract Checks whether or not WKWebViews handle the given URL scheme by default.
281  @param scheme The URL scheme to check.
282  */
283 + (BOOL)handlesURLScheme:(NSString *)urlScheme WK_API_AVAILABLE(macos(10.13), ios(11.0));
284
285 @end
286
287 #if !TARGET_OS_IPHONE
288
289 @interface WKWebView (WKIBActions) <NSUserInterfaceValidations>
290
291 /*! @abstract Action method that navigates to the back item in the
292  back-forward list.
293  @param sender The object that sent this message.
294  */
295 - (IBAction)goBack:(nullable id)sender;
296
297 /*! @abstract Action method that navigates to the forward item in the
298  back-forward list.
299  @param sender The object that sent this message.
300  */
301 - (IBAction)goForward:(nullable id)sender;
302
303 /*! @abstract Action method that reloads the current page.
304  @param sender The object that sent this message.
305  */
306 - (IBAction)reload:(nullable id)sender;
307
308 /*! @abstract Action method that reloads the current page, performing
309  end-to-end revalidation using cache-validating conditionals if possible.
310  @param sender The object that sent this message.
311  */
312 - (IBAction)reloadFromOrigin:(nullable id)sender;
313
314 /*! @abstract Action method that stops loading all resources on the current
315  page.
316  @param sender The object that sent this message.
317  */
318 - (IBAction)stopLoading:(nullable id)sender;
319
320 @end
321
322 #endif
323
324 @interface WKWebView (WKDeprecated)
325
326 @property (nonatomic, readonly, copy) NSArray *certificateChain WK_API_DEPRECATED_WITH_REPLACEMENT("serverTrust", macos(10.11, 10.12), ios(9.0, 10.0));
327
328 @end
329
330 NS_ASSUME_NONNULL_END