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