WebKit delegate methods should document their default behaviors
[WebKit-https.git] / Source / WebKit2 / UIProcess / API / Cocoa / WKUIDelegate.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 #import <Foundation/Foundation.h>
31
32 @class WKFrameInfo;
33 @class WKWebViewConfiguration;
34 @class WKWindowFeatures;
35
36 /*! A class conforming to the WKUIDelegate protocol provides methods for
37  presenting native UI on behalf of a webpage.
38  */
39 @protocol WKUIDelegate <NSObject>
40
41 @optional
42
43 /*! @abstract Creates a new web view.
44  @param webView The web view invoking the delegate method.
45  @param configuration The configuration to use when creating the new web
46  view.
47  @param navigationAction The navigation action causing the new web view to
48  be created.
49  @param windowFeatures Window features requested by the webpage.
50  @result A new web view or nil.
51  @discussion The web view returned must be created with the specified configuration. WebKit will load the request in the returned web view.
52
53  If you do not implement this method, the web view will cancel the navigation.
54  */
55 - (WKWebView *)webView:(WKWebView *)webView createWebViewWithConfiguration:(WKWebViewConfiguration *)configuration forNavigationAction:(WKNavigationAction *)navigationAction windowFeatures:(WKWindowFeatures *)windowFeatures;
56
57 /*! @abstract Displays a JavaScript alert panel.
58  @param webView The web view invoking the delegate method.
59  @param message The message to display.
60  @param frame Information about the frame whose JavaScript initiated this
61  call.
62  @param completionHandler The completion handler to call after the alert
63  panel has been dismissed.
64  @discussion For user security, your app should call attention to the fact
65  that a specific website controls the content in this panel. A simple forumla
66  for identifying the controlling website is frame.request.URL.host.
67  The panel should have a single OK button.
68
69  If you do not implement this method, the web view will behave as if the user selected the OK button.
70  */
71 - (void)webView:(WKWebView *)webView runJavaScriptAlertPanelWithMessage:(NSString *)message initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)())completionHandler;
72
73 /*! @abstract Displays a JavaScript confirm panel.
74  @param webView The web view invoking the delegate method.
75  @param message The message to display.
76  @param frame Information about the frame whose JavaScript initiated this call.
77  @param completionHandler The completion handler to call after the confirm
78  panel has been dismissed. Pass YES if the user chose OK, NO if the user
79  chose Cancel.
80  @discussion For user security, your app should call attention to the fact
81  that a specific website controls the content in this panel. A simple forumla
82  for identifying the controlling website is frame.request.URL.host.
83  The panel should have two buttons, such as OK and Cancel.
84
85  If you do not implement this method, the web view will behave as if the user selected the Cancel button.
86  */
87 - (void)webView:(WKWebView *)webView runJavaScriptConfirmPanelWithMessage:(NSString *)message initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(BOOL result))completionHandler;
88
89 /*! @abstract Displays a JavaScript text input panel.
90  @param webView The web view invoking the delegate method.
91  @param message The message to display.
92  @param defaultText The initial text to display in the text entry field.
93  @param frame Information about the frame whose JavaScript initiated this call.
94  @param completionHandler The completion handler to call after the text
95  input panel has been dismissed. Pass the entered text if the user chose
96  OK, otherwise nil.
97  @discussion For user security, your app should call attention to the fact
98  that a specific website controls the content in this panel. A simple forumla
99  for identifying the controlling website is frame.request.URL.host.
100  The panel should have two buttons, such as OK and Cancel, and a field in
101  which to enter text.
102
103  If you do not implement this method, the web view will behave as if the user selected the Cancel button.
104  */
105 - (void)webView:(WKWebView *)webView runJavaScriptTextInputPanelWithPrompt:(NSString *)prompt defaultText:(NSString *)defaultText initiatedByFrame:(WKFrameInfo *)frame completionHandler:(void (^)(NSString *result))completionHandler;
106
107 @end
108
109 #endif