Annotation of books/www/chapters/ch02.html, revision 1.21

1.15      petejc      1:     <link rel="prev" href="http://books.mozdev.org/chapters/ch01.html" />
                      2:     <link rel="next" href="http://books.mozdev.org/chapters/ch03.html" />
                      3: 
1.14      petejc      4:     <style type="text/css">
                      5:       div.c9 {margin-left: 2em}
                      6:       div.c8 {font-weight: bold; text-align: center}
                      7:       div.c7 {text-align: center}
                      8:     </style>
                      9: 
                     10:     <h2>Chapter 2</h2>
                     11:     <h1><a name="77048"></a> Getting Started</h1>
                     12:     <p>To help you start creating applications as quickly as
                     13:     possible, this chapter presents two "Hello World" examples that
                     14:     demonstrate the beginning stages of Mozilla application
                     15:     development.</p>
                     16:     <p>The first example is a simple XUL file that is loaded into
                     17:     the browser window. This example is then expanded on by adding
                     18:     additional features to the XUL file, such as imported
                     19:     stylesheets and JavaScript functions. The second "Hello World"
                     20:     example shows how to turn files like these into packages, which
                     21:     are the modular, bundled sets of files that fit together to
                     22:     make Mozilla applications or new modules for the Mozilla
                     23:     browser.</p>
                     24:     <p>These examples provide a context for discussing the
                     25:     development of Mozilla applications. The first example focuses
                     26:     on creating and editing the basic file types, and the second
                     27:     focuses on the organization and distribution of applications on
                     28:     the Mozilla platform.</p>
                     29:     <h2><a name="77049"></a> Simple XUL Example</h2>
                     30:     <p>Like all good "Hello World" applications, 
                     31:     <!--INDEX Hello World XUL example --> 
                     32:     <!--INDEX XUL (XML-based User-interface Language):Hello World example -->
                     33:     <a href="#77016">Example 2-1</a> shows one of the simplest
                     34:     possible examples of XUL. Although it is small, it demonstrates
                     35:     some important aspects of XUL programming, including the use of
                     36:     event handlers to add behavior and the use of a <tt>box</tt> to
                     37:     lay out elements properly within the window. This example also
                     38:     provides a context for discussing more general features of the
                     39:     language, such as the file format, the namespace, and some XUL
                     40:     programming conventions.</p>
                     41:     <p><i>Example 2-1: <a name="77016"></a></i> <i>Hello
                     42:     xFly</i></p>
                     43: <pre>
                     44:  &lt;?xml version="1.0"?&gt;
1.1       david      45:  &lt;!-- Sample XUL file --&gt;
1.14      petejc     46:  &lt;window xmlns="<a href=
                     47: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"&gt;
1.1       david      48:  &lt;box align="center"&gt;
                     49:    &lt;button label="hello xFly" onclick="alert('Hello World');" /&gt;
                     50:  &lt;/box&gt;
1.14      petejc     51:  &lt;/window&gt;
                     52: </pre>
                     53:     <p>Use your text editor to save the code in <a href=
                     54:     "#77016">Example 2-1</a> in a file called <i>hello.xul</i> and
                     55:     then load the file in Mozilla (you can do this by using File
                     56:     &gt; Open File from the browser window and browsing to where
                     57:     you saved the file). You should see a button in the upper-left
                     58:     corner of the browser window that brings up an alert box when
                     59:     clicked. <a href="#77002">Figure 2-1</a> shows an example of
                     60:     the alert pop-up window that appears.</p>
                     61:     <div class="c7">
                     62:       <img src="foo.gif">
                     63:     </div>
                     64:     <p><i>Figure 2-1: <a name="77002"></a></i> <i>The first Hello
                     65:     xFly example</i></p>
                     66:     <p>The next few sections describe this sample file in more
                     67:     detail. The covered topics include the file itself, the syntax
                     68:     of the markup, XUL namespaces, and the basic layout of a XUL
                     69:     file.</p>
                     70:     <blockquote>
                     71:       <hr>
                     72:       <b>The xFly Examples</b> 
                     73:       <p>The best way to understand the possible uses of the
                     74:       Mozilla framework is to look more closely at a number of
                     75:       various existing applications. This book highlights several
                     76:       Mozilla development projects, such as ChatZilla and JSLib, as
                     77:       examples of how some people have already started using
                     78:       Mozilla's XPFE technologies.</p>
                     79:       <p>Along with these applications, you'll note the use of the
                     80:       name "xFly" in many examples in this chapter and elsewhere in
                     81:       this book. The xFly examples are used throughout <a href=
                     82:       "#77048">Chapter 2</a> to <a href="ch06.html#77063">Chapter
                     83:       6</a> to show how to create and package a simple Mozilla
                     84:       application. An installable version of the complete xFly
                     85:       application can be found at <i><a href=
                     86:       "http://xfly.mozdev.org">http://xfly.mozdev.org</a></i>.</p>
                     87:       <p>This simple application is useful because it provides a
                     88:       place to start exploring the new information that you will
                     89:       learn about in this book. As you read more about XUL, CSS,
                     90:       JavaScript, and the other parts of Mozilla's development
                     91:       framework, you can create and edit the xFly files to see how
                     92:       these technologies work in practice.</p>
                     93:       <hr>
                     94:     </blockquote>
                     95:     <h2><a name="77050"></a> Basic XUL Concepts</h2>
                     96:     <p>You have already seen many of XUL's basic features at work.
                     97:     When you load the example in the previous example, the browser
                     98:     identifies it as a XUL file, parses the data, creates a new
                     99:     window and draws the button widget, and executes the function
                    100:     you've defined when the button is clicked.</p>
                    101:     <p>These activities are part of the basic and often transparent
                    102:     interaction between your application files and Mozilla.
                    103:     However, the format of your XUL files, their syntax and
                    104:     namespace, the XUL layout, and the windowing system are all
                    105:     basic to successful XUL programming.</p>
                    106:     <h3><a name="77051"></a> The XUL File Format</h3>
                    107:     <p>A XUL file is a simple text file <!--INDEX XUL files --> 
                    108:     <!--INDEX files:XUL files --> that contains proper XML syntax
                    109:     and has a <i>.xul</i> file extension. Mozilla expects to draw
                    110:     UI widgets when it encounters a file with a <i>.xul</i>
                    111:     extension or when it encounters the XUL namespace in other
                    112:     markup files that it recognizes, including HTML and XML.</p>
                    113:     <p>The MIME type registered <!--INDEX MIME type, XUL files --> 
                    114:     <!--INDEX XUL files:MIME type registered --> for XUL files is
                    115:     <i>application/vnd.mozilla.xul+xml</i>. When editing and using
                    116:     XUL files locally, you shouldn't need to worry about setting
                    117:     this on your computer; however, sometimes you may need to set
                    118:     the MIME type, such as when you host XUL files on a server. <a
                    119:     href="ch12.html#51383">Chapter 12</a> provides additional
                    120:     information about how you can set the correct file type for
                    121:     your system.</p>
                    122:     <h3><a name="77052"></a> Conventions</h3>
                    123:     <p>XUL has to follow certain 
                    124:     <!--INDEX XUL (XML-based User-interface Language):conventions -->
                    125:     <!--INDEX conventions, XUL --> conventions (as does XHTML or
                    126:     any other XML-based file) in order to be valid. Mozilla
                    127:     generates an error when it encounters an invalid XUL file.</p>
                    128:     <p>The first thing required in a XUL document is the XML
                    129:     declaration.</p>
                    130: <pre>
                    131: &lt;?xml version="1.0"?&gt;
                    132: </pre>
                    133:     <p>Any comments used to introduce <!--INDEX comments:XUL --> 
                    134:     <!--INDEX XUL (XML-based User-interface Language):comments -->
                    135:     your file can begin on the line after the declaration. Comments
                    136:     in XUL follow the same format used in HTML and XML, delimited
                    137:     by <tt>&lt;!--</tt> and <tt>--&gt;</tt>.</p>
                    138:     <p>All tag sets must be closed. Empty <!--INDEX tags, XUL --> 
                    139:     <!--INDEX XUL (XML-based User-interface Language):tags --> tags
                    140:     are allowed for some elements, such as the
                    141:     <tt>&lt;label&gt;</tt> element, that are used without nested
                    142:     elements or content. Note that a trailing slash at the end of
                    143:     the tag is required to denote an empty element.</p>
                    144: <pre>
                    145: &lt;label value="Getting Started" /&gt;
                    146: </pre>
                    147:     <p>Another thing to remember is 
                    148:     <!--INDEX case-sensitivity, XUL --> 
                    149:     <!--INDEX XUL (XML-based User-interface Language):case-sensitivity -->
                    150:     that XUL is case-sensitive. Closing a XUL
                    151:     <tt>&lt;window&gt;</tt> tag with <tt>&lt;/Window&gt;</tt>
                    152:     renders it invalid.</p>
                    153:     <p>These conventions ensure that the rendering engine can parse
                    154:     the XUL file successfully and display the elements defined
                    155:     there. Mozilla does not validate XML files, such as XUL, and it
                    156:     does not resolve externally parsed entities, but it does check
                    157:     for document well-formedness.</p>
                    158:     <p>Following the XML specification, Mozilla ignores well-formed
                    159:     tags that it does not recognize, which can give your
                    160:     applications extra flexibility, particularly as you begin to
                    161:     use technologies such as XBL. But it can also make debugging a
                    162:     little more difficult, as when you create an element named
                    163:     <tt>&lt;botton&gt;</tt> and don't see why your XUL button
                    164:     doesn't have the typical borders or three-dimensional
                    165:     style.</p>
                    166:     <p>A good practice to follow when creating XUL files is to use
                    167:     comments, copious whitespace, indentations (but not tabbed
                    168:     indentations where you can avoid them), and XUL widgets you are
                    169:     familiar with.</p>
                    170:     <h3><a name="77053"></a> The XUL Namespace</h3>
                    171:     <p>Like other markup <!--INDEX namespaces:XUL --> 
                    172:     <!--INDEX XUL (XML-based User-interface Language):namespace -->
                    173:     vocabularies, XUL uses a namespace declaration to define the
                    174:     particular elements that may be included in a valid file. <a
                    175:     href="#77018">Example 2-2</a> shows a sample of the required
                    176:     namespace declaration. The namespace is an attribute of the
                    177:     root <tt>window</tt> element. The lack of any suffix on the XML
                    178:     namespace declaration (i.e., <tt>xmlns:xul</tt>) indicates that
                    179:     XUL is the default namespace for this file.</p>
                    180:     <p><i>Example 2-2: <a name="77018"></a></i> <i>The XUL
                    181:     namespace declaration</i></p>
                    182: <pre>
                    183:  &lt;window
                    184:    xmlns="<a href=
                    185: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"&gt;
1.1       david     186:    &lt;description&gt;Illustrating the XUL namespace&lt;/description&gt;
1.14      petejc    187:  &lt;/window&gt;
                    188: </pre>
                    189:     <p>If you want to include XUL content in documents that use
                    190:     other types of markup, you need to declare more than one
                    191:     namespace. Common namespace declarations for getting other
                    192:     language elements into your code include HTML and RDF, but you
                    193:     can invent your own as well. If you wanted to put the button
                    194:     from <a href="#77016">Example 2-1</a> into a vanilla XML file,
                    195:     for example, you could place it into an XML document by using
                    196:     the <tt>xmlns:xul</tt> attribute, as shown in <a href=
                    197:     "#77020">Example 2-3</a>.</p>
                    198:     <p><i>Example 2-3: <a name="77020"></a></i> <i>Mixed namespaces
                    199:     in an XML document</i></p>
                    200: <pre>
                    201:  &lt;flies:flies
                    202:    xmlns:flies="<a href=
                    203: "http://www.flies.com/come.fly.with.me.xml">http://www.flies.com/come.fly.with.me.xml</a>#"
                    204:    xmlns:html="<a href=
                    205: "http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
                    206:    xmlns:xul="<a href=
                    207: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"&gt;
1.1       david     208:    &lt;flies:wings&gt;
                    209:      &lt;xul:box align="center"&gt;
                    210:        &lt;xul:button label="hello xFly" onclick="alert('hello.');" /&gt;
                    211:      &lt;/xul:box&gt;
                    212:      &lt;html:img src="wings.jpg" /&gt;
                    213:    &lt;/flies:wings&gt;
1.14      petejc    214:  &lt;/flies:flies&gt;
                    215: </pre>
                    216:     <p>This file has three types of content: XUL, HTML, and
                    217:     customized markup called <tt>flies</tt>. When you use mixed
                    218:     namespaces, you have to prefix the XUL elements with
                    219:     <tt>xul</tt>: to distinguish them from markup in other
                    220:     namespaces, as with the <tt>xul:box</tt> and
                    221:     <tt>xul:button</tt> shown in <a href="#77020">Example
                    222:     2-3</a>.</p>
                    223:     <h3><a name="77054"></a> Basic XUL Layout</h3>
                    224:     <p><a href="#77016">Example 2-1</a> features 
                    225:     <!--INDEX XUL (XML-based User-interface Language):elements -->
                    226:     some very common XUL elements. In this section, each element is
                    227:     dissected to show what it does and how it interacts with other
                    228:     elements. The <tt>&lt;window&gt;</tt> element is the root of
                    229:     individual primary XUL documents (in contrast to dialogs that
                    230:     pop up from <!--INDEX dialog element, XUL --> windows, which
                    231:     can use <tt>&lt;dialog&gt;</tt> as the root, and XUL documents
                    232:     loaded within other XUL containers, which can use
                    233:     <tt>&lt;page&gt;</tt>).</p>
                    234:     <p>As in HTML, the root element defines the document into which
                    235:     all elements are drawn, but in XUL, that document is a piece of
                    236:     an application interface and not a web page. We'll have more to
                    237:     say about the window and some of its features in the second
                    238:     example.</p>
                    239:     <p>A <tt>&lt;box&gt;</tt> element that 
                    240:     <!--INDEX box element, XUL --> 
                    241:     <!--INDEX button element, XUL --> contains a
                    242:     <tt>&lt;button&gt;</tt> is inside the window in <a href=
                    243:     "#77016">Example 2-1</a>. Although you can use attributes on
                    244:     the window element to lay out and position window children,
                    245:     it's never a bad idea to use the <tt>&lt;box&gt;</tt> as a
                    246:     container, particularly when you add new layout to your
                    247:     document, such as rows of buttons, grids, tabs, or other
                    248:     elements that need to be arranged precisely within the space of
                    249:     the window. The <tt>box</tt> is the basic element for layout in
                    250:     XUL.</p>
                    251:     <p>The <tt>align</tt> attribute on the box specifies that the
                    252:     children do not stretch and center themselves in the middle of
                    253:     the available space. If the box was omitted and there were
                    254:     multiple children of the root window, they would be laid out
                    255:     vertically by default, one under the other. This setting can be
                    256:     overridden by adding the <tt>orient</tt> attribute to
                    257:     <tt>&lt;window&gt;</tt> and giving it a value of
                    258:     "horizontal."</p>
                    259:     <h3><a name="77055"></a> Using XUL Windows</h3>
                    260:     <p>The foundation of an XPFE application is 
                    261:     <!--INDEX XUL (XML-based User-interface Language):windows --> 
                    262:     <!--INDEX windows:XUL --> a window. Each XUL document has to
                    263:     have at least one XUL <tt>&lt;window&gt;</tt> element, and it
                    264:     must be the root of the document-the surrounding, outermost
                    265:     element in the XML document, set apart from the XML declaration
                    266:     itself and other processing "preambles." A basic window with no
                    267:     content looks like this:</p>
                    268: <pre>
                    269: &lt;?xml version="1.0"?&gt;
1.1       david     270: &lt;!DOCTYPE window&gt;
                    271: &lt;window
1.14      petejc    272: xmlns:html="<a href=
                    273: "http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
                    274: xmlns="<a href=
                    275: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"&gt;
                    276: &lt;/window&gt;
                    277: </pre>
                    278:     <p>Commonly, an application has more than one window, with a
                    279:     number of dialogs and secondary windows. Each window is also 
                    280:     <!--INDEX window element, XUL --> contained within a
                    281:     <tt>&lt;window&gt;</tt> element (though recent additions to the
                    282:     XUL specification include the <tt>dialog</tt> and <tt>page</tt>
                    283:     elements, which are derived from <tt>window</tt> and can be
                    284:     used in its place as root elements in your XUL files).</p>
                    285:     <p>As your application becomes more complex, you need a way to
                    286:     keep track of the windows and ensure that they can communicate
                    287:     with one another. In Mozilla, there is a way to do this by
                    288:     using <!--INDEX toOpenWindowByType( ) function --> 
                    289:     <!--INDEX functions:toOpenWindowByType( ) --> the <tt>type</tt>
                    290:     attribute identifier, which allows you to use special
                    291:     window-opening functions like <tt>toOpenWindowByType( )</tt> to
                    292:     manage particular window types.</p>
                    293:     <blockquote>
                    294:       <div class="c8">
                    295:         NOTE
                    296:       </div>
                    297:       <p>As with any existing Mozilla functions referred to in this
                    298:       book, you can look up <tt>toOpenWindowByType</tt> by using
                    299:       the LXR web-based source code viewer, described in <a href=
                    300:       "appa.html#90096">Appendix A</a> and available at <a href=
                    301:       "http://lxr.mozilla.org/">http://lxr.mozilla.org/</a>.</p>
                    302:     </blockquote>
                    303:     <h4><a name="77056"></a> Window features</h4>
                    304:     <p>An <tt>id</tt> attribute is present on 
                    305:     <!--INDEX XUL (XML-based User-interface Language):windows --> 
                    306:     <!--INDEX windows:XML --> the <tt>&lt;window&gt;</tt> element.
                    307:     Using this <!--INDEX window element, XUL:id attribute -->
                    308:     attribute is not necessary to run the windows system, but it is
                    309:     a good idea to give each window a unique identifier because it
                    310:     makes nodes easier to find from script (see the DOM method
                    311:     <tt>getElementByID</tt> in <a href="ch05.html#77037">Chapter
                    312:     5</a> for information about how to get elements by identifier).
                    313:     This is how to set up an ID attribute:</p>
                    314: <pre>
                    315: &lt;window
                    316: xmlns:html="<a href=
                    317: "http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
                    318: xmlns="<a href=
                    319: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
                    320: id="xflyMain"&gt;
                    321: </pre>
                    322:     <p>Load event handlers such as <tt>onload</tt> and
                    323:     <tt>onunload</tt> are useful and 
                    324:     <!--INDEX load event handlers, window element, XUL -->
                    325:     necessary if you want to add behavior to a window, pass input
                    326:     to it, or manipulate its content depending on context:</p>
                    327: <pre>
                    328: &lt;window
                    329: xmlns:html="<a href=
                    330: "http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
                    331: xmlns="<a href=
                    332: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
1.1       david     333: id="xfly-main"
                    334: onload="startUp( )"
                    335: onunload="shutdown( )"
1.14      petejc    336: onclose="onClose( )"&gt;
                    337: </pre>
                    338:     <p>When you load a XUL file that begins in this way, the event
                    339:     handler attributes <tt>onload</tt> and <tt>onunload</tt> carry
                    340:     out the functions listed as values (<tt>startUp( )</tt> and
                    341:     <tt>shutdown( )</tt>). In addition, Mozilla provides an
                    342:     <tt>onclose</tt> event handler that intercepts the upcoming
                    343:     window closure to carry out any extra processing you need. The
                    344:     close event is fired before the <tt>unload</tt> event, so you
                    345:     can stop the window from closing in the <tt>onclose</tt> event
                    346:     handler if necessary. To stop window closure, the close event
                    347:     must return <i>false</i>.</p>
                    348:     <p>Additional handlers are available for dialog windows. They
                    349:     are listed and their use is outlined in the section <a href=
                    350:     "ch03.html#77087">"Application Windows</a>" in <a href=
                    351:     "ch03.html#32764">Chapter 3</a>.</p>
                    352:     <h4><a name="77057"></a> Window properties</h4>
                    353:     <p>The window declaration is 
                    354:     <!--INDEX windows:XUL:properties --> 
                    355:     <!--INDEX properties:windows, XUL --> 
                    356:     <!--INDEX XUL (XML-based User-interface Language):windows:properties -->
                    357:     expanding, but there is still plenty of room for more features.
                    358:     In addition to the <i>attributes-</i>the event handlers, the
                    359:     ID, and the namespace that appear within the
                    360:     <tt>&lt;window&gt;</tt> tag itself-a XUL window also has all of
                    361:     the properties of the DOM <tt>window</tt> object from HTML.
                    362:     These properties are listed below, along with additional
                    363:     properties for application specific tasks.</p>
                    364:     <table width="100%" border="1">
                    365:       <tr>
                    366:         <td>Navigator</td>
                    367:         <td>Document</td>
                    368:         <td>window</td>
                    369:         <td>Parent</td>
                    370:       </tr>
                    371:       <tr>
                    372:         <td>Top</td>
                    373:         <td>Scrollbars</td>
                    374:         <td>name</td>
                    375:         <td>ScrollX</td>
                    376:       </tr>
                    377:       <tr>
                    378:         <td>ScrollY</td>
                    379:         <td>ScrollTo</td>
                    380:         <td>scrollBy</td>
                    381:         <td>GetSelection</td>
                    382:       </tr>
                    383:       <tr>
                    384:         <td>ScrollByLines</td>
                    385:         <td>ScrollByPages</td>
                    386:         <td>Size</td>
                    387:       </tr>
                    388:       <tr>
                    389:         <td>ToContent</td>
                    390:         <td>Dump</td>
                    391:       </tr>
                    392:       <tr>
                    393:         <td>SetTimeout</td>
                    394:         <td>SetInterval</td>
                    395:         <td>Clear</td>
                    396:       </tr>
                    397:       <tr>
                    398:         <td>Timeout</td>
                    399:         <td>ClearInterval</td>
                    400:       </tr>
                    401:       <tr>
                    402:         <td>SetResizable</td>
                    403:         <td>CaptureEvents</td>
                    404:         <td>Release</td>
                    405:       </tr>
                    406:       <tr>
                    407:         <td>Events</td>
                    408:         <td>RouteEvent</td>
                    409:       </tr>
                    410:       <tr>
                    411:         <td>Enable</td>
                    412:       </tr>
                    413:       <tr>
                    414:         <td>External</td>
                    415:       </tr>
                    416:       <tr>
                    417:         <td>Capture</td>
                    418:         <td>DisableExternal</td>
                    419:       </tr>
                    420:       <tr>
                    421:         <td>Capture</td>
                    422:         <td>prompt</td>
                    423:         <td>Open</td>
                    424:       </tr>
                    425:       <tr>
                    426:         <td>OpenDialog</td>
                    427:         <td>Frames</td>
                    428:         <td>find</td>
                    429:         <td>self</td>
                    430:       </tr>
                    431:       <tr>
                    432:         <td>Screen</td>
                    433:         <td>History</td>
                    434:         <td>content</td>
                    435:         <td>Sidebar</td>
                    436:       </tr>
                    437:       <tr>
                    438:         <td>Menubar</td>
                    439:         <td>Toolbar</td>
                    440:         <td>Locationbar</td>
                    441:         <td>Personalbar</td>
                    442:       </tr>
                    443:       <tr>
                    444:         <td>Statusbar</td>
                    445:         <td>Directories</td>
                    446:         <td>closed</td>
                    447:         <td>Crypto</td>
                    448:       </tr>
                    449:       <tr>
                    450:         <td>pkcs11</td>
                    451:         <td>Controllers</td>
                    452:         <td>opener</td>
                    453:         <td>Status</td>
                    454:       </tr>
                    455:       <tr>
                    456:         <td>defaultStatus</td>
                    457:         <td>Location</td>
                    458:         <td>innerWidth</td>
                    459:         <td>InnerHeight</td>
                    460:       </tr>
                    461:       <tr>
                    462:         <td>outerWidth</td>
                    463:         <td>OuterHeight</td>
                    464:         <td>screenX</td>
                    465:         <td>ScreenY</td>
                    466:       </tr>
                    467:       <tr>
                    468:         <td>pageXOffset</td>
                    469:         <td>PageYOffset</td>
                    470:         <td>length</td>
                    471:         <td>FullScreen</td>
                    472:       </tr>
                    473:       <tr>
                    474:         <td>alert</td>
                    475:         <td>Confirm</td>
                    476:         <td>focus</td>
                    477:         <td>Blur</td>
                    478:       </tr>
                    479:       <tr>
                    480:         <td>back</td>
                    481:         <td>Forward</td>
                    482:         <td>home</td>
                    483:         <td>Stop</td>
                    484:       </tr>
                    485:       <tr>
                    486:         <td>print</td>
                    487:         <td>MoveTo</td>
                    488:         <td>moveBy</td>
                    489:         <td>ResizeTo</td>
                    490:       </tr>
                    491:       <tr>
                    492:         <td>resizeBy</td>
                    493:         <td>Scroll</td>
                    494:         <td>close</td>
                    495:         <td>UpdateCommands</td>
                    496:       </tr>
                    497:       <tr>
                    498:         <td>escape</td>
                    499:         <td>Unescape</td>
                    500:         <td>atob</td>
                    501:         <td>Btoa</td>
                    502:       </tr>
                    503:       <tr>
                    504:         <td>AddEvent</td>
                    505:       </tr>
                    506:       <tr>
                    507:         <td>Listener</td>
                    508:         <td>RemoveEvent</td>
                    509:       </tr>
                    510:       <tr>
                    511:         <td>Listener</td>
                    512:         <td>Dispatch</td>
                    513:       </tr>
                    514:       <tr>
                    515:         <td>Event</td>
                    516:         <td>GetComputed</td>
                    517:       </tr>
                    518:       <tr>
                    519:         <td>Style</td>
                    520:       </tr>
                    521:     </table>
                    522:     <p>Special properties of the XUL window object include:</p>
                    523:     <dl>
                    524:       <dt>window.content</dt>
                    525:       <dd>Using this property is a quick way 
                    526:       <!--INDEX window.content property, window object --> to
                    527:       access the content area of your window, if one exists. This
                    528:       property is useful only if your window uses one of the
                    529:       content elements, namely <tt>&lt;iframe&gt;</tt>,
                    530:       <tt>&lt;browser&gt;</tt>, and <tt>&lt;editor&gt;</tt>. Refer
                    531:       to the section <a href="ch03.html#77123">"Content Panels</a>"
                    532:       in <a href="ch03.html#32764">Chapter 3</a> for a more
                    533:       detailed discussion. The <tt>content</tt> property is linked
                    534:       only to the frame you have explicitly declared as the primary
                    535:       area.</dd>
                    536:     </dl>
                    537:     &lt;browser type="content-primary" ...&gt; 
                    538:     <dl>
                    539:       <dd>Subsequently, you can access and manipulate the
                    540:       content.</dd>
                    541:     </dl>
                    542:     window.content.focus( ); 
                    543:     <dl>
                    544:       <dt>window.sizeToContent( )</dt>
                    545:       <dd>This property is used to ensure 
                    546:       <!--INDEX window.sizeToContent( ) property, window object -->
                    547:       intrinsic sizing, which is important in XUL application
                    548:       development, especially in dialog windows. Intrinsic sizing
                    549:       ensures that the window adapts and morphs to fit the content.
                    550:       This is preferable to constraining your window with a fixed
                    551:       width and height when the <tt>onload</tt> handler anticipates
                    552:       changeable content, depends on context, or takes input from
                    553:       another window. The colorpicker in the Mozilla Editor, for
                    554:       example, uses this function to make sure that the window
                    555:       displaying the chosen palette shrinks to fit that
                    556:       palette:</dd>
                    557:     </dl>
                    558:     function ChangePalette(palette) {
                    559:     gDialog.ColorPicker.setAttribute("palettename", palette);
                    560:     window.sizeToContent( ); } 
                    561:     <h4><a name="77058"></a> Interaction between windows</h4>
                    562:     <p>The <tt>nsIWindowMediator</tt> XPCOM component 
                    563:     <!--INDEX nsIWindowMediator, XPCOM --> 
                    564:     <!--INDEX XPCOM:nsIWindowMediator --> 
                    565:     <!--INDEX windows:XUL:nsIWindowMeditor --> 
                    566:     <!--INDEX XUL (XML-based User-interface Language):windows:nsIWindowMediator -->
                    567:     provides several routines for interacting with different
                    568:     windows. Though it's a little too early to discuss using a
                    569:     component like this in the Hello World examples, these routines
                    570:     include:</p>
                    571:     <ul>
                    572:       <li>Getting the most recent window of a particular type</li>
                    573:       <li>Enumerating all open windows</li>
                    574:       <li>Registering and unregistering the window</li>
                    575:       <li>Updating the window timestamp</li>
                    576:       <li>Updating the window title</li>
                    577:       <li>Setting the Z-order position</li>
                    578:     </ul>
                    579:     <p><a href="ch08.html#78382">Chapter 8</a> provides full
                    580:     details of how to understand and use XPCOM components.</p>
                    581:     <h4><a name="77059"></a> Window behavior</h4>
                    582:     <p>Mozilla supports the 
                    583:     <!--INDEX XUL (XML-based User-interface Language):windows:behaviors -->
                    584:     <!--INDEX windows:XUL:behaviors --> 
                    585:     <!--INDEX window.open function (JavaScript) --> 
                    586:     <!--INDEX functions:JavaScript:window.open --> 
                    587:     <!--INDEX JavaScript:functions:window.open --> standard
                    588:     <tt>window.open</tt> JavaScript function, which has its origins
                    589:     in the world of browser scripting and the launching of new
                    590:     browser windows. Mozilla extends the function to provide some
                    591:     features for application development. It also provides the
                    592:     <tt>window.openDialog</tt> 
                    593:     <!--INDEX window.openDialog function, JavaScript --> 
                    594:     <!--INDEX functions:JavaScript:window.OpenDialog --> 
                    595:     <!--INDEX JavaScript:functions:window.openDialog --> function
                    596:     for opening windows in the XPFE scripting environment. The
                    597:     latter function has become the more commonly used method to
                    598:     open a new XUL window, although the two are
                    599:     interchangeable.</p>
                    600:     <p>The usage of <tt>window.open</tt> is:</p>
                    601: <pre>
                    602: window.open (url, name, features);
                    603: </pre>
                    604:     <p><tt>window.openDialog</tt> extends this functionality with a
                    605:     new argument list passed to it, which is optional and can be
                    606:     any number of arguments as needed:</p>
                    607: <pre>
                    608: window.openDialog (url, type, features, argument1, argument2);
                    609: </pre>
                    610:     <p>Here is a list of some of the features of a XUL window
                    611:     opened using <tt>window.openDialog</tt>:</p>
                    612:     <dl>
                    613:       <dt>close</dt>
                    614:       <dd>The window can be created with or without a close
                    615:       widget.</dd>
                    616:       <dt>chrome</dt>
                    617:       <dd>The new window has to 
                    618:       <!--INDEX chrome context, XUL windows --> 
                    619:       <!--INDEX XUL (XML-based User-interface Language):windows:chrome context -->
                    620:       <!--INDEX windows:XUL:chrome context --> be treated as a
                    621:       window within the chrome context, rather than in the browser
                    622:       context. It gets its own top-level window. The window itself
                    623:       is the chrome URL passed to the function, and is not to be
                    624:       loaded in a browser window.</dd>
                    625:       <dt>dependent</dt>
                    626:       <dd>The new window belongs 
                    627:       <!--INDEX dependence, XUL windows --> 
                    628:       <!--INDEX windows:XUL:dependence --> 
                    629:       <!--INDEX XUL (XML-based User-interface Language):windows:dependence -->
                    630:       to the calling window on operating systems that support this
                    631:       behavior. It "floats" on top of the opening window, and you
                    632:       can still access the parent window. It is minimized with its
                    633:       parent.</dd>
                    634:       <dt>modal</dt>
                    635:       <dd>The window will be run 
                    636:       <!--INDEX modality, XUL windows --> 
                    637:       <!--INDEX XUL (XML-based User-interface Language):windows:modality -->
                    638:       <!--INDEX windows:XUL:modality --> modally. Control is not
                    639:       given back to the parent window until this window has
                    640:       closed.</dd>
                    641:       <dt>titlebar</dt>
                    642:       <dd>The window can be created 
                    643:       <!--INDEX windows:XUL:titlebars --> 
                    644:       <!--INDEX XUL (XML-based User-interface Language):windows:titlebar -->
                    645:       <!--INDEX titlebars, XUL windows --> with or without a
                    646:       titlebar.</dd>
                    647:       <dt>centerscreen</dt>
                    648:       <dd>Open the window centered 
                    649:       <!--INDEX centerscreen, windows (XUL) --> 
                    650:       <!--INDEX windows:XUL:centerscreen --> 
                    651:       <!--INDEX XUL (XML-based User-interface Language):windows:centerscreen -->
                    652:       on screen.</dd>
                    653:     </dl>
                    654:     <p>A comma delimits the features list and the entire list must
                    655:     be in quotes. The script that handles the new window accesses
                    656:     the arguments list:</p>
                    657: <pre>
                    658: window.openDialog("chrome://xfly/content/utils/prompt.xul"
1.1       david     659: "XFLYndo_prompt",
                    660: "chrome,dialog,modal",
1.14      petejc    661: message);
                    662: </pre>
                    663:     <p>The window created in this example will be modal and use the
                    664:     message that was passed to it in the variable <i>message</i>.
                    665:     By default, Mozilla assumes that the <tt>chrome</tt> feature is
                    666:     on when you use either <tt>window.open</tt> or
                    667:     <tt>window.openDialog</tt> in a chrome environment, and creates
                    668:     a new window in the window hierarchy.</p>
                    669:     <h2><a name="77060"></a> Making Mozilla Work for You</h2>
                    670:     <p>The second "Hello World" sample, 
                    671:     <!--INDEX Hello World XUL example:JavaScript and --> 
                    672:     <!--INDEX XUL (XML-based User-interface Language):Hello World example:JavaScript and -->
                    673:     shown in <a href="#77022">Example 2-4</a>, adds some important
                    674:     application features and begins to take advantage of the
                    675:     resources that Mozilla provides for you. This section goes over
                    676:     the ways you can import stylesheets and Mozilla scripts to make
                    677:     your XUL more sophisticated and modular. It also prepares you
                    678:     to make an actual application.</p>
                    679:     <p>You can see this example in action by saving the code in <a
                    680:     href="#77022">Example 2-4</a> to a file, <i>hello2.xul</i>, and
                    681:     then launching Mozilla and selecting File &gt; Open File from
                    682:     the browser. This displays the example as content in the
                    683:     Mozilla browser, as shown in <a href="#77004">Figure
                    684:     2-2</a>.</p>
                    685:     <p><i>Example 2-4: <a name="77022"></a></i> <i>Sample XUL
                    686:     window</i></p>
                    687: <pre>
                    688:  &lt;?xml version="1.0"?&gt;
1.1       david     689:  &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;
                    690:  &lt;!DOCTYPE window&gt;
                    691:  &lt;window title="Hello xFly"
1.14      petejc    692:    xmlns:html="<a href=
                    693: "http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
                    694:    xmlns="<a href=
                    695: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
1.1       david     696:    style="background-color: white;"
                    697:    width="300"
                    698:    height="215"
                    699:    onload="centerWindowOnScreen( )"&gt;
                    700:  &lt;script type="application/x-javascript"
                    701:    src="chrome://global/content/dialogOverlay.js" /&gt;
                    702:  &lt;vbox align="left"&gt;
                    703:    &lt;label style="font-weight: bold;"
                    704:        value="Hello, Welcome to the xFly" /&gt;
1.14      petejc    705:    &lt;image src="<a href=
                    706: "http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</a>" /&gt;
1.1       david     707:    &lt;button label="hello xFly" oncommand="alert('Hello World');" /&gt;
                    708:  &lt;/vbox&gt;
1.14      petejc    709:  &lt;/window&gt;
                    710: </pre>
                    711:     <p>The difference between <a href="#77022">Example 2-4</a> and
                    712:     the first example is the addition of new elements, including
                    713:     the <tt>script</tt> element that brings in Mozilla JavaScript
                    714:     functions for use, additional box layout properties, inline
                    715:     style rules and processing instructions to import stylesheets,
                    716:     and the <tt>DOCTYPE</tt> declaration, which we describe later
                    717:     in this chapter in the section <a href="#77078">"The xFly
                    718:     DTD</a>."</p>
                    719:     <p>These extras make your XUL file work more like an
                    720:     application by giving you access to services and features that
                    721:     already exist in Mozilla. They can also help you organize your
                    722:     own work into reusable parts, such as application stylesheets,
                    723:     widgets, and script libraries, as described later in this
                    724:     chapter in the section <a href="#77065">"Creating a
                    725:     Package</a>."</p>
                    726:     <div class="c7">
                    727:       <img src="foo.gif">
                    728:     </div>
                    729:     <p><i>Figure 2-2: <a name="77004"></a></i> <i>The second Hello
                    730:     xFly example loaded in the browser</i></p>
                    731:     <h3><a name="77061"></a> Importing Resources from Mozilla</h3>
                    732:     <p>The code in <a href="#77022">Example 2-4</a> uses scripts 
                    733:     <!--INDEX resources:importing from Mozilla --> 
                    734:     <!--INDEX importing:resources --> and styles that are already
                    735:     defined in Mozilla. As you'll see in examples in this book 
                    736:     <!--INDEX global.css stylesheet --> 
                    737:     <!--INDEX stylesheets:global.css --> and in the Mozilla source
                    738:     code, the <i>global.css</i> stylesheet is where many basic
                    739:     styles 
                    740:     <!--INDEX XUL widgets:styles;widgets:XUL:styles;styles:widgets, XUL -->
                    741:     are defined for XUL widgets. Most XUL widgets have some
                    742:     inherent style, as you can see in <a href="#77016">Example
                    743:     2-1</a>, where the button has a button-like look without any
                    744:     explicit style rules or stylesheet imports.</p>
                    745:     <p>As the XPFE has evolved, XUL widgets 
                    746:     <!--INDEX XUL widgets:XBL and;XBL (eXtensible Binding Language):XUL widgets and -->
                    747:     have used XBL internally to define some of these inherent looks
                    748:     and behaviors, which has taken some of the responsibility away
                    749:     from <i>global.css</i> and other CSS files. But this stylesheet
                    750:     still contains important rules for displaying basic XUL
                    751:     widgets. It's usually a good idea to import this main
                    752:     stylesheet into your application, as described here, and see
                    753:     what it gets you in terms of presentation. If you load <a href=
                    754:     "#77022">Example 2-4</a> with and without the <i>global.css</i>
                    755:     line, you can see the way that the rules in the stylesheet
                    756:     provide styles for the widgets in the XUL.</p>
                    757:     <p>Similarly, scripts like <i>globalOverlay.js</i>,
                    758:     <i>tasksOverlay.js</i>, and <i>dialogOverlay.js</i>, imported
                    759:     in <a href="#77022">Example 2-4</a>, provide basic functions
                    760:     you can use in your applications.</p>
                    761:     <h4><a name="77062"></a> Loading stylesheets</h4>
                    762:     <p>In the second line of <a href="#77022">Example 2-4</a>, the
                    763:     stylesheet <!--INDEX stylesheets:loading --> declaration uses a
                    764:     <i>chrome://</i> URL to refer to and load the <i>global.css</i>
                    765:     file. The style rules in that file give the button widget its
                    766:     "widgetness." You can use the stylesheet 
                    767:     <!--INDEX stylesheets:(see also CSS)[stylesheets:zz(see also CSS)] -->
                    768:     processing instruction to load Mozilla stylesheets like
                    769:     <i>global.css</i>, <i>navigator.css</i>, 
                    770:     <!--INDEX navigator.css stylesheet;toolbar.css stylesheet;stylesheets:navigator.css;stylesheets:toolbar.css -->
                    771:     and <i>toolbar.css</i>, or you can use it to load your own
                    772:     application stylesheet. In both cases, the <i>chrome://</i> URL
                    773:     allows you to refer to packaged files in a flexible way.</p>
                    774: <pre>
                    775: &lt;!--import the navigator.css stylesheet
1.1       david     776: from the Mozilla navigator component--&gt;
                    777: &lt;?xml-stylesheet href="chrome://navigator/skin" type="text/css"?&gt;
                    778: &lt;!--import xfly.css stylesheet from the xFly package--&gt;
1.14      petejc    779: &lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;
                    780: </pre>
                    781:     <p>Also note the use of an inline style in <a href=
                    782:     "#77022">Example 2-4</a>. The <tt>style</tt> property on the
                    783:     <tt>label</tt> widget gives you a place to define CSS rules
                    784:     directly on widgets. In this case, the label is given a bold
                    785:     font so that it shows up better in the window. You could also
                    786:     define this style rule in an external stylesheet and make that
                    787:     stylesheet part of the package for your application, as we do
                    788:     later in this chapter in the section <a href=
                    789:     "#77075">"Separating the Files</a>."</p>
                    790:     <h4><a name="77063"></a> Accessing script in XUL</h4>
                    791:     <p>To access a script in XUL, use the <tt>script</tt> element 
                    792:     <!--INDEX XUL (XML-based User-interface Language):scripts, access;scripts:XUL, access -->
                    793:     and a URL value for its <tt>src</tt> attribute:</p>
                    794: <pre>
                    795: &lt;script type="application/x-javascript"
                    796: src="chrome://xfly/content/xfly.js" /&gt;
                    797: </pre>
                    798:     <p>The <tt>dialogOverlay.js</tt> script imported into 
                    799:     <!--INDEX dialogOverlay.js script;scripts:dialogOverlay.js -->
                    800:     your XUL file in <a href="#77022">Example 2-4</a> provides
                    801:     access to the <tt>CenterWindowOnScreen( )</tt> function. This 
                    802:     <!--INDEX CenterWindowOnScreen( ) function, JavaScript;functions:JavaScript:CenterWindowOnScreen( );JavaScript:functions:CenterWindowOnScreen( ) -->
                    803:     function is made available to your XUL file with the line:</p>
                    804: <pre>
                    805: &lt;script type="application/x-javascript"
                    806: src="chrome://global/content/dialogOverlay.js" /&gt;
                    807: </pre>
                    808:     <p>All functions in <i>dialogOverlay.js</i> are imported into
                    809:     the scope of the XUL file and can be called directly, as
                    810:     <tt>CenterWindowOnScreen( )</tt> is in the <tt>onload</tt>
                    811:     event handler for the XUL window. Note that the functions
                    812:     contained in an imported JavaScript file are not broadcast in
                    813:     any particular way (though you can see them if you use the
                    814:     JavaScript Debugger). You may need to look around in the source
                    815:     code or see how other applications import files to find the
                    816:     functions you need, but the routines you want to use in your
                    817:     application code are probably already available in Mozilla.<a
                    818:     name="b260"></a><a href="#260">[*]</a></p>
                    819:     <h2><a name="77064"></a> Displaying XUL Files as Chrome</h2>
                    820:     <p><a href="#77004">Figure 2-2</a> shows the XUL file 
                    821:     <!--INDEX XUL files:displaying as chrome;chrome:XUL files, displaying -->
                    822:     in <a href="#77022">Example 2-4</a> loaded into the browser's
                    823:     main content area. The example features a <tt>label</tt> widget
                    824:     and an <tt>image</tt>, both situated within a <tt>vbox</tt>
                    825:     that lays them out properly in the available space. These
                    826:     widgets make up the chrome of your application, the Mozilla
                    827:     user interface that can refer to itself and its resources with
                    828:     the special <i>chrome://</i> URL.</p>
                    829:     <p>This example is starting to show off some of the nice
                    830:     features of XPFE programming, but it still isn't an application
                    831:     yet. Among other things, you probably don't want your code to
                    832:     live inside the browser window forever. As it grows, you may
                    833:     also want to divide it into sensible parts-a XUL file, a
                    834:     separate stylesheet, and a script file, for example. The rest
                    835:     of this chapter explains how to organize and package the code
                    836:     in <a href="#77022">Example 2-4</a> and launch it as a
                    837:     standalone window by using the <tt>-chrome</tt> option when
                    838:     launching Mozilla.</p>
                    839:     <p>Launching a XUL file by using the chrome switch requires
                    840:     that you register your application in the chrome registry so
                    841:     that Mozilla sees and recognizes it. The <a href=
                    842:     "#77079">"Registering a Package</a>" section later in this
                    843:     chapter provides more information about the chrome environment
                    844:     and how to register this sample application.</p>
                    845:     <p>Although this example hasn't been registered yet, we want to
                    846:     give you a preview of what it will look like when launched in a
                    847:     standalone window so you can compare it with how the same XUL
                    848:     file looks when loaded into the browser window. When you do
                    849:     launch the example by using the <tt>-chrome</tt> option (as
                    850:     described later in this chapter in the section <a href=
                    851:     "#77080">"Launching the Application</a>"), you will see the
                    852:     window displayed in <a href="#77006">Figure 2-3</a>.</p>
                    853:     <div class="c7">
                    854:       <img src="foo.gif">
                    855:     </div>
                    856:     <p><i>Figure 2-3: <a name="77006"></a></i> <i>The second Hello
                    857:     xFly example launched in its own window</i></p>
                    858:     <p>Using the <tt>-chrome</tt> option tells Mozilla to display
                    859:     the specified file (in this case, the code from <a href=
                    860:     "#77022">Example 2-4</a>) as a standalone application rather
                    861:     than as content within a browser window. The file itself is the
                    862:     same regardless of how it is loaded, but the results differ
                    863:     depending on what you tell Mozilla to do with the file.</p>
                    864:     <p>Displaying a XUL file in its own chrome window makes it more
                    865:     independent and breaks the link to the browser content area
                    866:     that is present when you use the File &gt; Open File... method.
                    867:     Launching standalone windows, accompanied by the JavaScript
                    868:     <tt>window.openDialog</tt> function explained later in this
                    869:     chapter, opens up much more flexible window display options for
                    870:     your application.</p>
                    871:     <h2><a name="77065"></a> Creating a Package</h2>
                    872:     <p>The previous two main sections 
                    873:     <!--INDEX chrome:package content;packages:chrome and -->
                    874:     introduced the concept of chrome and the prospect of creating
                    875:     standalone application windows. The next step is to make the
                    876:     example into an actual package-a modularized collection of
                    877:     files that can be installed in Mozilla as a new
                    878:     application.</p>
                    879:     <p>In the earlier section <a href="#77060">"Making Mozilla Work
                    880:     for You</a>," you added features and complexity to your XUL
                    881:     file. In this section, you pull those features into separate
                    882:     files-a CSS file, JS file, and a DTD file-register these files
                    883:     together, and make them installable as a single package.</p>
                    884:     <p>Only when you have packaged your work will your files have
                    885:     access to Mozilla files, such as CSS and scripts, be accessible
                    886:     from the special <i>chrome://</i> type URLs, be able to accept
                    887:     new themes, and be able 
                    888:     <!--INDEX packages:CSS and;packages:scripts and;packages:themes and;packages:XPCOM objects and -->
                    889:     <!--INDEX stylesheets:packages and;scripts:packages and;themes:packages and;XPCOM:methods:JavaScript implementation -->
                    890:     to get to the XPCOM objects in which much of the application
                    891:     for Mozilla is defined.</p>
                    892:     <p>Tools are available that help set up the files that form the
                    893:     basis of a new package. <a href="appb.html#78077">Appendix
                    894:     B</a> provides information about XULKit, which is a collection
                    895:     of scripts that automates part of the package creation process.
                    896:     It is recommended that you try to set up your own package by
                    897:     hand first to understand how packages are put together before
                    898:     using the XULKit scripts.</p>
                    899:     <h3><a name="77066"></a> Architecture of a Chrome Package</h3>
                    900:     <p>The architecture of the <!--INDEX packages:architecture --> 
                    901:     <!--INDEX chrome:packages (see packages) --> Mozilla XPFE is
                    902:     component- or layer-based. One of the primary aims of the
                    903:     design was the separation of each different component of an
                    904:     application, namely content, functionality, and layout. This
                    905:     design results in greater modularization, making it easy to
                    906:     create and change a UI-to change skins for your application,
                    907:     for example, update the language in which the user interface is
                    908:     presented, or bring in new script elements.</p>
                    909:     <p>When a package is modularized like it can be in Mozilla,
                    910:     design determinations can be left to the designer, language in
                    911:     the user interface can be left to writers, and the application
                    912:     framework itself can be handled by software developers (though
                    913:     the programmer handles all of these in many small- to
                    914:     medium-sized projects). The next several sections provide more
                    915:     detail about each component and its content and file types. The
                    916:     way basic packages fit components together can be the basis for
                    917:     your own application development.</p>
                    918:     <p>A package is a group of directories and related files that
                    919:     make up a Mozilla application. A small, typical package may
                    920:     include a single XUL file, a script file (currently JavaScript,
                    921:     with implementations for Perl, Python, Ruby, and other
                    922:     languages being developed), and a CSS file. However, a single
                    923:     package might include dozens of these files, and may also
                    924:     include XBL files, Image File Types (PNG, JPG, GIF), DTD, HTML,
                    925:     and RDF files. Each has an important role to play in the
                    926:     application.</p>
                    927:     <h3><a name="77067"></a> Package Components</h3>
                    928:     <p>As you will discover, each <!--INDEX packages:components -->
                    929:     component in a package is independent. It is possible for your
                    930:     application to exist with just one or two of these components.
                    931:     Yet they all tie together when necessary to create a full
                    932:     featured application, and they are all at your disposal to take
                    933:     advantage of.</p>
                    934:     <h4><a name="77068"></a> Chrome content</h4>
                    935:     <p>The content is 
                    936:     <!--INDEX packages:chrome content;chrome:package content;XUL data, packages;XBL data, packages;packages:XUL data;packages:XBL 
                    937:     data --> the XUL and XBL data, contained in one or more files.
                    938:     This content is pulled in at runtime from files, overlays, and
                    939:     bindings, for display in the window system. The cross-platform
                    940:     implementation ensures consistency in the native system, and
                    941:     fits into the "write once, run anywhere" model. The XUL defines
                    942:     a single set of UI elements for all platforms. The XUL parser
                    943:     is much less tolerant than many HTML parsers; in fact, it's
                    944:     completely intolerant. However, it needs to be because every
                    945:     element in XUL impacts others and affects the layout of the
                    946:     UI-especially in the context of the Box Model, which <a href=
                    947:     "ch03.html#77084">Chapter 3</a> describes in detail.</p>
                    948:     <p>The widget set consists of simple widgets that display by
                    949:     drawing themselves absolutely in their allotted space, and of
                    950:     more complex widgets that act as containers, draw on top of
                    951:     others, or <!--INDEX packages:widget set;widgets:packages -->
                    952:     accept input. A <tt>&lt;label&gt;</tt> widget is an example of
                    953:     the former, while <tt>&lt;stack&gt;</tt> is of the latter, more
                    954:     complex group. If the parser does not find an element in the
                    955:     content files, it fails to load and returns an error. Errors
                    956:     vary by type. An XML syntax error, for example, displays in the
                    957:     window in place of the expected content. It gives you the file
                    958:     the error originated in, along with the line number and column
                    959:     number.</p>
                    960:     <p>Built as a complementary 
                    961:     <!--INDEX XBL (eXtensible Binding Language):widget creation -->
                    962:     description language to XUL, XBL allows you to create your own
                    963:     widgets or add new behavior to existing XUL widgets. You may
                    964:     attach scripting and create (anonymous) content in a single
                    965:     binding or in many. With a little imagination, you can extend
                    966:     the content available to you infinitely by adding your own
                    967:     styling and behavior with XBL.</p>
                    968:     <h4><a name="77069"></a> Chrome appearance</h4>
                    969:     <p>Loading up a XUL file with 
                    970:     <!--INDEX chrome:appearance, packages;packages:chrome content:appearance -->
                    971:     no styles attached 
                    972:     <!--INDEX styles:packages;packages:styles --> to the XUL
                    973:     elements will render the UI as a plain, disproportioned group
                    974:     of widgets. While plain text on a web page can be effective for
                    975:     simply relaying information, the situation is not analogous in
                    976:     user interfaces.</p>
                    977:     <p>Mozilla user interfaces without style are not very usable.
                    978:     Even to achieve the traditional plain gray interface that so
                    979:     many applications use, you must use CSS to style the Mozilla
                    980:     front end, and subtle effects, such as color grades or 3D
                    981:     button effects, often make even the most basic interface look
                    982:     and work better.</p>
                    983:     <p>Themes and the ability to customize 
                    984:     <!--INDEX themes:packages;packages:themes and --> the look of
                    985:     an application are becoming more prominent. Mozilla developers
                    986:     realized this prominence during the design phase of Mozilla,
                    987:     and it's reflected in the architecture: the appearance of the
                    988:     interface is almost entirely separate from the structural
                    989:     representation in the content.</p>
                    990:     <h4><a name="77070"></a> Chrome behavior</h4>
                    991:     <p>Mozilla currently supports 
                    992:     <!--INDEX chrome:package content:behavior;packages:chrome content:behavior -->
                    993:     only JavaScript <!--INDEX JavaScript:UI and --> as the bridge
                    994:     between the UI and the application code. JavaScript is the glue
                    995:     that binds the UI and the back end functionality, which is
                    996:     almost entirely written in C++.</p>
                    997:     <p>Much of the infrastructure is in place for 
                    998:     <!--INDEX Python;Perl --> the support of other programming
                    999:     languages, however, and Python and Perl are currently being
                   1000:     proposed as the next languages to fit into the framework.
                   1001:     Currently, you will see JavaScript associated with XUL content
                   1002:     via the following declaration:</p>
                   1003: <pre>
                   1004: &lt;script type="application/x-javascript" src="xfly.js" /&gt;
                   1005: </pre>
                   1006:     <p><tt>type</tt> replaces the now deprecated <tt>language</tt>
                   1007:     attribute and expects a MIME type for its value. As Mozilla
                   1008:     matures and support for other languages arrives, this value may
                   1009:     become interchangeable-which fits in with the philosophy,
                   1010:     common in open source projects, of there being More Than One
                   1011:     Way To Do It. Note that the behavior component of a Mozilla
                   1012:     application usually sits in the <i>content</i> subdirectory of
                   1013:     a package, as described later in the section <a href=
                   1014:     "#77072">"Directory Structure</a>."</p>
                   1015:     <h4><a name="77071"></a> Chrome locale</h4>
                   1016:     <p>Localization is 
                   1017:     <!--INDEX packages:chrome content:locale;chrome:package content:locale -->
                   1018:     the modification of software to meet the language of a location
                   1019:     and the adaptation of resources, such as user interface and
                   1020:     documentation, for that region. Widgets such as menu items,
                   1021:     buttons, window titlebars, and alert dialogs commonly need to
                   1022:     be localized. Beyond these widgets, there can be other
                   1023:     localizable content in an application, from HTML pages to
                   1024:     install packages.</p>
                   1025:     <p>The formats used by Mozilla are:</p>
                   1026:     <ul>
                   1027:       <li>DTD (<i>.dtd</i>) files, which contain entities that host
                   1028:       the strings to be included in your XUL content.</li>
                   1029:       <li>Property files (<i>.properties</i>), which contain string
                   1030:       bundles that are accessed by dynamic content in JavaScript
                   1031:       and C++ files or, theoretically, any language.</li>
                   1032:       <li>HTML files for certain pages installed with the
                   1033:       application-e.g., About Mozilla.</li>
                   1034:       <li>RDF files.</li>
                   1035:     </ul>
                   1036:     <h3><a name="77072"></a> Directory Structure</h3>
                   1037:     <p>Files can be organized <!--INDEX directories --> in many
                   1038:     different ways. If your application is small-say a single
                   1039:     window with a simple structure that needs to be available only
                   1040:     in one language-then having all your files in one directory may
                   1041:     be easier. As the size of an application goes over a certain
                   1042:     threshold, however, logically grouping your files into
                   1043:     subdirectories is a good practice to make the files more
                   1044:     accessible.</p>
                   1045:     <p>Most applications use a directory structure that mirrors the
                   1046:     package component descriptions described earlier: XUL and
                   1047:     JavaScript <!--INDEX directories:content;content directory -->
                   1048:     in a <i>content</i> subdirectory, CSS and images in a
                   1049:     <i>skin</i> subdirectory, 
                   1050:     <!--INDEX skin directory;directories:skin --> and DTDs and
                   1051:     other resources for localizing the interface in a <i>locale</i>
                   1052:     subdirectory. <a href="#77008">Figure 2-4</a> 
                   1053:     <!--INDEX locale directory;directories:locale --> shows this
                   1054:     common grouping.</p>
                   1055:     <div class="c7">
                   1056:       <img src="foo.gif">
                   1057:     </div>
                   1058:     <p><i>Figure 2-4: <a name="77008"></a></i> <i>A sample package
                   1059:     layout in the directory system</i></p>
                   1060:     <p>These three different directories usually contain the
                   1061:     following type of files:</p>
                   1062:     <dl>
                   1063:       <dt>content</dt>
                   1064:       <dd>The <i>content</i> directory is 
                   1065:       <!--INDEX XUL files:content directory;content directory:XUL files -->
                   1066:       the home for the XUL files that contain the widgets to be
                   1067:       drawn for you application. It is 
                   1068:       <!--INDEX JavaScript:files, content directory --> common
                   1069:       practice to also place files related to behavior, namely
                   1070:       JavaScript files, in this directory.</dd>
                   1071:       <dt>locale</dt>
                   1072:       <dd>This directory contains 
                   1073:       <!--INDEX locale directory;directories:locale --> the files 
                   1074:       <!--INDEX DTD:locale directory --> that contain localized
                   1075:       strings for your package. Most files are DTD files that
                   1076:       contain the entities referenced in XUL files. There is a
                   1077:       subdirectory for each language, and the naming convention is
                   1078:       <i>code-region</i>, such as <tt>en-US</tt>.</dd>
                   1079:       <dt>skin</dt>
                   1080:       <dd>The term "skin" is an 
                   1081:       <!--INDEX skin directory;directories:skin --> internal name 
                   1082:       <!--INDEX stylesheets:skin directory --> for a theme. The
                   1083:       <i>skin</i> directory contains all CSS files and images that
                   1084:       contribute to the appearance of the windows. This is a good
                   1085:       place to put the application images-in their own
                   1086:       subdirectory.</dd>
                   1087:     </dl>
                   1088:     <h4><a name="77073"></a> The xFly application directory
                   1089:     structure</h4>
                   1090:     <p>The structure of the directories in which 
                   1091:     <!--INDEX xFly package:directories --> an application is
                   1092:     defined (whether those directories are in the filesystem or
                   1093:     subdirectories in an archive such as a JAR file) is an
                   1094:     important part of that application's design and relationship to
                   1095:     Mozilla. Use the following steps to make your xFly package
                   1096:     self-contained, registerable, and adaptable.</p>
                   1097:     <ul>
                   1098:       <li>On your computer, go to the directory where you have
                   1099:       installed Mozilla and create a new directory underneath the
                   1100:       <i>chrome</i> directory called "<i>xfly</i>."</li>
                   1101:     </ul>
                   1102:     <div class="c9">
                   1103:       <p>All Mozilla applications live in the <i>chrome</i>
                   1104:       directory.</p>
                   1105:     </div>
                   1106:     <ul>
                   1107:       <li>Under that directory, create the three new directories,
                   1108:       <i>content</i>, <i>locale</i>, and <i>skin</i>, as shown in
1.19      david    1109:       <a href="#77010">Figure 2-5</a>. The <i>locale</i> directory 
                   1110:       will have the default 'en-US' language pack structure.</li>
1.14      petejc   1111:     </ul>
                   1112:     <div class="c7">
                   1113:       <img src="foo.gif">
                   1114:     </div>
                   1115:     <p><i>Figure 2-5: <a name="77010"></a></i> <i>xFly package
                   1116:     directory structure</i></p>
                   1117:     <h3><a name="77074"></a> Package Manifests</h3>
                   1118:     <p>Now that you have created the 
                   1119:     <!--INDEX packages:manifests;manifests:packages --> directories
                   1120:     for your package, you must tell Mozilla about them. All Mozilla
                   1121:     packages must include manifests that describe their contents
                   1122:     and make it possible to register them with Mozilla. A manifest
                   1123:     is an RDF file (or series of RDF files) that sits within the
                   1124:     package and interacts with Mozilla's <i>chrome</i> directory.
                   1125:     RDF files are XML files that describe data in a
                   1126:     machine-readable form.</p>
                   1127:     <p>Each xFly package subdirectory needs its own manifest file.
                   1128:     Mozilla uses these files (in each case, called
                   1129:     <i>contents.rdf</i>) when registering the application. These
                   1130:     files are listed in Examples <a href="#77024">2-5</a>, <a href=
                   1131:     "#77026">2-6</a>, and <a href="#77028">2-7</a>. Create these
                   1132:     files in your xFly <i>content</i>, <i>skin</i>, and
                   1133:     <i>locale</i> subdirectories, respectively.</p>
                   1134:     <p><i>Example 2-5: <a name="77024"></a></i>
                   1135:     <i>chrome/xfly/content/contents.rdf file</i></p>
                   1136: <pre>
                   1137:  &lt;?xml version="1.0"?&gt;
                   1138:  &lt;RDF:RDF xmlns:RDF="<a href=
                   1139: "http://www.w3.org/1999/02/22-rdf-syntax-ns">http://www.w3.org/1999/02/22-rdf-syntax-ns</a>#"
                   1140:           xmlns:chrome="<a href=
                   1141: "http://www.mozilla.org/rdf/chrome">http://www.mozilla.org/rdf/chrome</a>#"&gt;
1.1       david    1142:    &lt;!-- list all the packages being supplied --&gt;
                   1143:    &lt;RDF:Seq about="urn:mozilla:package:root"&gt;
                   1144:      &lt;RDF:li resource="urn:mozilla:package:xfly"/&gt;
                   1145:    &lt;/RDF:Seq&gt;
                   1146:    &lt;!-- package information --&gt;
                   1147:    &lt;RDF:Description about="urn:mozilla:package:xfly"
                   1148:          chrome:displayName="xFly"
                   1149:          chrome:author="xfly.mozdev.org"
                   1150:          chrome:name="xfly"&gt;
                   1151:    &lt;/RDF:Description&gt;
1.14      petejc   1152:  &lt;/RDF:RDF&gt;
                   1153: </pre>
                   1154:     <p>In the content manifest in <a href="#77024">Example 2-5</a>,
                   1155:     note the <tt>chrome:name</tt>, <tt>chrome:author</tt>, and the
                   1156:     other metadata that the manifest provides to Mozilla. This
                   1157:     information can be used by others to identify what your
                   1158:     application is and who wrote it. For example, the name, author,
                   1159:     and short description information for each browser theme you
                   1160:     have installed is viewable by going to Preferences and
                   1161:     selecting Appearance &gt; Themes.</p>
                   1162:     <p>In <a href="#77026">Example 2-6</a>, which describes 
                   1163:     <!--INDEX skins:xFly application;xFly:skins --> the skin for
                   1164:     xFly only, note that new skin resources for the Classic theme
                   1165:     are all that is supplied, as indicated in the <tt>RDF:Seq</tt>,
                   1166:     which lists only <tt>classic</tt> as affected by this new
                   1167:     package.</p>
                   1168:     <p><i>Example 2-6: <a name="77026"></a></i>
                   1169:     <i>chrome/xfly/skin/contents.rdf file</i></p>
                   1170: <pre>
                   1171:  &lt;?xml version="1.0"?&gt;
                   1172:  &lt;RDF:RDF xmlns:RDF="<a href=
                   1173: "http://www.w3.org/1999/02/22-rdf-syntax-ns">http://www.w3.org/1999/02/22-rdf-syntax-ns</a>#"
                   1174:           xmlns:chrome="<a href=
                   1175: "http://www.mozilla.org/rdf/chrome">http://www.mozilla.org/rdf/chrome</a>#"&gt;
1.1       david    1176:    &lt;RDF:Seq about="urn:mozilla:skin:root"&gt;
                   1177:      &lt;RDF:li resource="urn:mozilla:skin:classic/1.0" /&gt;
                   1178:    &lt;/RDF:Seq&gt;
                   1179:    &lt;RDF:Description about="urn:mozilla:skin:classic/1.0"&gt;
                   1180:      &lt;chrome:packages&gt;
                   1181:        &lt;RDF:Seq about="urn:mozilla:skin:classic/1.0:packages"&gt;
                   1182:          &lt;RDF:li resource="urn:mozilla:skin:classic/1.0:xfly"/&gt;
                   1183:        &lt;/RDF:Seq&gt;
                   1184:      &lt;/chrome:packages&gt;
                   1185:    &lt;/RDF:Description&gt;
1.14      petejc   1186:  &lt;/RDF:RDF&gt;
                   1187: </pre>
                   1188:     <p>In <a href="#77028">Example 2-7</a>, which shows the third
                   1189:     kind of manifest, for new locale information, the English
                   1190:     language pack (<tt>en-US</tt>) is augmented with the
                   1191:     localizable resources in the xFly package named there. The
                   1192:     <tt>RDF:Seq</tt> structure 
                   1193:     <!--INDEX RDF\:Seq structure, manifests --> in a manifest
                   1194:     states, "to the package listed here (i.e., the <tt>en-US</tt>
                   1195:     language pack), add the following."</p>
                   1196:     <p><i>Example 2-7: <a name="77028"></a></i>
                   1197:     <i>chrome/xfly/locale/contents.rdf file</i></p>
                   1198: <pre>
                   1199:  &lt;?xml version="1.0"?&gt;
                   1200:  &lt;RDF:RDF xmlns:RDF="<a href=
                   1201: "http://www.w3.org/1999/02/22-rdf-syntax-ns">http://www.w3.org/1999/02/22-rdf-syntax-ns</a>#"
                   1202:           xmlns:chrome="<a href=
                   1203: "http://www.mozilla.org/rdf/chrome">http://www.mozilla.org/rdf/chrome</a>#"&gt;
1.1       david    1204:    &lt;RDF:Seq about="urn:mozilla:locale:root"&gt;
                   1205:      &lt;RDF:li resource="urn:mozilla:locale:en-US"/&gt;
                   1206:    &lt;/RDF:Seq&gt;
                   1207:    &lt;!-- locale information --&gt;
1.17      brian    1208:    &lt;RDF:Description about="urn:mozilla:locale:en-US"
1.1       david    1209:          chrome:displayName="English(US)"
                   1210:          chrome:author="xfly.mozdev.org"
                   1211:          chrome:name="en-US"
1.14      petejc   1212:          chrome:previewURL="<a href=
                   1213: "http://www.mozilla.org/locales/en-US.gif">http://www.mozilla.org/locales/en-US.gif</a>"&gt;
1.1       david    1214:      &lt;chrome:packages&gt;
                   1215:        &lt;RDF:Seq about="urn:mozilla:locale:en-US:packages"&gt;
1.17      brian    1216:          &lt;RDF:li resource="urn:mozilla:locale:en-US:xfly"/&gt;
1.1       david    1217:        &lt;/RDF:Seq&gt;
                   1218:      &lt;/chrome:packages&gt;
                   1219:    &lt;/RDF:Description&gt;
1.14      petejc   1220:  &lt;/RDF:RDF&gt;
                   1221: </pre>
                   1222:     <p>Manifests are detailed in <a href="ch06.html#15291">Chapter
                   1223:     6</a>. For now, it's enough to see that each manifest describes
                   1224:     the subdirectory in which it is located, and that the contents
                   1225:     of those subdirectories make up the package collectively.</p>
                   1226:     <p>The content describes the content of the xFly package, the
                   1227:     XUL, and the JavaScript. The skin describes the theme of xFly,
                   1228:     or the CSS and images used to lay out the XUL. The third part
                   1229:     describes the locale, or the strings in the UI that can be
                   1230:     localized or adapted for various languages or locales.</p>
                   1231:     <h3><a name="77075"></a> Separating the Files</h3>
                   1232:     <p>Once you have a subdirectory structure set up 
                   1233:     <!--INDEX packages:file separation;files:separating, packages;separating files, packages -->
                   1234:     in accordance with the package component structure of your
                   1235:     application, you can pull the pieces of your XUL file out into
                   1236:     their own files and modularize your application. These separate
                   1237:     files-the basic XUL file and separate CSS, JS, and DTD
                   1238:     files-are registered as a single package and can then be
                   1239:     launched as a standalone application.</p>
                   1240:     <p>Though the files contain the information you've already seen
                   1241:     in the "Hello World" sample shown in <a href="#77022">Example
                   1242:     2-4</a>, their interaction demonstrates how packages can work
                   1243:     together in Mozilla. Each step taken to separate the different
                   1244:     components requires editing the base XUL file.</p>
                   1245:     <h4><a name="77076"></a> The xFly CSS file</h4>
                   1246:     <p>The inline style rule 
                   1247:     <!--INDEX xfly.css file;stylesheets:xfly.css file;packages:xfly.css file -->
                   1248:     on the label widget can go almost unadulterated into a separate
                   1249:     text file called <i>xfly.css</i>. Save the code in <a href=
                   1250:     "#77030">Example 2-8</a> in the <i>chrome/xfly/skin/</i>
                   1251:     directory.</p>
                   1252:     <p><i>Example 2-8: <a name="77030"></a></i> <i>The contents of
                   1253:     the xfly.css file</i></p>
                   1254: <pre>
                   1255:  #xlabel { font-weight: bold; }
                   1256:  window  { background-color: white; }
                   1257: </pre>
                   1258:     <p>Using style rules from an external file is different because
                   1259:     you have to specify some way for the style rule to associate
                   1260:     itself with the appropriate tags in the XUL file. CSS provides
                   1261:     a rich collection of selectors, which bind style data to
                   1262:     elements. In this case, where you have two separate elements
                   1263:     that need to pick up rules, the <tt>id</tt> attribute on the
                   1264:     XUL element is used to bind a unique element to an external
                   1265:     style rule and the other style rule is bound by referring to
                   1266:     the XUL element directly. <a href="#77030">Example 2-8</a>
                   1267:     includes the selectors for the two elements, and <a href=
                   1268:     "#77032">Example 2-9</a> shows the updated XUL that uses
                   1269:     <i>xfly.css</i>.</p>
                   1270:     <p><i>Example 2-9: <a name="77032"></a></i> <i>XUL using
                   1271:     external style data</i></p>
                   1272: <pre>
                   1273:  &lt;?xml version="1.0"?&gt;
1.1       david    1274:  &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;
                   1275:  &lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;
                   1276:  &lt;!DOCTYPE window&gt;
                   1277:  &lt;window title="Hello xFly"
1.14      petejc   1278:    xmlns:html="<a href=
                   1279: "http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
                   1280:    xmlns="<a href=
                   1281: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
1.1       david    1282:    width="300"
                   1283:    height="215"
                   1284:    onload="centerWindowOnScreen( )"&gt;
                   1285:   &lt;script type="application/x-javascript"
                   1286:    src="chrome://global/content/dialogOverlay.js" /&gt;
1.14      petejc   1287:   &lt;vbox align="left" id="vb"&lt;/td&gt;&gt;
1.1       david    1288:    &lt;label id="xlabel"
                   1289:        value="Hello, Welcome to the xFly" /&gt;
1.14      petejc   1290:    &lt;image src="<a href=
                   1291: "http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</a>" /&gt;
1.1       david    1292:    &lt;button label="hello xFly" oncommand="alert('hello.');" /&gt;
                   1293:   &lt;/vbox&gt;
1.14      petejc   1294:  &lt;/window&gt;
                   1295: </pre>
                   1296:     <p>Note the extra stylesheet import statement at the top and
                   1297:     the use of the new <tt>id</tt> attribute on the label. When you
                   1298:     register the new files in your package with Mozilla, the
                   1299:     <i>xfly</i> directory in that stylesheet processing instruction
                   1300:     will point into your application directory structure (at the
                   1301:     <i>skin</i> subdirectory, and at a file named after the
                   1302:     directory itself, <i>xfly.css</i>). The label will pick up the
                   1303:     style information in the file that was previously defined
                   1304:     directly in its <tt>style</tt> attribute.</p>
                   1305:     <h4><a name="77077"></a> The xFly script file</h4>
                   1306:     <p>The next step is to take 
                   1307:     <!--INDEX xfly.js file;JavaScript:xfly.js file;packages:xfly.js file -->
                   1308:     the scripting portion, as simple as it is, out of the XUL file
                   1309:     and put it into an external JavaScript file. <a href=
                   1310:     "#77034">Example 2-10</a> shows a XUL file that gets a function
                   1311:     for the button from an external script file, given here as
1.20      brian    1312:     <i>xfly.js</i>. </p>
                   1313:     <p>Example 2-10<a name="77034"></a> <i>XUL using
1.14      petejc   1314:     an external script</i></p>
                   1315: <pre>
                   1316:  &lt;?xml version="1.0"?&gt;
1.1       david    1317:  &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;
                   1318:  &lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;
                   1319:  &lt;!DOCTYPE window&gt;
                   1320:  &lt;window title="Hello xFly"
1.14      petejc   1321:    xmlns:html="<a href=
                   1322: "http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
                   1323:    xmlns="<a href=
                   1324: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
1.1       david    1325:    width="300"
                   1326:    height="215"
                   1327:    onload="centerWindowOnScreen( )"&gt;
                   1328:  &lt;script type="application/x-javascript"
                   1329:    src="chrome://global/content/dialogOverlay.js" /&gt;
1.16      brian    1330:  &lt;script type="application/x-javascript"
1.1       david    1331:    src="chrome://xfly/content/xfly.js" /&gt;
                   1332:   &lt;vbox align="left" id="vb"&gt;
                   1333:    &lt;label id="xlabel"
                   1334:        value="Hello, Welcome to the xFly" /&gt;
1.14      petejc   1335:    &lt;image src="<a href=
                   1336: "http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</a>" /&gt;
1.1       david    1337:    &lt;button label="hello xFly" oncommand="greet( );" /&gt;
                   1338:   &lt;/vbox&gt;
1.14      petejc   1339:  &lt;/window&gt;
                   1340: </pre>
                   1341:     <p>Note that the function <tt>greet( )</tt> is used to name the
                   1342:     action that is performed when the button is clicked. The
                   1343:     <tt>greet( )</tt> function is now defined in the <i>xfly.js</i>
                   1344:     file that the XUL file picks up with the script import
                   1345:     statement:</p>
                   1346: <pre>
                   1347: &lt;script type="application/x-javascript"
                   1348: src="chrome://xfly/content/xfly.js" /&gt;
                   1349: </pre>
                   1350:     <p><a href="#77036">Example 2-11</a> contains all of the code
                   1351:     needed for the <i>xfly.js</i> file. Example 2-11<a name=
                   1352:     "77036"></a> <i>The contents of the xfly.js file</i></p>
                   1353: <pre>
                   1354:  function greet( ) {
1.1       david    1355:    alert("Hello World");
1.14      petejc   1356:  }
                   1357: </pre>
                   1358:     <p>Save <i>xfly.js</i> in the <i>content</i> subdirectory of
                   1359:     the xFly application (<i>chrome/xfly/content/</i>). The script
                   1360:     import statement above uses the <i>chrome://</i> URL to locate
                   1361:     scripts from directories that were registered with Mozilla.</p>
                   1362:     <h4><a name="77078"></a> The xFly DTD</h4>
                   1363:     <p>The final step in a basic 
                   1364:     <!--INDEX xfly.dtd file;DTD:xfly.dtd file --> application setup
                   1365:     is to generalize parts of the interface that are written in a
                   1366:     particular language, such as English. When you create a
                   1367:     <i>locale</i> subdirectory for your package and place a DTD
                   1368:     file that contains the English strings in the user interface,
                   1369:     you can refer to and load that DTD just as you do with the CSS
                   1370:     and script files.</p>
                   1371:     <p>For example, to localize the text of the label and button
                   1372:     elements in the "hello xFly" example, you can use a special
                   1373:     syntax to tell Mozilla to use an entity rather than a string.
                   1374:     Because that entity is defined in <i>xfly.dtd</i> and located
                   1375:     in the locale subdirectory, it can easily be swapped for an
                   1376:     entity from a different language pack when the user switches
                   1377:     languages in Mozilla.</p>
                   1378:     <p>Once again, the external file you create can be very simple.
                   1379:     <a href="#77038">Example 2-12</a> contains the code needed for
                   1380:     the <i>xfly.dtd</i> file, which you create and save in the
                   1381:     <i>locale</i> subdirectory. Example 2-12<a name="77038"></a>
                   1382:     <i>The contents of the xfly.dtd file</i></p>
                   1383: <pre>
                   1384:  &lt;!ENTITY label.val       "Hello, Welcome to the xFly " &gt;
                   1385:  &lt;!ENTITY btn.lbl         "hello xFly " &gt;
                   1386: </pre>
                   1387:     <p>The updated XUL file that uses this external DTD, then,
                   1388:     appears in <a href="#77040">Example 2-13</a>. Once you have
                   1389:     made the final changes in the XUL to refer to the external
                   1390:     files you've created, save the code in <a href="#77040">Example
                   1391:     2-13</a> as <i>xfly.xul</i> in the <i>chrome/xfly/content/</i>
                   1392:     directory. Example 2-13<a name="77040"></a> <i>XUL using an
                   1393:     external DTD file</i></p>
                   1394: <pre>
                   1395:  &lt;?xml version="1.0"?&gt;
1.1       david    1396:  &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;
                   1397:  &lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;
                   1398:  &lt;!DOCTYPE window SYSTEM "chrome://xfly/locale/xfly.dtd" &gt;
                   1399:  &lt;window title="Hello xFly"
1.14      petejc   1400:    xmlns:html="<a href=
                   1401: "http://www.w3.org/1999/xhtml">http://www.w3.org/1999/xhtml</a>"
                   1402:    xmlns="<a href=
                   1403: "http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul</a>"
1.1       david    1404:    width="300"
                   1405:    height="215"
                   1406:    onload="centerWindowOnScreen( )"&gt;
                   1407:  &lt;script type="application/x-javascript"
                   1408:    src="chrome://global/content/dialogOverlay.js" /&gt;
                   1409:  &lt;script type="application/x-javascript"
                   1410:    src="chrome://xfly/content/xfly.js" /&gt;
                   1411:   &lt;vbox align="left" id="vb"&gt;
                   1412:    &lt;label id="xlabel"
1.17      brian    1413:        value="&amp;label.val;" /&gt;
1.14      petejc   1414:    &lt;image src="<a href=
                   1415: "http://books.mozdev.org/xfly.gif">http://books.mozdev.org/xfly.gif</a>" /&gt;
1.17      brian    1416:    &lt;button label="&amp;btn.lbl;" oncommand="greet( );" /&gt;
1.1       david    1417:   &lt;/vbox&gt;
1.14      petejc   1418:  &lt;/window&gt;
                   1419: </pre>
                   1420:     <p>Like the CSS and script file imports, the updated
                   1421:     <tt>DOCTYPE</tt> definition at the top of the file tells
                   1422:     Mozilla to load additional entities as part of the xFly
                   1423:     package. Those entities-the English strings that display in the
                   1424:     user interface-are defined so they can be localized or
                   1425:     internationalized without affecting the application's
                   1426:     structure.</p>
                   1427:     <p>All three of these imports use the <i>chrome://</i> URL to
                   1428:     refer to resources that are internal to the xFly package. These
                   1429:     type of URLs can also refer to resources elsewhere in Mozilla,
                   1430:     such as image resources, strings that have already been defined
                   1431:     in entities, and functions from scripts such as
                   1432:     <tt>centerWindowOnScreen( )</tt>.</p>
                   1433:     <p>When you finish setting things up in the package
                   1434:     directories, you should have a structure that looks like the
                   1435:     tree structure in <a href="#77042">Example 2-14</a>. Example
                   1436:     2-14<a name="77042"></a> <i>Tree structure of a completed
                   1437:     sample xFly package</i></p>
                   1438: <pre>
                   1439:  chrome/
1.1       david    1440:         xfly/
                   1441:             content/
                   1442:                    xfly.xul
                   1443:                    xfly.js
                   1444:                    contents.rdf
1.17      brian    1445:             locale/en-US/
1.1       david    1446:                    xfly.dtd
                   1447:                    contents.rdf
                   1448:             skin/
                   1449:                    xfly.css
1.14      petejc   1450:                    contents.rdf
                   1451: </pre>
                   1452:     <h3><a name="77079"></a> Registering a Package</h3>
                   1453:     <p>Registering packages in Mozilla 
                   1454:     <!--INDEX packages:registration;registration:packages --> can
                   1455:     be confusing at first, so don't worry about understanding
                   1456:     everything at this point. Later chapters provide more detailed
                   1457:     information about packaging and registration, and you can
                   1458:     always copy the examples given here to install your own
                   1459:     application. In general, to make your package registerable,
                   1460:     create manifests that describe your package in terms that
                   1461:     Mozilla can understand.</p>
                   1462:     <p>Although it's customary to make registration a part of the
                   1463:     installation process by using the XPInstall API and
                   1464:     installation 
                   1465:     <!--INDEX XPInstall:registration and;registration:XPInstall API -->
                   1466:     scripts, you need a simple way to register the xFly application
                   1467:     so you can see your work and test it as it develops. For this
                   1468:     purpose, hacking the <i>installed-chrome.txt</i> file living 
                   1469:     <!--INDEX installed-chrome.txt file --> in Mozilla's
                   1470:     <i>chrome</i> directory will do.</p>
                   1471:     <p>The <i>installed-chrome.txt</i> file is a list of packages
                   1472:     and package parts that Mozilla should find and register on
                   1473:     start up. When you add entries to this file, you point to your
                   1474:     package and tell Mozilla to register that package when it
                   1475:     starts up.</p>
                   1476:     <p>Append the entries in <a href="#77044">Example 2-15</a> to
                   1477:     the bottom of the <i>installed-chrome.txt</i> file in the main
                   1478:     chrome directory. Example 2-15<a name="77044"></a> <i>Additions
                   1479:     to the installed-chrome.txt file</i></p>
                   1480: <pre>
1.18      brian    1481: content,install,url,resource:/chrome/xfly/content/
1.1       david    1482: skin,install,url,resource:/chrome/xfly/skin/
1.18      brian    1483: locale,install,url,resource:/chrome/xfly/locale/en-US/
1.14      petejc   1484: </pre>
                   1485:     <p>When Mozilla starts up, it looks for the package manifests,
                   1486:     reads them, and registers the xFly package.</p>
                   1487:     <p>When others install your application and use it on their
                   1488:     machines (but do not use the hack to
                   1489:     <i>installed-chrome.txt</i>), you can provide them with a
                   1490:     JavaScript installation file that downloads and registers your
                   1491:     package from a web page. See <a href="ch06.html#15291">Chapter
                   1492:     6</a> for more information about these installation files and
                   1493:     the XPInstall technology they are based upon.</p>
                   1494:     <h2><a name="77080"></a> Launching the Application</h2>
                   1495:     <p>Once your package is registered, you can use these startup
                   1496:     options to access your package directly.<a name=
                   1497:     "77081"></a></p>
                   1498:     <h4><a name="77082"></a> Windows launch</h4>
                   1499:     <p>In the Mozilla install directory, launch xFly at 
                   1500:     <!--INDEX xFly:Windows launch;Windows:xFly launch --> the
                   1501:     command prompt with:</p>
                   1502: <pre>
                   1503: mozilla -chrome chrome://xfly/content/
                   1504: </pre>
                   1505:     <p>You can also launch xFly from a shortcut on your desktop by
                   1506:     right-clicking on the existing Mozilla icon and selecting
                   1507:     Properties. In the Target area of the Properties box, add the
                   1508:     following text at the end of the line:</p>
                   1509: <pre>
                   1510: -chrome chrome://xfly/content/
                   1511: </pre>
                   1512:     <p><a href="#77012">Figure 2-6</a> shows what the new
                   1513:     properties box should look like.</p>
                   1514:     <div class="c7">
                   1515:       <img src="foo.gif">
                   1516:     </div>
                   1517:     <p><i>Figure 2-6: <a name="77012"></a></i> <i>Modified shortcut
                   1518:     properties</i></p>
                   1519:     <h4><a name="77083"></a> Unix launch</h4>
                   1520:     <p>In the Mozilla install directory, launch xFly 
                   1521:     <!--INDEX xFly:Unix launch;Unix:xFly launch --> with:</p>
                   1522: <pre>
                   1523: ./mozilla -chrome chrome://xfly/content/
                   1524: </pre>
                   1525:     <h4><a name="77084"></a> Macintosh launch</h4>
                   1526:     <p>Start xFly by creating a text file on your desktop 
                   1527:     <!--INDEX xFly:Macintosh launch;Macintosh:application launch -->
                   1528:     with the following content:</p>
                   1529: <pre>
                   1530: -chrome chrome://xfly/content/
                   1531: </pre>
                   1532:     <p>You can either drag this text file onto your Mozilla icon to
                   1533:     launch the application or set the text file's creator type to
                   1534:     <tt>MOZZ</tt>. If you change the creator type, you should be
                   1535:     able to double-click on the text file to launch Mozilla.</p>
                   1536:     <p>Once you register your application, you are free to continue
                   1537:     developing it in the various component subdirectories and
                   1538:     relaunching it as it progresses. You can add new XUL files in
                   1539:     the <i>content</i> directory, for example, that are invoked
                   1540:     from buttons using <tt>window.openDialog( )</tt> event
                   1541:     handlers.</p>
                   1542:     <p>You can add new widgets to <i>xfly.xul</i>, add new styles
                   1543:     to <i>xfly.css</i> that apply to the XUL, add new functions to
                   1544:     <i>xfly.js</i>, or use existing functions in the Mozilla source
                   1545:     code that you can find new ways to use in your own
                   1546:     application.</p>
                   1547:     <p>The steps described in this chapter-creating a basic XUL
                   1548:     file, adding features, displaying that XUL file as a standalone
                   1549:     window, organizing the code into separate files and a package
                   1550:     structure, and registering and launching that package-are the
                   1551:     basic building blocks of all Mozilla applications. When you get
                   1552:     a feel for what's going on here, you'll be able to quickly
                   1553:     understand and use the topics described in the rest of the
                   1554:     book.</p>
                   1555:     <hr>
                   1556:     <hr>
                   1557:     <a name="260"></a><a href="#b260">[Back]</a> <a name=
                   1558:     "77047"></a> Unfortunately, no good reference exists for the
                   1559:     functions defined in the various scripts files you can import.
                   1560:     The functions and their locations within the files continue to
                   1561:     change, so finding and using the right ones is sometimes a
                   1562:     matter of luck, sometimes a matter of whom you know, and often
                   1563:     a matter of testing, determination, and patience. 
                   1564:     <hr>
                   1565:     <br>
                   1566:     <br>
                   1567:     File a <a href=
                   1568:     "http://mozdev.org/bugs/enter_bug.cgi?product=books">Bug</a>
                   1569:     for chapter 2. <!-- ?php require(NOTES); ? -->
1.21    ! cdn      1570:     <?php $hide_text_control=1; $post_to_list=NO; $author='reviewers@mozdev.org'; $target_page='ch02'; require(NOTES); ?>

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