Diff for /books/www/chapters/ch02.html between versions 1.10 and 1.24

version 1.10, 2002/11/27 13:20:25 version 1.24, 2003/03/31 21:36:26
Line 1 Line 1
<HTML>    <link rel="prev" href="http://books.mozdev.org/chapters/ch01.html" />
<HEAD><TITLE>Chapter 2</TITLE></HEAD><BODY BGCOLOR=WHITE><H2>Chapter 2</H2>    <link rel="next" href="http://books.mozdev.org/chapters/ch03.html" />
<H1><A NAME="77048"></A> Getting Started</H1> 
<P>To help you start creating applications as quickly as possible, this chapter presents two "Hello World" examples that demonstrate the beginning stages of Mozilla application development. 
<P>The first example is a simple XUL file that is loaded into the browser window. This example is then expanded on by adding additional features to the XUL file, such as imported stylesheets and JavaScript functions. The second "Hello World" example shows how to turn files like these into packages, which are the modular, bundled sets of files that fit together to make Mozilla applications or new modules for the Mozilla browser. 
<P>These examples provide a context for discussing the development of Mozilla applications. The first example focuses on creating and editing the basic file types, and the second focuses on the organization and distribution of applications on the Mozilla platform. 
<H2><A NAME="77049"></A> Simple XUL Example</H2> 
<P>Like all good "Hello World" applications,  <!--INDEX Hello World XUL example -->  <!--INDEX XUL (XML-based User-interface Language):Hello World example --> <A HREF="#77016">Example 2-1</A> shows one of the simplest possible examples of XUL. Although it is small, it demonstrates some important aspects of XUL programming, including the use of event handlers to add behavior and the use of a <TT>box</TT> to lay out elements properly within the window. This example also provides a context for discussing more general features of the language, such as the file format, the namespace, and some XUL programming conventions. 
   
<P><I>Example 2-1: <A NAME="77016"></A></I>    <style type="text/css">
<I>Hello xFly</I>      div.c9 {margin-left: 2em}
<PRE> &lt;?xml version="1.0"?&gt;      div.c8 {font-weight: bold; text-align: center}
       div.c7 {text-align: center}
     </style>
 
     <h2>Chapter 2</h2>
     <h1><a name="77048"></a> Getting Started</h1>
     <p>To help you start creating applications as quickly as
     possible, this chapter presents two "Hello World" examples that
     demonstrate the beginning stages of Mozilla application
     development.</p>
     <p>The first example is a simple XUL file that is loaded into
     the browser window. This example is then expanded on by adding
     additional features to the XUL file, such as imported
     stylesheets and JavaScript functions. The second "Hello World"
     example shows how to turn files like these into packages, which
     are the modular, bundled sets of files that fit together to
     make Mozilla applications or new modules for the Mozilla
     browser.</p>
     <p>These examples provide a context for discussing the
     development of Mozilla applications. The first example focuses
     on creating and editing the basic file types, and the second
     focuses on the organization and distribution of applications on
     the Mozilla platform.</p>
     <h2><a name="77049"></a> Simple XUL Example</h2>
     <p>Like all good "Hello World" applications, 
     <!--INDEX Hello World XUL example --> 
     <!--INDEX XUL (XML-based User-interface Language):Hello World example -->
     <a href="#77016">Example 2-1</a> shows one of the simplest
     possible examples of XUL. Although it is small, it demonstrates
     some important aspects of XUL programming, including the use of
     event handlers to add behavior and the use of a <tt>box</tt> to
     lay out elements properly within the window. This example also
     provides a context for discussing more general features of the
     language, such as the file format, the namespace, and some XUL
     programming conventions.</p>
     <p><i>Example 2-1: <a name="77016"></a></i> <i>Hello
     xFly</i></p>
 <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;!-- Sample XUL file --&gt;   &lt;!-- Sample XUL file --&gt;
 &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; &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;
  &lt;box align="center"&gt;   &lt;box align="center"&gt;
    &lt;button label="hello xFly" onclick="alert('Hello World');" /&gt;     &lt;button label="hello xFly" onclick="alert('Hello World');" /&gt;
  &lt;/box&gt;   &lt;/box&gt;
 &lt;/window&gt;</PRE> &lt;/window&gt;
</pre>
<P>Use your text editor to save the code in <A HREF="#77016">Example 2-1</A> in a file called <I>hello.xul</I> and then load the file in Mozilla (you can do this by using File &gt; Open File from the browser window and browsing to where you saved the file). You should see a button in the upper-left corner of the browser window that brings up an alert box when clicked. <A HREF="#77002">Figure 2-1</A> shows an example of the alert pop-up window that appears.    <p>Use your text editor to save the code in <a href=
<P><CENTER><IMG SRC="foo.gif"></CENTER>    "#77016">Example 2-1</a> in a file called <i>hello.xul</i> and
<P><I>Figure 2-1: <A NAME="77002"></A></I>    then load the file in Mozilla (you can do this by using File
<I>The first Hello xFly example</I>    &gt; Open File from the browser window and browsing to where
    you saved the file). You should see a button in the upper-left
<P>The next few sections describe this sample file in more detail. The covered topics include the file itself, the syntax of the markup, XUL namespaces, and the basic layout of a XUL file.    corner of the browser window that brings up an alert box when
<BLOCKQUOTE><HR><B>The xFly Examples</B>    clicked. <a href="#77002">Figure 2-1</a> shows an example of
<P>The best way to understand the possible uses of the Mozilla framework is to look more closely at a number of various existing applications. This book highlights several Mozilla development projects, such as ChatZilla and JSLib, as examples of how some people have already started using Mozilla's XPFE technologies.    the alert pop-up window that appears.</p>
<P>Along with these applications, you'll note the use of the name "xFly" in many examples in this chapter and elsewhere in this book. The xFly     <div class="c7">
examples are used throughout <A HREF="#77048">Chapter 2</A> to <A HREF="ch06.html#77063">Chapter 6</A> to show how to create and package a simple Mozilla application.      <img src="foo.gif">
<P>This simple application is useful because it provides a place to start exploring the new information that you will learn about in this book. As you read more about XUL, CSS, JavaScript, and the other parts of Mozilla's development framework, you can create and edit the xFly files to see how these technologies work in practice.<HR></BLOCKQUOTE>    </div>
    <p><i>Figure 2-1: <a name="77002"></a></i> <i>The first Hello
<H2><A NAME="77050"></A> Basic XUL Concepts</H2>    xFly example</i></p>
<P>You have already seen many of XUL's basic features at work. When you load the example in the previous example, the browser identifies it as a XUL file, parses the data, creates a new window and draws the button widget, and executes the function you've defined when the button is clicked.    <p>The next few sections describe this sample file in more
<P>These activities are part of the basic and often transparent interaction between your application files and Mozilla. However, the format of your XUL files, their syntax and namespace, the XUL layout, and the windowing system are all basic to successful XUL programming.    detail. The covered topics include the file itself, the syntax
<H3><A NAME="77051"></A> The XUL File Format</H3>    of the markup, XUL namespaces, and the basic layout of a XUL
<P>A XUL file is a simple text file  <!--INDEX XUL files -->  <!--INDEX files:XUL files --> that contains proper XML syntax and has a <I>.xul</I> file extension. Mozilla expects to draw UI widgets when it encounters a file with a <I>.xul</I> extension or when it encounters the XUL namespace in other markup files that it recognizes, including HTML and XML.    file.</p>
<P>The MIME type registered  <!--INDEX MIME type, XUL files -->  <!--INDEX XUL files:MIME type registered --> for XUL files is     <blockquote>
<I>application/vnd.mozilla.xul+xml</I>. When editing and using XUL files locally, you shouldn't need to worry about setting this on your computer; however, sometimes you may need to set the MIME type, such as when you host XUL files on a server. <A HREF="ch12.html#51383">Chapter 12</A> provides additional information about how you can set the correct file type for your system.      <hr>
<H3><A NAME="77052"></A> Conventions</H3>      <b>The xFly Examples</b> 
<P>XUL has to follow certain  <!--INDEX XUL (XML-based User-interface Language):conventions -->  <!--INDEX conventions, XUL --> conventions (as does XHTML or any other XML-based file) in order to be valid. Mozilla generates an error when it encounters an invalid XUL file.      <p>The best way to understand the possible uses of the
<P>The first thing required in a XUL document is the XML declaration.      Mozilla framework is to look more closely at a number of
<PRE>&lt;?xml version="1.0"?&gt;</PRE>      various existing applications. This book highlights several
<P>Any comments used to introduce  <!--INDEX comments:XUL -->  <!--INDEX XUL (XML-based User-interface Language):comments --> your file can begin on the line after the declaration. Comments in XUL follow the same format used in HTML and XML, delimited by <TT>&lt;!--</TT> and <TT>--&gt;</TT>.      Mozilla development projects, such as ChatZilla and JSLib, as
<P>All tag sets must be closed. Empty  <!--INDEX tags, XUL -->  <!--INDEX XUL (XML-based User-interface Language):tags --> tags are allowed for some elements, such as the <TT>&lt;label&gt;</TT> element, that are used without nested elements or content. Note that a trailing slash at the end of the tag is required to denote an empty element.      examples of how some people have already started using
<PRE>&lt;label value="Getting Started" /&gt;</PRE>      Mozilla's XPFE technologies.</p>
<P>Another thing to remember is  <!--INDEX case-sensitivity, XUL -->  <!--INDEX XUL (XML-based User-interface Language):case-sensitivity --> that XUL is case-sensitive. Closing a XUL <TT>&lt;window&gt;</TT> tag with <TT>&lt;/Window&gt;</TT> renders it invalid.      <p>Along with these applications, you'll note the use of the
<P>These conventions ensure that the rendering engine can parse the XUL file successfully and display the elements defined there. Mozilla does not validate XML files, such as XUL, and it does not resolve externally parsed entities, but it does check for document well-formedness.      name "xFly" in many examples in this chapter and elsewhere in
<P>Following the XML specification, Mozilla ignores well-formed tags that it does not recognize, which can give your applications extra flexibility, particularly as you begin to use technologies such as XBL. But it can also make debugging a little more difficult, as when you create an element named <TT>&lt;botton&gt;</TT> and don't see why your XUL button doesn't have the typical borders or three-dimensional style.      this book. The xFly examples are used throughout <a href=
<P>A good practice to follow when creating XUL files is to use comments, copious whitespace, indentations (but not tabbed indentations where you can avoid them), and XUL widgets you are familiar with.      "#77048">Chapter 2</a> to <a href="ch06.html#77063">Chapter
<H3><A NAME="77053"></A> The XUL Namespace</H3>      6</a> to show how to create and package a simple Mozilla
<P>Like other markup  <!--INDEX namespaces:XUL -->  <!--INDEX XUL (XML-based User-interface Language):namespace --> vocabularies, XUL uses a namespace declaration to define the particular elements that may be included in a valid file. <A HREF="#77018">Example 2-2</A> shows a sample of the required namespace declaration. The namespace is an attribute of the root <TT>window</TT> element. The lack of any suffix on the XML namespace declaration (i.e., <TT>xmlns:xul</TT>) indicates that XUL is the default namespace for this file.      application. An installable version of the complete xFly
      application can be found at <i><a href=
<P><I>Example 2-2: <A NAME="77018"></A></I>      "http://xfly.mozdev.org">http://xfly.mozdev.org</a></i>.</p>
<I>The XUL namespace declaration</I>      <p>This simple application is useful because it provides a
<PRE> &lt;window      place to start exploring the new information that you will
   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;      learn about in this book. As you read more about XUL, CSS,
       JavaScript, and the other parts of Mozilla's development
       framework, you can create and edit the xFly files to see how
       these technologies work in practice.</p>
       <hr>
     </blockquote>
     <h2><a name="77050"></a> Basic XUL Concepts</h2>
     <p>You have already seen many of XUL's basic features at work.
     When you load the example in the previous example, the browser
     identifies it as a XUL file, parses the data, creates a new
     window and draws the button widget, and executes the function
     you've defined when the button is clicked.</p>
     <p>These activities are part of the basic and often transparent
     interaction between your application files and Mozilla.
     However, the format of your XUL files, their syntax and
     namespace, the XUL layout, and the windowing system are all
     basic to successful XUL programming.</p>
     <h3><a name="77051"></a> The XUL File Format</h3>
     <p>A XUL file is a simple text file <!--INDEX XUL files --> 
     <!--INDEX files:XUL files --> that contains proper XML syntax
     and has a <i>.xul</i> file extension. Mozilla expects to draw
     UI widgets when it encounters a file with a <i>.xul</i>
     extension or when it encounters the XUL namespace in other
     markup files that it recognizes, including HTML and XML.</p>
     <p>The MIME type registered <!--INDEX MIME type, XUL files --> 
     <!--INDEX XUL files:MIME type registered --> for XUL files is
     <i>application/vnd.mozilla.xul+xml</i>. When editing and using
     XUL files locally, you shouldn't need to worry about setting
     this on your computer; however, sometimes you may need to set
     the MIME type, such as when you host XUL files on a server. <a
     href="ch12.html#51383">Chapter 12</a> provides additional
     information about how you can set the correct file type for
     your system.</p>
     <h3><a name="77052"></a> Conventions</h3>
     <p>XUL has to follow certain 
     <!--INDEX XUL (XML-based User-interface Language):conventions -->
     <!--INDEX conventions, XUL --> conventions (as does XHTML or
     any other XML-based file) in order to be valid. Mozilla
     generates an error when it encounters an invalid XUL file.</p>
     <p>The first thing required in a XUL document is the XML
     declaration.</p>
 <pre>
 &lt;?xml version="1.0"?&gt;
 </pre>
     <p>Any comments used to introduce <!--INDEX comments:XUL --> 
     <!--INDEX XUL (XML-based User-interface Language):comments -->
     your file can begin on the line after the declaration. Comments
     in XUL follow the same format used in HTML and XML, delimited
     by <tt>&lt;!--</tt> and <tt>--&gt;</tt>.</p>
     <p>All tag sets must be closed. Empty <!--INDEX tags, XUL --> 
     <!--INDEX XUL (XML-based User-interface Language):tags --> tags
     are allowed for some elements, such as the
     <tt>&lt;label&gt;</tt> element, that are used without nested
     elements or content. Note that a trailing slash at the end of
     the tag is required to denote an empty element.</p>
 <pre>
 &lt;label value="Getting Started" /&gt;
 </pre>
     <p>Another thing to remember is 
     <!--INDEX case-sensitivity, XUL --> 
     <!--INDEX XUL (XML-based User-interface Language):case-sensitivity -->
     that XUL is case-sensitive. Closing a XUL
     <tt>&lt;window&gt;</tt> tag with <tt>&lt;/Window&gt;</tt>
     renders it invalid.</p>
     <p>These conventions ensure that the rendering engine can parse
     the XUL file successfully and display the elements defined
     there. Mozilla does not validate XML files, such as XUL, and it
     does not resolve externally parsed entities, but it does check
     for document well-formedness.</p>
     <p>Following the XML specification, Mozilla ignores well-formed
     tags that it does not recognize, which can give your
     applications extra flexibility, particularly as you begin to
     use technologies such as XBL. But it can also make debugging a
     little more difficult, as when you create an element named
     <tt>&lt;botton&gt;</tt> and don't see why your XUL button
     doesn't have the typical borders or three-dimensional
     style.</p>
     <p>A good practice to follow when creating XUL files is to use
     comments, copious whitespace, indentations (but not tabbed
     indentations where you can avoid them), and XUL widgets you are
     familiar with.</p>
     <h3><a name="77053"></a> The XUL Namespace</h3>
     <p>Like other markup <!--INDEX namespaces:XUL --> 
     <!--INDEX XUL (XML-based User-interface Language):namespace -->
     vocabularies, XUL uses a namespace declaration to define the
     particular elements that may be included in a valid file. <a
     href="#77018">Example 2-2</a> shows a sample of the required
     namespace declaration. The namespace is an attribute of the
     root <tt>window</tt> element. The lack of any suffix on the XML
     namespace declaration (i.e., <tt>xmlns:xul</tt>) indicates that
     XUL is the default namespace for this file.</p>
     <p><i>Example 2-2: <a name="77018"></a></i> <i>The XUL
     namespace declaration</i></p>
 <pre>
  &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;
    &lt;description&gt;Illustrating the XUL namespace&lt;/description&gt;     &lt;description&gt;Illustrating the XUL namespace&lt;/description&gt;
 &lt;/window&gt;</PRE> &lt;/window&gt;
</pre>
<P>If you want to include XUL content in documents that use other types of markup, you need to declare more than one namespace. Common namespace declarations for getting other language elements into your code include HTML and RDF, but you can invent your own as well. If you wanted to put the button from <A HREF="#77016">Example 2-1</A> into a vanilla XML file, for example, you could place it into an XML document by using the <TT>xmlns:xul</TT> attribute, as shown in <A HREF="#77020">Example 2-3</A>.    <p>If you want to include XUL content in documents that use
    other types of markup, you need to declare more than one
<P><I>Example 2-3: <A NAME="77020"></A></I>    namespace. Common namespace declarations for getting other
<I>Mixed namespaces in an XML document</I>    language elements into your code include HTML and RDF, but you
<PRE> &lt;flies:flies    can invent your own as well. If you wanted to put the button
   xmlns:flies="<A HREF="http://www.flies.com/come.fly.with.me.xml">http://www.flies.com/come.fly.with.me.xml</A>#"    from <a href="#77016">Example 2-1</a> into a vanilla XML file,
   xmlns:html="<A HREF="http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</A>"    for example, you could place it into an XML document by using
   xmlns:xul="<A HREF="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</A>"&gt;    the <tt>xmlns:xul</tt> attribute, as shown in <a href=
     "#77020">Example 2-3</a>.</p>
     <p><i>Example 2-3: <a name="77020"></a></i> <i>Mixed namespaces
     in an XML document</i></p>
 <pre>
  &lt;flies:flies
    xmlns:flies="<a href=
 "http://www.flies.com/come.fly.with.me.xml">http://www.flies.com/come.fly.with.me.xml</a>#"
    xmlns:html="<a href=
 "http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
    xmlns:xul="<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;flies:wings&gt;     &lt;flies:wings&gt;
      &lt;xul:box align="center"&gt;       &lt;xul:box align="center"&gt;
        &lt;xul:button label="hello xFly" onclick="alert('hello.');" /&gt;         &lt;xul:button label="hello xFly" onclick="alert('hello.');" /&gt;
      &lt;/xul:box&gt;       &lt;/xul:box&gt;
      &lt;html:img src="wings.jpg" /&gt;       &lt;html:img src="wings.jpg" /&gt;
    &lt;/flies:wings&gt;     &lt;/flies:wings&gt;
 &lt;/flies:flies&gt;</PRE> &lt;/flies:flies&gt;
</pre>
<P>This file has three types of content: XUL, HTML, and customized markup called <TT>flies</TT>. When you use mixed namespaces, you have to prefix the XUL elements with <TT>xul</TT>: to distinguish them from markup in other namespaces, as with the <TT>xul:box</TT> and <TT>xul:button</TT> shown in <A HREF="#77020">Example 2-3</A>.    <p>This file has three types of content: XUL, HTML, and
<H3><A NAME="77054"></A> Basic XUL Layout</H3>    customized markup called <tt>flies</tt>. When you use mixed
<P><A HREF="#77016">Example 2-1</A> features  <!--INDEX XUL (XML-based User-interface Language):elements --> some very common XUL elements. In this section, each element is dissected to show what it does and how it interacts with other elements. The <TT>&lt;window&gt;</TT> element is the root of individual primary XUL documents (in contrast to dialogs that pop up from  <!--INDEX dialog element, XUL --> windows, which can use <TT>&lt;dialog&gt;</TT> as the root, and XUL documents loaded within other XUL containers, which can use <TT>&lt;page&gt;</TT>).    namespaces, you have to prefix the XUL elements with
<P>As in HTML, the root element defines the document into which all elements are drawn, but in XUL, that document is a piece of an application interface and not a web page. We'll have more to say about the window and some of its features in the second example.    <tt>xul</tt>: to distinguish them from markup in other
<P>A <TT>&lt;box&gt;</TT> element that  <!--INDEX box element, XUL -->  <!--INDEX button element, XUL --> contains a <TT>&lt;button&gt;</TT> is inside the window in <A HREF="#77016">Example 2-1</A>. Although you can use attributes on the window element to lay out and position window children, it's never a bad idea to use the <TT>&lt;box&gt;</TT> as a container, particularly when you add new layout to your document, such as rows of buttons, grids, tabs, or other elements that need to be arranged precisely within the space of the window. The <TT>box</TT> is the basic element for layout in XUL.    namespaces, as with the <tt>xul:box</tt> and
<P>The <TT>align</TT> attribute on the box specifies that the children do not stretch and center themselves in the middle of the available space. If the box was omitted and there were multiple children of the root window, they would be laid out vertically by default, one under the other. This setting can be overridden by adding the <TT>orient</TT> attribute to <TT>&lt;window&gt;</TT> and giving it a value of "horizontal."    <tt>xul:button</tt> shown in <a href="#77020">Example
<H3><A NAME="77055"></A> Using XUL Windows</H3>    2-3</a>.</p>
<P>The foundation of an XPFE application is  <!--INDEX XUL (XML-based User-interface Language):windows -->  <!--INDEX windows:XUL --> a window. Each XUL document has to have at least one XUL <TT>&lt;window&gt;</TT> element, and it must be the root of the document-the surrounding, outermost element in the XML document, set apart from the XML declaration itself and other processing "preambles." A basic window with no content looks like this:    <h3><a name="77054"></a> Basic XUL Layout</h3>
<PRE>&lt;?xml version="1.0"?&gt;    <p><a href="#77016">Example 2-1</a> features 
     <!--INDEX XUL (XML-based User-interface Language):elements -->
     some very common XUL elements. In this section, each element is
     dissected to show what it does and how it interacts with other
     elements. The <tt>&lt;window&gt;</tt> element is the root of
     individual primary XUL documents (in contrast to dialogs that
     pop up from <!--INDEX dialog element, XUL --> windows, which
     can use <tt>&lt;dialog&gt;</tt> as the root, and XUL documents
     loaded within other XUL containers, which can use
     <tt>&lt;page&gt;</tt>).</p>
     <p>As in HTML, the root element defines the document into which
     all elements are drawn, but in XUL, that document is a piece of
     an application interface and not a web page. We'll have more to
     say about the window and some of its features in the second
     example.</p>
     <p>A <tt>&lt;box&gt;</tt> element that 
     <!--INDEX box element, XUL --> 
     <!--INDEX button element, XUL --> contains a
     <tt>&lt;button&gt;</tt> is inside the window in <a href=
     "#77016">Example 2-1</a>. Although you can use attributes on
     the window element to lay out and position window children,
     it's never a bad idea to use the <tt>&lt;box&gt;</tt> as a
     container, particularly when you add new layout to your
     document, such as rows of buttons, grids, tabs, or other
     elements that need to be arranged precisely within the space of
     the window. The <tt>box</tt> is the basic element for layout in
     XUL.</p>
     <p>The <tt>align</tt> attribute on the box specifies that the
     children do not stretch and center themselves in the middle of
     the available space. If the box was omitted and there were
     multiple children of the root window, they would be laid out
     vertically by default, one under the other. This setting can be
     overridden by adding the <tt>orient</tt> attribute to
     <tt>&lt;window&gt;</tt> and giving it a value of
     "horizontal."</p>
     <h3><a name="77055"></a> Using XUL Windows</h3>
     <p>The foundation of an XPFE application is 
     <!--INDEX XUL (XML-based User-interface Language):windows --> 
     <!--INDEX windows:XUL --> a window. Each XUL document has to
     have at least one XUL <tt>&lt;window&gt;</tt> element, and it
     must be the root of the document-the surrounding, outermost
     element in the XML document, set apart from the XML declaration
     itself and other processing "preambles." A basic window with no
     content looks like this:</p>
 <pre>
 &lt;?xml version="1.0"?&gt;
 &lt;!DOCTYPE window&gt;  &lt;!DOCTYPE window&gt;
 &lt;window  &lt;window
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>"&gt;"http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
&lt;/window&gt;</PRE>xmlns="<a href=
<P>Commonly, an application has more than one window, with a number of dialogs and secondary windows. Each window is also  <!--INDEX window element, XUL --> contained within a <TT>&lt;window&gt;</TT> element (though recent additions to the XUL specification include the <TT>dialog</TT> and <TT>page</TT> elements, which are derived from <TT>window</TT> and can be used in its place as root elements in your XUL files)."http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"&gt;
<P>As your application becomes more complex, you need a way to keep track of the windows and ensure that they can communicate with one another. In Mozilla, there is a way to do this by using  <!--INDEX toOpenWindowByType( ) function -->  <!--INDEX functions:toOpenWindowByType( ) --> the <TT>type</TT> attribute identifier, which allows you to use special window-opening functions like <TT>toOpenWindowByType( )</TT> to manage particular window types.&lt;/window&gt;
<BLOCKQUOTE><CENTER><B>NOTE</B></CENTER></pre>
<P>As with any existing Mozilla functions referred to in this book, you can look up <TT>toOpenWindowByType</TT> by using the LXR web-based source     <p>Commonly, an application has more than one window, with a
code viewer, described in <A HREF="appa.html#90096">Appendix A</A> and available at <A HREF="http://lxr.mozilla.org/">http://lxr.mozilla.org/</A>.<P></BLOCKQUOTE>    number of dialogs and secondary windows. Each window is also 
<H4><A NAME="77056"></A> Window features</H4>    <!--INDEX window element, XUL --> contained within a
<P>An <TT>id</TT> attribute is present on  <!--INDEX XUL (XML-based User-interface Language):windows -->  <!--INDEX windows:XML --> the     <tt>&lt;window&gt;</tt> element (though recent additions to the
<TT>&lt;window&gt;</TT> element. Using this  <!--INDEX window element, XUL:id attribute --> attribute is not necessary to run the windows system, but it is a good idea to give each window a unique identifier because it makes nodes easier to find from script (see the DOM method <TT>getElementByID</TT> in <A HREF="ch05.html#77037">Chapter 5</A> for information about how to get elements by identifier). This is how to set up an ID attribute:    XUL specification include the <tt>dialog</tt> and <tt>page</tt>
<PRE>&lt;window    elements, which are derived from <tt>window</tt> and can be
xmlns:html="<A HREF="http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</A>"    used in its place as root elements in your XUL files).</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>"    <p>As your application becomes more complex, you need a way to
id="xflyMain"&gt;</PRE>    keep track of the windows and ensure that they can communicate
<P>Load event handlers such as <TT>onload</TT> and <TT>onunload</TT> are useful and  <!--INDEX load event handlers, window element, XUL --> necessary if you want to add behavior to a window, pass input to it, or manipulate its content depending on context:    with one another. In Mozilla, there is a way to do this by
<PRE>&lt;window    using <!--INDEX toOpenWindowByType( ) function --> 
xmlns:html="<A HREF="http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</A>"    <!--INDEX functions:toOpenWindowByType( ) --> the <tt>type</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>"    attribute identifier, which allows you to use special
     window-opening functions like <tt>toOpenWindowByType( )</tt> to
     manage particular window types.</p>
     <blockquote>
       <div class="c8">
         NOTE
       </div>
       <p>As with any existing Mozilla functions referred to in this
       book, you can look up <tt>toOpenWindowByType</tt> by using
       the LXR web-based source code viewer, described in <a href=
       "appa.html#90096">Appendix A</a> and available at <a href=
       "http://lxr.mozilla.org/">http://lxr.mozilla.org/</a>.</p>
     </blockquote>
     <h4><a name="77056"></a> Window features</h4>
     <p>An <tt>id</tt> attribute is present on 
     <!--INDEX XUL (XML-based User-interface Language):windows --> 
     <!--INDEX windows:XML --> the <tt>&lt;window&gt;</tt> element.
     Using this <!--INDEX window element, XUL:id attribute -->
     attribute is not necessary to run the windows system, but it is
     a good idea to give each window a unique identifier because it
     makes nodes easier to find from script (see the DOM method
     <tt>getElementByID</tt> in <a href="ch05.html#77037">Chapter
     5</a> for information about how to get elements by identifier).
     This is how to set up an ID attribute:</p>
 <pre>
 &lt;window
 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>"
 id="xflyMain"&gt;
 </pre>
     <p>Load event handlers such as <tt>onload</tt> and
     <tt>onunload</tt> are useful and 
     <!--INDEX load event handlers, window element, XUL -->
     necessary if you want to add behavior to a window, pass input
     to it, or manipulate its content depending on context:</p>
 <pre>
 &lt;window
 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>"
 id="xfly-main"  id="xfly-main"
 onload="startUp( )"  onload="startUp( )"
 onunload="shutdown( )"  onunload="shutdown( )"
onclose="onClose( )"&gt;</PRE>onclose="onClose( )"&gt;
<P>When you load a XUL file that begins in this way, the event handler attributes <TT>onload</TT> and <TT>onunload</TT> carry out the functions listed as values (<TT>startUp( )</TT> and <TT>shutdown( )</TT>). In addition, Mozilla provides an <TT>onclose</TT> event handler that intercepts the upcoming window closure to carry out any extra processing you need. The close event is fired before the <TT>unload</TT> event, so you can stop the window from closing in the <TT>onclose</TT> event handler if necessary. To stop window closure, the close event must return <I>false</I>.</pre>
<P>Additional handlers are available for dialog windows. They are listed and their use is outlined in the section <    <p>When you load a XUL file that begins in this way, the event
HREF="ch03.html#77087">"Application Windows</A>" in <A HREF="ch03.html#32764">Chapter 3</A>.    handler attributes <tt>onload</tt> and <tt>onunload</tt> carry
<H4><A NAME="77057"></A> Window properties</H4>    out the functions listed as values (<tt>startUp( )</tt> and
<P>The window declaration is  <!--INDEX windows:XUL:properties -->  <!--INDEX properties:windows, XUL -->  <!--INDEX XUL (XML-based User-interface Language):windows:properties --> expanding, but there is still plenty of room for more features. In addition to the <I>attributes-</I>the event handlers, the ID, and the namespace that appear within the <TT>&lt;window&gt;</TT> tag itself-a XUL window also has all of the properties of the DOM <TT>window</TT> object from HTML. These properties are listed below, along with additional properties for application specific tasks.    <tt>shutdown( )</tt>). In addition, Mozilla provides an
<P><TABLE WIDTH=100% BORDER=1><TR><TD> Navigator</TD>     <TD> Document</TD>     <TD> window</TD>     <TD> Parent</TD></TR>    <tt>onclose</tt> event handler that intercepts the upcoming
<TR><TD> Top</TD>     <TD> Scrollbars</TD>     <TD> name</TD>     <TD> ScrollX</TD></TR>    window closure to carry out any extra processing you need. The
<TR><TD> ScrollY</TD>     <TD> ScrollTo</TD>     <TD> scrollBy</TD>     <TD> GetSelection</TD></TR>    close event is fired before the <tt>unload</tt> event, so you
<TR><TD> ScrollByLines</TD>     <TD> ScrollByPages</TD>     <TD> Size</TD></TR>    can stop the window from closing in the <tt>onclose</tt> event
<TR><TD> ToContent</TD>     <TD> Dump</TD></TR>    handler if necessary. To stop window closure, the close event
<TR><TD> SetTimeout</TD>     <TD> SetInterval</TD>     <TD> Clear</TD></TR>    must return <i>false</i>.</p>
<TR><TD> Timeout</TD>     <TD> ClearInterval</TD></TR>    <p>Additional handlers are available for dialog windows. They
<TR><TD> SetResizable</TD>     <TD> CaptureEvents</TD>     <TD> Release</TD></TR>    are listed and their use is outlined in the section <a href=
<TR><TD> Events</TD>     <TD> RouteEvent</TD></TR>    "ch03.html#77087">"Application Windows</a>" in <a href=
<TR><TD> Enable</TD></TR>    "ch03.html#32764">Chapter 3</a>.</p>
<TR><TD> External</TD></TR>    <h4><a name="77057"></a> Window properties</h4>
<TR><TD> Capture</TD>     <TD> DisableExternal</TD></TR>    <p>The window declaration is 
<TR><TD> Capture</TD>     <TD> prompt</TD>     <TD> Open</TD></TR>    <!--INDEX windows:XUL:properties --> 
<TR><TD> OpenDialog</TD>     <TD> Frames</TD>     <TD> find</TD>     <TD> self</TD></TR>    <!--INDEX properties:windows, XUL --> 
<TR><TD> Screen</TD>     <TD> History</TD>     <TD> content</TD>     <TD> Sidebar</TD></TR>    <!--INDEX XUL (XML-based User-interface Language):windows:properties -->
<TR><TD> Menubar</TD>     <TD> Toolbar</TD>     <TD> Locationbar</TD>     <TD> Personalbar</TD></TR>    expanding, but there is still plenty of room for more features.
<TR><TD> Statusbar</TD>     <TD> Directories</TD>     <TD> closed</TD>     <TD> Crypto</TD></TR>    In addition to the <i>attributes-</i>the event handlers, the
<TR><TD> pkcs11</TD>     <TD> Controllers</TD>     <TD> opener</TD>     <TD> Status</TD></TR>    ID, and the namespace that appear within the
<TR><TD> defaultStatus</TD>     <TD> Location</TD>     <TD> innerWidth</TD>     <TD> InnerHeight</TD></TR>    <tt>&lt;window&gt;</tt> tag itself-a XUL window also has all of
<TR><TD> outerWidth</TD>     <TD> OuterHeight</TD>     <TD> screenX</TD>     <TD> ScreenY</TD></TR>    the properties of the DOM <tt>window</tt> object from HTML.
<TR><TD> pageXOffset</TD>     <TD> PageYOffset</TD>     <TD> length</TD>     <TD> FullScreen</TD></TR>    These properties are listed below, along with additional
<TR><TD> alert</TD>     <TD> Confirm</TD>     <TD> focus</TD>     <TD> Blur</TD></TR>    properties for application specific tasks.</p>
<TR><TD> back</TD>     <TD> Forward</TD>     <TD> home</TD>     <TD> Stop</TD></TR>    <table width="100%" border="1">
<TR><TD> print</TD>     <TD> MoveTo</TD>     <TD> moveBy</TD>     <TD> ResizeTo</TD></TR>      <tr>
<TR><TD> resizeBy</TD>     <TD> Scroll</TD>     <TD> close</TD>     <TD> UpdateCommands</TD></TR>        <td>Navigator</td>
<TR><TD> escape</TD>     <TD> Unescape</TD>     <TD> atob</TD>     <TD> Btoa</TD></TR>        <td>Document</td>
<TR><TD> AddEvent</TD></TR>        <td>window</td>
<TR><TD> Listener</TD>     <TD> RemoveEvent</TD></TR>        <td>Parent</td>
<TR><TD> Listener</TD>     <TD> Dispatch</TD></TR>      </tr>
<TR><TD> Event</TD>     <TD> GetComputed</TD></TR>      <tr>
<TR><TD> Style</TD></TR></TABLE><P>        <td>Top</td>
        <td>Scrollbars</td>
<P>Special properties of the XUL window object include:        <td>name</td>
<DL><DT>window.content        <td>ScrollX</td>
<DD>Using this property is a quick way  <!--INDEX window.content property, window object --> to access the content area of your window, if one       </tr>
exists. This property is useful only if your window uses one of the content elements, namely <TT>&lt;iframe&gt;</TT>, <TT>&lt;browser&gt;</TT>,       <tr>
and <TT>&lt;editor&gt;</TT>. Refer to the section <A HREF="ch03.html#77123">"Content Panels</A>" in <A HREF="ch03.html#32764">Chapter 3</A> for a more detailed discussion. The <TT>content</TT> property is linked only to the frame you have explicitly declared as the primary area.<P></DL>        <td>ScrollY</td>
&lt;browser type="content-primary" ...&gt;        <td>ScrollTo</td>
<DL><DD>Subsequently, you can access and manipulate the content.<P></DL>        <td>scrollBy</td>
window.content.focus( );        <td>GetSelection</td>
<DL><DT>window.sizeToContent( )      </tr>
<DD>This property is used to ensure  <!--INDEX window.sizeToContent( ) property, window object --> intrinsic sizing, which is important in XUL application development, especially in dialog windows. Intrinsic sizing ensures that the window adapts and morphs to fit the content. This is preferable to constraining your window with a fixed width and height when the <TT>onload</TT> handler anticipates changeable content, depends on context, or takes input from another window. The colorpicker in the Mozilla Editor, for example, uses this function to make sure that the window displaying the chosen palette shrinks to fit that palette:<P></DL>      <tr>
function ChangePalette(palette)        <td>ScrollByLines</td>
{        <td>ScrollByPages</td>
  gDialog.ColorPicker.setAttribute("palettename", palette);        <td>Size</td>
  window.sizeToContent( );      </tr>
}      <tr>
<H4><A NAME="77058"></A> Interaction between windows</H4>        <td>ToContent</td>
<P>The <TT>nsIWindowMediator</TT> XPCOM component  <!--INDEX nsIWindowMediator, XPCOM -->  <!--INDEX XPCOM:nsIWindowMediator -->  <!--INDEX windows:XUL:nsIWindowMeditor -->  <!--INDEX XUL (XML-based User-interface Language):windows:nsIWindowMediator --> provides several routines for interacting with different windows. Though it's a little too early to discuss using a component like this in the Hello World examples, these routines include:        <td>Dump</td>
<UL><P><LI>Getting the most recent window of a particular type<P>      </tr>
<P><LI>Enumerating all open windows<P>      <tr>
<P><LI>Registering and unregistering the window<P>        <td>SetTimeout</td>
<P><LI>Updating the window timestamp<P>        <td>SetInterval</td>
<P><LI>Updating the window title<P>        <td>Clear</td>
<P><LI>Setting the Z-order position<P></UL>      </tr>
<P><A HREF="ch08.html#78382">Chapter 8</A> provides full details of how to understand and use XPCOM components.      <tr>
<H4><A NAME="77059"></A> Window behavior</H4>        <td>Timeout</td>
<P>Mozilla supports the  <!--INDEX XUL (XML-based User-interface Language):windows:behaviors -->  <!--INDEX windows:XUL:behaviors -->  <!--INDEX window.open function (JavaScript) -->  <!--INDEX functions:JavaScript:window.open -->  <!--INDEX JavaScript:functions:window.open --> standard <TT>window.open</TT> JavaScript function, which has its origins in the world of browser scripting and the launching of new browser windows. Mozilla extends the function to provide some features for application development. It also provides the <TT>window.openDialog</TT>  <!--INDEX window.openDialog function, JavaScript -->  <!--INDEX functions:JavaScript:window.OpenDialog -->  <!--INDEX JavaScript:functions:window.openDialog --> function for opening windows in the XPFE scripting environment. The latter function has become the more commonly used method to open a new XUL window, although the two are interchangeable.        <td>ClearInterval</td>
<P>The usage of <TT>window.open</TT> is:      </tr>
<PRE>window.open (url, name, features);</PRE>      <tr>
<P><TT>window.openDialog</TT> extends this functionality with a new argument list passed to it, which is optional and can be any number of arguments as needed:        <td>SetResizable</td>
<PRE>window.openDialog (url, type, features, argument1, argument2);</PRE>        <td>CaptureEvents</td>
<P>Here is a list of some of the features of a XUL window opened using <TT>window.openDialog</TT>:        <td>Release</td>
<DL><DT>close      </tr>
<DD>The window can be created with or without a close widget.<P>      <tr>
<DT>chrome        <td>Events</td>
<DD>The new window has to  <!--INDEX chrome context, XUL windows -->  <!--INDEX XUL (XML-based User-interface Language):windows:chrome context -->  <!--INDEX windows:XUL:chrome context --> be treated as a window within the chrome context, rather than in the browser context. It gets its own top-level window. The window itself is the chrome URL passed to the function, and is not to be loaded in a browser window.<P>        <td>RouteEvent</td>
<DT>dependent      </tr>
<DD>The new window belongs  <!--INDEX dependence, XUL windows -->  <!--INDEX windows:XUL:dependence -->  <!--INDEX XUL (XML-based User-interface Language):windows:dependence --> to the calling window on operating systems that support this behavior. It "floats" on top of the opening window, and you can still access the parent window. It is minimized with its parent.<P>      <tr>
<DT>modal        <td>Enable</td>
<DD>The window will be run  <!--INDEX modality, XUL windows -->  <!--INDEX XUL (XML-based User-interface Language):windows:modality -->  <!--INDEX windows:XUL:modality --> modally. Control is not given back to the parent window until this window has closed.<P>      </tr>
<DT>titlebar      <tr>
<DD>The window can be created  <!--INDEX windows:XUL:titlebars -->  <!--INDEX XUL (XML-based User-interface Language):windows:titlebar -->  <!--INDEX titlebars, XUL windows --> with or without a titlebar.<P>        <td>External</td>
<DT>centerscreen      </tr>
<DD>Open the window centered  <!--INDEX centerscreen, windows (XUL) -->  <!--INDEX windows:XUL:centerscreen -->  <!--INDEX XUL (XML-based User-interface Language):windows:centerscreen --> on screen.<P></DL>      <tr>
<P>A comma delimits the features list and the entire list must be in quotes. The script that handles the new window accesses the arguments list:        <td>Capture</td>
<PRE>window.openDialog("chrome://xfly/content/utils/prompt.xul"        <td>DisableExternal</td>
       </tr>
       <tr>
         <td>Capture</td>
         <td>prompt</td>
         <td>Open</td>
       </tr>
       <tr>
         <td>OpenDialog</td>
         <td>Frames</td>
         <td>find</td>
         <td>self</td>
       </tr>
       <tr>
         <td>Screen</td>
         <td>History</td>
         <td>content</td>
         <td>Sidebar</td>
       </tr>
       <tr>
         <td>Menubar</td>
         <td>Toolbar</td>
         <td>Locationbar</td>
         <td>Personalbar</td>
       </tr>
       <tr>
         <td>Statusbar</td>
         <td>Directories</td>
         <td>closed</td>
         <td>Crypto</td>
       </tr>
       <tr>
         <td>pkcs11</td>
         <td>Controllers</td>
         <td>opener</td>
         <td>Status</td>
       </tr>
       <tr>
         <td>defaultStatus</td>
         <td>Location</td>
         <td>innerWidth</td>
         <td>InnerHeight</td>
       </tr>
       <tr>
         <td>outerWidth</td>
         <td>OuterHeight</td>
         <td>screenX</td>
         <td>ScreenY</td>
       </tr>
       <tr>
         <td>pageXOffset</td>
         <td>PageYOffset</td>
         <td>length</td>
         <td>FullScreen</td>
       </tr>
       <tr>
         <td>alert</td>
         <td>Confirm</td>
         <td>focus</td>
         <td>Blur</td>
       </tr>
       <tr>
         <td>back</td>
         <td>Forward</td>
         <td>home</td>
         <td>Stop</td>
       </tr>
       <tr>
         <td>print</td>
         <td>MoveTo</td>
         <td>moveBy</td>
         <td>ResizeTo</td>
       </tr>
       <tr>
         <td>resizeBy</td>
         <td>Scroll</td>
         <td>close</td>
         <td>UpdateCommands</td>
       </tr>
       <tr>
         <td>escape</td>
         <td>Unescape</td>
         <td>atob</td>
         <td>Btoa</td>
       </tr>
       <tr>
         <td>AddEvent</td>
       </tr>
       <tr>
         <td>Listener</td>
         <td>RemoveEvent</td>
       </tr>
       <tr>
         <td>Listener</td>
         <td>Dispatch</td>
       </tr>
       <tr>
         <td>Event</td>
         <td>GetComputed</td>
       </tr>
       <tr>
         <td>Style</td>
       </tr>
     </table>
     <p>Special properties of the XUL window object include:</p>
     <dl>
       <dt>window.content</dt>
       <dd>Using this property is a quick way 
       <!--INDEX window.content property, window object --> to
       access the content area of your window, if one exists. This
       property is useful only if your window uses one of the
       content elements, namely <tt>&lt;iframe&gt;</tt>,
       <tt>&lt;browser&gt;</tt>, and <tt>&lt;editor&gt;</tt>. Refer
       to the section <a href="ch03.html#77123">"Content Panels</a>"
       in <a href="ch03.html#32764">Chapter 3</a> for a more
       detailed discussion. The <tt>content</tt> property is linked
       only to the frame you have explicitly declared as the primary
       area.</dd>
     </dl>
     &lt;browser type="content-primary" ...&gt; 
     <dl>
       <dd>Subsequently, you can access and manipulate the
       content.</dd>
     </dl>
     window.content.focus( ); 
     <dl>
       <dt>window.sizeToContent( )</dt>
       <dd>This property is used to ensure 
       <!--INDEX window.sizeToContent( ) property, window object -->
       intrinsic sizing, which is important in XUL application
       development, especially in dialog windows. Intrinsic sizing
       ensures that the window adapts and morphs to fit the content.
       This is preferable to constraining your window with a fixed
       width and height when the <tt>onload</tt> handler anticipates
       changeable content, depends on context, or takes input from
       another window. The colorpicker in the Mozilla Editor, for
       example, uses this function to make sure that the window
       displaying the chosen palette shrinks to fit that
       palette:</dd>
     </dl>
     function ChangePalette(palette) {
     gDialog.ColorPicker.setAttribute("palettename", palette);
     window.sizeToContent( ); 
     <h4><a name="77058"></a> Interaction between windows</h4>
     <p>The <tt>nsIWindowMediator</tt> XPCOM component 
     <!--INDEX nsIWindowMediator, XPCOM --> 
     <!--INDEX XPCOM:nsIWindowMediator --> 
     <!--INDEX windows:XUL:nsIWindowMeditor --> 
     <!--INDEX XUL (XML-based User-interface Language):windows:nsIWindowMediator -->
     provides several routines for interacting with different
     windows. Though it's a little too early to discuss using a
     component like this in the Hello World examples, these routines
     include:</p>
     <ul>
       <li>Getting the most recent window of a particular type</li>
       <li>Enumerating all open windows</li>
       <li>Registering and unregistering the window</li>
       <li>Updating the window timestamp</li>
       <li>Updating the window title</li>
       <li>Setting the Z-order position</li>
     </ul>
     <p><a href="ch08.html#78382">Chapter 8</a> provides full
     details of how to understand and use XPCOM components.</p>
     <h4><a name="77059"></a> Window behavior</h4>
     <p>Mozilla supports the 
     <!--INDEX XUL (XML-based User-interface Language):windows:behaviors -->
     <!--INDEX windows:XUL:behaviors --> 
     <!--INDEX window.open function (JavaScript) --> 
     <!--INDEX functions:JavaScript:window.open --> 
     <!--INDEX JavaScript:functions:window.open --> standard
     <tt>window.open</tt> JavaScript function, which has its origins
     in the world of browser scripting and the launching of new
     browser windows. Mozilla extends the function to provide some
     features for application development. It also provides the
     <tt>window.openDialog</tt> 
     <!--INDEX window.openDialog function, JavaScript --> 
     <!--INDEX functions:JavaScript:window.OpenDialog --> 
     <!--INDEX JavaScript:functions:window.openDialog --> function
     for opening windows in the XPFE scripting environment. The
     latter function has become the more commonly used method to
     open a new XUL window, although the two are
     interchangeable.</p>
     <p>The usage of <tt>window.open</tt> is:</p>
 <pre>
 window.open (url, name, features);
 </pre>
     <p><tt>window.openDialog</tt> extends this functionality with a
     new argument list passed to it, which is optional and can be
     any number of arguments as needed:</p>
 <pre>
 window.openDialog (url, type, features, argument1, argument2);
 </pre>
     <p>Here is a list of some of the features of a XUL window
     opened using <tt>window.openDialog</tt>:</p>
     <dl>
       <dt>close</dt>
       <dd>The window can be created with or without a close
       widget.</dd>
       <dt>chrome</dt>
       <dd>The new window has to 
       <!--INDEX chrome context, XUL windows --> 
       <!--INDEX XUL (XML-based User-interface Language):windows:chrome context -->
       <!--INDEX windows:XUL:chrome context --> be treated as a
       window within the chrome context, rather than in the browser
       context. It gets its own top-level window. The window itself
       is the chrome URL passed to the function, and is not to be
       loaded in a browser window.</dd>
       <dt>dependent</dt>
       <dd>The new window belongs 
       <!--INDEX dependence, XUL windows --> 
       <!--INDEX windows:XUL:dependence --> 
       <!--INDEX XUL (XML-based User-interface Language):windows:dependence -->
       to the calling window on operating systems that support this
       behavior. It "floats" on top of the opening window, and you
       can still access the parent window. It is minimized with its
       parent.</dd>
       <dt>modal</dt>
       <dd>The window will be run 
       <!--INDEX modality, XUL windows --> 
       <!--INDEX XUL (XML-based User-interface Language):windows:modality -->
       <!--INDEX windows:XUL:modality --> modally. Control is not
       given back to the parent window until this window has
       closed.</dd>
       <dt>titlebar</dt>
       <dd>The window can be created 
       <!--INDEX windows:XUL:titlebars --> 
       <!--INDEX XUL (XML-based User-interface Language):windows:titlebar -->
       <!--INDEX titlebars, XUL windows --> with or without a
       titlebar.</dd>
       <dt>centerscreen</dt>
       <dd>Open the window centered 
       <!--INDEX centerscreen, windows (XUL) --> 
       <!--INDEX windows:XUL:centerscreen --> 
       <!--INDEX XUL (XML-based User-interface Language):windows:centerscreen -->
       on screen.</dd>
     </dl>
     <p>A comma delimits the features list and the entire list must
     be in quotes. The script that handles the new window accesses
     the arguments list:</p>
 <pre>
 window.openDialog("chrome://xfly/content/utils/prompt.xul"
 "XFLYndo_prompt",  "XFLYndo_prompt",
 "chrome,dialog,modal",  "chrome,dialog,modal",
message);</PRE>message);
<P>The window created in this example will be modal and use the message that was passed to it in the variable <I>message</I>. By default, Mozilla assumes that the <TT>chrome</TT> feature is on when you use either <TT>window.open</TT> or <TT>window.openDialog</TT> in a chrome environment, and creates a new window in the window hierarchy.</pre>
<H2><A NAME="77060"></A> Making Mozilla Work for You</H2>    <p>The window created in this example will be modal and use the
<P>The second "Hello World" sample,  <!--INDEX Hello World XUL example:JavaScript and -->  <!--INDEX XUL (XML-based User-interface Language):Hello World example:JavaScript and --> shown in <A HREF="#77022">Example 2-4</A>, adds some important application features and begins to take advantage of the resources that Mozilla provides for you. This section goes over the ways you can import stylesheets and Mozilla scripts to make your XUL more sophisticated and modular. It also prepares you to make an actual application.    message that was passed to it in the variable <i>message</i>.
<P>You can see this example in action by saving the code in <A HREF="#77022">Example 2-4</A> to a file, <I>hello2.xul</I>, and then launching Mozilla and selecting File &gt; Open File from the browser. This displays the example as content in the Mozilla browser, as shown in <A HREF="#77004">Figure 2-2</A>.    By default, Mozilla assumes that the <tt>chrome</tt> feature is
    on when you use either <tt>window.open</tt> or
<P><I>Example 2-4: <A NAME="77022"></A></I>    <tt>window.openDialog</tt> in a chrome environment, and creates
<I>Sample XUL window</I>    a new window in the window hierarchy.</p>
<PRE> &lt;?xml version="1.0"?&gt;    <h2><a name="77060"></a> Making Mozilla Work for You</h2>
     <p>The second "Hello World" sample, 
     <!--INDEX Hello World XUL example:JavaScript and --> 
     <!--INDEX XUL (XML-based User-interface Language):Hello World example:JavaScript and -->
     shown in <a href="#77022">Example 2-4</a>, adds some important
     application features and begins to take advantage of the
     resources that Mozilla provides for you. This section goes over
     the ways you can import stylesheets and Mozilla scripts to make
     your XUL more sophisticated and modular. It also prepares you
     to make an actual application.</p>
     <p>You can see this example in action by saving the code in <a
     href="#77022">Example 2-4</a> to a file, <i>hello2.xul</i>, and
     then launching Mozilla and selecting File &gt; Open File from
     the browser. This displays the example as content in the
     Mozilla browser, as shown in <a href="#77004">Figure
     2-2</a>.</p>
     <p><i>Example 2-4: <a name="77022"></a></i> <i>Sample XUL
     window</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;!DOCTYPE window&gt;   &lt;!DOCTYPE window&gt;
  &lt;window title="Hello xFly"   &lt;window title="Hello xFly"
   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="background-color: white;"     style="background-color: white;"
    width="300"     width="300"
    height="215"     height="215"
Line 214  message);</PRE> Line 702  message);</PRE>
  &lt;vbox align="left"&gt;   &lt;vbox align="left"&gt;
    &lt;label style="font-weight: bold;"     &lt;label style="font-weight: bold;"
        value="Hello, Welcome to the xFly" /&gt;         value="Hello, Welcome to the xFly" /&gt;
   &lt;image src="<A HREF="http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</A>" /&gt;   &lt;image src="<a href=
 "http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</a>" /&gt;
    &lt;button label="hello xFly" oncommand="alert('Hello World');" /&gt;     &lt;button label="hello xFly" oncommand="alert('Hello World');" /&gt;
  &lt;/vbox&gt;   &lt;/vbox&gt;
 &lt;/window&gt;</PRE> &lt;/window&gt;
</pre>
<P>The difference between <A HREF="#77022">Example 2-4</A> and the first example is the addition of new elements, including the <TT>script</TT> element that brings in Mozilla JavaScript functions for use, additional box layout properties, inline style rules and processing instructions to import stylesheets, and the <TT>DOCTYPE</TT> declaration, which we describe later in this chapter in the section <A HREF="#77078">"The xFly DTD</A>."    <p>The difference between <a href="#77022">Example 2-4</a> and
<P>These extras make your XUL file work more like an application by giving you access to services and features that already exist in Mozilla. They can also help you organize your own work into reusable parts, such as application stylesheets, widgets, and script libraries, as described later in this chapter in the section <A HREF="#77065">"Creating a Package</A>."    the first example is the addition of new elements, including
<P><CENTER><IMG SRC="foo.gif"></CENTER>    the <tt>script</tt> element that brings in Mozilla JavaScript
<P><I>Figure 2-2: <A NAME="77004"></A></I>    functions for use, additional box layout properties, inline
<I>The second Hello xFly example loaded in the browser</I>    style rules and processing instructions to import stylesheets,
    and the <tt>DOCTYPE</tt> declaration, which we describe later
<H3><A NAME="77061"></A> Importing Resources from Mozilla</H3>    in this chapter in the section <a href="#77078">"The xFly
<P>The code in <A HREF="#77022">Example 2-4</A> uses scripts  <!--INDEX resources:importing from Mozilla -->  <!--INDEX importing:resources --> and styles that are already defined in Mozilla. As you'll see in examples in this book  <!--INDEX global.css stylesheet -->  <!--INDEX stylesheets:global.css --> and in the Mozilla source code, the <I>global.css</I> stylesheet is where many basic styles  <!--INDEX XUL widgets:styles;widgets:XUL:styles;styles:widgets, XUL --> are defined for XUL widgets. Most XUL widgets have some inherent style, as you can see in <A HREF="#77016">Example 2-1</A>, where the button has a button-like look without any explicit style rules or stylesheet imports.    DTD</a>."</p>
<P>As the XPFE has evolved, XUL widgets  <!--INDEX XUL widgets:XBL and;XBL (eXtensible Binding Language):XUL widgets and --> have used XBL internally to define some of these inherent looks and behaviors, which has taken some of the responsibility away from <I>global.css</I> and other CSS files. But this stylesheet still contains important rules for displaying basic XUL widgets. It's usually a good idea to import this main stylesheet into your application, as described here, and see what it gets you in terms of presentation. If you load <A HREF="#77022">Example 2-4</A> with and without the <I>global.css</I> line, you can see the way that the rules in the stylesheet provide styles for the widgets in the XUL.    <p>These extras make your XUL file work more like an
<P>Similarly, scripts like <I>globalOverlay.js</I>, <I>tasksOverlay.js</I>, and <I>dialogOverlay.js</I>, imported in <A HREF="#77022">Example 2-4</A>, provide basic functions you can use in your applications.    application by giving you access to services and features that
<H4><A NAME="77062"></A> Loading stylesheets</H4>    already exist in Mozilla. They can also help you organize your
<P>In the second line of <A HREF="#77022">Example 2-4</A>, the stylesheet  <!--INDEX stylesheets:loading --> declaration uses a <I>chrome://</I> URL to refer to and load the <I>global.css</I> file. The style rules in that file give the button widget its "widgetness." You can use the stylesheet  <!--INDEX stylesheets:(see also CSS)[stylesheets:zz(see also CSS)] --> processing instruction to load Mozilla stylesheets like <I>global.css</I>, <I>navigator.css</I>,  <!--INDEX navigator.css stylesheet;toolbar.css stylesheet;stylesheets:navigator.css;stylesheets:toolbar.css --> and <I>toolbar.css</I>, or you can use it to load your own application stylesheet. In both cases, the <I>chrome://</I> URL allows you to refer to packaged files in a flexible way.    own work into reusable parts, such as application stylesheets,
<PRE>&lt;!--import the navigator.css stylesheet    widgets, and script libraries, as described later in this
     chapter in the section <a href="#77065">"Creating a
     Package</a>."</p>
     <div class="c7">
       <img src="foo.gif">
     </div>
     <p><i>Figure 2-2: <a name="77004"></a></i> <i>The second Hello
     xFly example loaded in the browser</i></p>
     <h3><a name="77061"></a> Importing Resources from Mozilla</h3>
     <p>The code in <a href="#77022">Example 2-4</a> uses scripts 
     <!--INDEX resources:importing from Mozilla --> 
     <!--INDEX importing:resources --> and styles that are already
     defined in Mozilla. As you'll see in examples in this book 
     <!--INDEX global.css stylesheet --> 
     <!--INDEX stylesheets:global.css --> and in the Mozilla source
     code, the <i>global.css</i> stylesheet is where many basic
     styles 
     <!--INDEX XUL widgets:styles;widgets:XUL:styles;styles:widgets, XUL -->
     are defined for XUL widgets. Most XUL widgets have some
     inherent style, as you can see in <a href="#77016">Example
     2-1</a>, where the button has a button-like look without any
     explicit style rules or stylesheet imports.</p>
     <p>As the XPFE has evolved, XUL widgets 
     <!--INDEX XUL widgets:XBL and;XBL (eXtensible Binding Language):XUL widgets and -->
     have used XBL internally to define some of these inherent looks
     and behaviors, which has taken some of the responsibility away
     from <i>global.css</i> and other CSS files. But this stylesheet
     still contains important rules for displaying basic XUL
     widgets. It's usually a good idea to import this main
     stylesheet into your application, as described here, and see
     what it gets you in terms of presentation. If you load <a href=
     "#77022">Example 2-4</a> with and without the <i>global.css</i>
     line, you can see the way that the rules in the stylesheet
     provide styles for the widgets in the XUL.</p>
     <p>Similarly, scripts like <i>globalOverlay.js</i>,
     <i>tasksOverlay.js</i>, and <i>dialogOverlay.js</i>, imported
     in <a href="#77022">Example 2-4</a>, provide basic functions
     you can use in your applications.</p>
     <h4><a name="77062"></a> Loading stylesheets</h4>
     <p>In the second line of <a href="#77022">Example 2-4</a>, the
     stylesheet <!--INDEX stylesheets:loading --> declaration uses a
     <i>chrome://</i> URL to refer to and load the <i>global.css</i>
     file. The style rules in that file give the button widget its
     "widgetness." You can use the stylesheet 
     <!--INDEX stylesheets:(see also CSS)[stylesheets:zz(see also CSS)] -->
     processing instruction to load Mozilla stylesheets like
     <i>global.css</i>, <i>navigator.css</i>, 
     <!--INDEX navigator.css stylesheet;toolbar.css stylesheet;stylesheets:navigator.css;stylesheets:toolbar.css -->
     and <i>toolbar.css</i>, or you can use it to load your own
     application stylesheet. In both cases, the <i>chrome://</i> URL
     allows you to refer to packaged files in a flexible way.</p>
 <pre>
 &lt;!--import the navigator.css stylesheet
 from the Mozilla navigator component--&gt;  from the Mozilla navigator component--&gt;
 &lt;?xml-stylesheet href="chrome://navigator/skin" type="text/css"?&gt;  &lt;?xml-stylesheet href="chrome://navigator/skin" type="text/css"?&gt;
 &lt;!--import xfly.css stylesheet from the xFly package--&gt;  &lt;!--import xfly.css stylesheet from the xFly package--&gt;
&lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;</PRE>&lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;
<P>Also note the use of an inline style in <A HREF="#77022">Example 2-4</A>. The <TT>style</TT> property on the <TT>label</TT> widget gives you a place to define CSS rules directly on widgets. In this case, the label is given a bold font so that it shows up better in the window. You could also define this style rule in an external stylesheet and make that stylesheet part of the package for your application, as we do later in this chapter in the section <A HREF="#77075">"Separating the Files</A>."</pre>
<H4><A NAME="77063"></A> Accessing script in XUL</H4>    <p>Also note the use of an inline style in <a href=
<P>To access a script in XUL, use the <TT>script</TT> element  <!--INDEX XUL (XML-based User-interface Language):scripts, access;scripts:XUL, access --> and a URL value for its <TT>src</TT> attribute:    "#77022">Example 2-4</a>. The <tt>style</tt> property on the
<PRE>&lt;script type="application/x-javascript"    <tt>label</tt> widget gives you a place to define CSS rules
src="chrome://xfly/content/xfly.js" /&gt;</PRE>    directly on widgets. In this case, the label is given a bold
<P>The <TT>dialogOverlay.js</TT> script imported into  <!--INDEX dialogOverlay.js script;scripts:dialogOverlay.js --> your XUL file in <    font so that it shows up better in the window. You could also
HREF="#77022">Example 2-4</A> provides access to the <TT>CenterWindowOnScreen( )</TT> function. This  <!--INDEX CenterWindowOnScreen( ) function, JavaScript;functions:JavaScript:CenterWindowOnScreen( );JavaScript:functions:CenterWindowOnScreen( ) --> function is made available to your XUL file with the line:    define this style rule in an external stylesheet and make that
<PRE>&lt;script type="application/x-javascript"    stylesheet part of the package for your application, as we do
src="chrome://global/content/dialogOverlay.js" /&gt;</PRE>    later in this chapter in the section <a href=
<P>All functions in <I>dialogOverlay.js</I> are imported into the scope of the XUL file and can be called directly, as <TT>CenterWindowOnScreen( )</TT> is in the <TT>onload</TT> event handler for the XUL window. Note that the functions contained in an imported JavaScript file are not broadcast in any particular way (though you can see them if you use the JavaScript Debugger). You may need to look around in the source code or see how other applications import files to find the functions you need, but the routines you want to use in your application code are probably already available in Mozilla.<A NAME="b260"></A><A HREF="#260">[*]</A>    "#77075">"Separating the Files</a>."</p>
<H2><A NAME="77064"></A> Displaying XUL Files as Chrome</H2>    <h4><a name="77063"></a> Accessing script in XUL</h4>
<P><A HREF="#77004">Figure 2-2</A> shows the XUL file  <!--INDEX XUL files:displaying as chrome;chrome:XUL files, displaying --> in <A HREF="#77022">Example 2-4</A> loaded into the browser's main content area. The example features a <TT>label</TT> widget and an <TT>image</TT>, both situated within a <TT>vbox</TT> that lays them out properly in the available space. These widgets make up the chrome of your application, the Mozilla user interface that can refer to itself and its resources with the special <I>chrome://</I> URL.    <p>To access a script in XUL, use the <tt>script</tt> element 
<P>This example is starting to show off some of the nice features of XPFE programming, but it still isn't an application yet. Among other things, you probably don't want your code to live inside the browser window forever. As it grows, you may also want to divide it into sensible parts-a XUL file, a separate stylesheet, and a script file, for example. The rest of this chapter explains how to organize and package the code in <A HREF="#77022">Example 2-4</A> and launch it as a standalone window by using the <TT>-chrome</TT> option when launching Mozilla.    <!--INDEX XUL (XML-based User-interface Language):scripts, access;scripts:XUL, access -->
<P>Launching a XUL file by using the chrome switch requires that you register your application in the chrome registry so that Mozilla sees and recognizes it. The <A HREF="#77079">"Registering a Package</A>" section later in this chapter provides more information about the chrome environment and how to register this sample application.    and a URL value for its <tt>src</tt> attribute:</p>
<P>Although this example hasn't been registered yet, we want to give you a preview of what it will look like when launched in a standalone window so you can compare it with how the same XUL file looks when loaded into the browser window. When you do launch the example by using the <TT>-chrome</TT> option (as described later in this chapter in the section <A HREF="#77080">"Launching the Application</A>"), you will see the window displayed in <A HREF="#77006">Figure 2-3</A>.<pre>
<P><CENTER><IMG SRC="foo.gif"></CENTER>&lt;script type="application/x-javascript"
<P><I>Figure 2-3: <A NAME="77006"></A></I>src="chrome://xfly/content/xfly.js" /&gt;
<I>The second Hello xFly example launched in its own window</I></pre>
    <p>The <tt>dialogOverlay.js</tt> script imported into 
<P>Using the <TT>-chrome</TT> option tells Mozilla to display the specified file (in this case, the code from <A HREF="#77022">Example 2-4</A>) as a standalone application rather than as content within a browser window. The file itself is the same regardless of how it is loaded, but the results differ depending on what you tell Mozilla to do with the file.    <!--INDEX dialogOverlay.js script;scripts:dialogOverlay.js -->
<P>Displaying a XUL file in its own chrome window makes it more independent and breaks the link to the browser content area that is present when you use the File &gt; Open File... method. Launching standalone windows, accompanied by the JavaScript <TT>window.openDialog</TT> function explained later in this chapter, opens up much more flexible window display options for your application.    your XUL file in <a href="#77022">Example 2-4</a> provides
<H2><A NAME="77065"></A> Creating a Package</H2>    access to the <tt>CenterWindowOnScreen( )</tt> function. This 
<P>The previous two main sections  <!--INDEX chrome:package content;packages:chrome and --> introduced the concept of chrome and the prospect of creating standalone application windows. The next step is to make the example into an actual package-a modularized collection of files that can be installed in Mozilla as a new application.    <!--INDEX CenterWindowOnScreen( ) function, JavaScript;functions:JavaScript:CenterWindowOnScreen( );JavaScript:functions:CenterWindowOnScreen( ) -->
<P>In the earlier section <A HREF="#77060">"Making Mozilla Work for You</A>," you added features and complexity to your XUL file. In this section, you pull those features into separate files-a CSS file, JS file, and a DTD file-register these files together, and make them installable as a single package.    function is made available to your XUL file with the line:</p>
<P>Only when you have packaged your work will your files have access to Mozilla files, such as CSS and scripts, be accessible from the special <I>chrome://</I> type URLs, be able to accept new themes, and be able  <!--INDEX packages:CSS and;packages:scripts and;packages:themes and;packages:XPCOM objects and -->  <!--INDEX stylesheets:packages and;scripts:packages and;themes:packages and;XPCOM:methods:JavaScript implementation --> to get to the XPCOM objects in which much of the application for Mozilla is defined.<pre>
<P>Tools are available that help set up the files that form the basis of a new package. <A HREF="appb.html#78077">Appendix B</A> provides &lt;script type="application/x-javascript"
information about XULKit, which is a collection of scripts that automates part of the package creation process. It is recommended that you try to set up your own package by hand first to understand how packages are put together before using the XULKit scripts.src="chrome://global/content/dialogOverlay.js" /&gt;
<H3><A NAME="77066"></A> Architecture of a Chrome Package</H3></pre>
<P>The architecture of the  <!--INDEX packages:architecture -->  <!--INDEX chrome:packages (see packages) --> Mozilla XPFE is component- or layer-based. One of the primary aims of the design was the separation of each different component of an application, namely content, functionality, and layout. This design results in greater modularization, making it easy to create and change a UI-to change skins for your application, for example, update the language in which the user interface is presented, or bring in new script elements.    <p>All functions in <i>dialogOverlay.js</i> are imported into
<P>When a package is modularized like it can be in Mozilla, design determinations can be left to the designer, language in the user interface can be left to writers, and the application framework itself can be handled by software developers (though the programmer handles all of these in many small- to medium-sized projects). The next several sections provide more detail about each component and its content and file types. The way basic packages fit components together can be the basis for your own application development.    the scope of the XUL file and can be called directly, as
<P>A package is a group of directories and related files that make up a Mozilla application. A small, typical package may include a single XUL file, a script file (currently JavaScript, with implementations for Perl, Python, Ruby, and other languages being developed), and a CSS file. However, a single package might include dozens of these files, and may also include XBL files, Image File Types (PNG, JPG, GIF), DTD, HTML, and RDF files. Each has an important role to play in the application.    <tt>CenterWindowOnScreen( )</tt> is in the <tt>onload</tt>
<H3><A NAME="77067"></A> Package Components</H3>    event handler for the XUL window. Note that the functions
<P>As you will discover, each  <!--INDEX packages:components --> component in a package is independent. It is possible for your application to exist with just one or two of these components. Yet they all tie together when necessary to create a full featured application, and they are all at your disposal to take advantage of.    contained in an imported JavaScript file are not broadcast in
<H4><A NAME="77068"></A> Chrome content</H4>    any particular way (though you can see them if you use the
<P>The content is  <!--INDEX packages:chrome content;chrome:package content;XUL data, packages;XBL data, packages;packages:XUL data;packages:XBL     JavaScript Debugger). You may need to look around in the source
data --> the XUL and XBL data, contained in one or more files. This content is pulled in at runtime from files, overlays, and bindings, for display in the window system. The cross-platform implementation ensures consistency in the native system, and fits into the "write once, run anywhere" model. The XUL defines a single set of UI elements for all platforms. The XUL parser is much less tolerant than many HTML parsers; in fact, it's completely intolerant. However, it needs to be because every element in XUL impacts others and affects the layout of the UI-especially in the context of the Box Model, which <A HREF="ch03.html#77084">Chapter 3</A> describes in detail.    code or see how other applications import files to find the
<P>The widget set consists of simple widgets that display by drawing themselves absolutely in their allotted space, and of more complex widgets that act as containers, draw on top of others, or  <!--INDEX packages:widget set;widgets:packages --> accept input. A <TT>&lt;label&gt;</TT> widget is an example of the former, while <TT>&lt;stack&gt;</TT> is of the latter, more complex group. If the parser does not find an element in the content files, it fails to load and returns an error. Errors vary by type. An XML syntax error, for example, displays in the window in place of the expected content. It gives you the file the error originated in, along with the line number and column number.    functions you need, but the routines you want to use in your
<P>Built as a complementary  <!--INDEX XBL (eXtensible Binding Language):widget creation --> description language to XUL, XBL allows you to create your own widgets or add new behavior to existing XUL widgets. You may attach scripting and create (anonymous) content in a single binding or in many. With a little imagination, you can extend the content available to you infinitely by adding your own styling and behavior with XBL.    application code are probably already available in Mozilla.<a
<H4><A NAME="77069"></A> Chrome appearance</H4>    name="b260"></a><a href="#260">[*]</a></p>
<P>Loading up a XUL file with  <!--INDEX chrome:appearance, packages;packages:chrome content:appearance --> no styles attached  <!--INDEX styles:packages;packages:styles --> to the XUL elements will render the UI as a plain, disproportioned group of widgets. While plain text on a web page can be effective for simply relaying information, the situation is not analogous in user interfaces.    <h2><a name="77064"></a> Displaying XUL Files as Chrome</h2>
<P>Mozilla user interfaces without style are not very usable. Even to achieve the traditional plain gray interface that so many applications use, you must use CSS to style the Mozilla front end, and subtle effects, such as color grades or 3D button effects, often make even the most basic interface look and work better.    <p><a href="#77004">Figure 2-2</a> shows the XUL file 
<P>Themes and the ability to customize  <!--INDEX themes:packages;packages:themes and --> the look of an application are becoming more prominent. Mozilla developers realized this prominence during the design phase of Mozilla, and it's reflected in the architecture: the appearance of the interface is almost entirely separate from the structural representation in the content.    <!--INDEX XUL files:displaying as chrome;chrome:XUL files, displaying -->
<H4><A NAME="77070"></A> Chrome behavior</H4>    in <a href="#77022">Example 2-4</a> loaded into the browser's
<P>Mozilla currently supports  <!--INDEX chrome:package content:behavior;packages:chrome content:behavior --> only JavaScript  <!--INDEX JavaScript:UI and --> as the bridge between the UI and the application code. JavaScript is the glue that binds the UI and the back end functionality, which is almost entirely written in C++.    main content area. The example features a <tt>label</tt> widget
<P>Much of the infrastructure is in place for  <!--INDEX Python;Perl --> the support of other programming languages, however, and Python and Perl are currently being proposed as the next languages to fit into the framework. Currently, you will see JavaScript associated with XUL content via the following declaration:    and an <tt>image</tt>, both situated within a <tt>vbox</tt>
<PRE>&lt;script type="application/x-javascript" src="xfly.js" /&gt;</PRE>    that lays them out properly in the available space. These
<P><TT>type</TT> replaces the now deprecated <TT>language</TT> attribute and expects a MIME type for its value. As Mozilla matures and support for other languages arrives, this value may become interchangeable-which fits in with the philosophy, common in open source projects, of there being More Than One Way To Do It. Note that the behavior component of a Mozilla application usually sits in the <I>content</I> subdirectory of a package, as described later in the section <A HREF="#77072">"Directory Structure</A>."    widgets make up the chrome of your application, the Mozilla
<H4><A NAME="77071"></A> Chrome locale</H4>    user interface that can refer to itself and its resources with
<P>Localization is  <!--INDEX packages:chrome content:locale;chrome:package content:locale --> the modification of software to meet the language of a location and the adaptation of resources, such as user interface and documentation, for that region. Widgets such as menu items, buttons, window titlebars, and alert dialogs commonly need to be localized. Beyond these widgets, there can be other localizable content in an application, from HTML pages to install packages.    the special <i>chrome://</i> URL.</p>
<P>The formats used by Mozilla are:    <p>This example is starting to show off some of the nice
<UL><P><LI>DTD (<I>.dtd</I>) files, which contain entities that host the strings to be included in your XUL content.<P>    features of XPFE programming, but it still isn't an application
<P><LI>Property files (<I>.properties</I>), which contain string bundles that are accessed by dynamic content in JavaScript and C++ files or, theoretically, any language.<P>    yet. Among other things, you probably don't want your code to
<P><LI>HTML files for certain pages installed with the application-e.g., About Mozilla.<P>    live inside the browser window forever. As it grows, you may
<P><LI>RDF files.<P></UL>    also want to divide it into sensible parts-a XUL file, a
<H3><A NAME="77072"></A> Directory Structure</H3>    separate stylesheet, and a script file, for example. The rest
<P>Files can be organized  <!--INDEX directories --> in many different ways. If your application is small-say a single window with a simple structure that needs to be available only in one language-then having all your files in one directory may be easier. As the size of an application goes over a certain threshold, however, logically grouping your files into subdirectories is a good practice to make the files more accessible.    of this chapter explains how to organize and package the code
<P>Most applications use a directory structure that mirrors the package component descriptions described earlier: XUL and JavaScript  <!--INDEX directories:content;content directory --> in a <I>content</I> subdirectory, CSS and images in a <I>skin</I> subdirectory,  <!--INDEX skin directory;directories:skin --> and DTDs and other resources for localizing the interface in a <I>locale</I> subdirectory. <A HREF="#77008">Figure 2-4</A>  <!--INDEX locale directory;directories:locale --> shows this common grouping.    in <a href="#77022">Example 2-4</a> and launch it as a
<P><CENTER><IMG SRC="foo.gif"></CENTER>    standalone window by using the <tt>-chrome</tt> option when
<P><I>Figure 2-4: <A NAME="77008"></A></I>    launching Mozilla.</p>
<I>A sample package layout in the directory system</I>    <p>Launching a XUL file by using the chrome switch requires
    that you register your application in the chrome registry so
<P>These three different directories usually contain the following type of files:    that Mozilla sees and recognizes it. The <a href=
<DL><DT>content    "#77079">"Registering a Package</a>" section later in this
<DD>The <I>content</I> directory is  <!--INDEX XUL files:content directory;content directory:XUL files --> the home for the XUL files that contain the widgets to be drawn for you application. It is  <!--INDEX JavaScript:files, content directory --> common practice to also place files related to behavior, namely JavaScript files, in this directory.<P>    chapter provides more information about the chrome environment
<DT>locale    and how to register this sample application.</p>
<DD>This directory contains  <!--INDEX locale directory;directories:locale --> the files  <!--INDEX DTD:locale directory --> that contain localized strings for your package. Most files are DTD files that contain the entities referenced in XUL files. There is a subdirectory for each language, and the naming convention is <I>code-region</I>, such as <TT>en-US</TT>.<P>    <p>Although this example hasn't been registered yet, we want to
<DT>skin    give you a preview of what it will look like when launched in a
<DD>The term "skin" is an  <!--INDEX skin directory;directories:skin --> internal name  <!--INDEX stylesheets:skin directory --> for a theme. The <I>skin</I> directory contains all CSS files and images that contribute to the appearance of the windows. This is a good place to put the application images-in their own subdirectory.<P></DL>    standalone window so you can compare it with how the same XUL
<H4><A NAME="77073"></A> The xFly application directory structure</H4>    file looks when loaded into the browser window. When you do
<P>The structure of the directories in which  <!--INDEX xFly package:directories --> an application is defined (whether those directories are in the filesystem or subdirectories in an archive such as a JAR file) is an important part of that application's design and relationship to Mozilla. Use the following steps to make your xFly package self-contained, registerable, and adaptable.    launch the example by using the <tt>-chrome</tt> option (as
<UL><P><LI>On your computer, go to the directory where you have installed Mozilla and create a new directory underneath the <I>chrome</I> directory called "<I>xfly</I>."<P></UL>    described later in this chapter in the section <a href=
<OL><P>All Mozilla applications live in the <I>chrome</I> directory.<P></OL>    "#77080">"Launching the Application</a>"), you will see the
<UL><P><LI>Under that directory, create the three new directories, <I>content</I>, <I>locale</I>, and <I>skin</I>, as shown in <A HREF="#77010">Figure 2-5</A>.<P></UL>    window displayed in <a href="#77006">Figure 2-3</a>.</p>
<P><CENTER><IMG SRC="foo.gif"></CENTER>    <div class="c7">
<P><I>Figure 2-5: <A NAME="77010"></A></I>      <img src="foo.gif">
<I>xFly package directory structure</I>    </div>
    <p><i>Figure 2-3: <a name="77006"></a></i> <i>The second Hello
<H3><A NAME="77074"></A> Package Manifests</H3>    xFly example launched in its own window</i></p>
<P>Now that you have created the  <!--INDEX packages:manifests;manifests:packages --> directories for your package, you must tell Mozilla about them. All Mozilla packages must include manifests that describe their contents and make it possible to register them with Mozilla. A manifest is an RDF file (or series of RDF files) that sits within the package and interacts with Mozilla's <I>chrome</I> directory. RDF files are XML files that describe data in a machine-readable form.    <p>Using the <tt>-chrome</tt> option tells Mozilla to display
<P>Each xFly package subdirectory needs its own manifest file. Mozilla uses these files (in each case, called <I>contents.rdf</I>) when registering the application. These files are listed in Examples <A HREF="#77024">2-5</A>, <A HREF="#77026">2-6</A>, and <A HREF="#77028">2-7</A>. Create these files in your xFly <I>content</I>, <I>skin</I>, and <I>locale</I> subdirectories, respectively.    the specified file (in this case, the code from <a href=
    "#77022">Example 2-4</a>) as a standalone application rather
<P><I>Example 2-5: <A NAME="77024"></A></I>    than as content within a browser window. The file itself is the
<I>chrome/xfly/content/contents.rdf file</I>    same regardless of how it is loaded, but the results differ
<PRE> &lt;?xml version="1.0"?&gt;    depending on what you tell Mozilla to do with the file.</p>
 &lt;RDF:RDF xmlns:RDF="<A HREF="http://www.w3.org/1999/02/22-rdf-syntax-ns">http://www.w3.org/1999/02/22-rdf-syntax-ns</A>#"    <p>Displaying a XUL file in its own chrome window makes it more
          xmlns:chrome="<A HREF="http://www.mozilla.org/rdf/chrome">http://www.mozilla.org/rdf/chrome</A>#"&gt;    independent and breaks the link to the browser content area
     that is present when you use the File &gt; Open File... method.
     Launching standalone windows, accompanied by the JavaScript
     <tt>window.openDialog</tt> function explained later in this
     chapter, opens up much more flexible window display options for
     your application.</p>
     <h2><a name="77065"></a> Creating a Package</h2>
     <p>The previous two main sections 
     <!--INDEX chrome:package content;packages:chrome and -->
     introduced the concept of chrome and the prospect of creating
     standalone application windows. The next step is to make the
     example into an actual package-a modularized collection of
     files that can be installed in Mozilla as a new
     application.</p>
     <p>In the earlier section <a href="#77060">"Making Mozilla Work
     for You</a>," you added features and complexity to your XUL
     file. In this section, you pull those features into separate
     files-a CSS file, JS file, and a DTD file-register these files
     together, and make them installable as a single package.</p>
     <p>Only when you have packaged your work will your files have
     access to Mozilla files, such as CSS and scripts, be accessible
     from the special <i>chrome://</i> type URLs, be able to accept
     new themes, and be able 
     <!--INDEX packages:CSS and;packages:scripts and;packages:themes and;packages:XPCOM objects and -->
     <!--INDEX stylesheets:packages and;scripts:packages and;themes:packages and;XPCOM:methods:JavaScript implementation -->
     to get to the XPCOM objects in which much of the application
     for Mozilla is defined.</p>
     <p>Tools are available that help set up the files that form the
     basis of a new package. <a href="appb.html#78077">Appendix
     B</a> provides information about XULKit, which is a collection
     of scripts that automates part of the package creation process.
     It is recommended that you try to set up your own package by
     hand first to understand how packages are put together before
     using the XULKit scripts.</p>
     <h3><a name="77066"></a> Architecture of a Chrome Package</h3>
     <p>The architecture of the <!--INDEX packages:architecture --> 
     <!--INDEX chrome:packages (see packages) --> Mozilla XPFE is
     component- or layer-based. One of the primary aims of the
     design was the separation of each different component of an
     application, namely content, functionality, and layout. This
     design results in greater modularization, making it easy to
     create and change a UI-to change skins for your application,
     for example, update the language in which the user interface is
     presented, or bring in new script elements.</p>
     <p>When a package is modularized like it can be in Mozilla,
     design determinations can be left to the designer, language in
     the user interface can be left to writers, and the application
     framework itself can be handled by software developers (though
     the programmer handles all of these in many small- to
     medium-sized projects). The next several sections provide more
     detail about each component and its content and file types. The
     way basic packages fit components together can be the basis for
     your own application development.</p>
     <p>A package is a group of directories and related files that
     make up a Mozilla application. A small, typical package may
     include a single XUL file, a script file (currently JavaScript,
     with implementations for Perl, Python, Ruby, and other
     languages being developed), and a CSS file. However, a single
     package might include dozens of these files, and may also
     include XBL files, Image File Types (PNG, JPG, GIF), DTD, HTML,
     and RDF files. Each has an important role to play in the
     application.</p>
     <h3><a name="77067"></a> Package Components</h3>
     <p>As you will discover, each <!--INDEX packages:components -->
     component in a package is independent. It is possible for your
     application to exist with just one or two of these components.
     Yet they all tie together when necessary to create a full
     featured application, and they are all at your disposal to take
     advantage of.</p>
     <h4><a name="77068"></a> Chrome content</h4>
     <p>The content is 
     <!--INDEX packages:chrome content;chrome:package content;XUL data, packages;XBL data, packages;packages:XUL data;packages:XBL 
     data --> the XUL and XBL data, contained in one or more files.
     This content is pulled in at runtime from files, overlays, and
     bindings, for display in the window system. The cross-platform
     implementation ensures consistency in the native system, and
     fits into the "write once, run anywhere" model. The XUL defines
     a single set of UI elements for all platforms. The XUL parser
     is much less tolerant than many HTML parsers; in fact, it's
     completely intolerant. However, it needs to be because every
     element in XUL impacts others and affects the layout of the
     UI-especially in the context of the Box Model, which <a href=
     "ch03.html#77084">Chapter 3</a> describes in detail.</p>
     <p>The widget set consists of simple widgets that display by
     drawing themselves absolutely in their allotted space, and of
     more complex widgets that act as containers, draw on top of
     others, or <!--INDEX packages:widget set;widgets:packages -->
     accept input. A <tt>&lt;label&gt;</tt> widget is an example of
     the former, while <tt>&lt;stack&gt;</tt> is of the latter, more
     complex group. If the parser does not find an element in the
     content files, it fails to load and returns an error. Errors
     vary by type. An XML syntax error, for example, displays in the
     window in place of the expected content. It gives you the file
     the error originated in, along with the line number and column
     number.</p>
     <p>Built as a complementary 
     <!--INDEX XBL (eXtensible Binding Language):widget creation -->
     description language to XUL, XBL allows you to create your own
     widgets or add new behavior to existing XUL widgets. You may
     attach scripting and create (anonymous) content in a single
     binding or in many. With a little imagination, you can extend
     the content available to you infinitely by adding your own
     styling and behavior with XBL.</p>
     <h4><a name="77069"></a> Chrome appearance</h4>
     <p>Loading up a XUL file with 
     <!--INDEX chrome:appearance, packages;packages:chrome content:appearance -->
     no styles attached 
     <!--INDEX styles:packages;packages:styles --> to the XUL
     elements will render the UI as a plain, disproportioned group
     of widgets. While plain text on a web page can be effective for
     simply relaying information, the situation is not analogous in
     user interfaces.</p>
     <p>Mozilla user interfaces without style are not very usable.
     Even to achieve the traditional plain gray interface that so
     many applications use, you must use CSS to style the Mozilla
     front end, and subtle effects, such as color grades or 3D
     button effects, often make even the most basic interface look
     and work better.</p>
     <p>Themes and the ability to customize 
     <!--INDEX themes:packages;packages:themes and --> the look of
     an application are becoming more prominent. Mozilla developers
     realized this prominence during the design phase of Mozilla,
     and it's reflected in the architecture: the appearance of the
     interface is almost entirely separate from the structural
     representation in the content.</p>
     <h4><a name="77070"></a> Chrome behavior</h4>
     <p>Mozilla currently supports 
     <!--INDEX chrome:package content:behavior;packages:chrome content:behavior -->
     only JavaScript <!--INDEX JavaScript:UI and --> as the bridge
     between the UI and the application code. JavaScript is the glue
     that binds the UI and the back end functionality, which is
     almost entirely written in C++.</p>
     <p>Much of the infrastructure is in place for 
     <!--INDEX Python;Perl --> the support of other programming
     languages, however, and Python and Perl are currently being
     proposed as the next languages to fit into the framework.
     Currently, you will see JavaScript associated with XUL content
     via the following declaration:</p>
 <pre>
 &lt;script type="application/x-javascript" src="xfly.js" /&gt;
 </pre>
     <p><tt>type</tt> replaces the now deprecated <tt>language</tt>
     attribute and expects a MIME type for its value. As Mozilla
     matures and support for other languages arrives, this value may
     become interchangeable-which fits in with the philosophy,
     common in open source projects, of there being More Than One
     Way To Do It. Note that the behavior component of a Mozilla
     application usually sits in the <i>content</i> subdirectory of
     a package, as described later in the section <a href=
     "#77072">"Directory Structure</a>."</p>
     <h4><a name="77071"></a> Chrome locale</h4>
     <p>Localization is 
     <!--INDEX packages:chrome content:locale;chrome:package content:locale -->
     the modification of software to meet the language of a location
     and the adaptation of resources, such as user interface and
     documentation, for that region. Widgets such as menu items,
     buttons, window titlebars, and alert dialogs commonly need to
     be localized. Beyond these widgets, there can be other
     localizable content in an application, from HTML pages to
     install packages.</p>
     <p>The formats used by Mozilla are:</p>
     <ul>
       <li>DTD (<i>.dtd</i>) files, which contain entities that host
       the strings to be included in your XUL content.</li>
       <li>Property files (<i>.properties</i>), which contain string
       bundles that are accessed by dynamic content in JavaScript
       and C++ files or, theoretically, any language.</li>
       <li>HTML files for certain pages installed with the
       application-e.g., About Mozilla.</li>
       <li>RDF files.</li>
     </ul>
     <h3><a name="77072"></a> Directory Structure</h3>
     <p>Files can be organized <!--INDEX directories --> in many
     different ways. If your application is small-say a single
     window with a simple structure that needs to be available only
     in one language-then having all your files in one directory may
     be easier. As the size of an application goes over a certain
     threshold, however, logically grouping your files into
     subdirectories is a good practice to make the files more
     accessible.</p>
     <p>Most applications use a directory structure that mirrors the
     package component descriptions described earlier: XUL and
     JavaScript <!--INDEX directories:content;content directory -->
     in a <i>content</i> subdirectory, CSS and images in a
     <i>skin</i> subdirectory, 
     <!--INDEX skin directory;directories:skin --> and DTDs and
     other resources for localizing the interface in a <i>locale</i>
     subdirectory. <a href="#77008">Figure 2-4</a> 
     <!--INDEX locale directory;directories:locale --> shows this
     common grouping.</p>
     <div class="c7">
       <img src="foo.gif">
     </div>
     <p><i>Figure 2-4: <a name="77008"></a></i> <i>A sample package
     layout in the directory system</i></p>
     <p>These three different directories usually contain the
     following type of files:</p>
     <dl>
       <dt>content</dt>
       <dd>The <i>content</i> directory is 
       <!--INDEX XUL files:content directory;content directory:XUL files -->
       the home for the XUL files that contain the widgets to be
       drawn for you application. It is 
       <!--INDEX JavaScript:files, content directory --> common
       practice to also place files related to behavior, namely
       JavaScript files, in this directory.</dd>
       <dt>locale</dt>
       <dd>This directory contains 
       <!--INDEX locale directory;directories:locale --> the files 
       <!--INDEX DTD:locale directory --> that contain localized
       strings for your package. Most files are DTD files that
       contain the entities referenced in XUL files. There is a
       subdirectory for each language, and the naming convention is
       <i>code-region</i>, such as <tt>en-US</tt>.</dd>
       <dt>skin</dt>
       <dd>The term "skin" is an 
       <!--INDEX skin directory;directories:skin --> internal name 
       <!--INDEX stylesheets:skin directory --> for a theme. The
       <i>skin</i> directory contains all CSS files and images that
       contribute to the appearance of the windows. This is a good
       place to put the application images-in their own
       subdirectory.</dd>
     </dl>
     <h4><a name="77073"></a> The xFly application directory
     structure</h4>
     <p>The structure of the directories in which 
     <!--INDEX xFly package:directories --> an application is
     defined (whether those directories are in the filesystem or
     subdirectories in an archive such as a JAR file) is an
     important part of that application's design and relationship to
     Mozilla. Use the following steps to make your xFly package
     self-contained, registerable, and adaptable.</p>
     <ul>
       <li>On your computer, go to the directory where you have
       installed Mozilla and create a new directory underneath the
       <i>chrome</i> directory called "<i>xfly</i>."</li>
     </ul>
     <div class="c9">
       <p>All Mozilla applications live in the <i>chrome</i>
       directory.</p>
     </div>
     <ul>
       <li>Under that directory, create the three new directories,
       <i>content</i>, <i>locale</i>, and <i>skin</i>, as shown in
       <a href="#77010">Figure 2-5</a>.</li>
     </ul>
     <div class="c7">
       <img src="foo.gif">
     </div>
     <p><i>Figure 2-5: <a name="77010"></a></i> <i>xFly package
     directory structure</i></p>
     <h3><a name="77074"></a> Package Manifests</h3>
     <p>Now that you have created the 
     <!--INDEX packages:manifests;manifests:packages --> directories
     for your package, you must tell Mozilla about them. All Mozilla
     packages must include manifests that describe their contents
     and make it possible to register them with Mozilla. A manifest
     is an RDF file (or series of RDF files) that sits within the
     package and interacts with Mozilla's <i>chrome</i> directory.
     RDF files are XML files that describe data in a
     machine-readable form.</p>
     <p>Each xFly package subdirectory needs its own manifest file.
     Mozilla uses these files (in each case, called
     <i>contents.rdf</i>) when registering the application. These
     files are listed in Examples <a href="#77024">2-5</a>, <a href=
     "#77026">2-6</a>, and <a href="#77028">2-7</a>. Create these
     files in your xFly <i>content</i>, <i>skin</i>, and
     <i>locale</i> subdirectories, respectively.</p>
     <p><i>Example 2-5: <a name="77024"></a></i>
     <i>chrome/xfly/content/contents.rdf file</i></p>
 <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;RDF:RDF xmlns:RDF="<a href=
 "http://www.w3.org/1999/02/22-rdf-syntax-ns">http://www.w3.org/1999/02/22-rdf-syntax-ns</a>#"
           xmlns:chrome="<a href=
 "http://www.mozilla.org/rdf/chrome">http://www.mozilla.org/rdf/chrome</a>#"&gt;
    &lt;!-- list all the packages being supplied --&gt;     &lt;!-- list all the packages being supplied --&gt;
    &lt;RDF:Seq about="urn:mozilla:package:root"&gt;     &lt;RDF:Seq about="urn:mozilla:package:root"&gt;
      &lt;RDF:li resource="urn:mozilla:package:xfly"/&gt;       &lt;RDF:li resource="urn:mozilla:package:xfly"/&gt;
Line 332  data --> the XUL and XBL data, contained Line 1148  data --> the XUL and XBL data, contained
          chrome:author="xfly.mozdev.org"           chrome:author="xfly.mozdev.org"
          chrome:name="xfly"&gt;           chrome:name="xfly"&gt;
    &lt;/RDF:Description&gt;     &lt;/RDF:Description&gt;
 &lt;/RDF:RDF&gt;</PRE> &lt;/RDF:RDF&gt;
</pre>
<P>In the content manifest in <A HREF="#77024">Example 2-5</A>, note the <TT>chrome:name</TT>, <TT>chrome:author</TT>, and the other metadata that the manifest provides to Mozilla. This information can be used by others to identify what your application is and who wrote it. For example, the name, author, and short description information for each browser theme you have installed is viewable by going to Preferences and selecting Appearance  &gt;  Themes.    <p>In the content manifest in <a href="#77024">Example 2-5</a>,
<P>In <A HREF="#77026">Example 2-6</A>, which describes  <!--INDEX skins:xFly application;xFly:skins --> the skin for xFly only, note that new skin resources for the Classic theme are all that is supplied, as indicated in the <TT>RDF:Seq</TT>, which lists only <TT>classic</TT> as affected by this new package.    note the <tt>chrome:name</tt>, <tt>chrome:author</tt>, and the
    other metadata that the manifest provides to Mozilla. This
<P><I>Example 2-6: <A NAME="77026"></A></I>    information can be used by others to identify what your
<I>chrome/xfly/skin/contents.rdf file</I>    application is and who wrote it. For example, the name, author,
<PRE> &lt;?xml version="1.0"?&gt;    and short description information for each browser theme you
 &lt;RDF:RDF xmlns:RDF="<A HREF="http://www.w3.org/1999/02/22-rdf-syntax-ns">http://www.w3.org/1999/02/22-rdf-syntax-ns</A>#"    have installed is viewable by going to Preferences and
          xmlns:chrome="<A HREF="http://www.mozilla.org/rdf/chrome">http://www.mozilla.org/rdf/chrome</A>#"&gt;    selecting Appearance &gt; Themes.</p>
     <p>In <a href="#77026">Example 2-6</a>, which describes 
     <!--INDEX skins:xFly application;xFly:skins --> the skin for
     xFly only, note that new skin resources for the Classic theme
     are all that is supplied, as indicated in the <tt>RDF:Seq</tt>,
     which lists only <tt>classic</tt> as affected by this new
     package.</p>
     <p><i>Example 2-6: <a name="77026"></a></i>
     <i>chrome/xfly/skin/contents.rdf file</i></p>
 <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;RDF:RDF xmlns:RDF="<a href=
 "http://www.w3.org/1999/02/22-rdf-syntax-ns">http://www.w3.org/1999/02/22-rdf-syntax-ns</a>#"
           xmlns:chrome="<a href=
 "http://www.mozilla.org/rdf/chrome">http://www.mozilla.org/rdf/chrome</a>#"&gt;
    &lt;RDF:Seq about="urn:mozilla:skin:root"&gt;     &lt;RDF:Seq about="urn:mozilla:skin:root"&gt;
      &lt;RDF:li resource="urn:mozilla:skin:classic/1.0" /&gt;       &lt;RDF:li resource="urn:mozilla:skin:classic/1.0" /&gt;
    &lt;/RDF:Seq&gt;     &lt;/RDF:Seq&gt;
Line 352  data --> the XUL and XBL data, contained Line 1182  data --> the XUL and XBL data, contained
        &lt;/RDF:Seq&gt;         &lt;/RDF:Seq&gt;
      &lt;/chrome:packages&gt;       &lt;/chrome:packages&gt;
    &lt;/RDF:Description&gt;     &lt;/RDF:Description&gt;
 &lt;/RDF:RDF&gt;</PRE> &lt;/RDF:RDF&gt;
</pre>
<P>In <A HREF="#77028">Example 2-7</A>, which shows the third kind of manifest, for new locale information, the English language pack (<TT>en-US</TT>) is augmented with the localizable resources in the xFly package named there. The <TT>RDF:Seq</TT> structure  <!--INDEX RDF\:Seq structure, manifests --> in a manifest states, "to the package listed here (i.e., the <TT>en-US</TT> language pack), add the following."    <p>In <a href="#77028">Example 2-7</a>, which shows the third
    kind of manifest, for new locale information, the English
<P><I>Example 2-7: <A NAME="77028"></A></I>    language pack (<tt>en-US</tt>) is augmented with the
<I>chrome/xfly/locale/contents.rdf file</I>    localizable resources in the xFly package named there. The
<PRE> &lt;?xml version="1.0"?&gt;    <tt>RDF:Seq</tt> structure 
 &lt;RDF:RDF xmlns:RDF="<A HREF="http://www.w3.org/1999/02/22-rdf-syntax-ns">http://www.w3.org/1999/02/22-rdf-syntax-ns</A>#"    <!--INDEX RDF\:Seq structure, manifests --> in a manifest
          xmlns:chrome="<A HREF="http://www.mozilla.org/rdf/chrome">http://www.mozilla.org/rdf/chrome</A>#"&gt;    states, "to the package listed here (i.e., the <tt>en-US</tt>
     language pack), add the following."</p>
     <p><i>Example 2-7: <a name="77028"></a></i>
     <i>chrome/xfly/locale/contents.rdf file</i></p>
 <pre>
  &lt;?xml version="1.0"?&gt;
  &lt;RDF:RDF xmlns:RDF="<a href=
 "http://www.w3.org/1999/02/22-rdf-syntax-ns">http://www.w3.org/1999/02/22-rdf-syntax-ns</a>#"
           xmlns:chrome="<a href=
 "http://www.mozilla.org/rdf/chrome">http://www.mozilla.org/rdf/chrome</a>#"&gt;
    &lt;RDF:Seq about="urn:mozilla:locale:root"&gt;     &lt;RDF:Seq about="urn:mozilla:locale:root"&gt;
      &lt;RDF:li resource="urn:mozilla:locale:en-US"/&gt;       &lt;RDF:li resource="urn:mozilla:locale:en-US"/&gt;
    &lt;/RDF:Seq&gt;     &lt;/RDF:Seq&gt;
    &lt;!-- locale information --&gt;     &lt;!-- locale information --&gt;
   </TD>&lt;RDF:Description about="urn:mozilla:locale:en-US"   &lt;/td&gt;&lt;RDF:Description about="urn:mozilla:locale:en-US"
          chrome:displayName="English(US)"           chrome:displayName="English(US)"
          chrome:author="xfly.mozdev.org"           chrome:author="xfly.mozdev.org"
          chrome:name="en-US"           chrome:name="en-US"
         chrome:previewURL="<A HREF="http://www.mozilla.org/locales/en-US.gif">http://www.mozilla.org/locales/en-US.gif</A>"&gt;         chrome:previewURL="<a href=
 "http://www.mozilla.org/locales/en-US.gif">http://www.mozilla.org/locales/en-US.gif</a>"&gt;
      &lt;chrome:packages&gt;       &lt;chrome:packages&gt;
        &lt;RDF:Seq about="urn:mozilla:locale:en-US:packages"&gt;         &lt;RDF:Seq about="urn:mozilla:locale:en-US:packages"&gt;
         </TD>&lt;RDF:li resource="urn:mozilla:locale:en-US:xfly"/&gt;         &lt;/td&gt;&lt;RDF:li resource="urn:mozilla:locale:en-US:xfly"/&gt;
        &lt;/RDF:Seq&gt;         &lt;/RDF:Seq&gt;
      &lt;/chrome:packages&gt;       &lt;/chrome:packages&gt;
    &lt;/RDF:Description&gt;     &lt;/RDF:Description&gt;
 &lt;/RDF:RDF&gt;</PRE> &lt;/RDF:RDF&gt;
</pre>
<P>Manifests are detailed in <A HREF="ch06.html#15291">Chapter 6</A>. For now, it's enough to see that each manifest describes the subdirectory in     <p>Manifests are detailed in <a href="ch06.html#15291">Chapter
which it is located, and that the contents of those subdirectories make up the package collectively.    6</a>. For now, it's enough to see that each manifest describes
<P>The content describes the content of the xFly package, the XUL, and the JavaScript. The skin describes the theme of xFly, or the CSS and images used to lay out the XUL. The third part describes the locale, or the strings in the UI that can be localized or adapted for various languages or locales.    the subdirectory in which it is located, and that the contents
<H3><A NAME="77075"></A> Separating the Files</H3>    of those subdirectories make up the package collectively.</p>
<P>Once you have a subdirectory structure set up  <!--INDEX packages:file separation;files:separating, packages;separating files, packages --> in accordance with the package component structure of your application, you can pull the pieces of your XUL file out into their own files and modularize your application. These separate files-the basic XUL file and separate CSS, JS, and DTD files-are registered as a single package and can then be launched as a standalone application.    <p>The content describes the content of the xFly package, the
<P>Though the files contain the information you've already seen in the "Hello World" sample shown in <A HREF="#77022">Example 2-4</A>, their interaction demonstrates how packages can work together in Mozilla. Each step taken to separate the different components requires editing the base XUL file.    XUL, and the JavaScript. The skin describes the theme of xFly,
<H4><A NAME="77076"></A> The xFly CSS file</H4>    or the CSS and images used to lay out the XUL. The third part
<P>The inline style rule  <!--INDEX xfly.css file;stylesheets:xfly.css file;packages:xfly.css file --> on the label widget can go almost unadulterated into a separate text file called <I>xfly.css</I>. Save the code in <A HREF="#77030">Example 2-8</A> in the <I>chrome/xfly/skin/</I> directory.    describes the locale, or the strings in the UI that can be
    localized or adapted for various languages or locales.</p>
<P><I>Example 2-8: <A NAME="77030"></A></I>    <h3><a name="77075"></a> Separating the Files</h3>
<I>The contents of the xfly.css file</I>    <p>Once you have a subdirectory structure set up 
<PRE> #xlabel { font-weight: bold; }    <!--INDEX packages:file separation;files:separating, packages;separating files, packages -->
 window  { background-color: white; }</PRE>    in accordance with the package component structure of your
    application, you can pull the pieces of your XUL file out into
<P>Using style rules from an external file is different because you have to specify some way for the style rule to associate itself with the appropriate tags in the XUL file. CSS provides a rich collection of selectors, which bind style data to elements. In this case, where you have two separate elements that need to pick up rules, the <TT>id</TT> attribute on the XUL element is used to bind a unique element to an external style rule and the other style rule is bound by referring to the XUL element directly. <A HREF="#77030">Example 2-8</A> includes the selectors for the two elements, and <A HREF="#77032">Example 2-9</A> shows the updated XUL that uses <I>xfly.css</I>.    their own files and modularize your application. These separate
    files-the basic XUL file and separate CSS, JS, and DTD
<P><I>Example 2-9: <A NAME="77032"></A></I>    files-are registered as a single package and can then be
<I>XUL using external style data</I>    launched as a standalone application.</p>
<PRE> &lt;?xml version="1.0"?&gt;    <p>Though the files contain the information you've already seen
     in the "Hello World" sample shown in <a href="#77022">Example
     2-4</a>, their interaction demonstrates how packages can work
     together in Mozilla. Each step taken to separate the different
     components requires editing the base XUL file.</p>
     <h4><a name="77076"></a> The xFly CSS file</h4>
     <p>The inline style rule 
     <!--INDEX xfly.css file;stylesheets:xfly.css file;packages:xfly.css file -->
     on the label widget can go almost unadulterated into a separate
     text file called <i>xfly.css</i>. Save the code in <a href=
     "#77030">Example 2-8</a> in the <i>chrome/xfly/skin/</i>
     directory.</p>
     <p><i>Example 2-8: <a name="77030"></a></i> <i>The contents of
     the xfly.css file</i></p>
 <pre>
  #xlabel { font-weight: bold; }
  window  { background-color: white; }
 </pre>
     <p>Using style rules from an external file is different because
     you have to specify some way for the style rule to associate
     itself with the appropriate tags in the XUL file. CSS provides
     a rich collection of selectors, which bind style data to
     elements. In this case, where you have two separate elements
     that need to pick up rules, the <tt>id</tt> attribute on the
     XUL element is used to bind a unique element to an external
     style rule and the other style rule is bound by referring to
     the XUL element directly. <a href="#77030">Example 2-8</a>
     includes the selectors for the two elements, and <a href=
     "#77032">Example 2-9</a> shows the updated XUL that uses
     <i>xfly.css</i>.</p>
     <p><i>Example 2-9: <a name="77032"></a></i> <i>XUL using
     external style data</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;!DOCTYPE window&gt;   &lt;!DOCTYPE window&gt;
  &lt;window title="Hello xFly"   &lt;window title="Hello xFly"
   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>"
    width="300"     width="300"
    height="215"     height="215"
    onload="centerWindowOnScreen( )"&gt;     onload="centerWindowOnScreen( )"&gt;
   &lt;script type="application/x-javascript"    &lt;script type="application/x-javascript"
    src="chrome://global/content/dialogOverlay.js" /&gt;     src="chrome://global/content/dialogOverlay.js" /&gt;
  &lt;vbox align="left" id="vb"</TD>&gt;  &lt;vbox align="left" id="vb"&lt;/td&gt;&gt;
    &lt;label id="xlabel"     &lt;label id="xlabel"
        value="Hello, Welcome to the xFly" /&gt;         value="Hello, Welcome to the xFly" /&gt;
   &lt;image src="<A HREF="http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</A>" /&gt;   &lt;image src="<a href=
 "http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</a>" /&gt;
    &lt;button label="hello xFly" oncommand="alert('hello.');" /&gt;     &lt;button label="hello xFly" oncommand="alert('hello.');" /&gt;
   &lt;/vbox&gt;    &lt;/vbox&gt;
 &lt;/window&gt;</PRE> &lt;/window&gt;
</pre>
<P>Note the extra stylesheet import statement at the top and the use of the new <TT>id</TT> attribute on the label. When you register the new files in your package with Mozilla, the <I>xfly</I> directory in that stylesheet processing instruction will point into your application directory structure (at the <I>skin</I> subdirectory, and at a file named after the directory itself, <I>xfly.css</I>). The label will pick up the style information in the file that was previously defined directly in its <TT>style</TT> attribute.    <p>Note the extra stylesheet import statement at the top and
<H4><A NAME="77077"></A> The xFly script file</H4>    the use of the new <tt>id</tt> attribute on the label. When you
<P>The next step is to take  <!--INDEX xfly.js file;JavaScript:xfly.js file;packages:xfly.js file --> the scripting portion, as simple as it is, out of the XUL file and put it into an external JavaScript file. <A HREF="#77034">Example 2-10</A> shows a XUL file that gets a function for the button from an external script file, given here as <I>xfly.js</I>.    register the new files in your package with Mozilla, the
    <i>xfly</i> directory in that stylesheet processing instruction
Example 2-10<A NAME="77034"></A>    will point into your application directory structure (at the
<I>XUL using an external script</I>    <i>skin</i> subdirectory, and at a file named after the
<PRE> &lt;?xml version="1.0"?&gt;    directory itself, <i>xfly.css</i>). The label will pick up the
     style information in the file that was previously defined
     directly in its <tt>style</tt> attribute.</p>
     <h4><a name="77077"></a> The xFly script file</h4>
     <p>The next step is to take 
     <!--INDEX xfly.js file;JavaScript:xfly.js file;packages:xfly.js file -->
     the scripting portion, as simple as it is, out of the XUL file
     and put it into an external JavaScript file. <a href=
     "#77034">Example 2-10</a> shows a XUL file that gets a function
     for the button from an external script file, given here as
     <i>xfly.js</i>. Example 2-10<a name="77034"></a> <i>XUL using
     an external script</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;!DOCTYPE window&gt;   &lt;!DOCTYPE window&gt;
  &lt;window title="Hello xFly"   &lt;window title="Hello xFly"
   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>"
    width="300"     width="300"
    height="215"     height="215"
    onload="centerWindowOnScreen( )"&gt;     onload="centerWindowOnScreen( )"&gt;
  &lt;script type="application/x-javascript"   &lt;script type="application/x-javascript"
    src="chrome://global/content/dialogOverlay.js" /&gt;     src="chrome://global/content/dialogOverlay.js" /&gt;
 </TD>&lt;script type="application/x-javascript" &lt;script type="application/x-javascript"
    src="chrome://xfly/content/xfly.js" /&gt;     src="chrome://xfly/content/xfly.js" /&gt;
   &lt;vbox align="left" id="vb"&gt;    &lt;vbox align="left" id="vb"&gt;
    &lt;label id="xlabel"     &lt;label id="xlabel"
        value="Hello, Welcome to the xFly" /&gt;         value="Hello, Welcome to the xFly" /&gt;
   &lt;image src="<A HREF="http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</A>" /&gt;   &lt;image src="<a href=
 "http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</a>" /&gt;
    &lt;button label="hello xFly" oncommand="greet( );" /&gt;     &lt;button label="hello xFly" oncommand="greet( );" /&gt;
   &lt;/vbox&gt;    &lt;/vbox&gt;
 &lt;/window&gt;</PRE> &lt;/window&gt;
</pre>
<P>Note that the function <TT>greet( )</TT> is used to name the action that is performed when the button is clicked. The <TT>greet( )</TT> function is now defined in the <I>xfly.js</I> file that the XUL file picks up with the script import statement:    <p>Note that the function <tt>greet( )</tt> is used to name the
<PRE>&lt;script type="application/x-javascript"    action that is performed when the button is clicked. The
src="chrome://xfly/content/xfly.js" /&gt;</PRE>    <tt>greet( )</tt> function is now defined in the <i>xfly.js</i>
<P><A HREF="#77036">Example 2-11</A> contains all of the code needed for the <I>xfly.js</I> file.    file that the XUL file picks up with the script import
    statement:</p>
Example 2-11<A NAME="77036"></A><pre>
<I>The contents of the xfly.js file</I>&lt;script type="application/x-javascript"
<PRE> function greet( ) {src="chrome://xfly/content/xfly.js" /&gt;
 </pre>
     <p><a href="#77036">Example 2-11</a> contains all of the code
     needed for the <i>xfly.js</i> file. Example 2-11<a name=
     "77036"></a> <i>The contents of the xfly.js file</i></p>
 <pre>
  function greet( ) {
    alert("Hello World");     alert("Hello World");
 }</PRE> }
</pre>
<P>Save <I>xfly.js</I> in the <I>content</I> subdirectory of the xFly application (<I>chrome/xfly/content/</I>). The script import statement above uses the <I>chrome://</I> URL to locate scripts from directories that were registered with Mozilla.    <p>Save <i>xfly.js</i> in the <i>content</i> subdirectory of
<H4><A NAME="77078"></A> The xFly DTD</H4>    the xFly application (<i>chrome/xfly/content/</i>). The script
<P>The final step in a basic  <!--INDEX xfly.dtd file;DTD:xfly.dtd file --> application setup is to generalize parts of the interface that are written in a particular language, such as English. When you create a <I>locale</I> subdirectory for your package and place a DTD file that contains the English strings in the user interface, you can refer to and load that DTD just as you do with the CSS and script files.    import statement above uses the <i>chrome://</i> URL to locate
<P>For example, to localize the text of the label and button elements in the "hello xFly" example, you can use a special syntax to tell Mozilla to use an entity rather than a string. Because that entity is defined in <I>xfly.dtd</I> and located in the locale subdirectory, it can easily be swapped for an entity from a different language pack when the user switches languages in Mozilla.    scripts from directories that were registered with Mozilla.</p>
<P>Once again, the external file you create can be very simple. <A HREF="#77038">Example 2-12</A> contains the code needed for the <I>xfly.dtd</I> file, which you create and save in the <I>locale</I> subdirectory.    <h4><a name="77078"></a> The xFly DTD</h4>
    <p>The final step in a basic 
Example 2-12<A NAME="77038"></A>    <!--INDEX xfly.dtd file;DTD:xfly.dtd file --> application setup
<I>The contents of the xfly.dtd file</I>    is to generalize parts of the interface that are written in a
<PRE> &lt;!ENTITY label.val       "Hello, Welcome to the xFly " &gt;    particular language, such as English. When you create a
 &lt;!ENTITY btn.lbl         "hello xFly " &gt;</PRE>    <i>locale</i> subdirectory for your package and place a DTD
    file that contains the English strings in the user interface,
<P>The updated XUL file that uses this external DTD, then, appears in <A HREF="#77040">Example 2-13</A>. Once you have made the final changes in the XUL to refer to the external files you've created, save the code in <A HREF="#77040">Example 2-13</A> as <I>xfly.xul</I> in the <I>chrome/xfly/content/</I> directory.    you can refer to and load that DTD just as you do with the CSS
    and script files.</p>
Example 2-13<A NAME="77040"></A>    <p>For example, to localize the text of the label and button
<I>XUL using an external DTD file</I>    elements in the "hello xFly" example, you can use a special
<PRE> &lt;?xml version="1.0"?&gt;    syntax to tell Mozilla to use an entity rather than a string.
     Because that entity is defined in <i>xfly.dtd</i> and located
     in the locale subdirectory, it can easily be swapped for an
     entity from a different language pack when the user switches
     languages in Mozilla.</p>
     <p>Once again, the external file you create can be very simple.
     <a href="#77038">Example 2-12</a> contains the code needed for
     the <i>xfly.dtd</i> file, which you create and save in the
     <i>locale</i> subdirectory. Example 2-12<a name="77038"></a>
     <i>The contents of the xfly.dtd file</i></p>
 <pre>
  &lt;!ENTITY label.val       "Hello, Welcome to the xFly " &gt;
  &lt;!ENTITY btn.lbl         "hello xFly " &gt;
 </pre>
     <p>The updated XUL file that uses this external DTD, then,
     appears in <a href="#77040">Example 2-13</a>. Once you have
     made the final changes in the XUL to refer to the external
     files you've created, save the code in <a href="#77040">Example
     2-13</a> as <i>xfly.xul</i> in the <i>chrome/xfly/content/</i>
     directory. Example 2-13<a name="77040"></a> <i>XUL using an
     external DTD file</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;!DOCTYPE window SYSTEM "chrome://xfly/locale/xfly.dtd" &gt;   &lt;!DOCTYPE window SYSTEM "chrome://xfly/locale/xfly.dtd" &gt;
  &lt;window title="Hello xFly"   &lt;window title="Hello xFly"
   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>"
    width="300"     width="300"
    height="215"     height="215"
    onload="centerWindowOnScreen( )"&gt;     onload="centerWindowOnScreen( )"&gt;
Line 486  Example 2-13<A NAME="77040"></A> Line 1408  Example 2-13<A NAME="77040"></A>
    src="chrome://xfly/content/xfly.js" /&gt;     src="chrome://xfly/content/xfly.js" /&gt;
   &lt;vbox align="left" id="vb"&gt;    &lt;vbox align="left" id="vb"&gt;
    &lt;label id="xlabel"     &lt;label id="xlabel"
       value="&amp;label.val;"</TD> /&gt;       value="&amp;label.val;"&lt;/td&gt; /&gt;
   &lt;image src="<A HREF="http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</A>" /&gt;   &lt;image src="<a href=
   &lt;button label="&amp;btn.lbl;"</TD> oncommand="greet( );" /&gt;"http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</a>" /&gt;
    &lt;button label="&amp;btn.lbl;"&lt;/td&gt; oncommand="greet( );" /&gt;
   &lt;/vbox&gt;    &lt;/vbox&gt;
 &lt;/window&gt;</PRE> &lt;/window&gt;
</pre>
<P>Like the CSS and script file imports, the updated <TT>DOCTYPE</TT> definition at the top of the file tells Mozilla to load additional entities as part of the xFly package. Those entities-the English strings that display in the user interface-are defined so they can be localized or internationalized without affecting the application's structure.    <p>Like the CSS and script file imports, the updated
<P>All three of these imports use the <I>chrome://</I> URL to refer to resources that are internal to the xFly package. These type of URLs can also refer to resources elsewhere in Mozilla, such as image resources, strings that have already been defined in entities, and functions from scripts such as <TT>centerWindowOnScreen( )</TT>.    <tt>DOCTYPE</tt> definition at the top of the file tells
<P>When you finish setting things up in the package directories, you should have a structure that looks like the tree structure in <A HREF="#77042">Example 2-14</A>.    Mozilla to load additional entities as part of the xFly
    package. Those entities-the English strings that display in the
Example 2-14<A NAME="77042"></A>    user interface-are defined so they can be localized or
<I>Tree structure of a completed sample xFly package</I>    internationalized without affecting the application's
<PRE> chrome/    structure.</p>
     <p>All three of these imports use the <i>chrome://</i> URL to
     refer to resources that are internal to the xFly package. These
     type of URLs can also refer to resources elsewhere in Mozilla,
     such as image resources, strings that have already been defined
     in entities, and functions from scripts such as
     <tt>centerWindowOnScreen( )</tt>.</p>
     <p>When you finish setting things up in the package
     directories, you should have a structure that looks like the
     tree structure in <a href="#77042">Example 2-14</a>. Example
     2-14<a name="77042"></a> <i>Tree structure of a completed
     sample xFly package</i></p>
 <pre>
  chrome/
         xfly/          xfly/
             content/              content/
                    xfly.xul                     xfly.xul
Line 509  Example 2-14<A NAME="77042"></A> Line 1445  Example 2-14<A NAME="77042"></A>
                    contents.rdf                     contents.rdf
             skin/              skin/
                    xfly.css                     xfly.css
                   contents.rdf</PRE>                   contents.rdf
</pre>
<H3><A NAME="77079"></A> Registering a Package</H3>    <h3><a name="77079"></a> Registering a Package</h3>
<P>Registering packages in Mozilla  <!--INDEX packages:registration;registration:packages --> can be confusing at first, so don't worry about understanding everything at this point. Later chapters provide more detailed information about packaging and registration, and you can always copy the examples given here to install your own application. In general, to make your package registerable, create manifests that describe your package in terms that Mozilla can understand.    <p>Registering packages in Mozilla 
<P>Although it's customary to make registration a part of the installation process by using the XPInstall API and installation  <!--INDEX XPInstall:registration and;registration:XPInstall API --> scripts, you need a simple way to register the xFly application so you can see your work and test it as it develops. For this purpose, hacking the <I>installed-chrome.txt</I> file living  <!--INDEX installed-chrome.txt file --> in Mozilla's <I>chrome</I> directory will do.    <!--INDEX packages:registration;registration:packages --> can
<P>The <I>installed-chrome.txt</I> file is a list of packages and package parts that Mozilla should find and register on start up. When you add entries to this file, you point to your package and tell Mozilla to register that package when it starts up.    be confusing at first, so don't worry about understanding
<P>Append the entries in <A HREF="#77044">Example 2-15</A> to the bottom of the <I>installed-chrome.txt</I> file in the main chrome directory.    everything at this point. Later chapters provide more detailed
    information about packaging and registration, and you can
Example 2-15<A NAME="77044"></A>    always copy the examples given here to install your own
<I>Additions to the installed-chrome.txt file</I>    application. In general, to make your package registerable,
<PRE>content,install,url,resource:/chrome/xfly/content/    create manifests that describe your package in terms that
     Mozilla can understand.</p>
     <p>Although it's customary to make registration a part of the
     installation process by using the XPInstall API and
     installation 
     <!--INDEX XPInstall:registration and;registration:XPInstall API -->
     scripts, you need a simple way to register the xFly application
     so you can see your work and test it as it develops. For this
     purpose, hacking the <i>installed-chrome.txt</i> file living 
     <!--INDEX installed-chrome.txt file --> in Mozilla's
     <i>chrome</i> directory will do.</p>
     <p>The <i>installed-chrome.txt</i> file is a list of packages
     and package parts that Mozilla should find and register on
     start up. When you add entries to this file, you point to your
     package and tell Mozilla to register that package when it
     starts up.</p>
     <p>Append the entries in <a href="#77044">Example 2-15</a> to
     the bottom of the <i>installed-chrome.txt</i> file in the main
     chrome directory. Example 2-15<a name="77044"></a> <i>Additions
     to the installed-chrome.txt file</i></p>
 <pre>
 content,install,url,resource:/chrome/xfly/content/
 skin,install,url,resource:/chrome/xfly/skin/  skin,install,url,resource:/chrome/xfly/skin/
locale,install,url,resource:/chrome/xfly/locale/</PRE>locale,install,url,resource:/chrome/xfly/locale/
</pre>
<P>When Mozilla starts up, it looks for the package manifests, reads them, and registers the xFly package.    <p>When Mozilla starts up, it looks for the package manifests,
<P>When others install your application and use it on their machines (but do not use the hack to <I>installed-chrome.txt</I>), you can provide     reads them, and registers the xFly package.</p>
them with a JavaScript installation file that downloads and registers your package from a web page. See <A HREF="ch06.html#15291">Chapter 6</A> for more information about these installation files and the XPInstall technology they are based upon.    <p>When others install your application and use it on their
<H2><A NAME="77080"></A> Launching the Application</H2>    machines (but do not use the hack to
<P>Once your package is registered, you can use these startup options to access your package directly.<A NAME="77081"></A>    <i>installed-chrome.txt</i>), you can provide them with a
<H4><A NAME="77082"></A> Windows launch</H4>    JavaScript installation file that downloads and registers your
<P>In the Mozilla install directory, launch xFly at  <!--INDEX xFly:Windows launch;Windows:xFly launch --> the command prompt with:    package from a web page. See <a href="ch06.html#15291">Chapter
<PRE>mozilla -chrome chrome://xfly/content/</PRE>    6</a> for more information about these installation files and
<P>You can also launch xFly from a shortcut on your desktop by right-clicking on the existing Mozilla icon and selecting Properties. In the Target area of the Properties box, add the following text at the end of the line:    the XPInstall technology they are based upon.</p>
<PRE>-chrome chrome://xfly/content/</PRE>    <h2><a name="77080"></a> Launching the Application</h2>
<P><A HREF="#77012">Figure 2-6</A> shows what the new properties box should look like.    <p>Once your package is registered, you can use these startup
<P><CENTER><IMG SRC="foo.gif"></CENTER>    options to access your package directly.<a name=
<P><I>Figure 2-6: <A NAME="77012"></A></I>    "77081"></a></p>
<I>Modified shortcut properties</I>    <h4><a name="77082"></a> Windows launch</h4>
    <p>In the Mozilla install directory, launch xFly at 
<H4><A NAME="77083"></A> Unix launch</H4>    <!--INDEX xFly:Windows launch;Windows:xFly launch --> the
<P>In the Mozilla install directory, launch xFly  <!--INDEX xFly:Unix launch;Unix:xFly launch --> with:    command prompt with:</p>
<PRE>./mozilla -chrome chrome://xfly/content/</PRE><pre>
<H4><A NAME="77084"></A> Macintosh launch</H4>mozilla -chrome chrome://xfly/content/
<P>Start xFly by creating a text file on your desktop  <!--INDEX xFly:Macintosh launch;Macintosh:application launch --> with the following content:</pre>
<PRE>-chrome chrome://xfly/content/</PRE>    <p>You can also launch xFly from a shortcut on your desktop by
<P>You can either drag this text file onto your Mozilla icon to launch the application or set the text file's creator type to <TT>MOZZ</TT>. If you change the creator type, you should be able to double-click on the text file to launch Mozilla.    right-clicking on the existing Mozilla icon and selecting
<P>Once you register your application, you are free to continue developing it in the various component subdirectories and relaunching it as it progresses. You can add new XUL files in the <I>content</I> directory, for example, that are invoked from buttons using <TT>window.openDialog( )</TT> event handlers.    Properties. In the Target area of the Properties box, add the
<P>You can add new widgets to <I>xfly.xul</I>, add new styles to <I>xfly.css</I> that apply to the XUL, add new functions to <I>xfly.js</I>, or use existing functions in the Mozilla source code that you can find new ways to use in your own application.    following text at the end of the line:</p>
<P>The steps described in this chapter-creating a basic XUL file, adding features, displaying that XUL file as a standalone window, organizing the code into separate files and a package structure, and registering and launching that package-are the basic building blocks of all Mozilla applications. When you get a feel for what's going on here, you'll be able to quickly understand and use the topics described in the rest of the book.<pre>
<HR>-chrome chrome://xfly/content/
<HR><A NAME="260"></A><A HREF="#b260">[Back]</A></pre>
<A NAME="77047"></A>    <p><a href="#77012">Figure 2-6</a> shows what the new
Unfortunately, no good reference exists for the    properties box should look like.</p>
functions defined in the various scripts files you can import. The    <div class="c7">
functions and their locations within the files continue to change, so      <img src="foo.gif">
finding and using the right ones is sometimes a matter of luck,    </div>
sometimes a matter of whom you know, and often a matter of testing,    <p><i>Figure 2-6: <a name="77012"></a></i> <i>Modified shortcut
determination, and patience.    properties</i></p>
<HR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR>    <h4><a name="77083"></a> Unix launch</h4>
<!-- ?php require(NOTES); ? -->    <p>In the Mozilla install directory, launch xFly 
<?php $post_to_list=NO; $author='reviewers@mozdev.org'; $target_page='ch02'; require(NOTES); ?>    <!--INDEX xFly:Unix launch;Unix:xFly launch --> with:</p>
</BODY><pre>
</HTML>./mozilla -chrome chrome://xfly/content/
 </pre>
     <h4><a name="77084"></a> Macintosh launch</h4>
     <p>Start xFly by creating a text file on your desktop 
     <!--INDEX xFly:Macintosh launch;Macintosh:application launch -->
     with the following content:</p>
 <pre>
 -chrome chrome://xfly/content/
 </pre>
     <p>You can either drag this text file onto your Mozilla icon to
     launch the application or set the text file's creator type to
     <tt>MOZZ</tt>. If you change the creator type, you should be
     able to double-click on the text file to launch Mozilla.</p>
 
     <p>Note: If you have trouble editing and relaunching the xFly
      application, there are a couple of platform specific culprits
      to look into. On Windows, the Quick Launch feature may prevent
      you from seeing changes to your files. On Unix, file permission
      conflicts can also cause problems viewing your files. Making sure that
      Quick Launch is disabled and double checking file
      permissions may help get xFly working on your system.
 
     <p>Once you register your application, you are free to continue
     developing it in the various component subdirectories and
     relaunching it as it progresses. You can add new XUL files in
     the <i>content</i> directory, for example, that are invoked
     from buttons using <tt>window.openDialog( )</tt> event
     handlers.</p>
     <p>You can add new widgets to <i>xfly.xul</i>, add new styles
     to <i>xfly.css</i> that apply to the XUL, add new functions to
     <i>xfly.js</i>, or use existing functions in the Mozilla source
     code that you can find new ways to use in your own
     application.</p>
     <p>The steps described in this chapter-creating a basic XUL
     file, adding features, displaying that XUL file as a standalone
     window, organizing the code into separate files and a package
     structure, and registering and launching that package-are the
     basic building blocks of all Mozilla applications. When you get
     a feel for what's going on here, you'll be able to quickly
     understand and use the topics described in the rest of the
     book.</p>
     <hr>
     <hr>
     <a name="260"></a><a href="#b260">[Back]</a> <a name=
     "77047"></a> Unfortunately, no good reference exists for the
     functions defined in the various scripts files you can import.
     The functions and their locations within the files continue to
     change, so finding and using the right ones is sometimes a
     matter of luck, sometimes a matter of whom you know, and often
     a matter of testing, determination, and patience. 
     <hr>
     <br>
     <br>
     File a <a href=
     "http://mozdev.org/bugs/enter_bug.cgi?product=books">Bug</a>
     for chapter 2. <!-- ?php require(NOTES); ? -->
     <?php $post_to_list=NO; $author='reviewers@mozdev.org'; $target_page='ch02'; require(NOTES); ?>

Removed from v.1.10  
changed lines
  Added in v.1.24


FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>