Overlays

オーバーレイ

This section will describe overlays which can be used to separate common content.

このセクションでは、共通の内容を分離するのに使えるオーバーレイの説明をします。

Using Overlays

オーバーレイを使う

In a simple application with only one window, you will generally have only one XUL file, along with a script file, a style sheet, a DTD file and perhaps some images. Some applications will have a number of dialogs associated with them also. These will be stored in separate XUL files. More sophisticated applications will contain many windows and dialogs.

ウィンドウを一つしか使わない単純なアプリケーションでは、普通、XUL ファイルが一つに、 スクリプトファイル、スタイルシート、DTD ファイルが一つずつ、それにおそらく画像が 幾つかあるだけでしょう。アプリケーションによっては、関連付けられたダイアログを 多数もつものもあることでしょう。これらのダイアログは、別々の XUL ファイルに保存 することと思います。もっと込み入ったアプリケーションの場合には、多数のウィンドウと ダイアログがあることでしょう。

An application that has several windows will have numerous elements or parts of the user interface that are common between each window. For example, each of Mozilla's components share some common elements. Some of the menus are similar, such as the Tools and Help menus, the sidebar is similar, and each window shares some common global keyboard shortcuts.

ウィンドウを幾つかもつアプリケーションには、個々のウィンドウ間に共通する ユーザインターフェイスの要素や部分が数多くあることでしょう。例えば、Mozilla の個々のコンポーネントは、共通する要素を共有しています。タスクやヘルプメニューなど、 メニューの幾つかは類似しています。サイドバーは類似しています。個々のウィンドウは、 共通のグローバルなキーボードショートカットを共有しています。

One could handle this by re-implementing the similar elements and functions in each file that are needed. However, this would be difficult to maintain. If you decide to change something, you would have to change it in numerous places. Instead, it would be better to use a mechanism that allows you to separate the common elements and have them shared between windows. You can do this with overlays.

必要なファイルのそれぞれで、類似した要素や機能を再実装することによって、 このようなことを処理できるかもしれません。しかし、そうするとメンテナンスが 困難になります。あるものを変えようと決めた場合、それを色々な場所で変えなければ ならなくなるでしょう。むしろ、共通する要素を分離し、それらをウィンドウ間で 共有できるメカニズムを使う方がよいでしょう。これはオーバーレイを使えば可能です。

Within an overlay, you may place elements that are shared between all windows that use that overlay. Those elements are added into the window at locations determined by their ids.

オーバーレイの内部には、オーバーレイを使うウィンドウすべてで共有される要素を置きます。 こうした要素は、id によって決められたウィンドウ内の場所に追加されます。

For example, let's say you want to create a help menu that is shared between several windows. The help menu will be placed in an overlay, using the same XUL that you would use normally. The menu will be given an id attribute to identify it. Each window will import the overlay using a directive which will be described in a moment. To use the help menu as defined in the overlay, you only need to add a single menu element with the same value for its id attribute as used in the overlay. This menu does not need to contain any children as those will be placed in the overlay.

例えば、幾つかのウィンドウ間で共有されるヘルプメニューを作りたいとしましょう。 ヘルプメニューは、通常使用するのと同じ XUL を使って、オーバーレイに置きます。 メニューには、識別用に id 属性を与えておきます。 個々のウィンドウは、すぐ後で説明するディレクティブ (directive) を使って オーバーレイをインポートします。オーバーレイで定義されたヘルプメニューを使うには、 id 属性にオーバーレイで使ったのと同じ値をもつ メニュー要素を一つ追加するだけです。オーバーレイ内に子供を置くため、 このメニューは子供をもつ必要はありません。

When a window with an overlay is opened, the elements in both the window and the overlay with the same ids are combined together. The children of matching elements are added to the end of the set of children in the window's element. Attributes that are present on the overlay's elements will be applied to the window's elements. These details will be explained in more detail later.

オーバーレイをもつウィンドウを開くと、ウィンドウとオーバーレイの両方に同じ id をもつ要素は、互いに結び付けられます。マッチした要素の子供は、ウィンドウの 要素内の子供セットの後ろに追加されます。オーバーレイの要素にある属性は、 ウィンドウの要素に適用されます。この詳細は後でもっと詳しく説明します。

To import an overlay into a window, use the syntax described below. Let's add this near the top of the findfiles dialog XUL file.

オーバーレイをウィンドウにインポートするには、以下で説明するシンタックスを使います。 「ファイル検索」ダイアログの XUL ファイルの先頭近くに次のコードを追加しましょう。

<?xul-overlay href="chrome://findfile/content/helpoverlay.xul"?>

This line should be added somewhere near the top of the file, usually just before any DTDs are declared. In the example above, the window is importing an overlay stored in the file helpoverlay.xul.

この行はファイルの先頭近くのどこか、通常は DTD を宣言するすぐ前に追加します。 上の例では、ウィンドウは helpoverlay.xul ファイルに保存されたオーバーレイを インポートします。

The overlay itself is a XUL file that contains an overlay element instead of a window element. Other than that, it is much the same. You can import overlays from inside other overlays. Overlays can also have their own stylesheets, DTDs and scripts. The example below shows a simple Help menu stored in an overlay.

オーバーレイ自身は、ウィンドウ要素の代わりにオーバーレイ要素をもつ XUL ファイルです。 それ以外は、ほとんど同じです。他のオーバーレイの内部からオーバーレイをインポート することもできます。オーバーレイは、それ自身のスタイルシートや DTD、スクリプトを もつこともできます。下の例は、オーバーレイに保存された簡単なヘルプメニューを 示しています。

Example 12.6.1: Source
<?xml version="1.0"?>

<!DOCTYPE overlay SYSTEM "chrome://findfile/locale/findfile.dtd">

<overlay id="toverlay"
  xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<menu id="help-menu">
  <menupopup id="help-popup">
    <menuitem id="help-contents" label="&contentsCmd.label;"
              accesskey="&contentsCmd.accesskey;"/>
    <menuitem id="help-index" label="&indexCmd.label;"
              accesskey="&indexCmd.accesskey;"/>
    <menuitem id="help-about" label="&aboutCmd.label;"
              accesskey="&aboutCmd.accesskey;"/>
  </menupopup>
</menu>

</overlay>

The overlay element surrounds the overlay content. It uses the same namespace as XUL window files. Defined within the overlay is a single menu with three items in it. The id of this menu is help-menu. This means that its content will be added to the window where a similar element exists with the same id value. If such an element does not exist, that part of the overlay is ignored. The overlay can contain as many elements as necessary. Note that the overlay needs to include the DTD file also. We use the same one as the main window here, but normally you would create a separate DTD file for each overlay.

overlay 要素がオーバーレイの 内容を囲んでいます。これには、XUL ウィンドウファイルと同じ名前空間を使います。 オーバーレイの内部には、3 つの項目からなるメニューが一つ定義されています。 このメニューの idhelp-menu です。これは、同じ id 値をもつ類似した要素があるウィンドウ内に、その内容が追加される ということを表しています。そのような要素がない場合、オーバーレイのその部分は無視 されます。オーバーレイは、必要に応じて要素を幾つでももつことができます。 このオーバーレイは DTD ファイルも必要としている、ということを記しておきます。 ここではメインウィンドウと同じファイルを用いていますが、普通はオーバーレイごとに わけて DTD ファイルを作るようにします。

Next, we need to add the help menu to the findfiles dialog window. To do this just add a menu with the same id in the right location. The most likely place is just after the edit menu.

次に、ヘルプメニューを「ファイル検索」ダイアログウィンドウに追加する必要が あります。このためには、同じ id をもつメニューを適切な場所に加えるだけです。 最もよさそうな場所は edit メニューのすぐ後でしょう。

  <menu id="edit-menu" label="Edit" accesskey="e">
    <menupopup id="edit-popup">
      <menuitem label="&cutCmd.label;" accesskey="&cutCmd.accesskey;"
                key="cut_cmd"/>
      <menuitem label="&copyCmd.label;" accesskey="&copyCmd.accesskey;"
                key="copy_cmd"/>
      <menuitem label="&pasteCmd.label;" accesskey="&pasteCmd.accesskey;"
                key="paste_cmd" disabled="true"/>
    </menupopup>
  </menu>
  <menu id="help-menu" label="&helpCmd.label;"
        accesskey="&helpCmd.accesskey;"/>
</menubar>

Here, the help menu element contains no content. The items from the menu are taken from the overlay because the ids match. We can then import the overlay in other windows and only have the contents of the help menu defined in one place. We need to add some lines to the DTD file as well:

ここでは、ヘルプメニュー要素には内容が何もありません。メニューの項目は、 id がマッチするので、オーバーレイから取られます。このオーバーレイは別の ウィンドウでもインポートできます。そのため、一個所で定義したヘルプメニューの 内容がありさえすれば十分です。それから DTD ファイルにも数行を追加する必要があります:

 <!ENTITY helpCmd.label "Help">
 <!ENTITY helpCmd.accesskey "h">
 <!ENTITY contentsCmd.label "Contents">
 <!ENTITY indexCmd.label "Index">
 <!ENTITY aboutCmd.label "About...">
 <!ENTITY contentsCmd.accesskey "c">
 <!ENTITY indexCmd.accesskey "i">
 <!ENTITY aboutCmd.accesskey "a">
 <!ENTITY findfilehelpCmd.label "Find files help">
 <!ENTITY findfilehelpCmd.accesskey "f">

We will use the last two entities in a moment.

すぐ後で最後の 2 つの実体 (entity) について説明します。

We can further reduce the amount of code within the window by putting the attributes on the help menu (label and accesskey in this example) in the overlay instead. Those attributes will be inherited by the element. If both the element and the window specify the same attribute, the value in the overlay will override the element's value.

ヘルプメニューの属性 (この例では labelaccesskey) をオーバーレイに置くことによって、 ウィンドウ内のコードの量をさらに減らすことができます。要素はこれらの属性を継承します。 要素とウィンドウの両方に同じ属性を指定すると、オーバーレイ内の値が要素の値を 上書きします。

Let's change the help menu in this manner.

ヘルプメニューをこのやり方で変更しましょう。

findfile.xul:

<menu id="help-menu"/>

helpoverlay.xul:

<menu id="help-menu" label="&helpCmd.label;"
       accesskey="&helpCmd.accesskey;">

If there is content inside both the XUL window and in the overlay, the window's content will be used as is and the overlay's content will be appended to the end. This following example demonstrates this:

XUL ウィンドウとオーバーレイの両方に内容があるときは、ウィンドウの内容が そのまま使われ、オーバーレイの内容はその末尾に追加されます。以下の例は、 このことを示しています:

stopandgo.xul:

<?xml version="1.0"?>

<?xml-stylesheet href="chrome://global/skin/global.css" type="text/css"?>

<window title="Stop and Go" id="test-window"
   xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<?xul-overlay href="chrome://findfile/content/toverlay.xul"?>

<box id="singlebox">
  <button id="gobutton" label="Go"/>
  <button id="stopbutton" label="Stop"/>
</box>

</window>

toverlay.xul:

<?xml version="1.0"?>

<overlay id="toverlay"
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<box id="singlebox">
  <button id="backbutton" label="Back"/>
  <button id="forwardbutton" label="Forward"/>
</box>

</overlay>

In this example, the box with the identifier singlebox contains its own content. The elements are combined and the two buttons from the overlay are added to the end of the box.

この例では、識別子 singlebox をもつボックスには それ自身の内容があります。要素は結合されて、オーバーレイの 2 つのボタンが ボックスの末尾に追加されます。

We can use this technique in the find files dialog also:

「ファイル検索」ダイアログでも、このテクニックを使うことができます:

findfile.xul:

  <menu id="help-menu">
    <menupopup id="help-popup">
      <menuitem id="help-findfiles" label="&findfilehelpCmd.label;" accesskey="&findfilehelpCmd.accesskey;"/>
    </menupopup>
   </menu>
</menubar>

The id attribute of the menupopup element also matches the one in the overlay. This will cause the items to be merged into the same popup. Overlays will merge items with the same ids even if they are inside of other elements.

menupopup 要素の id 属性もオーバーレイのものとマッチしています。 このため、同じポップアップに項目が併合されます。他の要素の内側にある項目で あっても、同じ id 属性をもつものはオーバーレイによって併合されます。

Placing Overlaid Elements

オーバーレイされた要素を置く

However, we may have wanted to have the menu items from the overlay in the previous example placed at the beginning of the menu instead of at the end. XUL provides a mechanism that allows you to not only place them at the beginning but to put some of the items at the top and others at the bottom (or anywhere in-between). This allows you to overlay menus, toolbars and other widgets at the exact location that you wish.

さて前の例では、オーバーレイ内のメニュー項目を末尾にではなく、メニューの先頭に 置きたかったのでした。XUL は、それらを先頭だけでなく、項目の幾つかを先頭に置き 残りを下部 (あるいは、その間のどこにでも) 置くメカニズムを提供しています。 これによって、メニュー、ツールバー、その他のウィジェットを必要な正確な場所に オーバーレイすることができます。

To do this, use the insertbefore attribute on the menuitems. Its value should be the id of an element that you want to insert the item before. Alternatively, you can use the insertafter attribute to indicate which element to insert after. These attributes only affect the element the attributes are added to. If one element is 'inserted before', the remaining elements are still added to the end. If you want to have all the elements appear before, you must put the insertbefore attribute on all elements.

このためには、メニュー項目に insertbefore 属性を使います。その値は、項目を挿入したい位置のすぐ後の要素の id にします。それ以外に、どの要素の後ろに 項目を挿入したいのかを指示するため、insertafter 属性が使えます。これらの属性は、それが指定されている要素だけに影響します。 ある要素が '前に挿入された' としても、残りの要素は末尾に追加されます。 要素すべてを前に表示させたい場合、要素すべてに insertbefore を置かなければなりません。

In addition, you can use the position attribute if you want to specify a specific index position. The first position is 1.

更に、特定のインデックスの位置を指定したい場合は、 position 属性が使えます。最初の位置は 1 です。

Let's say that we wanted the Contents and Index items from the previous example to appear before the Find files help item and the About item to appear after. To do this we add the insertbefore attribute to both the Contents and Index menu items. For completeness, you could add an insertafter attribute on the About menu too, but it isn't necessary because it appears at the end by default.

前の例でオーバーレイの Contents 項目と Index 項目を "Find files help" 項目の前に表示し、 About 項目を後ろに表示したいとしましょう。このためには、 メニューの Contents 項目と Index 項目の両方に insertbefore 属性を追加します。完璧を期すため、 About メニュー項目にも insertafter を追加しても 構いませんが、これは必要ありません。それはデフォルトで末尾に表示されるからです。

In the help menu example above, the id of the menu item is help-findfiles. Thus, we need to set the insertbefore attributes to this id. The example below shows the changes:

上のヘルプメニューの例では、メニュー項目の id は help-findfiles です。このため、 insertbefore をこの id に設定する必要があります。 下の例はこの変更を示しています:

<menupopup id="help-popup">
  <menuitem id="help-contents" label="Contents" insertbefore="help-findfiles"/>
  <menuitem id="help-index" label="Index" insertbefore="help-findfiles"/>
  <menuitem id="help-about" label="About..."/>
</menupopup>

Now, when a window using the help overlay (such as the find files dialog) is opened, the following will occur:

これで、(「ファイル検索」ダイアログなどの) ヘルプオーバーレイを使ったウィンドウ が開かれると、次のことが起こります:

  1. For all of the items directly in the overlay, that is all the children of the overlay element, an element in the base window is found with the same id. If not found, that element in the overlay is ignored. In this example, the elements with the ids of help-menu and help-popup are found.
  2. If found, the attributes on the overlay's element are copied to the found element.
  3. The children of the overlay's element, in this case each menuitem, are inserted as children of the base window's element.
    • If the overlay's element contains an insertafter attribute, the element is added just after the element in the base window with the id that matches the value of this attribute.
    • If the overlay's element contains an insertbefore attribute, the element is added just before the element in the base window with the id that matches the value of this attribute.
    • If the overlay's element contains an position attribute, the element is added at the one-based index specified in this attribute.
    • Otherwise, the element is added as the last child.
  1. オーバーレイ内に直接ある項目すべて、つまりはオーバーレイ要素の子供すべて に対して、ベースとなるウィンドウの要素が同じ id をもつか調べられる。 もしなければ、オーバーレイ内の要素は無視される。この例の場合、 help-menuhelp-popup という id をもつ要素が見つかっている。
  2. もしあれば、オーバーレイ内の要素の属性が見付けられた要素にコピーされる。
  3. オーバーレイの要素の子供はベースとなるウィンドウの要素の子供として挿入される。 例の場合では、個々のメニュー項目が挿入される。
    • オーバーレイの要素に insertafter 属性があれば、この属性の値にマッチする id をもつベースウィンドウ内の 要素の直後に、この要素は追加される。
    • オーバーレイの要素に insertbefore 属性があれば、この属性の値にマッチする id をもつベースウィンドウ内の 要素の直前に、この要素は追加される。
    • オーバーレイの要素に position 属性があれば、 この属性で指定された 1 をベースとするインデックスの位置に、 この要素は追加される。
    • それ以外の場合、要素は、最後の子供として追加される。

Actually, the values of insertbefore and insertafter can be comma-separated lists, in which case the first id in the list that is found in the window is used to determine the position.

実際には、insertbeforeinsertafter の値は、カンマで区切ったリストでも 構いません。この場合は、ウィンドウで見付かったリスト内の最初の id が、 その位置を決めるのに使われます。


(Next) Next, we'll find out to apply overlays to windows in different packages.

(進む) 次は、オーバーレイを異なったパッケージ内のウィンドウに適用する場合を見ることにしましょう。

Examples: 12.6.1

Find files example so far: Source

今のところの「ファイル検索」の例: Source


Copyright (C) 1999 - 2004 XulPlanet.com
訳者: kmine
このドキュメントのオリジナルは XULPlanet において英語で公布されています。
またドキュメントの管理の言語は現在も英語です。この日本語訳は、
利用者の利便のために Mozilla Japan 翻訳部門によって提供されたものです。
フィードバックは英語で、元の著者に送って下さい。
翻訳された文書の一覧は、現在以下のURLで見ることが出来ます。
http://www.mozilla.gr.jp/jt/xul/progress.html