WebFrameLoadDelegate Protocol Reference

(informal protocol)

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
Declared in
WebFrameLoadDelegate.h

Overview

WebView frame load delegates implement this informal protocol to be notified while frame loads are in progress. Delegates are notified when a frame load starts, when a page title or icon is loaded, when a redirect occurs, when a data source is committed, and when the change is complete. The webView:didStartProvisionalLoadForFrame: method is invoked when a frame load starts, and the webView:didFinishLoadForFrame: method is invoked when the change is done. However, depending on the content being loaded, some of the other methods defined in this protocol may be invoked multiple times. All the methods in this protocol are optional.

Tasks

State Change Messages

Data Received Messages

Error Messages

Client and Server Redirect Messages

WebScript Messages

Instance Methods

webView:didCancelClientRedirectForFrame:

Invoked when a client redirect is cancelled.

- (void)webView:(WebView *)sender didCancelClientRedirectForFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

frame

The frame being loaded.

Discussion

This might happen if a frame changes locations before a pending client redirect is fired. The client redirect occurred in frame.

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

webView:didChangeLocationWithinPageForFrame:

Invoked when the scroll position within a frame changes.

- (void)webView:(WebView *)sender didChangeLocationWithinPageForFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

frame

The frame being loaded.

Discussion

Typically, invoked when the user clicks on an anchor within a page. Additional information about the request can be obtained from the data source of frame.

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

webView:didClearWindowObject:forFrame:

Invoked when the JavaScript window object in a frame is ready for loading.

- (void)webView:(WebView *)sender didClearWindowObject:(WebScriptObject *)windowObject forFrame:(WebFrame *)frame
Parameters
sender

The web view sending this message.

windowObject

The cleared JavaScript window object.

frame

The frame containing the JavaScript window object.

Discussion

Use this method to set custom properties on the window object before the page is actually loaded. Every time a frame loads or is reloaded all DOM properties are cleared from the window object so the new page has a fresh window object to use. If the page you are loading depends on specific window object properties to exist, they should be added at this point before any scripts are executed.

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

webView:didCommitLoadForFrame:

Invoked when content starts arriving for a page load.

- (void)webView:(WebView *)sender didCommitLoadForFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

frame

The frame being loaded.

Discussion

This method is invoked when a data source transitions from a provisional to committed state—that is, once the data source of frame has received one byte or more of data. This method is invoked after a webView:didStartProvisionalLoadForFrame: message but before a webView:didFinishLoadForFrame: message is sent to the delegate.

In some cases, a single frame load may be committed more than once. This happens in the case of multipart/x-mixed-replace, also known as a “server push.” In this case, a single frame load results in multiple documents loaded in sequence. This method is invoked once for each document that is successfully loaded.

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

webView:didFailLoadWithError:forFrame:

Invoked when an error occurs loading a committed data source.

- (void)webView:(WebView *)sender didFailLoadWithError:(NSError *)error forFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

error

The type of error that occurred during the load.

frame

The frame being loaded.

Discussion

This method is called after the data source has been committed but resulted in an error.

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

webView:didFailProvisionalLoadWithError:forFrame:

Invoked if an error occurs when starting to load data for a page.

- (void)webView:(WebView *)sender didFailProvisionalLoadWithError:(NSError *)error forFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

error

Specifies the type of error that occurred during the load.

frame

The frame being loaded.

Discussion

The frame continues to display the committed data source if there is one.

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

webView:didFinishLoadForFrame:

Invoked when a page load completes.

- (void)webView:(WebView *)sender didFinishLoadForFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

frame

The frame being loaded.

Discussion

This method is invoked when a location request for frame has completed; that is, when all the resources are done loading. Additional information about the request can be obtained from the data source of frame.

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

webView:didReceiveIcon:forFrame:

Invoked when a page icon changes.

- (void)webView:(WebView *)sender didReceiveIcon:(NSImage *)image forFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

image

The page icon for a data source.

frame

The frame being loaded.

Discussion

This method may be invoked multiple times before all resources for frame are completely loaded. Sometimes a page uses a default icon or stored image that changes when the actual images is loaded.

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

webView:didReceiveServerRedirectForProvisionalLoadForFrame:

Invoked when a provisional data source for a frame receives a server redirect.

- (void)webView:(WebView *)sender didReceiveServerRedirectForProvisionalLoadForFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

frame

The frame being loaded.

Discussion

A server redirect is when one URL location is redirected to another. Additional information about the new request can be obtained from the data source of frame.

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

webView:didReceiveTitle:forFrame:

Invoked when the page title of a frame loads or changes.

- (void)webView:(WebView *)sender didReceiveTitle:(NSString *)title forFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

title

The newly loaded title.

frame

The frame being loaded.

Discussion

This method may be invoked multiple times before all resources for frame are completely loaded. Delegates might implement this message to display the page title to the user.

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

webView:didStartProvisionalLoadForFrame:

Invoked when a page load is in progress in a given frame.

- (void)webView:(WebView *)sender didStartProvisionalLoadForFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

frame

The frame being loaded.

Discussion

This method is invoked when a new client request is made by sender to load a provisional data source for frame. This method may be invoked after sending loadRequest: to a WebFrame object or as a consequence of the user clicking a link displayed in a web frame view. Delegates might implement this method to notify the user that a request is in progress. Additional information about the request can be obtained from the data source of frame.

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

webView:willCloseFrame:

Invoked when a frame will be closed.

- (void)webView:(WebView *)sender willCloseFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

frame

The frame being loaded.

Discussion

Invoked right before WebKit is done with frame and the objects it owns.

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

webView:willPerformClientRedirectToURL:delay:fireDate:forFrame:

Invoked when a frame receives a client redirect and before it is fired.

- (void)webView:(WebView *)sender willPerformClientRedirectToURL:(NSURL *)URL delay:(NSTimeInterval)seconds fireDate:(NSDate *)date forFrame:(WebFrame *)frame
Parameters
sender

The web view containing the frame.

URL

The redirect location.

seconds

The number of seconds from date before the redirect will be fired.

date

The date and time to fire the redirect.

frame

The frame where the redirect occurred.

Discussion

Delegates might implement this method to display progress while a client redirect is pending. If a client redirect is cancelled the webView:didCancelClientRedirectForFrame: delegate method is invoked.

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