Class

WebView

WebView is the core view class in the WebKit framework that manages interactions between the 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.

Declaration

@interface WebView : NSView

Overview

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 webpage where the root is called the main frame. There is a WebFrameView object per WebFrame object used to display the frame content. Therefore, there is a parallel hierarchy of WebFrameView objects used to render an entire page. The WebView object 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 a link.

You customize your embedded web content by implementing WebView delegates to handle certain aspects of the process. WebView objects have multiple delegates because the process of loading a webpage is asynchronous and complicated if errors occur. All the WebView delegates use informal protocols so you only need to implement only the delegates and methods that define the behavior 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 may want to implement a user interface delegate. See the individual informal delegate protocols 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 object 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 object 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 object, such as the font, text encoding, and image settings. You can modify the preferences for individual WebView objects or specify a shared WebPreferences object using the preferencesIdentifier method. Use the autosaves WebPreferences method to specify whether the preferences should be automatically saved to the user defaults database.

You can also extend WebKit 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 a WebView object.

Topics

Registering Document Views and Representations

+ registerURLSchemeAsLocal:

Adds the specified URL scheme to the list of local schemes.

+ registerViewClass:representationClass:forMIMEType:

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

Initializing Views

- initWithFrame:frameName:groupName:

Initializes the receiver with a frame rectangle, frame name, and group name.

Closing the View

- close

Closes the web view when it’s no longer needed.

shouldCloseWithWindow

A Boolean that indicates whether the web view should close when its window or host window closes.

Getting the Main Frame

mainFrame

The main frame, the root of the web frame hierarchy for this page.

Loading Content

- stopLoading:

An action method that stops the loading of any web frame content managed by the receiver.

- takeStringURLFrom:

Sets the receiver’s current location by obtaining a URL string from the sender.

- reload:

An action method that reloads the current page.

- reloadFromOrigin:

Action method that performs an end-to-end revalidation using cache-validating conditionals if possible.

estimatedProgress

An estimate, as a percentage, of the amount of content that is currently loaded.

Drawing

drawsBackground

A Boolean that indicates whether the web view draws a background.

shouldUpdateWhileOffscreen

A Boolean that inidicates whether the web view should update even when it is not in a window that is currently visible.

Moving Back and Forward

- setMaintainsBackForwardList:

Sets whether to use a back-forward list.

backForwardList

The receiver’s back-forward list.

canGoBack

A Boolean that indicates whether the previous location can be loaded.

- goBack

Loads the previous location in the back-forward list.

- goBack:

An action method that loads the previous location in the back-forward list.

canGoForward

A Boolean that indicates whether the next location can be loaded.

- goForward

Loads the next location in the back-forward list.

- goForward:

An action method that loads the next location in the back-forward list.

- goToBackForwardItem:

Loads a specific location from the back-forward list and sets it as the current item.

Changing the Text Size

canMakeTextLarger

A Boolean that indicates whether the text can be made larger.

- makeTextLarger:

Action method that increases the text size by one unit.

canMakeTextSmaller

A Boolean that indicates whether the text can be made smaller.

- makeTextSmaller:

Action method that reduces the text size by one unit.

Getting and Setting Delegates

downloadDelegate

The receiver’s download delegate.

frameLoadDelegate

The receiver’s frame load delegate.

policyDelegate

The receiver's policy delegate.

resourceLoadDelegate

The receiver’s resource load delegate.

UIDelegate

The receiver's user interface delegate.

Getting and Setting the Window

hostWindow

The receiver’s host window.

Getting and Setting Preferences

preferences

The receiver’s preferences.

preferencesIdentifier

The identifier of the receiver’s preferences.

Getting and Setting Frame Contents

loading

A Boolean that indicates whether the web view is loading content.

selectedFrame

The frame with the active selection.

mainFrameURL

The URL that the main frame loads.

mainFrameTitle

The HTML title of the loaded page.

mainFrameIcon

The site’s favicon.

mainFrameDocument

The DOM document for the main frame.

Getting and Setting Content Information

+ canShowMIMEType:

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

+ MIMETypesShownAsHTML

Returns a list of MIME types that WebKit renders as HTML.

+ setMIMETypesShownAsHTML:

Sets the MIME types that WebKit attempts to render as HTML.

+ canShowMIMETypeAsHTML:

Returns whether the receiver interprets a MIME type as HTML.

supportsTextEncoding

A Boolean that indicates whether the document view supports different text encodings.

customTextEncodingName

The custom text encoding name.

textSizeMultiplier

The font size multiplier for text displayed in web frame view objects managed by the receiver.

Searching the Document

- searchFor:direction:caseSensitive:wrap:

Searches a document view for a string and highlights it if it is found.

Getting and Setting the Group Name

groupName

The receiver’s group name.

Getting and Setting User-agent Strings

- userAgentForURL:

Returns the appropriate user-agent string for a given URL.

applicationNameForUserAgent

The receiver’s application name that is used in the user-agent string.

customUserAgent

The receiver’s custom user-agent string.

Processing JavaScript

- stringByEvaluatingJavaScriptFromString:

Returns the result of running a script.

Using the Pasteboard

+ URLFromPasteboard:

Returns a URL from the specified pasteboard.

+ URLTitleFromPasteboard:

Returns the title of a URL from the specified pasteboard.

- pasteboardTypesForElement:

Returns an array of pasteboard types for an element.

pasteboardTypesForSelection

An array of pasteboard types that can be used for the current selection of the receiver.

- writeElement:withPasteboardTypes:toPasteboard:

Writes an element to the pasteboard using a list of types.

- writeSelectionWithPasteboardTypes:toPasteboard:

Writes the receiver’s current selection to a pasteboard using a list of types.

Dragging

- elementAtPoint:

Returns a dictionary description of the element at a given point in the receiver’s coordinates.

- moveDragCaretToPoint:

Moves the drag caret that indicates the destination of a drag operation to a given point.

- removeDragCaret

Removes the drag caret that indicates the destination of a drag operation.

Cut, Copy and Paste Action Methods

- copy:

Action method that copies the selected content to the general pasteboard.

- copyFont:

An action method that copies font information onto the font pasteboard.

- cut:

An action method that deletes selected content and puts it on the general pasteboard.

- delete:

An action method that deletes the selected content.

- paste:

An action method that pastes content from the pasteboard at the insertion point or over the selection.

- pasteFont:

An action method that pastes font information from the font pasteboard.

- pasteAsPlainText:

An action method that pastes pasteboard content as plain text.

- pasteAsRichText:

An action method that pastes pasteboard content into the receiver as rich text, maintaining its attributes.

Content Alignment Action Methods

- alignCenter:

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

- alignJustified:

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

- alignLeft:

An action method that applies left justification to selected content or all content if there’s no selection.

- alignRight:

An action method that applies right justification to selected content or all content if there is no selection.

Changing the Font, Color and Other Attributes When Editing

- changeFont:

An action method that changes the font of the selection, or all content if there is no selection.

- changeAttributes:

An action method that changes the attributes of the current selection.

- changeDocumentBackgroundColor:

Sets the background color of the selected content.

- changeColor:

Sets the color of the selected content.

Spell-checking Action Methods

- checkSpelling:

An action method that searches for a misspelled word in the receiver.

- showGuessPanel:

An action method that shows a spelling correction panel.

Find Panel Action Method

- performFindPanelAction:

An action method that opens the Find menu and Find panel.

Controlling Speakable Text

- startSpeaking:

An action method that starts speaking the selected text or all text if there’s no selection.

- stopSpeaking:

An action method that stops speaking that is in progress.

Getting and Setting Document Editing Attributes

editable

A Boolean that indicates whether the user is allowed to edit the document.

smartInsertDeleteEnabled

A Boolean that indicates whether smart-space insertion and deletion is enabled.

continuousSpellCheckingEnabled

A Boolean that indicates whether the web view has continuous spell-checking enabled.

spellCheckerDocumentTag

The spell-checker document tag for this document.

undoManager

The receiver’s undo manager.

editingDelegate

The receiver’s editing delegate.

- editableDOMRangeForPoint:

Returns the editable DOM object located at a given point.

Editing Documents

- replaceSelectionWithNode:

Replaces the receiver’s current selection with the specified DOM node.

- replaceSelectionWithText:

Replaces the current selection with a string of text.

- replaceSelectionWithMarkupString:

Replaces the current selection with mixed text and markup.

- replaceSelectionWithArchive:

Replaces the current selection with an archive's contents.

- deleteSelection

Deletes the receiver’s current selection unless it’s collapsed.

- moveToBeginningOfSentence:

Moves the insertion point to the beginning of the current sentence.

- moveToBeginningOfSentenceAndModifySelection:

Moves the insertion point and extends the selection to the beginning of the current sentence.

- moveToEndOfSentence:

Moves the insertion point to the end of the current sentence.

- moveToEndOfSentenceAndModifySelection:

Moves the insertion point and extends the selection to the end of the current sentence.

- selectSentence:

Selects the entire sentence around the insertion point.

- toggleContinuousSpellChecking:

Toggles whether continuous spell checking is available.

- toggleSmartInsertDelete:

Toggles whether spaces around selected words are inserted or deleted to preserve proper spacing and punctuation.

canMakeTextStandardSize

A Boolean that indicates whether the current text size is a multiple of 1.

- makeTextStandardSize:

Resets the text size to a multiple of 1.

maintainsInactiveSelection

A Boolean that indicates whether the selection is maintained when focus is lost.

Selecting Content in the Document

selectedDOMRange

The range of the current selection.

- setSelectedDOMRange:affinity:

Selects a range of nodes.

selectionAffinity

The current selection affinity.

Getting and Setting CSS Properties

- computedStyleForElement:pseudoElement:

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

mediaStyle

The receiver’s CSS media property.

typingStyle

The receiver’s CSS typing style.

- styleDeclarationWithText:

Returns the CSS style declaration for the specified text.

- applyStyle:

Applies the CSS typing style to the current selection.

Using WebScript

windowScriptObject

The receiver’s window object from the scripting environment.

Constants

Element Dictionary Keys

Predefined keys used to access an element dictionary.

Notifications

WebViewDidBeginEditingNotification

Posted when a web view begins any operation that changes its contents in response to user editing.

WebViewDidChangeNotification

Posted when a web view performs any operation that changes its contents in response to user editing.

WebViewDidChangeSelectionNotification

Posted when a web view changes its typing selection.

WebViewDidChangeTypingStyleNotification

Posted when a web view changes its typing style.

WebViewDidEndEditingNotification

Posted when a web view ends any operation that changes its contents in response to user editing.

WebViewProgressEstimateChangedNotification

Posted by a WebView object when the estimated progress value of a load changes.

WebViewProgressFinishedNotification

Posted by a WebView object when the load has finished.

WebViewProgressStartedNotification

Posted by a WebView object when a load begins, including a load that is initiated in a subframe.

Instance Methods

Relationships

Inherits From

See Also

Setting Up a Web View (Legacy)

WebPreferences

WebPreferences encapsulates the preferences you can change per WebView object. These preferences include font, text encoding, and image settings. Normally a WebView object uses the standard preferences returned by the standardPreferences class method. However, you can modify the preferences for individual WebView instances too. Use the preferencesIdentifier WebView method to change a WebView object’s preferences, or to share preferences between WebView objects. Use the autosaves method to specify if the preferences object should be automatically saved to the user defaults database.

Deprecated
WebUIDelegate

Web view user interface delegates implement this protocol to control the opening of new windows, augment the behavior of default menu items displayed when the user clicks elements, and perform other user interface–related tasks. These methods can 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, need to implement some of these methods to handle that case. The default implementation assumes one window per web view, so non-conventional user interfaces might implement a user interface delegate.

Deprecated