Reviewed by Chris Blumenberg.
[WebKit-https.git] / WebKit / WebView.subproj / WebUIDelegate.h
1 /*
2  * Copyright (C) 2003, 2004, 2005 Apple Computer, 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  *
8  * 1.  Redistributions of source code must retain the above copyright
9  *     notice, this list of conditions and the following disclaimer. 
10  * 2.  Redistributions in binary form must reproduce the above copyright
11  *     notice, this list of conditions and the following disclaimer in the
12  *     documentation and/or other materials provided with the distribution. 
13  * 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
14  *     its contributors may be used to endorse or promote products derived
15  *     from this software without specific prior written permission. 
16  *
17  * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
18  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20  * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
21  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27  */
28
29 #import <Cocoa/Cocoa.h>
30 #import <Foundation/NSURLRequest.h>
31
32 /*!
33     @enum WebMenuItemTag
34     @discussion Each menu item in the default menu items array passed in
35     contextMenuItemsForElement:defaultMenuItems: has its tag set to one of the WebMenuItemTags.
36     When iterating through the default menu items array, use the tag to differentiate between them.
37 */
38
39 enum {
40     WebMenuItemTagOpenLinkInNewWindow=1,
41     WebMenuItemTagDownloadLinkToDisk,
42     WebMenuItemTagCopyLinkToClipboard,
43     WebMenuItemTagOpenImageInNewWindow,
44     WebMenuItemTagDownloadImageToDisk,
45     WebMenuItemTagCopyImageToClipboard,
46     WebMenuItemTagOpenFrameInNewWindow,
47     WebMenuItemTagCopy,
48     WebMenuItemTagGoBack,
49     WebMenuItemTagGoForward,
50     WebMenuItemTagStop,
51     WebMenuItemTagReload,
52     WebMenuItemTagCut,
53     WebMenuItemTagPaste,
54     WebMenuItemTagSpellingGuess,
55     WebMenuItemTagNoGuessesFound,
56     WebMenuItemTagIgnoreSpelling,
57     WebMenuItemTagLearnSpelling,
58     WebMenuItemTagOther,
59     WebMenuItemTagOpenWithDefaultApplication,
60     WebMenuItemPDFActualSize,
61     WebMenuItemPDFZoomIn,
62     WebMenuItemPDFZoomOut,
63     WebMenuItemPDFAutoSize,
64     WebMenuItemPDFSinglePage,
65     WebMenuItemPDFFacingPages,
66     WebMenuItemPDFContinuous,
67     WebMenuItemPDFNextPage,
68     WebMenuItemPDFPreviousPage,
69 };
70
71 /*!
72     @enum WebDragDestinationAction
73     @abstract Actions that the destination of a drag can perform.
74     @constant WebDragDestinationActionNone No action
75     @constant WebDragDestinationActionDHTML Allows DHTML (such as JavaScript) to handle the drag
76     @constant WebDragDestinationActionEdit Allows editable documents to be edited from the drag
77     @constant WebDragDestinationActionLoad Allows a location change from the drag
78     @constant WebDragDestinationActionAny Allows any of the above to occur
79 */
80 typedef enum {
81     WebDragDestinationActionNone    = 0,
82     WebDragDestinationActionDHTML   = 1,
83     WebDragDestinationActionEdit    = 2,
84     WebDragDestinationActionLoad    = 4,
85     WebDragDestinationActionAny     = UINT_MAX
86 } WebDragDestinationAction;
87
88 /*!
89     @enum WebDragSourceAction
90     @abstract Actions that the source of a drag can perform.
91     @constant WebDragSourceActionNone No action
92     @constant WebDragSourceActionDHTML Allows DHTML (such as JavaScript) to start a drag
93     @constant WebDragSourceActionImage Allows an image drag to occur
94     @constant WebDragSourceActionLink Allows a link drag to occur
95     @constant WebDragSourceActionSelection Allows a selection drag to occur
96     @constant WebDragSourceActionAny Allows any of the above to occur
97 */
98 typedef enum {
99     WebDragSourceActionNone         = 0,
100     WebDragSourceActionDHTML        = 1,
101     WebDragSourceActionImage        = 2,
102     WebDragSourceActionLink         = 4,
103     WebDragSourceActionSelection    = 8,
104     WebDragSourceActionAny          = UINT_MAX
105 } WebDragSourceAction;
106
107 /*!
108     @protocol WebOpenPanelResultListener
109     @discussion This protocol is used to call back with the results of
110     the file open panel requested by runOpenPanelForFileButtonWithResultListener:
111 */
112 @protocol WebOpenPanelResultListener <NSObject>
113
114 /*!
115     @method chooseFilename:
116     @abstract Call this method to return a filename from the file open panel.
117     @param fileName
118 */
119 - (void)chooseFilename:(NSString *)fileName;
120
121 /*!
122     @method cancel
123     @abstract Call this method to indicate that the file open panel was cancelled.
124 */
125 - (void)cancel;
126
127 @end
128
129 @class WebView;
130
131 /*!
132     @category WebUIDelegate
133     @discussion A class that implements WebUIDelegate provides
134     window-related methods that may be used by Javascript, plugins and
135     other aspects of web pages. These methods are used to open new
136     windows and control aspects of existing windows.
137 */
138 @interface NSObject (WebUIDelegate)
139
140 /*!
141     @method webView:createWebViewWithRequest:
142     @abstract Create a new window and begin to load the specified request.
143     @discussion The newly created window is hidden, and the window operations delegate on the
144     new WebViews will get a webViewShow: call.
145     @param sender The WebView sending the delegate method.
146     @param request The request to load.
147     @result The WebView for the new window.
148 */
149 - (WebView *)webView:(WebView *)sender createWebViewWithRequest:(NSURLRequest *)request;
150
151 /*!
152     @method webViewShow:
153     @param sender The WebView sending the delegate method.
154     @abstract Show the window that contains the top level view of the WebView,
155     ordering it frontmost.
156     @discussion This will only be called just after createWindowWithRequest:
157     is used to create a new window.
158 */
159 - (void)webViewShow:(WebView *)sender;
160
161 /*!
162     @method webViewClose:
163     @abstract Close the current window. 
164     @param sender The WebView sending the delegate method.
165     @discussion Clients showing multiple views in one window may
166     choose to close only the one corresponding to this
167     WebView. Other clients may choose to ignore this method
168     entirely.
169 */
170 - (void)webViewClose:(WebView *)sender;
171
172 /*!
173     @method webViewFocus:
174     @abstract Focus the current window (i.e. makeKeyAndOrderFront:).
175     @param The WebView sending the delegate method.
176     @discussion Clients showing multiple views in one window may want to
177     also do something to focus the one corresponding to this WebView.
178 */
179 - (void)webViewFocus:(WebView *)sender;
180
181 /*!
182     @method webViewUnfocus:
183     @abstract Unfocus the current window.
184     @param sender The WebView sending the delegate method.
185     @discussion Clients showing multiple views in one window may want to
186     also do something to unfocus the one corresponding to this WebView.
187 */
188 - (void)webViewUnfocus:(WebView *)sender;
189
190 /*!
191     @method webViewFirstResponder:
192     @abstract Get the first responder for this window.
193     @param sender The WebView sending the delegate method.
194     @discussion This method should return the focused control in the
195     WebView's view, if any. If the view is out of the window
196     hierarchy, this might return something than calling firstResponder
197     on the real NSWindow would. It's OK to return either nil or the
198     real first responder if some control not in the window has focus.
199 */
200 - (NSResponder *)webViewFirstResponder:(WebView *)sender;
201
202 /*!
203     @method webView:makeFirstResponder:
204     @abstract Set the first responder for this window.
205     @param sender The WebView sending the delegate method.
206     @param responder The responder to make first (will always be a view)
207     @discussion responder will always be a view that is in the view
208     subhierarchy of the top-level web view for this WebView. If the
209     WebView's top level view is currently out of the view
210     hierarchy, it may be desirable to save the first responder
211     elsewhere, or possibly ignore this call.
212 */
213 - (void)webView:(WebView *)sender makeFirstResponder:(NSResponder *)responder;
214
215 /*!
216     @method webView:setStatusText:
217     @abstract Set the window's status display, if any, to the specified string.
218     @param sender The WebView sending the delegate method.
219     @param text The status text to set
220 */
221 - (void)webView:(WebView *)sender setStatusText:(NSString *)text;
222
223 /*!
224     @method webViewStatusText:
225     @abstract Get the currently displayed status text.
226     @param sender The WebView sending the delegate method.
227     @result The status text
228 */
229 - (NSString *)webViewStatusText:(WebView *)sender;
230
231 /*!
232     @method webViewAreToolbarsVisible:
233     @abstract Determine whether the window's toolbars are currently visible
234     @param sender The WebView sending the delegate method.
235     @discussion This method should return YES if the window has any
236     toolbars that are currently on, besides the status bar. If the app
237     has more than one toolbar per window, for example a regular
238     command toolbar and a favorites bar, it should return YES from
239     this method if at least one is on.
240     @result YES if at least one toolbar is visible, otherwise NO.
241 */
242 - (BOOL)webViewAreToolbarsVisible:(WebView *)sender;
243
244 /*!
245     @method webView:setToolbarsVisible:
246     @param sender The WebView sending the delegate method.
247     @abstract Set whether the window's toolbars are currently visible.
248     @param visible New value for toolbar visibility
249     @discussion Setting this to YES should turn on all toolbars
250     (except for a possible status bar). Setting it to NO should turn
251     off all toolbars (with the same exception).
252 */
253 - (void)webView:(WebView *)sender setToolbarsVisible:(BOOL)visible;
254
255 /*!
256     @method webViewIsStatusBarVisible:
257     @abstract Determine whether the status bar is visible.
258     @param sender The WebView sending the delegate method.
259     @result YES if the status bar is visible, otherwise NO.
260 */
261 - (BOOL)webViewIsStatusBarVisible:(WebView *)sender;
262
263 /*!
264     @method webView:setStatusBarVisible:
265     @abstract Set whether the status bar is currently visible.
266     @param visible The new visibility value
267     @discussion Setting this to YES should show the status bar,
268     setting it to NO should hide it.
269 */
270 - (void)webView:(WebView *)sender setStatusBarVisible:(BOOL)visible;
271
272 /*!
273     @method webViewIsResizable:
274     @abstract Determine whether the window is resizable or not.
275     @param sender The WebView sending the delegate method.
276     @result YES if resizable, NO if not.
277     @discussion If there are multiple views in the same window, they
278     have have their own separate resize controls and this may need to
279     be handled specially.
280 */
281 - (BOOL)webViewIsResizable:(WebView *)sender;
282
283 /*!
284     @method webView:setResizable:
285     @abstract Set the window to resizable or not
286     @param sender The WebView sending the delegate method.
287     @param resizable YES if the window should be made resizable, NO if not.
288     @discussion If there are multiple views in the same window, they
289     have have their own separate resize controls and this may need to
290     be handled specially.
291 */
292 - (void)webView:(WebView *)sender setResizable:(BOOL)resizable;
293
294 /*!
295     @method webView:setFrame:
296     @abstract Set the window's frame rect
297     @param sender The WebView sending the delegate method.
298     @param frame The new window frame size
299     @discussion Even though a caller could set the frame directly using the NSWindow,
300     this method is provided so implementors of this protocol can do special
301     things on programmatic move/resize, like avoiding autosaving of the size.
302 */
303 - (void)webView:(WebView *)sender setFrame:(NSRect)frame;
304
305 /*!
306     @method webViewFrame:
307     @param sender The WebView sending the delegate method.
308     @abstract REturn the window's frame rect
309     @discussion 
310 */
311 - (NSRect)webViewFrame:(WebView *)sender;
312
313 /*!
314     @method webView:setContentRect:
315     @abstract Set the window's content rect
316     @param sender The WebView sending the delegate method.
317     @param frame The new window content rect
318     @discussion Even though a caller could set the content rect
319     directly using the NSWindow, this method is provided so
320     implementors of this protocol can do special things on
321     programmatic move/resize, like avoiding autosaving of the size.
322 */
323 - (void)webView:(WebView *)sender setContentRect:(NSRect)contentRect;
324
325 /*!
326     @method webViewContentRect:
327     @abstract Return the window's content rect
328     @discussion 
329 */
330 - (NSRect)webViewContentRect:(WebView *)sender;
331
332 /*!
333     @method webView:runJavaScriptAlertPanelWithMessage:
334     @abstract Display a JavaScript alert panel
335     @param sender The WebView sending the delegate method.
336     @param message The message to display
337     @discussion Clients should visually indicate that this panel comes
338     from JavaScript. The panel should have a single OK button.
339 */
340 - (void)webView:(WebView *)sender runJavaScriptAlertPanelWithMessage:(NSString *)message;
341
342 /*!
343     @method webView:runJavaScriptConfirmPanelWithMessage:
344     @abstract Display a JavaScript confirm panel
345     @param sender The WebView sending the delegate method.
346     @param message The message to display
347     @result YES if the user hit OK, no if the user chose Cancel.
348     @discussion Clients should visually indicate that this panel comes
349     from JavaScript. The panel should have two buttons, e.g. "OK" and
350     "Cancel".
351 */
352 - (BOOL)webView:(WebView *)sender runJavaScriptConfirmPanelWithMessage:(NSString *)message;
353
354 /*!
355     @method webView:runJavaScriptTextInputPanelWithPrompt:defaultText:
356     @abstract Display a JavaScript text input panel
357     @param sender The WebView sending the delegate method.
358     @param message The message to display
359     @param defaultText The initial text for the text entry area.
360     @result The typed text if the user hit OK, otherwise nil.
361     @discussion Clients should visually indicate that this panel comes
362     from JavaScript. The panel should have two buttons, e.g. "OK" and
363     "Cancel", and an area to type text.
364 */
365 - (NSString *)webView:(WebView *)sender runJavaScriptTextInputPanelWithPrompt:(NSString *)prompt defaultText:(NSString *)defaultText;
366
367 /*!
368     @method webView:runOpenPanelForFileButtonWithResultListener:
369     @abstract Display a file open panel for a file input control.
370     @param sender The WebView sending the delegate method.
371     @param resultListener The object to call back with the results.
372     @discussion This method is passed a callback object instead of giving a return
373     value so that it can be handled with a sheet.
374 */
375 - (void)webView:(WebView *)sender runOpenPanelForFileButtonWithResultListener:(id<WebOpenPanelResultListener>)resultListener;
376
377 /*!
378     @method webView:mouseDidMoveOverElement:modifierFlags:
379     @abstract Update the window's feedback for mousing over links to reflect a new item the mouse is over
380     or new modifier flags.
381     @param sender The WebView sending the delegate method.
382     @param elementInformation Dictionary that describes the element that the mouse is over, or nil.
383     @param modifierFlags The modifier flags as in NSEvent.
384 */
385 - (void)webView:(WebView *)sender mouseDidMoveOverElement:(NSDictionary *)elementInformation modifierFlags:(unsigned int)modifierFlags;
386
387 /*!
388     @method webView:contextMenuItemsForElement:defaultMenuItems:
389     @abstract Returns the menu items to display in an element's contextual menu.
390     @param sender The WebView sending the delegate method.
391     @param element A dictionary representation of the clicked element.
392     @param defaultMenuItems An array of default NSMenuItems to include in all contextual menus.
393     @result An array of NSMenuItems to include in the contextual menu.
394 */
395 - (NSArray *)webView:(WebView *)sender contextMenuItemsForElement:(NSDictionary *)element defaultMenuItems:(NSArray *)defaultMenuItems;
396
397 /*!
398     @method webView:validateUserInterfaceItem:defaultValidation:
399     @abstract Controls UI validation
400     @param webView The WebView sending the delegate method
401     @param item The user interface item being validated
402     @pararm defaultValidation Whether or not the WebView thinks the item is valid
403     @discussion This method allows the UI delegate to control WebView's validation of user interface items.
404     See WebView.h to see the methods to that WebView can currently validate. See NSUserInterfaceValidations and
405     NSValidatedUserInterfaceItem for information about UI validation.
406 */
407 - (BOOL)webView:(WebView *)webView validateUserInterfaceItem:(id <NSValidatedUserInterfaceItem>)item defaultValidation:(BOOL)defaultValidation;
408
409 /*!
410     @method webView:shouldPerformAction:fromSender:
411     @abstract Controls actions
412     @param webView The WebView sending the delegate method
413     @param action The action being sent
414     @param sender The sender of the action
415     @discussion This method allows the UI delegate to control WebView's behavior when an action is being sent.
416     For example, if the action is copy:, the delegate can return YES to allow WebView to perform its default
417     copy behavior or return NO and perform copy: in some other way. See WebView.h to see the actions that
418     WebView can perform.
419 */
420 - (BOOL)webView:(WebView *)webView shouldPerformAction:(SEL)action fromSender:(id)sender;
421
422 /*!
423     @method webView:dragDestinationActionMaskForDraggingInfo:
424     @abstract Controls behavior when dragging to a WebView
425     @param webView The WebView sending the delegate method
426     @param draggingInfo The dragging info of the drag
427     @discussion This method is called periodically as something is dragged over a WebView. The UI delegate can return a mask
428     indicating which drag destination actions can occur, WebDragDestinationActionAny to allow any kind of action or
429     WebDragDestinationActionNone to not accept the drag.
430 */
431 - (unsigned)webView:(WebView *)webView dragDestinationActionMaskForDraggingInfo:(id <NSDraggingInfo>)draggingInfo;
432
433 /*!
434     @method webView:willPerformDragDestinationAction:forDraggingInfo:
435     @abstract Informs that WebView will perform a drag destination action
436     @param webView The WebView sending the delegate method
437     @param action The drag destination action
438     @param draggingInfo The dragging info of the drag
439     @discussion This method is called after the last call to webView:dragDestinationActionMaskForDraggingInfo: after something is dropped on a WebView.
440     This method informs the UI delegate of the drag destination action that WebView will perform.
441 */
442 - (void)webView:(WebView *)webView willPerformDragDestinationAction:(WebDragDestinationAction)action forDraggingInfo:(id <NSDraggingInfo>)draggingInfo;
443
444 /*!
445     @method webView:dragSourceActionMaskForPoint:
446     @abstract Controls behavior when dragging from a WebView
447     @param webView The WebView sending the delegate method
448     @param point The point where the drag started in the coordinates of the WebView
449     @discussion This method is called after the user has begun a drag from a WebView. The UI delegate can return a mask indicating
450     which drag source actions can occur, WebDragSourceActionAny to allow any kind of action or WebDragSourceActionNone to not begin a drag.
451 */
452 - (unsigned)webView:(WebView *)webView dragSourceActionMaskForPoint:(NSPoint)point;
453
454 /*!
455     @method webView:willPerformDragSourceAction:fromPoint:withPasteboard:
456     @abstract Informs that a drag a has begun from a WebView
457     @param webView The WebView sending the delegate method
458     @param action The drag source action
459     @param point The point where the drag started in the coordinates of the WebView
460     @param pasteboard The drag pasteboard
461     @discussion This method is called after webView:dragSourceActionMaskForPoint: is called after the user has begun a drag from a WebView.
462     This method informs the UI delegate of the drag source action that will be performed and gives the delegate an opportunity to modify
463     the contents of the dragging pasteboard.
464 */
465 - (void)webView:(WebView *)webView willPerformDragSourceAction:(WebDragSourceAction)action fromPoint:(NSPoint)point withPasteboard:(NSPasteboard *)pasteboard;
466
467 @end