toolkit/components/places/nsINavHistoryService.idlScriptable
Describes the result of a history or bookmark query.
1.0
66
Introduced
Gecko 1.8
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Places results use a Model-View-Controller (MVC) design pattern. Result objects represent the model in which the data is stored. External components provide the view and controller pieces of the puzzle; they define how the data looks and how the data is interacted with. More specifically, the nsINavHistoryResultViewer interface provides the View component of the pattern, and nsINavHistoryResultViewObserver is the Controller.

The result indicates to the view when something changes by using the nsINavHistoryResultViewer interface. Viewers register themselves through the registerViewer() method. The viewer then tells the actual view object what to do.

You can use nsINavHistoryResultTreeViewer as the viewer; this provides a prepackaged interaction with a nsiTreeBoxObject. If you need a different view, you'll need to create your own viewer interface.

The viewer provides notifications to the controller when view events occur; this is done using the nsINavHistoryResultViewObserver interface.

Method overview

void addObserver(in nsINavHistoryResultObserver aObserver, in boolean aOwnsWeak);
void removeObserver(in nsINavHistoryResultObserver aObserver);

Attributes

Attribute Type Description
root nsINavHistoryContainerResultNode The root of the results. This container gives you access to all the results in the tree.
Note: Keep in mind that you need to open containers for their results to be valid.
When a result goes out of scope it will continue to observe changes till it is cycle collected. While the result waits to be collected it will stay in memory, and continue to update itself, potentially causing unwanted additional work. When you close the root node the result will stop observing changes, so it is good practice to close the root node when you are done with a result, since that will avoid unwanted performance hits. Read only.
sortingAnnotation AUTF8String The annotation to use in SORT_BY_ANNOTATION_* sorting modes; you must set this value before setting the sortingMode attribute.
sortingMode unsigned short Specifies the sorting mode for the result. This value must be one of nsINavHistoryQueryOptions.SORT_BY_*. Changing this value updates the corresponding options for the result so that reusing the current options and queries will always return results based on the current view.
suppressNotifications boolean If true, notifications are suppressed. This is used to prevent rapid flickering of changes when performing batch or temporary operations on the result structure.
viewer nsINavHistoryResultViewer The viewer for this result. The viewer is responsible for actually updating the view object itself, as well as for handling events on the view. Obsolete since Gecko 2.0

Methods

addObserver()

Adds an observer for changes that occur on the result.

void addObserver(
  in nsINavHistoryResultObserver aObserver,
  in boolean aOwnsWeak
);
Parameters
aObserver
An object that implements the nsINavHistoryResultObserver interface, which will receive notifications of changes on the result.
aOwnsWeak
If false, the result will keep an owning reference to the observer, which must be removed by calling removeObserver(). If true, the result will keep a weak reference to the observer, which must implement the nsISupportsWeakReference interface.

removeObserver()

Removes an observer that was added by a previous call to addObserver().

void removeObserver(
  in nsINavHistoryResultObserver aObserver
);
Parameters
aObserver
The observer to remove.

See also