---

WebUIDelegate Protocol Reference

(informal protocol)

Overview

WebView user interface delegates implement this informal protocol to control the opening of new windows, augment the default menu items displayed when the user clicks on elements, and other user interface-related aspects. These methods may be invoked as a result of handling JavaScript or other plug-in content. Delegates that display more than one web view per window, for example, will need to implement some of these methods to handle that case. The default implementation assumes one window per web view, so any non-conventional user interfaces might implement a user interface delegate.

Tasks

Creating and Closing Windows

• – webView:createWebViewWithRequest:
• – webViewClose:

Moving and Resizing Windows

• – webViewIsResizable:
• – webView:setResizable:
• – webView:setFrame:
• – webViewFrame:

Moving and Resizing Content Views

• – webView:setContentRect:
• – webViewContentRect:

Making Key and Main Windows

• – webViewFocus:
• – webViewUnfocus:

Ordering Windows

• – webViewShow:

Working with the Responder Chain

• – webViewFirstResponder:
• – webView:makeFirstResponder:

Handling Mouse Events

• – webView:mouseDidMoveOverElement:modifierFlags:
• – webView:contextMenuItemsForElement:defaultMenuItems:

Opening Panels

• – webView:runJavaScriptAlertPanelWithMessage:
• – webView:runJavaScriptAlertPanelWithMessage:initiatedByFrame:
• – webView:runJavaScriptConfirmPanelWithMessage:
• – webView:runJavaScriptConfirmPanelWithMessage:initiatedByFrame:
• – webView:runJavaScriptTextInputPanelWithPrompt:defaultText:
• – webView:runJavaScriptTextInputPanelWithPrompt:defaultText:initiatedByFrame:
• – webView:runOpenPanelForFileButtonWithResultListener:
• – webView:runBeforeUnloadConfirmPanelWithMessage:initiatedByFrame:

Displaying Status Messages

• – webView:setStatusText:
• – webViewStatusText:

Managing Toolbars

• – webViewAreToolbarsVisible:
• – webView:setToolbarsVisible:
• – webViewIsStatusBarVisible:
• – webView:setStatusBarVisible:

Controlling Dragging Behaviors

• – webView:dragDestinationActionMaskForDraggingInfo:
• – webView:dragSourceActionMaskForPoint:
• – webView:willPerformDragDestinationAction:forDraggingInfo:
• – webView:willPerformDragSourceAction:fromPoint:withPasteboard:

Controlling Other Behaviors

• – webView:shouldPerformAction:fromSender:
• – webView:validateUserInterfaceItem:defaultValidation:

Instance Methods

webView:contextMenuItemsForElement:defaultMenuItems:

Returns an array of menu items to display in an element's contextual menu.

- (NSArray *)webView:(WebView *)sender contextMenuItemsForElement:(NSDictionary *)element defaultMenuItems:(NSArray *)defaultMenuItems

Discussion

This method is invoked every time the user presses the right mouse button or control-clicks an element, and returns an array of menu items to display in the resulting contextual menu. The receiver typically returns a modified copy of defaultMenuItems, adding and removing menu items as appropriate for this type of element. You may use this mechanism to remove items that are not appropriate for a particular environment or task, such as saving files to the desktop in a web kiosk. You do not need to set the actions and targets of the default items.

The element argument is a dictionary representation of the clicked element. See the WebView “Constants” for a description of the key-value pairs in this dictionary.

The defaultMenuItems array contains the default NSMenuItem objects included in all contextual menus. The default menu items define common actions the user might want to do to elements. You use the constants defined in “Constants” to differentiate between these different types of menu items.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebUIDelegate.h

webView:createWebViewWithRequest:

Creates a new window containing a new WebView object to handle a request.

- (WebView *)webView:(WebView *)sender createWebViewWithRequest:(NSURLRequest *)request

Discussion

This method should begin loading the content for request for this WebView by sending loadRequest: to its main frame. The new window should initially be hidden. Later a webViewShow: message is sent to the delegate of the new WebView. The default behavior returns nil.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebUIDelegate.h

webView:dragDestinationActionMaskForDraggingInfo:

Returns a mask indicating what drag operations are allowed by the sender.

- (unsigned)webView:(WebView *)sender dragDestinationActionMaskForDraggingInfo:(id <NSDraggingInfo>)draggingInfo

Discussion

This method should return a mask indicating which operations are allowed when content is dragged over sender. For example, it may return WebDragDestinationActionAny to allow all actions, or return WebDragDestinationActionNone to not allow any actions. (See “Constants” for a complete list of possible return values.)

The draggingInfo argument is the information object for this drag operation. This method may be invoked multiple times while content is dragged over sender. When the content is dropped, sender sends webView:willPerformDragDestinationAction:forDraggingInfo:to the receiver.

If you do not implement this method, the default behavior returns WebDragDestinationActionAny.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebUIDelegate.h

webView:dragSourceActionMaskForPoint:

Returns a mask of allowable actions for a drag beginning at a set of coordinates on the sender.

- (unsigned)webView:(WebView *)sender dragSourceActionMaskForPoint:(NSPoint)point

Discussion

This method controls the behavior of dragging elements from a web view. It returns a mask indicating the allowed actions for a drag operation that begins at the coordinates specified by point within the coordinates of sender.

For example, this method may return WebDragSourceActionAny to allow all actions or may return WebDragSourceActionNone to disallow all actions. (See “Constants” for a complete list of possible return values.)

This method may be invoked multiple times while content is dragged from sender. When the content is dropped, sender sends webView:willPerformDragSourceAction:fromPoint:withPasteboard:to the receiver.

The default behavior returns (WebDragSourceActionAny & ~WebDragSourceActionLink) if the cursor is in an editable part of the WebView, WebDragDestinationActionAny otherwise.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebUIDelegate.h

webView:makeFirstResponder:

Sets the first responder of a web view’s window.

- (void)webView:(WebView *)sender makeFirstResponder:(NSResponder *)responder

Discussion

This method sets the first responder for a web view's window to responder. The responder argument is a view in a web view’s hierarchy. You might ignore this message if sender is not attached to a window yet.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webViewFirstResponder:

Declared In

WebUIDelegate.h

webView:mouseDidMoveOverElement:modifierFlags:

Updates information about the element the user moused over.

- (void)webView:(WebView *)sender mouseDidMoveOverElement:(NSDictionary *)elementInformation modifierFlags:(WebNSUInteger)modifierFlags

Discussion

When a user mouses over an element in a web view, various feedback is given. This method updates that feedback to reflect a new element or new modifier flags. The elementInformation dictionary describes the element that the mouse is over, and may be nil. See the WebView “Constants” for a description of the key-value pairs in this dictionary. The modifierFlags argument is an integer bit field indicating the modifier keys in effect during the event. See NSEvent for a description of possible modifiers.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebUIDelegate.h

webView:runBeforeUnloadConfirmPanelWithMessage:initiatedByFrame:

Displays an alert before a window closes.

- (BOOL)webView:(WebView *)senderrunBeforeUnloadConfirmPanelWithMessage:(NSString *)message initiatedByFrame:(WebFrame *)frame

Discussion

This method is used to display a file open panel for a file input control. This method uses a listener object to set the results of the file open panel, instead of returning the value directly. This approach allows delegates to implement the file open panel as a sheet. See the WebOpenPanelResultListener protocol for how to set the values of resultListener. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebUIDelegate.h

webView:runJavaScriptAlertPanelWithMessage:

Displays a JavaScript alert panel.

- (void)webView:(WebView *)sender runJavaScriptAlertPanelWithMessage:(NSString *)message

Discussion

This method is used to display a panel whenJavaScript code calls alert. Delegates should visually indicate that this panel comes from JavaScript. The panel should have, for example, a single OK button. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webView:runJavaScriptConfirmPanelWithMessage:
• – webView:runJavaScriptTextInputPanelWithPrompt:defaultText:

Declared In

WebUIDelegate.h

webView:runJavaScriptAlertPanelWithMessage:initiatedByFrame:

Displays a JavaScript alert panel.

- (void)webView:(WebView *)senderrunJavaScriptAlertPanelWithMessage:(NSString *)message initiatedByFrame:(WebFrame *)frame

Discussion

This method is used to display a panel whenJavaScript code calls alert. Delegates should visually indicate that this panel comes from JavaScript. The panel should have, for example, a single OK button. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

WebUIDelegate.h

webView:runJavaScriptConfirmPanelWithMessage:

Displays a JavaScript confirm panel.

- (BOOL)webView:(WebView *)sender runJavaScriptConfirmPanelWithMessage:(NSString *)message

Discussion

This method is used to display a confirmation panel when JavaScript code calls confirm. It returns YES if confirmed, NO otherwise. Delegates should visually indicate that this panel comes from JavaScript. The panel should have, for example, an OK and Cancel button. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webView:runJavaScriptAlertPanelWithMessage:
• – webView:runJavaScriptTextInputPanelWithPrompt:defaultText:

Declared In

WebUIDelegate.h

webView:runJavaScriptConfirmPanelWithMessage:initiatedByFrame:

Displays a JavaScript confirm panel.

- (BOOL)webView:(WebView *)senderrunJavaScriptConfirmPanelWithMessage:(NSString *)message initiatedByFrame:(WebFrame *)frame

Discussion

This method is used to display a confirmation panel when JavaScript code calls confirm. It returns YES if confirmed, NO otherwise. Delegates should visually indicate that this panel comes from JavaScript. The panel should have, for example, an OK and Cancel button. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

WebUIDelegate.h

webView:runJavaScriptTextInputPanelWithPrompt:defaultText:

Displays a JavaScript text input panel and returns the entered text.

- (NSString *)webView:(WebView *)sender runJavaScriptTextInputPanelWithPrompt:(NSString *)prompt defaultText:(NSString *)defaultText

Discussion

This method is used to provide an alternate prompt panel when JavaScript code calls prompt. Delegates should visually indicate that this panel comes from JavaScript. The panel should have an OK and Cancel button, and an editable text field. If you do not implement this method, a JavaScript text input panel is displayed.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webView:runJavaScriptAlertPanelWithMessage:
• – webView:runJavaScriptConfirmPanelWithMessage:

Declared In

WebUIDelegate.h

webView:runJavaScriptTextInputPanelWithPrompt:defaultText:initiatedByFrame:

Displays a JavaScript text input panel and returns the entered text.

- (NSString *)webView:(WebView *)senderrunJavaScriptTextInputPanelWithPrompt:(NSString *)promptdefaultText:(NSString *)defaultText initiatedByFrame:(WebFrame *)frame

Discussion

This method is used to provide an alternate prompt panel when JavaScript code calls prompt. Delegates should visually indicate that this panel comes from JavaScript. The panel should have an OK and Cancel button, and an editable text field. If you do not implement this method, a JavaScript text input panel is displayed.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

WebUIDelegate.h

webView:runOpenPanelForFileButtonWithResultListener:

Displays a file open panel for a file input control.

- (void)webView:(WebView *)senderrunOpenPanelForFileButtonWithResultListener:(id < WebOpenPanelResultListener >)resultListener

Discussion

This method is used to display a file open panel for a file input control. This method uses a listener object to set the results of the file open panel, instead of returning the value directly. This approach allows delegates to implement the file open panel as a sheet. See the WebOpenPanelResultListener protocol for how to set the values of resultListener. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebUIDelegate.h

webView:setContentRect:

Sets the window’s content view frame to contentRect.

- (void)webView:(WebView *)sender setContentRect:(NSRect)contentRect

Discussion

The content view is the highest accessible NSView object in the view hierarchy displayed in the window. A web view invokes this method instead of setting the content view’s frame directly, allowing delegates to augment the behavior, such as avoiding auto-saving of the size.

If this method is not implemented by the delegate, then webView:setFrame: is invoked with the rectangle returned by sending frameRectForContentRect:styleMask: to NSWindow.

Special Considerations

This method has been deprecated for Mac OS X v.10.5.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webViewContentRect:

Declared In

WebUIDelegate.h

webView:setFrame:

Sets the frame rectangle of a web view’s window to frame.

- (void)webView:(WebView *)sender setFrame:(NSRect)frame

Discussion

The sender invokes this method instead of setting the window’s frame directly, allowing delegates to augment the behavior, such as saving the original window size before resizing as a result of JavaScript running. If you do not implement this method, setFrame:display: is sent to the NSWindow containing sender passing YES as the display argument.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webViewFrame:

Declared In

WebUIDelegate.h

webView:setResizable:

Sets whether or not a web view’s window is resizable.

- (void)webView:(WebView *)sender setResizable:(BOOL)resizable

Discussion

By default, this method sets the window containing a web view to resizable. If you display multiple web views in a window then your user interface delegate should implement this method to handle this special case. If you do not implement this method, setShowsResizeIndicator: is sent to the NSWindow containing sender.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webViewIsResizable:

Declared In

WebUIDelegate.h

webView:setStatusBarVisible:

Sets the status bar visibility.

- (void)webView:(WebView *)sender setStatusBarVisible:(BOOL)visible

Discussion

Sets the visibility of the status bar to visible. If visible is YES, the delegate should display the status bar (if any). If visible is NO, the delegate should hide the status bar. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webViewIsStatusBarVisible:

Declared In

WebUIDelegate.h

webView:setStatusText:

Changes the status line for a web view's window.

- (void)webView:(WebView *)sender setStatusText:(NSString *)text

Discussion

Sets the status message displayed by a web view’s window, if any, to text. The delegate receives this message when a JavaScript function in the WebView explicitly sets the status text. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webViewStatusText:

Declared In

WebUIDelegate.h

webView:setToolbarsVisible:

Sets visibility for a web view's toolbars.

- (void)webView:(WebView *)sender setToolbarsVisible:(BOOL)visible

Discussion

This method sets the visibility of all toolbars associated with a web view (with the possible exception of a status bar) to visible. If visible is YES, the toolbars are shown, otherwise they are removed. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webViewAreToolbarsVisible:

Declared In

WebUIDelegate.h

webView:shouldPerformAction:fromSender:

Returns whether an action invoked by a sender object should be allowed.

- (BOOL)webView:(WebView *)sender shouldPerformAction:(SEL)action fromSender:(id)fromObject

Discussion

This method should return YES if the action invoked by fromObject should be allowed, NO otherwise. This method allows the delegate to control the WebView’s behavior when action methods are invoked. For example, if the action is copy:, the delegate may return NO in order to perform a copy in some other way than the default.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebUIDelegate.h

webView:validateUserInterfaceItem:defaultValidation:

Returns whether a user interface item is valid.

- (BOOL)webView:(WebView *)sender validateUserInterfaceItem:(id < NSValidatedUserInterfaceItem >)item defaultValidation:(BOOL)defaultValidation

Discussion

This method returns YES if the user interface item specified by item is valid, NO otherwise. The defaultValidation argument is YES if a web view believes it is a valid user interface item, NO otherwise. See NSUserInterfaceValidations and NSValidatedUserInterfaceItem for more information about user interface validation. If you do not implement this method, the value of defaultValidation is used.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebUIDelegate.h

webView:willPerformDragDestinationAction:forDraggingInfo:

Informs the receiver that the sender will perform a drag destination action.

- (void)webView:(WebView *)sender willPerformDragDestinationAction:(WebDragDestinationAction)action forDraggingInfo:(id < NSDraggingInfo >)draggingInfo

Discussion

This method informs the receiver that sender will perform a drag destination action specified by action. The draggingInfo argument is the information object for this drag operation. This method is invoked when the dragged content is dropped and the sender is about to perform the destination action. Invoked after the last invocation of the webView:dragDestinationActionMaskForDraggingInfo: method. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebUIDelegate.h

webView:willPerformDragSourceAction:fromPoint:withPasteboard:

Informs the receiver that the sender will perform a drag source action.

- (void)webView:(WebView *)sender willPerformDragSourceAction:(WebDragSourceAction)action fromPoint:(NSPoint)point withPasteboard:(NSPasteboard *)pasteboard

Discussion

This method informs the receiver that sender will perform a drag source action specified by action. The point argument is the point in the coordinates of sender where the drag operation began. This method is invoked when the dragged content is dropped and the sender is about to perform the source action. Invoked after the last invocation of the webView:dragSourceActionMaskForPoint: method. Gives the delegate an opportunity to modify the contents of the object on pasteboard before completing the source action. No action is taken if you do not implement this method.

Availability

• Available in Mac OS X v10.3.9 and later.

Declared In

WebUIDelegate.h

webViewAreToolbarsVisible:

Returns whether any toolbars are visible in a web view's window.

- (BOOL)webViewAreToolbarsVisible:(WebView *)sender

Discussion

Returns YES if a web view’s window has any toolbars that are currently on (besides the status bar), NO otherwise. If your application has more than one toolbar per window (for example, a regular command toolbar and a favorites bar) this method should return YES if any of the toolbars are turned on. The default behavior returns NO.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webView:setToolbarsVisible:

Declared In

WebUIDelegate.h

webViewClose:

Closes a web view within a window.

- (void)webViewClose:(WebView *)sender

Discussion

If you display multiple web views in a window then your might want to close just sender in your implementation. If unimplemented, the default behavior sends close to the NSWindow containing sender.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebUIDelegate.h

webViewContentRect:

Returns a web view window's content rectangle.

- (NSRect)webViewContentRect:(WebView *)sender

Discussion

The content view is the highest accessible NSView object in the view hierarchy displayed in the window. A web view invokes this method instead of setting the content view’s frame directly, allowing delegates to alter the size returned.

Special Considerations

This method has been deprecated for Mac OS X v.10.5.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webView:setContentRect:

Declared In

WebUIDelegate.h

webViewFirstResponder:

Returns the first responder of web view’s window.

- (NSResponder *)webViewFirstResponder:(WebView *)sender

Discussion

This method returns the view or subview that currently has the input focus. It returns nil or the default first responder if the sender is not attached to a window or if another view (not in the window) has the focus.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webView:makeFirstResponder:

Declared In

WebUIDelegate.h

webViewFocus:

Brings a web view’s window to the front and makes it the active window.

- (void)webViewFocus:(WebView *)sender

Discussion

This method (by default) brings a web view's window into focus. If you display multiple web views in a window then you might want to, in addition, focus the input on sender with webView:makeFirstResponder:.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webViewUnfocus:

Declared In

WebUIDelegate.h

webViewFrame:

Return the frame rectangle of a web view’s window.

- (NSRect)webViewFrame:(WebView *)sender

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webView:setFrame:

Declared In

WebUIDelegate.h

webViewIsResizable:

Returns YES if a web view’s window is resizable, NO otherwise.

- (BOOL)webViewIsResizable:(WebView *)sender

Discussion

If you display multiple web views in a window then your user interface delegate should implement this method to handle this special case.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webView:setResizable:

Declared In

WebUIDelegate.h

webViewIsStatusBarVisible:

Returns the visibility of the status bar for a web view's window.

- (BOOL)webViewIsStatusBarVisible:(WebView *)sender

Discussion

This method returns YES if a web view's status bar (if any) is visible, NO otherwise. If you do not implement this method, the default value will be NO.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webView:setStatusBarVisible:

Declared In

WebUIDelegate.h

webViewShow:

Shows a web view’s window and moves it to the front.

- (void)webViewShow:(WebView *)sender

Discussion

This method is typically used after a call to webView:createWebViewWithRequest:, which creates a new window. The web view's window will not be shown (or reordered) if you do not implement this method.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebUIDelegate.h

webViewStatusText:

Returns the current status line from a web view's window.

- (NSString *)webViewStatusText:(WebView *)sender

Discussion

Returns the status message displayed by a web view’s window if one has been set with webView:setStatusText:. Otherwise, it returns nil.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webView:setStatusText:

Declared In

WebUIDelegate.h

webViewUnfocus:

Relinquishes focus on a web view’s window.

- (void)webViewUnfocus:(WebView *)sender

Discussion

This method releases focus for the entire window. If you display multiple web views in a window then you might instead want to change the input focus to another view with webView:makeFirstResponder:.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – webViewFocus:

Declared In

WebUIDelegate.h

Constants

The following constants define tags used by the default menu items passed to the webView:contextMenuItemsForElement:defaultMenuItems: method. These constants define common actions the user might want to do to elements with in a page. You use the constants below to differentiate between the different types of menu items.

The following constants define the actions that the destination object of a drag operation can perform.

The following constants define the actions that the source object of a drag operation can perform.

---