Class

Web​View

Web​View is the core view class in the WebKit framework that manages interactions between the Web​Frame and Web​Frame​View classes. To embed web content in your application, you just create a Web​View object, attach it to a window, and send a load(_:​) message to its main frame.

Overview

Behind the scenes, Web​Frame objects encapsulate the content contained in a single frame element. A hierarchy of Web​Frame objects is used to model an entire webpage where the root is called the main frame. There is a Web​Frame​View object per Web​Frame object used to display the frame content. Therefore, there is a parallel hierarchy of Web​Frame​View objects used to render an entire page. The Web​View object is also the parent view of this hierarchy. You do not need to create Web​Frame and Web​Frame​View 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 Web​View delegates to handle certain aspects of the process. Web​View objects have multiple delegates because the process of loading a webpage is asynchronous and complicated if errors occur. All the Web​View 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, Web​Resource​Load​Delegate, and Web​UIDelegate.

Another way to monitor load progress with less control is to observe the Web​View​Progress​Estimate​Changed, Web​View​Progress​Finished, and Web​View​Progress​Started 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 estimated​Progress method to get an estimate of the amount of content that is currently loaded.

A Web​View 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 Web​View object manages a back-forward list by default, and has go​Back(_:​) and go​Forward(_:​) 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 Web​Preferences object to encapsulate the preferences of a Web​View object, such as the font, text encoding, and image settings. You can modify the preferences for individual Web​View objects or specify a shared Web​Preferences object using the preferences​Identifier method. Use the autosaves Web​Preferences 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 register​Class(_:​representation​Class:​for​MIMEType:​) class method to register your custom classes with a Web​View object.

Symbols

Registering Document Views and Representations

class func register​URLScheme(as​Local:​ String!)

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

class func register​Class(Any​Class!, representation​Class:​ Any​Class!, for​MIMEType:​ String!)

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

Initializing Views

init!(frame:​ NSRect, frame​Name:​ String!, group​Name:​ String!)

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

Closing the View

func close()

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

var should​Close​With​Window:​ Bool

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

Getting the Main Frame

var main​Frame:​ Web​Frame!

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

Loading Content

func stop​Loading(Any?)

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

func take​String​URLFrom(Any?)

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

func reload(Any?)

An action method that reloads the current page.

func reload​From​Origin(Any?)

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

var estimated​Progress:​ Double

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

Drawing

var draws​Background:​ Bool

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

var should​Update​While​Offscreen:​ Bool

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

func set​Maintains​Back​Forward​List(Bool)

Sets whether to use a back-forward list.

var can​Go​Back:​ Bool

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

func go​Back()

Loads the previous location in the back-forward list.

func go​Back(Any?)

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

var can​Go​Forward:​ Bool

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

func go​Forward()

Loads the next location in the back-forward list.

func go​Forward(Any?)

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

func go(to​Back​Forward​Item:​ Web​History​Item!)

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

Changing the Text Size

var can​Make​Text​Larger:​ Bool

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

func make​Text​Larger(Any?)

Action method that increases the text size by one unit.

var can​Make​Text​Smaller:​ Bool

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

func make​Text​Smaller(Any?)

Action method that reduces the text size by one unit.

Getting and Setting Delegates

var ui​Delegate:​ Web​UIDelegate!

The receiver's user interface delegate.

Getting and Setting the Window

var host​Window:​ NSWindow!

The receiver’s host window.

Getting and Setting Preferences

var preferences:​ Web​Preferences!

The receiver’s preferences.

var preferences​Identifier:​ String!

The identifier of the receiver’s preferences.

Getting and Setting Frame Contents

var is​Loading:​ Bool

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

var selected​Frame:​ Web​Frame!

The frame with the active selection.

var main​Frame​URL:​ String!

The URL that the main frame loads.

var main​Frame​Title:​ String!

The HTML title of the loaded page.

var main​Frame​Document:​ DOMDocument!

The DOM document for the main frame.

Getting and Setting Content Information

class func can​Show​MIMEType(String!)

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

class func mime​Types​Shown​As​HTML()

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

class func set​MIMETypes​Shown​As​HTML([Any]!)

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

class func can​Show​MIMEType(as​HTML:​ String!)

Returns whether the receiver interprets a MIME type as HTML.

var supports​Text​Encoding:​ Bool

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

var text​Size​Multiplier:​ Float

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

Searching the Document

func search(for:​ String!, direction:​ Bool, case​Sensitive:​ Bool, wrap:​ Bool)

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

Getting and Setting the Group Name

var group​Name:​ String!

The receiver’s group name.

Getting and Setting User-agent Strings

func user​Agent(for:​ URL!)

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

var application​Name​For​User​Agent:​ String!

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

var custom​User​Agent:​ String!

The receiver’s custom user-agent string.

Processing JavaScript

Using the Pasteboard

class func url(from:​ NSPasteboard!)

Returns a URL from the specified pasteboard.

class func url​Title(from:​ NSPasteboard!)

Returns the title of a URL from the specified pasteboard.

func pasteboard​Types(for​Element:​ [Any​Hashable :​ Any]!)

Returns an array of pasteboard types for an element.

var pasteboard​Types​For​Selection:​ [Any]!

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

func write​Selection(with​Pasteboard​Types:​ [Any]!, to:​ NSPasteboard!)

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

Dragging

func element(at:​ NSPoint)

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

func move​Drag​Caret(to:​ NSPoint)

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

func remove​Drag​Caret()

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

Cut, Copy and Paste Action Methods

func copy(Any?)

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

func copy​Font(Any?)

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

func cut(Any?)

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

func delete(Any?)

An action method that deletes the selected content.

func paste(Any?)

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

func paste​Font(Any?)

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

func paste​As​Plain​Text(Any?)

An action method that pastes pasteboard content as plain text.

func paste​As​Rich​Text(Any?)

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

Content Alignment Action Methods

func align​Center(Any?)

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

func align​Justified(Any?)

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

func align​Left(Any?)

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

func align​Right(Any?)

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

func change​Font(Any?)

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

func change​Attributes(Any?)

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

func change​Document​Background​Color(Any?)

Sets the background color of the selected content.

func change​Color(Any?)

Sets the color of the selected content.

Spell-checking Action Methods

func check​Spelling(Any?)

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

func show​Guess​Panel(Any?)

An action method that shows a spelling correction panel.

Find Panel Action Method

func perform​Find​Panel​Action(Any?)

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

Controlling Speakable Text

func start​Speaking(Any?)

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

func stop​Speaking(Any?)

An action method that stops speaking that is in progress.

Getting and Setting Document Editing Attributes

var is​Editable:​ Bool

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

var smart​Insert​Delete​Enabled:​ Bool

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

var is​Continuous​Spell​Checking​Enabled:​ Bool

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

var spell​Checker​Document​Tag:​ Int

The spell-checker document tag for this document.

var undo​Manager:​ Undo​Manager!

The receiver’s undo manager.

func editable​DOMRange(for:​ NSPoint)

Returns the editable DOM object located at a given point.

Editing Documents

func replace​Selection(with:​ DOMNode!)

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

func replace​Selection(with​Text:​ String!)

Replaces the current selection with a string of text.

func replace​Selection(with​Markup​String:​ String!)

Replaces the current selection with mixed text and markup.

func replace​Selection(with:​ Web​Archive!)

Replaces the current selection with an archive's contents.

func delete​Selection()

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

func move​To​Beginning​Of​Sentence(Any?)

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

func move​To​Beginning​Of​Sentence​And​Modify​Selection(Any?)

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

func move​To​End​Of​Sentence(Any?)

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

func move​To​End​Of​Sentence​And​Modify​Selection(Any?)

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

func select​Sentence(Any?)

Selects the entire sentence around the insertion point.

func toggle​Continuous​Spell​Checking(Any?)

Toggles whether continuous spell checking is available.

func toggle​Smart​Insert​Delete(Any?)

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

var can​Make​Text​Standard​Size:​ Bool

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

func make​Text​Standard​Size(Any?)

Resets the text size to a multiple of 1.

var maintains​Inactive​Selection:​ Bool

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

Selecting Content in the Document

Getting and Setting CSS Properties

func computed​Style(for:​ DOMElement!, pseudo​Element:​ String!)

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

var media​Style:​ String!

The receiver’s CSS media property.

var typing​Style:​ DOMCSSStyle​Declaration!

The receiver’s CSS typing style.

func style​Declaration(with​Text:​ String!)

Returns the CSS style declaration for the specified text.

func apply​Style(DOMCSSStyle​Declaration!)

Applies the CSS typing style to the current selection.

Using WebScript

var window​Script​Object:​ Web​Script​Object!

The receiver’s window object from the scripting environment.

Constants

Element Dictionary Keys

Predefined keys used to access an element dictionary.

Notifications

static let Web​View​Did​Begin​Editing:​ NSNotification.Name

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

static let Web​View​Did​Change:​ NSNotification.Name

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

static let Web​View​Did​Change​Selection:​ NSNotification.Name

Posted when a web view changes its typing selection.

static let Web​View​Did​End​Editing:​ NSNotification.Name

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

static let Web​View​Progress​Estimate​Changed:​ NSNotification.Name

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

static let Web​View​Progress​Finished:​ NSNotification.Name

Posted by a WebView object when the load has finished.

static let Web​View​Progress​Started:​ NSNotification.Name

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

Instance Methods

See Also