Source/WebKit2/UIProcess/API/Cocoa/WKUIDelegate.h - WebKit - Git at Google

 /*
  * Copyright (C) 2014 Apple Inc. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
  *    documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  * THE POSSIBILITY OF SUCH DAMAGE.
  */

 #import <WebKit/WKFoundation.h>

 #if WK_API_ENABLED

 #import <Foundation/Foundation.h>
 #import <WebKit/WKPreviewActionItem.h>

 NS_ASSUME_NONNULL_BEGIN

 @class WKFrameInfo;
 @class WKNavigationAction;
 @class WKPreviewElementInfo;
 @class WKWebViewConfiguration;
 @class WKWindowFeatures;

 /*! A class conforming to the WKUIDelegate protocol provides methods for
  presenting native UI on behalf of a webpage.
  */
 @protocol WKUIDelegate <NSObject>

 @optional

 /*! @abstract Creates a new web view.
  @param webView The web view invoking the delegate method.
  @param configuration The configuration to use when creating the new web
  view.
  @param navigationAction The navigation action causing the new web view to
  be created.
  @param windowFeatures Window features requested by the webpage.
  @result A new web view or nil.
  @discussion The web view returned must be created with the specified configuration. WebKit will load the request in the returned web view.

  If you do not implement this method, the web view will cancel the navigation.
  */
 - (nullable WKWebView *)webView:(WKWebView *)webView createWebViewWithConfiguration:(WKWebViewConfiguration *)configuration forNavigationAction:(WKNavigationAction *)navigationAction windowFeatures:(WKWindowFeatures *)windowFeatures;

 /*! @abstract Notifies your app that the DOM window object's close() method completed successfully.
   @param webView The web view invoking the delegate method.
   @discussion Your app should remove the web view from the view hierarchy and update
   the UI as needed, such as by closing the containing browser tab or window.
   */
 - (void)webViewDidClose:(WKWebView *)webView WK_AVAILABLE(10_11, 9_0);

 /*! @abstract Displays a JavaScript alert panel.
  @param webView The web view invoking the delegate method.
  @param message The message to display.
  @param frame Information about the frame whose JavaScript initiated this
  call.
  @param completionHandler The completion handler to call after the alert
  panel has been dismissed.
  @discussion For user security, your app should call attention to the fact
  that a specific website controls the content in this panel. A simple forumla
  for identifying the controlling website is frame.request.URL.host.
  The panel should have a single OK button.

  If you do not implement this method, the web view will behave as if the user selected the OK button.
  */
 - (void)webView:(WKWebView *)webView runJavaScriptAlertPanelWithMessage:(NSString *)message initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(void))completionHandler;

 /*! @abstract Displays a JavaScript confirm panel.
  @param webView The web view invoking the delegate method.
  @param message The message to display.
  @param frame Information about the frame whose JavaScript initiated this call.
  @param completionHandler The completion handler to call after the confirm
  panel has been dismissed. Pass YES if the user chose OK, NO if the user
  chose Cancel.
  @discussion For user security, your app should call attention to the fact
  that a specific website controls the content in this panel. A simple forumla
  for identifying the controlling website is frame.request.URL.host.
  The panel should have two buttons, such as OK and Cancel.

  If you do not implement this method, the web view will behave as if the user selected the Cancel button.
  */
 - (void)webView:(WKWebView *)webView runJavaScriptConfirmPanelWithMessage:(NSString *)message initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(BOOL result))completionHandler;

 /*! @abstract Displays a JavaScript text input panel.
  @param webView The web view invoking the delegate method.
  @param message The message to display.
  @param defaultText The initial text to display in the text entry field.
  @param frame Information about the frame whose JavaScript initiated this call.
  @param completionHandler The completion handler to call after the text
  input panel has been dismissed. Pass the entered text if the user chose
  OK, otherwise nil.
  @discussion For user security, your app should call attention to the fact
  that a specific website controls the content in this panel. A simple forumla
  for identifying the controlling website is frame.request.URL.host.
  The panel should have two buttons, such as OK and Cancel, and a field in
  which to enter text.

  If you do not implement this method, the web view will behave as if the user selected the Cancel button.
  */
 - (void)webView:(WKWebView *)webView runJavaScriptTextInputPanelWithPrompt:(NSString *)prompt defaultText:(nullable NSString *)defaultText initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(NSString * WK_NULLABLE_SPECIFIER result))completionHandler;

 #if TARGET_OS_IPHONE

 /*! @abstract Allows your app to determine whether or not the given element should show a preview.
  @param webView The web view invoking the delegate method.
  @param elementInfo The elementInfo for the element the user has started touching.
  @discussion To disable previews entirely for the given element, return NO. Returning NO will prevent
  webView:previewingViewControllerForElement:defaultActions: and webView:commitPreviewingViewController:
  from being invoked.

  This method will only be invoked for elements that have default preview in WebKit, which is
  limited to links. In the future, it could be invoked for additional elements.
  */
 - (BOOL)webView:(WKWebView *)webView shouldPreviewElement:(WKPreviewElementInfo *)elementInfo WK_AVAILABLE(NA, WK_IOS_TBA);

 /*! @abstract Allows your app to provide a custom view controller to show when the given element is peeked.
  @param webView The web view invoking the delegate method.
  @param elementInfo The elementInfo for the element the user is peeking.
  @param defaultActions An array of the actions that WebKit would use as previewActionItems for this element by
  default. These actions would be used if allowsLinkPreview is YES but these delegate methods have not been
  implemented, or if this delegate method returns nil.
  @discussion Returning a view controller will result in that view controller being displayed as a peek preview.
  To use the defaultActions, your app is responsible for returning whichever of those actions it wants in your
  view controller's implementation of -previewActionItems.

  Returning nil will result in WebKit's default preview behavior. webView:commitPreviewingViewController: will only be invoked
  if a non-nil view controller was returned.
  */
 - (nullable UIViewController *)webView:(WKWebView *)webView previewingViewControllerForElement:(WKPreviewElementInfo *)elementInfo defaultActions:(NSArray <id <WKPreviewActionItem>> *)previewActions WK_AVAILABLE(NA, WK_IOS_TBA);

 /*! @abstract Allows your app to pop to the view controller it created.
  @param webView The web view invoking the delegate method.
  @param previewingViewController The view controller that is being popped.
  */
 - (void)webView:(WKWebView *)webView commitPreviewingViewController:(UIViewController *)previewingViewController WK_AVAILABLE(NA, WK_IOS_TBA);

 #endif // TARGET_OS_IPHONE

 @end

 NS_ASSUME_NONNULL_END

 #endif
	/*
	* Copyright (C) 2014 Apple Inc. All rights reserved.
	*
	* Redistribution and use in source and binary forms, with or without
	* modification, are permitted provided that the following conditions
	* are met:
	* 1. Redistributions of source code must retain the above copyright
	* notice, this list of conditions and the following disclaimer.
	* 2. Redistributions in binary form must reproduce the above copyright
	* notice, this list of conditions and the following disclaimer in the
	* documentation and/or other materials provided with the distribution.
	*
	* THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
	* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
	* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
	* BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
	* THE POSSIBILITY OF SUCH DAMAGE.
	*/

	#import <WebKit/WKFoundation.h>

	#if WK_API_ENABLED

	#import <Foundation/Foundation.h>
	#import <WebKit/WKPreviewActionItem.h>

	NS_ASSUME_NONNULL_BEGIN

	@class WKFrameInfo;
	@class WKNavigationAction;
	@class WKPreviewElementInfo;
	@class WKWebViewConfiguration;
	@class WKWindowFeatures;

	/*! A class conforming to the WKUIDelegate protocol provides methods for
	presenting native UI on behalf of a webpage.
	*/
	@protocol WKUIDelegate <NSObject>

	@optional

	/*! @abstract Creates a new web view.
	@param webView The web view invoking the delegate method.
	@param configuration The configuration to use when creating the new web
	view.
	@param navigationAction The navigation action causing the new web view to
	be created.
	@param windowFeatures Window features requested by the webpage.
	@result A new web view or nil.
	@discussion The web view returned must be created with the specified configuration. WebKit will load the request in the returned web view.

	If you do not implement this method, the web view will cancel the navigation.
	*/
	- (nullable WKWebView )webView:(WKWebView )webView createWebViewWithConfiguration:(WKWebViewConfiguration )configuration forNavigationAction:(WKNavigationAction )navigationAction windowFeatures:(WKWindowFeatures *)windowFeatures;

	/*! @abstract Notifies your app that the DOM window object's close() method completed successfully.
	@param webView The web view invoking the delegate method.
	@discussion Your app should remove the web view from the view hierarchy and update
	the UI as needed, such as by closing the containing browser tab or window.
	*/
	- (void)webViewDidClose:(WKWebView *)webView WK_AVAILABLE(10_11, 9_0);

	/*! @abstract Displays a JavaScript alert panel.
	@param webView The web view invoking the delegate method.
	@param message The message to display.
	@param frame Information about the frame whose JavaScript initiated this
	call.
	@param completionHandler The completion handler to call after the alert
	panel has been dismissed.
	@discussion For user security, your app should call attention to the fact
	that a specific website controls the content in this panel. A simple forumla
	for identifying the controlling website is frame.request.URL.host.
	The panel should have a single OK button.

	If you do not implement this method, the web view will behave as if the user selected the OK button.
	*/
	- (void)webView:(WKWebView )webView runJavaScriptAlertPanelWithMessage:(NSString )message initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(void))completionHandler;

	/*! @abstract Displays a JavaScript confirm panel.
	@param webView The web view invoking the delegate method.
	@param message The message to display.
	@param frame Information about the frame whose JavaScript initiated this call.
	@param completionHandler The completion handler to call after the confirm
	panel has been dismissed. Pass YES if the user chose OK, NO if the user
	chose Cancel.
	@discussion For user security, your app should call attention to the fact
	that a specific website controls the content in this panel. A simple forumla
	for identifying the controlling website is frame.request.URL.host.
	The panel should have two buttons, such as OK and Cancel.

	If you do not implement this method, the web view will behave as if the user selected the Cancel button.
	*/
	- (void)webView:(WKWebView )webView runJavaScriptConfirmPanelWithMessage:(NSString )message initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(BOOL result))completionHandler;

	/*! @abstract Displays a JavaScript text input panel.
	@param webView The web view invoking the delegate method.
	@param message The message to display.
	@param defaultText The initial text to display in the text entry field.
	@param frame Information about the frame whose JavaScript initiated this call.
	@param completionHandler The completion handler to call after the text
	input panel has been dismissed. Pass the entered text if the user chose
	OK, otherwise nil.
	@discussion For user security, your app should call attention to the fact
	that a specific website controls the content in this panel. A simple forumla
	for identifying the controlling website is frame.request.URL.host.
	The panel should have two buttons, such as OK and Cancel, and a field in
	which to enter text.

	If you do not implement this method, the web view will behave as if the user selected the Cancel button.
	*/
	- (void)webView:(WKWebView )webView runJavaScriptTextInputPanelWithPrompt:(NSString )prompt defaultText:(nullable NSString )defaultText initiatedByFrame:(WKFrameInfo )frame completionHandler:(void (^)(NSString * WK_NULLABLE_SPECIFIER result))completionHandler;

	#if TARGET_OS_IPHONE

	/*! @abstract Allows your app to determine whether or not the given element should show a preview.
	@param webView The web view invoking the delegate method.
	@param elementInfo The elementInfo for the element the user has started touching.
	@discussion To disable previews entirely for the given element, return NO. Returning NO will prevent
	webView:previewingViewControllerForElement:defaultActions: and webView:commitPreviewingViewController:
	from being invoked.

	This method will only be invoked for elements that have default preview in WebKit, which is
	limited to links. In the future, it could be invoked for additional elements.
	*/
	- (BOOL)webView:(WKWebView )webView shouldPreviewElement:(WKPreviewElementInfo )elementInfo WK_AVAILABLE(NA, WK_IOS_TBA);

	/*! @abstract Allows your app to provide a custom view controller to show when the given element is peeked.
	@param webView The web view invoking the delegate method.
	@param elementInfo The elementInfo for the element the user is peeking.
	@param defaultActions An array of the actions that WebKit would use as previewActionItems for this element by
	default. These actions would be used if allowsLinkPreview is YES but these delegate methods have not been
	implemented, or if this delegate method returns nil.
	@discussion Returning a view controller will result in that view controller being displayed as a peek preview.
	To use the defaultActions, your app is responsible for returning whichever of those actions it wants in your
	view controller's implementation of -previewActionItems.

	Returning nil will result in WebKit's default preview behavior. webView:commitPreviewingViewController: will only be invoked
	if a non-nil view controller was returned.
	*/
	- (nullable UIViewController )webView:(WKWebView )webView previewingViewControllerForElement:(WKPreviewElementInfo )elementInfo defaultActions:(NSArray <id <WKPreviewActionItem>> )previewActions WK_AVAILABLE(NA, WK_IOS_TBA);

	/*! @abstract Allows your app to pop to the view controller it created.
	@param webView The web view invoking the delegate method.
	@param previewingViewController The view controller that is being popped.
	*/
	- (void)webView:(WKWebView )webView commitPreviewingViewController:(UIViewController )previewingViewController WK_AVAILABLE(NA, WK_IOS_TBA);

	#endif // TARGET_OS_IPHONE

	@end

	NS_ASSUME_NONNULL_END

	#endif