File:  [mozdev] / books / www / chapters / ch02.html
Revision 1.26: download - view: text, annotated - select for diffs - revision graph
Fri Apr 4 16:27:40 2003 UTC (16 years, 8 months ago) by cdn
Branches: MAIN
CVS tags: HEAD
ahem

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

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