WebBackForwardList Class Reference

Inherits from
Conforms to
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
WebBackForwardList.h

Overview

A WebBackForwardList object maintains a list of visited pages used to go back and forward to the most recent page. A WebBackForwardList object maintains only the list data—it does not perform actual page loads (in other words, it does not make any client requests). If you need to perform a page load, see the loadRequest: method in WebFrame Class Reference to find out how to do this.

Items are typically inserted in a back-forward list in the order they are visited. A WebBackForwardList object also maintains the notion of the current item (which is always at index 0), the preceding item (which is at index -1), and the following item (which is at index 1). The goBack and goForward methods move the current item backward or forward by one. The goToItem: method sets the current item to the specified item. All other methods that return WebHistoryItem objects do not change the value of the current item, they just return the requested item or items. You can also limit the number of history items stored in the back-forward list using the setCapacity: method.

WebBackForwardList objects also control the number of pages cached. You can turn page caching off by setting the page cache size to 0 using the pageCacheSize method, or limit the number of pages cached by passing a value greater than 0.

Tasks

Adding and Removing Items

Moving Backward and Forward

Querying the Back-Forward List

Page Caching

Setting Attributes

Instance Methods

addItem:

Inserts an item into the back-forward list, immediately after the current item.

- (void)addItem:(WebHistoryItem *)item
Parameters
item

A web history item that represents a visited webpage. If item is nil, an NSInvalidArgumentException exception is raised.

Discussion

Any items following item in the back-forward list are removed. This method also removes items if the capacity of the receiver is exceeded.

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

backItem

Returns the item that precedes the current item in the back-forward list.

- (WebHistoryItem *)backItem
Return Value

The item that precedes the current item in the back-forward list, or nil if none precedes it.

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

backListCount

Returns the number of items that precede the current item in the back-forward list.

- (int)backListCount
Return Value

The number of items that precede the current item in the back-forward list.

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

backListWithLimit:

Returns the items that precede the current item in the back-forward list, up to the specified number of items.

- (NSArray *)backListWithLimit:(int)limit
Parameters
limit

The greatest number of items to return.

Return Value

An array containing (at most) the specified number of items, or nil if no items precede the current item.

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

capacity

Returns the maximum number of items that the back-forward list can contain.

- (int)capacity
Return Value

The maximum number of items the back-forward list can contain.

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

containsItem:

Returns a Boolean value indicating whether the back-forward list contains the specified item.

- (BOOL)containsItem:(WebHistoryItem *)item
Parameters
item

The item to find in the back-forward list.

Return Value

YES if the specified item is in the back-forward list; otherwise, NO.

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

currentItem

Returns the current item in the back-forward list.

- (WebHistoryItem *)currentItem
Return Value

The current item, or nil if the back-forward list is empty.

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

forwardItem

Returns the item that follows the current item in the back-forward list.

- (WebHistoryItem *)forwardItem
Return Value

The item that follows the current item, or nil if none follows it.

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

forwardListCount

Returns the number of items that follow the current item in the back-forward list.

- (int)forwardListCount
Return Value

The number of items that follow the current item.

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

forwardListWithLimit:

Returns the items that follow the current item in the back-forward list, up to the specified number of items.

- (NSArray *)forwardListWithLimit:(int)limit
Parameters
limit

The greatest number of items to return.

Return Value

An array containing (at most) the specified number of items, or nil if no items follow the current item.

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

goBack

Moves backward one item in the back-forward list.

- (void)goBack
Discussion

This method works by changing the current item to the item that precedes it. This method raises an NSInternalInconsistencyException exception if no item precedes the current item.

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

goForward

Moves forward one item in the back-forward list.

- (void)goForward
Discussion

This method works by changing the current item to the item that follows it. This method raises an NSInternalInconsistencyException exception if no item follows the current item.

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

goToItem:

Makes the specified item in the back-forward list the current item.

- (void)goToItem:(WebHistoryItem *)item
Parameters
item

A web history item that represents a visited webpage. If item is not in the back-forward list, an NSInvalidArgumentException exception is raised.

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

itemAtIndex:

Returns the item at the specified index in the back-forward list.

- (WebHistoryItem *)itemAtIndex:(int)index
Parameters
index

The index of the item to return. The position of the current item is index 0, and the position of any other item is expressed as an offset from index 0. For example, the item preceding the current item is at index -1, and the item following the current item is at index 1.

Return Value

The item at the specified index, or nil if index exceeds the bounds of the back-forward list (that is, if index is greater than the value returned by forwardListCount, or less than the negative form of the value returned by backListCount).

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

setCapacity:

Sets the maximum number of items that the back-forward list can contain.

- (void)setCapacity:(int)size
Parameters
size

The maximum number of items that the list can contain.

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
WebBackForwardList.h