Displaying Places information using views

  • Revision slug: Displaying_Places_information_using_views
  • Revision title: Displaying Places information using views
  • Revision id: 96315
  • Created:
  • Creator: Kohei
  • Is current revision? No
  • Comment /* In other languages */

Revision Content

{{template.Firefox3()}}

Views are how you display nsINavHistoryResult objects to the user. Views implement the interface nsINavHistoryResultViewer defined in {{template.Source("toolkit/components/places/public/nsINavHistoryService.idl", "nsINavHistoryService.idl")}}.

For many applications, it will be sufficient to use one of the Places controls with built-in views and the complexity of using your own view can be avoided. See Instantiating Views for more on this topic.

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. To clear the view, set the viewer attribute to null. This will cause the view's result attribute to be set to null as well.

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/content/treeView.js")}}.

This object implements both nsINavHistoryResultViewer and {{template.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(...); // your Places query result
var tree = document.getElementById("mytree"); // your tree control

var showRootNodeInTree = true;
var treeviewer = new PlacesTreeView(showRootNodeInTree);

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

The built-in tree view also allows observers to attach that implement nsINavHistoryResultViewObserver (declared in {{template.Source("toolkit/components/places/public/nsINavHistoryService.idl", "nsINavHistoryService.idl")}}). This observer interface allows external components to see what is happening and to take appropriate action. For the Places trees, the controller attaches and, for example, notices when something has been drag-and-dropped on the tree. It then takes the appropriate action.

Implementing 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.

The nsINavHistoryResultViewer also has an observer interface to allow an nsINavHistoryResultViewObserver to observer changes. However, this observer interface is specifically for trees. The {{template.Bug(337638)}} is for moving this to the nsINavHistoryResultTreeViewer object. Other implementors if nsINavHistoryResultViewer should use their own observers.

{{ wiki.languages( { "ja": "ja/Places/Views" } ) }}

Revision Source

<p>
{{template.Firefox3()}}
</p><p>Views are how you display <code>nsINavHistoryResult</code> objects to the user. Views implement the interface <code>nsINavHistoryResultViewer</code> defined in {{template.Source("toolkit/components/places/public/nsINavHistoryService.idl", "nsINavHistoryService.idl")}}.
</p><p>For many applications, it will be sufficient to use one of the Places controls with built-in views and the complexity of using your own view can be avoided. See <a href="en/Places/Instantiating_Views">Instantiating Views</a> for more on this topic.
</p>
<h3 name="Registering_a_view"> Registering a view </h3>
<p>Register the view by setting the <code>viewer</code> attribute on <code>nsINavHistoryResult</code>. When you do this, the result will in turn set the <code>result</code> attribute on the given view. <i>You should not set the <code>result</code> attribute on the view explicitly.</i> To clear the view, set the <code>viewer</code> attribute to <code>null</code>. This will cause the view's <code>result</code> attribute to be set to <code>null</code> as well.
</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 <code>result.viewer</code> to <code>null</code>. The built-in tree view (see below) does this automatically. When the tree is destroyed or a different <code>nsITreeView</code> 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/content/treeView.js")}}.
</p><p>This object implements both <code>nsINavHistoryResultViewer</code> and {{template.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(...); // your Places query result
var tree = document.getElementById("mytree"); // your tree control

var showRootNodeInTree = true;
var treeviewer = new PlacesTreeView(showRootNodeInTree);

result.viewer = treeviewer;
tree.view = treeviewer.QueryInterface(Components.interfaces.nsITreeView);
</pre>
<p>The built-in tree view also allows observers to attach that implement <code>nsINavHistoryResultViewObserver</code> (declared in {{template.Source("toolkit/components/places/public/nsINavHistoryService.idl", "nsINavHistoryService.idl")}}). This observer interface allows external components to see what is happening and to take appropriate action. For the Places trees, the controller attaches and, for example, notices when something has been drag-and-dropped on the tree. It then takes the appropriate action.
</p>
<h3 name="Implementing_a_view"> Implementing a view </h3>
<p>If you require a customized tree view, it may be easiest to wrap the <code>nsINavHistoryResultTreeViewer</code> in your own class. For example, if you wanted a "special" first row, your object would provide <code>nsITreeView</code> 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 <code>nsINavHistoryResultNode.viewIndex</code> is provided explicitly for the use of the view. These values are initialized to <code>-1</code> 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><p>The <code>nsINavHistoryResultViewer</code> also has an observer interface to allow an <code>nsINavHistoryResultViewObserver</code> to observer changes. However, this observer interface is specifically for trees. The {{template.Bug(337638)}} is for moving this to the <code>nsINavHistoryResultTreeViewer</code> object. Other implementors if <code>nsINavHistoryResultViewer</code> should use their own observers.
</p>{{ wiki.languages( { "ja": "ja/Places/Views" } ) }}
Revert to this revision