---

WebView Class Reference

Overview

WebView is the core view class in the Web Kit Framework that manages interactions between WebFrame and WebFrameView classes. To embed web content in your application, you just create a WebView object, attach it to a window, and send a loadRequest: message to its main frame.

Behind the scenes, WebFrame objects encapsulate the content contained in a single frame element. A hierarchy of WebFrame objects is used to model an entire web page where the root is called the main frame. There is a WebFrameView object per WebFrame used to display the frame content. Therefore, there is a parallel hierarchy of WebFrameView objects used to render an entire page. The WebView is also the parent view of this hierarchy. You do not need to create WebFrame and WebFrameView objects directly. These objects are automatically created when the page loads, either programmatically or by the user clicking on a link.

You customize your embedded web content by implementing WebView delegates to handle certain aspects of the process. WebView has multiple delegates because the process of loading a web page is asynchronous and complicated if errors occur. All the WebView delegates use informal protocols so you only need to implement the delegates and methods that you wish to change—default implementations are already provided.

For example, you might want to implement the frame load and resource load delegates to monitor the load progress and display status messages. Applications that use multiple windows will want to implement a user interface delegate. See the individual delegate methods for more details: WebFrameLoadDelegate, WebPolicyDelegate, WebResourceLoadDelegate, and WebUIDelegate.

Another way to monitor load progress with less control is to observe the WebViewProgressEstimateChangedNotification, WebViewProgressFinishedNotification, and WebViewProgressStartedNotification notifications. For example, you could observe these notifications to implement a simple progress indicator in your application. You update the progress indicator by invoking the estimatedProgress method to get an estimate of the amount of content that is currently loaded.

A WebView is intended to support most features you would expect in a web browser except that it doesn’t implement the specific user interface for those features. You are responsible for implementing the user interface objects such as status bars, toolbars, buttons, and text fields. For example, a WebView manages a back-forward list by default, and has goBack: and goForward: action methods. It is your responsibility to create the buttons that would send theses action messages. Note, there is some overhead in maintaining a back-forward list and page cache, so you should disable it if your application doesn’t use it.

You use a WebPreferences object to encapsulate the preferences of a WebView, such as the font, text encoding, and image settings. You can modify the preferences for individual WebView instances or specify a shared WebPreferences object using the setPreferencesIdentifier: method. Use the setAutosaves: WebPreferences method to specify if the preferences should be automatically saved to the user defaults database.

You can also extend Web Kit by implementing your own document view and representation classes for specific MIME types. Use the registerViewClass:representationClass:forMIMEType: class method to register your custom classes with WebView.

Tasks

Registering Document Views and Representations

• + registerViewClass:representationClass:forMIMEType:

Initializing Views

• – initWithFrame:frameName:groupName:

Closing the View

• – close
• – shouldCloseWithWindow
• – setShouldCloseWithWindow:

Getting the Main Frame

• – mainFrame

Loading Content

• – stopLoading:
• – takeStringURLFrom:
• – reload:
• – estimatedProgress

Background Drawing

• – drawsBackground
• – setDrawsBackground:

Moving Back and Forward

• – setMaintainsBackForwardList:
• – backForwardList
• – canGoBack
• – goBack
• – goBack:
• – canGoForward
• – goForward
• – goForward:
• – goToBackForwardItem:

Changing the Text Size

• – canMakeTextLarger
• – makeTextLarger:
• – canMakeTextSmaller
• – makeTextSmaller:

Getting and Setting Delegates

• – downloadDelegate
• – setDownloadDelegate:
• – frameLoadDelegate
• – setFrameLoadDelegate:
• – policyDelegate
• – setPolicyDelegate:
• – resourceLoadDelegate
• – setResourceLoadDelegate:
• – UIDelegate
• – setUIDelegate:

Getting and Setting the Window

• – hostWindow
• – setHostWindow:

Getting and Setting Preferences

• – preferences
• – setPreferences:
• – preferencesIdentifier
• – setPreferencesIdentifier:

Getting and Setting Frame Contents

• – isLoading
• – selectedFrame
• – setMainFrameURL:
• – mainFrameURL
• – mainFrameTitle
• – mainFrameIcon
• – mainFrameDocument

Getting and Setting Content Information

• + canShowMIMEType:
• + MIMETypesShownAsHTML
• + setMIMETypesShownAsHTML:
• + canShowMIMETypeAsHTML:
• – supportsTextEncoding
• – customTextEncodingName
• – setCustomTextEncodingName:
• – textSizeMultiplier
• – setTextSizeMultiplier:

Searching the Document

• – searchFor:direction:caseSensitive:wrap:

Getting and Setting the Group Name

• – groupName
• – setGroupName:

Getting and Setting User-agent Strings

• – userAgentForURL:
• – applicationNameForUserAgent
• – setApplicationNameForUserAgent:
• – customUserAgent
• – setCustomUserAgent:

Processing JavaScript

• – stringByEvaluatingJavaScriptFromString:

Showing Modal Dialogs

• – webView:createWebViewModalDialogWithRequest:
• – webViewRunModal:

Using the Pasteboard

• + URLFromPasteboard:
• + URLTitleFromPasteboard:
• – pasteboardTypesForElement:
• – pasteboardTypesForSelection
• – writeElement:withPasteboardTypes:toPasteboard:
• – writeSelectionWithPasteboardTypes:toPasteboard:

Dragging

• – elementAtPoint:
• – moveDragCaretToPoint:
• – removeDragCaret

Cut, Copy and Paste Action Methods

• – copy:
• – copyFont:
• – cut:
• – delete:
• – paste:
• – pasteFont:
• – pasteAsPlainText:
• – pasteAsRichText:

Content Alignment Action Methods

• – alignCenter:
• – alignJustified:
• – alignLeft:
• – alignRight:

Changing the Font, Color and Other Attributes When Editing

• – changeFont:
• – changeAttributes:
• – changeDocumentBackgroundColor:
• – changeColor:

Spell Checking Action Methods

• – checkSpelling:
• – showGuessPanel:

Find Panel Action Method

• – performFindPanelAction:

Controlling Speakable Text

• – startSpeaking:
• – stopSpeaking:

Getting and Setting Document Editing Attributes

• – isEditable
• – setEditable:
• – smartInsertDeleteEnabled
• – setSmartInsertDeleteEnabled:
• – isContinuousSpellCheckingEnabled
• – setContinuousSpellCheckingEnabled:
• – spellCheckerDocumentTag
• – undoManager
• – editingDelegate
• – setEditingDelegate:
• – editableDOMRangeForPoint:

Editing Documents

• – replaceSelectionWithNode:
• – replaceSelectionWithText:
• – replaceSelectionWithMarkupString:
• – replaceSelectionWithArchive:
• – deleteSelection
• – moveToBeginningOfSentence:
• – moveToBeginningOfSentenceAndModifySelection:
• – moveToEndOfSentence:
• – moveToEndOfSentenceAndModifySelection:
• – selectSentence:
• – toggleContinuousSpellChecking:
• – toggleSmartInsertDelete:
• – canMakeTextStandardSize
• – makeTextStandardSize:
• – maintainsInactiveSelection

Selecting Content in the Document

• – selectedDOMRange
• – setSelectedDOMRange:affinity:
• – selectionAffinity

Getting and Setting CSS Properties

• – computedStyleForElement:pseudoElement:
• – mediaStyle
• – setMediaStyle:
• – typingStyle
• – setTypingStyle:
• – styleDeclarationWithText:
• – applyStyle:

Using WebScript

• – windowScriptObject

Class Methods

canShowMIMEType:

Returns whether the receiver can display content of a given MIME type.

+ (BOOL)canShowMIMEType:(NSString *)MIMEType

Discussion

Returns YES if the receiver can display content of the specified MIME type where MIMEType is one of the standard types like “image/gif”, NO otherwise.

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

WebView.h

canShowMIMETypeAsHTML:

Returns whether the receiver will interpret a mime type as HTML.

+ (BOOL)canShowMIMETypeAsHTML:(NSString *)MIMEType

Discussion

This method returns YES if the receiver will interpret MIMEType as HTML, NO otherwise.

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

WebView.h

MIMETypesShownAsHTML

Returns a list of MIME types that Web Kit will render as HTML.

+ (NSArray *)MIMETypesShownAsHTML

Discussion

This method returns an array containing NSString objects that represent the MIME types Web Kit will attempt to render as HTML.

Availability

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

See Also

• + setMIMETypesShownAsHTML:

Declared In

WebView.h

registerViewClass:representationClass:forMIMEType:

Specifies the view and representation objects to be used for specific MIME types.

+ (void)registerViewClass:(Class)viewClass representationClass:(Class)representationClass forMIMEType:(NSString *)MIMEType

Discussion

After invoking this method, when MIMEType content is encountered, instances of representationClass and viewClass are created to handle and display it. You may supply your own classes to handle specific MIME types as long as viewClass and representationClass conforms to the WebDocumentView and WebDocumentRepresentation protocols respectively. The MIMEType argument may represent a primary MIME type or subtype. For example, if MIMEType is “video/” the specified view and representation objects will be used for all video types. More specific subtype mappings, such as “image/gif”, takes precedence over primary type matching, such as “image/”.

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

WebView.h

setMIMETypesShownAsHTML:

Sets the MIME types that Web Kit will attempt to render as HTML.

+ (void)setMIMETypesShownAsHTML:(NSArray *)MIMETypes

Discussion

The MIMETypes argument is an array of NSString objects representing the MIME types. Typically, you create MIMETypes by adding additional types to the array returned by the MIMETypesShownAsHTML class method.

Availability

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

Declared In

WebView.h

URLFromPasteboard:

Returns a URL from the specified pasteboard.

+ (NSURL *)URLFromPasteboard:(NSPasteboard *)pasteboard

Discussion

This method supports multiple pasteboard types including NSRULPboardType. Returns nil if there’s no URL on pasteboard.

Availability

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

See Also

• + URLTitleFromPasteboard:

Declared In

WebView.h

URLTitleFromPasteboard:

Returns the title of a URL from the specified pasteboard.

+ (NSString *)URLTitleFromPasteboard:(NSPasteboard *)pasteboard

Discussion

Returns nil if there’s no URL on pasteboard, or the URL has no title.

Availability

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

See Also

• + URLFromPasteboard:

Declared In

WebView.h

Instance Methods

alignCenter:

Applies center alignment to content.

- (void)alignCenter:(id)sender

Discussion

This action method applies center alignment to selected content or all content if there’s no selection.

Availability

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

See Also

• – alignJustified:
• – alignLeft:
• – alignRight:

Declared In

WebView.h

alignJustified:

Applies full justification to content.

- (void)alignJustified:(id)sender

Discussion

This action method applies full justification to selected content or all content if there’s no selection.

Availability

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

See Also

• – alignJustified:
• – alignLeft:
• – alignRight:

Declared In

WebView.h

alignLeft:

Applies left justification to content.

- (void)alignLeft:(id)sender

Discussion

This action method applies left alignment to selected content or all content if there’s no selection.

Availability

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

See Also

• – alignJustified:
• – alignCenter:
• – alignRight:

Declared In

WebView.h

alignRight:

Applies right justification to content.

- (void)alignRight:(id)sender

Discussion

This action method applies right alignment to selected content or all content if there is no selection.

Availability

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

See Also

• – alignJustified:
• – alignLeft:
• – alignCenter:

Declared In

WebView.h

applicationNameForUserAgent

Returns the receiver’s application name that will be used in the user-agent string.

- (NSString *)applicationNameForUserAgent

Discussion

The user-agent is used by web sites to identify the client browser.

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

• – setApplicationNameForUserAgent:
• – setCustomUserAgent:
• – customUserAgent

Declared In

WebView.h

applyStyle:

Applies the CSS typing style to the current selection.

- (void)applyStyle:(DOMCSSStyleDeclaration *)style

Discussion

This method does nothing if there is no current selection or if the current selection is collapsed.

This method hides the complexities of applying styles to elements. If necessary, this method will make multiple passes over the range of the current selection to ensure that the requested style is applied to the elements in that range, and takes into account the complexities of CSS style application rules. This method also simplifies styling attributes so that the minimum number of styling directives are used to yield a given computed style.

Availability

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

See Also

• – setTypingStyle:
• – typingStyle
• – computedStyleForElement:pseudoElement:

Declared In

WebView.h

backForwardList

Returns the receiver’s back-forward list.

- (WebBackForwardList *)backForwardList

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

• – goBack
• – goForward
• – goToBackForwardItem:

Declared In

WebView.h

canGoBack

Returns YES if able to move backward, NO otherwise.

- (BOOL)canGoBack

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

• – goBack:
• – canGoForward
• – goForward:

Declared In

WebView.h

canGoForward

Returns YES if able to move forward, NO otherwise.

- (BOOL)canGoForward

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

• – goForward:
• – canGoBack
• – goBack:

Declared In

WebView.h

canMakeTextLarger

Returns YES if able to make the text larger, NO otherwise.

- (BOOL)canMakeTextLarger

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

• – makeTextLarger:
• – makeTextSmaller:
• – canMakeTextSmaller

Declared In

WebView.h

canMakeTextSmaller

Returns YES if able to make the text smaller, NO otherwise.

- (BOOL)canMakeTextSmaller

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

• – makeTextSmaller:
• – canMakeTextLarger
• – makeTextLarger:

Declared In

WebView.h

canMakeTextStandardSize

Returns YES if the current text size is a multiple of 1.

- (BOOL)canMakeTextStandardSize

Availability

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

Declared In

WebView.h

changeAttributes:

This action method changes the attributes of the current selection.

- (void)changeAttributes:(id)sender

Availability

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

See Also

• – changeFont:

Declared In

WebView.h

changeColor:

Invoked by the NSColorPanel sender to set the color of the selected content.

- (void)changeColor:(id)sender

Availability

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

See Also

• – changeDocumentBackgroundColor:

Declared In

WebView.h

changeDocumentBackgroundColor:

nvoked by the NSColorPanel sender to set the background color of the selected content.

- (void)changeDocumentBackgroundColor:(id)sender

Availability

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

See Also

• – changeColor:

Declared In

WebView.h

changeFont:

Changes the font.

- (void)changeFont:(id)sender

Discussion

This action method changes the font of the selection for the receiver, or of all content for the receiver. If the receiver doesn’t use the Font panel, this method does nothing.

Availability

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

See Also

• – changeAttributes:

Declared In

WebView.h

checkSpelling:

Searches for a misspelled word in the receiver.

- (void)checkSpelling:(id)sender

Discussion

This action method starts a search at the end of the selection and continues until it reaches a word suspected of being misspelled or the end of the content. If a word isn’t recognized by the spelling server, a showGuessPanel: message is sent to the receiver which opens the Guess panel and allows the user to make a correction or add the word to the local dictionary.

Availability

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

See Also

• – showGuessPanel:

Declared In

WebView.h

close

Closes the WebView when it’s no longer needed.

- (void)close

Discussion

Closes the WebView so that it can be garbage collected.

Availability

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

Declared In

WebView.h

computedStyleForElement:pseudoElement:

Returns the computed style of an element and its pseudo element.

- (DOMCSSStyleDeclaration *)computedStyleForElement:(DOMElement *)element pseudoElement:(NSString *)pseudoElement

Discussion

This method returns an immutable DOMCSSStyleDeclaration object describing the computed style of element and pseudoElement according to the Cascading Style Sheets Specification at http://www.w3.org/TR/CSS21. It returns nil if the receiver doesn’t display element.

Availability

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

See Also

• – typingStyle
• – setTypingStyle:
• – applyStyle:

Declared In

WebView.h

copy:

Copies the seliected content to the general pasteboard.

- (void)copy:(id)sender

Discussion

This action method copies the selected content onto the general pasteboard, in as many formats as the receiver supports. For example, a plain text object uses NSStringPboardType for plain text, and a rich text object also uses NSRTFPboardType.

Availability

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

See Also

• – cut:
• – paste:

Declared In

WebView.h

copyFont:

Copies font info onto the font pasteboard.

- (void)copyFont:(id)sender

Discussion

This action method copies the font information for the first character of the selection (or for the insertion point) onto the font pasteboard, as NSFontPboardType.

Availability

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

See Also

• – pasteFont: