Reviewed by Adam and Steve.
[WebKit-https.git] / WebKit / win / Interfaces / IWebUIDelegate.idl
1 /*
2  * Copyright (C) 2006, 2007 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 COMPUTER, INC. ``AS IS'' AND ANY
14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
24  */
25
26 cpp_quote("/*")
27 cpp_quote(" * Copyright (C) 2006, 2007 Apple Inc.  All rights reserved.")
28 cpp_quote(" *")
29 cpp_quote(" * Redistribution and use in source and binary forms, with or without")
30 cpp_quote(" * modification, are permitted provided that the following conditions")
31 cpp_quote(" * are met:")
32 cpp_quote(" * 1. Redistributions of source code must retain the above copyright")
33 cpp_quote(" *    notice, this list of conditions and the following disclaimer.")
34 cpp_quote(" * 2. Redistributions in binary form must reproduce the above copyright")
35 cpp_quote(" *    notice, this list of conditions and the following disclaimer in the")
36 cpp_quote(" *    documentation and/or other materials provided with the distribution.")
37 cpp_quote(" *")
38 cpp_quote(" * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY")
39 cpp_quote(" * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE")
40 cpp_quote(" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR")
41 cpp_quote(" * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR")
42 cpp_quote(" * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,")
43 cpp_quote(" * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,")
44 cpp_quote(" * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR")
45 cpp_quote(" * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY")
46 cpp_quote(" * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT")
47 cpp_quote(" * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE")
48 cpp_quote(" * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ")
49 cpp_quote(" */")
50
51 import "oaidl.idl";
52 import "ocidl.idl";
53 import "IWebUndoTarget.idl";
54 import "IWebURLRequest.idl";
55 import "IWebFrame.idl";
56
57 interface IWebFrame;
58 interface IWebView;
59 interface IWebURLRequest;
60
61 /*!
62     @enum WebMenuItemTag
63     @discussion Each menu item in the default menu items array passed in
64     contextMenuItemsForElement:defaultMenuItems: has its tag set to one of the WebMenuItemTags.
65     When iterating through the default menu items array, use the tag to differentiate between them.
66 */
67 typedef enum WebMenuItemTag {
68     WebMenuItemTagOpenLinkInNewWindow=1,
69     WebMenuItemTagDownloadLinkToDisk,
70     WebMenuItemTagCopyLinkToClipboard,
71     WebMenuItemTagOpenImageInNewWindow,
72     WebMenuItemTagDownloadImageToDisk,
73     WebMenuItemTagCopyImageToClipboard,
74     WebMenuItemTagOpenFrameInNewWindow,
75     WebMenuItemTagCopy,
76     WebMenuItemTagGoBack,
77     WebMenuItemTagGoForward,
78     WebMenuItemTagStop,
79     WebMenuItemTagReload,
80     WebMenuItemTagCut,
81     WebMenuItemTagPaste,
82     WebMenuItemTagSpellingGuess,
83     WebMenuItemTagNoGuessesFound,
84     WebMenuItemTagIgnoreSpelling,
85     WebMenuItemTagLearnSpelling,
86     WebMenuItemTagOther,
87     WebMenuItemTagSearchInSpotlight,
88     WebMenuItemTagSearchWeb,
89     WebMenuItemTagLookUpInDictionary,
90     WebMenuItemTagOpenWithDefaultApplication,
91     WebMenuItemPDFActualSize,
92     WebMenuItemPDFZoomIn,
93     WebMenuItemPDFZoomOut,
94     WebMenuItemPDFAutoSize,
95     WebMenuItemPDFSinglePage,
96     WebMenuItemPDFFacingPages,
97     WebMenuItemPDFContinuous,
98     WebMenuItemPDFNextPage,
99     WebMenuItemPDFPreviousPage,
100     // FIXME: Review these names before release!
101     WebMenuItemTagOpenLink = 2000,
102     WebMenuItemTagIgnoreGrammar,
103     WebtMenuItemTagSpellingMenu,
104     WebMenuItemTagShowSpellingPanel,
105     WebMenuItemTagCheckSpelling,
106     WebMenuItemTagCheckSpellingWhileTyping,
107     WebMenuItemTagCheckGrammarWithSpelling,
108     WebMenuItemTagFontMenu,
109     WebMenuItemTagShowFonts,
110     WebMenuItemTagBold,
111     WebMenuItemTagItalic,
112     WebMenuItemTagUnderline,
113     WebMenuItemTagOutline,
114     WebMenuItemTagStyles,
115     WebMenuItemTagShowColors,
116     WebMenuItemTagSpeechMenu,
117     WebMenuItemTagStartSpeaking,
118     WebMenuItemTagStopSpeaking,
119     WebMenuItemTagWritingDirectionMenu,
120     WebMenuItemTagDefaultDirection,
121     WebMenuItemTagLeftToRight,
122     WebMenuItemTagRightToLeft,
123     WebMenuItemTagPDFSinglePageScrolling,
124     WebMenuItemTagPDFFacingPagesScrolling,
125     WebMenuItemTagInspectElement,
126     WebMenuItemBaseApplicationTag=10000
127 } WebMenuItemTag;
128
129 /*!
130     @enum WebDragDestinationAction
131     @abstract Actions that the destination of a drag can perform.
132     @constant WebDragDestinationActionNone No action
133     @constant WebDragDestinationActionDHTML Allows DHTML (such as JavaScript) to handle the drag
134     @constant WebDragDestinationActionEdit Allows editable documents to be edited from the drag
135     @constant WebDragDestinationActionLoad Allows a location change from the drag
136     @constant WebDragDestinationActionAny Allows any of the above to occur
137 */
138 typedef enum WebDragDestinationAction {
139     WebDragDestinationActionNone    = 0,
140     WebDragDestinationActionDHTML   = 1,
141     WebDragDestinationActionEdit    = 2,
142     WebDragDestinationActionLoad    = 4,
143     WebDragDestinationActionAny     = (unsigned long)-1
144 } WebDragDestinationAction;
145
146 /*!
147     @enum WebDragSourceAction
148     @abstract Actions that the source of a drag can perform.
149     @constant WebDragSourceActionNone No action
150     @constant WebDragSourceActionDHTML Allows DHTML (such as JavaScript) to start a drag
151     @constant WebDragSourceActionImage Allows an image drag to occur
152     @constant WebDragSourceActionLink Allows a link drag to occur
153     @constant WebDragSourceActionSelection Allows a selection drag to occur
154     @constant WebDragSourceActionAny Allows any of the above to occur
155 */
156 typedef enum WebDragSourceAction {
157     WebDragSourceActionNone         = 0,
158     WebDragSourceActionDHTML        = 1,
159     WebDragSourceActionImage        = 2,
160     WebDragSourceActionLink         = 4,
161     WebDragSourceActionSelection    = 8,
162     WebDragSourceActionAny          = (unsigned long)-1
163 } WebDragSourceAction;
164
165
166 /*!
167     @protocol WebOpenPanelResultListener
168     @discussion This protocol is used to call back with the results of
169     the file open panel requested by runOpenPanelForFileButtonWithResultListener:
170     @protocol WebOpenPanelResultListener <NSObject>
171 */
172 [
173     object,
174     oleautomation,
175     uuid(634198C7-9DFC-4aba-9E8C-90AEEA7A4144),
176     pointer_default(unique)
177 ]
178 interface IWebOpenPanelResultListener : IUnknown
179 {
180     /*!
181         @method chooseFilename:
182         @abstract Call this method to return a filename from the file open panel.
183         @param fileName
184         - (void)chooseFilename:(NSString *)fileName;
185     */
186     HRESULT chooseFilename([out, retval] BSTR* fileName);
187
188     /*!
189         @method cancel
190         @abstract Call this method to indicate that the file open panel was cancelled.
191         - (void)cancel;
192     */
193     HRESULT cancel();
194 }
195
196 /*!
197     @category WebUIDelegate
198     @discussion A class that implements WebUIDelegate provides
199     window-related methods that may be used by Javascript, plugins and
200     other aspects of web pages. These methods are used to open new
201     windows and control aspects of existing windows.
202     @interface NSObject (WebUIDelegate)
203 */
204 [
205     object,
206     oleautomation,
207     uuid(2452A889-A74A-4fbc-9617-326A0A953630),
208     pointer_default(unique)
209 ]
210 interface IWebUIDelegate : IUnknown
211 {
212     /*!
213         @method webView:createWebViewWithRequest:
214         @abstract Create a new window and begin to load the specified request.
215         @discussion The newly created window is hidden, and the window operations delegate on the
216         new WebViews will get a webViewShow: call.
217         @param sender The WebView sending the delegate method.
218         @param request The request to load.
219         @result The WebView for the new window.
220         - (WebView *)webView:(WebView *)sender createWebViewWithRequest:(NSURLRequest *)request;
221     */
222     HRESULT createWebViewWithRequest([in] IWebView* sender, [in] IWebURLRequest* request, [out, retval] IWebView** newWebView);
223
224     /*!
225         @method webViewShow:
226         @param sender The WebView sending the delegate method.
227         @abstract Show the window that contains the top level view of the WebView,
228         ordering it frontmost.
229         @discussion This will only be called just after createWindowWithRequest:
230         is used to create a new window.
231         - (void)webViewShow:(WebView *)sender;
232     */
233     HRESULT webViewShow([in] IWebView* sender);
234
235     /*!
236         @method webViewClose:
237         @abstract Close the current window. 
238         @param sender The WebView sending the delegate method.
239         @discussion Clients showing multiple views in one window may
240         choose to close only the one corresponding to this
241         WebView. Other clients may choose to ignore this method
242         entirely.
243         - (void)webViewClose:(WebView *)sender;
244     */
245     HRESULT webViewClose([in] IWebView* sender);
246
247     /*!
248         @method webViewFocus:
249         @abstract Focus the current window (i.e. makeKeyAndOrderFront:).
250         @param The WebView sending the delegate method.
251         @discussion Clients showing multiple views in one window may want to
252         also do something to focus the one corresponding to this WebView.
253         - (void)webViewFocus:(WebView *)sender;
254     */
255     HRESULT webViewFocus([in] IWebView* sender);
256
257     /*!
258         @method webViewUnfocus:
259         @abstract Unfocus the current window.
260         @param sender The WebView sending the delegate method.
261         @discussion Clients showing multiple views in one window may want to
262         also do something to unfocus the one corresponding to this WebView.
263         - (void)webViewUnfocus:(WebView *)sender;
264     */
265     HRESULT webViewUnfocus([in] IWebView* sender);
266
267     /*!
268         @method webViewFirstResponder:
269         @abstract Get the first responder for this window.
270         @param sender The WebView sending the delegate method.
271         @discussion This method should return the focused control in the
272         WebView's view, if any. If the view is out of the window
273         hierarchy, this might return something than calling firstResponder
274         on the real NSWindow would. It's OK to return either nil or the
275         real first responder if some control not in the window has focus.
276         - (NSResponder *)webViewFirstResponder:(WebView *)sender;
277     */
278     HRESULT webViewFirstResponder([in] IWebView* sender, [out, retval] OLE_HANDLE* responderHWnd);
279
280     /*!
281         @method webView:makeFirstResponder:
282         @abstract Set the first responder for this window.
283         @param sender The WebView sending the delegate method.
284         @param responder The responder to make first (will always be a view)
285         @discussion responder will always be a view that is in the view
286         subhierarchy of the top-level web view for this WebView. If the
287         WebView's top level view is currently out of the view
288         hierarchy, it may be desirable to save the first responder
289         elsewhere, or possibly ignore this call.
290         - (void)webView:(WebView *)sender makeFirstResponder:(NSResponder *)responder;
291     */
292     HRESULT makeFirstResponder([in] IWebView* sender, [in] OLE_HANDLE responderHWnd);
293
294     /*!
295         @method webView:setStatusText:
296         @abstract Set the window's status display, if any, to the specified string.
297         @param sender The WebView sending the delegate method.
298         @param text The status text to set
299         - (void)webView:(WebView *)sender setStatusText:(NSString *)text;
300     */
301     HRESULT setStatusText([in] IWebView* sender, [in] BSTR text);
302
303     /*!
304         @method webViewStatusText:
305         @abstract Get the currently displayed status text.
306         @param sender The WebView sending the delegate method.
307         @result The status text
308         - (NSString *)webViewStatusText:(WebView *)sender;
309     */
310     HRESULT webViewStatusText([in] IWebView* sender, [out, retval] BSTR* text);
311
312     /*!
313         @method webViewAreToolbarsVisible:
314         @abstract Determine whether the window's toolbars are currently visible
315         @param sender The WebView sending the delegate method.
316         @discussion This method should return YES if the window has any
317         toolbars that are currently on, besides the status bar. If the app
318         has more than one toolbar per window, for example a regular
319         command toolbar and a favorites bar, it should return YES from
320         this method if at least one is on.
321         @result YES if at least one toolbar is visible, otherwise NO.
322         - (BOOL)webViewAreToolbarsVisible:(WebView *)sender;
323     */
324     HRESULT webViewAreToolbarsVisible([in] IWebView* sender, [out, retval] BOOL* visible);
325
326     /*!
327         @method webView:setToolbarsVisible:
328         @param sender The WebView sending the delegate method.
329         @abstract Set whether the window's toolbars are currently visible.
330         @param visible New value for toolbar visibility
331         @discussion Setting this to YES should turn on all toolbars
332         (except for a possible status bar). Setting it to NO should turn
333         off all toolbars (with the same exception).
334         - (void)webView:(WebView *)sender setToolbarsVisible:(BOOL)visible;
335     */
336     HRESULT setToolbarsVisible([in] IWebView* sender, [in] BOOL visible);
337
338     /*!
339         @method webViewIsStatusBarVisible:
340         @abstract Determine whether the status bar is visible.
341         @param sender The WebView sending the delegate method.
342         @result YES if the status bar is visible, otherwise NO.
343         - (BOOL)webViewIsStatusBarVisible:(WebView *)sender;
344     */
345     HRESULT webViewIsStatusBarVisible([in] IWebView* sender, [out, retval] BOOL* visible);
346
347     /*!
348         @method webView:setStatusBarVisible:
349         @abstract Set whether the status bar is currently visible.
350         @param visible The new visibility value
351         @discussion Setting this to YES should show the status bar,
352         setting it to NO should hide it.
353         - (void)webView:(WebView *)sender setStatusBarVisible:(BOOL)visible;
354     */
355     HRESULT setStatusBarVisible([in] IWebView* sender, [in] BOOL visible);
356
357     /*!
358         @method webViewIsResizable:
359         @abstract Determine whether the window is resizable or not.
360         @param sender The WebView sending the delegate method.
361         @result YES if resizable, NO if not.
362         @discussion If there are multiple views in the same window, they
363         have have their own separate resize controls and this may need to
364         be handled specially.
365         - (BOOL)webViewIsResizable:(WebView *)sender;
366     */
367     HRESULT webViewIsResizable([in] IWebView* sender, [out, retval] BOOL* resizable);
368
369     /*!
370         @method webView:setResizable:
371         @abstract Set the window to resizable or not
372         @param sender The WebView sending the delegate method.
373         @param resizable YES if the window should be made resizable, NO if not.
374         @discussion If there are multiple views in the same window, they
375         have have their own separate resize controls and this may need to
376         be handled specially.
377         - (void)webView:(WebView *)sender setResizable:(BOOL)resizable;
378     */
379     HRESULT setResizable([in] IWebView* sender, [in] BOOL resizable);
380
381     /*!
382         @method webView:setFrame:
383         @abstract Set the window's frame rect
384         @param sender The WebView sending the delegate method.
385         @param frame The new window frame size
386         @discussion Even though a caller could set the frame directly using the NSWindow,
387         this method is provided so implementors of this protocol can do special
388         things on programmatic move/resize, like avoiding autosaving of the size.
389         - (void)webView:(WebView *)sender setFrame:(NSRect)frame;
390     */
391     HRESULT setFrame([in] IWebView* sender, [in] RECT* frame);
392
393     /*!
394         @method webViewFrame:
395         @param sender The WebView sending the delegate method.
396         @abstract REturn the window's frame rect
397         @discussion 
398         - (NSRect)webViewFrame:(WebView *)sender;
399     */
400     HRESULT webViewFrame([in] IWebView* sender, [out, retval] RECT* frame);
401
402     /*!
403         @method webView:setContentRect:
404         @abstract Set the window's content rect
405         @param sender The WebView sending the delegate method.
406         @param frame The new window content rect
407         @discussion Even though a caller could set the content rect
408         directly using the NSWindow, this method is provided so
409         implementors of this protocol can do special things on
410         programmatic move/resize, like avoiding autosaving of the size.
411         - (void)webView:(WebView *)sender setContentRect:(NSRect)contentRect;
412     */
413     HRESULT setContentRect([in] IWebView* sender, [in] RECT* contentRect);
414
415     /*!
416         @method webViewContentRect:
417         @abstract Return the window's content rect
418         @discussion 
419         - (NSRect)webViewContentRect:(WebView *)sender;
420     */
421     HRESULT webViewContentRect([in] IWebView* sender, [out, retval] RECT* contentRect);
422
423     /*!
424         @method webView:runJavaScriptAlertPanelWithMessage:
425         @abstract Display a JavaScript alert panel
426         @param sender The WebView sending the delegate method.
427         @param message The message to display
428         @discussion Clients should visually indicate that this panel comes
429         from JavaScript. The panel should have a single OK button.
430         - (void)webView:(WebView *)sender runJavaScriptAlertPanelWithMessage:(NSString *)message;
431     */
432     HRESULT runJavaScriptAlertPanelWithMessage([in] IWebView* sender, [in] BSTR message);
433
434     /*!
435         @method webView:runJavaScriptConfirmPanelWithMessage:
436         @abstract Display a JavaScript confirm panel
437         @param sender The WebView sending the delegate method.
438         @param message The message to display
439         @result YES if the user hit OK, no if the user chose Cancel.
440         @discussion Clients should visually indicate that this panel comes
441         from JavaScript. The panel should have two buttons, e.g. "OK" and
442         "Cancel".
443         - (BOOL)webView:(WebView *)sender runJavaScriptConfirmPanelWithMessage:(NSString *)message;
444     */
445     HRESULT runJavaScriptConfirmPanelWithMessage([in] IWebView* sender, [in] BSTR message, [out, retval] BOOL* result);
446
447     /*!
448         @method webView:runJavaScriptTextInputPanelWithPrompt:defaultText:
449         @abstract Display a JavaScript text input panel
450         @param sender The WebView sending the delegate method.
451         @param message The message to display
452         @param defaultText The initial text for the text entry area.
453         @result The typed text if the user hit OK, otherwise nil.
454         @discussion Clients should visually indicate that this panel comes
455         from JavaScript. The panel should have two buttons, e.g. "OK" and
456         "Cancel", and an area to type text.
457         - (NSString *)webView:(WebView *)sender runJavaScriptTextInputPanelWithPrompt:(NSString *)prompt defaultText:(NSString *)defaultText;
458     */
459     HRESULT runJavaScriptTextInputPanelWithPrompt([in] IWebView* sender, [in] BSTR message, [in] BSTR defaultText, [out, retval] BSTR* result);
460
461     /*!
462         @method webView:runJavaScriptConfirmPanelWithMessage:initiatedByFrame:
463         @abstract Display a confirm panel by an "before unload" event handler.
464         @param sender The WebView sending the delegate method.
465         @param message The message to display.
466         @param frame The WebFrame whose JavaScript initiated this call.
467         @result YES if the user hit OK, NO if the user chose Cancel.
468         @discussion Clients should include a message in addition to the one
469         supplied by the web page that indicates. The panel should have 
470         two buttons, e.g. "OK" and "Cancel".
471         - (BOOL)webView:(WebView *)sender runBeforeUnloadConfirmPanelWithMessage:(NSString *)message initiatedByFrame:(WebFrame *)frame;
472     */
473     HRESULT runBeforeUnloadConfirmPanelWithMessage([in] IWebView* sender, [in] BSTR message, [in] IWebFrame* initiatedByFrame, [out, retval] BOOL* result);
474
475     /*!
476         @method webView:runOpenPanelForFileButtonWithResultListener:
477         @abstract Display a file open panel for a file input control.
478         @param sender The WebView sending the delegate method.
479         @param resultListener The object to call back with the results.
480         @discussion This method is passed a callback object instead of giving a return
481         value so that it can be handled with a sheet.
482         - (void)webView:(WebView *)sender runOpenPanelForFileButtonWithResultListener:(id<WebOpenPanelResultListener>)resultListener;
483     */
484     HRESULT runOpenPanelForFileButtonWithResultListener([in] IWebView* sender, [in] IWebOpenPanelResultListener* resultListener);
485
486     /*!
487         @method webView:mouseDidMoveOverElement:modifierFlags:
488         @abstract Update the window's feedback for mousing over links to reflect a new item the mouse is over
489         or new modifier flags.
490         @param sender The WebView sending the delegate method.
491         @param elementInformation Dictionary that describes the element that the mouse is over, or nil.
492         @param modifierFlags The modifier flags as in NSEvent.
493         - (void)webView:(WebView *)sender mouseDidMoveOverElement:(NSDictionary *)elementInformation modifierFlags:(WebNSUInt)modifierFlags;
494     */
495     HRESULT mouseDidMoveOverElement([in] IWebView* sender, [in] IPropertyBag* elementInformation, [in] UINT modifierFlags);
496
497     /*!
498         @method webView:contextMenuItemsForElement:defaultMenuItems:
499         @abstract Returns the menu items to display in an element's contextual menu.
500         @param sender The WebView sending the delegate method.
501         @param element A dictionary representation of the clicked element.
502         @param defaultMenuItems An array of default NSMenuItems to include in all contextual menus.
503         @result An array of NSMenuItems to include in the contextual menu.
504         - (NSArray *)webView:(WebView *)sender contextMenuItemsForElement:(NSDictionary *)element defaultMenuItems:(NSArray *)defaultMenuItems;
505     */
506     HRESULT contextMenuItemsForElement([in] IWebView* sender, [in] IPropertyBag* element, [in] OLE_HANDLE defaultItemsHMenu, [out, retval] OLE_HANDLE* resultHMenu);
507
508     /*!
509         @method webView:validateUserInterfaceItem:defaultValidation:
510         @abstract Controls UI validation
511         @param webView The WebView sending the delegate method
512         @param item The user interface item being validated
513         @pararm defaultValidation Whether or not the WebView thinks the item is valid
514         @discussion This method allows the UI delegate to control WebView's validation of user interface items.
515         See WebView.h to see the methods to that WebView can currently validate. See NSUserInterfaceValidations and
516         NSValidatedUserInterfaceItem for information about UI validation.
517         - (BOOL)webView:(WebView *)webView validateUserInterfaceItem:(id <NSValidatedUserInterfaceItem>)item defaultValidation:(BOOL)defaultValidation;
518     */
519     HRESULT validateUserInterfaceItem([in] IWebView* webView, [in] UINT itemCommandID, [in] BOOL defaultValidation, [out, retval] BOOL* isValid);
520
521     /*!
522         @method webView:shouldPerformAction:fromSender:
523         @abstract Controls actions
524         @param webView The WebView sending the delegate method
525         @param action The action being sent
526         @param sender The sender of the action
527         @discussion This method allows the UI delegate to control WebView's behavior when an action is being sent.
528         For example, if the action is copy:, the delegate can return YES to allow WebView to perform its default
529         copy behavior or return NO and perform copy: in some other way. See WebView.h to see the actions that
530         WebView can perform.
531         - (BOOL)webView:(WebView *)webView shouldPerformAction:(SEL)action fromSender:(id)sender;
532     */
533     HRESULT shouldPerformAction([in] IWebView* webView, [in] UINT itemCommandID, [in] UINT sender);
534
535     /*!
536         @method webView:dragDestinationActionMaskForDraggingInfo:
537         @abstract Controls behavior when dragging to a WebView
538         @param webView The WebView sending the delegate method
539         @param draggingInfo The dragging info of the drag
540         @discussion This method is called periodically as something is dragged over a WebView. The UI delegate can return a mask
541         indicating which drag destination actions can occur, WebDragDestinationActionAny to allow any kind of action or
542         WebDragDestinationActionNone to not accept the drag.
543         - (unsigned)webView:(WebView *)webView dragDestinationActionMaskForDraggingInfo:(id <NSDraggingInfo>)draggingInfo;
544     */
545     HRESULT dragDestinationActionMaskForDraggingInfo([in] IWebView* webView, [in] IDataObject* draggingInfo, [out, retval] WebDragDestinationAction* action);
546
547     /*!
548         @method webView:willPerformDragDestinationAction:forDraggingInfo:
549         @abstract Informs that WebView will perform a drag destination action
550         @param webView The WebView sending the delegate method
551         @param action The drag destination action
552         @param draggingInfo The dragging info of the drag
553         @discussion This method is called after the last call to webView:dragDestinationActionMaskForDraggingInfo: after something is dropped on a WebView.
554         This method informs the UI delegate of the drag destination action that WebView will perform.
555         - (void)webView:(WebView *)webView willPerformDragDestinationAction:(WebDragDestinationAction)action forDraggingInfo:(id <NSDraggingInfo>)draggingInfo;
556     */
557     HRESULT willPerformDragDestinationAction([in] IWebView* webView, [in] WebDragDestinationAction action, [in] IDataObject* draggingInfo);
558
559     /*!
560         @method webView:dragSourceActionMaskForPoint:
561         @abstract Controls behavior when dragging from a WebView
562         @param webView The WebView sending the delegate method
563         @param point The point where the drag started in the coordinates of the WebView
564         @discussion This method is called after the user has begun a drag from a WebView. The UI delegate can return a mask indicating
565         which drag source actions can occur, WebDragSourceActionAny to allow any kind of action or WebDragSourceActionNone to not begin a drag.
566         - (unsigned)webView:(WebView *)webView dragSourceActionMaskForPoint:(NSPoint)point;
567     */
568     HRESULT dragSourceActionMaskForPoint([in] IWebView* webView, [in] LPPOINT point, [out, retval] WebDragSourceAction* action);
569
570     /*!
571         @method webView:willPerformDragSourceAction:fromPoint:withPasteboard:
572         @abstract Informs that a drag a has begun from a WebView
573         @param webView The WebView sending the delegate method
574         @param action The drag source action
575         @param point The point where the drag started in the coordinates of the WebView
576         @param pasteboard The drag pasteboard
577         @discussion This method is called after webView:dragSourceActionMaskForPoint: is called after the user has begun a drag from a WebView.
578         This method informs the UI delegate of the drag source action that will be performed and gives the delegate an opportunity to modify
579         the contents of the dragging pasteboard.
580         - (void)webView:(WebView *)webView willPerformDragSourceAction:(WebDragSourceAction)action fromPoint:(NSPoint)point withPasteboard:(NSPasteboard *)pasteboard;
581     */
582     HRESULT willPerformDragSourceAction([in] IWebView* webView, [in] WebDragSourceAction action, [in] LPPOINT point, [in] IDataObject* pasteboard);
583
584     /*!
585         @method webView:contextMenuItemSelected:ForElement:
586         @abstract Perform the action associated with the selected item.
587         @param sender The WebView sending the delegate method.
588         @param item The menu item that was selected.
589         @param element A dictionary representation of the clicked element.
590     */
591     [local] HRESULT contextMenuItemSelected([in] IWebView* sender, [in] void* item, [in] IPropertyBag* element);
592
593     /*
594         @method hasCustomMenuImplementation:
595         @abstract Returns whether the application uses the following functions to create a custom menu impementation.
596     */
597     HRESULT hasCustomMenuImplementation([out, retval] BOOL* hasCustomMenus);
598     
599     /*
600         @method webView:trackCutsomPopupMenu
601         @abstract Adds custom draw data to the menu items and calls a custom trackPopupMenu.
602         @param sender The WebView sending the delegate method.
603         @param menu The menu that we want to pop up.
604         @param point The point associated with the context menu event in the coordinates of the WebView
605     */
606     HRESULT trackCustomPopupMenu([in] IWebView* sender, [in] OLE_HANDLE hMenu, [in] LPPOINT point);
607
608     /*
609         @method webView:measureCustomMenuItem
610         @abstract This is called when the WM_MEASUREITEM command is received to measure the custom menu items
611         @param sender The WebView sending the delegate method.
612         @param measureItem The LPMEASUREITEMSTRUCT associated with the item.
613     */
614     [local] HRESULT measureCustomMenuItem([in] IWebView* sender, [in] void* measureItem);
615
616     /*
617         @method webView:drawCustomMenuItem
618         @abstract This is called when the WM_DRAWITEM command is received to draw the custom menu item
619         @param sender The WebView sending the delegate method.
620         @param drawItem The LPDRAWITEMSTRUCT associated with the item.
621     */
622     [local] HRESULT drawCustomMenuItem([in] IWebView* sender, [in] void* drawItem);
623
624     /*
625         @method webView:addCustomMenuDrawingData
626         @abstract Add custom data to the menu that the delegate can use when asked to draw.
627         @param sender The WebView sending the delegate method.
628         @param menu The cutsom menu to clean up.
629         @discussion This method is called for submenus as well.
630     */
631     HRESULT addCustomMenuDrawingData([in] IWebView* sender, [in] OLE_HANDLE hMenu);
632
633     /*
634         @method webView:cleanUpCustomMenuDrawingData
635         @abstract Clean up any custom data added to the menu items
636         @param sender The WebView sending the delegate method.
637         @param menu The cutsom menu to clean up.
638     */
639     HRESULT cleanUpCustomMenuDrawingData([in] IWebView* sender, [in] OLE_HANDLE hMenu);
640
641     /*!
642         @method webView:canTakeFocus:
643         @abstract Informs whether focus can be transferred out of the WebView in the specified direction
644         @param sender The WebView sending the delegate method.
645         @param forward Whether focus is moving forward or backward.
646     */
647     HRESULT canTakeFocus([in] IWebView* sender, [in] BOOL forward, [out] BOOL* result);
648
649     /*!
650         @method webView:takeFocus:
651         @abstract Instructs the delegate to take focus out of the WebView
652         @param sender The WebView sending the delegate method.
653         @param forward Whether focus is moving forward or backward.
654     */
655     HRESULT takeFocus([in] IWebView* sender, [in] BOOL forward);
656
657     /// Undo related UI delegate methods --------------------------------------------------------------------------------
658
659     /*!
660         @method registerUndoWithTarget:
661         @abstract Registers an undo operation of a IWebUndoTarget on the undo/redo stack.
662         @param target The target that will be called back when the action is undone
663         @param actionName The name of the action - this will be passed back to the target when we need to undo the operation
664         @param actionArg An object that target used to save undo information
665     */
666     HRESULT registerUndoWithTarget([in] IWebUndoTarget* target, [in] BSTR actionName, [in] IUnknown* actionArg);
667
668     /*!
669         @method removeAllActionsWithTarget:
670         @abstract remove all the undo operations that are registered for the passed in target on the undo/redo stack.
671         @param target 
672     */
673     HRESULT removeAllActionsWithTarget([in] IWebUndoTarget* target);
674
675     /*!
676         @method setActionTitle:
677         @abstract Sets the name of the action for the current group of undo operations
678         @param actionName Name of the action
679     */
680     HRESULT setActionTitle([in] BSTR actionTitle);
681
682     /*!
683         @method undo:
684         @abstract Undo the last group of operations
685     */
686     HRESULT undo();
687
688     /*!
689         @method redo:
690         @abstract Redo the last group of operations
691     */
692     HRESULT redo();
693
694     /*!
695         @method canUndo:
696         @abstract Returns whether there's anything on the undo stack to be undone
697     */
698     HRESULT canUndo([out, retval] BOOL* result);
699
700     /*!
701         @method canRedo:
702         @abstract Returns whether there's anything on the redo stack to be redone
703     */
704     HRESULT canRedo([out, retval] BOOL* result);
705 }
706
707 /*!
708     @category WebUIDelegate2
709     @discussion A class that supplements the IWebUIDelegate interface
710 */
711 [
712     object,
713     oleautomation,
714     uuid(C6FF73E1-304D-4129-A60C-66326C2578DB),
715     pointer_default(unique)
716 ]
717 interface IWebUIDelegate2 : IWebUIDelegate
718 {
719 /*!
720     @method webView:printFrame:
721     @abstract Informs that a WebFrame needs to be printed
722     @param webView The WebView sending the delegate method
723     @param frame The WebFrame needing to be printed
724     @discussion This method is called when a script or user requests the page to be printed.
725     In this method the delegate can prepare the WebFrame to be printed.
726 */
727     HRESULT printFrame([in] IWebView* webView, [in] IWebFrame* frame);
728
729 /*!
730     @method webView:ftpDirectoryTemplatePath
731     @abstract Returns the path to the FTP directory listing template document
732     @param webView The WebView sending the delegate method
733     @param path The path to the template document
734     @discussion This method is called when an FTP directory listing is viewed in a webView.  
735     In practice, all WebViews show the same template document data that was loaded for the very
736     first WebView that displayed a directory listing, so this will only be called once.
737 */
738     HRESULT ftpDirectoryTemplatePath([in] IWebView* webView, [out, retval] BSTR* path);
739
740 /*!
741     @method webViewHeaderHeight:
742     @param webView The WebView sending the delegate method
743     @abstract Reserve a height for the printed page header.
744     @result The height to reserve for the printed page header, return 0.0 to not reserve any space for a header.
745     @discussion The height returned will be used to calculate the rect passed to webView:drawHeaderInRect:.
746
747     - (float)webViewHeaderHeight:(WebView *)sender;
748 */
749     HRESULT webViewHeaderHeight([in] IWebView* webView, [out, retval] float* result);
750
751 /*!
752     @method webViewFooterHeight:
753     @param webView The WebView sending the delegate method
754     @abstract Reserve a height for the printed page footer.
755     @result The height to reserve for the printed page footer, return 0.0 to not reserve any space for a footer.
756     @discussion The height returned will be used to calculate the rect passed to webView:drawFooterInRect:.
757
758     - (float)webViewFooterHeight:(WebView *)sender;
759 */
760     HRESULT webViewFooterHeight([in] IWebView* webView, [out, retval] float* result);
761
762 /*!
763     @method webView:drawHeaderInRect:
764     @param webView The WebView sending the delegate method
765     @param rect The NSRect reserved for the header of the page
766     @abstract The delegate should draw a header for the sender in the supplied rect.
767
768     - (void)webView:(WebView *)sender drawHeaderInRect:(NSRect)rect;
769 */
770     HRESULT drawHeaderInRect([in] IWebView* webView, [in] RECT* rect, [in] OLE_HANDLE drawingContext);
771
772 /*!
773     @method webView:drawFooterInRect:
774     @param webView The WebView sending the delegate method
775     @param rect The NSRect reserved for the footer of the page
776     @abstract The delegate should draw a footer for the sender in the supplied rect.
777
778     - (void)webView:(WebView *)sender drawFooterInRect:(NSRect)rect;
779 */
780     HRESULT drawFooterInRect([in] IWebView* webView, [in] RECT* rect, [in] OLE_HANDLE drawingContext, [in] UINT pageIndex, [in] UINT pageCount);
781
782     HRESULT webViewPrintingMarginRect([in] IWebView* webView, [out, retval] RECT* rect);
783 }
784
785 /*!
786     @category WebUIDelegate3
787     @discussion A class that supplements the IWebUIDelegate interface
788 */
789 [
790     object,
791     oleautomation,
792     uuid(DD544D90-C233-4562-8EFD-A8D3A0DEBC19),
793     pointer_default(unique)
794 ]
795 interface IWebUIDelegate3 : IWebUIDelegate2
796 {
797     HRESULT canRunModal([in] IWebView* webView, [out, retval] BOOL* canRunBoolean);
798     HRESULT createModalDialog([in] IWebView* sender, [in] IWebURLRequest* request, [out, retval] IWebView** newWebView);
799     HRESULT runModal([in] IWebView* webView);
800 }