Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

WebFrame Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/WebKit.framework
Availability
Available in Mac OS X v10.2 with Safari 1.0 and later.
Available in Mac OS X v10.2.7 and later.
Companion guide
Declared in
WebFrame.h

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 web page is represented by a hierarchy of WebFrame objects where 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, pre-defined, frame names that you can use when referring to, or finding a WebFrame. Some of the pre-defined 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 receiver’s immediate children frames.

- (NSArray *)childFrames

Discussion

Each child frame is an instance of WebFrame and corresponds to an HTML frame set or iframe element.

Availability
See Also
Declared In
WebFrame.h

dataSource

Returns the committed data source.

- (WebDataSource *)dataSource

Discussion

This method returns nil if the provisional data source is not done loading.

Availability
See Also
Declared In
WebFrame.h

DOMDocument

Returns the receiver’s DOM document.

- (DOMDocument *)DOMDocument

Discussion

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

Availability
Declared In
WebFrame.h

findFrameNamed:

Returns a web frame that matches the given name.

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

Discussion

For pre-defined 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. 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. Returns nil if no match is found.

Availability
See Also
Declared In
WebFrame.h

frameElement

Returns the receiver’s DOM frame element.

- (DOMHTMLElement *)frameElement

Discussion

The returned object may be an instance of either DOMHTMLFrameElement, DOMHTMLIFrameElement or DOMHTMLObjectElement. Returns nil if the receiver is the main frame.

Availability
Declared In
WebFrame.h

frameView

Returns the receiver’s view object.

- (WebFrameView *)frameView

Availability
See Also
Declared In
WebFrame.h

initWithName:webFrameView:webView:

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

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

Discussion

The frameName argument is typically a custom name or nil (if none is specified). It would be inappropriate to use one of the pre-defined frame names described in findFrameNamed: as they have special meanings. The frameView object is the view associated with the receiver, and webView is the parent view that manages the main frame and its children.

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 a WebView’s main frame to load web content.

This method is the designated initializer for the WebFrame class. Returns self.

Availability
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

Discussion

The string argument is the string that will be used as the main page for the document. The baseURL argument is used to resolve relative URLS within the document.

You can use this message to display page-level loading errors in a web view. Typically, a WebFrameLoadDelegate or WebPolicyDelegate 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
Declared In
WebFrame.h

loadArchive:

Loads an archive into the web frame.

- (void)loadArchive:(WebArchive *)archive

Availability
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

Discussion

This method Sets the data to use for the main page of the document to data, specifies the IANA encoding name as encodingName (as in “utf-8” or “utf-16”), and base URL as URL. The base URL allows relative URLs within a document.

Availability
See Also
Declared In
WebFrame.h

loadHTMLString:baseURL:

Sets the main page contents and base URL.

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

Discussion

Sets the string to use for the main page of the document to string, and the base URL to URL. The base URL allows relative URLs within a document.

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

Availability
See Also
Declared In
WebFrame.h

loadRequest:

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

- (void)loadRequest:(NSURLRequest *)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
See Also
Declared In
WebFrame.h

name

Returns the frame’s name.

- (NSString *)name

Availability
See Also
Declared In
WebFrame.h

parentFrame

Returns the receiver’s parent frame, or nil if it has none.

- (WebFrame *)parentFrame

Availability
See Also
Declared In
WebFrame.h

provisionalDataSource

Returns the provisional data source.

- (WebDataSource *)provisionalDataSource

Discussion

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. Therefore this method returns nil if either a load request is not in progress, or a load request has completed.

Availability
See Also
Declared In
WebFrame.h

reload

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

- (void)reload

Availability
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
See Also
Declared In
WebFrame.h

webView

Returns the web view object that manages this frame.

- (WebView *)webView

Discussion

The WebView object returned manages the entire hierarchy of frame objects that contains the receiver.

Availability
See Also
Declared In
WebFrame.h

Next Page > Hide TOC

Last updated: 2006-05-23

Did this document help you?
Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.
Get information on Apple products.
Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Copyright © 2007 Apple Inc.
All rights reserved. | Terms of use | Privacy Notice