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

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

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