Revision 96072 of Displaying Places information using views

  • リビジョンの URL スラグ: Displaying_Places_information_using_views
  • リビジョンのタイトル: Displaying Places information using views
  • リビジョンの ID: 96072
  • 作成日:
  • 作成者: Kohei
  • 現行リビジョン いいえ
  • コメント

このリビジョンの内容

{{ Firefox3() }}

ビューは、{{ Interface("nsINavHistoryResult") }} オブジェクトをユーザに表示する方法です。ビューは {{ Interface("nsINavHistoryResultViewer") }} インタフェースを実装しています。

組み込みのビュー

拡張機能やアプリケーションの中でブックマークや履歴の内容を表示したい場合、組み込みの Places ビューを使うことができます。これは、汎用的なもので、基本的な機能を実装する時間を大幅に節約できるため、開発者は拡張機能やアプリケーションの開発作業に集中できます。

利用可能なビュー

Places では以下の組み込みビューが利用可能です。

  • ツリー
  • メニュー
  • ツールバー - 上位フォルダにはメニュービューを使用

XML におけるインスタンス化

<!-- XBL バインディングを得るため、Places のスタイルシートをインクルードします -->
<?xml-stylesheet href="chrome://browser/content/places/places.css"?>

<!-- また、以下のスタイルシートをインクルードすることで、ツリーに
     既定のスタイル (アイコンなど) を適用することができます -->
<?xml-stylesheet href="chrome://browser/skin/places/places.css"?>

<!-- Places オーバーレイを読み込んで、必要な JavaScript ファイルや
     既定のコマンド、コンテキストメニューをインクルードします -->
<?xul-overlay href="chrome://browser/content/places/placesOverlay.xul"?>

<!-- ツリービュー -->
<tree id="myTree"
      type="places"
      place="place:...">
  <treecols>
    <treecol id="name" flex="1" primary="true"/>
  </treecols>
  <treechildren flex="1"/>
</tree>

<!-- メニュービュー -->
<menu id="myMenu" label="My Menu">
  <menupopup type="places" place="place:..."/>
</menu>

<!-- ツールバービュー -->
<toolbaritem id="myToolbaritem"
             type="places"
             place="place:..."/>

スクリプトの仕掛け

var view = document.getElementById("your_view");
view.init(null);
view.appendController(PlacesController);

null を使ってビューを初期化します (これにより既定のビューの設定が使用されます - オプションについては Places:View Configurations を参照してください。ここには ViewConfig オブジェクトを使ってビューの機能に変更を加える詳しい方法が載っています)。それから、コントローラを加えます。これでビューは使用可能になりました。

PlacesView インタフェース

PlacesView インタフェースを通じてビューと情報のやりとりを行う方法は The PlacesView interface を参照してください。

独自ビューの作成

より高い柔軟性を求める場合や、Places 情報の表示に独自形式を使用したい場合は、独自にビューを作成することで実現できます。

ビューの登録

ビューを登録するには、nsINavHistoryResultviewer 属性を設定します。これにより、指定されたビューに対して結果が順次 result 属性を設定していきます。ビュー上に明示的に result 属性を設定してはいけません。 ビューをクリアするには、viewer 属性を null に設定します。これにより、ビューの result 属性も null に設定されます。

ここで参照サイクルに気を付ける必要があります。ビューと結果はそれぞれ互いに所有参照を保持しています。これらのオブジェクトを削除するには、result.viewernull を設定して、このサイクルをクリアする必要があります。組み込みのツリービュー (下記参照) ではこの処理が自動的に行われます。ツリーが破棄されるか、異なる nsITreeView がツリーに関連付けられると、ツリーは nsITreeView.tree = null を呼び出します。ビューアはこの状況を判別するとともに、それ自体を結果から切り離します。

組み込みのツリービュー

もっとも一般的なビューの種類はツリーコントロールですが、一方でこれは比較的実装が難しいものです。そのため Places では、開発者が結果をツリービューに表示したい場合に利用できる、組み込みのビューオブジェクトが提供されています。これは {{ Source("browser/components/places/content/treeView.js") }} で実装されています。

このオブジェクトは nsINavHistoryResultViewer と {{ Source("/layout/xul/base/src/tree/public/nsITreeView.idl", "nsITreeView") }} を実装しています。このため、このオブジェクトを利用することで、結果 (Querying Places 参照) とツリーの間の橋渡しをすることができます。

var result = historyService.executeQuery(...); // Places のクエリの結果
var tree = document.getElementById("mytree"); // ツリーコントロール

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

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

組み込みのツリービューは、オブザーバがその実装である nsINavHistoryResultViewObserver ({{ Source("toolkit/components/places/public/nsINavHistoryService.idl", "nsINavHistoryService.idl") }} で宣言されています) を追加できるようにしています。このオブザーバインタフェースを利用すると、外部のコンポーネントからどのような処理が行われているかを確認し、適切な処理が行うことができます。Places のツリーでは、コントローラを追加することで、例えば、何かがツリー上にドラッグ&ドロップされたときに通知を行っています。その際に適切な処理が実行されます。

ビューの実装

カスタマイズしたツリービューが必要な場合は、自作クラス内で nsINavHistoryResultTreeViewer をラップするのが最も簡単な方法です。例えば、「特別な」列を最初に加えたい場合は、自作オブジェクトでその最初の行のための nsITreeView レスポンスを実装し、他のすべてのメッセージを、インデックスをひとつずらして、組み込みのツリービューに渡します。

nsINavHistoryResultNode.viewIndex 属性は、ビューを利用するために明示的に提供されています。これらの値は、各ノードが作成される際 -1 に初期化されます。この値を使うと、表示されているノードを把握することができます。組み込みのツリービューアでは、ノードが含まれる列のインデックスを保持するためにこの属性が使われています。

nsINavHistoryResultViewer には、nsINavHistoryResultViewObserver が変更を監視できるようにするオブザーバインタフェースも含まれています。ただし、このオブザーバインタフェースはツリー専用です。これを nsINavHistoryResultTreeViewer オブジェクトに移す作業が {{ Bug("337638") }} で行われました。nsINavHistoryResultViewer が独自のオブザーバを使う必要があるなら、追加の実装が必要となります。

関連記事

{{ languages( { "en": "en/Displaying_Places_information_using_views" } ) }}

このリビジョンのソースコード

<p>
{{ Firefox3() }}
</p><p>ビューは、{{ Interface("nsINavHistoryResult") }} オブジェクトをユーザに表示する方法です。ビューは {{ Interface("nsINavHistoryResultViewer") }} インタフェースを実装しています。
</p>
<h2 name=".E7.B5.84.E3.81.BF.E8.BE.BC.E3.81.BF.E3.81.AE.E3.83.93.E3.83.A5.E3.83.BC"> 組み込みのビュー </h2>
<p>拡張機能やアプリケーションの中でブックマークや履歴の内容を表示したい場合、組み込みの Places ビューを使うことができます。これは、汎用的なもので、基本的な機能を実装する時間を大幅に節約できるため、開発者は拡張機能やアプリケーションの開発作業に集中できます。
</p>
<h3 name=".E5.88.A9.E7.94.A8.E5.8F.AF.E8.83.BD.E3.81.AA.E3.83.93.E3.83.A5.E3.83.BC"> 利用可能なビュー </h3>
<p>Places では以下の組み込みビューが利用可能です。
</p>
<ul><li> ツリー
</li><li> メニュー
</li><li> ツールバー - 上位フォルダにはメニュービューを使用
</li></ul>
<h3 name="XML_.E3.81.AB.E3.81.8A.E3.81.91.E3.82.8B.E3.82.A4.E3.83.B3.E3.82.B9.E3.82.BF.E3.83.B3.E3.82.B9.E5.8C.96"> XML におけるインスタンス化 </h3>
<pre>&lt;!-- XBL バインディングを得るため、Places のスタイルシートをインクルードします --&gt;
&lt;?xml-stylesheet href="chrome://browser/content/places/places.css"?&gt;

&lt;!-- また、以下のスタイルシートをインクルードすることで、ツリーに
     既定のスタイル (アイコンなど) を適用することができます --&gt;
&lt;?xml-stylesheet href="chrome://browser/skin/places/places.css"?&gt;

&lt;!-- Places オーバーレイを読み込んで、必要な JavaScript ファイルや
     既定のコマンド、コンテキストメニューをインクルードします --&gt;
&lt;?xul-overlay href="chrome://browser/content/places/placesOverlay.xul"?&gt;

&lt;!-- ツリービュー --&gt;
&lt;tree id="myTree"
      type="places"
      place="place:..."&gt;
  &lt;treecols&gt;
    &lt;treecol id="name" flex="1" primary="true"/&gt;
  &lt;/treecols&gt;
  &lt;treechildren flex="1"/&gt;
&lt;/tree&gt;

&lt;!-- メニュービュー --&gt;
&lt;menu id="myMenu" label="My Menu"&gt;
  &lt;menupopup type="places" place="place:..."/&gt;
&lt;/menu&gt;

&lt;!-- ツールバービュー --&gt;
&lt;toolbaritem id="myToolbaritem"
             type="places"
             place="place:..."/&gt;
</pre>
<h3 name=".E3.82.B9.E3.82.AF.E3.83.AA.E3.83.97.E3.83.88.E3.81.AE.E4.BB.95.E6.8E.9B.E3.81.91"> スクリプトの仕掛け </h3>
<pre>var view = document.getElementById("your_view");
view.init(null);
view.appendController(PlacesController);
</pre>
<p><code>null</code> を使ってビューを初期化します (これにより既定のビューの設定が使用されます - オプションについては <a href="ja/Places/View_Configurations">Places:View Configurations</a> を参照してください。ここには ViewConfig オブジェクトを使ってビューの機能に変更を加える詳しい方法が載っています)。それから、コントローラを加えます。これでビューは使用可能になりました。
</p>
<h3 name="PlacesView_.E3.82.A4.E3.83.B3.E3.82.BF.E3.83.95.E3.82.A7.E3.83.BC.E3.82.B9"> PlacesView インタフェース </h3>
<p>PlacesView インタフェースを通じてビューと情報のやりとりを行う方法は <a href="ja/The_PlacesView_interface">The PlacesView interface</a> を参照してください。
</p>
<h2 name=".E7.8B.AC.E8.87.AA.E3.83.93.E3.83.A5.E3.83.BC.E3.81.AE.E4.BD.9C.E6.88.90"> 独自ビューの作成 </h2>
<p>より高い柔軟性を求める場合や、Places 情報の表示に独自形式を使用したい場合は、独自にビューを作成することで実現できます。
</p>
<h3 name=".E3.83.93.E3.83.A5.E3.83.BC.E3.81.AE.E7.99.BB.E9.8C.B2"> ビューの登録 </h3>
<p>ビューを登録するには、<code>nsINavHistoryResult</code> に <code>viewer</code> 属性を設定します。これにより、指定されたビューに対して結果が順次 <code>result</code> 属性を設定していきます。<i>ビュー上に明示的に <code>result</code> 属性を設定してはいけません。</i> ビューをクリアするには、<code>viewer</code> 属性を <code>null</code> に設定します。これにより、ビューの <code>result</code> 属性も <code>null</code> に設定されます。
</p><p>ここで参照サイクルに気を付ける必要があります。ビューと結果はそれぞれ互いに所有参照を保持しています。これらのオブジェクトを削除するには、<code>result.viewer</code> に <code>null</code> を設定して、このサイクルをクリアする必要があります。組み込みのツリービュー (下記参照) ではこの処理が自動的に行われます。ツリーが破棄されるか、異なる <code>nsITreeView</code> がツリーに関連付けられると、ツリーは <code>nsITreeView.tree = null</code> を呼び出します。ビューアはこの状況を判別するとともに、それ自体を結果から切り離します。
</p>
<h5 name=".E7.B5.84.E3.81.BF.E8.BE.BC.E3.81.BF.E3.81.AE.E3.83.84.E3.83.AA.E3.83.BC.E3.83.93.E3.83.A5.E3.83.BC"> 組み込みのツリービュー </h5>
<p>もっとも一般的なビューの種類はツリーコントロールですが、一方でこれは比較的実装が難しいものです。そのため Places では、開発者が結果をツリービューに表示したい場合に利用できる、組み込みのビューオブジェクトが提供されています。これは {{ Source("browser/components/places/content/treeView.js") }} で実装されています。
</p><p>このオブジェクトは <code>nsINavHistoryResultViewer</code> と {{ Source("/layout/xul/base/src/tree/public/nsITreeView.idl", "nsITreeView") }} を実装しています。このため、このオブジェクトを利用することで、結果 (<a href="ja/Querying_Places">Querying Places</a> 参照) とツリーの間の橋渡しをすることができます。
</p>
<pre>var result = historyService.executeQuery(...); // Places のクエリの結果
var tree = document.getElementById("mytree"); // ツリーコントロール

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

result.viewer = treeviewer;
tree.view = treeviewer.QueryInterface(Components.interfaces.nsITreeView);
</pre>
<p>組み込みのツリービューは、オブザーバがその実装である <code>nsINavHistoryResultViewObserver</code> ({{ Source("toolkit/components/places/public/nsINavHistoryService.idl", "nsINavHistoryService.idl") }} で宣言されています) を追加できるようにしています。このオブザーバインタフェースを利用すると、外部のコンポーネントからどのような処理が行われているかを確認し、適切な処理が行うことができます。Places のツリーでは、コントローラを追加することで、例えば、何かがツリー上にドラッグ&ドロップされたときに通知を行っています。その際に適切な処理が実行されます。
</p>
<h3 name=".E3.83.93.E3.83.A5.E3.83.BC.E3.81.AE.E5.AE.9F.E8.A3.85"> ビューの実装 </h3>
<p>カスタマイズしたツリービューが必要な場合は、自作クラス内で <code>nsINavHistoryResultTreeViewer</code> をラップするのが最も簡単な方法です。例えば、「特別な」列を最初に加えたい場合は、自作オブジェクトでその最初の行のための <code>nsITreeView</code> レスポンスを実装し、他のすべてのメッセージを、インデックスをひとつずらして、組み込みのツリービューに渡します。
</p><p><code>nsINavHistoryResultNode.viewIndex</code> 属性は、ビューを利用するために明示的に提供されています。これらの値は、各ノードが作成される際 <code>-1</code> に初期化されます。この値を使うと、表示されているノードを把握することができます。組み込みのツリービューアでは、ノードが含まれる列のインデックスを保持するためにこの属性が使われています。
</p><p><code>nsINavHistoryResultViewer</code> には、<code>nsINavHistoryResultViewObserver</code> が変更を監視できるようにするオブザーバインタフェースも含まれています。ただし、このオブザーバインタフェースはツリー専用です。これを <code>nsINavHistoryResultTreeViewer</code> オブジェクトに移す作業が {{ Bug("337638") }} で行われました。<code>nsINavHistoryResultViewer</code> が独自のオブザーバを使う必要があるなら、追加の実装が必要となります。
</p>
<h3 name=".E9.96.A2.E9.80.A3.E8.A8.98.E4.BA.8B"> 関連記事 </h3>
<ul><li> <a href="ja/The_PlacesView_interface">The PlacesView interface</a>
</li></ul>
{{ languages( { "en": "en/Displaying_Places_information_using_views" } ) }}
このリビジョンへ戻す