mozilla

Revision 96301 of Displaying Places information using views

  • Revision slug: Displaying_Places_information_using_views
  • Revision title: Displaying Places information using views
  • Revision id: 96301
  • Created:
  • Creator: BrettWilson
  • Is current revision? No
  • Comment /* Registering a view */

Revision Content

Views are how you display nsINavHistoryResult objects to the user.

Introduction

Views implement the interface nsINavHistoryResultViewer defined in {{wiki.template('Named-source', [ "browser/components/places/public/nsINavHistoryService.idl", "nsINavHistoryService.idl" ])}}.


Registering a view

Register the view by setting the viewer attribute on nsINavHistoryResult. When you do this, the result will in turn set the result attribute on the given view. You should not set the result attribute on the view explicitly.

Be careful about reference cycles. The view and the result both hold owning references to each other. For these objects to be deleted, you must clear this cycle, by setting result.viewer to null. The built-in tree view (see below) does this automatically. When the tree is destroyed or a different nsITreeView is associated with the tree, the tree will call nsITreeView.tree = null; The viewer detects this case and also detaches itself from the result.

The built-in tree view

The most common type of view is in a tree control, but it is also relatively difficult to implement. Therefore, Places provides a built-in view object for when you want to display a result in a tree view. It is implemented in {{template.Source("browser/components/places/src/nsNavHistoryResult.cpp")}}.

This object's contract ID is "@mozilla.org/browser/nav-history/result-tree-viewer;1". This object implements both nsINavHistoryResultViewer and {{wiki.template('Named-source', [ "/layout/xul/base/src/tree/public/nsITreeView.idl", "nsITreeView" ])}}. You can therefore use this object to bridge between a result (see Places:Query System) and a tree:

var result = historyService.executeQuery(...);
var tree = document.getElementById("mytree"); // your tree control

var treeviewer = Components.classes["@mozilla.org/browser/nav-history/result-tree-viewer;1"].
                           .createInstance(Ci.nsINavHistoryResultViewer);

result.viewer = treeviewer;
tree.view = treeviewer.QueryInterface(Components.interfaces.nsITreeView);

Implemeting a view

If you require a customized tree view, it may be easiest to wrap the nsINavHistoryResultTreeViewer in your own class. For example, if you wanted a "special" first row, your object would provide nsITreeView responses for the first row, and pass all other messages through to the built-in tree view with indices shifted by one.

The attribute nsINavHistoryResultNode.viewIndex is provided explicitly for the use of the view. These values are initialized to -1 when each node is created. You can use this value to keep track of visible nodes. The built-in tree viewer uses this attribute to store the row index that the node is on.

Revision Source

<p>
</p><p>Views are how you display nsINavHistoryResult objects to the user.
</p>
<h3 name="Introduction"> Introduction </h3>
<p>Views implement the interface nsINavHistoryResultViewer defined in {{wiki.template('Named-source', [ "browser/components/places/public/nsINavHistoryService.idl", "nsINavHistoryService.idl" ])}}.
</p><p><br>
</p>
<h3 name="Registering_a_view"> Registering a view </h3>
<p>Register the view by setting the <b>viewer</b> attribute on nsINavHistoryResult. When you do this, the result will in turn set the <b>result</b> attribute on the given view. <i>You should not set the result attribute on the view explicitly.</i>
</p><p>Be careful about reference cycles. The view and the result both hold owning references to each other. For these objects to be deleted, you must clear this cycle, by setting result.viewer to null. The built-in tree view (see below) does this automatically. When the tree is destroyed or a different nsITreeView is associated with the tree, the tree will call <code>nsITreeView.tree = null;</code> The viewer detects this case and also detaches itself from the result.
</p>
<h5 name="The_built-in_tree_view"> The built-in tree view </h5>
<p>The most common type of view is in a tree control, but it is also relatively difficult to implement. Therefore, Places provides a built-in view object for when you want to display a result in a tree view. It is implemented in {{template.Source("browser/components/places/src/nsNavHistoryResult.cpp")}}.
</p><p>This object's contract ID is <code>"@mozilla.org/browser/nav-history/result-tree-viewer;1"</code>. This object implements both nsINavHistoryResultViewer and {{wiki.template('Named-source', [ "/layout/xul/base/src/tree/public/nsITreeView.idl", "nsITreeView" ])}}. You can therefore use this object to bridge between a result (see <a href="en/Places/Query_System">Places:Query System</a>) and a tree:
</p>
<pre>var result = historyService.executeQuery(...);
var tree = document.getElementById("mytree"); // your tree control

var treeviewer = Components.classes["@mozilla.org/browser/nav-history/result-tree-viewer;1"].
                           .createInstance(Ci.nsINavHistoryResultViewer);

result.viewer = treeviewer;
tree.view = treeviewer.QueryInterface(Components.interfaces.nsITreeView);
</pre>
<h3 name="Implemeting_a_view"> Implemeting a view </h3>
<p>If you require a customized tree view, it may be easiest to wrap the nsINavHistoryResultTreeViewer in your own class. For example, if you wanted a "special" first row, your object would provide nsITreeView responses for the first row, and pass all other messages through to the built-in tree view with indices shifted by one.
</p><p>The attribute <b>nsINavHistoryResultNode.viewIndex</b> is provided explicitly for the use of the view. These values are initialized to -1 when each node is created. You can use this value to keep track of visible nodes. The built-in tree viewer uses this attribute to store the row index that the node is on.
</p>
Revert to this revision