目次
1 序章
1.1 概要
1.2 主要な埋め込みオブジェクト
1.2.1 Docshell オブジェクト 1.2.2 WebBrowser オブジェクト
1.2.3 Webbrowser site オブジェクト
2 主要なインタフェース
2.1 インタフェース：nsIBaseWindow
2.1.1 実装オブジェクト
2.1.2 ソースコード
2.2 インタフェース：nsIContentViewerContainer
2.2.1 注意
2.2.2 実装オブジェクト
2.2.3 ソースコード
2.3 インタフェース：nsIDocShell
2.3.1 実装オブジェクト
2.3.2 ソースコード
2.4 インタフェース：nsIDocShellTreeItem
2.4.1 実装オブジェクト
2.4.2 ソースコード
2.5 インタフェース：nsIDocShellTreeNode
2.5.1 実装オブジェクト
2.5.2 ソースコード
2.6 インタフェース：nsIDocShellTreeOwner
2.6.1 実装オブジェクト
2.6.2 ソースコード
2.7 インタフェース：nsIInterfaceRequestor
2.7.1 実装オブジェクト
2.7.2 ソースコード
2.8 インタフェース：nsIPrompt
2.8.1 実装オブジェクト
2.8.2 ソースコード
2.9 インタフェース：nsIRefreshURI
2.9.1 実装オブジェクト
2.9.2 ソースコード
2.10 インタフェース：nsIScriptGlobalObjectOwner
2.10.1 実装オブジェクト
2.10.2 ソースコード
2.11 インタフェース：nsIScrollable
2.11.1 実装オブジェクト
2.11.2 ソースコード
2.12 インタフェース：nsIStreamObserver
2.12.1 実装オブジェクト
2.12.2 ソースコード
2.13 インタフェース：nsITextScroll
2.13.1 実装オブジェクト
2.13.2 ソースコード
2.14 インタフェース：nsIWebBrowser
2.14.1 実装オブジェクト
2.14.2 ソースコード
2.15 インタフェース：nsIWebBrowserChrome
2.15.1 実装オブジェクト
2.15.2 ソースコード
2.16 インタフェース：nsIWebNavigation
2.16.1 実装オブジェクト
2.16.2 ソースコード
2.17 インタフェース：nsIWebProgress
2.17.1 実装オブジェクト
2.17.2 ソースコード
2.18 インタフェース：nsIWebProgressListener
2.18.1 実装オブジェクト
2.18.2 ソースコード
3 埋め込みインタフェースを用いたアプリケーション開発
3.1.1 ヘッダファイルとライブラリ
3.1.2 初期化
3.1.3 終了処理(Closing down)
3.1.4 WebBrowser オブジェクトの生成
3.1.5 ルートのdocshellを取得する
3.1.6 イベントの予約購読
3.1.7 特定のURLをブラウズする
3.1.8 クリップボードの操作
3.1.9 コンテクストメニューの通知を受け取る
1. 序章
このドキュメントは、サードパーティのアプリケーションへと"Gecko"を埋め込むためのAPIについて記述したものである。ここでは、webbrowserオブジェクトと docshellオブジェクトおよびそれらを制御するためのインタフェースについて議論している。
XPCOM, CID, インタフェースそしてIDL といったような用語が至る所にばらまかれている。もしあなたが XPCOM に慣れていないのなら、その言葉の意味するところを修得するために、
http://www.mozilla.org/projects/xpcom/ を読み切ってください。COM/ActiveX に慣れているWindows のプログラマは、XPCOM を理解しやすいだろう。両者には密接な関連がある。
斜体字は起案中の件(draft notes)を表している。
1.1 概要
あなたが Mozillaを起動すると、ブラウザウィンドウが現れます。このブラウザは、chrome,コンテンツ, サイドパネル, ボタンその他を表すフレームによって作られています。フレームはほかのフレームへと入れ子状に組み込まれ、階層構造を形作ります。ルートのフレームはブラウザウィンドウを表し、それは個別のコンポーネントを管理するサブフレームを持っている。各フレームはそのコンテンツとなるドキュメントに関連づけされる。
コンテンツには責任のあるものと無いものがある。責任あるコンテンツは chromeとして知られている。これは通常ローカルなストアからロードされ、ホストマシンと相互にやりとりするためにより大きな権限を持っている。通常、最前面のフレームはchromeで、コンテンツのサブフレーム
から構成される。
最近になるまで、フレームと関連ドキュメントの管理に対する責任を負ったオブジェクトはwebshellと呼ばれていた。最前面の webshellはホストアプリケーションによって制御され、各々の子webshellは順にその親webshellによって管理される。
図１： 従来の構造
webshell は子webshellと親webshellに対する横断的なメソッドを持っていた。またwebshell は、他にも多くのメソッドを持っていた。サイズ指定や位置指定、ドキュメントの読込みや再読込み、前方・後方へのナビゲーションや、chromeや、プログレス・コールバックの登録や、プリファレンスの設定や．．．容易に想像できるように、webshellは非常に複雑でデブになってしまった。さらに悪いことに、露出したメソッドの全てが単一のインタフェース上に定義されていた！nsIWebShell インタフェースは３０を超えるメソッドとプロパティを持っていて、あまりにも変化を重ねてきたために、もはや事実上それを不変のものにすることは不可能になっていた。 webshellを書き替えることができたなら、Mozilla がもっとよいものになることは明らかだった。
nsIWebShellが生まれてこの方、そこにいくつのメソッドが追加されてきたかを理解するために、ここを見てほしい。あなたは nsIWebShell がIDLから生成されているのではなく、C++で定義されていることにも気がつくだろう。これによって、XPConnectによって使われることを防止し、全ての種類のXPCOMの乱用に至ることを防ぎ、メソッドの入出力の意味があいまいにならずに済む。
Travis Bogard はwebshell オブジェクトとnsIWebShell インタフェースの再設計を開始した。メソッドは新しく、より論理的なインタフェースへと生まれ変わり、webshellの機能はdocshellと呼ばれる新しい基底クラスにスッキリと書き替えられた。埋め込み用の機能はwebbrowserという新しいオブジェクトに移動した。
docshell は階層構造の各ノードで必要とされる機能にフォーカスを当てた、webshellをきれいに置き換えるものである。webbrowser オブジェクトはクライアントアプリケーションが埋め込み用に使用するものである。
docshell という名前はドキュメント管理用のオブジェクトとしては、webshellよりも的を得ている。ここでいうドキュメントには HTML ドキュメントが含まれる。docshellはあらゆるタイプのドキュメントを保持することができるが、通常はDOMによってパーズされ表現されうるドキュメントである。DOMへとパーズされたHTML やXML は生きている間docshellによって管理される。
図２： Docshell の階層構造
新しいデザインでは、横断的なインタフェースから埋め込みに特化した要素を切り離した。これによって、埋め込み用クライアントアプリケーションに直接接している最前面のドキュメントのみが、予約購読と通知のコード（何が進行中かをクライアントに知らせ続けるために必要とされる）を含む。
各々の docshell は、それがロードされている間そのdocshell上にセットされた一つのドキュメントを管理する。ローディングでは、docshellのナビゲーション・インタフェース・メソッドによって初期化される。 docshell はプレゼンテーション領域およびドキュメント描画用のコンテキストを明示する。例えば、コンテキストがスクロールバーを持っているかどうか、chromeとコンテンツのどちらを表すのか、プラグインをサポートするのかどうか、そして子docshellなのか親docshellなのか、といったことを明示する。
Webshell は完全に無くなってしまったわけではないが、その要素がますますdocshell基底クラスに移動するにつれて、ゆっくりと収縮していく。やがてwebshellオブジェクトと nsIWebShell インタフェースは消え去るだろう。webshellとnsIWebShell のどちらも、今後は使われることがないように、ここではドキュメント化されていない。
1.2 主要な埋め込みオブジェクト
ここに主要な埋め込みオブジェクトの概要を示す。
図 3 埋め込みオブジェクトとそれらの主要なインタフェース
1.2.1 Docshell オブジェクト
1.2.1.1 クラス：nsDocShell
docshell XPCOM オブジェクトはnsDocShellによって C++のクラスとして実装されている。
このクラスはドキュメントのローディングと表示に関して責任を持っている。
URIのローディングの場合は、docshell は一つのURI ローダオブジェクトを生成する。次にそれにコンテンツを取ってくるように指示し、ヘルパーオブジェクトであるnsDSURIContentListenerを経由してコンテンツの到着を監視する。最初のコンテンツが到着すると、 docshellはコンテンツ表示オブジェクトを生成する。コンテンツ表示オブジェクトはコンテンツのレンダリングに責任を持つ。
docshell（表示すべき新しいDOMを明示する）の SetDocument が呼ばれると、それは新しいドキュメントとドキュメントを管理するビューを生成し、 そのビューワをdocshellに関連づける。次にそれはDOMのルートノードをドキュメントオブジェクトに関連づける。この関連づけは、そのドキュメントの各プレゼンテーション・シェル（presshellをdocshellと同じ大きさになるようにサイズ調節する）を通して行われる。ドキュメントがロードされると、それは処理が完了したことをオブザーバに通知するために、EndDocumentLoadイベントを発射する。
docshell は、その公開されたインタフェース経由で制御されるXPCOM オブジェクトである。docshell は、新しいコンテンツをロードするメソッドや、カレントのドキュメントを変更するメソッドや、カレントのスクロールバーの位置を見てスクロールするビューに作用するメソッドや、親docshellや子docshellを取得するためのメソッドを持っている。
1.2.1.2 シークエンスダイアグラム
するべき事： もっとシークエンスダイアグラムを追加しよう
ドキュメントがリクエストされると (例えば、特定の URLをロードするようにdocshellに指示することによって)、docshell は処理を開始する。その処理は最終的には生成中のコンテンツビューワへとつながる。コンテンツビューワはドキュメントのコンテンツをプレゼンテーション・シェルへと表示する。
図 4 ローディングのシークエンス
1.2.1.3 docshellによって実装されるインタフェース
- nsIDocShell
- nsIDocShellTreeItem
- nsIDocShellTreeNode
- nsIWebNavigation
- nsIWebProgress
- nsIBaseWindow
- nsIScrollable
- nsITextScroll
- nsIContentViewerContainer
- nsIInterfaceRequestor
- nsIScriptGlobalObjectOwner
- nsIRefreshURI
1.2.2 WebBrowser オブジェクト
1.2.2.1 クラス：nsWebBrowser
webbrowser オブジェクトはC++ のクラスであるnsWebBrowserによって実装されている。埋め込み用のクライアントはアプリケーションにGeckoを埋め込むために、このクラスのインスタンスを生成しなければならない。
このオブジェクトの主要なインタフェースは nsIWebBrowserです。このインタフェースは、クライアントがコンテンツをロードしたり、コールバック・インタフェース（進行状況やナビゲーションの通知を受け取るための）を登録したりするために用いるメソッドと属性を持っています。
機能は個別のインタフェースに分割されます。それによって、ウェブ・ナビゲーションの機能はwebbrowserコンポーネントの位置決めやサイズ出しに使われる機能とは区別されます。その機能はまた、表示をスクロールさせるために使われる機能とも異なります。このことは、モノリシックなnsIWebShell とは対照的です。nsIWebShellでは全てが 一つのインタフェース上にありました。
クライアントがインスタンス生成した全ての webbrowser に対して、それの仲間となるコンテナオブジェクトあるいはサイトオブジェクトもまた生成する必要があります。これらのオブジェクトはwebbrowserが正しく機能するために必要なコールバック関数のハンドリングなどを行います。
webbrowser site オブジェクトは一つのXPCOM オブジェクトです。それは、自身が実装するインタフェースを通して、呼び出しを受け取ります。受け取るタイミングとしては、ローディングの前／最中／後や、webbrowserがwebbrowser site に対してサイズ変更や進行状況の通知を要求するときなどがあります。
1.2.2.2 シークエンス・ダイアグラム
するべき事：
docshellの取得
listenersの登録
1.2.2.3 WebBrowserによって実装されるインタフェース
- nsIWebBrowser
- nsIWebNavigation
- nsIBaseWindow
- nsIWebProgress
- nsIScrollable
- nsITextScroll
- nsIDocShellTreeItem
1.2.3 Webbrowser site オブジェクト
このオブジェクトはクライアントアプリケーションによって、webbrowserオブジェクトと相互にやり取りするために実装されなければなりません。これはここではサイト・オブジェクトとして参照されますが、時には他の場所にあるコンテナによって呼び出されます。
このオブジェクト上のインタフェースは、このオブジェクトを docshell階層構造のオーナーにします。そしてドキュメントがロードされているときや、コンテンツが何らかのユーザインタフェースの表示、例えばメッセージボックスの表示などを要求したときに、それをコールバック関数で受け取ることができるようにします。
図５： webbrowser と関連づけられたwebbrowser site
1.2.3.1 シークエンス・ダイアグラム
するべき事：
1.2.3.2 webbrowser site によって実装される。
これらのインタフェースのほとんどがオプションとしてあるべきです。しかし実際は そうではありません。Webbrowserとdocshellはサイト・オブジェクトのインタフェースの 欠落にもさらに耐えられるように変更されるべきです。なぜなら、それを書くことは埋め込みアプリの開発者にとってはたいへんな苦痛だからです。
- nsIBaseWindow - 私はなぜこのインタフェースが必要なのかについては確信がない。
- nsIWebBrowserChrome -
- nsIWebProgressListener
- nsIStreamObserver
- nsIURIContentListener
- nsIDocumentLoaderObserver - 旧式のもの
- nsIDocShellTreeOwner
- nsIInterfaceRequestor
- nsIPrompt - 任意のもの
2 主なインタフェース
2.1 インタフェース：nsIBaseWindow
ウィジェットのコンテナはこのインタフェースを実装する。このインタフェースは、
ウィンドウに対しての生成、破棄、初期化、サイズ変更、移動といったメソッドからなる。
2.1.1 実装オブジェクト
- Webbrowser
- Webbrowser site
2.1.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/widget/public/nsIBaseWindow.idl
2.2 インタフェース：nsIContentViewerContainer
コンテンツ・ビューワのコンテナはこのインタフェースを実装する。このインタフェースは、コンテンツ・ビューワ・オブジェクトをコンテナに挿入する際に呼ばれる単一のメソッドからなる。
2.2.1 注意
IDL ファイルとしては定義されていない。なんてこった!
2.2.2 実装オブジェクト
2.2.3 ソースコード
http://lxr.mozilla.org/seamonkey/source/webshell/public/nsIContentViewerContainer.h
2.3 インタフェース：nsIDocShell
docshell オブジェクトはこのインタフェースを実装する。このインタフェースは含まれるドキュメントを設定する、URIをロードする、ハンドラおよびリスナーを登録するメソッドからなる。
2.3.1 実装オブジェクト
2.3.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/docshell/base/nsIDocShell.idl
2.4 インタフェース：nsIDocShellTreeItem
docshellツリーの階層構造におけるアイテムはこのインタフェースを実装する。このインタフェースは、親アイテムや名前の付いた子アイテムを取得するメソッドからなる。このインタフェースはまた、アイテムがchromeとコンテンツのどちらを表しているかを示すプロパティを含む。
2.4.1 実装オブジェクト
2.4.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/docshell/base/nsIDocShellTreeItem.idl
2.5 インタフェース：nsIDocShellTreeNode
docshellツリーの階層構造におけるアイテムはこのインタフェースを実装する。このインタフェースは、子ノードを追加、削除および列挙するメソッドからなる。
2.5.1 実装オブジェクト
2.5.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/docshell/base/nsIDocShellTreeNode.idl
2.6 インタフェース：nsIDocShellTreeOwner
docshellツリーの階層構造のオーナーは、このインタフェースを実装する。このインタフェースは名前の付いたdocshellや、リサイズの要求に応えるコールバック関数を設定するメソッドを持つ。docshellツリーのオーナーによって実装される。
2.6.1 実装オブジェクト
2.6.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/docshell/base/nsIDocShellTreeOwner.idl
2.7 インタフェース：nsIInterfaceRequestor
nsIInterfaceRequestor はオブジェクトがリターンすることを許可する。
2.7.1 実装オブジェクト
2.7.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/xpcom/base/nsIInterfaceRequestor.idl
2.8 インタフェース：nsIPrompt
クライアントに独自バージョンのダイアログの実装を可能にする。そのダイアログは、例えば、ユーザが安全なページから安全でないページに行った時や、ページのローディングがタイムアウトしたときに、Geckoが表示する必要があるものである。
2.8.1 実装オブジェクト
- Webbrowser site - またはnsIInterfaceRequestor経由のヘルパーオブジェクト
2.8.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/netwerk/base/public/nsIPrompt.idl
2.9 インタフェース：nsIRefreshURI
Docshell オブジェクトはこのインタフェースを実装する。コンテンツをリフレッシュするタイマをセットしたりキャンセルするメソッドからなる。
2.9.1 実装オブジェクト
2.9.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/webshell/public/nsIRefreshURI.h
2.10 インタフェース：nsIScriptGlobalObjectOwner
グローバル・スクリプト・オブジェクトを返すメソッド。
2.10.1 実装オブジェクト
2.10.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/dom/public/nsIScriptGlobalObjectOwner.idl
2.11 インタフェース：nsIScrollable
現在のスクロールバーの位置と、その振る舞いに影響するプロパティを得るためのメソッド。
2.11.1 実装オブジェクト
2.11.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/docshell/base/nsIScrollable.idl
2.12 インタフェース：nsIStreamObserver
2.12.1 実装オブジェクト
2.12.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/netwerk/base/public/nsIStreamObserver.idl
2.13 インタフェース：nsITextScroll
表示をスクロールするためのメソッド。上下方向。ライン単位またはページ単位。
2.13.1 実装オブジェクト
2.13.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/docshell/base/nsITextScroll.idl
2.14 インタフェース：nsIWebBrowser
クライアントがリスナを登録し、ルートオブジェクトのnsIDocShellを取得するためのプロパティです。
2.14.1 実装オブジェクト
2.14.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/embedding/browser/webbrowser/nsIWebBrowser.idl
2.15 インタフェース：nsIWebBrowserChrome
コンテンツは、あなたのコンテナが自分自身をモーダルに表示したり、ステータスバーのような一種の飾りを隠すといったようなある種の振る舞いをすることを要求することがある。これはそんなリクエストに応えるためのインタフェースです。
2.15.1 実装オブジェクト
2.15.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/embedding/browser/webbrowser/nsIWebBrowserChrome.idl
2.16 インタフェース：nsIWebNavigation
ウェブ・ナビゲーションのために使われるインタフェース。新しいURIのローディング、ローディングの停止、再ローディング、前方・後方へのヒストリ移動、カレントのURIを示すプロパティ表示などのメソッドを持つ。
2.16.1 実装オブジェクト
2.16.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/docshell/base/nsIWebNavigation.idl
2.17 インタフェース：nsIWebProgress
nsIWebProgressListener インタフェースを登録するメソッドです。現在のダウンロード状況の通知を伴って呼ばれます。
2.17.1 実装オブジェクト
- Webbrowser
- Webbrowser site
2.17.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/uriloader/base/nsIWebProgress.idl
2.18 インタフェース：nsIWebProgressListener
このインタフェースはローディングの最中に、その進行状況を示すために呼ばれます。
2.18.1 実装オブジェクト
2.18.2 ソースコード
http://lxr.mozilla.org/seamonkey/source/uriloader/base/nsIWebProgressListener.idl
3 埋め込みインタフェースを用いたアプリケーション開発
3.1.1 ヘッダファイルとライブラリ
するべき事：
3.1.2 初期化
あなたはブラウザオブジェクトを生成する前に、埋め込み用にあなたのアプリを初期化しなければならない。こんな風に。
NS_InitEmbedding();
あなたのアプリが Mozilla のバイナリ・ディレクトリの外側で実行されるなら、Gecko が必要なコンポーネントの在処を見つけられるように、パラメータとしてパスを指定しなければならない。
例：
const char *szPath = "usr/local/mozilla/bin"
NS_InitEmbedding(szPath);
3.1.3 終了処理(Closing down)
するべき事：
NS_TermEmbedding();
3.1.4 WebBrowserオブジェクトを生成する
webbrowser コンポーネントはそのクラスID (CID)かまたはそのプログラム ID (PROGID)を経由して、インスタンス生成される。PROGID は人間が読めるCIDと等価な文字列で、CIDをそのまま使うことができないスクリプト言語のためのものです。一般的に言って、CID はC++言語で使用されるべきです。理由は、それがオブジェクトを指定する曖昧さのない方法だからです。
3.1.5 ルートのdocshellを取得する
ルートの docshell はコンテンツの最前面のフレームです。あなたがこれを必要とするのは、特定のURIからコンテンツをロードしたいときと、DOMをパーズしたいときなど、その他なんでもです。webbrowser がこのオブジェクトを管理するのであなたはそれをする必要はありません。しかし、それを便利に使うためにストアする必要はあります。
3.1.6 イベントの予約購読
複数のdocshellが入れ子構造になること、および埋め込み用のクライアントがwebbrowser経由で最前面のdocshellに連結するということはすでに示したとおりです。そのクライアントアプリケーションはwebbrowserを使って、一つのサイト・オブジェクトを登録しなければなりません。サイト・オブジェクトにはコールバック関数 XXXX が含まれています。
3.1.7 特定のURLをブラウズする
nsIWebNavigation インタフェースはルートのdocshell に指定したURLをロードさせるために使用します。
パラメータに URL を渡してLoadURI()を呼び出してください。例えば、次のように。
nsCOMPtr<nsIWebNavigation> webNav = do_QueryInterface(mRootDocShell);
webNav->LoadURI("http://www.mozilla.org");
3.1.8 クリップボードの操作
クリップボードの操作はコンテキスト・ビューワから利用可能です。nsIContentViewerEditインタフェースはテキストをコピーし、ペーストし、カットし、選択するメソッドを持っている。例えば、次のように。
nsCOMPtr<nsIContentViewer> viewer;
mRootDocShell->GetContentViewer(getter_AddRefs(viewer));
nsCOMPtr<nsIContentViewerEdit> edit(do_QueryInterface(viewer));
edit->CopySelection();
3.1.9 コンテクストメニューの通知を受け取る
いくつかのクライアントは、ユーザがリンクや他の要素をを右クリックした場合に、ポップアップメニューを表示するために、通知を受ける必要がある。クライアントは、nsIContextMenuListenerを自身のwebbrowser siteオブジェクトに実装することによって、またはそれをnsIInterfaceRequestorインタフェース経由で供給することによって、この通知を受け取ることがある。
するべき事：
|
