Creating toolbar buttons

はじめに、機能を強化させたいツールバーを含む文書への オーバレイ を作成する必要があります。オーバレイの説明はこのチュートリアルでは扱いません。XUL チュートリアル をご覧ください。

文書をオーバレイするには、その文書の URI を知らなければなりません。よくオーバレイされる文書の URI は このページの最後 にあります。

ツールキットアプリケーションのツールバーはカスタマイズ可能です。そのため、拡張機能の練習として、直接ツールバーにボタンを追加するのではなく、ツールバーボタンをツールバーパレットに追加するというものがよくあります。直接追加することも可能ですが、非推奨であり、実装も面倒です。

ツールバーパレットにボタンを追加するのはとても簡単です。このようにこのコードをオーバレイに追加するだけです：

<toolbarpalette id="BrowserToolbarPalette">
  <toolbarbutton id="myextension-button" class="toolbarbutton-1"
    label="&toolbarbutton.label;" tooltiptext="&toolbarbutton.tooltip;"
    oncommand="MyExtension.onToolbarButtonCommand(event);"/>
</toolbarpalette>

注意：

• パレットの id（この例では BrowserToolbarPalette）はボタンを追加したいツールバーのあるウィンドウによって異なります。下 のよく使われるパレットの ID のリストを参照してください。
• class="toolbarbutton-1" によって、「アイコンと文字」モードで正常にツールバーボタンが表示されるようになります。さらにパッディングも調整されます。
• oncommand 属性で、ボタンがクリックされたときに実行されるコマンドを指定してください。ミドルクリックを扱いたい場合は onclick ハンドラを追加し、その中で event.button を確認してください。

onclick: function(event) {
  switch(event.button) {
    case 0:
      // Left click
      break;
    case 1:
      // Middle click
      break;
    case 2:
      // Right click
      break;
  }
}

さらにボタンを追加するには、<toolbarbutton> 要素を <toolbarpalette> 要素の内側にさらに追加してください。<toolbarbutton> 以外の要素は <toolbaritem> 内に内包するようにしてください。

ツールバーボタンのほとんどはアイコンが付いています。ボタンに画像を付けるには Mozilla のスキン機能を使用します。これについてよく知らないのであれば、Jonah Bishop によるすばらしいツールバーチュートリアルのスキンの使用に関するセクション を読んでおくことをお勧めします。その記事ではボタンを作るだけというよりもむしろツールバー全体を作ることを扱っていますが、私たちがここで使うテクニックの説明としてはすばらしいものです。

アイコンのサイズ

ツールバーボタンは大小 2 種類のサイズを持ちえます。つまり、ツールバーボタンにそれぞれ 2 つのアイコンを持たせる必要があるということです。さまざまなアプリケーションでの大小両方のアイコンの寸法は以下の表のとおりです（他のアプリケーションについての情報もご自由に追加してください【訳註：英語版に追加すべき】）：

スタイルシート

ツールバーボタンに画像を指定するために、以下の CSS ルールを使用してください：

/*  skin/toolbar-button.css  */

#myextension-button {
  list-style-image: url("chrome://myextension/skin/btn_large.png");
}

toolbar[iconsize="small"] #myextension-button {
  list-style-image: url("chrome://myextension/skin/btn_small.png");
}

スタイルシートの適用

作成したスタイルシートをオーバレイファイルと Customize Toolbar ウィンドウの両方に適用するのを忘れないでください。オーバレイファイルに適用するには、この処理命令 (PI) をオーバレイファイルの頭に付けてください：

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

Customize Toolbar ウィンドウ (<tt>chrome://global/content/customizeToolbar.xul</tt>) に適用するには、以下のような <tt>skin/contents.rdf</tt> を使用することのがよいでしょう：

<?xml version="1.0"?>
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:chrome="http://www.mozilla.org/rdf/chrome#">

  <Seq about="urn:mozilla:skin:root">
    <li resource="urn:mozilla:skin:classic/1.0"/>
  </Seq>

  <Description about="urn:mozilla:skin:classic/1.0">
    <chrome:packages>
      <Seq about="urn:mozilla:skin:classic/1.0:packages">
        <li resource="urn:mozilla:skin:classic/1.0:myextension"/>
      </Seq>
    </chrome:packages>
  </Description>

  <Seq about="urn:mozilla:stylesheets">
    <li resource="chrome://global/content/customizeToolbar.xul"/>
  </Seq>

  <Seq about="chrome://global/content/customizeToolbar.xul">
    <li>chrome://myextension/skin/toolbar-button.css</li>
  </Seq>
</RDF>

Firefox/Thunderbird 1.5 向けの拡張機能では代わりに以下のような chrome.manifest を使用すべきです：

skin  myextension  classic/1.0  chrome/skin/
style chrome://global/content/customizeToolbar.xul chrome://myextension/skin/toolbar-button.css

これは拡張機能作者がよく起こす間違いとその症状、そしてその解決策のリストです。

問題点： ツールバー上や Customize Toolbars ウィンドウ内に自分のアイコンではなく、デフォルトのボタン全体が表示される。

原因： スタイルシートが正しく記述されていないか、またはスタイルシートが適用されていない。

解決法： スタイルシートに誤りがないか、<tt>contents.rdf</tt>（または <tt>chrome.manifest</tt>）に誤りがないかを確認し、確実に <tt>customizeToolbar.xul</tt> に スタイルシートを適用する。

• XulPlanet.com リファレンス: <toolbarbutton>、<toolbaritem>
• ツールバーボタンのラベルの位置を調整する方法
• 拡張機能のインストール直後に（パレットにではなく）ツールバーにアイテムを追加することに関する フォーラムのスレッド。この方法は非推奨であることに注意。
• MDC 上には SeaMonkey のさまざまなウィンドウにボタンを追加することについての 別のページ があります。ChatZilla へのオーバレイについての便利な情報が載っています。