Creating toolbar buttons: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
(move to devmo)
Line 1: Line 1:
{{msg:extdev}}
{{msg:extdev}}


This article explains the steps that need to be done in order to add a toolbar button to toolkit applications ([[Firefox]], [[Thunderbird]], [[Nvu]] etc.) using the ''overlaying'' mechanism (often utilized by extensions). Intended audience is XUL developers who have basic knowledge of [[XUL]] and [[CSS]].


==Creating an overlay==
== Moved ==
In order to add a toolbar button, you should create an overlay to the window that contains the toolbar you wish to enhance. Explaining overlays is not in the scope of this tutorial - you can read about overlays at [http://xulplanet.com/tutorials/xultu/crosspov.html XulPlanet] and learn from existing extensions.
Moved to Devmo: http://developer.mozilla.org/en/docs/Creating_toolbar_buttons
 
You can see the list of common URLs at the bottom of this page.
 
: ''Note: Some people overlay ''chrome://messenger/content/mailWindowOverlay.xul''. That should cause the button to appear on all windows that mailWindowOverlay.xul is applied to (i.e. Main window and View Message window). Need to check that.''
 
==Adding the toolbar button==
Toolkit applications have customizable toolbars. Therefore, the common practice for extensions is to add their toolbar buttons to the toolbar palette rather than adding them directly to the toolbar. The latter is possible but is not recommended and is harder to implement.
 
Adding a button to the toolbar palette is very easy. Just add this code to your overlay:
<pre><toolbarpalette id="BrowserToolbarPalette">
  <toolbarbutton id="myextension-button" class="toolbarbutton-1"
    label="&toolbarbutton.label;" tooltiptext="&toolbarbutton.tooltip;"
    oncommand="MyExtension.onToolbarButtonCommand(event);"/>
</toolbarpalette></pre>
 
* The <code>id</code> of palette (<code>BrowserToolbarPalette</code> in the example) is different for different windows. See [[#The list of commonly overlayed windows with toolbars | below]] for the list of common palette ids.
* <code>class="toolbarbutton-1"</code> makes the toolbar button appear correctly in Icons and Text mode; it also adjusts padding.
* Put the command to be executed when the button is clicked in <code>oncommand</code> attribute. If you need to handle middle-click, add an <code>onclick</code> handler and check <code>event.button</code> in it.
 
To add more buttons, put more <code><toolbarbutton></code> elements inside the <code><toolbarpalette></code> element. Wrap other elements in <code><toolbaritem></code>.
 
==Styling the button==
Most toolbar buttons have an icon. To attach an image to the button we use standard Mozilla skinning facilities. If you're unfamiliar with it, I highly recommend you to read the [http://www.borngeek.com/firefox/tutorial/part_05.html skinning section of Jonah Bishop's excellent Toolbar Tutorial]. It talks about slightly different thing &mdash; creating a whole custom toolbar &mdash; but it has a great explanation of the techniques we'll use.
 
===Icon sizes===
Toolbar buttons can have two different sizes &mdash; big and small. This means you'll need to provide  two icons for each of your toolbar buttons. Here's the table of small and big icon sizes (in pixels) in various applications for your convenience.
{| border="1" cellpadding="5" rules="all"
! Application !! Big icon size !! Small icon size
|-
| Firefox 1.0 (Winstripe) || 24x24 || 16x16
|-
| Thunderbird 1.0 (Qute) || 24x24 || 16x16
|-
| Nvu (Orbit?) || ? || ?
|}
 
===The stylesheet===
To set the image for your toolbar button, use the following CSS:
<pre>/*  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");
}</pre>
 
===Applying the stylesheet===
Remember to attach this stylesheet to both the overlay file and <tt>customizeToolbar.xul</tt> window. To attach it to the overlay, put this PI at the top of it:
<pre><?xml-stylesheet href="chrome://myextension/skin/toolbar-button.css" type="text/css"?></pre>
 
To attach it to <tt>customizeToolbar.xul</tt>, you may use <tt>skin/contents.rdf</tt>, e.g.:
<pre><?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></pre>
 
Extensions for Firefox/Thunderbird 1.5 should have something like this in [http://developer.mozilla.org/en/docs/Chrome_Registration chrome.manifest] instead:
skin myextension classic/1.0 skin/
style chrome://global/content/customizeToolbar.xul chrome://myextension/skin/toolbar-button.css
 
==Common mistakes==
* Malformed or not applied stylesheet - the whole set of default buttons is painted instead of your own icon on the toolbar or in the Customize Toolbars window.
** '''Solution:''' check if your stylesheet is correct, check if your contents.rdf (or chrome.manifest) is correct, make sure you didn't forget to [[#Applying the stylesheet|apply the stylesheet]] to customizeToolbar.xul.
 
==Example extension==
[http://ihoss.not-a-blog.com/redbutton.php redButton]
Error Note: The link to this page works but the XPI install is missing (404).
 
==The list of commonly overlayed windows with toolbars==
{| border="1" cellpadding="5" rules="all"
! URL !! Application and affected window(s) !! Palette id
|-
| ''chrome://browser/content/browser.xul'' || Firefox - Main window || BrowserToolbarPalette
|-
| ''chrome://messenger/content/messenger.xul'' || Thunderbird - Main window || MailToolbarPalette
|-
| ''chrome://messenger/content/messengercompose/messengercompose.xul'' || Thunderbird - Compose window || MsgComposeToolbarPalette
|-
| ''chrome://editor/content/editor.xul'' || Nvu - Main window || NvuToolbarPalette
|-
|}
 
==More information==
* XulPlanet.com references: [http://xulplanet.com/references/elemref/ref_toolbarbutton.html <code><toolbarbutton></code>], [http://xulplanet.com/references/elemref/ref_toolbaritem.html <code><toolbaritem></code>].
* [http://forums.mozillazine.org/viewtopic.php?t=220220 How to adjust toolbarbutton's label position]
* [http://forums.mozillazine.org/viewtopic.php?t=189667 A forum thread] about adding an item to the toolbar (instead of just adding it to palette) right after an extension is installed. Note that doing this is not recommended.


[[Category:Example code]] [[Category:XUL example code]]
[[Category:Example code]] [[Category:XUL example code]]

Revision as of 12:30, 22 August 2005

This page is part of the extension development documentation project.

Ask your questions in MozillaZine Forums. Also try browsing example code.

Note: development documentation is in process of being moved to Mozilla Development Center (MDC).


Moved

Moved to Devmo: http://developer.mozilla.org/en/docs/Creating_toolbar_buttons