nsINavHistoryResult

  • Revision slug: nsINavHistoryResult
  • Revision title: nsINavHistoryResult
  • Revision id: 79621
  • Created:
  • Creator: trevorh
  • Is current revision? No
  • Comment Minor cleanup; 149 words added, 20 words removed

Revision Content

{{ IFSummary("toolkit/components/places/nsINavHistoryService.idl", "nsISupports", "Scriptable", "2.0", "Describes the result of a history or bookmark query.", "1.8") }}

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 {{interface("nsINavHistoryResultViewer")} interface provides the View component of the pattern, and {{interface("nsINavHistoryResultViewObserver")} is the Controller.

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

You can use {{ interface("nsINavHistoryResultTreeViewer") }} as the viewer; this provides a prepackaged interaction with a {{ interface("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 {{interface("nsINavHistoryResultViewObserver")} interface.

Method overview

void addObserver(in nsINavHistoryResultObserver aObserver, in boolean aOwnsWeak); {{ gecko_minversion_inline("2.0") }}
void removeObserver(in nsINavHistoryResultObserver aObserver); {{ gecko_minversion_inline("2.0") }}

Attributes

Attribute Type Description
root {{ Interface("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. {{ gecko_minversion_inline("1.9") }}
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. {{ gecko_minversion_inline("2.0") }}
viewer {{ Interface("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_inline("2.0") }}

Methods

{{ method_gecko_minversion("addObserver", "2.0") }}

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 {{ interface("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 {{ manch("removeObserver") }}. If true, the result will keep a weak reference to the observer, which must implement the {{ interface("nsISupportsWeakReference") }} interface.

{{ method_gecko_minversion("removeObserver", "2.0") }}

Removes an observer that was added by a previous call to {{ manch("addObserver") }}.

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

See also

  • {{ Interface("nsINavHistoryResultObserver") }}
  • {{ Interface("nsINavHistoryContainerResultNode") }}

Revision Source

<p>{{ IFSummary("toolkit/components/places/nsINavHistoryService.idl", "nsISupports", "Scriptable", "2.0", "Describes the result of a history or bookmark query.", "1.8") }}</p>
<p>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 {{interface("nsINavHistoryResultViewer")} interface provides the View component of the pattern, and {{interface("nsINavHistoryResultViewObserver")} is the Controller.</p>
<p>The result indicates to the view when something changes by using the {{ interface("nsINavHistoryResultViewer") }} interface. Viewers register themselves through the {{ manch("registerViewer") }} method. The viewer then tells the actual view object what to do.</p>
<p>You can use {{ interface("nsINavHistoryResultTreeViewer") }} as the viewer; this provides a prepackaged interaction with a {{ interface("nsiTreeBoxObject") }}. If you need a different view, you'll need to create your own viewer interface.</p>
<p>The viewer provides notifications to the controller when view events occur; this is done using the {{interface("nsINavHistoryResultViewObserver")} interface.</p>
<h2 id="Method_overview" name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>void <a href="#addObserver()">addObserver</a>(in nsINavHistoryResultObserver aObserver, in boolean aOwnsWeak);</code> {{ gecko_minversion_inline("2.0") }}</td> </tr> <tr> <td><code>void <a href="#removeObserver()">removeObserver</a>(in nsINavHistoryResultObserver aObserver);</code> {{ gecko_minversion_inline("2.0") }}</td> </tr> </tbody>
</table>
<h2 id="Attributes" name="Attributes">Attributes</h2>
<table class="standard-table"> <tbody> <tr> <td class="header">Attribute</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>root</code></td> <td>{{ Interface("nsINavHistoryContainerResultNode") }}</td> <td>The root of the results. This container gives you access to all the results in the tree. <div class="note"><strong>Note:</strong> Keep in mind that you need to open containers for their results to be valid.</div> 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 <code>root</code> node the result will stop observing changes, so it is good practice to close the <code>root</code> node when you are done with a result, since that will avoid unwanted performance hits. <strong>Read only.</strong></td> </tr> <tr> <td><code>sortingAnnotation</code></td> <td><code><a href="/en/AUTF8String" title="en/AUTF8String">AUTF8String</a></code></td> <td>The annotation to use in <code>SORT_BY_ANNOTATION_*</code> sorting modes; you must set this value before setting the <code>sortingMode</code> attribute. {{ gecko_minversion_inline("1.9") }}</td> </tr> <tr> <td><code>sortingMode</code></td> <td><code><a href="/en/unsigned_short" title="en/unsigned short">unsigned short</a></code></td> <td>Specifies the sorting mode for the result. This value must be one of <code>nsINavHistoryQueryOptions.SORT_BY_*</code>. 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.</td> </tr> <tr> <td><code>suppressNotifications</code></td> <td><code><a href="/en/boolean" title="en/boolean">boolean</a></code></td> <td>If <code>true</code>, notifications are suppressed. This is used to prevent rapid flickering of changes when performing batch or temporary operations on the result structure. {{ gecko_minversion_inline("2.0") }}</td> </tr> <tr> <td><code>viewer</code></td> <td>{{ Interface("nsINavHistoryResultViewer") }}</td> <td>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_inline("2.0") }}</td> </tr> </tbody>
</table>
<h2 id="Methods" name="Methods">Methods</h2>
<p>{{ method_gecko_minversion("addObserver", "2.0") }}</p>
<p>Adds an observer for changes that occur on the result.</p>
<pre class="eval">void addObserver(
  in nsINavHistoryResultObserver aObserver,
  in boolean aOwnsWeak
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl> <dt><code>aObserver</code></dt> <dd>An object that implements the {{ interface("nsINavHistoryResultObserver") }} interface, which will receive notifications of changes on the result.</dd> <dt><code>aOwnsWeak</code></dt> <dd>If <code>false</code>, the result will keep an owning reference to the observer, which must be removed by calling {{ manch("removeObserver") }}. If <code>true</code>, the result will keep a weak reference to the observer, which must implement the {{ interface("nsISupportsWeakReference") }} interface.</dd>
</dl>
<p>{{ method_gecko_minversion("removeObserver", "2.0") }}</p>
<p>Removes an observer that was added by a previous call to {{ manch("addObserver") }}.</p>
<pre class="eval">void removeObserver(
  in nsINavHistoryResultObserver aObserver
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl> <dt><code>aObserver</code></dt> <dd>The observer to remove.</dd>
</dl>
<h2 id="See_also" name="See_also">See also</h2>
<ul> <li>{{ Interface("nsINavHistoryResultObserver") }}</li> <li>{{ Interface("nsINavHistoryContainerResultNode") }}</li>
</ul>
Revert to this revision