---

WebBackForwardList Class Reference

Overview

A WebBackForwardList object maintains a list of visited pages used to go back and forward to the most recent page. WebBackForwardList just maintains the back-forward list data—it does not perform actual page loads (it does not make any client requests). Use the WebFrame loadRequest: method to change a location.

Items are typically inserted in a back-forward list in the order they are visited. A WebBackForwardList also maintains the notion of a current item that is always at index 0, the proceeding item is at index –1, and the following item is at index 1. The goBack and goForward methods move the current item backward or forward by 1 index. The goToItem: method sets the current item to the specified item. All other get 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

• – addItem:

Moving Backward and Forward

• – goBack
• – goForward
• – goToItem:

Querying the Back-forward List

• – backItem
• – backListCount
• – backListWithLimit:
• – containsItem:
• – currentItem
• – itemAtIndex:
• – forwardItem
• – forwardListCount
• – forwardListWithLimit:

Page Caching

• – pageCacheSize Deprecated in Mac OS X v10.4.11
• – setPageCacheSize: Deprecated in Mac OS X v10.4.11

Setting Attributes

• – capacity
• – setCapacity:

Instance Methods

addItem:

Inserts an item immediately after the current item.

- (void)addItem:(WebHistoryItem *)item

Discussion

Any items following item in the back-forward list are removed. This method also removes items if the receiver’s capacity is exceeded. If item is nil, this method raises an NSInvalidArgumentException exception.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebBackForwardList.h

backItem

Returns the item that precedes the current item, or nil if none precedes it.

- (WebHistoryItem *)backItem

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – currentItem
• – forwardItem

Declared In

WebBackForwardList.h

backListCount

Returns the number of items that precede the current item.

- (int)backListCount

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – forwardListCount

Declared In

WebBackForwardList.h

backListWithLimit:

Returns a limited-size array of items that precede the current item.

- (NSArray *)backListWithLimit:(int)limit

Discussion

This method will return a new array containing (at most) the number of elements specified by [limit]. Returns nil if no items precede the current item.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – forwardListWithLimit:

Declared In

WebBackForwardList.h

capacity

Returns the maximum number of items the receiver can contain.

- (int)capacity

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – setCapacity:

Declared In

WebBackForwardList.h

containsItem:

Returns YES if the receiver contains the specified item, NO otherwise.

- (BOOL)containsItem:(WebHistoryItem *)item

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebBackForwardList.h

currentItem

Returns the current item, or nil if the receiver is empty.

- (WebHistoryItem *)currentItem

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – backItem
• – forwardItem

Declared In

WebBackForwardList.h

forwardItem

Returns the item that succeeds the current item, or nil if none succeeds it.

- (WebHistoryItem *)forwardItem

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – backItem
• – currentItem

Declared In

WebBackForwardList.h

forwardListCount

Returns the number of items that succeed the current item.

- (int)forwardListCount

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – backListCount

Declared In

WebBackForwardList.h

forwardListWithLimit:

Returns a limited-size array containing items that succeeds the current item.

- (NSArray *)forwardListWithLimit:(int)limit

Discussion

This method returns a new array containing (at most) the number of elements specified by [limit]. Returns nil if no items succeed the current item.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – backListWithLimit:

Declared In

WebBackForwardList.h

goBack

Steps backward in the back-forward list.

- (void)goBack

Discussion

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

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – goForward
• – goToItem:

Declared In

WebBackForwardList.h

goForward

Steps forward in the back-forward list.

- (void)goForward

Discussion

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

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – goBack
• – goToItem:

Declared In

WebBackForwardList.h

goToItem:

Moves to itema given item in the back-forward list by making it the current item.

- (void)goToItem:(WebHistoryItem *)item

Discussion

Raises an NSInvalidArgumentException exception, if item is not in the back-forward list.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

See Also

• – goBack
• – goForward

Declared In

WebBackForwardList.h

itemAtIndex:

Returns the item at a given index relative to the current item.

- (WebHistoryItem *)itemAtIndex:(int)index

Discussion

This method returns the item located at an index expressed as an offset relative to the current item's position in the list. For example, the current item is at index 0, the preceding item is at index -1, and the succeeding item is at index 1. If index exceeds the bounds of the receiver (that is, if index is greater than the value returned by forwardListCount , or less than the negative form of the value returned by backListCount ), then this method returns nil.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebBackForwardList.h

setCapacity:

Sets the maximum number of items the receiver can contain.

- (void)setCapacity:(int)size

Discussion

Use the capacity method to get the current setting.

Availability

• Available in Mac OS X v10.2 with Safari 1.0 and later.
• Available in Mac OS X v10.2.7 and later.

Declared In

WebBackForwardList.h

---