WebFrame Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/WebKit.framework
Availability
Available in OS X v10.2 with Safari 1.0 and later.
Available in OS X v10.2.7 and later.
Companion guide
WebKit Objective-C Programming Guide
Declared in
WebFrame.h
Related sample code

Overview

A WebFrame object encapsulates the data displayed in a WebFrameView object. There is one WebFrame object per frame displayed in a WebView. An entire webpage is represented by a hierarchy of WebFrame objects in which the root object is called the main frame.

Each WebFrame also has a WebDataSource object that manages the loading of frame content. You use the loadRequest: method to initiate an asynchronous client request which will create a provisional data source. The provisional data source will transition to a committed data source once any data has been received.

There are some special, predefined, frame names that you can use when referring to or finding a WebFrame. Some of the predefined frame names are: “_self”, “_current”, “_parent”, and “_top.” See findFrameNamed: for a description of their meaning. Frame names may also be specified in the HTML source, or set by clients.

However, the group name is an arbitrary identifier used to group related frames. For example, JavaScript running in a frame can access any other frame in the same group. It's up to the application how it chooses to scope related frames.

Tasks

Initializing Frames

Loading Content

Getting the Data Source

Getting Related Frames and Views

Finding Frames

Getting DOM Objects

Instance Methods

childFrames

Returns the frames of the web frame’s immediate children.

- (NSArray *)childFrames
Return Value

The web frame’s immediate children. Each child web frame is an instance of WebFrame and corresponds to an HTML frameset or iframe element.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

dataSource

Returns the committed data source.

- (WebDataSource *)dataSource
Return Value

The committed data source, or nil if the provisional data source is not done loading.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

DOMDocument

Returns the web frame’s DOM document.

- (DOMDocument *)DOMDocument
Return Value

The web frame’s DOM document.

Discussion

Returns nil if the receiver doesn’t have a DOM document; for example, if it’s a standalone image.

Availability
  • Available in OS X v10.3.9 and later.
Declared In
WebFrame.h

findFrameNamed:

Returns a web frame that matches the given name.

- (WebFrame *)findFrameNamed:(NSString *)name
Parameters
name

The name of a frame.

Return Value

For predefined names, returns the receiver if name is “_self” or “_current”, returns the receiver’s parent frame if name is “_parent”, and returns the main frame if name is “_top”. Also returns the receiver if it is the main frame and name is either “_parent” or “_top.” For other names, this method returns the first frame that matches name. Returns nil if no match is found.

Discussion

This method searches the receiver and its descendents first, then the receiver’s parent and its children moving up the hierarchy until a match is found. If no match is found in the receivers hierarchy, this method will search for a matching frame in other main frame hierarchies.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

frameElement

Returns the web view’s DOM frame element.

- (DOMHTMLElement *)frameElement
Return Value

The web view’s DOM frame element. Returns nil if the receiver is the main frame.

Discussion

The returned object may be an instance of either DOMHTMLFrameElement, DOMHTMLIFrameElement or DOMHTMLObjectElement.

Availability
  • Available in OS X v10.3.9 and later.
Declared In
WebFrame.h

frameView

Returns the web frame’s view object.

- (WebFrameView *)frameView
Return Value

The web frame’s view object.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

globalContext

Returns the global JavaScript execution context for bridging between the WebKit and JavaScriptCore C API.

- (JSGlobalContextRef)globalContext
Return Value

The global JavaScript execution context.

Availability
  • Available in OS X v10.4.11 and later.
Related Sample Code
Declared In
WebFrame.h

initWithName:webFrameView:webView:

Initializes the receiver with a frame name, web frame view, and controlling web view.

- (id)initWithName:(NSString *)frameName webFrameView:(WebFrameView *)frameView webView:(WebView *)webView
Parameters
frameName

The frame name. Typically a custom name or nil (if none is specified). It would be inappropriate to use one of the predefined frame names described in findFrameNamed: as they have special meanings.

view

The view that displays this web frame—the view associated with the receiver.

webView

The parent view that manages the main frame and its children.

Return Value

An initialized web frame.

Discussion

Normally, you do not invoke this method directly. WebView objects automatically create the main frame and subsequent children when new content is loaded. Send a loadRequest: message to the main frame of a WebView to load web content.

This method is the designated initializer for the WebFrame class.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
Declared In
WebFrame.h

loadAlternateHTMLString:baseURL:forUnreachableURL:

Loads alternate content for a frame whose URL is unreachable.

- (void)loadAlternateHTMLString:(NSString *)string baseURL:(NSURL *)URL forUnreachableURL:(NSURL *)unreachableURL
Parameters
string

The string to use as the main page for the document.

URL

A file that is used to resolve relative URLs within the document.

unreachableURL

The URL for the alternate page content.

Discussion

Use this method to display page-level loading errors in a web view. Typically, a WebFrameLoadDelegate or WebPolicyDelegate object invokes this method from these methods: webView:didFailProvisionalLoadWithError:forFrame: (WebFrameLoadDelegate), webView:decidePolicyForMIMEType:request:frame:decisionListener: (WebPolicyDelegate), or webView:unableToImplementPolicyWithError:frame: (WebPolicyDelegate). If invoked from one of these methods, the back-forward list is maintained.

Availability
  • Available in OS X v10.3.9 and later.
Declared In
WebFrame.h

loadArchive:

Loads an archive into the web frame.

- (void)loadArchive:(WebArchive *)archive
Parameters
archive

The archive to load.

Availability
  • Available in OS X v10.3.9 and later.
Declared In
WebFrame.h

loadData:MIMEType:textEncodingName:baseURL:

Sets the main page contents, MIME type, content encoding, and base URL.

- (void)loadData:(NSData *)data MIMEType:(NSString *)MIMEType textEncodingName:(NSString *)encodingName baseURL:(NSURL *)URL
Parameters
data

The data to use for the main page of the document.

MIMEType

The MIME type of the data.

encodingName

The IANA encoding name (for example, “utf-8” or “utf-16”).

URL

A file that is used to resolve relative URLs within the document.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

loadHTMLString:baseURL:

Sets the main page contents and base URL.

- (void)loadHTMLString:(NSString *)string baseURL:(NSURL *)URL
Parameters
string

The string to use as the main page for the document.

Since the string is treated as a webpage with UTF-8 encoding, the default encoding for any script elements referenced by the HTML is also UTF-8. To avoid this, include a character set attribute on the script element.

URL

A file that is used to resolve relative URLs within the document.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

loadRequest:

Connects to a given URL by initiating an asynchronous client request.

- (void)loadRequest:(NSURLRequest *)request
Parameters
request

A client request.

Discussion

Creates a provisional data source that will transition to a committed data source once any data has been received. Use the dataSource method to check if a committed data source is available, and the stopLoading method to stop the load. This method is typically invoked on the main frame.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Related Sample Code
Declared In
WebFrame.h

name

Returns the web frame’s name.

- (NSString *)name
Return Value

The web frame’s name.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

parentFrame

Returns the web frame’s parent web frame.

- (WebFrame *)parentFrame
Return Value

The parent web frame, or nil if it has none.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

provisionalDataSource

Returns the provisional data source.

- (WebDataSource *)provisionalDataSource
Return Value

The provisional data source, or nil if either a load request is not in progress or a load request has completed.

Discussion

Use the loadRequest: method to initiate an asynchronous client request, which creates a provisional data source. The provisional data source transitions to a committed data source once any data is received.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

reload

Reloads the initial request passed as an argument to loadRequest:.

- (void)reload
Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

reloadFromOrigin

Performs an end-to-end revalidation using cache-validating conditionals if possible.

- (void)reloadFromOrigin
Discussion

End-to-end reload may be necessary if the cache entry has become corrupted for some reason.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
WebFrame.h

stopLoading

Stops any pending loads on the receiver’s data source, and those of its children.

- (void)stopLoading
Discussion

This method does not change the state of the receiver—whatever content has been loaded is preserved.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

webView

Returns the view object that manages the web frame.

- (WebView *)webView
Return Value

The view object that manages the entire hierarchy of web frame objects that contains the receiver.

Availability
  • Available in OS X v10.2 with Safari 1.0 and later.
  • Available in OS X v10.2.7 and later.
See Also
Declared In
WebFrame.h

windowObject

Returns the JavaScript window object.

- (WebScriptObject *)windowObject
Return Value

The JavaScript window object.

Availability
  • Available in OS X v10.4.11 and later.
Declared In
WebFrame.h


© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-03-25)

Did this document help you? Yes It's good, but... Not helpful...