Diff for /books/www/chapters/ch03.html between versions 1.8 and 1.9

version 1.8, 2002/12/04 06:07:15 version 1.9, 2002/12/11 18:57:10
Line 1 Line 1
<HTML>    <style type="text/css">
<HEAD><TITLE>Chapter 3</TITLE></HEAD><BODY BGCOLOR=WHITE><H2>Chapter 3</H2>      div.c11 {font-weight: bold; text-align: center}
<H1><A NAME="77084"></A> XUL Elements and Features</H1>      div.c10 {text-align: center}
<P>The XML-based User-interface Language (XUL) includes all of the basic widgets you need to build application user interfaces. These interfaces include tabs, text areas, buttons, and menus, as well as handy interfaces you may not have thought you needed, such as the <TT>&lt;stack&gt;</TT> widget or <TT>&lt;colorpicker&gt;</TT>.    </style>
<P><A HREF="ch02.html#77048">Chapter 2</A> introduced some of the XUL elements that make up a window and basic applications. This chapter examines 
XUL elements and features in more detail, describing the rationale behind them, their look and behavior, and common usage. Though not     <h2>Chapter 3</h2>
comprehensive, the chapter provides more than enough information about XUL to get you started on building your own Mozilla applications, particularly when used in conjunction with the XUL reference in <A HREF="appc.html#77003">Appendix C</A>.    <h1><a name="77084"></a> XUL Elements and Features</h1>
<P>The elements described here, such as menus, buttons, trees, and boxes, are needed in almost any type of application, and most of the examples are generic, so you can plug them into any application or customize them to your needs. We've packed a lot information in this chapter and it be a useful reference as you begin to develop your applications.    <p>The XML-based User-interface Language (XUL) includes all of
<H2><A NAME="77085"></A> The XUL Document Object</H2>    the basic widgets you need to build application user
<P>At the core of a XUL file  <!--INDEX XUL document object;objects:XUL document object --> is the <TT>document</TT> object. As in HTML, <TT>document</TT> is an object that represents the XUL document itself-the content as opposed to the window that surrounds it. The <TT>document</TT> provides methods for getting individual elements, manipulating the structure of the document, or updating style rules.    interfaces. These interfaces include tabs, text areas, buttons,
<P>A <TT>document</TT> object provides  <!--INDEX getElementById( ) method;methods:getElementById( ) -->  <!--INDEX getElementsByTagName( )     and menus, as well as handy interfaces you may not have thought
method;methods:getElementByTagName( ) -->  <!--INDEX createElement( ) method;methods:createElement( ) -->  <!--INDEX createTextNode( ) method;methods:createTextNode( ) --> methods such as <TT>getElementById</TT>, <TT>getElementsByTagName</TT>, <TT>createElement</TT>, and <TT>createTextNode</TT> for DOM querying and manipulation of the actual document. Further details about the DOM are available in <A HREF="ch05.html#44523">Chapter 5</A>.    you needed, such as the <tt>&lt;stack&gt;</tt> widget or
<P>Other types of <TT>document</TT> objects include the width and height of the window, a <TT>popupNode</TT> property that accesses the elements currently displaying a pop up (a XUL widget that attaches to another widget and appears above it holding some content), a <TT>tooltipNode</TT> property that accesses the element currently displaying a tooltip, and a <TT>documentElement</TT> property that accesses the body of the document:    <tt>&lt;colorpicker&gt;</tt>.</p>
<PRE>var docEl = document.documentElement;    <p><a href="ch02.html#77048">Chapter 2</a> introduced some of
     the XUL elements that make up a window and basic applications.
     This chapter examines XUL elements and features in more detail,
     describing the rationale behind them, their look and behavior,
     and common usage. Though not comprehensive, the chapter
     provides more than enough information about XUL to get you
     started on building your own Mozilla applications, particularly
     when used in conjunction with the XUL reference in <a href=
     "appc.html#77003">Appendix C</a>.</p>
     <p>The elements described here, such as menus, buttons, trees,
     and boxes, are needed in almost any type of application, and
     most of the examples are generic, so you can plug them into any
     application or customize them to your needs. We've packed a lot
     information in this chapter and it be a useful reference as you
     begin to develop your applications.</p>
     <h2><a name="77085"></a> The XUL Document Object</h2>
     <p>At the core of a XUL file 
     <!--INDEX XUL document object;objects:XUL document object -->
     is the <tt>document</tt> object. As in HTML, <tt>document</tt>
     is an object that represents the XUL document itself-the
     content as opposed to the window that surrounds it. The
     <tt>document</tt> provides methods for getting individual
     elements, manipulating the structure of the document, or
     updating style rules.</p>
     <p>A <tt>document</tt> object provides 
     <!--INDEX getElementById( ) method;methods:getElementById( ) -->
     <!--INDEX getElementsByTagName( ) 
     method;methods:getElementByTagName( ) --> 
     <!--INDEX createElement( ) method;methods:createElement( ) --> 
     <!--INDEX createTextNode( ) method;methods:createTextNode( ) -->
     methods such as <tt>getElementById</tt>,
     <tt>getElementsByTagName</tt>, <tt>createElement</tt>, and
     <tt>createTextNode</tt> for DOM querying and manipulation of
     the actual document. Further details about the DOM are
     available in <a href="ch05.html#44523">Chapter 5</a>.</p>
     <p>Other types of <tt>document</tt> objects include the width
     and height of the window, a <tt>popupNode</tt> property that
     accesses the elements currently displaying a pop up (a XUL
     widget that attaches to another widget and appears above it
     holding some content), a <tt>tooltipNode</tt> property that
     accesses the element currently displaying a tooltip, and a
     <tt>documentElement</tt> property that accesses the body of the
     document:</p>
 <pre>
 var docEl = document.documentElement;
 var secondLevelNodes = new Array( );  var secondLevelNodes = new Array( );
 for (var I=0; I&lt;docEl.childNodes.length;I++)  {  for (var I=0; I&lt;docEl.childNodes.length;I++)  {
 secondLevelNodes[I] = docEl.childNodes[i];  secondLevelNodes[I] = docEl.childNodes[i];
}</PRE>}
<P>This example creates an array of all the second-level nodes in relation to the document, and could be extended to walk to the whole tree. Using nodes in the structural representation of the document to get to other nodes in this way allows you to quickly access and change any part of a document with script.</pre>
<P>The <TT>document</TT> object is global only for the particular scope that you are working in, so every window, dialog, and page has its own <TT>document</TT> object. To access it, just use the <TT>document</TT>. prefix followed by the name of the property you want to access:    <p>This example creates an array of all the second-level nodes
<PRE>var title = document.getElementById("bookTitle");</PRE>    in relation to the document, and could be extended to walk to
<P>It is possible to access <TT>document</TT> outside the current scope-for example, the window that opened another one using <TT>window.opener</TT>:    the whole tree. Using nodes in the structural representation of
<PRE>var title = window.opener.document.getElementById("bookTitle");</PRE>    the document to get to other nodes in this way allows you to
<H3><A NAME="77086"></A> XUL Parsing and the Document Object Model</H3>    quickly access and change any part of a document with
<P>Mozilla runs XUL documents  <!--INDEX DOM (Document Object Model):XUL parsing and;XUL (XML-based User-interface Language):parsing, DOM and;parsing:XUL, DOM and --> through the Expat XML parser to check that they are well-formed. Expat is an XML parser library, written in C, that was integrated into Mozilla at the early stages of the code rewrite when the source was made open.    script.</p>
<P>During parsing, a content model based on the Document Object Model (DOM) is built, allowing access to the content in a way that facilitates dynamic manipulation. Once the XML tags are in the correct namespaces, Mozilla parses the document a second time to ensure that XUL tags themselves are valid. If this fails, or if the document does not conform to the syntax rules, an error appears in your window so you can address the problem.    <p>The <tt>document</tt> object is global only for the
<P>The parsing process builds an internal tree structure that can be used as a handle for querying, modifying, and copying documents the structure     particular scope that you are working in, so every window,
represents. <A HREF="ch05.html#44523">Chapter 5</A> describes in more detail the relationship between JavaScript (the main scripting engine used     dialog, and page has its own <tt>document</tt> object. To
in Mozilla) and the DOM, and it goes further with examples of commonly used methods for querying and modifying a XUL document. To view that internal tree, you can use a tool called the DOM Inspector, which is a Mozilla application that lets you view and manipulate the document object model of any XUL file or web page. For more information about the DOM Inspector, see <A HREF="appb.html#78077">Appendix B</A>.    access it, just use the <tt>document</tt>. prefix followed by
<H2><A NAME="77087"></A> Application Windows</H2>    the name of the property you want to access:</p>
<P><TT>&lt;window&gt;</TT> is just one of the  <!--INDEX STARTRANGE--XUL (XML-based User-interface Language):application windows;application windows:XUL;windows:XUL:application windows --> possible root elements of a XUL document, the others being <TT>&lt;overlay&gt;</TT>, <TT>&lt;dialog&gt;</TT>, <TT>&lt;page&gt;</TT>, and <TT>&lt;wizard&gt;</TT>. Overlays play an especially important role in managing and modularizing  <!--INDEX overlay element, XUL -->  <!--INDEX dialog element, XUL -->  <!--INDEX page element, XUL -->  <!--INDEX wizard element, XUL --> the code in your XUL application, so the section <A HREF="#77141">"Overlays</A>," later in this chapter, is dedicated to them.<pre>
<P>The remaining root elements all have the XUL namespace and XUL window attributes and properties. All have a XUL <TT>document</TT> object. Yet, added features exist for each. Which element you choose for the XUL document depends on the purpose of the window. A <TT>&lt;window&gt;</TT> is typically top-level, a <TT>&lt;dialog&gt;</TT> is secondary, appearing above another window, a <TT>&lt;page&gt;</TT> is a document that appears in a frame, and a <TT>&lt;wizard&gt;</TT> stores a set of subsections for loading one at a time through a step-by-step process.var title = document.getElementById("bookTitle");
<H3><A NAME="77088"></A> Dialogs</H3></pre>
<P>Dialogs usually carry out specific functions  <!--INDEX dialogs, application windows (XUL);application windows:XUL:dialogs;XUL (XML-based User-interface Language):application windows:dialogs --> like displaying a message or getting information from the user. The <TT>&lt;dialog&gt;</TT> element was created relatively late in the XUL toolkit development cycle to cater for some special needs of dialog windows, including their position relative to other windows (particularly the main application window) and the existence of buttons for accepting or rejecting a particular operation. A dialog in XUL appears in <A HREF="#77034">Example 3-1</A>.    <p>It is possible to access <tt>document</tt> outside the
    current scope-for example, the window that opened another one
<P><I>Example 3-1: <A NAME="77034"></A></I>    using <tt>window.opener</tt>:</p>
<I>XUL dialog</I><pre>
<PRE> &lt;dialog id="turboDialog" buttons="accept" buttonpack="center"var title = window.opener.document.getElementById("bookTitle");
         xmlns="<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>"</pre>
     <h3><a name="77086"></a> XUL Parsing and the Document Object
     Model</h3>
     <p>Mozilla runs XUL documents 
     <!--INDEX DOM (Document Object Model):XUL parsing and;XUL (XML-based User-interface Language):parsing, DOM and;parsing:XUL, DOM and -->
     through the Expat XML parser to check that they are
     well-formed. Expat is an XML parser library, written in C, that
     was integrated into Mozilla at the early stages of the code
     rewrite when the source was made open.</p>
     <p>During parsing, a content model based on the Document Object
     Model (DOM) is built, allowing access to the content in a way
     that facilitates dynamic manipulation. Once the XML tags are in
     the correct namespaces, Mozilla parses the document a second
     time to ensure that XUL tags themselves are valid. If this
     fails, or if the document does not conform to the syntax rules,
     an error appears in your window so you can address the
     problem.</p>
     <p>The parsing process builds an internal tree structure that
     can be used as a handle for querying, modifying, and copying
     documents the structure represents. <a href=
     "ch05.html#44523">Chapter 5</a> describes in more detail the
     relationship between JavaScript (the main scripting engine used
     in Mozilla) and the DOM, and it goes further with examples of
     commonly used methods for querying and modifying a XUL
     document. To view that internal tree, you can use a tool called
     the DOM Inspector, which is a Mozilla application that lets you
     view and manipulate the document object model of any XUL file
     or web page. For more information about the DOM Inspector, see
     <a href="appb.html#78077">Appendix B</a>.</p>
     <h2><a name="77087"></a> Application Windows</h2>
     <p><tt>&lt;window&gt;</tt> is just one of the 
     <!--INDEX STARTRANGE==XUL (XML-based User-interface Language):application windows;application windows:XUL;windows:XUL:application windows -->
     possible root elements of a XUL document, the others being
     <tt>&lt;overlay&gt;</tt>, <tt>&lt;dialog&gt;</tt>,
     <tt>&lt;page&gt;</tt>, and <tt>&lt;wizard&gt;</tt>. Overlays
     play an especially important role in managing and modularizing 
     <!--INDEX overlay element, XUL --> 
     <!--INDEX dialog element, XUL --> 
     <!--INDEX page element, XUL --> 
     <!--INDEX wizard element, XUL --> the code in your XUL
     application, so the section <a href="#77141">"Overlays</a>,"
     later in this chapter, is dedicated to them.</p>
     <p>The remaining root elements all have the XUL namespace and
     XUL window attributes and properties. All have a XUL
     <tt>document</tt> object. Yet, added features exist for each.
     Which element you choose for the XUL document depends on the
     purpose of the window. A <tt>&lt;window&gt;</tt> is typically
     top-level, a <tt>&lt;dialog&gt;</tt> is secondary, appearing
     above another window, a <tt>&lt;page&gt;</tt> is a document
     that appears in a frame, and a <tt>&lt;wizard&gt;</tt> stores a
     set of subsections for loading one at a time through a
     step-by-step process.</p>
     <h3><a name="77088"></a> Dialogs</h3>
     <p>Dialogs usually carry out specific functions 
     <!--INDEX dialogs, application windows (XUL);application windows:XUL:dialogs;XUL (XML-based User-interface Language):application windows:dialogs -->
     like displaying a message or getting information from the user.
     The <tt>&lt;dialog&gt;</tt> element was created relatively late
     in the XUL toolkit development cycle to cater for some special
     needs of dialog windows, including their position relative to
     other windows (particularly the main application window) and
     the existence of buttons for accepting or rejecting a
     particular operation. A dialog in XUL appears in <a href=
     "#77034">Example 3-1</a>.</p>
     <p><i>Example 3-1: <a name="77034"></a></i> <i>XUL
     dialog</i></p>
 <pre>
  &lt;dialog id="turboDialog" buttons="accept" buttonpack="center"
          xmlns="<a href=
 "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
          title="Empty the Cache"           title="Empty the Cache"
         onunload="SetTurboPref( );"&gt;</PRE>         onunload="SetTurboPref( );"&gt;
</pre>
<P>As you can see, the dialog includes the XUL namespace and the <TT>id</TT> and <TT>title</TT> attributes. However, some attributes, such as <TT>buttons</TT> and <TT>buttonpack</TT>, don't appear in a regular window context.    <p>As you can see, the dialog includes the XUL namespace and
<P>Dialogs commonly require  <!--INDEX buttons:dialogs, XUL --> the user to take some action or make a choice, so the button attributes are provided for this purpose. In addition to <TT>buttons</TT> and <TT>buttonpack</TT>, there are special event handlers on the dialog element-<TT>ondialogaccept</TT>, <TT>ondialogcancel</TT>, and <TT>ondialoghelp-</TT>that correspond to the buttons typically displayed and can execute code in response to user input. As with <TT>onunload</TT>, you can place a function in the <TT>ondialogaccept</TT> event handler that executes when the user clicks the OK button:    the <tt>id</tt> and <tt>title</tt> attributes. However, some
<PRE>&lt;dialog id="flush" buttons="accept" buttonpack="center"    attributes, such as <tt>buttons</tt> and <tt>buttonpack</tt>,
xmlns="<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>"    don't appear in a regular window context.</p>
     <p>Dialogs commonly require <!--INDEX buttons:dialogs, XUL -->
     the user to take some action or make a choice, so the button
     attributes are provided for this purpose. In addition to
     <tt>buttons</tt> and <tt>buttonpack</tt>, there are special
     event handlers on the dialog element-<tt>ondialogaccept</tt>,
     <tt>ondialogcancel</tt>, and <tt>ondialoghelp-</tt>that
     correspond to the buttons typically displayed and can execute
     code in response to user input. As with <tt>onunload</tt>, you
     can place a function in the <tt>ondialogaccept</tt> event
     handler that executes when the user clicks the OK button:</p>
 <pre>
 &lt;dialog id="flush" buttons="accept" buttonpack="center"
 xmlns="<a href=
 "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
 title="&amp;exitWarningTitle.label;"  title="&amp;exitWarningTitle.label;"
ondialogaccept="doCacheFlush( );"&gt;</PRE>ondialogaccept="doCacheFlush( );"&gt;
<H3><A NAME="77089"></A> Pages</H3></pre>
<P>The <TT>&lt;page&gt;</TT> element is  <!--INDEX page element, XUL --> designed specifically for documents that are loaded in a frame of a higher-level document. They are not top-level windows themselves. In Mozilla, the <TT>page</TT> element is used often in the preferences dialog to represent the various preference panels.    <h3><a name="77089"></a> Pages</h3>
<P>As with the dialog in <A HREF="#77034">Example 3-1</A>, the <TT>&lt;page&gt;</TT> element in <A HREF="#77036">Example 3-2</A> includes the familiar namespace attribute (<TT>xmlns</TT>) and load handler (<TT>onload</TT>). The <TT>headertitle</TT> attribute is also used for the top of the page, which itself gets loaded into another window that has its own title.    <p>The <tt>&lt;page&gt;</tt> element is 
    <!--INDEX page element, XUL --> designed specifically for
<P><I>Example 3-2: <A NAME="77036"></A></I>    documents that are loaded in a frame of a higher-level
<I>XUL page</I>    document. They are not top-level windows themselves. In
<PRE> &lt;page xmlns="<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>"    Mozilla, the <tt>page</tt> element is used often in the
     preferences dialog to represent the various preference
     panels.</p>
     <p>As with the dialog in <a href="#77034">Example 3-1</a>, the
     <tt>&lt;page&gt;</tt> element in <a href="#77036">Example
     3-2</a> includes the familiar namespace attribute
     (<tt>xmlns</tt>) and load handler (<tt>onload</tt>). The
     <tt>headertitle</tt> attribute is also used for the top of the
     page, which itself gets loaded into another window that has its
     own title.</p>
     <p><i>Example 3-2: <a name="77036"></a></i> <i>XUL page</i></p>
 <pre>
  &lt;page xmlns="<a href=
 "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
        onload="parent.initPanel('chrome://communicator/content/pref/pref-fonts.xul');"         onload="parent.initPanel('chrome://communicator/content/pref/pref-fonts.xul');"
       headertitle="&amp;lHeader;"&gt;</PRE>       headertitle="&amp;lHeader;"&gt;
</pre>
<P>An application of the <TT> <!--INDEX preferences, page element --> page</TT> element in Mozilla is in the global preferences for the whole suite of Mozilla applications. <A HREF="#77002">Figure 3-1</A> shows the layout of this preferences panel. In <A HREF="#77036">Example 3-2</A>, the entity in the header title, <TT>&amp;lHeader;</TT>, resolves to "Languages" and be displayed above the individual preference panel page.    <p>An application of the <tt>
<P>The main preferences window is a XUL dialog, and the content is split in two. On the left is a tree from an overlay that contains the preference topics, and on the right is a XUL <TT>page</TT> loaded into an <TT>&lt;iframe&gt;</TT>.    <!--INDEX preferences, page element --> page</tt> element in
<PRE>&lt;iframe id="panelFrame" name="panelFrame" style="width:0px" flex="1"/&gt;</PRE>    Mozilla is in the global preferences for the whole suite of
<P><CENTER><IMG SRC="foo.gif"></CENTER>    Mozilla applications. <a href="#77002">Figure 3-1</a> shows the
<P><I>Figure 3-1: <A NAME="77002"></A></I>    layout of this preferences panel. In <a href="#77036">Example
<I>Preferences panel loaded as a page</I>    3-2</a>, the entity in the header title,
    <tt>&amp;lHeader;</tt>, resolves to "Languages" and be
<P>As shown in <A HREF="#77002">Figure 3-1</A>, selecting one of the topics in the left panel changes the page that is loaded into the frame. Although the changeover requires quite a bit of scripting in practice, at a basic level, it is just a case of changing the <TT>src</TT> attribute on the frame:    displayed above the individual preference panel page.</p>
<PRE>document.getElementById("panelFrame").setAttribute("src", "chrome://communicator/content/pref/pref-navigator.xul" );</PRE>    <p>The main preferences window is a XUL dialog, and the content
<H3><A NAME="77090"></A> Wizards</H3>    is split in two. On the left is a tree from an overlay that
<P>This type of window  <!--INDEX application windows:wizards;wizards, application windows --> is designed for a very specific type of functionality-to walk the user through a step-by-step process, with each step represented by a different screen. Using one <TT>window</TT> after another can create inconsistencies, including different sizes and performance issues. These can be especially bad when you try to create an interface that guides the user through a new process, such as setting up an account of some kind. Thus, the <TT>wizard</TT> element was adapted from the wizard paradigm now common in some native toolkits. <A HREF="#77038">Example 3-3</A> shows how Mozilla handles wizard dialogs.    contains the preference topics, and on the right is a XUL
    <tt>page</tt> loaded into an <tt>&lt;iframe&gt;</tt>.</p>
<P><I>Example 3-3: <A NAME="77038"></A></I><pre>
<I>A XUL wizard</I>&lt;iframe id="panelFrame" name="panelFrame" style="width:0px" flex="1"/&gt;
<PRE> &lt;wizard</TD> id="NewAccount" title="Account Set-up"</pre>
     <div class="c10">
       <img src="foo.gif">
     </div>
     <p><i>Figure 3-1: <a name="77002"></a></i> <i>Preferences panel
     loaded as a page</i></p>
     <p>As shown in <a href="#77002">Figure 3-1</a>, selecting one
     of the topics in the left panel changes the page that is loaded
     into the frame. Although the changeover requires quite a bit of
     scripting in practice, at a basic level, it is just a case of
     changing the <tt>src</tt> attribute on the frame:</p>
 <pre>
 document.getElementById("panelFrame").setAttribute("src", "chrome://communicator/content/pref/pref-navigator.xul" );
 </pre>
     <h3><a name="77090"></a> Wizards</h3>
     <p>This type of window 
     <!--INDEX application windows:wizards;wizards, application windows -->
     is designed for a very specific type of functionality-to walk
     the user through a step-by-step process, with each step
     represented by a different screen. Using one <tt>window</tt>
     after another can create inconsistencies, including different
     sizes and performance issues. These can be especially bad when
     you try to create an interface that guides the user through a
     new process, such as setting up an account of some kind. Thus,
     the <tt>wizard</tt> element was adapted from the wizard
     paradigm now common in some native toolkits. <a href=
     "#77038">Example 3-3</a> shows how Mozilla handles wizard
     dialogs.</p>
     <p><i>Example 3-3: <a name="77038"></a></i> <i>A XUL
     wizard</i></p>
 <pre>
  &lt;wizard&lt;/td&gt; id="NewAccount" title="Account Set-up"
      onwizardcancel="return Cancel( );"       onwizardcancel="return Cancel( );"
      onwizardfinish="return Finish( );"       onwizardfinish="return Finish( );"
      onload="onLoad( );"       onload="onLoad( );"
      width="44em" height="30em"       width="44em" height="30em"
     xmlns=<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>     xmlns=<a href=
     xmlns:nc="<A HREF="http://home.netscape.com/NC-rdf">http://home.netscape.com/NC-rdf</A>#"&gt;"http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>
   &lt;wizardpage</TD> id="wPage1" pageid="page-1" label="New Account"     xmlns:nc="<a href=
 "http://home.netscape.com/NC-rdf">http://home.netscape.com/NC-rdf</a>#"&gt;
    &lt;wizardpage&lt;/td&gt; id="wPage1" pageid="page-1" label="New Account"
        onpageshow="return acctNamePageInit( );"         onpageshow="return acctNamePageInit( );"
        onpageadvanced="nextPage(this)"&gt;         onpageadvanced="nextPage(this)"&gt;
      &lt;vbox flex="1"&gt;       &lt;vbox flex="1"&gt;
Line 87  ondialogaccept="doCacheFlush( );"&gt;</P Line 259  ondialogaccept="doCacheFlush( );"&gt;</P
    &lt;/wizardpage&gt;     &lt;/wizardpage&gt;
    &lt;wizardpage id="wPage2"/&gt;     &lt;wizardpage id="wPage2"/&gt;
    &lt;wizardpage id="wPage3"/&gt;     &lt;wizardpage id="wPage3"/&gt;
 &lt;/wizard&gt;</PRE> &lt;/wizard&gt;
</pre>
<P>A <TT>wizardpage</TT> is similar to a <TT>page</TT> because it has a surrounding window into which it is loaded. The difference, as shown in <A HREF="#77038">Example 3-3</A>, is that in the wizard, the pages exist as a set within the  <!--INDEX wizard element, XUL --> window-level <TT>&lt;wizard&gt;</TT> element. Order wizardpages in the sequence you want them to appear on the screen. When the user accepts one page, the next one is loaded. In <A HREF="#77038">Example 3-3</A>, the content of the first page is text and an image, and the other pages define only <TT>id</TT> attributes (though this is exactly how you might set them up if their actual content were overlaid into this wizard at runtime). You can use the wizard code in <A HREF="#77038">Example 3-3</A> by including the <TT>&lt;?xml</TT> <TT>version="1.0"?&gt;</TT> preamble at the top, adding <TT>label</TT> attributes to pages two and three, and seeing the pages advance as you click the buttons that guide the wizard process when  <!--INDEX ENDRANGE--XUL (XML-based User-interface Language):application windows;application windows:XUL;windows:XUL:application windows --> you load the XUL file into the browser.    <p>A <tt>wizardpage</tt> is similar to a <tt>page</tt> because
<H2><A NAME="77091"></A> Application Widgets</H2>    it has a surrounding window into which it is loaded. The
<P>Like most applications,  <!--INDEX STARTRANGE--XUL (XML-based User-interface Language):application widgets;widgets:XUL;application widgets, XUL --> yours may rely on menus and toolbars as part of the basic user interface. Menus and toolbars are common, multipurpose widgets that are familiar to most users. Menus often appear as part of a menu bar that organizes all of the capabilities of the program, or they can be single menus for presenting a simple list of choices. Buttons provide quick access to the most commonly used tasks and help get information back from the user. Beyond these basics, however, XUL provides widgets for creating almost any kind of interface (and the flexibility of Mozilla's presentation layer means you can make even the most prosaic menus look any way you want).    difference, as shown in <a href="#77038">Example 3-3</a>, is
<H3><A NAME="77092"></A> The Toolbox</H3>    that in the wizard, the pages exist as a set within the 
<P>As your applications grow  <!--INDEX toolbox;toolbar;toolbargrippy --> in complexity and provide more services to the user, the toolbox can be a good way to organize menus, toolbars, and other widgets. A <TT>&lt;toolbox&gt;</TT> is a special container for holding one or more toolbars and/or menu bars. A Mozilla toolbar implements a <TT>toolbargrippy</TT> and a box that contains children. The <TT>toolbargrippy</TT> is a bar on the lefthand side used for collapsing and expanding the bar. This useful method allows users to control the space that is available to them onscreen.    <!--INDEX wizard element, XUL --> window-level
<H4><A NAME="77093"></A> Toolbars</H4>    <tt>&lt;wizard&gt;</tt> element. Order wizardpages in the
<P>The <TT>&lt;toolbar&gt;</TT> element shown  <!--INDEX toolbars;toolbar element, XUL --> in <A HREF="#77040">Example 3-4</A> contains buttons used to carry out various application functions. Buttons are the most common children of a toolbar, but they are by no means the only widgets or content you can put in there.    sequence you want them to appear on the screen. When the user
    accepts one page, the next one is loaded. In <a href=
<P><I>Example 3-4: <A NAME="77040"></A></I>    "#77038">Example 3-3</a>, the content of the first page is text
<I>Toolbar with buttons and spacing</I>    and an image, and the other pages define only <tt>id</tt>
<PRE> &lt;toolbox&gt;    attributes (though this is exactly how you might set them up if
     their actual content were overlaid into this wizard at
     runtime). You can use the wizard code in <a href=
     "#77038">Example 3-3</a> by including the <tt>&lt;?xml</tt>
     <tt>version="1.0"?&gt;</tt> preamble at the top, adding
     <tt>label</tt> attributes to pages two and three, and seeing
     the pages advance as you click the buttons that guide the
     wizard process when 
     <!--INDEX ENDRANGE==XUL (XML-based User-interface Language):application windows;application windows:XUL;windows:XUL:application windows -->
     you load the XUL file into the browser.</p>
     <h2><a name="77091"></a> Application Widgets</h2>
     <p>Like most applications, 
     <!--INDEX STARTRANGE==XUL (XML-based User-interface Language):application widgets;widgets:XUL;application widgets, XUL -->
     yours may rely on menus and toolbars as part of the basic user
     interface. Menus and toolbars are common, multipurpose widgets
     that are familiar to most users. Menus often appear as part of
     a menu bar that organizes all of the capabilities of the
     program, or they can be single menus for presenting a simple
     list of choices. Buttons provide quick access to the most
     commonly used tasks and help get information back from the
     user. Beyond these basics, however, XUL provides widgets for
     creating almost any kind of interface (and the flexibility of
     Mozilla's presentation layer means you can make even the most
     prosaic menus look any way you want).</p>
     <h3><a name="77092"></a> The Toolbox</h3>
     <p>As your applications grow 
     <!--INDEX toolbox;toolbar;toolbargrippy --> in complexity and
     provide more services to the user, the toolbox can be a good
     way to organize menus, toolbars, and other widgets. A
     <tt>&lt;toolbox&gt;</tt> is a special container for holding one
     or more toolbars and/or menu bars. A Mozilla toolbar implements
     a <tt>toolbargrippy</tt> and a box that contains children. The
     <tt>toolbargrippy</tt> is a bar on the lefthand side used for
     collapsing and expanding the bar. This useful method allows
     users to control the space that is available to them
     onscreen.</p>
     <h4><a name="77093"></a> Toolbars</h4>
     <p>The <tt>&lt;toolbar&gt;</tt> element shown 
     <!--INDEX toolbars;toolbar element, XUL --> in <a href=
     "#77040">Example 3-4</a> contains buttons used to carry out
     various application functions. Buttons are the most common
     children of a toolbar, but they are by no means the only
     widgets or content you can put in there.</p>
     <p><i>Example 3-4: <a name="77040"></a></i> <i>Toolbar with
     buttons and spacing</i></p>
 <pre>
  &lt;toolbox&gt;
    &lt;toolbar id="fixed-toolbar" class="toolbar-primary"     &lt;toolbar id="fixed-toolbar" class="toolbar-primary"
        tbautostretch="always" persist="collapsed"&gt;         tbautostretch="always" persist="collapsed"&gt;
      &lt;toolbarbutton id="newfileBtn" label="New" oncommand="doNew( );" /&gt;       &lt;toolbarbutton id="newfileBtn" label="New" oncommand="doNew( );" /&gt;
      &lt;toolbarseparator /&gt;       &lt;toolbarseparator /&gt;
      &lt;toolbarbutton id="openfileBtn" label="Open" oncommand="doOpen( );" /&gt;       &lt;toolbarbutton id="openfileBtn" label="Open" oncommand="doOpen( );" /&gt;
     </TD>&lt;spacer flex="1" /&gt;     &lt;/td&gt;&lt;spacer flex="1" /&gt;
    &lt;/toolbar&gt;     &lt;/toolbar&gt;
 &lt;/toolbox&gt;</PRE> &lt;/toolbox&gt;
</pre>
<P>To apply spacing between elements,  <!--INDEX elements:XUL, spacing;XUL (XML-based User-interface Language):elements:spacing -->  <!--INDEX spacer element, XUL --> the <TT>&lt;spacer&gt;</TT> element can be used. In <A HREF="#77040">Example 3-4</A>, all space that remains after the buttons are drawn goes <I>after</I> the buttons because the spacer there is flexible and the buttons are not. Space added elsewhere with other <TT>&lt;spacer&gt;</TT> elements is determined by ratio of the <TT>flex</TT> values on the elements competing for layout space. Extending the toolbar in <A HREF="#77040">Example 3-4</A>, you can add a print button on the far right:    <p>To apply spacing between elements, 
<PRE>&lt;toolbarbutton id="newfileBtn" label="New" oncommand="doNew( );" /&gt;    <!--INDEX elements:XUL, spacing;XUL (XML-based User-interface Language):elements:spacing -->
     <!--INDEX spacer element, XUL --> the <tt>&lt;spacer&gt;</tt>
     element can be used. In <a href="#77040">Example 3-4</a>, all
     space that remains after the buttons are drawn goes
     <i>after</i> the buttons because the spacer there is flexible
     and the buttons are not. Space added elsewhere with other
     <tt>&lt;spacer&gt;</tt> elements is determined by ratio of the
     <tt>flex</tt> values on the elements competing for layout
     space. Extending the toolbar in <a href="#77040">Example
     3-4</a>, you can add a print button on the far right:</p>
 <pre>
 &lt;toolbarbutton id="newfileBtn" label="New" oncommand="doNew( );" /&gt;
 &lt;toolbarseparator /&gt;  &lt;toolbarseparator /&gt;
 &lt;toolbarbutton id="openfileBtn" label="Open" oncommand="doOpen( );" /&gt;  &lt;toolbarbutton id="openfileBtn" label="Open" oncommand="doOpen( );" /&gt;
 &lt;spacer flex="1" /&gt;  &lt;spacer flex="1" /&gt;
&lt;toolbarbutton id="printBtn" label="Print" oncommand="doPrint( );" /&gt;</PRE>&lt;toolbarbutton id="printBtn" label="Print" oncommand="doPrint( );" /&gt;
<P>The <TT>&lt;toolbarseparator&gt;</TT> element does not create additional spacing between the first two <TT>toolbarbuttons</TT>, but there is space between them and the print button, which is pushed to the far right because the <TT>flex</TT> attribute of the spacer in between is set to 1.</pre>
<H4><A NAME="77094"></A> Menu bar</H4>    <p>The <tt>&lt;toolbarseparator&gt;</tt> element does not
<P>Among the other most common  <!--INDEX menu bar;menubar element, XUL --> nested elements within a toolbox is a XUL <TT>&lt;menubar&gt;</TT>. <TT>&lt;menubar&gt;</TT> is a container much like the toolbar that has one or more menus as its children.    create additional spacing between the first two
<PRE>&lt;menubar id="fixed-menubar"&gt;    <tt>toolbarbuttons</tt>, but there is space between them and
     the print button, which is pushed to the far right because the
     <tt>flex</tt> attribute of the spacer in between is set to
     1.</p>
     <h4><a name="77094"></a> Menu bar</h4>
     <p>Among the other most common 
     <!--INDEX menu bar;menubar element, XUL --> nested elements
     within a toolbox is a XUL <tt>&lt;menubar&gt;</tt>.
     <tt>&lt;menubar&gt;</tt> is a container much like the toolbar
     that has one or more menus as its children.</p>
 <pre>
 &lt;menubar id="fixed-menubar"&gt;
 &lt;menu label="Quantity" /&gt;  &lt;menu label="Quantity" /&gt;
 &lt;menu label="Color" /&gt;  &lt;menu label="Color" /&gt;
&lt;/menubar&gt;</PRE>&lt;/menubar&gt;
<BLOCKQUOTE><CENTER><B>WARNING</B></CENTER></pre>
<P>There is one caveat in <TT>menubar</TT> behavior that you should be aware of. On the Mac OS, application menu bars appear at the top of the screen. If you have any nonmenu elements contained in your menu bar widget, they are ignored because the OS does not know how to display them there.<P></BLOCKQUOTE>    <blockquote>
<P>As <A HREF="#77042">Example 3-5</A> illustrates, it's easy to build up a simple application menu and get the intrinsic look and collapsibility of a menu bar with a few simple lines of code:      <div class="c11">
        WARNING
<P><I>Example 3-5: <A NAME="77042"></A></I>      </div>
<I>Application menu bar</I>      <p>There is one caveat in <tt>menubar</tt> behavior that you
<PRE> &lt;?xml version="1.0"?&gt;      should be aware of. On the Mac OS, application menu bars
       appear at the top of the screen. If you have any nonmenu
       elements contained in your menu bar widget, they are ignored
       because the OS does not know how to display them there.</p>
     </blockquote>
     <p>As <a href="#77042">Example 3-5</a> illustrates, it's easy
     to build up a simple application menu and get the intrinsic
     look and collapsibility of a menu bar with a few simple lines
     of code:</p>
     <p><i>Example 3-5: <a name="77042"></a></i> <i>Application menu
     bar</i></p>
 <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;window   &lt;window
    xmlns="<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>"&gt;    xmlns="<a href=
 "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"&gt;
  &lt;menubar id="appbar"&gt;   &lt;menubar id="appbar"&gt;
    &lt;menu label="File"&gt;     &lt;menu label="File"&gt;
       &lt;menupopup&gt;        &lt;menupopup&gt;
Line 140  ondialogaccept="doCacheFlush( );"&gt;</P Line 393  ondialogaccept="doCacheFlush( );"&gt;</P
    &lt;/menu&gt;     &lt;/menu&gt;
    &lt;menu label="Edit" /&gt;     &lt;menu label="Edit" /&gt;
  &lt;/menubar&gt;   &lt;/menubar&gt;
 &lt;/window&gt;</PRE> &lt;/window&gt;
</pre>
<P>The complete XUL file in <A HREF="#77042">Example 3-5</A> produces the menu bar in <A HREF="#77004">Figure 3-2</A>.    <p>The complete XUL file in <a href="#77042">Example 3-5</a>
<P><CENTER><IMG SRC="foo.gif"></CENTER>    produces the menu bar in <a href="#77004">Figure 3-2</a>.</p>
<P><I>Figure 3-2: <A NAME="77004"></A></I>    <div class="c10">
<I>Application menu bar</I>      <img src="foo.gif">
    </div>
<H3><A NAME="77095"></A> Selection Lists</H3>    <p><i>Figure 3-2: <a name="77004"></a></i> <i>Application menu
<P>There are a number of ways to  <!--INDEX lists;selection lists --> create lists in Mozilla. This section provides three alternative ways of presenting the same choices to the user. The options are illustrated in <A HREF="#77006">Figure 3-3</A>. The one thing these three selection list widgets-<I>menus</I>, <I>pop ups</I>, and <I>menu lists-</I>have in common is they all use menu items to display individual choices:    bar</i></p>
<PRE>&lt;menuitem label="Tachinidae"   oncommand="changeF(1)"/&gt;    <h3><a name="77095"></a> Selection Lists</h3>
     <p>There are a number of ways to 
     <!--INDEX lists;selection lists --> create lists in Mozilla.
     This section provides three alternative ways of presenting the
     same choices to the user. The options are illustrated in <a
     href="#77006">Figure 3-3</a>. The one thing these three
     selection list widgets-<i>menus</i>, <i>pop ups</i>, and
     <i>menu lists-</i>have in common is they all use menu items to
     display individual choices:</p>
 <pre>
 &lt;menuitem label="Tachinidae"   oncommand="changeF(1)"/&gt;
 &lt;menuitem label="Tanyderidae"   oncommand="changeF(2)"/&gt;  &lt;menuitem label="Tanyderidae"   oncommand="changeF(2)"/&gt;
 &lt;menuitem label="Tipulidae"   oncommand="changeF(3)"/&gt;  &lt;menuitem label="Tipulidae"   oncommand="changeF(3)"/&gt;
 &lt;menuitem label="Syrphidae"   oncommand="changeF(4)"/&gt;  &lt;menuitem label="Syrphidae"   oncommand="changeF(4)"/&gt;
&lt;menuitem label="Tephritidae"   oncommand="changeF(5)"/&gt;</PRE>&lt;menuitem label="Tephritidae"   oncommand="changeF(5)"/&gt;
<P>When you wrap the <TT>menuitem</TT> elements above in a menu, a menu list, and a pop-up window, you see the variations in <A HREF="#77006">Figure 3-3</A>.</pre>
<P><CENTER><IMG SRC="foo.gif"></CENTER>    <p>When you wrap the <tt>menuitem</tt> elements above in a
<P><I>Figure 3-3: <A NAME="77006"></A></I>    menu, a menu list, and a pop-up window, you see the variations
<I>Visual comparison of menu widgets</I>    in <a href="#77006">Figure 3-3</a>.</p>
    <div class="c10">
<H4><A NAME="77096"></A> Menus</H4>      <img src="foo.gif">
<P>Menus are much more flexible  <!--INDEX lists:menus;selection lists:menus;menus --> than they first appear to be. They can appear anywhere in the UI, for one thing, and needn't be stuck at the top of the window. They can be in buttons, trees, or just out on their own. <A HREF="#77044">Example 3-6</A> shows the basic structure of a menu.    </div>
    <p><i>Figure 3-3: <a name="77006"></a></i> <i>Visual comparison
<P><I>Example 3-6: <A NAME="77044"></A></I>    of menu widgets</i></p>
<I>A sample menu</I>    <h4><a name="77096"></a> Menus</h4>
<PRE> &lt;menu label="Quantity"&gt;    <p>Menus are much more flexible 
     <!--INDEX lists:menus;selection lists:menus;menus --> than they
     first appear to be. They can appear anywhere in the UI, for one
     thing, and needn't be stuck at the top of the window. They can
     be in buttons, trees, or just out on their own. <a href=
     "#77044">Example 3-6</a> shows the basic structure of a
     menu.</p>
     <p><i>Example 3-6: <a name="77044"></a></i> <i>A sample
     menu</i></p>
 <pre>
  &lt;menu label="Quantity"&gt;
    &lt;menupopup&gt;     &lt;menupopup&gt;
      &lt;!-- menuitems here --&gt;       &lt;!-- menuitems here --&gt;
    &lt;/menupopup&gt;     &lt;/menupopup&gt;
 &lt;/menu&gt;</PRE> &lt;/menu&gt;
</pre>
<P>There is a rigid ordering of nesting in a menu. A menu contains a <TT>&lt;menupopup&gt;</TT>, which in turn contains one or more menu items. Optionally, you can segregate groups of menu items by using a <TT>&lt;menuseparator&gt;</TT> in the pop up, which draws a thin line between items.    <p>There is a rigid ordering of nesting in a menu. A menu
<H4><A NAME="77097"></A> Pop ups</H4>    contains a <tt>&lt;menupopup&gt;</tt>, which in turn contains
<P>The pop up manifests as either  <!--INDEX lists:pop ups;selection lists:pop ups;pop ups;menupopup element, XUL --> a <TT>&lt;menupopup&gt;</TT> or a <TT>&lt;popup&gt;</TT> element. The latter can be used in a number of different ways, but <A HREF="#77046">Example 3-7</A> focuses on its common use in context menus.    one or more menu items. Optionally, you can segregate groups of
    menu items by using a <tt>&lt;menuseparator&gt;</tt> in the pop
<P><I>Example 3-7: <A NAME="77046"></A></I>    up, which draws a thin line between items.</p>
<I>Context menu using pop up</I>    <h4><a name="77097"></a> Pop ups</h4>
<PRE> &lt;popup id="FlyContext"    <p>The pop up manifests as either 
     <!--INDEX lists:pop ups;selection lists:pop ups;pop ups;menupopup element, XUL -->
     a <tt>&lt;menupopup&gt;</tt> or a <tt>&lt;popup&gt;</tt>
     element. The latter can be used in a number of different ways,
     but <a href="#77046">Example 3-7</a> focuses on its common use
     in context menus.</p>
     <p><i>Example 3-7: <a name="77046"></a></i> <i>Context menu
     using pop up</i></p>
 <pre>
  &lt;popup id="FlyContext"
      onpopupshowing="return doThis( );"       onpopupshowing="return doThis( );"
      onpopuphiding=" return doThat( );"&gt;       onpopuphiding=" return doThat( );"&gt;
    &lt;!-- menuitems here --&gt;     &lt;!-- menuitems here --&gt;
 &lt;/popup&gt;</PRE> &lt;/popup&gt;
</pre>
<P>A couple of extra steps are needed to prepare a context pop up for activation. First, you must attach the <TT>popup</TT> element to a widget in the UI by using the <TT>id</TT> of the pop up that must correspond to the <TT>context</TT> of the widget:    <p>A couple of extra steps are needed to prepare a context pop
<PRE>&lt;toolbar id="main-toolbar" context="FlyContext" /&gt;</PRE>    up for activation. First, you must attach the <tt>popup</tt>
<P>When the toolbar is clicked, the pop up that corresponds to that value appears. You can have some script execute when you show and/or hide the pop up by using the <TT>onpopupshowing</TT> and <TT>onpopuphiding</TT> methods, as when you show and hide items in a dynamic menu.    element to a widget in the UI by using the <tt>id</tt> of the
<P>The second step includes the pop up in a set of pop ups, enclosed in a <TT>&lt;popupset&gt;</TT> element. Though not strictly necessary as a container for pop ups, the pop-up set helps organize the free-floating<A NAME="b314"></A><A HREF="#314">[*]</A> pop-up windows in your application and makes it easy to overlay them or overlay into them as the situation requires.    pop up that must correspond to the <tt>context</tt> of the
<H4><A NAME="77098"></A> Menu lists</H4>    widget:</p>
<P>Another manifestation of the pop  <!--INDEX lists:menu lists;selection lists:menu lists;menu lists;menulist element, XUL --> up is in the use of menu lists. A menu list is a choice of options presented to solicit a single choice, usually in the form of a drop-down menu, for which XUL provides the <TT>&lt;menulist&gt;</TT> element. <A HREF="#77048">Example 3-8</A> presents a straightforward menu list with a selection of items to choose from. As in the other pop-up examples, selecting an item executes the code defined in the <TT>oncommand</TT> event handler for that item (e.g., <TT>changeF(1)</TT> for the menu item "Tachinidae").<pre>
&lt;toolbar id="main-toolbar" context="FlyContext" /&gt;
<P><I>Example 3-8: <A NAME="77048"></A></I></pre>
<I>XUL menu list</I>    <p>When the toolbar is clicked, the pop up that corresponds to
<PRE> &lt;menulist id="FlyInput"&gt;    that value appears. You can have some script execute when you
     show and/or hide the pop up by using the
     <tt>onpopupshowing</tt> and <tt>onpopuphiding</tt> methods, as
     when you show and hide items in a dynamic menu.</p>
     <p>The second step includes the pop up in a set of pop ups,
     enclosed in a <tt>&lt;popupset&gt;</tt> element. Though not
     strictly necessary as a container for pop ups, the pop-up set
     helps organize the free-floating<a name="b314"></a><a href=
     "#314">[*]</a> pop-up windows in your application and makes it
     easy to overlay them or overlay into them as the situation
     requires.</p>
     <h4><a name="77098"></a> Menu lists</h4>
     <p>Another manifestation of the pop 
     <!--INDEX lists:menu lists;selection lists:menu lists;menu lists;menulist element, XUL -->
     up is in the use of menu lists. A menu list is a choice of
     options presented to solicit a single choice, usually in the
     form of a drop-down menu, for which XUL provides the
     <tt>&lt;menulist&gt;</tt> element. <a href="#77048">Example
     3-8</a> presents a straightforward menu list with a selection
     of items to choose from. As in the other pop-up examples,
     selecting an item executes the code defined in the
     <tt>oncommand</tt> event handler for that item (e.g.,
     <tt>changeF(1)</tt> for the menu item "Tachinidae").</p>
     <p><i>Example 3-8: <a name="77048"></a></i> <i>XUL menu
     list</i></p>
 <pre>
  &lt;menulist id="FlyInput"&gt;
    &lt;menupopup&gt;     &lt;menupopup&gt;
      &lt;!-- menuitems here --&gt;       &lt;!-- menuitems here --&gt;
    &lt;/menupopup&gt;     &lt;/menupopup&gt;
 &lt;/menulist&gt;</PRE> &lt;/menulist&gt;
</pre>
<P>The <TT>menulist</TT> widget provides functionality beyond that of a regular menu. The menu list can be made editable when the user should be allowed to enter a value not represented in the menu items. In this case, the <TT>menulist</TT> element definition in <A HREF="#77048">Example 3-8</A> would change to something such as:    <p>The <tt>menulist</tt> widget provides functionality beyond
<PRE>&lt;menulist id="FlyInput" editable="true"    that of a regular menu. The menu list can be made editable when
     the user should be allowed to enter a value not represented in
     the menu items. In this case, the <tt>menulist</tt> element
     definition in <a href="#77048">Example 3-8</a> would change to
     something such as:</p>
 <pre>
 &lt;menulist id="FlyInput" editable="true"
 oninput="onInputFly( );"  oninput="onInputFly( );"
onchange="onChangeFly( );"&gt;</PRE>onchange="onChangeFly( );"&gt;
<P>A <TT>true</TT> value on the <TT>editable</TT> attribute allows input in the list. Input can be validated immediately by using the <TT>oninput</TT> attribute. The addition of the <TT>onchange</TT> attribute can be used to carry out an extra  <!--INDEX ENDRANGE--XUL (XML-based User-interface Language):application widgets;widgets:XUL;application widgets, XUL --> script when a new selection is made.</pre>
<H2><A NAME="77099"></A> Tabular and Hierarchical Information</H2>    <p>A <tt>true</tt> value on the <tt>editable</tt> attribute
<P>Many options exist to display hierarchical  <!--INDEX STARTRANGE--tabular information;hierarchical information --> information in your user interface. The most common are tree-like and table-like structures, both of which are represented by elements in Mozilla's XPFE toolkit. In this section, we look at list boxes, trees, and grids. With the exception of the tree, these elements are not limited in regard to the content they can contain. Currently, the tree only holds text and image content and grids are designed for holding the more diverse content as shown in upcoming examples.    allows input in the list. Input can be validated immediately by
<H3><A NAME="77100"></A> List Boxes</H3>    using the <tt>oninput</tt> attribute. The addition of the
<P><TT>&lt;listbox&gt;</TT> is used to display  <!--INDEX tabular information:list boxes;list boxes;listbox element, XUL --> tabular data. <A HREF="#77050">Example 3-9</A> shows a <TT>listbox</TT> widget with all the basic features, including the definition of the number of columns (<TT>listcol</TT>), the <TT>listbox</TT> header (<TT>listhead</TT>), and a list item (<TT>listitem</TT>).    <tt>onchange</tt> attribute can be used to carry out an extra 
    <!--INDEX ENDRANGE==XUL (XML-based User-interface Language):application widgets;widgets:XUL;application widgets, XUL -->
<P><I>Example 3-9: <A NAME="77050"></A></I>    script when a new selection is made.</p>
<I>Listbox widget</I>    <h2><a name="77099"></a> Tabular and Hierarchical
<PRE> &lt;listbox rows="5" class="list" id="FlyTree" onselect="SelectFly( )"&gt;    Information</h2>
     <p>Many options exist to display hierarchical 
     <!--INDEX STARTRANGE==tabular information;hierarchical information -->
     information in your user interface. The most common are
     tree-like and table-like structures, both of which are
     represented by elements in Mozilla's XPFE toolkit. In this
     section, we look at list boxes, trees, and grids. With the
     exception of the tree, these elements are not limited in regard
     to the content they can contain. Currently, the tree only holds
     text and image content and grids are designed for holding the
     more diverse content as shown in upcoming examples.</p>
     <h3><a name="77100"></a> List Boxes</h3>
     <p><tt>&lt;listbox&gt;</tt> is used to display 
     <!--INDEX tabular information:list boxes;list boxes;listbox element, XUL -->
     tabular data. <a href="#77050">Example 3-9</a> shows a
     <tt>listbox</tt> widget with all the basic features, including
     the definition of the number of columns (<tt>listcol</tt>), the
     <tt>listbox</tt> header (<tt>listhead</tt>), and a list item
     (<tt>listitem</tt>).</p>
     <p><i>Example 3-9: <a name="77050"></a></i> <i>Listbox
     widget</i></p>
 <pre>
  &lt;listbox rows="5" class="list" id="FlyTree" onselect="SelectFly( )"&gt;
    &lt;listcols&gt;     &lt;listcols&gt;
      &lt;listcol flex="1"/&gt;       &lt;listcol flex="1"/&gt;
      &lt;splitter class="tree-splitter"/&gt;       &lt;splitter class="tree-splitter"/&gt;
Line 224  onchange="onChangeFly( );"&gt;</PRE> Line 560  onchange="onChangeFly( );"&gt;</PRE>
      &lt;listcell label="flower" /&gt;       &lt;listcell label="flower" /&gt;
    &lt;/listitem&gt;     &lt;/listitem&gt;
    &lt;!-- More Items --&gt;     &lt;!-- More Items --&gt;
 &lt;/listbox&gt;</PRE> &lt;/listbox&gt;
</pre>
<P>The first thing of note in the markup in <A HREF="#77050">Example 3-9</A> is the rules for the nesting of elements within a <TT>listbox</TT> structure. The number of columns needs to be set, each with a <TT>&lt;listcol&gt;</TT> element, and all have to be wrapped in a <TT>&lt;listcols&gt;</TT> set. <A HREF="#77050">Example 3-9</A> has two columns. They are separated by a draggable <TT>grippy</TT> item, which also acts as a column separator in the header row. The cells for those columns are contained in a <TT>&lt;listitem&gt;</TT> grouping. The header is optional and has the same structure as a list item. Once you've put a hierarchy like this in place, you can put the content you want into the tabular structure.    <p>The first thing of note in the markup in <a href=
<BLOCKQUOTE><CENTER><B>NOTE</B></CENTER>    "#77050">Example 3-9</a> is the rules for the nesting of
<P>The <TT>listbox</TT> does not support multilevel/nested rows. Also note that the class attribute example above is what gives the tree much of its particular appearance. Listboxes and trees often use class-based style rules for their appearance and positioning (e.g., the column splitter in <A HREF="#77050">Example 3-9</A>).<P></BLOCKQUOTE>    elements within a <tt>listbox</tt> structure. The number of
<P><A HREF="#77050">Example 3-9</A> creates the listbox in <A HREF="#77008">Figure 3-4</A>.    columns needs to be set, each with a <tt>&lt;listcol&gt;</tt>
<P><CENTER><IMG SRC="foo.gif"></CENTER>    element, and all have to be wrapped in a
<P><I>Figure 3-4: <A NAME="77008"></A></I>    <tt>&lt;listcols&gt;</tt> set. <a href="#77050">Example 3-9</a>
<I>Listbox</I>    has two columns. They are separated by a draggable
    <tt>grippy</tt> item, which also acts as a column separator in
<H3><A NAME="77101"></A> High Performance Trees</H3>    the header row. The cells for those columns are contained in a
<P>The <TT>&lt;listbox&gt;</TT> widget is  <!--INDEX trees;tree element, XUL --> suitable only for certain kinds of content. For better scalability and multilevel capabilities, the <TT>&lt;tree&gt;</TT> was created. <TT>&lt;tree&gt;</TT> is an advanced tree widget that was originally designed for  <!--INDEX Mail/News component --> the Mail/News component in Mozilla. In its first incarnation, it was called the outliner widget.    <tt>&lt;listitem&gt;</tt> grouping. The header is optional and
<P>The tree is designed for high performance in large lists, such as newsgroups, message folders, and other applications where the volume of data is expected to be high. The tree widget has a simpler, more lightweight layout, but it is more difficult to use, requiring the addition of special "views" in order to display data.    has the same structure as a list item. Once you've put a
<H4><A NAME="77102"></A> Tree features</H4>    hierarchy like this in place, you can put the content you want
<P>The implementation of the tree widget is unique  <!--INDEX trees:features --> in the XUL universe in that it displays its content only when it comes into view, which makes it very efficient for long lists of data. <A HREF="#77026">Table 3-1</A> lists some of the main features of the tree.    into the tabular structure.</p>
    <blockquote>
<P><I>Table 3-1: <A NAME="77026"></A></I>      <div class="c11">
<I>Main features of the tree</I>        NOTE
<P><TABLE WIDTH=100% BORDER=1><TR><TD><B>  Row features</B></TD> <TD><B>  Column features</B></TD> <TD><B>  Visual features</B></TD></TR>      </div>
<TR><TD>  Plain or hierarchical rows</TD>     <TD>  Multicolumn</TD>     <TD>  Each cell can display an image preceding text</TD></TR>      <p>The <tt>listbox</tt> does not support multilevel/nested
<TR><TD>  Multiselection based on selection ranges</TD>     <TD>  Resizing using mouse dragging</TD>     <TD>  Look of each element (row, cell, image, etc.) is defined in CSS</TD></TR>      rows. Also note that the class attribute example above is
<TR><TD>  Drag and drop, either on a row or in between rows</TD>     <TD>  Column hiding using pop-up menu in top-right corner</TD>     <TD>  Appearance of the drop feedback during drag-and-drop can be styled</TD></TR></TABLE><P>      what gives the tree much of its particular appearance.
        <TD>  Reordering using drag-and-drop</TD>       <TD>  Spring loaded containers that open after hovering over a closed container for a second</TD>      Listboxes and trees often use class-based style rules for
        <TD>  Sorting by clicking on a column header; custom views can implement their own sorting</TD>       their appearance and positioning (e.g., the column splitter
      in <a href="#77050">Example 3-9</a>).</p>
<P>Even with this rich set of features, however, a <TT>tree</TT> can display only text and image content. The <TT>listbox</TT> is more flexible in the type of content that appears in its cells.    </blockquote>
<H4><A NAME="77103"></A> Tree views</H4>    <p><a href="#77050">Example 3-9</a> creates the listbox in <a
<P>In the tree widget, a <I>view</I> is a model for the  <!--INDEX trees:views -->  <!--INDEX views, tree views --> population and display of data. The view is a flexible feature of the tree that can handle everything from simple data in a content view to more dynamic data from a custom view or an RDF datasource (builder view). <A HREF="#77028">Table 3-2</A> shows the main features of each, using general categories of datasource, speed, and type of usage.    href="#77008">Figure 3-4</a>.</p>
    <div class="c10">
<P><I>Table 3-2: <A NAME="77028"></A></I>      <img src="foo.gif">
<I>Tree views</I>    </div>
<P><TABLE WIDTH=100% BORDER=1><TR><TD><B>  Content view</B></TD> <TD><B>  Builder view</B></TD> <TD><B>  Custom view</B></TD></TR>    <p><i>Figure 3-4: <a name="77008"></a></i> <i>Listbox</i></p>
<TR><TD>  Rows are built from a content model.</TD>     <TD>  Rows are built from an RDF datasource.</TD>     <TD>  Consumer provides its own tree view implementation.</TD></TR>    <h3><a name="77101"></a> High Performance Trees</h3>
<TR><TD>  Fast but not as memory efficient (bigger footprint).</TD>     <TD>  Still fast and efficient.</TD>     <TD>  The fastest and most efficient way.</TD></TR>    <p>The <tt>&lt;listbox&gt;</tt> widget is 
<TR><TD>  Suitable for small trees; easiest to use.</TD>     <TD>  Relatively easy to use.</TD>     <TD>  Most difficult to implement.</TD></TR></TABLE><P>    <!--INDEX trees;tree element, XUL --> suitable only for certain
    kinds of content. For better scalability and multilevel
<P>As already mentioned, the <TT>tree</TT> is used in the Mail/News thread pane, but there are plenty of other places to look for it in Mozilla. Custom views and tree widgets are implemented for the Address Book results, JS Debugger, DOM Inspector, Bookmarks, and for autocomplete. You can see builder views in History and a content view implementation in Preferences.    capabilities, the <tt>&lt;tree&gt;</tt> was created.
<H4><A NAME="77104"></A> The tree content model</H4>    <tt>&lt;tree&gt;</tt> is an advanced tree widget that was
<P>The content in a tree is  <!--INDEX trees:content model;content model, trees;treecols element, XUL --> defined  <!--INDEX treecol element, XUL --> with <TT>&lt;tree&gt;</TT>, <TT>&lt;treecols&gt;</TT>, <TT>&lt;treecol&gt;</TT>, and <TT>&lt;treechildren&gt;</TT> tags. <A HREF="#77052">Example 3-10</A> shows a basic column number definition (two in this instance) and a <TT>treechildren</TT> placeholder that defines the tree body.    originally designed for <!--INDEX Mail/News component --> the
    Mail/News component in Mozilla. In its first incarnation, it
Example 3-10<A NAME="77052"></A>    was called the outliner widget.</p>
<I>Tree base model</I>    <p>The tree is designed for high performance in large lists,
<PRE> &lt;tree id="tree" flex="1"&gt;    such as newsgroups, message folders, and other applications
     where the volume of data is expected to be high. The tree
     widget has a simpler, more lightweight layout, but it is more
     difficult to use, requiring the addition of special "views" in
     order to display data.</p>
     <h4><a name="77102"></a> Tree features</h4>
     <p>The implementation of the tree widget is unique 
     <!--INDEX trees:features --> in the XUL universe in that it
     displays its content only when it comes into view, which makes
     it very efficient for long lists of data. <a href=
     "#77026">Table 3-1</a> lists some of the main features of the
     tree.</p>
     <p><i>Table 3-1: <a name="77026"></a></i> <i>Main features of
     the tree</i></p>
     <table width="100%" border="1">
       <tr>
         <td><b>Row features</b></td>
         <td><b>Column features</b></td>
         <td><b>Visual features</b></td>
       </tr>
       <tr>
         <td>Plain or hierarchical rows</td>
         <td>Multicolumn</td>
         <td>Each cell can display an image preceding text</td>
       </tr>
       <tr>
         <td>Multiselection based on selection ranges</td>
         <td>Resizing using mouse dragging</td>
         <td>Look of each element (row, cell, image, etc.) is
         defined in CSS</td>
       </tr>
       <tr>
         <td>Drag and drop, either on a row or in between rows</td>
         <td>Column hiding using pop-up menu in top-right
         corner</td>
         <td>Appearance of the drop feedback during drag-and-drop
         can be styled</td>
       </tr>
     </table>
     <p>Even with this rich set of features, however, a
     <tt>tree</tt> can display only text and image content. The
     <tt>listbox</tt> is more flexible in the type of content that
     appears in its cells.</p>
     <h4><a name="77103"></a> Tree views</h4>
     <p>In the tree widget, a <i>view</i> is a model for the 
     <!--INDEX trees:views --> <!--INDEX views, tree views -->
     population and display of data. The view is a flexible feature
     of the tree that can handle everything from simple data in a
     content view to more dynamic data from a custom view or an RDF
     datasource (builder view). <a href="#77028">Table 3-2</a> shows
     the main features of each, using general categories of
     datasource, speed, and type of usage.</p>
     <p><i>Table 3-2: <a name="77028"></a></i> <i>Tree views</i></p>
     <table>
       <tr>
         <td>Reordering using drag-and-drop</td>
         <td>Spring loaded containers that open after hovering over
         a closed container for a second</td>
         <td>Sorting by clicking on a column header; custom views
         can implement their own sorting</td>
       </tr>
       <tr>
         <td><b>Content view</b></td>
         <td><b>Builder view</b></td>
         <td><b>Custom view</b></td>
       </tr>
       <tr>
         <td>Rows are built from a content model.</td>
         <td>Rows are built from an RDF datasource.</td>
         <td>Consumer provides its own tree view
         implementation.</td>
       </tr>
       <tr>
         <td>Fast but not as memory efficient (bigger
         footprint).</td>
         <td>Still fast and efficient.</td>
         <td>The fastest and most efficient way.</td>
       </tr>
       <tr>
         <td>Suitable for small trees; easiest to use.</td>
         <td>Relatively easy to use.</td>
         <td>Most difficult to implement.</td>
       </tr>
     </table>
     <p>As already mentioned, the <tt>tree</tt> is used in the
     Mail/News thread pane, but there are plenty of other places to
     look for it in Mozilla. Custom views and tree widgets are
     implemented for the Address Book results, JS Debugger, DOM
     Inspector, Bookmarks, and for autocomplete. You can see builder
     views in History and a content view implementation in
     Preferences.</p>
     <h4><a name="77104"></a> The tree content model</h4>
     <p>The content in a tree is 
     <!--INDEX trees:content model;content model, trees;treecols element, XUL -->
     defined <!--INDEX treecol element, XUL --> with
     <tt>&lt;tree&gt;</tt>, <tt>&lt;treecols&gt;</tt>,
     <tt>&lt;treecol&gt;</tt>, and <tt>&lt;treechildren&gt;</tt>
     tags. <a href="#77052">Example 3-10</a> shows a basic column
     number definition (two in this instance) and a
     <tt>treechildren</tt> placeholder that defines the tree body.
     Example 3-10<a name="77052"></a> <i>Tree base model</i></p>
 <pre>
  &lt;tree id="tree" flex="1"&gt;
    &lt;treecols&gt;     &lt;treecols&gt;
      &lt;treecol id="Col1" label="Col1" flex="1"/&gt;       &lt;treecol id="Col1" label="Col1" flex="1"/&gt;
      &lt;treecol id="Col2" label="Col1" flex="1"/&gt;       &lt;treecol id="Col2" label="Col1" flex="1"/&gt;
    &lt;/treecols&gt;     &lt;/treecols&gt;
    &lt;treechildren/&gt;     &lt;treechildren/&gt;
 &lt;/tree&gt;</PRE> &lt;/tree&gt;
</pre>
<P>As in the <TT>listbox</TT>, a well-defined hierarchy of elements has to be observed. This hierarchy is part of the content model for a tree. The organization of content within a tree enforced by the specific tree elements is listed below.    <p>As in the <tt>listbox</tt>, a well-defined hierarchy of
<BLOCKQUOTE><CENTER><B>NOTE</B></CENTER>    elements has to be observed. This hierarchy is part of the
<P>Unlike <TT>listbox</TT>, nested children are possible for multilevel trees. An example of nested children appears later in this chapter in <A HREF="#77054">Example 3-11</A>.<P></BLOCKQUOTE>    content model for a tree. The organization of content within a
<DL><DT>&lt;treeitem&gt;    tree enforced by the specific tree elements is listed
<DD>This element contains a  <!--INDEX treeitem element, XUL --> single top-level row and all its descendants. The <TT>container</TT> attribute is used to mark this row as a container and is optional. The <TT>open</TT> attribute is used for expanded containers.<P>    below.</p>
<DT>&lt;treerow&gt;    <blockquote>
<DD>The row is contained in the <TT> <!--INDEX treeitem element, XUL --> &lt;treeitem&gt;</TT> element. You may optionally set the <TT>properties</TT> attribute on the <TT>&lt;treerow&gt;</TT> to a whitespace-separated list of properties.<P>      <div class="c11">
<DT>&lt;treeseparator&gt;        NOTE
<DD>A special element used to draw  <!--INDEX treerow element, XUL --> a horizontal separating line. The <TT>properties</TT> attribute is used to compute the properties that apply to the separator.<P>      </div>
<DT>&lt;treecell&gt;      <p>Unlike <tt>listbox</tt>, nested children are possible for
<DD>The <TT> <!--INDEX treecell element, XUL --> &lt;treecell&gt;</TT> element must appear within the <TT>&lt;treerow&gt;</TT> element. It specifies the text and properties that apply for a cell. The <TT>label</TT> attribute is used to set the text for the cell. The optional <TT>properties</TT> attribute is used to compute the properties that apply to the cell. The <TT>ref</TT> attribute correlates a cell within an <TT>&lt;treerow&gt;</TT> to the column in the <TT>tree</TT> and is optional.<P></DL>      multilevel trees. An example of nested children appears later
<P>Tying the concepts presented in this section together allows us to present <A HREF="#77054">Example 3-11</A>, which shows a multilevel <TT>tree</TT> with two columns and two top-level rows.      in this chapter in <a href="#77054">Example 3-11</a>.</p>
    </blockquote>
Example 3-11<A NAME="77054"></A>    <dl>
<I>Multilevel tree content view</I>      <dt>&lt;treeitem&gt;</dt>
<PRE> &lt;tree id="tree" hidecolumnpicker="true" flex="1"&gt;      <dd>This element contains a 
       <!--INDEX treeitem element, XUL --> single top-level row and
       all its descendants. The <tt>container</tt> attribute is used
       to mark this row as a container and is optional. The
       <tt>open</tt> attribute is used for expanded containers.</dd>
       <dt>&lt;treerow&gt;</dt>
       <dd>The row is contained in the <tt>
       <!--INDEX treeitem element, XUL --> &lt;treeitem&gt;</tt>
       element. You may optionally set the <tt>properties</tt>
       attribute on the <tt>&lt;treerow&gt;</tt> to a
       whitespace-separated list of properties.</dd>
       <dt>&lt;treeseparator&gt;</dt>
       <dd>A special element used to draw 
       <!--INDEX treerow element, XUL --> a horizontal separating
       line. The <tt>properties</tt> attribute is used to compute
       the properties that apply to the separator.</dd>
       <dt>&lt;treecell&gt;</dt>
       <dd>The <tt><!--INDEX treecell element, XUL -->
       &lt;treecell&gt;</tt> element must appear within the
       <tt>&lt;treerow&gt;</tt> element. It specifies the text and
       properties that apply for a cell. The <tt>label</tt>
       attribute is used to set the text for the cell. The optional
       <tt>properties</tt> attribute is used to compute the
       properties that apply to the cell. The <tt>ref</tt> attribute
       correlates a cell within an <tt>&lt;treerow&gt;</tt> to the
       column in the <tt>tree</tt> and is optional.</dd>
     </dl>
     <p>Tying the concepts presented in this section together allows
     us to present <a href="#77054">Example 3-11</a>, which shows a
     multilevel <tt>tree</tt> with two columns and two top-level
     rows. Example 3-11<a name="77054"></a> <i>Multilevel tree
     content view</i></p>
 <pre>
  &lt;tree id="tree" hidecolumnpicker="true" flex="1"&gt;
    &lt;treecols&gt;     &lt;treecols&gt;
      &lt;treecol id="type" label="Type" flex="1" primary="true"/&gt;       &lt;treecol id="type" label="Type" flex="1" primary="true"/&gt;
      &lt;treecol id="method" label="Method" flex="1"/&gt;       &lt;treecol id="method" label="Method" flex="1"/&gt;
    &lt;/treecols&gt;     &lt;/treecols&gt;
   </TD>&lt;treechildren&gt;   &lt;/td&gt;&lt;treechildren&gt;
      &lt;treeitem&gt;       &lt;treeitem&gt;
        &lt;treerow&gt;         &lt;treerow&gt;
          &lt;treecell label="Bike"/&gt;           &lt;treecell label="Bike"/&gt;
Line 306  Example 3-11<A NAME="77054"></A> Line 777  Example 3-11<A NAME="77054"></A>
          &lt;treecell label="Fly"/&gt;           &lt;treecell label="Fly"/&gt;
          &lt;treecell label="Wings"/&gt;           &lt;treecell label="Wings"/&gt;
        &lt;/treerow&gt;         &lt;/treerow&gt;
       </TD>&lt;treechildren&gt;  &lt;!-- Second level row --&gt;       &lt;/td&gt;&lt;treechildren&gt;  &lt;!-- Second level row --&gt;
          &lt;treeitem&gt;           &lt;treeitem&gt;
            &lt;treerow&gt;             &lt;treerow&gt;
              &lt;treecell label="Glide"/&gt;               &lt;treecell label="Glide"/&gt;
Line 316  Example 3-11<A NAME="77054"></A> Line 787  Example 3-11<A NAME="77054"></A>
        &lt;/treechildren&gt;         &lt;/treechildren&gt;
      &lt;/treeitem&gt;       &lt;/treeitem&gt;
    &lt;/treechildren&gt;     &lt;/treechildren&gt;
 &lt;/tree&gt;</PRE> &lt;/tree&gt;
</pre>
<P>To create a new sublevel, create another <TT> <!--INDEX treechildren element, XUL --> &lt;treechildren&gt;</TT> element; inside of it, place a <TT>&lt;treeitem&gt;</TT>, which, in turn, contains one or more rows and cells. <A HREF="#77010">Figure 3-5</A> illustrates the result of this hierarchy.    <p>To create a new sublevel, create another <tt>
<P><CENTER><IMG SRC="foo.gif"></CENTER>    <!--INDEX treechildren element, XUL -->
<P><I>Figure 3-5: <A NAME="77010"></A></I>    &lt;treechildren&gt;</tt> element; inside of it, place a
<I>Multilevel tree hierarchy</I>    <tt>&lt;treeitem&gt;</tt>, which, in turn, contains one or more
    rows and cells. <a href="#77010">Figure 3-5</a> illustrates the
<H4><A NAME="77105"></A> Using trees in XUL templates</H4>    result of this hierarchy.</p>
<P>XUL templates are special built-in structures  <!--INDEX XUL (XML-based User-interface Language):templates, trees in;templates:XUL templates:trees in;trees:XUL templates --> that allow dynamic updating of XUL elements and that are often used with trees and list boxes. Templates harness the power of the Resource Description Framework (RDF) to  <!--INDEX RDF (Resource Description Framework) --> pull data from external datasources and dynamically create or update content in the UI. The following code extract shows the basic structure of a XUL template for displaying the browser history in Mozilla:    <div class="c10">
<PRE>&lt;template&gt;      <img src="foo.gif">
     </div>
     <p><i>Figure 3-5: <a name="77010"></a></i> <i>Multilevel tree
     hierarchy</i></p>
     <h4><a name="77105"></a> Using trees in XUL templates</h4>
     <p>XUL templates are special built-in structures 
     <!--INDEX XUL (XML-based User-interface Language):templates, trees in;templates:XUL templates:trees in;trees:XUL templates -->
     that allow dynamic updating of XUL elements and that are often
     used with trees and list boxes. Templates harness the power of
     the Resource Description Framework (RDF) to 
     <!--INDEX RDF (Resource Description Framework) --> pull data
     from external datasources and dynamically create or update
     content in the UI. The following code extract shows the basic
     structure of a XUL template for displaying the browser history
     in Mozilla:</p>
 <pre>
 &lt;template&gt;
 &lt;rule&gt;  &lt;rule&gt;
 &lt;treechildren&gt;  &lt;treechildren&gt;
&lt;treeitem uri="rdf:*" rdf:type="rdf:<A HREF="http://www.w3.org/1999/02/22-rdf-syntax">http://www.w3.org/1999/02/22-rdf-syntax</A>-            ns#type"&gt;&lt;treeitem uri="rdf:*" rdf:type="rdf:<a href=
 "http://www.w3.org/1999/02/22-rdf-syntax">http://www.w3.org/1999/02/22-rdf-syntax</a>-            ns#type"&gt;
 &lt;treerow&gt;  &lt;treerow&gt;
&lt;treecell label="rdf:<A HREF="http://home.netscape.com/NC-rdf">http://home.netscape.com/NC-rdf</A>#Name"/&gt;&lt;treecell label="rdf:<a href=
&lt;treecell label="rdf:<A HREF="http://home.netscape.com/NC-rdf">http://home.netscape.com/NC-rdf</A>#URL"/&gt;"http://home.netscape.com/NC-rdf">http://home.netscape.com/NC-rdf</a>#Name"/&gt;
&lt;treecell label="rdf:<A HREF="http://home.netscape.com/NC-rdf">http://home.netscape.com/NC-rdf</A>#Date"/&gt;&lt;treecell label="rdf:<a href=
 "http://home.netscape.com/NC-rdf">http://home.netscape.com/NC-rdf</a>#URL"/&gt;
 &lt;treecell label="rdf:<a href=
 "http://home.netscape.com/NC-rdf">http://home.netscape.com/NC-rdf</a>#Date"/&gt;
 &lt;!-- further cells --&gt;  &lt;!-- further cells --&gt;
 &lt;/treerow&gt;  &lt;/treerow&gt;
 &lt;/treeitem&gt;  &lt;/treeitem&gt;
 &lt;/treechildren&gt;  &lt;/treechildren&gt;
 &lt;/rule&gt;  &lt;/rule&gt;
&lt;/template&gt;</PRE>&lt;/template&gt;
<P>For each entry or row in the browser history, the template extracts information from the datasource and renders it in a <TT>treecell</TT>. It </pre>
then updates it each time a page is visited. For a more detailed discussion, refer to <A HREF="ch09.html#97291">Chapter 9</A>.    <p>For each entry or row in the browser history, the template
<H4><A NAME="77106"></A> Custom tree views</H4>    extracts information from the datasource and renders it in a
<P>Custom views extend upon the static presentation  <!--INDEX trees:views:custom;views, tree views:custom --> of data in a tree with more flexibility, different ways to present the same data, and interfaces for defining behavior related to content. The functions include intercepting a <TT>treeitem</TT> selection and carrying out some functionality, populating or getting values from the tree, and returning the number of rows currently in the tree.    <tt>treecell</tt>. It then updates it each time a page is
<P>The first thing you have to do to build a custom view is instantiate your <TT>tree</TT> and then associate a <TT>view</TT> object with it, commonly known as a view.    visited. For a more detailed discussion, refer to <a href=
<PRE>document.getElementById('main-tree').treeBoxObject.view=mainView;</PRE>    "ch09.html#97291">Chapter 9</a>.</p>
<P>In this example, the view that is exposed in the <TT>nsITreeView</TT> XPCOM object is essentially the lifeline for the tree, supplying the data that populates the view. The view is assigned to the code object that contains all the functions available to it and your implementation of what you need to do when they are activated.    <h4><a name="77106"></a> Custom tree views</h4>
<P>Here is a large subset of the functions available to the view object:    <p>Custom views extend upon the static presentation 
<P>setTree(tree)    <!--INDEX trees:views:custom;views, tree views:custom --> of
<DL><DD>Called during initialization and used to connect the tree view to the front end. This connection ensures that the correct tree is associated with the view.<P>    data in a tree with more flexibility, different ways to present
<DT>getCellText (row,column)    the same data, and interfaces for defining behavior related to
<DD>Returns the text of a particular cell, or an empty string if there's just an image in it.<P>    content. The functions include intercepting a <tt>treeitem</tt>
<DT>rowCount    selection and carrying out some functionality, populating or
<DD>Set up the number of rows that you anticipate for your tree.<P>    getting values from the tree, and returning the number of rows
<DT>cycleHeader(index)    currently in the tree.</p>
<DD>Called when you click on the header of a particular column.<P>    <p>The first thing you have to do to build a custom view is
<DT>toggleOpenState    instantiate your <tt>tree</tt> and then associate a
<DD>Put code in here to be carried out when the view is expanded and collapsed.<P>    <tt>view</tt> object with it, commonly known as a view.</p>
<DT>setCellText (row, colID, value)<pre>
<DD>Called when the contents of the cell have been edited.<P>document.getElementById('main-tree').treeBoxObject.view=mainView;
<DT>performAction (action)</pre>
<DD>An event from a set of commands can be invoked when you carry out a certain action on the outliner. The tree invokes this method when certain keys are pressed. For example, when the ENTER key is pressed, <TT>performAction</TT> calls with the "enter" string.<P>    <p>In this example, the view that is exposed in the
<DD>There are more local conveniences in the form of <TT>PerformActionOnRow</TT> and <TT>performActionOnCell</TT>.<P>    <tt>nsITreeView</tt> XPCOM object is essentially the lifeline
<DT>selectionChanged    for the tree, supplying the data that populates the view. The
<DD>Should be hooked up to the <TT>onselect</TT> handler of the <TT>&lt;tree&gt;</TT> element in the XUL content.<P></DL>    view is assigned to the code object that contains all the
<H3><A NAME="77107"></A> Grid</H3>    functions available to it and your implementation of what you
<P>A <TT>&lt;grid&gt;</TT> is another XUL table  <!--INDEX grid element, XUL --> structure, designed  <!--INDEX tabular information:grids --> to be more flexible with the content it can hold than the other tabular widgets. <A HREF="#77056">Example 3-12</A> shows a two-column grid that holds text input boxes and labels for them.    need to do when they are activated.</p>
    <p>Here is a large subset of the functions available to the
Example 3-12<A NAME="77056"></A>    view object:</p>
<I>XUL grid</I>    <p>setTree(tree)</p>
<PRE> &lt;grid&gt;    <dl>
       <dd>Called during initialization and used to connect the tree
       view to the front end. This connection ensures that the
       correct tree is associated with the view.</dd>
       <dt>getCellText (row,column)</dt>
       <dd>Returns the text of a particular cell, or an empty string
       if there's just an image in it.</dd>
       <dt>rowCount</dt>
       <dd>Set up the number of rows that you anticipate for your
       tree.</dd>
       <dt>cycleHeader(index)</dt>
       <dd>Called when you click on the header of a particular
       column.</dd>
       <dt>toggleOpenState</dt>
       <dd>Put code in here to be carried out when the view is
       expanded and collapsed.</dd>
       <dt>setCellText (row, colID, value)</dt>
       <dd>Called when the contents of the cell have been
       edited.</dd>
       <dt>performAction (action)</dt>
       <dd>An event from a set of commands can be invoked when you
       carry out a certain action on the outliner. The tree invokes
       this method when certain keys are pressed. For example, when
       the ENTER key is pressed, <tt>performAction</tt> calls with
       the "enter" string.</dd>
       <dd>There are more local conveniences in the form of
       <tt>PerformActionOnRow</tt> and
       <tt>performActionOnCell</tt>.</dd>
       <dt>selectionChanged</dt>
       <dd>Should be hooked up to the <tt>onselect</tt> handler of
       the <tt>&lt;tree&gt;</tt> element in the XUL content.</dd>
     </dl>
     <h3><a name="77107"></a> Grid</h3>
     <p>A <tt>&lt;grid&gt;</tt> is another XUL table 
     <!--INDEX grid element, XUL --> structure, designed 
     <!--INDEX tabular information:grids --> to be more flexible
     with the content it can hold than the other tabular widgets. <a
     href="#77056">Example 3-12</a> shows a two-column grid that
     holds text input boxes and labels for them. Example 3-12<a
     name="77056"></a> <i>XUL grid</i></p>
 <pre>
  &lt;grid&gt;
    &lt;columns&gt;&lt;column flex="1"/&gt;&lt;column flex="2"/&gt;&lt;/columns&gt;     &lt;columns&gt;&lt;column flex="1"/&gt;&lt;column flex="2"/&gt;&lt;/columns&gt;
    &lt;rows&gt;     &lt;rows&gt;
      &lt;row align="center"&gt;       &lt;row align="center"&gt;
Line 385  Example 3-12<A NAME="77056"></A> Line 917  Example 3-12<A NAME="77056"></A>
        &lt;textbox id="about-text" oninput=" TextboxInput(this.id)"/&gt;         &lt;textbox id="about-text" oninput=" TextboxInput(this.id)"/&gt;
      &lt;/row&gt;       &lt;/row&gt;
    &lt;/rows&gt;     &lt;/rows&gt;
 &lt;/grid&gt;</PRE> &lt;/grid&gt;
</pre>
<P>In a grid, the number of columns needs to be defined and placed in a <TT>&lt;columns&gt;</TT> set. In <A HREF="#77056">Example 3-12</A>, the first column holds the labels and the second contains the text boxes. These two columns are horizontal to each other and in rows for easy association. The flex is greater on the second column, allowing more space for the text input boxes. As with all examples in this chapter, you can see <A HREF="#77056">Example 3-12</A> in action by adding the XML processing instruction at the top and  <!--INDEX ENDRANGE--tabular information;hierarchical information --> surrounding the grid in a basic <TT>window</TT> root element.    <p>In a grid, the number of columns needs to be defined and
<H2><A NAME="77108"></A> Words and Pictures</H2>    placed in a <tt>&lt;columns&gt;</tt> set. In <a href=
<P>The text widgets described here are used to label other widgets, or simply to display messages or instructions to the user in the interface and include a text input widget. Images can be displayed with the main <TT>image</TT> element or in various ways on other elements, such as buttons or menus.    "#77056">Example 3-12</a>, the first column holds the labels
<H3><A NAME="77109"></A> Text Input</H3>    and the second contains the text boxes. These two columns are
<P>The <TT>&lt;textbox&gt;</TT> element is a text input box not  <!--INDEX text widgets, input;input text;text:input text --> unlike  <!--INDEX textbox element, XUL --> the HTML <TT>&lt;textarea&gt;</TT> element. The default <TT>&lt;textbox&gt;</TT> element has a single line.    horizontal to each other and in rows for easy association. The
<PRE>&lt;textbox id="singleFlyInput" /&gt;</PRE>    flex is greater on the second column, allowing more space for
<P>However, setting the <TT>multiline</TT> attribute makes it into a larger text area.    the text input boxes. As with all examples in this chapter, you
<PRE>&lt;textbox id="multiFlyInput" value="Fly Name" multiline="true" rows="4" /&gt;</PRE>    can see <a href="#77056">Example 3-12</a> in action by adding
<P>A multiline textbox defaults to three lines unless constricted by a fixed size on a container or stretched out with flex. To force the number of lines, use the <TT>rows</TT> attribute. If you want to restrict the number of characters inputted, set the <TT>size</TT> attribute to a numeric value.    the XML processing instruction at the top and 
<PRE>&lt;textbox id="holdtheFlyInput" cols="3" rows="2" /&gt;</PRE>    <!--INDEX ENDRANGE==tabular information;hierarchical information -->
<P>The initial value of an input widget is blank if no <TT>value</TT> is specified. Setting the <TT>readonly</TT> attribute to <TT>true</TT> or <TT>false</TT> can control editing access.    surrounding the grid in a basic <tt>window</tt> root
<H4><A NAME="77110"></A> Autocomplete</H4>    element.</p>
<P>Autocompletion is the process of  <!--INDEX autocomplete, text input and;text:input text:autocomplete;input text:autocomplete --> automatically finishing a user's input by offering possible choices, or completions, when something is typed in. In Mozilla, this mechanism is simply known as <I>autocomplete</I>, and the textbox widget is used for this process in such places as the browser URL bar and in the address area of the mail compose window. <A HREF="#77058">Example 3-13</A> shows the code from the Open Web Location dialog, which provides autocompletion.    <h2><a name="77108"></a> Words and Pictures</h2>
    <p>The text widgets described here are used to label other
Example 3-13<A NAME="77058"></A>    widgets, or simply to display messages or instructions to the
<I>Text autocomplete</I>    user in the interface and include a text input widget. Images
<PRE> &lt;textbox id="dialog.input" flex="1" type="autocomplete"    can be displayed with the main <tt>image</tt> element or in
     various ways on other elements, such as buttons or menus.</p>
     <h3><a name="77109"></a> Text Input</h3>
     <p>The <tt>&lt;textbox&gt;</tt> element is a text input box not
     <!--INDEX text widgets, input;input text;text:input text -->
     unlike <!--INDEX textbox element, XUL --> the HTML
     <tt>&lt;textarea&gt;</tt> element. The default
     <tt>&lt;textbox&gt;</tt> element has a single line.</p>
 <pre>
 &lt;textbox id="singleFlyInput" /&gt;
 </pre>
     <p>However, setting the <tt>multiline</tt> attribute makes it
     into a larger text area.</p>
 <pre>
 &lt;textbox id="multiFlyInput" value="Fly Name" multiline="true" rows="4" /&gt;
 </pre>
     <p>A multiline textbox defaults to three lines unless
     constricted by a fixed size on a container or stretched out
     with flex. To force the number of lines, use the <tt>rows</tt>
     attribute. If you want to restrict the number of characters
     inputted, set the <tt>size</tt> attribute to a numeric
     value.</p>
 <pre>
 &lt;textbox id="holdtheFlyInput" cols="3" rows="2" /&gt;
 </pre>
     <p>The initial value of an input widget is blank if no
     <tt>value</tt> is specified. Setting the <tt>readonly</tt>
     attribute to <tt>true</tt> or <tt>false</tt> can control
     editing access.</p>
     <h4><a name="77110"></a> Autocomplete</h4>
     <p>Autocompletion is the process of 
     <!--INDEX autocomplete, text input and;text:input text:autocomplete;input text:autocomplete -->
     automatically finishing a user's input by offering possible
     choices, or completions, when something is typed in. In
     Mozilla, this mechanism is simply known as <i>autocomplete</i>,
     and the textbox widget is used for this process in such places
     as the browser URL bar and in the address area of the mail
     compose window. <a href="#77058">Example 3-13</a> shows the
     code from the Open Web Location dialog, which provides
     autocompletion. Example 3-13<a name="77058"></a> <i>Text
     autocomplete</i></p>
 <pre>
  &lt;textbox id="dialog.input" flex="1" type="autocomplete"
      searchSessions="history" timeout="50" maxrows="6"       searchSessions="history" timeout="50" maxrows="6"
      disablehistory="false"       disablehistory="false"
      oninput="doEnabling( );"&gt;       oninput="doEnabling( );"&gt;
Line 411  Example 3-13<A NAME="77058"></A> Line 985  Example 3-13<A NAME="77058"></A>
        popupalign="topleft" popupanchor="bottomleft"         popupalign="topleft" popupanchor="bottomleft"
        onpopupshowing="createUBHistoryMenu(event.target);"         onpopupshowing="createUBHistoryMenu(event.target);"
        oncommand="useUBHistoryItem(event.target)"/&gt;         oncommand="useUBHistoryItem(event.target)"/&gt;
 &lt;/textbox&gt;</PRE> &lt;/textbox&gt;
</pre>
<P>The first thing to note is the nested <TT>&lt;menupopup&gt;</TT>. This pop up holds the choices in a drop-down format. The relevant attribute in this example is <TT>type</TT> on the <TT>&lt;textbox&gt;</TT>, which has a value of <TT>autocomplete</TT>.    <p>The first thing to note is the nested
<P><A HREF="#77012">Figure 3-6</A> shows the <TT>autocomplete</TT> widget. As the user types the URL into the textbox, auto completion kicks in and the values are retrieved to show in the pop-up list, from which the user can then choose. When similar values are input regularly, <TT>autocomplete</TT> can be a great time-saving feature.    <tt>&lt;menupopup&gt;</tt>. This pop up holds the choices in a
<P><CENTER><IMG SRC="foo.gif"></CENTER>    drop-down format. The relevant attribute in this example is
<P><I>Figure 3-6: <A NAME="77012"></A></I>    <tt>type</tt> on the <tt>&lt;textbox&gt;</tt>, which has a
<I>Autocomplete for Open Web Location</I>    value of <tt>autocomplete</tt>.</p>
    <p><a href="#77012">Figure 3-6</a> shows the
<H3><A NAME="77111"></A> Text Display</H3>    <tt>autocomplete</tt> widget. As the user types the URL into
<P>Three tags available in XUL handle  <!--INDEX text:displaying -->  <!--INDEX display:text --> basic text display in the UI, and each has its own context for use. They include a <TT> <!--INDEX caption element, XUL -->  <!--INDEX label element, XUL --> &lt;caption&gt;</TT>, a <TT>&lt;label&gt;</TT>, and a <TT> <!--INDEX description element, XUL --> &lt;description&gt;</TT> element.    the textbox, auto completion kicks in and the values are
<P>The <TT>caption</TT> is designed specifically for the text that appears inline in the border of a group box. You can control where the caption appears by putting the caption element above or below the other content in the group box:    retrieved to show in the pop-up list, from which the user can
<PRE>&lt;groupbox id="textWidgetsBox"&gt;    then choose. When similar values are input regularly,
     <tt>autocomplete</tt> can be a great time-saving feature.</p>
     <div class="c10">
       <img src="foo.gif">
     </div>
     <p><i>Figure 3-6: <a name="77012"></a></i> <i>Autocomplete for
     Open Web Location</i></p>
     <h3><a name="77111"></a> Text Display</h3>
     <p>Three tags available in XUL handle 
     <!--INDEX text:displaying --> <!--INDEX display:text --> basic
     text display in the UI, and each has its own context for use.
     They include a <tt><!--INDEX caption element, XUL --> 
     <!--INDEX label element, XUL --> &lt;caption&gt;</tt>, a
     <tt>&lt;label&gt;</tt>, and a <tt>
     <!--INDEX description element, XUL --> &lt;description&gt;</tt>
     element.</p>
     <p>The <tt>caption</tt> is designed specifically for the text
     that appears inline in the border of a group box. You can
     control where the caption appears by putting the caption
     element above or below the other content in the group box:</p>
 <pre>
 &lt;groupbox id="textWidgetsBox"&gt;
 &lt;caption id="textTitle" label="Text Widgets"/&gt;  &lt;caption id="textTitle" label="Text Widgets"/&gt;
 &lt;!-- content here --&gt;  &lt;!-- content here --&gt;
&lt;/groupbox&gt;</PRE>&lt;/groupbox&gt;
<P><TT>label</TT> is more flexible than <TT>caption</TT> because it isn't tied to a particular widget and can even be used as a standalone.</pre>
<P>For longer text, the <TT>&lt;description&gt;</TT> element is best. You can embed text in the description element and have it wrap to the maximum size of the containing element:    <p><tt>label</tt> is more flexible than <tt>caption</tt>
<PRE>&lt;decription&gt;    because it isn't tied to a particular widget and can even be
     used as a standalone.</p>
     <p>For longer text, the <tt>&lt;description&gt;</tt> element is
     best. You can embed text in the description element and have it
     wrap to the maximum size of the containing element:</p>
 <pre>
 &lt;decription&gt;
 The mozdev.org site provides free project hosting for the Mozilla community. You are welcome to take a look at the more than 60 projects hosted on the site or to start your own development project.  The mozdev.org site provides free project hosting for the Mozilla community. You are welcome to take a look at the more than 60 projects hosted on the site or to start your own development project.
&lt;/decription&gt;</PRE>&lt;/decription&gt;
<P>Or you can use the <TT>value</TT> attribute when you're sure the text will not overflow. In this case, <TT>&lt;description&gt;</TT> is interchangeable with the <TT>&lt;label&gt;</TT> element for use in identifying other items in the UI:</pre>
<PRE>&lt;description value="Start a project today." /&gt;</PRE>    <p>Or you can use the <tt>value</tt> attribute when you're sure
<H3><A NAME="77112"></A> Images</H3>    the text will not overflow. In this case,
<P>XUL supports the display of images in the native web  <!--INDEX images:displaying;display:images;XUL (XML-based User-interface Language):images     <tt>&lt;description&gt;</tt> is interchangeable with the
--> formats of JPEG, PNG, and GIF. Most images you will find in the Mozilla UI are GIF files, which retain the best quality when compressed. <A HREF="ch04.html#37942">Chapter 4</A> discusses theme issues  <!--INDEX JPEG files;PNG files;GIG files --> and considerations in more detail. The basic syntax for displaying an image is:    <tt>&lt;label&gt;</tt> element for use in identifying other
<PRE>&lt;image src="myImage.png" /&gt;</PRE>    items in the UI:</p>
<P>The <TT> <!--INDEX image element, XUL --> &lt;image&gt;</TT> element is analogous to the HTML <TT>&lt;img&gt;</TT> element. The image to be displayed is directly associated with the element using the <TT>src</TT> attribute. You can also use <TT>list-style-image</TT>, which is a CSS2 property used to associate an image with an element. To do this, you need a style <I>selector-</I>in this case, the <TT>id</TT>.<pre>
<PRE>&lt;image id="foo" /&gt;</PRE>&lt;description value="Start a project today." /&gt;
<P>The style property takes a value of <TT>src</TT>, which has one parameter, the image, or a chrome or resource URL pointing to the image.</pre>
<PRE>#foo  {    <h3><a name="77112"></a> Images</h3>
     <p>XUL supports the display of images in the native web 
     <!--INDEX images:displaying;display:images;XUL (XML-based User-interface Language):images 
     --> formats of JPEG, PNG, and GIF. Most images you will find in
     the Mozilla UI are GIF files, which retain the best quality
     when compressed. <a href="ch04.html#37942">Chapter 4</a>
     discusses theme issues 
     <!--INDEX JPEG files;PNG files;GIG files --> and considerations
     in more detail. The basic syntax for displaying an image
     is:</p>
 <pre>
 &lt;image src="myImage.png" /&gt;
 </pre>
     <p>The <tt><!--INDEX image element, XUL --> &lt;image&gt;</tt>
     element is analogous to the HTML <tt>&lt;img&gt;</tt> element.
     The image to be displayed is directly associated with the
     element using the <tt>src</tt> attribute. You can also use
     <tt>list-style-image</tt>, which is a CSS2 property used to
     associate an image with an element. To do this, you need a
     style <i>selector-</i>in this case, the <tt>id</tt>.</p>
 <pre>
 &lt;image id="foo" /&gt;
 </pre>
     <p>The style property takes a value of <tt>src</tt>, which has
     one parameter, the image, or a chrome or resource URL pointing
     to the image.</p>
 <pre>
 #foo  {
 list-style-image: url("myImage.png");  list-style-image: url("myImage.png");
}</PRE>}
<P><TT>src</TT> is good for single images and for convenience, but in general, using the CSS property is recommended because it follows the principal of separating functionality from presentation and it better fits into a theme-swapping architecture, as used in the Mozilla suite.</pre>
<BLOCKQUOTE><CENTER><B>NOTE</B></CENTER>    <p><tt>src</tt> is good for single images and for convenience,
<P>Many in the open source community feel that PNG would have been a more natural choice for the project because it is a free format. Efforts to make this switch have been held up by a bug in gamma-corrected CSS color values and specified in both CSS1 and CSS2.<P></BLOCKQUOTE>    but in general, using the CSS property is recommended because
<H4><A NAME="77113"></A> Images in other XUL elements</H4>    it follows the principal of separating functionality from
<P>Image display is  <!--INDEX list-style-image property (CSS);properties:list-style-image --> not the sole province of the <TT>image</TT> element. Using the <TT>list-style-image</TT> property, you can attach images to almost any element. For example, the <TT>tree</TT> widget has a couple of its own special associated CSS properties that allow you to define <TT>list-style-image</TT> values. <TT>-moz-tree-image</TT> defines images contained in a cell, and it takes input parameters that let you specify the <TT>id</TT> of the specific column and row to which the image should be applied:    presentation and it better fits into a theme-swapping
<PRE>treechildren:-moz-tree-image(col-id,row-id) {    architecture, as used in the Mozilla suite.</p>
     <blockquote>
       <div class="c11">
         NOTE
       </div>
       <p>Many in the open source community feel that PNG would have
       been a more natural choice for the project because it is a
       free format. Efforts to make this switch have been held up by
       a bug in gamma-corrected CSS color values and specified in
       both CSS1 and CSS2.</p>
     </blockquote>
     <h4><a name="77113"></a> Images in other XUL elements</h4>
     <p>Image display is 
     <!--INDEX list-style-image property (CSS);properties:list-style-image -->
     not the sole province of the <tt>image</tt> element. Using the
     <tt>list-style-image</tt> property, you can attach images to
     almost any element. For example, the <tt>tree</tt> widget has a
     couple of its own special associated CSS properties that allow
     you to define <tt>list-style-image</tt> values.
     <tt>-moz-tree-image</tt> defines images contained in a cell,
     and it takes input parameters that let you specify the
     <tt>id</tt> of the specific column and row to which the image
     should be applied:</p>
 <pre>
 treechildren:-moz-tree-image(col-id,row-id) {
 list-style-image: url("chrome://xfly/skin/images/outliner.gif");  list-style-image: url("chrome://xfly/skin/images/outliner.gif");
}</PRE>}
<P>Also, <TT>-moz-tree-twisty</TT>  <!--INDEX -moz-tree-twisty[moz-tree-twisty] --> allows you define an image for the <TT>twisty</TT> that is used to open and close a level in a tree.</pre>
<PRE>treechildren:-moz-tree-twisty {    <p>Also, <tt>-moz-tree-twisty</tt> 
     <!--INDEX -moz-tree-twisty[moz-tree-twisty] --> allows you
     define an image for the <tt>twisty</tt> that is used to open
     and close a level in a tree.</p>
 <pre>
 treechildren:-moz-tree-twisty {
 list-style-image: url("chrome://xfly/skin/images/twisty.gif");  list-style-image: url("chrome://xfly/skin/images/twisty.gif");
}</PRE>}
<P>The example above uses a parameter of <TT>open</TT>, but if no parameter is specified, the default is closed, so you can have a different image for both states.</pre>
<P>The <TT>&lt;tab&gt;</TT> widget can also take a <TT>list-style-image</TT> property in CSS.    <p>The example above uses a parameter of <tt>open</tt>, but if
<PRE>&lt;tab id="TabOne" class="tabbies" selected="1" label="Click Me!"  oncommand="SelectTab(1);" /&gt;</PRE>    no parameter is specified, the default is closed, so you can
<P>In this case, the <TT>class</TT> attribute is used as a selector for associating the element with the style rule in which the image is referenced:    have a different image for both states.</p>
<PRE>.tabbies {    <p>The <tt>&lt;tab&gt;</tt> widget can also take a
     <tt>list-style-image</tt> property in CSS.</p>
 <pre>
 &lt;tab id="TabOne" class="tabbies" selected="1" label="Click Me!"  oncommand="SelectTab(1);" /&gt;
 </pre>
     <p>In this case, the <tt>class</tt> attribute is used as a
     selector for associating the element with the style rule in
     which the image is referenced:</p>
 <pre>
 .tabbies {
 list-style-image: url("chrome://xfly/skin/images/tab.gif");  list-style-image: url("chrome://xfly/skin/images/tab.gif");
}</PRE>}
<H2><A NAME="77114"></A> Form Controls</H2></pre>
<P>In the HTML world, the textbox  <!--INDEX STARTRANGE--form controls:XUL;XUL (XML-based User-interface Language):forms, controls;controls, forms:XUL --> is one of the most commonly used elements in a form control. While the XPFE toolkit has no concept of a form, it was originally designed to allow HTML in the UI when needed, but only on a limited scale. Although it's still possible to incorporate HTML when you use the correct namespace, the existence of XUL widgets such as the textbox, checkbox and radio group selector obviates the need for HTML elements.    <h2><a name="77114"></a> Form Controls</h2>
<H3><A NAME="77115"></A> Radio</H3>    <p>In the HTML world, the textbox 
<P>Radio groups are useful UI controls  <!--INDEX radio groups, XUL and;XUL (XML-based User-interface Language):radio groups --> that present the user with a choice of options in XUL. In HTML, radio choices are represented by the <TT>&lt;INPUT&gt;</TT> element with the <TT>type</TT> attribute set to the value of <TT>radio</TT>, all wrapped in a form element. <A HREF="#77060">Example 3-14</A> shows how to make radio group choices in XUL.    <!--INDEX STARTRANGE==form controls:XUL;XUL (XML-based User-interface Language):forms, controls;controls, forms:XUL -->
    is one of the most commonly used elements in a form control.
Example 3-14<A NAME="77060"></A>    While the XPFE toolkit has no concept of a form, it was
<I>A radio group choice of options</I>    originally designed to allow HTML in the UI when needed, but
<PRE> &lt;radiogroup id="flyTypes" orient="vertical"&gt;    only on a limited scale. Although it's still possible to
     incorporate HTML when you use the correct namespace, the
     existence of XUL widgets such as the textbox, checkbox and
     radio group selector obviates the need for HTML elements.</p>
     <h3><a name="77115"></a> Radio</h3>
     <p>Radio groups are useful UI controls 
     <!--INDEX radio groups, XUL and;XUL (XML-based User-interface Language):radio groups -->
     that present the user with a choice of options in XUL. In HTML,
     radio choices are represented by the <tt>&lt;INPUT&gt;</tt>
     element with the <tt>type</tt> attribute set to the value of
     <tt>radio</tt>, all wrapped in a form element. <a href=
     "#77060">Example 3-14</a> shows how to make radio group choices
     in XUL. Example 3-14<a name="77060"></a> <i>A radio group
     choice of options</i></p>
 <pre>
  &lt;radiogroup id="flyTypes" orient="vertical"&gt;
    &lt;radio id="tachina" group="flyTypes" label="Tachinidae"     &lt;radio id="tachina" group="flyTypes" label="Tachinidae"
      oncommand="chooseType(this);"/&gt;       oncommand="chooseType(this);"/&gt;
    &lt;radio id="primitive-crane" group="flyTypes" label="Tanyderidae"     &lt;radio id="primitive-crane" group="flyTypes" label="Tanyderidae"
Line 480  Example 3-14<A NAME="77060"></A> Line 1161  Example 3-14<A NAME="77060"></A>
      oncommand="chooseType(this);"/&gt;       oncommand="chooseType(this);"/&gt;
    &lt;radio id="fruit" group="flyTypes" label="Tephritidae"     &lt;radio id="fruit" group="flyTypes" label="Tephritidae"
      oncommand="chooseType(this);"/&gt;       oncommand="chooseType(this);"/&gt;
 &lt;/radiogroup&gt;</PRE> &lt;/radiogroup&gt;
</pre>
<P>The options must be enclosed in the <TT>&lt;radiogroup&gt;</TT> element, and each one is represented by a <TT> <!--INDEX radio element, XUL --> &lt;radio&gt;</TT> element. The important attributes are the <TT>id</TT> on the <TT>&lt;radiogroup&gt;</TT> and the <TT>group</TT> attribute on the <TT>&lt;radio&gt;</TT> elements. These attributes have to be identical to ensure that only one option at a time can be chosen. The <TT>this</TT> keyword in JavaScript lets you access the selected item in a straightforward way. In this case, it sends the node to the script every time an option is selected.    <p>The options must be enclosed in the
<H3><A NAME="77116"></A> Checkbox</H3>    <tt>&lt;radiogroup&gt;</tt> element, and each one is
<P>A checkbox  <!--INDEX checkboxes;controls, forms:checkboxes;form controls:checkboxes;XUL (XML-based User-interface Language):checkboxes --> is a simpler widget that needn't be part of a selection group. It is often used to indicate if some functionality should be turned on or off, as shown in <A HREF="#77014">Figure 3-7</A>.    represented by a <tt><!--INDEX radio element, XUL -->
<PRE>&lt;checkbox id="closeWindow"    &lt;radio&gt;</tt> element. The important attributes are the
     <tt>id</tt> on the <tt>&lt;radiogroup&gt;</tt> and the
     <tt>group</tt> attribute on the <tt>&lt;radio&gt;</tt>
     elements. These attributes have to be identical to ensure that
     only one option at a time can be chosen. The <tt>this</tt>
     keyword in JavaScript lets you access the selected item in a
     straightforward way. In this case, it sends the node to the
     script every time an option is selected.</p>
     <h3><a name="77116"></a> Checkbox</h3>
     <p>A checkbox 
     <!--INDEX checkboxes;controls, forms:checkboxes;form controls:checkboxes;XUL (XML-based User-interface Language):checkboxes -->
     is a simpler widget that needn't be part of a selection group.
     It is often used to indicate if some functionality should be
     turned on or off, as shown in <a href="#77014">Figure
     3-7</a>.</p>
 <pre>
 &lt;checkbox id="closeWindow"
 label="Close this window when download is complete"  label="Close this window when download is complete"
checked="true" /&gt;</PRE>checked="true" /&gt;
<P><CENTER><IMG SRC="foo.gif"></CENTER></pre>
<P><I>Figure 3-7: <A NAME="77014"></A></I>    <div class="c10">
<I>Checkbox widget</I>      <img src="foo.gif">
    </div>
<P>Clicking on the box sets the <TT>clicked</TT> attribute, for which the check indicates a positive value. You can set this attribute in script to give the checkbox an initial value.    <p><i>Figure 3-7: <a name="77014"></a></i> <i>Checkbox
<H3><A NAME="77117"></A> Buttons</H3>    widget</i></p>
<P>A button is  <!--INDEX buttons;controls, forms:buttons;form controls:buttons;XUL (XML-based User-interface Language):buttons --> a multipurpose widget that commonly lives in toolbars and dialog boxes. The two button elements, <TT> <!--INDEX button element, XUL --> &lt;button&gt;</TT> and <TT> <!--INDEX toolbarbutton element, XUL --> &lt;toolbarbutton&gt;</TT>, are essentially the same. Often only the <TT>class</TT> attribute values distinguish the two. You can use a <TT>&lt;toolbarbutton&gt;</TT> outside a toolbar or use a <TT>&lt;button&gt;</TT> inside a toolbar, though in practice, the two usually stay in their respective domains. This flexibility has the nice effect of letting you get the buttons in a particular area by using the <TT>getElementsByTagName</TT> method with, for example, the tag name "button."    <p>Clicking on the box sets the <tt>clicked</tt> attribute, for
<P>A common form of the button contains text and an image, with image on the left and the text to the right by default. However, you may want to take advantage of some of the classes available in Mozilla to define a different orientation, or you can simply write your own style rules for your buttons.<A NAME="b315"></A><A HREF="#315">[*]</A> The text that appears on the button is contained in the <TT>label</TT> attribute and shown in this example:    which the check indicates a positive value. You can set this
<PRE>&lt;button id="newfileBtn"    attribute in script to give the checkbox an initial value.</p>
     <h3><a name="77117"></a> Buttons</h3>
     <p>A button is 
     <!--INDEX buttons;controls, forms:buttons;form controls:buttons;XUL (XML-based User-interface Language):buttons -->
     a multipurpose widget that commonly lives in toolbars and
     dialog boxes. The two button elements, <tt>
     <!--INDEX button element, XUL --> &lt;button&gt;</tt> and <tt>
     <!--INDEX toolbarbutton element, XUL -->
     &lt;toolbarbutton&gt;</tt>, are essentially the same. Often
     only the <tt>class</tt> attribute values distinguish the two.
     You can use a <tt>&lt;toolbarbutton&gt;</tt> outside a toolbar
     or use a <tt>&lt;button&gt;</tt> inside a toolbar, though in
     practice, the two usually stay in their respective domains.
     This flexibility has the nice effect of letting you get the
     buttons in a particular area by using the
     <tt>getElementsByTagName</tt> method with, for example, the tag
     name "button."</p>
     <p>A common form of the button contains text and an image, with
     image on the left and the text to the right by default.
     However, you may want to take advantage of some of the classes
     available in Mozilla to define a different orientation, or you
     can simply write your own style rules for your buttons.<a name=
     "b315"></a><a href="#315">[*]</a> The text that appears on the
     button is contained in the <tt>label</tt> attribute and shown
     in this example:</p>
 <pre>
 &lt;button id="newfileBtn"
 tooltiptext="New File"  tooltiptext="New File"
 oncommand="doNew( )"  oncommand="doNew( )"
label="New"/&gt;</PRE>label="New"/&gt;
<P>You can associate the image with the button using the <TT>src</TT> attribute, but the more common way is to use the <TT>list-style-image</TT> style rule in CSS, as in the following snippet of code that uses the <TT>id</TT> style selector:</pre>
<PRE>#newfileBtn    <p>You can associate the image with the button using the
     <tt>src</tt> attribute, but the more common way is to use the
     <tt>list-style-image</tt> style rule in CSS, as in the
     following snippet of code that uses the <tt>id</tt> style
     selector:</p>
 <pre>
 #newfileBtn
 {  {
 list-style-image:    url("chrome://editor/skin/images/newfile.gif");  list-style-image:    url("chrome://editor/skin/images/newfile.gif");
}</PRE>}
<H4><A NAME="77118"></A> Button types</H4></pre>
<P>Mozilla provides more than  <!--INDEX buttons:types;controls, forms:buttons;form controls:buttons;XUL (XML-based User-interface Language):buttons:types --> the standard "click" and "go" buttons in its toolkit. <A HREF="#77030">Table 3-3</A> describes the various button types in Mozilla.    <h4><a name="77118"></a> Button types</h4>
    <p>Mozilla provides more than 
<P><I>Table 3-3: <A NAME="77030"></A></I>    <!--INDEX buttons:types;controls, forms:buttons;form controls:buttons;XUL (XML-based User-interface Language):buttons:types -->
<I>Button types</I>    the standard "click" and "go" buttons in its toolkit. <a href=
<P><TABLE WIDTH=100% BORDER=1><TR><TD><B>  Type</B></TD> <TD><B>  Usage</B></TD> <TD><B>  Description</B></TD></TR>    "#77030">Table 3-3</a> describes the various button types in
<TR><TD>  Menu</TD>     <TD>  type= "menu"</TD>     <TD>  Menu integrated into the button with small arrow icon</TD></TR>    Mozilla.</p>
<TR><TD>  Dual Menu</TD>     <TD>  type= "menu-button"</TD>     <TD>  Menu appears distinct from the button, in separate clickable area</TD></TR>    <p><i>Table 3-3: <a name="77030"></a></i> <i>Button
<TR><TD>  Checkbox</TD>     <TD>  type= "checkbox"</TD>     <TD>  When selected, remains in a depressed state and toggles back to its natural state when selected again</TD></TR>    types</i></p>
<TR><TD>  Radio</TD>     <TD>  type= "radio"</TD>     <TD>  Designed to be part of a group; only one button is selectable at a time</TD></TR>    <table width="100%" border="1">
<TR><TD>  Disclosure</TD>     <TD>  dlgtype= "disclosure"</TD>     <TD>  Shows/Hides a portion of a dialog window</TD></TR>      <tr>
<TR><TD>  Default</TD>     <TD>  dlgtype= "accept"</TD>     <TD>  Performs the default action for a dialog</TD></TR>        <td><b>Type</b></td>
<TR><TD>  Cancel</TD>     <TD>  dlgtype= "cancel"</TD>     <TD>  Closes the dialog and does not carry out the default action</TD></TR>        <td><b>Usage</b></td>
<TR><TD>  Help</TD>     <TD>  dlgtype= "help"</TD>     <TD>  Activates context-sensitive help</TD></TR></TABLE><P>        <td><b>Description</b></td>
      </tr>
<P>Taking one of the button types in <A HREF="#77030">Table 3-3</A> as a mini-case study, you could use a button with the type <TT>menu-button</TT> to display more than one option at a time. The default orientation for this type of button is for the menu to be to the right of the button. Mozilla uses buttons of type <TT>menu-button</TT> for its back and forward buttons, in which the menu items hold previously visited pages. <A HREF="#77016">Figure 3-8</A> shows the appearance of the browser's back button displaying the last several pages viewed.      <tr>
<P><CENTER><IMG SRC="foo.gif"></CENTER>        <td>Menu</td>
<P><I>Figure 3-8: <A NAME="77016"></A></I>        <td>type= "menu"</td>
<I>menu-button for browser's back functionality</I>        <td>Menu integrated into the button with small arrow
        icon</td>
<P>Other possible uses include options for different variations of the same feature, such as a New button that displays New File, New Project, or New Template options. The button action is the default option and the <TT>menuitems</TT> contain the rest of the choices.      </tr>
<H4><A NAME="77119"></A> Dialog buttons</H4>      <tr>
<P>The last four items in <A HREF="#77030">Table 3-3</A> are  <!--INDEX dialog buttons;buttons:dialog buttons;controls, forms:dialog buttons;form controls:dialog buttons;XUL (XML-based User-interface Language):dialog buttons --> button types that make most sense in, and were designed especially for, dialog windows. The easiest way to include them in dialogs is to use the <TT>buttons</TT> attribute on the <TT> <!--INDEX dialog element, XUL --> &lt;dialog&gt;</TT> element, which displays them automatically, as shown here:        <td>Dual Menu</td>
<PRE>&lt;dialog        <td>type= "menu-button"</td>
xmlns="<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>"        <td>Menu appears distinct from the button, in separate
         clickable area</td>
       </tr>
       <tr>
         <td>Checkbox</td>
         <td>type= "checkbox"</td>
         <td>When selected, remains in a depressed state and toggles
         back to its natural state when selected again</td>
       </tr>
       <tr>
         <td>Radio</td>
         <td>type= "radio"</td>
         <td>Designed to be part of a group; only one button is
         selectable at a time</td>
       </tr>
       <tr>
         <td>Disclosure</td>
         <td>dlgtype= "disclosure"</td>
         <td>Shows/Hides a portion of a dialog window</td>
       </tr>
       <tr>
         <td>Default</td>
         <td>dlgtype= "accept"</td>
         <td>Performs the default action for a dialog</td>
       </tr>
       <tr>
         <td>Cancel</td>
         <td>dlgtype= "cancel"</td>
         <td>Closes the dialog and does not carry out the default
         action</td>
       </tr>
       <tr>
         <td>Help</td>
         <td>dlgtype= "help"</td>
         <td>Activates context-sensitive help</td>
       </tr>
     </table>
     <p>Taking one of the button types in <a href="#77030">Table
     3-3</a> as a mini-case study, you could use a button with the
     type <tt>menu-button</tt> to display more than one option at a
     time. The default orientation for this type of button is for
     the menu to be to the right of the button. Mozilla uses buttons
     of type <tt>menu-button</tt> for its back and forward buttons,
     in which the menu items hold previously visited pages. <a href=
     "#77016">Figure 3-8</a> shows the appearance of the browser's
     back button displaying the last several pages viewed.</p>
     <div class="c10">
       <img src="foo.gif">
     </div>
     <p><i>Figure 3-8: <a name="77016"></a></i> <i>menu-button for
     browser's back functionality</i></p>
     <p>Other possible uses include options for different variations
     of the same feature, such as a New button that displays New
     File, New Project, or New Template options. The button action
     is the default option and the <tt>menuitems</tt> contain the
     rest of the choices.</p>
     <h4><a name="77119"></a> Dialog buttons</h4>
     <p>The last four items in <a href="#77030">Table 3-3</a> are 
     <!--INDEX dialog buttons;buttons:dialog buttons;controls, forms:dialog buttons;form controls:dialog buttons;XUL (XML-based User-interface Language):dialog buttons -->
     button types that make most sense in, and were designed
     especially for, dialog windows. The easiest way to include them
     in dialogs is to use the <tt>buttons</tt> attribute on the <tt>
     <!--INDEX dialog element, XUL --> &lt;dialog&gt;</tt> element,
     which displays them automatically, as shown here:</p>
 <pre>
 &lt;dialog
 xmlns="<a href=
 "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
 buttons="accept,cancel,help"  buttons="accept,cancel,help"
 buttonpack="center"  buttonpack="center"
 ondialogaccept="return onAccept( );"  ondialogaccept="return onAccept( );"
 ondialogcancel="return onCancel( );"  ondialogcancel="return onCancel( );"
ondialoghelp="return doHelpButton( );"&gt;</PRE>ondialoghelp="return doHelpButton( );"&gt;
<P>The functions activated when these buttons are clicked on are defined in the <TT>ondialogaccept</TT>, <TT>ondialogcancel</TT>, and <TT>ondialoghelp</TT> event handler attributes. These event handler shortcuts are best if you simply want to inherit the default button text (Ok, Cancel, and Help). In cases when you want your own text, or want some extra control over the scripting, you can define your own button with the <TT>dlgtype</TT> attribute:</pre>
<PRE>&lt;button dlgtype="accept"    <p>The functions activated when these buttons are clicked on
     are defined in the <tt>ondialogaccept</tt>,
     <tt>ondialogcancel</tt>, and <tt>ondialoghelp</tt> event
     handler attributes. These event handler shortcuts are best if
     you simply want to inherit the default button text (Ok, Cancel,
     and Help). In cases when you want your own text, or want some
     extra control over the scripting, you can define your own
     button with the <tt>dlgtype</tt> attribute:</p>
 <pre>
 &lt;button dlgtype="accept"
 label="Go For It!"  label="Go For It!"
oncommand="doExtraFunction( )"/&gt;</PRE>oncommand="doExtraFunction( )"/&gt;
<P>The <TT>buttonpack</TT> attribute determines whether the buttons appear on the right, left, or center of the window. If no value is given, the default platform orientation takes effect. On Windows, the default is the right, and  <!--INDEX ENDRANGE--form controls:XUL;XUL (XML-based User-interface Language):forms, controls;controls, forms:XUL --> on Unix, it's the center.</pre>
<H2><A NAME="77120"></A> Widget Interaction</H2>    <p>The <tt>buttonpack</tt> attribute determines whether the
<P>At a level above the use of widgets  <!--INDEX STARTRANGE--widgets:interactions;interacting with widgets --> for different, singular functions in the application interface, Mozilla provides tools for hooking things together and creating application logic that can make your interfaces work more consistently and handle more complex tasks. If you have different elements in your application that execute the same function, for example, the command and observer system is the ideal way to facilitate reuse. Or you can use command sets to define command sets and key sets that can be overlaid and made available in different parts of your application, similar to how the cut and paste commands and others are spread over the Mozilla user interface but defined in a centralized file.    buttons appear on the right, left, or center of the window. If
<H3><A NAME="77121"></A> Broadcaster and Observers</H3>    no value is given, the default platform orientation takes
<P>Broadcasters and observers  <!--INDEX broadcasters;observers --> are a mechanism for making any number of elements aware of state and event information from a single, "broadcasting" element. That broadcasting element can be an actual <TT> <!--INDEX broadcaster element, XUL --> &lt;broadcaster&gt;</TT> or a regular element that broadcasts its state with special attributes. A common example of broadcasting is the disabling of a group of elements-a menu item and a separate button for viewing source, for example-when the source for a web page is not available.    effect. On Windows, the default is the right, and 
<P>The state of a broadcaster has to be changed explicitly for its observers to be updated:    <!--INDEX ENDRANGE==form controls:XUL;XUL (XML-based User-interface Language):forms, controls;controls, forms:XUL -->
<PRE>&lt;broadcasterset&gt;    on Unix, it's the center.</p>
     <h2><a name="77120"></a> Widget Interaction</h2>
     <p>At a level above the use of widgets 
     <!--INDEX STARTRANGE==widgets:interactions;interacting with widgets -->
     for different, singular functions in the application interface,
     Mozilla provides tools for hooking things together and creating
     application logic that can make your interfaces work more
     consistently and handle more complex tasks. If you have
     different elements in your application that execute the same
     function, for example, the command and observer system is the
     ideal way to facilitate reuse. Or you can use command sets to
     define command sets and key sets that can be overlaid and made
     available in different parts of your application, similar to
     how the cut and paste commands and others are spread over the
     Mozilla user interface but defined in a centralized file.</p>
     <h3><a name="77121"></a> Broadcaster and Observers</h3>
     <p>Broadcasters and observers 
     <!--INDEX broadcasters;observers --> are a mechanism for making
     any number of elements aware of state and event information
     from a single, "broadcasting" element. That broadcasting
     element can be an actual <tt>
     <!--INDEX broadcaster element, XUL --> &lt;broadcaster&gt;</tt>
     or a regular element that broadcasts its state with special
     attributes. A common example of broadcasting is the disabling
     of a group of elements-a menu item and a separate button for
     viewing source, for example-when the source for a web page is
     not available.</p>
     <p>The state of a broadcaster has to be changed explicitly for
     its observers to be updated:</p>
 <pre>
 &lt;broadcasterset&gt;
 &lt;broadcaster id="save_command" disabled="false"/&gt;  &lt;broadcaster id="save_command" disabled="false"/&gt;
&lt;/broadcasterset&gt;</PRE>&lt;/broadcasterset&gt;
<P>Once a broadcaster is defined, a XUL file may define elements that observe the broadcast command:</pre>
<PRE>&lt;button id="new" label="Save File" observes="save_command"/&gt;    <p>Once a broadcaster is defined, a XUL file may define
     elements that observe the broadcast command:</p>
 <pre>
 &lt;button id="new" label="Save File" observes="save_command"/&gt;
 &lt;key id="key_new" xulkey="true" key="s" observes="save_command" /&gt;  &lt;key id="key_new" xulkey="true" key="s" observes="save_command" /&gt;
&lt;menuitem id="new_menuitem" label="New" observes="save_command"/&gt;</PRE>&lt;menuitem id="new_menuitem" label="New" observes="save_command"/&gt;
<P>Observing elements can also be more specific about the attribute they want to mimic. This is done by using the <TT> <!--INDEX observes element, XUL --> &lt;observes&gt;</TT> element:</pre>
<PRE>&lt;menuitem id="new_menuitem" value="New" observes="open_new"/&gt;    <p>Observing elements can also be more specific about the
     attribute they want to mimic. This is done by using the <tt>
     <!--INDEX observes element, XUL --> &lt;observes&gt;</tt>
     element:</p>
 <pre>
 &lt;menuitem id="new_menuitem" value="New" observes="open_new"/&gt;
 &lt;observes element="open_new" attribute="disabled"/&gt;  &lt;observes element="open_new" attribute="disabled"/&gt;
&lt;/menu&gt;</PRE>&lt;/menu&gt;
<P>The <TT>element</TT> attribute associates the broadcaster and <TT>attribute</TT> tells the <TT>&lt;menuitem&gt;</TT> element to mimic the behavior of the broadcaster's <TT>"disabled"</TT> attribute.</pre>
<H3><A NAME="77122"></A> Commands</H3>    <p>The <tt>element</tt> attribute associates the broadcaster
<P>Any number of commands  <!--INDEX commands --> can be contained in a <TT> <!--INDEX commandset element, XUL --> &lt;commandset&gt;</TT>, and multiple sets can exist for different events in your application. It is also possible for sets to contain other command sets, mixed with commands or on their own. The idea is that there will be one base set that all other sets must inherit from; this base set can be defined in the top-level XUL file for your application. The following code has a command set that has its own commands and that pulls in a second set defined elsewhere (<TT>moreEditItems</TT>).    and <tt>attribute</tt> tells the <tt>&lt;menuitem&gt;</tt>
<PRE>&lt;commandset id="EditItems"    element to mimic the behavior of the broadcaster's
     <tt>"disabled"</tt> attribute.</p>
     <h3><a name="77122"></a> Commands</h3>
     <p>Any number of commands <!--INDEX commands --> can be
     contained in a <tt><!--INDEX commandset element, XUL -->
     &lt;commandset&gt;</tt>, and multiple sets can exist for
     different events in your application. It is also possible for
     sets to contain other command sets, mixed with commands or on
     their own. The idea is that there will be one base set that all
     other sets must inherit from; this base set can be defined in
     the top-level XUL file for your application. The following code
     has a command set that has its own commands and that pulls in a
     second set defined elsewhere (<tt>moreEditItems</tt>).</p>
 <pre>
 &lt;commandset id="EditItems"
 oncommandupdate="updateCommandsetItems(this)"  oncommandupdate="updateCommandsetItems(this)"
 commandupdater="true" events="select"&gt;  commandupdater="true" events="select"&gt;
 &lt;commandset id="moreEditItems" /&gt;  &lt;commandset id="moreEditItems" /&gt;
 &lt;command id="cmd_cut" oncommand="goDoCommand('cmd_cut');"/&gt;  &lt;command id="cmd_cut" oncommand="goDoCommand('cmd_cut');"/&gt;
 &lt;command id="cmd_copy" oncommand="goDoCommand('cmd_copy');"/&gt;  &lt;command id="cmd_copy" oncommand="goDoCommand('cmd_copy');"/&gt;
 &lt;command id="cmd_delete" oncommand="goDoCommand('cmd_delete');"/&gt;  &lt;command id="cmd_delete" oncommand="goDoCommand('cmd_delete');"/&gt;
&lt;/commandset&gt;</PRE>&lt;/commandset&gt;
<P>The command updater is the mechanism used to  <!--INDEX command updater -->  <!--INDEX events:command events, command updater and --> pass command events between widgets in the UI. When an event is carried out, the message filters through to the command sets. Thus in the example above, if the <TT>select</TT> <TT>event</TT> is activated, all UI elements in this <TT>commandset</TT> become active. For example, setting the <TT>disabled</TT> attribute on a command set for saving disables all functional elements depending on it-such as a menu item, a toolbar button, or a pop-up menu.</pre>
<P>There are a number of ways to trigger the command updater. First, associate a widget with a particular command by using the <TT>command</TT> attribute:    <p>The command updater is the mechanism used to 
<PRE>&lt;button id="cut-item" label="Cut" command="cmd_cut" enabled="true"/&gt;</PRE>    <!--INDEX command updater --> 
<P>When this button is clicked, the command (<TT>cmd_cut</TT>) is located and carried out, firing the <TT>goDoCommand</TT> routine for that particular command.    <!--INDEX events:command events, command updater and --> pass
<P>Alternatively, your application might have a select event for a text element or an image. When the select event is fired, the message filters through to the command set, which, in turn, updates (by using <TT>oncommandupdate</TT>) the widgets-associated button with the commands.    command events between widgets in the UI. When an event is
<P>The  <!--INDEX keyset element, XUL --> &lt;<TT>keyset&gt;</TT> element is a  <!--INDEX key elements, containers;elements:key elements, containers;containers:key elements --> container for key elements. Key elements are used to execute commands from a keystroke combination. The keys Ctrl-Shift-s can be defined to execute a Save As command in your application (and that command can actually be defined in a <TT>command</TT> element):    carried out, the message filters through to the command sets.
<PRE>&lt;key id="key_saveas" key="s" modifiers="control,shift" command="cmd_saveas"/&gt;</PRE>    Thus in the example above, if the <tt>select</tt>
<P>The key element has various special attributes like <TT>key</TT>, which is used to set an identifier shortcut key, or the <TT>modifiers</TT> attribute to set the trigger key. For example, <TT>modifiers="accel</TT>" would be the Ctrl key on Windows and GTK Unix platforms and the command button on Macintosh.    <tt>event</tt> is activated, all UI elements in this
<P><A HREF="#77062">Example 3-15</A> shows a simple window that  <!--INDEX ENDRANGE--widgets:interactions;interacting with widgets --> you can load up that has all element sets: commands, broadcasters, and keys.    <tt>commandset</tt> become active. For example, setting the
    <tt>disabled</tt> attribute on a command set for saving
Example 3-15<A NAME="77062"></A>    disables all functional elements depending on it-such as a menu
<I>Shortcut keys with command observers</I>    item, a toolbar button, or a pop-up menu.</p>
<PRE> &lt;?xml version="1.0"?&gt;    <p>There are a number of ways to trigger the command updater.
     First, associate a widget with a particular command by using
     the <tt>command</tt> attribute:</p>
 <pre>
 &lt;button id="cut-item" label="Cut" command="cmd_cut" enabled="true"/&gt;
 </pre>
     <p>When this button is clicked, the command (<tt>cmd_cut</tt>)
     is located and carried out, firing the <tt>goDoCommand</tt>
     routine for that particular command.</p>
     <p>Alternatively, your application might have a select event
     for a text element or an image. When the select event is fired,
     the message filters through to the command set, which, in turn,
     updates (by using <tt>oncommandupdate</tt>) the
     widgets-associated button with the commands.</p>
     <p>The <!--INDEX keyset element, XUL -->
     &lt;<tt>keyset&gt;</tt> element is a 
     <!--INDEX key elements, containers;elements:key elements, containers;containers:key elements -->
     container for key elements. Key elements are used to execute
     commands from a keystroke combination. The keys Ctrl-Shift-s
     can be defined to execute a Save As command in your application
     (and that command can actually be defined in a <tt>command</tt>
     element):</p>
 <pre>
 &lt;key id="key_saveas" key="s" modifiers="control,shift" command="cmd_saveas"/&gt;
 </pre>
     <p>The key element has various special attributes like
     <tt>key</tt>, which is used to set an identifier shortcut key,
     or the <tt>modifiers</tt> attribute to set the trigger key. For
     example, <tt>modifiers="accel</tt>" would be the Ctrl key on
     Windows and GTK Unix platforms and the command button on
     Macintosh.</p>
     <p><a href="#77062">Example 3-15</a> shows a simple window that
     <!--INDEX ENDRANGE==widgets:interactions;interacting with widgets -->
     you can load up that has all element sets: commands,
     broadcasters, and keys. Example 3-15<a name="77062"></a>
     <i>Shortcut keys with command observers</i></p>
 <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;window id="hello-goodbye"   &lt;window id="hello-goodbye"
      title="Hello Goodbye"       title="Hello Goodbye"
     xmlns:html="<A HREF="http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</A>"     xmlns:html="<a href=
     xmlns="<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>""http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
      xmlns="<a href=
 "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
      style="min-width:100px;min-height:100px;background-color:white;"&gt;       style="min-width:100px;min-height:100px;background-color:white;"&gt;
    &lt;broadcasterset id="broadcasterset"&gt;     &lt;broadcasterset id="broadcasterset"&gt;
      &lt;broadcaster id="cmd_hello"oncommand="alert('Hello There!');"/&gt;       &lt;broadcaster id="cmd_hello"oncommand="alert('Hello There!');"/&gt;
Line 600  Example 3-15<A NAME="77062"></A> Line 1496  Example 3-15<A NAME="77062"></A>
    &lt;textbox value="type ctl+shft+h"/&gt;     &lt;textbox value="type ctl+shft+h"/&gt;
    &lt;textbox value="type ctl+shft+g"/&gt;     &lt;textbox value="type ctl+shft+g"/&gt;
    &lt;spacer flex="1"/&gt;     &lt;spacer flex="1"/&gt;
 &lt;/window&gt;</PRE> &lt;/window&gt;
</pre>
<H2><A NAME="77123"></A> Content Panels</H2>    <h2><a name="77123"></a> Content Panels</h2>
<P>Content widgets allow you to  <!--INDEX STARTRANGE--control panels;content widgets, control panels --> load content into the UI for display. These widgets-<TT>browser</TT> and <TT>editor-</TT>provide a window into which you can load. In the standard browser, these documents can be written in HTML, XML, text, or other supported content types.    <p>Content widgets allow you to 
<H3><A NAME="77124"></A> Browser and IFrame</H3>    <!--INDEX STARTRANGE==control panels;content widgets, control panels -->
<P>The <TT> <!--INDEX browser element, XUL --> &lt;browser&gt;</TT> element displays online content and provides full browsing capabilities to your application, such as navigation features or maintaining a history.    load content into the UI for display. These
<PRE>&lt;browser id="content" type="content-primary" src="ch3.html"/&gt;</PRE>    widgets-<tt>browser</tt> and <tt>editor-</tt>provide a window
<P>The behind-the-scenes implementation for <TT>browser</TT> gives you access to certain interfaces that can be used in your scripts. These interfaces include:    into which you can load. In the standard browser, these
<UL><P><LI>nsIDocShell<P>    documents can be written in HTML, XML, text, or other supported
<P><LI>nsIWebNavigation<P>    content types.</p>
<P><LI>nsIMarkupDocumentViewer<P>    <h3><a name="77124"></a> Browser and IFrame</h3>
<P><LI>nsIContentViewerEdit<P>    <p>The <tt><!--INDEX browser element, XUL -->
<P><LI>nsIContentViewerFile<P>    &lt;browser&gt;</tt> element displays online content and
<P><LI>nsIWebBrowserFind<P>    provides full browsing capabilities to your application, such
<P><LI>nsIDocumentCharsetInfo<P></UL>    as navigation features or maintaining a history.</p>
<P>Without going into detail, these interfaces all provide sophisticated functionality for web browsing and other browser-like services, and are made available to JavaScript in the application interface. You can explore them further by looking at the interfaces themselves-at the IDL files of the same name in the Mozilla source tree.<pre>
<BLOCKQUOTE><CENTER><B>NOTE</B></CENTER>&lt;browser id="content" type="content-primary" src="ch3.html"/&gt;
<P>If you would like to learn more about these available interfaces, the best place to look is the source code. The two recommended files to start with are <I>browser.xml</I>, which shows how the interfaces are exposed, and <I>navigator.js</I>, which shows how they are used. Both files can be browsed on the online Mozilla Cross Reference, at <A HREF="http://lxr.mozilla.org">http://lxr.mozilla.org</A>.<P></BLOCKQUOTE></pre>
<P>An alternative to <TT>&lt;browser&gt;</TT> is the <TT> <!--INDEX iframe element, XUL --> &lt;iframe&gt;</TT>. It's similar to the browser widget in appearance, but better suited for simple or ephemeral content. It's often used as a preview window in HTML/XML editors and other WYSIWYG applications. iframes can also be good for dynamic document editing, as in the following example, in which the frame provides access to the document loaded as content. This can then be written to:    <p>The behind-the-scenes implementation for <tt>browser</tt>
<PRE>&lt;iframe id="simple-content" /&gt;</PRE>    gives you access to certain interfaces that can be used in your
<P>The document's <TT>open( )</TT>, <TT>write( )</TT>, and <TT>close( )</TT> methods, which are standard in the JavaScript engine, are used to write to the document:    scripts. These interfaces include:</p>
<PRE>var doc = window.frames[1].document;    <ul>
       <li>nsIDocShell</li>
       <li>nsIWebNavigation</li>
       <li>nsIMarkupDocumentViewer</li>
       <li>nsIContentViewerEdit</li>
       <li>nsIContentViewerFile</li>
       <li>nsIWebBrowserFind</li>
       <li>nsIDocumentCharsetInfo</li>
     </ul>
     <p>Without going into detail, these interfaces all provide
     sophisticated functionality for web browsing and other
     browser-like services, and are made available to JavaScript in
     the application interface. You can explore them further by
     looking at the interfaces themselves-at the IDL files of the
     same name in the Mozilla source tree.</p>
     <blockquote>
       <div class="c11">
         NOTE
       </div>
       <p>If you would like to learn more about these available
       interfaces, the best place to look is the source code. The
       two recommended files to start with are <i>browser.xml</i>,
       which shows how the interfaces are exposed, and
       <i>navigator.js</i>, which shows how they are used. Both
       files can be browsed on the online Mozilla Cross Reference,
       at <a href=
       "http://lxr.mozilla.org">http://lxr.mozilla.org</a>.</p>
     </blockquote>
     <p>An alternative to <tt>&lt;browser&gt;</tt> is the <tt>
     <!--INDEX iframe element, XUL --> &lt;iframe&gt;</tt>. It's
     similar to the browser widget in appearance, but better suited
     for simple or ephemeral content. It's often used as a preview
     window in HTML/XML editors and other WYSIWYG applications.
     iframes can also be good for dynamic document editing, as in
     the following example, in which the frame provides access to
     the document loaded as content. This can then be written
     to:</p>
 <pre>
 &lt;iframe id="simple-content" /&gt;
 </pre>
     <p>The document's <tt>open( )</tt>, <tt>write( )</tt>, and
     <tt>close( )</tt> methods, which are standard in the JavaScript
     engine, are used to write to the document:</p>
 <pre>
 var doc = window.frames[1].document;
 doc.open( );  doc.open( );
 doc.write("&lt;html&gt;&lt;body&gt;Come fly with me ...&lt;/body&gt;&lt;/html&gt;");  doc.write("&lt;html&gt;&lt;body&gt;Come fly with me ...&lt;/body&gt;&lt;/html&gt;");
doc.close( );</PRE>doc.close( );
<P>In this code snippet, you get a handle to the particular frame that you want by using <TT>window.frames</TT>, which returns an array of all frames contained in a document. There can be multiple frames in a document, which are indexed. Here it is assumed that we get the second (1 in a zero-based array) frame. The <TT>doc</TT> variable has a reference to the content area and uses the methods available on the <TT>document</TT> object to write content-in this case, HTML.</pre>
<P>Ideas for using content panels include:<A NAME="b316"></A><A HREF="#316">[*]</A>    <p>In this code snippet, you get a handle to the particular
<UL><P><LI>Create HTML or XML help pages for your application and upload them in a ready-made help browser.<P>    frame that you want by using <tt>window.frames</tt>, which
<P><LI>Create a previewer: test your XML, HTML, or CSS layout and styling in Gecko--one of the most standards-compliant layout engines around.<P>    returns an array of all frames contained in a document. There
<P><LI>A slight variation of the previous use, you could use mini-versions inline in dialogs to load up examples that change depending on the selection of the user from a number of choices (a font previewer, for example).<P>    can be multiple frames in a document, which are indexed. Here
<P><LI>Pop ups contained in a window for display of web content.<P></UL>    it is assumed that we get the second (1 in a zero-based array)
<H3><A NAME="77125"></A> Editor</H3>    frame. The <tt>doc</tt> variable has a reference to the content
<P>The <TT> <!--INDEX editor element, XUL --> &lt;editor&gt;</TT> element loads editable content and can handle text or HTML editing. A good example of its usage is in Mozilla Composer, the HTML editor that comes bundled with Mozilla.    area and uses the methods available on the <tt>document</tt>
<P>The <TT>&lt;editor&gt;</TT> tag creates  <!--INDEX nsEditorBoxObject interface --> an instance of the <I>nsEditorBoxObject</I> interface when it's initialized. From that point, you can use JavaScript (via the <TT>element.editorShell</TT> property) to get to the <TT>editorShell</TT> methods for carrying out editing on the loaded document.    object to write content-in this case, HTML.</p>
<P>The editor is also used in the various XUL and HTML text widgets in Mozilla, such as <TT>textbox</TT> and HTML forms, and for composing HTML messages in Mail and News. The text widgets differ from the full-blown <TT>editor</TT> because they act on a subtree of the document. Also, text widgets have limited text-editing services.    <p>Ideas for using content panels include:<a name="b316"></a><a
<P>Uses for the editor, both practical and speculative, include:    href="#316">[*]</a></p>
<UL><P><LI>Plain text editor<P>    <ul>
<P><LI>Web forms editor<P>      <li>Create HTML or XML help pages for your application and
<P><LI>An HTML-enabled bulletin board, a guestbook entry form, or a Wiki that is a web interface collaboration  <!--INDEX ENDRANGE--control panels;content widgets, control panels --> area for posting comments<P>      upload them in a ready-made help browser.</li>
<P><LI>Instant Messaging<P></UL>      <li>Create a previewer: test your XML, HTML, or CSS layout
<BLOCKQUOTE><HR><B>Keeping Track in Multiframe Documents</B>      and styling in Gecko--one of the most standards-compliant
<P>The content contained in a <TT>&lt;browser&gt;</TT>, <TT>&lt;iframe&gt;</TT>, and <TT>&lt;editor&gt;</TT> is treated as a separate document. At times, you may want to access that specific content, so how do you keep track of different content?      layout engines around.</li>
<P>To return all the content frames in a document, you can use:      <li>A slight variation of the previous use, you could use
<PRE>var contentAreas = content.frames;</PRE>      mini-versions inline in dialogs to load up examples that
There are two ways to access specific content in a script: through the index of the frame within the containing document or by using the <TT>id</TT> attribute.      change depending on the selection of the user from a number
<P>By index, starting at 0:      of choices (a font previewer, for example).</li>
<PRE>var content = window.frames[ 1 ];</PRE>      <li>Pop ups contained in a window for display of web
By <TT>id</TT>:      content.</li>
<PRE>var content = window.frames[ contentId ];</PRE>    </ul>
This code returns the second frame.    <h3><a name="77125"></a> Editor</h3>
<P>To flag one as default, use the <TT>type</TT> attribute and give it a value.    <p>The <tt><!--INDEX editor element, XUL -->
<PRE>&lt;iframe id="print-panel" type="content-primary" src="about:blank" flex="1""/&gt;</PRE>    &lt;editor&gt;</tt> element loads editable content and can
This code allows quick access to the default via the <TT>window.content</TT> property:    handle text or HTML editing. A good example of its usage is in
<PRE>window.content.print( );</PRE>    Mozilla Composer, the HTML editor that comes bundled with
<HR></BLOCKQUOTE>    Mozilla.</p>
    <p>The <tt>&lt;editor&gt;</tt> tag creates 
<H2><A NAME="77126"></A> The Box Model</H2>    <!--INDEX nsEditorBoxObject interface --> an instance of the
<P>The <I>box model</I> is the  <!--INDEX STARTRANGE--box model, XUL;XUL (XML-based User-interface Language):box model --> basic layout mechanism in XUL. Although it's possible to position your widgets in a window by using layout attributes of the <TT>window</TT> (a box-based container), using boxes allows you to arrange, nest, and position your widgets the way you want. The box model defines:    <i>nsEditorBoxObject</i> interface when it's initialized. From
<UL><P><LI>How much space elements take up in relation to their siblings and containing elements<P>    that point, you can use JavaScript (via the
<P><LI>The orientation of elements<P>    <tt>element.editorShell</tt> property) to get to the
<P><LI>The relationship of elements to one another<P></UL>    <tt>editorShell</tt> methods for carrying out editing on the
<P>Space can be determined in a number of ways. You can constrain size by putting fixed sizes on windows or the widgets contained therein. Or you can let the natural sizes take effect and let the elements size themselves according to their content. Applying boxes to your layout uses space efficiently and optimizes the layout of your XUL windows and dialogs.    loaded document.</p>
<H3><A NAME="77127"></A> Box Attributes</H3>    <p>The editor is also used in the various XUL and HTML text
<P>The XUL element <TT>&lt;box&gt;</TT> defines a  <!--INDEX boxes:attributes;attributes:boxes --> number  <!--INDEX box element, XUL --> of attributes and some implicit behavior for layout. Boxes can be oriented within other boxes to define the general layout of the UI. Some boxes stretch to fit the space available within the top-level window or their containing element; others take only as much space as needed to display their own children.    widgets in Mozilla, such as <tt>textbox</tt> and HTML forms,
<P>Attributes on the box and its child elements determine the flexibility of the content contained within the box, the way that windows are resized, and the alignment of elements, as <A HREF="#77032">Table 3-4</A> describes.    and for composing HTML messages in Mail and News. The text
    widgets differ from the full-blown <tt>editor</tt> because they
<P><I>Table 3-4: <A NAME="77032"></A></I>    act on a subtree of the document. Also, text widgets have
<I>Common box attributes</I>    limited text-editing services.</p>
<P><TABLE WIDTH=100% BORDER=1><TR><TD><B>  Attribute</B></TD> <TD><B>  Values</B></TD> <TD><B>  Default value</B></TD> <TD><B>  Description</B></TD></TR>    <p>Uses for the editor, both practical and speculative,
<TR><TD>  align</TD>     <TD>  start | end | center | baseline | stretch | inherit</TD>     <TD>  stretch</TD>     <TD>  Determines how the children are aligned in conjunction with the box's orientation</TD></TR>    include:</p>
<TR><TD>  flex</TD>     <TD>  &lt;number&gt; | inherit</TD>     <TD>  0.0</TD>     <TD>  Determines the flexibility of the contained elements, which depends on their particular flex values</TD></TR>    <ul>
<TR><TD>  style</TD>     <TD>  CSS property and value</TD>     <TD>  N/A</TD>     <TD>  Applies CSS style settings to the box</TD></TR>      <li>Plain text editor</li>
<TR><TD>  orient</TD>     <TD>  horizontal | vertical | inline-axis | block-axis | inherit</TD>     <TD>  inline-axis</TD>     <TD>  Determines the layout of the children of the box</TD></TR>      <li>Web forms editor</li>
<TR><TD>  pack</TD>     <TD>  start | end | center | justify | inherit</TD>     <TD>  start</TD>     <TD>  Determines the use of remaining whitespace once all other objects are stretched to their full size</TD></TR>      <li>An HTML-enabled bulletin board, a guestbook entry form,
<TR><TD>  direction</TD>     <TD>  normal | reverse | inherit</TD>     <TD>  normal</TD>     <TD>  Determines the direction of the children in the box</TD></TR>      or a Wiki that is a web interface collaboration 
<TR><TD>  ordinal-group</TD>     <TD>  &lt;integer&gt; | inherit</TD>     <TD>  1</TD>    <TD>  Controls the order in which widgets appear in a box</TD></TR></TABLE><P>      <!--INDEX ENDRANGE==control panels;content widgets, control panels -->
      area for posting comments</li>
<P>The attribute names in <A HREF="#77032">Table 3-4</A> (with the exception of <TT>style</TT>) are defined directly on the box. But there are       <li>Instant Messaging</li>
also CSS versions of  <!--INDEX stylesheets:box attributes --> these properties that use the prefix <TT>box-pack</TT> becomes <TT>box-pack</TT>     </ul>
when it's defined in CSS, for example. These properties are not part of the CSS specification, so you may need to go one step further and use the format <TT>-moz-box-pack</TT>. These special extensions to CSS are described in the section <A HREF="ch04.html#77083">"Special Mozilla Extensions</A>" in <A HREF="ch04.html#37942">Chapter 4</A>.    <blockquote>
<P>The most commonly used attributes  <!--INDEX orient attribute, boxes;align attribute, boxes;pack attribute, boxes --> are <TT>orient</TT>, <TT>align</TT>, and <TT>pack</TT>. The orientation of the children of a box can be either vertical or horizontal. The default is horizontal for a plain <TT>&lt;box&gt;</TT>, but not for all box containers (<TT>&lt;groupbox&gt;</TT> is vertical). The <TT>&lt;vbox&gt;</TT> and <TT>&lt;hbox&gt;</TT> conveniences were created to bypass the use of this attribute and increase box layout efficiency in the rendering phase.      <hr>
<P>Here is a look at how the pack and align properties can effect the layout of widgets. First, here is a bit of code with no constraints:      <b>Keeping Track in Multiframe Documents</b> 
<PRE>&lt;vbox style="width: 90px; height: 90px"&gt;      <p>The content contained in a <tt>&lt;browser&gt;</tt>,
       <tt>&lt;iframe&gt;</tt>, and <tt>&lt;editor&gt;</tt> is
       treated as a separate document. At times, you may want to
       access that specific content, so how do you keep track of
       different content?</p>
       <p>To return all the content frames in a document, you can
       use:</p>
 <pre>
 var contentAreas = content.frames;
 </pre>
       There are two ways to access specific content in a script:
       through the index of the frame within the containing document
       or by using the <tt>id</tt> attribute. 
       <p>By index, starting at 0:</p>
 <pre>
 var content = window.frames[ 1 ];
 </pre>
       By <tt>id</tt>: 
 <pre>
 var content = window.frames[ contentId ];
 </pre>
       This code returns the second frame. 
       <p>To flag one as default, use the <tt>type</tt> attribute
       and give it a value.</p>
 <pre>
 &lt;iframe id="print-panel" type="content-primary" src="about:blank" flex="1""/&gt;
 </pre>
       This code allows quick access to the default via the
       <tt>window.content</tt> property: 
 <pre>
 window.content.print( );
 </pre>
       <hr>
     </blockquote>
     <h2><a name="77126"></a> The Box Model</h2>
     <p>The <i>box model</i> is the 
     <!--INDEX STARTRANGE==box model, XUL;XUL (XML-based User-interface Language):box model -->
     basic layout mechanism in XUL. Although it's possible to
     position your widgets in a window by using layout attributes of
     the <tt>window</tt> (a box-based container), using boxes allows
     you to arrange, nest, and position your widgets the way you
     want. The box model defines:</p>
     <ul>
       <li>How much space elements take up in relation to their
       siblings and containing elements</li>
       <li>The orientation of elements</li>
       <li>The relationship of elements to one another</li>
     </ul>
     <p>Space can be determined in a number of ways. You can
     constrain size by putting fixed sizes on windows or the widgets
     contained therein. Or you can let the natural sizes take effect
     and let the elements size themselves according to their
     content. Applying boxes to your layout uses space efficiently
     and optimizes the layout of your XUL windows and dialogs.</p>
     <h3><a name="77127"></a> Box Attributes</h3>
     <p>The XUL element <tt>&lt;box&gt;</tt> defines a 
     <!--INDEX boxes:attributes;attributes:boxes --> number 
     <!--INDEX box element, XUL --> of attributes and some implicit
     behavior for layout. Boxes can be oriented within other boxes
     to define the general layout of the UI. Some boxes stretch to
     fit the space available within the top-level window or their
     containing element; others take only as much space as needed to
     display their own children.</p>
     <p>Attributes on the box and its child elements determine the
     flexibility of the content contained within the box, the way
     that windows are resized, and the alignment of elements, as <a
     href="#77032">Table 3-4</a> describes.</p>
     <p><i>Table 3-4: <a name="77032"></a></i> <i>Common box
     attributes</i></p>
     <table width="100%" border="1">
       <tr>
         <td><b>Attribute</b></td>
         <td><b>Values</b></td>
         <td><b>Default value</b></td>
         <td><b>Description</b></td>
       </tr>
       <tr>
         <td>align</td>
         <td>start | end | center | baseline | stretch |
         inherit</td>
         <td>stretch</td>
         <td>Determines how the children are aligned in conjunction
         with the box's orientation</td>
       </tr>
       <tr>
         <td>flex</td>
         <td>&lt;number&gt; | inherit</td>
         <td>0.0</td>
         <td>Determines the flexibility of the contained elements,
         which depends on their particular flex values</td>
       </tr>
       <tr>
         <td>style</td>
         <td>CSS property and value</td>
         <td>N/A</td>
         <td>Applies CSS style settings to the box</td>
       </tr>
       <tr>
         <td>orient</td>
         <td>horizontal | vertical | inline-axis | block-axis |
         inherit</td>
         <td>inline-axis</td>
         <td>Determines the layout of the children of the box</td>
       </tr>
       <tr>
         <td>pack</td>
         <td>start | end | center | justify | inherit</td>
         <td>start</td>
         <td>Determines the use of remaining whitespace once all
         other objects are stretched to their full size</td>
       </tr>
       <tr>
         <td>direction</td>
         <td>normal | reverse | inherit</td>
         <td>normal</td>
         <td>Determines the direction of the children in the
         box</td>
       </tr>
       <tr>
         <td>ordinal-group</td>
         <td>&lt;integer&gt; | inherit</td>
         <td>1</td>
         <td>Controls the order in which widgets appear in a
         box</td>
       </tr>
     </table>
     <p>The attribute names in <a href="#77032">Table 3-4</a> (with
     the exception of <tt>style</tt>) are defined directly on the
     box. But there are also CSS versions of 
     <!--INDEX stylesheets:box attributes --> these properties that
     use the prefix <tt>box-pack</tt> becomes <tt>box-pack</tt> when
     it's defined in CSS, for example. These properties are not part
     of the CSS specification, so you may need to go one step
     further and use the format <tt>-moz-box-pack</tt>. These
     special extensions to CSS are described in the section <a href=
     "ch04.html#77083">"Special Mozilla Extensions</a>" in <a href=
     "ch04.html#37942">Chapter 4</a>.</p>
     <p>The most commonly used attributes 
     <!--INDEX orient attribute, boxes;align attribute, boxes;pack attribute, boxes -->
     are <tt>orient</tt>, <tt>align</tt>, and <tt>pack</tt>. The
     orientation of the children of a box can be either vertical or
     horizontal. The default is horizontal for a plain
     <tt>&lt;box&gt;</tt>, but not for all box containers
     (<tt>&lt;groupbox&gt;</tt> is vertical). The
     <tt>&lt;vbox&gt;</tt> and <tt>&lt;hbox&gt;</tt> conveniences
     were created to bypass the use of this attribute and increase
     box layout efficiency in the rendering phase.</p>
     <p>Here is a look at how the pack and align properties can
     effect the layout of widgets. First, here is a bit of code with
     no constraints:</p>
 <pre>
 &lt;vbox style="width: 90px; height: 90px"&gt;
 &lt;button label="Pack Me!" /&gt;  &lt;button label="Pack Me!" /&gt;
 &lt;label value="This text is naturally aligned to the left" /&gt;  &lt;label value="This text is naturally aligned to the left" /&gt;
&lt;/vbox&gt;</PRE>&lt;/vbox&gt;
<P>This XUL does not tell the button and text inside where to go, so they occupy the default positions shown in <A HREF="#77018">Figure 3-9</A>.</pre>
<P><CENTER><IMG SRC="foo.gif"></CENTER>    <p>This XUL does not tell the button and text inside where to
<P><I>Figure 3-9: <A NAME="77018"></A></I>    go, so they occupy the default positions shown in <a href=
<I>Default box positioning</I>    "#77018">Figure 3-9</a>.</p>
    <div class="c10">
<P>Here is a changed <TT>box</TT> definition with the <TT>align</TT> and <TT>pack</TT> attributes set:      <img src="foo.gif">
<PRE>&lt;vbox style="width: 90px; height: 90px" align="right" pack="center"&gt;</PRE>    </div>
<P>A noticeable visual difference can be seen in <A HREF="#77020">Figure 3-10</A>.    <p><i>Figure 3-9: <a name="77018"></a></i> <i>Default box
<P><CENTER><IMG SRC="foo.gif"></CENTER>    positioning</i></p>
Figure 3-10<A NAME="77020"></A>    <p>Here is a changed <tt>box</tt> definition with the
<I>Box packing and alignment effects</I>    <tt>align</tt> and <tt>pack</tt> attributes set:</p>
<pre>
<P>The <TT>align</TT> value moves the items to the right of the <TT>box</TT>, while simultaneously constraining the <TT>button</TT> to fit only the text <TT>label</TT>, making better use of space. <TT>pack</TT> centers both the items horizontally.&lt;vbox style="width: 90px; height: 90px" align="right" pack="center"&gt;
<H3><A NAME="77128"></A> Box-Like Containers</H3></pre>
<P>The basic XUL box is represented by  <!--INDEX box-like containers;containers:box-like containers --> the <TT> <!--INDEX box element, XUL --> &lt;box&gt;</TT>, <TT> <!--INDEX vbox element, XUL --> &lt;vbox&gt;</TT>, and <TT> <!--INDEX hbox element, XUL --> &lt;hbox&gt;</TT> elements, but several more XUL elements are designed as box-like containers. They include:    <p>A noticeable visual difference can be seen in <a href=
<UL><P><LI><!--INDEX radiogroup element, XUL --> &lt;radiogroup&gt;<P>    "#77020">Figure 3-10</a>.</p>
<P><LI><!--INDEX scrollbox element, XUL --> &lt;scrollbox&gt;<P>    <div class="c10">
<P><LI><!--INDEX tabbox element, XUL --> &lt;tabbox&gt;<P>      <img src="foo.gif">
<P><LI><!--INDEX groupbox element, XUL --> &lt;groupbox&gt;<P>    </div>
<P><LI><!--INDEX toolbox element, XUL --> &lt;toolbox&gt;<P>    Figure 3-10<a name="77020"></a> <i>Box packing and alignment
<P><LI><!--INDEX stack element, XUL --> &lt;stack&gt;<P>    effects</i> 
<P><LI><!--INDEX deck element, XUL --> &lt;deck&gt;<P>    <p>The <tt>align</tt> value moves the items to the right of the
<P><LI><!--INDEX listbox element, XUL --> &lt;listbox&gt;<P>    <tt>box</tt>, while simultaneously constraining the
<P><LI><!--INDEX popup element, XUL --> &lt;popup&gt;<P>    <tt>button</tt> to fit only the text <tt>label</tt>, making
<P><LI><!--INDEX statusbar element, XUL --> &lt;statusbar&gt;<P></UL>    better use of space. <tt>pack</tt> centers both the items
<P>Descriptions of the tabbed box and the group box follow. Additional information on other box widgets can be found in the XUL element reference     horizontally.</p>
in <A HREF="appc.html#72321">Appendix C</A>.    <h3><a name="77128"></a> Box-Like Containers</h3>
<H4><A NAME="77129"></A> Tab box</H4>    <p>The basic XUL box is represented by 
<P>Tab  <!--INDEX tab boxes;boxes:tab boxes --> boxes may contain only <TT> <!--INDEX tabs element, XUL --> &lt;tabs&gt;</TT> and <TT> <!--INDEX tabpanels element, XUL --> &lt;tabpanels&gt;</TT> elements, as shown in <A HREF="#77064">Example 3-16</A>. Beyond this, there is no restriction on the content that can go into the panels themselves. For the panels to display content properly, there have to be the same number of children and tabs in the tab panels.    <!--INDEX box-like containers;containers:box-like containers -->
    the <tt><!--INDEX box element, XUL --> &lt;box&gt;</tt>, <tt>
Example 3-16<A NAME="77064"></A>    <!--INDEX vbox element, XUL --> &lt;vbox&gt;</tt>, and <tt>
<I>Tabbed panels</I>    <!--INDEX hbox element, XUL --> &lt;hbox&gt;</tt> elements, but
<PRE> &lt;tabbox orient="vertical" flex="1"&gt;    several more XUL elements are designed as box-like containers.
     They include:</p>
     <ul>
       <li>
       <!--INDEX radiogroup element, XUL -->&lt;radiogroup&gt;</li>
       <li>
       <!--INDEX scrollbox element, XUL -->&lt;scrollbox&gt;</li>
       <li><!--INDEX tabbox element, XUL -->&lt;tabbox&gt;</li>
       <li><!--INDEX groupbox element, XUL -->&lt;groupbox&gt;</li>
       <li><!--INDEX toolbox element, XUL -->&lt;toolbox&gt;</li>
       <li><!--INDEX stack element, XUL -->&lt;stack&gt;</li>
       <li><!--INDEX deck element, XUL -->&lt;deck&gt;</li>
       <li><!--INDEX listbox element, XUL -->&lt;listbox&gt;</li>
       <li><!--INDEX popup element, XUL -->&lt;popup&gt;</li>
       <li>
       <!--INDEX statusbar element, XUL -->&lt;statusbar&gt;</li>
     </ul>
     <p>Descriptions of the tabbed box and the group box follow.
     Additional information on other box widgets can be found in the
     XUL element reference in <a href="appc.html#72321">Appendix
     C</a>.</p>
     <h4><a name="77129"></a> Tab box</h4>
     <p>Tab <!--INDEX tab boxes;boxes:tab boxes --> boxes may
     contain only <tt><!--INDEX tabs element, XUL -->
     &lt;tabs&gt;</tt> and <tt><!--INDEX tabpanels element, XUL -->
     &lt;tabpanels&gt;</tt> elements, as shown in <a href=
     "#77064">Example 3-16</a>. Beyond this, there is no restriction
     on the content that can go into the panels themselves. For the
     panels to display content properly, there have to be the same
     number of children and tabs in the tab panels. Example 3-16<a
     name="77064"></a> <i>Tabbed panels</i></p>
 <pre>
  &lt;tabbox orient="vertical" flex="1"&gt;
    &lt;tabs&gt;     &lt;tabs&gt;
      &lt;tab label="Fish" /&gt;       &lt;tab label="Fish" /&gt;
      &lt;tab label="Birds" /&gt;       &lt;tab label="Birds" /&gt;
Line 729  Example 3-16<A NAME="77064"></A> Line 1852  Example 3-16<A NAME="77064"></A>
      &lt;button label="Fly"/&gt;       &lt;button label="Fly"/&gt;
      &lt;button label="Hack"/&gt;       &lt;button label="Hack"/&gt;
    &lt;/tabpanels&gt;     &lt;/tabpanels&gt;
 &lt;/tabbox&gt;</PRE> &lt;/tabbox&gt;
</pre>
<P><A HREF="#77064">Example 3-16</A> shows the main controls used to create a simple three-tab control with content elements on each panel. The tabs are associated with the appropriate panels by their order within the containing element.    <p><a href="#77064">Example 3-16</a> shows the main controls
<H4><A NAME="77130"></A> Status bar</H4>    used to create a simple three-tab control with content elements
<P>A status bar is a  <!--INDEX boxes:status bar;status bar --> horizontal box that appears on the bottom of the screen in many Mozilla applications, including the Mozilla browser itself. It can be used for the same purpose in your application if you need it. The <TT> <!--INDEX statusbar element, XUL --> &lt;statusbar&gt;</TT> element typically contains icon images and text within one or more <TT>&lt;statusbarpanel&gt;</TT> elements:    on each panel. The tabs are associated with the appropriate
<PRE>&lt;statusbar id="ch3-bar" persist="collapsed"&gt;    panels by their order within the containing element.</p>
     <h4><a name="77130"></a> Status bar</h4>
     <p>A status bar is a <!--INDEX boxes:status bar;status bar -->
     horizontal box that appears on the bottom of the screen in many
     Mozilla applications, including the Mozilla browser itself. It
     can be used for the same purpose in your application if you
     need it. The <tt><!--INDEX statusbar element, XUL -->
     &lt;statusbar&gt;</tt> element typically contains icon images
     and text within one or more <tt>&lt;statusbarpanel&gt;</tt>
     elements:</p>
 <pre>
 &lt;statusbar id="ch3-bar" persist="collapsed"&gt;
 &lt;statusbarpanel class="statusbarpanel-iconic" id="book-icon"/&gt;  &lt;statusbarpanel class="statusbarpanel-iconic" id="book-icon"/&gt;
 &lt;statusbarpanel id="status-text" label="Thanks for reading chapter 3"  &lt;statusbarpanel id="status-text" label="Thanks for reading chapter 3"
 flex="1" crop="right"/&gt;  flex="1" crop="right"/&gt;
 &lt;statusbarpanel class="statusbarpanel-iconic" id="book-icon-2"/&gt;  &lt;statusbarpanel class="statusbarpanel-iconic" id="book-icon-2"/&gt;
&lt;/statusbar&gt;</PRE>&lt;/statusbar&gt;
<P>As a box, the statusbar behaves like any other box widget. The panels constrain to their natural sizing and layout attributes such as flex situate all elements within. In this example, the icons appear to the left and right of the bar, while the flexed text panel takes up the remaining space.</pre>
<H3><A NAME="77131"></A> Additional Box Features</H3>    <p>As a box, the statusbar behaves like any other box widget.
<P>Boxes work in  <!--INDEX boxes:separator;separator element, XUL --> concert with a few other special elements, including the <TT>&lt;separator&gt;</TT> and <TT>&lt;spacer&gt;</TT>. These  <!--INDEX boxes:spacers;spacer element, XUL --> two elements create space between widgets in a box and can be horizontal or vertical depending on the orientation of the box. The separator is a visible divider and the spacer is invisible space. The default size for both of them is small, but they can be given <TT>flex</TT>, <TT>width</TT>, and <TT>height</TT> values like other elements. Used correctly, they can make all the difference in how your UI looks.    The panels constrain to their natural sizing and layout
<H4><A NAME="77132"></A> Visibility</H4>    attributes such as flex situate all elements within. In this
<P>You can control  <!--INDEX boxes:visibility;visibility of boxes --> the visibility of a box by showing and hiding it in different circumstances-toggling the appearance of an advanced panel in a dialog, for example, or text that appears after a user selects something. One way to control visibility is to use the <TT>collapsed</TT> attribute to cede the space taken by the box to surrounding elements:    example, the icons appear to the left and right of the bar,
<PRE>&lt;box flex="1" collapsed="true" /&gt;</PRE>    while the flexed text panel takes up the remaining space.</p>
<P>You can also set the CSS <TT>display</TT> property to <TT>none</TT>:    <h3><a name="77131"></a> Additional Box Features</h3>
<PRE>&lt;box flex="1" style="display: none;" /&gt;</PRE>    <p>Boxes work in 
<P>The document is rendered as though the element did not exist in the document tree. If you want the space to be maintained but the element to remain invisible, you can use the CSS <TT>visibility</TT> property:    <!--INDEX boxes:separator;separator element, XUL --> concert
<PRE>&lt;box flex="1" style="visibility: hidden;" /&gt;</PRE>    with a few other special elements, including the
<P>Rendering the space but not the content avoids flicker and UI wobbles when content is being shown and hidden intermittently.    <tt>&lt;separator&gt;</tt> and <tt>&lt;spacer&gt;</tt>. These 
<H4><A NAME="77133"></A> Overflow</H4>    <!--INDEX boxes:spacers;spacer element, XUL --> two elements
<P>A value of <TT>scroll</TT>  <!--INDEX overflow, scrollbars;scrollbars, overflow --> or auto for the CSS <TT>overflow</TT> property ensures that a scrollbar appears and that the content can be accessed even when it can't be displayed. A value of <TT>hidden</TT> hides the content outside of the box. The content is not clipped if this value is set to <TT>visible</TT>, but it will be visible outside the box.    create space between widgets in a box and can be horizontal or
<PRE>&lt;vbox flex="1" style="height:39px;overflow: auto;"&gt;</PRE>    vertical depending on the orientation of the box. The separator
<P>This snippet constrains the height of the box but displays a scrollbar when the content exceeds the available space.    is a visible divider and the spacer is invisible space. The
<H3><A NAME="77134"></A> Stacks and Decks</H3>    default size for both of them is small, but they can be given
<P>A variant and  <!--INDEX stacks;decks --> special model of the <TT>box</TT> is available in the <TT>stack</TT> and <TT>deck</TT> elements. Both are boxes, but they lay their children out one on top of the other like a stack of crates or a deck of cards, rather than sequentially.    <tt>flex</tt>, <tt>width</tt>, and <tt>height</tt> values like
<P>A <TT>stack</TT> shows all its levels at once. If you have transparency or extra space on one level, you can see  <!--INDEX transparency, stacks and;stacks:transparency;levels:stacks and;stacks:levels and --> underneath. Stacks are useful when you want to add shadows in your content or if you want to create transparent layering effects. If you have a bird's eye view of XUL content, you can see the elements on each layer flowing into each other, like the text on top of an image in <A HREF="#77022">Figure 3-11</A>.    other elements. Used correctly, they can make all the
<PRE>&lt;stack&gt;    difference in how your UI looks.</p>
     <h4><a name="77132"></a> Visibility</h4>
     <p>You can control 
     <!--INDEX boxes:visibility;visibility of boxes --> the
     visibility of a box by showing and hiding it in different
     circumstances-toggling the appearance of an advanced panel in a
     dialog, for example, or text that appears after a user selects
     something. One way to control visibility is to use the
     <tt>collapsed</tt> attribute to cede the space taken by the box
     to surrounding elements:</p>
 <pre>
 &lt;box flex="1" collapsed="true" /&gt;
 </pre>
     <p>You can also set the CSS <tt>display</tt> property to
     <tt>none</tt>:</p>
 <pre>
 &lt;box flex="1" style="display: none;" /&gt;
 </pre>
     <p>The document is rendered as though the element did not exist
     in the document tree. If you want the space to be maintained
     but the element to remain invisible, you can use the CSS
     <tt>visibility</tt> property:</p>
 <pre>
 &lt;box flex="1" style="visibility: hidden;" /&gt;
 </pre>
     <p>Rendering the space but not the content avoids flicker and
     UI wobbles when content is being shown and hidden
     intermittently.</p>
     <h4><a name="77133"></a> Overflow</h4>
     <p>A value of <tt>scroll</tt> 
     <!--INDEX overflow, scrollbars;scrollbars, overflow --> or auto
     for the CSS <tt>overflow</tt> property ensures that a scrollbar
     appears and that the content can be accessed even when it can't
     be displayed. A value of <tt>hidden</tt> hides the content
     outside of the box. The content is not clipped if this value is
     set to <tt>visible</tt>, but it will be visible outside the
     box.</p>
 <pre>
 &lt;vbox flex="1" style="height:39px;overflow: auto;"&gt;
 </pre>
     <p>This snippet constrains the height of the box but displays a
     scrollbar when the content exceeds the available space.</p>
     <h3><a name="77134"></a> Stacks and Decks</h3>
     <p>A variant and <!--INDEX stacks;decks --> special model of
     the <tt>box</tt> is available in the <tt>stack</tt> and
     <tt>deck</tt> elements. Both are boxes, but they lay their
     children out one on top of the other like a stack of crates or
     a deck of cards, rather than sequentially.</p>
     <p>A <tt>stack</tt> shows all its levels at once. If you have
     transparency or extra space on one level, you can see 
     <!--INDEX transparency, stacks and;stacks:transparency;levels:stacks and;stacks:levels and -->
     underneath. Stacks are useful when you want to add shadows in
     your content or if you want to create transparent layering
     effects. If you have a bird's eye view of XUL content, you can
     see the elements on each layer flowing into each other, like
     the text on top of an image in <a href="#77022">Figure
     3-11</a>.</p>
 <pre>
 &lt;stack&gt;
 &lt;image src="logo5.gif"/&gt;  &lt;image src="logo5.gif"/&gt;
 &lt;label value="BUZZ ..."  &lt;label value="BUZZ ..."
 style="font-weight:bold; font-size: large" top="70px" left="140px"/&gt;  style="font-weight:bold; font-size: large" top="70px" left="140px"/&gt;
&lt;/stack&gt;</PRE>&lt;/stack&gt;
<P><CENTER><IMG SRC="foo.gif"></CENTER></pre>
Figure 3-11<A NAME="77022"></A>    <div class="c10">
<I>Text stacked on an image</I>      <img src="foo.gif">
    </div>
<P>Decks show  <!--INDEX levels:decks and;decks:levels and --> only one level at a time. In <A HREF="#77066">Example 3-17</A>, <I>logo3.gif</I> is foremost because the <TT>selectedIndex</TT> attribute on the deck is set to 2 in a zero-based index.    Figure 3-11<a name="77022"></a> <i>Text stacked on an image</i>
    
Example 3-17<A NAME="77066"></A>    <p>Decks show <!--INDEX levels:decks and;decks:levels and -->
<I>A deck with three image layers</I>    only one level at a time. In <a href="#77066">Example 3-17</a>,
<PRE> &lt;deck id="fly-deck" selectedIndex="2"&gt;    <i>logo3.gif</i> is foremost because the <tt>selectedIndex</tt>
     attribute on the deck is set to 2 in a zero-based index.
     Example 3-17<a name="77066"></a> <i>A deck with three image
     layers</i></p>
 <pre>
  &lt;deck id="fly-deck" selectedIndex="2"&gt;
    &lt;image src="logo1.gif" /&gt;     &lt;image src="logo1.gif" /&gt;
    &lt;image src="logo2.gif" /&gt;     &lt;image src="logo2.gif" /&gt;
    &lt;image src="logo3.gif" /&gt;     &lt;image src="logo3.gif" /&gt;
 &lt;/deck&gt;</PRE> &lt;/deck&gt;
</pre>
<P>As <A HREF="#77068">Example 3-18</A> shows, it is possible to switch pages using the DOM by changing the index on the deck. The <TT>setAttribute</TT> method changes the <TT>selectedIndex</TT> attribute of the deck <TT>element</TT> in script and can be executed, for example, when a user clicks a button or in other places in the interface.    <p>As <a href="#77068">Example 3-18</a> shows, it is possible
    to switch pages using the DOM by changing the index on the
Example 3-18<A NAME="77068"></A>    deck. The <tt>setAttribute</tt> method changes the
<I>Deck layer switching</I>    <tt>selectedIndex</tt> attribute of the deck <tt>element</tt>
<PRE> var deck = document.getElementById("fly-deck");    in script and can be executed, for example, when a user clicks
     a button or in other places in the interface. Example 3-18<a
     name="77068"></a> <i>Deck layer switching</i></p>
 <pre>
  var deck = document.getElementById("fly-deck");
  var selected = deck.getAttribute("selectedIndex");   var selected = deck.getAttribute("selectedIndex");
  if (!selected)   if (!selected)
      selected = 0;       selected = 0;
Line 792  Example 3-18<A NAME="77068"></A> Line 1993  Example 3-18<A NAME="77068"></A>
  else  {   else  {
      selected = 0;       selected = 0;
      deck.setAttribute("selectedIndex", selected);       deck.setAttribute("selectedIndex", selected);
 }</PRE> }
</pre>
<P>When applied to the deck in <A HREF="#77066">Example 3-17</A>, the code in <A HREF="#77068">Example 3-18</A> continuously flips to the next image in the sequence and returns to the top of the deck when the last image is reached. In this case, there are only three images, so a maximum of 2 is put on the index check.    <p>When applied to the deck in <a href="#77066">Example
<H4><A NAME="77135"></A> Moveable content</H4>    3-17</a>, the code in <a href="#77068">Example 3-18</a>
<P>At one point  <!--INDEX content:movable;movable content;XUL (XML-based User-interface Language):content, movable --> in XUL toolkit development, an  <!--INDEX bulletinboard --> element called the <TT>bulletinboard</TT> allowed you to layer child elements one on top of another like its real-world namesake. You could change the coordinates of the child elements on the screen by using the <TT>top</TT> and <TT>left</TT> attributes. The order of the children in the XUL content determines the z-ordering on screen. As <TT>stack</TT> developed and took on much of this functionality, <TT>bulletinboard</TT> was officially deprecated and some of its properties were merged back into the <TT>stack</TT> element. As <A HREF="#77070">Example 3-19</A> demonstrates, this was a boon for the <TT>stack</TT> element, which can use coordinates to position children like its ancestor. The two boxes in the example are positioned at varying distances away from the stack's top left corner.    continuously flips to the next image in the sequence and
    returns to the top of the deck when the last image is reached.
Example 3-19<A NAME="77070"></A>    In this case, there are only three images, so a maximum of 2 is
<I>Content positioning in a stack</I>    put on the index check.</p>
<PRE> &lt;stack&gt;    <h4><a name="77135"></a> Moveable content</h4>
     <p>At one point 
     <!--INDEX content:movable;movable content;XUL (XML-based User-interface Language):content, movable -->
     in XUL toolkit development, an <!--INDEX bulletinboard -->
     element called the <tt>bulletinboard</tt> allowed you to layer
     child elements one on top of another like its real-world
     namesake. You could change the coordinates of the child
     elements on the screen by using the <tt>top</tt> and
     <tt>left</tt> attributes. The order of the children in the XUL
     content determines the z-ordering on screen. As <tt>stack</tt>
     developed and took on much of this functionality,
     <tt>bulletinboard</tt> was officially deprecated and some of
     its properties were merged back into the <tt>stack</tt>
     element. As <a href="#77070">Example 3-19</a> demonstrates,
     this was a boon for the <tt>stack</tt> element, which can use
     coordinates to position children like its ancestor. The two
     boxes in the example are positioned at varying distances away
     from the stack's top left corner. Example 3-19<a name=
     "77070"></a> <i>Content positioning in a stack</i></p>
 <pre>
  &lt;stack&gt;
   &lt;box id="box1" top="20px" left="40px"&gt;    &lt;box id="box1" top="20px" left="40px"&gt;
    &lt;image src="logo1.gif" /&gt;     &lt;image src="logo1.gif" /&gt;
   &lt;/box&gt;    &lt;/box&gt;
   &lt;box id="box2" top="40px" left="50px"&gt;    &lt;box id="box2" top="40px" left="50px"&gt;
    &lt;image src="logo2.gif" /&gt;     &lt;image src="logo2.gif" /&gt;
   &lt;/box&gt;    &lt;/box&gt;
 &lt;/stack&gt;</PRE> &lt;/stack&gt;
</pre>
<P>You can position the two boxes, each containing an image, in any of the following ways:    <p>You can position the two boxes, each containing an image, in
<UL><P><LI>By placing the <TT>top</TT> and <TT>left</TT> attributes directly on the tags<P>    any of the following ways:</p>
<P><LI>By setting them via stylesheets using the CSS properties <TT>top</TT> and left<P>    <ul>
<P><LI>By using DOM calls in your script<P></UL>      <li>By placing the <tt>top</tt> and <tt>left</tt> attributes
<P>Here is some script used to switch the position of the boxes from one location to another by changing the <TT>top</TT>  <!--INDEX ENDRANGE--box model, XUL;XUL (XML-based User-interface Language):box model --> and <TT>left</TT> attributes:      directly on the tags</li>
<PRE>Box1=document.getElementById("box1")      <li>By setting them via stylesheets using the CSS properties
       <tt>top</tt> and left</li>
       <li>By using DOM calls in your script</li>
     </ul>
     <p>Here is some script used to switch the position of the boxes
     from one location to another by changing the <tt>top</tt> 
     <!--INDEX ENDRANGE==box model, XUL;XUL (XML-based User-interface Language):box model -->
     and <tt>left</tt> attributes:</p>
 <pre>
 Box1=document.getElementById("box1")
 Box1.setAttribute("top","40px")  Box1.setAttribute("top","40px")
 Box1.setAttribute("left","50px")  Box1.setAttribute("left","50px")
 Box2=document.getElementById("box2")  Box2=document.getElementById("box2")
 Box2.setAttribute("top","20px")  Box2.setAttribute("top","20px")
Box2.setAttribute("left","40px")</PRE>Box2.setAttribute("left","40px")
<H2><A NAME="77136"></A> XUL Attributes</H2></pre>
<P>Each XUL element has an <TT>attributes</TT> property  <!--INDEX STARTRANGE--XUL (XML-based User-interface Language):attributes;attributes:XUL --> that contains an array of all its attributes. This section summarizes some of the general XUL attributes that developers find useful, including <TT>debug</TT>.    <h2><a name="77136"></a> XUL Attributes</h2>
<H3><A NAME="77137"></A> Stretchiness</H3>    <p>Each XUL element has an <tt>attributes</tt> property 
<P>An object becomes flexible when  <!--INDEX flex attribute;attributes:XUL:flex -->  <!--INDEX objects:flexible --> the <TT>flex</TT> attribute is placed on the element. Flexible objects can shrink or grow as the box shrinks and grows. Whenever extra space is left over in a box, the flexible objects are expanded to fill that space. Flex is specified as a numerical value, and all flex is relative. For example, a child with a flex of 2 is twice as flexible as a child with a flex of 1, as <A HREF="#77072">Example 3-20</A> shows. The <TT>flex</TT> attribute is invaluable for positioning elements in the box model.    <!--INDEX STARTRANGE==XUL (XML-based User-interface Language):attributes;attributes:XUL -->
    that contains an array of all its attributes. This section
Example 3-20<A NAME="77072"></A>    summarizes some of the general XUL attributes that developers
<I>Flexible buttons</I>    find useful, including <tt>debug</tt>.</p>
<PRE> &lt;?xml version="1.0"?&gt;    <h3><a name="77137"></a> Stretchiness</h3>
     <p>An object becomes flexible when 
     <!--INDEX flex attribute;attributes:XUL:flex --> 
     <!--INDEX objects:flexible --> the <tt>flex</tt> attribute is
     placed on the element. Flexible objects can shrink or grow as
     the box shrinks and grows. Whenever extra space is left over in
     a box, the flexible objects are expanded to fill that space.
     Flex is specified as a numerical value, and all flex is
     relative. For example, a child with a flex of 2 is twice as
     flexible as a child with a flex of 1, as <a href=
     "#77072">Example 3-20</a> shows. The <tt>flex</tt> attribute is
     invaluable for positioning elements in the box model. Example
     3-20<a name="77072"></a> <i>Flexible buttons</i></p>
 <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;   &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;
  &lt;window   &lt;window
    xmlns="<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>"&gt;    xmlns="<a href=
 "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"&gt;
  &lt;box id="parent" style="margin: 50px;"&gt;   &lt;box id="parent" style="margin: 50px;"&gt;
    &lt;button flex="2" label="flex2" /&gt;     &lt;button flex="2" label="flex2" /&gt;
    &lt;button flex="1" label="flex1" /&gt;     &lt;button flex="1" label="flex1" /&gt;
  &lt;/box&gt;   &lt;/box&gt;
 &lt;/window&gt;</PRE> &lt;/window&gt;
</pre>
<H3><A NAME="77138"></A> Style</H3>    <h3><a name="77138"></a> Style</h3>
<P>The <TT>style</TT> attribute allows you to  <!--INDEX style attribute;attributes:XUL:style attribute --> apply CSS style properties to your XUL element directly within the content. The attribute lets you access CSS properties (including <TT>width</TT>, <TT>height</TT>, <TT>min-width</TT>, <TT>min-height</TT>, <TT>max-width</TT>, and <TT>max-height</TT>), which give you more control over the size of your widget.    <p>The <tt>style</tt> attribute allows you to 
<PRE>&lt;button style="height: 20px; background-color: blue;" /&gt;</PRE>    <!--INDEX style attribute;attributes:XUL:style attribute -->
<P>Don't use the <TT>style</TT> attribute too often, though, especially if you want to have more than one theme for your application. See the     apply CSS style properties to your XUL element directly within
section <A HREF="ch04.html#77070">"Inline styles</A>" in <A HREF="ch04.html#37942">Chapter 4</A> for information about how this attribute can make     the content. The attribute lets you access CSS properties
your application less modular and, for some, a better way to apply style to your XUL documents.    (including <tt>width</tt>, <tt>height</tt>, <tt>min-width</tt>,
<H3><A NAME="77139"></A> Persistence</H3>    <tt>min-height</tt>, <tt>max-width</tt>, and
<P>The <TT>persist</TT> attribute preserves the  <!--INDEX persist attribute;attributes:XUL:persist attribute --> state and appearance of a widget on an attribute-by-attribute basis. This feature is useful for properties that change or are set by users during a session, such as window size and positioning, splitter state, and the visibility of certain elements.    <tt>max-height</tt>), which give you more control over the size
<PRE>&lt;splitter id="sidebar-splitter" collapse="before"    of your widget.</p>
persist="state hidden" align="center" orient="vertical"&gt;</PRE><pre>
<P>When the state of the splitter changes-when a user handles the <TT>&lt;grippy&gt;</TT> and collapses the splitter, for example, and then quits-the <TT>persist</TT> attribute preserves the splitter state and its visibility for the next session.&lt;button style="height: 20px; background-color: blue;" /&gt;
<H3><A NAME="77140"></A> The debug Attribute</H3></pre>
<P>Many of XUL elements, particularly  <!--INDEX debug attribute;attributes:XUL:debug attribute --> container elements like box and toolbar, support the <TT>debug</TT> attribute as a useful tool for developers. If <TT>debug</TT> is set to <TT>true</TT>, extra borders are drawn around the element and all its children, with different color coding for each level. This setting can be used to check the orientation and the flexibility of elements. <TT>debug</TT> displays horizontal boxes with a blue border and vertical boxes with a red border, for example, making it easy to see subtle differences or layout bugs. The border above the element will be straight for nonflexible elements and  <!--INDEX ENDRANGE--XUL (XML-based User-interface Language):attributes;attributes:XUL --> grooved for flexible elements.    <p>Don't use the <tt>style</tt> attribute too often, though,
<H2><A NAME="77141"></A> Overlays</H2>    especially if you want to have more than one theme for your
<P>An overlay is a separate file in  <!--INDEX overlays;XUL (XML-based User-interface Language):overlays --> which additional XUL content can be defined and loaded at runtime. Overlays are often used to define things like menus that appear in different components or parts of the application.    application. See the section <a href="ch04.html#77070">"Inline
<P>If you are creating a large application or a UI with many elements as a part of your design, the files can easily become large. The size in itself does not render it ineffective, but it does make the job of the developer a little difficult when tracking down and changing features. The best way to overcome this size problem is to use overlays. Another reason to use overlays is to extract information from a certain logical portion of the UI and contain it in a file of its own. This extraction and containment promotes modularization and reusability.    styles</a>" in <a href="ch04.html#37942">Chapter 4</a> for
<H3><A NAME="77142"></A> How to Use Overlays</H3>    information about how this attribute can make your application
<P>The following declaration is the principal method for including reusable content in a XUL window.    less modular and, for some, a better way to apply style to your
<PRE>&lt;?xul-overlay href="chrome://global/content/globalOverlay.xul"?&gt;</PRE>    XUL documents.</p>
<P>This declaration follows the same syntax as CSS processing instructions. Like other XML processing instructions, it uses a <TT>?</TT> at the beginning and end, just inside the braces. The <TT>href</TT> attribute points to the overlay and uses Mozilla's <I>chrome://</I> type URL.    <h3><a name="77139"></a> Persistence</h3>
<P>To insert content from an overlay, use  <!--INDEX overlays:inserting content from;content:overlay, inserting --> the same <TT>id</TT> of an element in the "base file" for a similar element in your overlay content, and the overlay will replace the base file at runtime (or be merged with it, as described later in this chapter in the <A HREF="#77144">"Content Positioning</A>" section).    <p>The <tt>persist</tt> attribute preserves the 
<P>When the base element is empty, it is replaced with the corresponding overlay element and any child subcontent. The following toolbar snippet shows a reference placed in a base file:    <!--INDEX persist attribute;attributes:XUL:persist attribute -->
<PRE>&lt;toolbar id="main-toolbar" /&gt;</PRE>    state and appearance of a widget on an attribute-by-attribute
<P>When an overlay is read with the content below, the previous line is replaced with that content:    basis. This feature is useful for properties that change or are
<PRE>&lt;toolbar id="main-menubar" persist="collapsed"&gt;    set by users during a session, such as window size and
     positioning, splitter state, and the visibility of certain
     elements.</p>
 <pre>
 &lt;splitter id="sidebar-splitter" collapse="before"
 persist="state hidden" align="center" orient="vertical"&gt;
 </pre>
     <p>When the state of the splitter changes-when a user handles
     the <tt>&lt;grippy&gt;</tt> and collapses the splitter, for
     example, and then quits-the <tt>persist</tt> attribute
     preserves the splitter state and its visibility for the next
     session.</p>
     <h3><a name="77140"></a> The debug Attribute</h3>
     <p>Many of XUL elements, particularly 
     <!--INDEX debug attribute;attributes:XUL:debug attribute -->
     container elements like box and toolbar, support the
     <tt>debug</tt> attribute as a useful tool for developers. If
     <tt>debug</tt> is set to <tt>true</tt>, extra borders are drawn
     around the element and all its children, with different color
     coding for each level. This setting can be used to check the
     orientation and the flexibility of elements. <tt>debug</tt>
     displays horizontal boxes with a blue border and vertical boxes
     with a red border, for example, making it easy to see subtle
     differences or layout bugs. The border above the element will
     be straight for nonflexible elements and 
     <!--INDEX ENDRANGE==XUL (XML-based User-interface Language):attributes;attributes:XUL -->
     grooved for flexible elements.</p>
     <h2><a name="77141"></a> Overlays</h2>
     <p>An overlay is a separate file in 
     <!--INDEX overlays;XUL (XML-based User-interface Language):overlays -->
     which additional XUL content can be defined and loaded at
     runtime. Overlays are often used to define things like menus
     that appear in different components or parts of the
     application.</p>
     <p>If you are creating a large application or a UI with many
     elements as a part of your design, the files can easily become
     large. The size in itself does not render it ineffective, but
     it does make the job of the developer a little difficult when
     tracking down and changing features. The best way to overcome
     this size problem is to use overlays. Another reason to use
     overlays is to extract information from a certain logical
     portion of the UI and contain it in a file of its own. This
     extraction and containment promotes modularization and
     reusability.</p>
     <h3><a name="77142"></a> How to Use Overlays</h3>
     <p>The following declaration is the principal method for
     including reusable content in a XUL window.</p>
 <pre>
 &lt;?xul-overlay href="chrome://global/content/globalOverlay.xul"?&gt;
 </pre>
     <p>This declaration follows the same syntax as CSS processing
     instructions. Like other XML processing instructions, it uses a
     <tt>?</tt> at the beginning and end, just inside the braces.
     The <tt>href</tt> attribute points to the overlay and uses
     Mozilla's <i>chrome://</i> type URL.</p>
     <p>To insert content from an overlay, use 
     <!--INDEX overlays:inserting content from;content:overlay, inserting -->
     the same <tt>id</tt> of an element in the "base file" for a
     similar element in your overlay content, and the overlay will
     replace the base file at runtime (or be merged with it, as
     described later in this chapter in the <a href=
     "#77144">"Content Positioning</a>" section).</p>
     <p>When the base element is empty, it is replaced with the
     corresponding overlay element and any child subcontent. The
     following toolbar snippet shows a reference placed in a base
     file:</p>
 <pre>
 &lt;toolbar id="main-toolbar" /&gt;
 </pre>
     <p>When an overlay is read with the content below, the previous
     line is replaced with that content:</p>
 <pre>
 &lt;toolbar id="main-menubar" persist="collapsed"&gt;
 &lt;toolbarbutton id="new-button" label="New" observes="cmd_new"/&gt;  &lt;toolbarbutton id="new-button" label="New" observes="cmd_new"/&gt;
 &lt;toolbarbutton id="open-button" label="Open" observes="cmd_open"/&gt;  &lt;toolbarbutton id="open-button" label="Open" observes="cmd_open"/&gt;
 &lt;toolbarbutton id="save-button" label="Save" observes="cmd_save"/&gt;  &lt;toolbarbutton id="save-button" label="Save" observes="cmd_save"/&gt;
&lt;/toolbar&gt;</PRE>&lt;/toolbar&gt;
<P>Overlay files are XUL files with a <I>.xul</I> extension. The content within that file has to be contained in an <TT>&lt;overlay&gt;</TT> element, which is the root of the document. For example, the toolbar is a first level child of the root.</pre>
<PRE>&lt;overlay id="xflyOverlay"&gt;    <p>Overlay files are XUL files with a <i>.xul</i> extension.
     The content within that file has to be contained in an
     <tt>&lt;overlay&gt;</tt> element, which is the root of the
     document. For example, the toolbar is a first level child of
     the root.</p>
 <pre>
 &lt;overlay id="xflyOverlay"&gt;
 &lt;toolbar id="main-toolbar" /&gt;  &lt;toolbar id="main-toolbar" /&gt;
 &lt;!-- more overlay content --&gt;  &lt;!-- more overlay content --&gt;
&lt;/overlay&gt;</PRE>&lt;/overlay&gt;
<BLOCKQUOTE><CENTER><B>WARNING</B></CENTER></pre>
<P>Styles from overlays override styles from base XUL files, so be careful not to load master styles in an overlay.<P></BLOCKQUOTE>    <blockquote>
<H4><A NAME="77143"></A> Dynamic loading</H4>      <div class="c11">
<P>The usual method for loading  <!--INDEX loading:overlays, dynamic loading;overlays:loading, dynamic loading;dynamic loading, overlays --> overlays, as outlined previously, is to include the overlay processing instruction in your XUL file. The dynamic loading of content is more subtle, but just as effective. Mozilla has a registry of overlays, in the form of an RDF datasource that lives in the <I>chrome</I> directory. These overlays live in the tree in a directory called <I>overlayinfo</I> under the <I>chrome</I> root.<A NAME="b317"></A><A HREF="#317">[*]</A> When a new package or component is registered, the overlays that come with it are loaded automatically.        WARNING
<P>Dynamic overlays are  <!--INDEX dynamic overlays;overlays:dynamic overlays --> commonly used to extend certain parts of the Mozilla application       </div>
itself when new packages are installed that need access points, as do new language packages and themes, for instance. Certain menus in the UI, for       <p>Styles from overlays override styles from base XUL files,
example, are open for third-party authors to add items. Adding the name of your package to Mozilla's Tasks menu, for example, provides a convenient launching point and is handled with dynamic overlays. <A HREF="ch06.html#15291">Chapter 6</A> provides more information on this topic, in the section <A HREF="ch06.html#77076">"Adding the xFly application to the Mozilla Tools menu</A>."      so be careful not to load master styles in an overlay.</p>
<H3><A NAME="77144"></A> Content Positioning</H3>    </blockquote>
<P>Content positioning is the order  <!--INDEX content:positioning;position:content positioning --> in which  <!--INDEX widgets:position;position:widgets --> widgets appear in the UI. Usually content is laid out in the order elements are defined in the XUL file. However, there are a couple of ways to override this ordering in XUL.    <h4><a name="77143"></a> Dynamic loading</h4>
<P>Continuing with the example of the overlaid toolbar in the previous section, it is possible for both the base definition and the overlaid definition to have children. In this instance, the content is merged, with the original content appearing before the overlaid content by default:    <p>The usual method for loading 
<PRE>&lt;toolbar id="main-toolbar"&gt;    <!--INDEX loading:overlays, dynamic loading;overlays:loading, dynamic loading;dynamic loading, overlays -->
     overlays, as outlined previously, is to include the overlay
     processing instruction in your XUL file. The dynamic loading of
     content is more subtle, but just as effective. Mozilla has a
     registry of overlays, in the form of an RDF datasource that
     lives in the <i>chrome</i> directory. These overlays live in
     the tree in a directory called <i>overlayinfo</i> under the
     <i>chrome</i> root.<a name="b317"></a><a href="#317">[*]</a>
     When a new package or component is registered, the overlays
     that come with it are loaded automatically.</p>
     <p>Dynamic overlays are 
     <!--INDEX dynamic overlays;overlays:dynamic overlays -->
     commonly used to extend certain parts of the Mozilla
     application itself when new packages are installed that need
     access points, as do new language packages and themes, for
     instance. Certain menus in the UI, for example, are open for
     third-party authors to add items. Adding the name of your
     package to Mozilla's Tasks menu, for example, provides a
     convenient launching point and is handled with dynamic
     overlays. <a href="ch06.html#15291">Chapter 6</a> provides more
     information on this topic, in the section <a href=
     "ch06.html#77076">"Adding the xFly application to the Mozilla
     Tools menu</a>."</p>
     <h3><a name="77144"></a> Content Positioning</h3>
     <p>Content positioning is the order 
     <!--INDEX content:positioning;position:content positioning -->
     in which <!--INDEX widgets:position;position:widgets -->
     widgets appear in the UI. Usually content is laid out in the
     order elements are defined in the XUL file. However, there are
     a couple of ways to override this ordering in XUL.</p>
     <p>Continuing with the example of the overlaid toolbar in the
     previous section, it is possible for both the base definition
     and the overlaid definition to have children. In this instance,
     the content is merged, with the original content appearing
     before the overlaid content by default:</p>
 <pre>
 &lt;toolbar id="main-toolbar"&gt;
 &lt;toolbarbutton id="print-button" label="Print" observes="cmd_print"/&gt;  &lt;toolbarbutton id="print-button" label="Print" observes="cmd_print"/&gt;
&lt;/toolbar&gt;</PRE>&lt;/toolbar&gt;
<P>If the <TT>toolbarbutton</TT> above is in the base XUL, then the ordering of the buttons would be Print, New, Open, and Save. It is possible to change this ordering by using <TT>insertbefore</TT>, however, as shown in <A HREF="#77074">Example 3-21</A>.</pre>
    <p>If the <tt>toolbarbutton</tt> above is in the base XUL, then
Example 3-21<A NAME="77074"></A>    the ordering of the buttons would be Print, New, Open, and
<I>Positioning attributes</I>    Save. It is possible to change this ordering by using
<PRE> &lt;toolbar id="main-toolbar" persist="collapsed"&gt;    <tt>insertbefore</tt>, however, as shown in <a href=
     "#77074">Example 3-21</a>. Example 3-21<a name="77074"></a>
     <i>Positioning attributes</i></p>
 <pre>
  &lt;toolbar id="main-toolbar" persist="collapsed"&gt;
    &lt;toolbarbutton id="new-button" label="New" observes="cmd_new"     &lt;toolbarbutton id="new-button" label="New" observes="cmd_new"
       </TD>insertbefore="print-button"/&gt;       &lt;/td&gt;insertbefore="print-button"/&gt;
    &lt;toolbarbutton id="open-button" label="Open" observes="cmd_open"/&gt;     &lt;toolbarbutton id="open-button" label="Open" observes="cmd_open"/&gt;
   </TD>&lt;toolbarbutton id="save-button" label="Save" observes="cmd_save"   &lt;/td&gt;&lt;toolbarbutton id="save-button" label="Save" observes="cmd_save"
       position="2"</TD>/&gt;       position="2"&lt;/td&gt;/&gt;
 &lt;/toolbar&gt;</PRE> &lt;/toolbar&gt;
</pre>
<P>The <TT>insertbefore</TT> attribute is  <!--INDEX insertbefore attribute;attributes:XUL:insertbefore --> placed on one of the child items to signify that it should go before a sibling in the base file. <TT>insertbefore</TT> takes an element <TT>id</TT> as a value and says, in this case, that the New button should go before Print. Conversely, you can move an item after it by using the <TT>insertafter</TT> attribute. For more precision, you can use <TT>position</TT> to position an item absolutely in the sequence of siblings. In <A HREF="#77074">Example 3-21</A>, the position attribute puts the Save button in the second position, so the final order is New, Save, Print, and Open.    <p>The <tt>insertbefore</tt> attribute is 
<H2><A NAME="77145"></A> The Extras</H2>    <!--INDEX insertbefore attribute;attributes:XUL:insertbefore -->
<P>Certain lesser-known elements and features are indispensable to the savvy XUL developer and can add that something extra to Mozilla applications, as shown here.    placed on one of the child items to signify that it should go
<H3><A NAME="77146"></A> Tooltips</H3>    before a sibling in the base file. <tt>insertbefore</tt> takes
<P>Tooltips are visual pop ups  <!--INDEX tooltips --> that appear when you place the cursor over a piece of the UI. The hovering behavior of a tooltip is useful for many things, including abbreviated help and the display of values that are otherwise obscured in the UI. In the Mozilla application, the most common places where they are used are on toolbar buttons and splitter grippies that divide panels in the window.    an element <tt>id</tt> as a value and says, in this case, that
<P>To invoke a tooltip, add a <TT> <!--INDEX tooltiptext attribute;attributes:XUL:tooltiptext --> tooltiptext</TT> attribute to the widget that needs it:    the New button should go before Print. Conversely, you can move
<PRE>&lt;button id="printButton" label="Print" tooltiptext="Print this page" /&gt;</PRE>    an item after it by using the <tt>insertafter</tt> attribute.
<P>Defining this attribute is enough to ensure that the generic Mozilla tip box appears with the specified text when you place the cursor over the element.    For more precision, you can use <tt>position</tt> to position
<P>Tooltips are actually implemented  <!--INDEX bindings:XBL:tooltips and;XBL bindings, tooltips and --> as an XBL binding. Underneath, a tooltip is essentially a pop up with a <TT>description</TT> element within that holds text. You can also create your own tooltips.    an item absolutely in the sequence of siblings. In <a href=
<P>To create your own content and customized appearance for a tooltip:    "#77074">Example 3-21</a>, the position attribute puts the Save
<OL><P><LI>Create the content.<P>    button in the second position, so the final order is New, Save,
<P><LI>Attach it to the pop-up element you will be using.<P>    Print, and Open.</p>
<P><LI>Give the pop up a unique ID.<P></OL>    <h2><a name="77145"></a> The Extras</h2>
<P>The following snippet shows the kind of tooltip you can create and then reuse in your application code:    <p>Certain lesser-known elements and features are indispensable
<PRE>&lt;popupset id="aTooltipSet"&gt;    to the savvy XUL developer and can add that something extra to
     Mozilla applications, as shown here.</p>
     <h3><a name="77146"></a> Tooltips</h3>
     <p>Tooltips are visual pop ups <!--INDEX tooltips --> that
     appear when you place the cursor over a piece of the UI. The
     hovering behavior of a tooltip is useful for many things,
     including abbreviated help and the display of values that are
     otherwise obscured in the UI. In the Mozilla application, the
     most common places where they are used are on toolbar buttons
     and splitter grippies that divide panels in the window.</p>
     <p>To invoke a tooltip, add a <tt>
     <!--INDEX tooltiptext attribute;attributes:XUL:tooltiptext -->
     tooltiptext</tt> attribute to the widget that needs it:</p>
 <pre>
 &lt;button id="printButton" label="Print" tooltiptext="Print this page" /&gt;
 </pre>
     <p>Defining this attribute is enough to ensure that the generic
     Mozilla tip box appears with the specified text when you place
     the cursor over the element.</p>
     <p>Tooltips are actually implemented 
     <!--INDEX bindings:XBL:tooltips and;XBL bindings, tooltips and -->
     as an XBL binding. Underneath, a tooltip is essentially a pop
     up with a <tt>description</tt> element within that holds text.
     You can also create your own tooltips.</p>
     <p>To create your own content and customized appearance for a
     tooltip:</p>
     <ol>
       <li>Create the content.</li>
       <li>Attach it to the pop-up element you will be using.</li>
       <li>Give the pop up a unique ID.</li>
     </ol>
     <p>The following snippet shows the kind of tooltip you can
     create and then reuse in your application code:</p>
 <pre>
 &lt;popupset id="aTooltipSet"&gt;
 &lt;popup id="myTooltip"  &lt;popup id="myTooltip"
 class="tooltip"  class="tooltip"
 onpopupshowing="return FillInTooltip(document.tooltipNode);" &gt;  onpopupshowing="return FillInTooltip(document.tooltipNode);" &gt;
 &lt;description id="TOOLTIP-tooltipText"  &lt;description id="TOOLTIP-tooltipText"
 class="my-tooltip-label" flex="1"/&gt;  class="my-tooltip-label" flex="1"/&gt;
 &lt;/popup&gt;  &lt;/popup&gt;
&lt;/popupset&gt;</PRE>&lt;/popupset&gt;
<P>Use your newly created widget by adding its <TT>id</TT> value to the <TT>tooltip</TT> attribute to the UI element that wants it:</pre>
<PRE>&lt;treeitem id="FlyDescription" tooltip="myTooltip" tooltiptext="" /&gt;</PRE>    <p>Use your newly created widget by adding its <tt>id</tt>
<P>Note that this example assumes that the actual text will be applied dynamically to the <TT>tooltiptext</TT> attribute, which is initially empty. This is useful in many situations-for example, in tree cells that contain transient values.    value to the <tt>tooltip</tt> attribute to the UI element that
<P>The advantage of creating your own tooltip is that you can apply your own styles to it, giving the text and background whatever font and colors you want. A variation of the <TT>tooltip</TT> attribute named <TT>contenttooltip</TT> is used for content panels.    wants it:</p>
<H3><A NAME="77147"></A> Progress Meter</H3><pre>
<P>Sometimes in your application you need  <!--INDEX progress meter;status bar/progress meter;downloading:progress meter;loading:progress meter --> to give the user feedback during a long operation. The classic example in the browser is the status bar that shows a visual representation of the time remaining when you load a big web page or download a file.&lt;treeitem id="FlyDescription" tooltip="myTooltip" tooltiptext="" /&gt;
<P>Of these two activities, loading pages and downloading files, downloading uses the determined mode, meaning that the time to complete the operation is calculable. In this case, an algorithm is written based on the file size and the bandwidth values to formulate the time remaining. The second of three modes of a progress meter is the undetermined mode, in which the time for the operation to complete is unknown. Commonly called the "barber pole," the progress meter shows a spinning pole when in undetermined mode. The third mode is normal, which shows an empty bar. You can get/set the mode by using the <TT>mode</TT> attribute.</pre>
<P>Here is the XUL for a sample progress meter:    <p>Note that this example assumes that the actual text will be
<PRE>&lt;progressmeter id="progressTask" mode="normal" value="0" onclick="alert(`Task is in progress')"/&gt;</PRE>    applied dynamically to the <tt>tooltiptext</tt> attribute,
<P>Here is the accompanying script for activating the progress meter:    which is initially empty. This is useful in many situations-for
<PRE>var meter = document.getElementById('progressTask');    example, in tree cells that contain transient values.</p>
     <p>The advantage of creating your own tooltip is that you can
     apply your own styles to it, giving the text and background
     whatever font and colors you want. A variation of the
     <tt>tooltip</tt> attribute named <tt>contenttooltip</tt> is
     used for content panels.</p>
     <h3><a name="77147"></a> Progress Meter</h3>
     <p>Sometimes in your application you need 
     <!--INDEX progress meter;status bar/progress meter;downloading:progress meter;loading:progress meter -->
     to give the user feedback during a long operation. The classic
     example in the browser is the status bar that shows a visual
     representation of the time remaining when you load a big web
     page or download a file.</p>
     <p>Of these two activities, loading pages and downloading
     files, downloading uses the determined mode, meaning that the
     time to complete the operation is calculable. In this case, an
     algorithm is written based on the file size and the bandwidth
     values to formulate the time remaining. The second of three
     modes of a progress meter is the undetermined mode, in which
     the time for the operation to complete is unknown. Commonly
     called the "barber pole," the progress meter shows a spinning
     pole when in undetermined mode. The third mode is normal, which
     shows an empty bar. You can get/set the mode by using the
     <tt>mode</tt> attribute.</p>
     <p>Here is the XUL for a sample progress meter:</p>
 <pre>
 &lt;progressmeter id="progressTask" mode="normal" value="0" onclick="alert(`Task is in progress')"/&gt;
 </pre>
     <p>Here is the accompanying script for activating the progress
     meter:</p>
 <pre>
 var meter = document.getElementById('progressTask');
 meter.setAttribute('mode', 'undetermined');  meter.setAttribute('mode', 'undetermined');
 sometask( );  sometask( );
 meter.setAttribute('mode', 'determined');  meter.setAttribute('mode', 'determined');
meter.setAttribute('value', '100%');</PRE>meter.setAttribute('value', '100%');
<P>The mode is changed to undetermined just before carrying out the task, and is represented  <!--INDEX sometask( ) function, JavaScript;JavaScript:functions:sometask( );functions:JavaScript:sometask( ) --> by the function <TT>sometask( )</TT>. The JavaScript code is synchronous, so it will not hand back control until the operation is complete.</pre>
<H3><A NAME="77148"></A> Links</H3>    <p>The mode is changed to undetermined just before carrying out
<P>Mozilla is  <!--INDEX links;XUL (XML-based User-interface Language):links --> a web application, and many programs and operating systems (e.g., Windows XP) are moving toward full web integration. Linking is fundamental in application programming, so Mozilla provides a couple of ways to do it in your XUL document.    the task, and is represented 
<H4><A NAME="77149"></A> Use of the &lt;html:a&gt; element</H4>    <!--INDEX sometask( ) function, JavaScript;JavaScript:functions:sometask( );functions:JavaScript:sometask( ) -->
<P>To use HTML in your XUL file, you must  <!--INDEX html\:a element --> define  <!--INDEX links:html\:a element and --> the  <!--INDEX XUL files:HTML in;HTML (Hypertext Markup Language):XUL files --> HTML namespace at the top of your document:    by the function <tt>sometask( )</tt>. The JavaScript code is
<PRE>&lt;window id="MyOverlay"    synchronous, so it will not hand back control until the
xmlns:html="<A HREF="http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</A>"    operation is complete.</p>
xmlns="<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>"&gt;</PRE>    <h3><a name="77148"></a> Links</h3>
<P>Then you can use the HTML elements just as you would in a regular web page, but with the addition of the namespace you declared:    <p>Mozilla is 
<PRE>&lt;vbox&gt;    <!--INDEX links;XUL (XML-based User-interface Language):links -->
     a web application, and many programs and operating systems
     (e.g., Windows XP) are moving toward full web integration.
     Linking is fundamental in application programming, so Mozilla
     provides a couple of ways to do it in your XUL document.</p>
     <h4><a name="77149"></a> Use of the &lt;html:a&gt; element</h4>
     <p>To use HTML in your XUL file, you must 
     <!--INDEX html\:a element --> define 
     <!--INDEX links:html\:a element and --> the 
     <!--INDEX XUL files:HTML in;HTML (Hypertext Markup Language):XUL files -->
     HTML namespace at the top of your document:</p>
 <pre>
 &lt;window id="MyOverlay"
 xmlns:html="<a href=
 "http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
 xmlns="<a href=
 "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"&gt;
 </pre>
     <p>Then you can use the HTML elements just as you would in a
     regular web page, but with the addition of the namespace you
     declared:</p>
 <pre>
 &lt;vbox&gt;
 &lt;html:a href="myOverlay.html"&gt;Go to Help page&lt;/html:a&gt;  &lt;html:a href="myOverlay.html"&gt;Go to Help page&lt;/html:a&gt;
&lt;/vbox&gt;</PRE>&lt;/vbox&gt;
<P>When you use a page with code in your application, the user can click the link and open a Mozilla browser to the requested page or item.</pre>
<H4><A NAME="77150"></A> Simple XLinks</H4>    <p>When you use a page with code in your application, the user
<P>You  <!--INDEX XLinks;links:XLinks --> can also tap into the more sophisticated XML capabilities in Mozilla by trying a simple XLink. Again, the correct namespace is required:    can click the link and open a Mozilla browser to the requested
<PRE>&lt;window xmlns:xlink=<A HREF="http://www.w3.org/1999/xlink">http://www.w3.org/1999/xlink</A> ...&gt;</PRE>    page or item.</p>
<P>Then you define your link as follows:    <h4><a name="77150"></a> Simple XLinks</h4>
<PRE>&lt;xlink:link xlink:type="simple" xlink:href="c.xml"&gt;c.xml&lt;/xlink:link&gt;</PRE>    <p>You <!--INDEX XLinks;links:XLinks --> can also tap into the
<P>The element here is <TT>link</TT>, the <TT>type</TT> is simple, and the locator is <TT>href</TT>.    more sophisticated XML capabilities in Mozilla by trying a
<H2><A NAME="77151"></A> Building the Application Shell</H2>    simple XLink. Again, the correct namespace is required:</p>
<P>Now that the  <!--INDEX application shell, building;shells:application shell, building --> main XUL widgets and some crucial concepts like the box model have been described, you can bring things together and create an <I>application shell</I>, a user interface that isn't (yet) hooked up to application code, but which can be re-used for different applications.<pre>
<P>The XUL in <A HREF="#77076">Example 3-22</A> extends  <!--INDEX xFly:shell;shells:xFly application --> the  <!--INDEX APIs (Application &lt;window xmlns:xlink=<a href=
Programming Interfaces) Component Manager and:(see also xFly) --> xFly application work you've already done in <A HREF="ch02.html#77048">Chapter 2</A>. It defines the interface for a viewer that will let you browse the examples in this book, giving xFly a measure of introspection. Examine the code closely in <A HREF="#77076">Example 3-22</A> to give yourself a feel for how the elements in the UI interact with each other to form something that is greater than the sum of its parts. Look particularly at how box elements are used such  <!--INDEX boxes:box elements --> as <TT>vbox</TT>, <TT>hbox</TT>, <TT>tabbox</TT>, and <TT>statusbar</TT>."http://www.w3.org/1999/xlink">http://www.w3.org/1999/xlink</a> ...&gt;
</pre>
Example 3-22<A NAME="77076"></A>    <p>Then you define your link as follows:</p>
<I>xFly application main workspace</I><pre>
<PRE> &lt;?xml version="1.0"?&gt;&lt;xlink:link xlink:type="simple" xlink:href="c.xml"&gt;c.xml&lt;/xlink:link&gt;
 </pre>
     <p>The element here is <tt>link</tt>, the <tt>type</tt> is
     simple, and the locator is <tt>href</tt>.</p>
     <h2><a name="77151"></a> Building the Application Shell</h2>
     <p>Now that the 
     <!--INDEX application shell, building;shells:application shell, building -->
     main XUL widgets and some crucial concepts like the box model
     have been described, you can bring things together and create
     an <i>application shell</i>, a user interface that isn't (yet)
     hooked up to application code, but which can be re-used for
     different applications.</p>
     <p>The XUL in <a href="#77076">Example 3-22</a> extends 
     <!--INDEX xFly:shell;shells:xFly application --> the 
     <!--INDEX APIs (Application 
     Programming Interfaces) Component Manager and:(see also xFly) -->
     xFly application work you've already done in <a href=
     "ch02.html#77048">Chapter 2</a>. It defines the interface for a
     viewer that will let you browse the examples in this book,
     giving xFly a measure of introspection. Examine the code
     closely in <a href="#77076">Example 3-22</a> to give yourself a
     feel for how the elements in the UI interact with each other to
     form something that is greater than the sum of its parts. Look
     particularly at how box elements are used such 
     <!--INDEX boxes:box elements --> as <tt>vbox</tt>,
     <tt>hbox</tt>, <tt>tabbox</tt>, and <tt>statusbar</tt>. Example
     3-22<a name="77076"></a> <i>xFly application main
     workspace</i></p>
 <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;   &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;
  &lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;   &lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;
  &lt;?xul-overlay href="chrome://xfly/content/xflyoverlay.xul"?&gt;   &lt;?xul-overlay href="chrome://xfly/content/xflyoverlay.xul"?&gt;
  &lt;!DOCTYPE window SYSTEM "chrome://xfly/locale/xfly.dtd"&gt;   &lt;!DOCTYPE window SYSTEM "chrome://xfly/locale/xfly.dtd"&gt;
  &lt;window title="&amp;window.title;"   &lt;window title="&amp;window.title;"
   xmlns:html="<A HREF="http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</A>"   xmlns:html="<a href=
   xmlns="<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>""http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
    xmlns="<a href=
 "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
    type="xfly:main"     type="xfly:main"
    width="800"     width="800"
    height="600"     height="600"
Line 1021  Example 3-22<A NAME="77076"></A> Line 2502  Example 3-22<A NAME="77076"></A>
        flex="4" crop="right"/&gt;         flex="4" crop="right"/&gt;
    &lt;statusbarpanel class="statusbarpanel-iconic" id="example-status" flex="1"/&gt;     &lt;statusbarpanel class="statusbarpanel-iconic" id="example-status" flex="1"/&gt;
  &lt;/statusbar&gt;   &lt;/statusbar&gt;
 &lt;/window&gt;</PRE> &lt;/window&gt;
</pre>
<P>The main application windows consists of a menu bar, two frames, and a status bar. The menus provide access to application-level functions like closing the window, or launching an "About" window. At the bottom of the window, the status bar displays the book icon and some status messages for the application. Between the menu bar and the status bar are the two main panels: a  <!--INDEX vertical boxes;vbox element, XUL --> vertical box (<TT>&lt;vbox&gt;</TT>) on the left that contains a tree for choosing examples with the xFly logo beneath it, and an <TT> <!--INDEX iframe element, XUL --> &lt;iframe&gt;</TT> into which the examples are loaded on the right. There are two tabs in the example pane, one for showing the example rendered and one for looking at the source.    <p>The main application windows consists of a menu bar, two
<P><CENTER><IMG SRC="foo.gif"></CENTER>    frames, and a status bar. The menus provide access to
Figure 3-12<A NAME="77024"></A>    application-level functions like closing the window, or
<I>xFly example viewing application</I>    launching an "About" window. At the bottom of the window, the
    status bar displays the book icon and some status messages for
<P>The code in <A HREF="#77076">Example 3-22</A> is not the final code for xFly, but it does show some important widgets used for the main layout of the application. But the layout in <A HREF="#77076">Example 3-22</A> (in which a <TT>&lt;toolbox&gt;</TT> holds the menus, a <TT>&lt;statusbar&gt;</TT> displays messages from the application, and the box model is used to layout the application display) is a very useful template for XUL applications.    the application. Between the menu bar and the status bar are
<P>What remains to define is the tree structure that actually holds the various examples. In <A HREF="#77076">Example 3-22</A>, the <TT>&lt;tree&gt;</TT> has an ID attribute that is meant to pick up content defined in an overlay. <A HREF="#77078">Example 3-23</A> shows what such an overlay would look like, but if you'd rather, you can take the content of the <TT>&lt;tree id="example-tree</TT>"&gt; element in this example, define it as direct content of the <TT>&lt;tree&gt;</TT