Expose a WKWebView API for allowing programmatic focus to trigger node assistance
[WebKit-https.git] / Source / WebKit2 / 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 WK_API_ENABLED
29
30 #if TARGET_OS_IPHONE
31 #import <UIKit/UIKit.h>
32 #else
33 #import <AppKit/AppKit.h>
34 #endif
35
36 WK_ASSUME_NONNULL_BEGIN
37
38 @class WKBackForwardList;
39 @class WKBackForwardListItem;
40 @class WKNavigation;
41 @class WKWebViewConfiguration;
42
43 @protocol WKNavigationDelegate;
44 @protocol WKUIDelegate;
45
46 /*!
47  A WKWebView object displays interactive Web content.
48  @helperclass @link WKWebViewConfiguration @/link
49  Used to configure @link WKWebView @/link instances.
50  */
51 #if TARGET_OS_IPHONE
52 WK_CLASS_AVAILABLE(10_10, 8_0)
53 @interface WKWebView : UIView
54 #else
55 WK_CLASS_AVAILABLE(10_10, 8_0)
56 @interface WKWebView : NSView
57 #endif
58
59 /*! @abstract A copy of the configuration with which the web view was
60  initialized. */
61 @property (nonatomic, readonly, copy) WKWebViewConfiguration *configuration;
62
63 /*! @abstract The web view's navigation delegate. */
64 @property (WK_NULLABLE_PROPERTY nonatomic, weak) id <WKNavigationDelegate> navigationDelegate;
65
66 /*! @abstract The web view's user interface delegate. */
67 @property (WK_NULLABLE_PROPERTY nonatomic, weak) id <WKUIDelegate> UIDelegate;
68
69 /*! @abstract The web view's back-forward list. */
70 @property (nonatomic, readonly, strong) WKBackForwardList *backForwardList;
71
72 /*! @abstract Returns a web view initialized with a specified frame and
73  configuration.
74  @param frame The frame for the new web view.
75  @param configuration The configuration for the new web view.
76  @result An initialized web view, or nil if the object could not be
77  initialized.
78  @discussion This is a designated initializer. You can use
79  @link -initWithFrame: @/link to initialize an instance with the default
80  configuration. The initializer copies the specified configuration, so
81  mutating the configuration after invoking the initializer has no effect
82  on the web view.
83  */
84 - (instancetype)initWithFrame:(CGRect)frame configuration:(WKWebViewConfiguration *)configuration WK_DESIGNATED_INITIALIZER;
85
86 - (instancetype)initWithCoder:(NSCoder *)coder WK_UNAVAILABLE;
87
88 /*! @abstract Navigates to a requested URL.
89  @param request The request specifying the URL to which to navigate.
90  @result A new navigation for the given request.
91  */
92 - (WK_NULLABLE WKNavigation *)loadRequest:(NSURLRequest *)request;
93
94 /*! @abstract Navigates to the requested file URL on the filesystem.
95  @param URL The file URL to which to navigate.
96  @param readAccessURL The URL to allow read access to.
97  @discussion If readAccessURL references a single file, only that file may be loaded by WebKit.
98  If readAccessURL references a directory, files inside that file may be loaded by WebKit.
99  @result A new navigation for the given file URL.
100  */
101 - (WK_NULLABLE WKNavigation *)loadFileURL:(NSURL *)URL allowingReadAccessToURL:(NSURL *)readAccessURL WK_AVAILABLE(10_11, 9_0);
102
103 /*! @abstract Sets the webpage contents and base URL.
104  @param string The string to use as the contents of the webpage.
105  @param baseURL A URL that is used to resolve relative URLs within the document.
106  @result A new navigation.
107  */
108 - (WK_NULLABLE WKNavigation *)loadHTMLString:(NSString *)string baseURL:(WK_NULLABLE NSURL *)baseURL;
109
110 /*! @abstract Sets the webpage contents and base URL.
111  @param data The data to use as the contents of the webpage.
112  @param MIMEType The MIME type of the data.
113  @param encodingName The data's character encoding name.
114  @param baseURL A URL that is used to resolve relative URLs within the document.
115  @result A new navigation.
116  */
117 - (WK_NULLABLE WKNavigation *)loadData:(NSData *)data MIMEType:(NSString *)MIMEType characterEncodingName:(NSString *)characterEncodingName baseURL:(NSURL *)baseURL WK_AVAILABLE(10_11, 9_0);
118
119 /*! @abstract Navigates to an item from the back-forward list and sets it
120  as the current item.
121  @param item The item to which to navigate. Must be one of the items in the
122  web view's back-forward list.
123  @result A new navigation to the requested item, or nil if it is already
124  the current item or is not part of the web view's back-forward list.
125  @seealso backForwardList
126  */
127 - (WK_NULLABLE WKNavigation *)goToBackForwardListItem:(WKBackForwardListItem *)item;
128
129 /*! @abstract The page title.
130  @discussion @link WKWebView @/link is key-value observing (KVO) compliant
131  for this property.
132  */
133 @property (WK_NULLABLE_PROPERTY nonatomic, readonly, copy) NSString *title;
134
135 /*! @abstract The active URL.
136  @discussion This is the URL that should be reflected in the user
137  interface.
138  @link WKWebView @/link is key-value observing (KVO) compliant for this
139  property.
140  */
141 @property (WK_NULLABLE_PROPERTY nonatomic, readonly, copy) NSURL *URL;
142
143 /*! @abstract A Boolean value indicating whether the view is currently
144  loading content.
145  @discussion @link WKWebView @/link is key-value observing (KVO) compliant
146  for this property.
147  */
148 @property (nonatomic, readonly, getter=isLoading) BOOL loading;
149
150 /*! @abstract An estimate of what fraction of the current navigation has been completed.
151  @discussion This value ranges from 0.0 to 1.0 based on the total number of
152  bytes expected to be received, including the main document and all of its
153  potential subresources. After a navigation completes, the value remains at 1.0
154  until a new navigation starts, at which point it is reset to 0.0.
155  @link WKWebView @/link is key-value observing (KVO) compliant for this
156  property.
157  */
158 @property (nonatomic, readonly) double estimatedProgress;
159
160 /*! @abstract A Boolean value indicating whether all resources on the page
161  have been loaded over securely encrypted connections.
162  @discussion @link WKWebView @/link is key-value observing (KVO) compliant
163  for this property.
164  */
165 @property (nonatomic, readonly) BOOL hasOnlySecureContent;
166
167 /*! @abstract An array of SecCertificateRef objects forming the certificate
168  chain for the currently committed navigation.
169  @discussion The certificates are ordered from leaf (at index 0) to anchor.
170  @link WKWebView @/link is key-value observing (KVO) compliant for this property.
171  */
172 @property (nonatomic, readonly, copy) NSArray *certificateChain WK_AVAILABLE(10_11, 9_0);
173
174 /*! @abstract A Boolean value indicating whether there is a back item in
175  the back-forward list that can be navigated to.
176  @discussion @link WKWebView @/link is key-value observing (KVO) compliant
177  for this property.
178  @seealso backForwardList.
179  */
180 @property (nonatomic, readonly) BOOL canGoBack;
181
182 /*! @abstract A Boolean value indicating whether there is a forward item in
183  the back-forward list that can be navigated to.
184  @discussion @link WKWebView @/link is key-value observing (KVO) compliant
185  for this property.
186  @seealso backForwardList.
187  */
188 @property (nonatomic, readonly) BOOL canGoForward;
189
190 /*! @abstract Navigates to the back item in the back-forward list.
191  @result A new navigation to the requested item, or nil if there is no back
192  item in the back-forward list.
193  */
194 - (WK_NULLABLE WKNavigation *)goBack;
195
196 /*! @abstract Navigates to the forward item in the back-forward list.
197  @result A new navigation to the requested item, or nil if there is no
198  forward item in the back-forward list.
199  */
200 - (WK_NULLABLE WKNavigation *)goForward;
201
202 /*! @abstract Reloads the current page.
203  @result A new navigation representing the reload.
204  */
205 - (WK_NULLABLE WKNavigation *)reload;
206
207 /*! @abstract Reloads the current page, performing end-to-end revalidation
208  using cache-validating conditionals if possible.
209  @result A new navigation representing the reload.
210  */
211 - (WK_NULLABLE WKNavigation *)reloadFromOrigin;
212
213 /*! @abstract Stops loading all resources on the current page.
214  */
215 - (void)stopLoading;
216
217 /* @abstract Evaluates the given JavaScript string.
218  @param javaScriptString The JavaScript string to evaluate.
219  @param completionHandler A block to invoke when script evaluation completes or fails.
220  @discussion The completionHandler is passed the result of the script evaluation or an error.
221 */
222 - (void)evaluateJavaScript:(NSString *)javaScriptString completionHandler:(void (^ WK_NULLABLE_SPECIFIER)(WK_NULLABLE_SPECIFIER id, NSError * WK_NULLABLE_SPECIFIER error))completionHandler;
223
224 /*! @abstract A Boolean value indicating whether horizontal swipe gestures
225  will trigger back-forward list navigations.
226  @discussion The default value is NO.
227  */
228 @property (nonatomic) BOOL allowsBackForwardNavigationGestures;
229
230 /*! @abstract The custom user agent string or nil if no custom user agent string has been set.
231 */
232 @property (WK_NULLABLE_PROPERTY nonatomic, copy) NSString *customUserAgent WK_AVAILABLE(10_11, 9_0);
233
234 /*! @abstract A Boolean value indicating whether link preview is allowed for any
235  links inside this WKWebView.
236  @discussion The default value is NO on iOS and YES on Mac.
237  */
238 @property (nonatomic) BOOL allowsLinkPreview WK_AVAILABLE(10_11, 9_0);
239
240 #if TARGET_OS_IPHONE
241 /*! @abstract The scroll view associated with the web view.
242  */
243 @property (nonatomic, readonly, strong) UIScrollView *scrollView;
244
245 /*! @abstract A Boolean value indicating whether programmatic focus on
246  an element is allowed to trigger assistance.
247  */
248 @property (nonatomic) BOOL canAssistOnProgrammaticFocus;
249 #endif
250
251 #if !TARGET_OS_IPHONE
252 /* @abstract A Boolean value indicating whether magnify gestures will
253  change the web view's magnification.
254  @discussion It is possible to set the magnification property even if
255  allowsMagnification is set to NO.
256  The default value is NO.
257  */
258 @property (nonatomic) BOOL allowsMagnification;
259
260 /* @abstract The factor by which the page content is currently scaled.
261  @discussion The default value is 1.0.
262  */
263 @property (nonatomic) CGFloat magnification;
264
265 /* @abstract Scales the page content by a specified factor and centers the
266  result on a specified point.
267  * @param magnification The factor by which to scale the content.
268  * @param point The point (in view space) on which to center magnification.
269  */
270 - (void)setMagnification:(CGFloat)magnification centeredAtPoint:(CGPoint)point;
271
272 #endif
273
274 @end
275
276 #if !TARGET_OS_IPHONE
277
278 @interface WKWebView (WKIBActions) <NSUserInterfaceValidations>
279
280 /*! @abstract Action method that navigates to the back item in the
281  back-forward list.
282  @param sender The object that sent this message.
283  */
284 - (IBAction)goBack:(WK_NULLABLE id)sender;
285
286 /*! @abstract Action method that navigates to the forward item in the
287  back-forward list.
288  @param sender The object that sent this message.
289  */
290 - (IBAction)goForward:(WK_NULLABLE id)sender;
291
292 /*! @abstract Action method that reloads the current page.
293  @param sender The object that sent this message.
294  */
295 - (IBAction)reload:(WK_NULLABLE id)sender;
296
297 /*! @abstract Action method that reloads the current page, performing
298  end-to-end revalidation using cache-validating conditionals if possible.
299  @param sender The object that sent this message.
300  */
301 - (IBAction)reloadFromOrigin:(WK_NULLABLE id)sender;
302
303 /*! @abstract Action method that stops loading all resources on the current
304  page.
305  @param sender The object that sent this message.
306  */
307 - (IBAction)stopLoading:(WK_NULLABLE id)sender;
308
309 @end
310
311 #endif
312
313 WK_ASSUME_NONNULL_END
314
315 #endif