File:  [mozdev] / books / www / docbook / ch02.xml
Revision 1.5: download - view: text, annotated - select for diffs - revision graph
Wed Apr 16 11:54:27 2003 UTC (16 years, 7 months ago) by halter
Branches: MAIN
CVS tags: HEAD
replaced all occurences of:
        <graphic align="center" fileref="figs/U2192.gif"/>
with:
        &gt;

should fix: http://mozdev.org/bugs/show_bug.cgi?id=3557

    1: <chapter label="2" id="mozilla-CHP-2">
    2: 
    3: <title>Getting Started</title>
    4: 
    5: 
    6: <para>To help you start creating applications as quickly as possible, this
    7: chapter presents two "Hello World"
    8: examples that demonstrate the beginning stages of Mozilla application
    9: development.
   10: </para>
   11: 
   12: <para>The first example is a simple XUL file that is loaded into the
   13: browser window. This example is then expanded on by adding additional
   14: features to the XUL file, such as imported stylesheets and JavaScript
   15: functions. The second "Hello World"
   16: example shows how to turn files like these into packages, which are
   17: the modular, bundled sets of files that fit together to make Mozilla
   18: applications or new modules for the Mozilla browser.
   19: </para>
   20: 
   21: <para>These examples provide a context for discussing the development of
   22: Mozilla applications. The first example focuses on creating and
   23: editing the basic file types, and the second focuses on the
   24: organization and distribution of applications on the Mozilla
   25: platform.
   26: </para>
   27: 
   28: 
   29: <sect1 role="" id="mozilla-CHP-2-SECT-1" label="2.1">
   30: <title>Simple XUL Example</title>
   31: 
   32: <para>Like all good "Hello World"
   33: applications, <indexterm id="IXT-2-356"><primary>Hello World XUL
   34: example</primary></indexterm><indexterm id="IXT-2-357"><primary>XUL (XML-based
   35: User-interface Language)</primary><secondary>Hello World
   36: example</secondary></indexterm><link linkend="mozilla-CHP-2-EX-1">Example 2-1</link> shows one
   37: of the simplest possible examples of XUL. Although it is small, it
   38: demonstrates some important aspects of XUL programming, including the
   39: use of event handlers to add behavior and the use of a
   40: <literal>box</literal> to lay out elements properly within the
   41: window. This example also provides a context for discussing more
   42: general features of the language, such as the file format, the
   43: namespace, and some XUL programming conventions.
   44: </para>
   45: 
   46: <example id="mozilla-CHP-2-EX-1" label="2-1">
   47: <title>Hello xFly </title>
   48: <programlisting>&lt;?xml version="1.0"?&gt;
   49: &lt;!-- Sample XUL file --&gt;
   50: &lt;window xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;
   51: &lt;box align="center"&gt;
   52:   &lt;button label="hello xFly" onclick="alert('Hello World');" /&gt;
   53: &lt;/box&gt;
   54: &lt;/window&gt;</programlisting>
   55: </example>
   56: 
   57: <para>Use your text editor to save the code in <link linkend="mozilla-CHP-2-EX-1">Example 2-1</link>
   58: in a file called <filename>hello.xul</filename> and then load the
   59: file in Mozilla (you can do this by using File &gt;
   60: Open File from the browser window and browsing to where you saved the
   61: file). You should see a button in the upper-left corner of the
   62: browser window that brings up an alert box when clicked. <link linkend="mozilla-CHP-2-FIG-1">Figure 2-1</link> shows an example of the alert pop-up window
   63: that appears.
   64: </para>
   65: 
   66: <figure id="mozilla-CHP-2-FIG-1" label="2-1">
   67: <title>The first Hello xFly example</title>
   68: <graphic fileref="figs/moz_0201.png"/></figure>
   69: 
   70: <para>The next few sections describe this sample file in more detail. The
   71: covered topics include the file itself, the syntax of the markup, XUL
   72: namespaces, and the basic layout of a XUL file.
   73: </para>
   74: 
   75: <sidebar id="mozilla-CHP-2-SIDEBAR-1">
   76: <title>The xFly Examples</title>
   77: 
   78: <para>The best way to understand the possible uses of the Mozilla framework
   79: is to look more closely at a number of various existing applications.
   80: This book highlights several Mozilla development projects, such as
   81: ChatZilla and JSLib, as examples of how some people have already
   82: started using Mozilla's XPFE technologies.
   83: </para>
   84: 
   85: <para>Along with these applications, you'll note the use
   86: of the name "xFly" in many examples
   87: in this chapter and elsewhere in this book. The xFly examples are
   88: used throughout <link linkend="mozilla-CHP-2">Chapter 2</link> to <link linkend="mozilla-CHP-6">Chapter 6</link> to show how to create and package a simple
   89: Mozilla application. An installable version of the complete xFly application can be found at 
   90: <systemitem role="url">http://xfly.mozdev.org</systemitem>.
   91: </para>
   92: 
   93: <para>This simple application is useful because it provides a place to
   94: start exploring the new information that you will learn about in this
   95: book. As you read more about XUL, CSS, JavaScript, and the other
   96: parts of Mozilla's development framework, you can
   97: create and edit the xFly files to see how these technologies work in
   98: practice.
   99: </para>
  100: </sidebar>
  101: 
  102: </sect1>
  103: 
  104: <sect1 role="" id="mozilla-CHP-2-SECT-2" label="2.2">
  105: <title>Basic XUL Concepts</title>
  106: 
  107: <para>You have already seen many of XUL's basic features
  108: at work. When you load the example in the previous example, the
  109: browser identifies it as a XUL file, parses the data, creates a new
  110: window and draws the button widget, and executes the function
  111: you've defined when the button is clicked.
  112: </para>
  113: 
  114: <para>These activities are part of the basic and often transparent
  115: interaction between your application files and Mozilla. However, the
  116: format of your XUL files, their syntax and namespace, the XUL layout,
  117: and the windowing system are all basic to successful XUL programming.
  118: </para>
  119: 
  120: <sect2 role="" id="mozilla-CHP-2-SECT-2.1" label="2.2.1">
  121: <title>The XUL File Format</title>
  122: 
  123: <para>A XUL file is a simple text file <indexterm id="IXT-2-358"><primary>XUL
  124: files</primary></indexterm><indexterm id="IXT-2-359"><primary>files</primary><secondary>XUL
  125: files</secondary></indexterm>that contains proper XML syntax and has
  126: a <filename>.xul</filename> file extension. Mozilla expects to draw
  127: UI widgets when it encounters a file with a <filename>.xul</filename>
  128: extension or when it encounters the XUL namespace in other markup
  129: files that it recognizes, including HTML and XML.
  130: </para>
  131: 
  132: <para>The MIME type registered <indexterm id="IXT-2-360"><primary>MIME type, XUL
  133: files</primary></indexterm><indexterm id="IXT-2-361"><primary>XUL
  134: files</primary><secondary>MIME type
  135: registered</secondary></indexterm>for XUL files is
  136: <filename>application/vnd.mozilla.xul+xml</filename>. When editing
  137: and using XUL files locally, you shouldn't need to
  138: worry about setting this on your computer; however, sometimes you may
  139: need to set the MIME type, such as when you host XUL files on a
  140: server. <link linkend="mozilla-CHP-12">Chapter 12</link> provides additional information
  141: about how you can set the correct file type for your system.
  142: </para>
  143: 
  144: </sect2>
  145: <sect2 role="" id="mozilla-CHP-2-SECT-2.2" label="2.2.2">
  146: <title>Conventions</title>
  147: 
  148: <para>XUL has to follow certain <indexterm id="IXT-2-362"><primary>XUL (XML-based
  149: User-interface
  150: Language)</primary><secondary>conventions</secondary></indexterm><indexterm id="IXT-2-363"><primary>conventions,
  151: XUL</primary></indexterm>conventions (as does XHTML or any other
  152: XML-based file) in order to be valid. Mozilla generates an error when
  153: it encounters an invalid XUL file.
  154: </para>
  155: 
  156: <para>The first thing required in a XUL document is the XML declaration.</para>
  157: 
  158: <programlisting>&lt;?xml version="1.0"?&gt;</programlisting>
  159: 
  160: <para>Any comments used to introduce
  161: <indexterm id="IXT-2-364"><primary>comments</primary><secondary>XUL</secondary></indexterm><indexterm id="IXT-2-365"><primary>XUL
  162: (XML-based User-interface
  163: Language)</primary><secondary>comments</secondary></indexterm>your
  164: file can begin on the line after the declaration. Comments in XUL
  165: follow the same format used in HTML and XML, delimited by
  166: <literal>&lt;!--</literal> and <literal>--&gt;</literal>.
  167: </para>
  168: 
  169: <para>All tag sets must be closed. Empty <indexterm id="IXT-2-366"><primary>tags,
  170: XUL</primary></indexterm><indexterm id="IXT-2-367"><primary>XUL (XML-based
  171: User-interface
  172: Language)</primary><secondary>tags</secondary></indexterm>tags are
  173: allowed for some elements, such as the
  174: <literal>&lt;label&gt;</literal> element, that are used without
  175: nested elements or content. Note that a trailing slash at the end of
  176: the tag is required to denote an empty element.
  177: </para>
  178: 
  179: <programlisting>&lt;label value="Getting Started" /&gt;</programlisting>
  180: 
  181: <para>Another thing to remember is <indexterm id="IXT-2-368"><primary>case-sensitivity,
  182: XUL</primary></indexterm><indexterm id="IXT-2-369"><primary>XUL (XML-based
  183: User-interface
  184: Language)</primary><secondary>case-sensitivity</secondary></indexterm>that
  185: XUL is case-sensitive. Closing a XUL
  186: <literal>&lt;window&gt;</literal> tag with
  187: <literal>&lt;/Window&gt;</literal> renders it invalid.
  188: </para>
  189: 
  190: <para>These conventions ensure that the rendering engine can parse the XUL
  191: file successfully and display the elements defined there. Mozilla
  192: does not validate XML files, such as XUL, and it does not resolve
  193: externally parsed entities, but it does check for document
  194: well-formedness.
  195: </para>
  196: 
  197: <para>Following the XML specification, Mozilla ignores well-formed tags
  198: that it does not recognize, which can give your applications extra
  199: flexibility, particularly as you begin to use technologies such as
  200: XBL. But it can also make debugging a little more difficult, as when
  201: you create an element named <literal>&lt;botton&gt;</literal> and
  202: don't see why your XUL button
  203: doesn't have the typical borders or
  204: three-dimensional style.
  205: </para>
  206: 
  207: <para>A good practice to follow when creating XUL files is to use comments,
  208: copious whitespace, indentations (but not tabbed indentations where
  209: you can avoid them), and XUL widgets you are familiar with.
  210: </para>
  211: 
  212: </sect2>
  213: <sect2 role="" id="mozilla-CHP-2-SECT-2.3" label="2.2.3">
  214: <title>The XUL Namespace</title>
  215: 
  216: <para>Like other markup
  217: <indexterm id="IXT-2-370"><primary>namespaces</primary><secondary>XUL</secondary></indexterm><indexterm id="IXT-2-371"><primary>XUL
  218: (XML-based User-interface
  219: Language)</primary><secondary>namespace</secondary></indexterm>vocabularies,
  220: XUL uses a namespace declaration to define the particular elements
  221: that may be included in a valid file. <link linkend="mozilla-CHP-2-EX-2">Example 2-2</link>
  222: shows a sample of the required namespace declaration. The namespace
  223: is an attribute of the root <literal>window</literal> element. The
  224: lack of any suffix on the XML namespace declaration (i.e.,
  225: <literal>xmlns:xul</literal>) indicates that XUL is the default
  226: namespace for this file.
  227: </para>
  228: 
  229: <example id="mozilla-CHP-2-EX-2" label="2-2">
  230: <title>The XUL namespace declaration </title>
  231: <programlisting>&lt;window
  232:   xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;
  233:   &lt;description&gt;Illustrating the XUL namespace&lt;/description&gt;
  234: &lt;/window&gt;</programlisting>
  235: </example>
  236: 
  237: <para>If you want to include XUL content in documents that use other types
  238: of markup, you need to declare more than one namespace. Common
  239: namespace declarations for getting other language elements into your
  240: code include HTML and RDF, but you can invent your own as well. If
  241: you wanted to put the button from <link linkend="mozilla-CHP-2-EX-1">Example 2-1</link> into a
  242: vanilla XML file, for example, you could place it into an XML
  243: document by using the <literal>xmlns:xul</literal> attribute, as
  244: shown in <link linkend="mozilla-CHP-2-EX-3">Example 2-3</link>.
  245: </para>
  246: 
  247: <example id="mozilla-CHP-2-EX-3" label="2-3">
  248: <title>Mixed namespaces in an XML document </title>
  249: <programlisting>&lt;flies:flies 
  250:   xmlns:flies="http://www.flies.com/come.fly.with.me.xml#" 
  251:   xmlns:html="http://www.w3.org/1999/xhtml"
  252:   xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;
  253:   &lt;flies:wings&gt;
  254:     &lt;xul:box align="center"&gt;
  255:       &lt;xul:button label="hello xFly" onclick="alert('hello.');" /&gt;
  256:     &lt;/xul:box&gt;
  257:     &lt;html:img src="wings.jpg" /&gt;
  258:   &lt;/flies:wings&gt;
  259: &lt;/flies:flies&gt;</programlisting>
  260: </example>
  261: 
  262: <para>This file has three types of content: XUL, HTML, and customized
  263: markup called <literal>flies</literal>. When you use mixed
  264: namespaces, you have to prefix the XUL elements with
  265: <literal>xul</literal>: to distinguish them from markup in other
  266: namespaces, as with the <literal>xul:box</literal> and
  267: <literal>xul:button</literal> shown in <link linkend="mozilla-CHP-2-EX-3">Example 2-3</link>.
  268: </para>
  269: 
  270: </sect2>
  271: <sect2 role="" id="mozilla-CHP-2-SECT-2.4" label="2.2.4">
  272: <title>Basic XUL Layout</title>
  273: 
  274: <para><link linkend="mozilla-CHP-2-EX-1">Example 2-1</link> features <indexterm id="IXT-2-372"><primary>XUL
  275: (XML-based User-interface
  276: Language)</primary><secondary>elements</secondary></indexterm>some
  277: very common XUL elements. In this section, each element is dissected
  278: to show what it does and how it interacts with other elements. The
  279: <literal>&lt;window&gt;</literal> element is the root of individual
  280: primary XUL documents (in contrast to dialogs that pop up from
  281: <indexterm id="IXT-2-373"><primary>dialog element, XUL</primary></indexterm>windows,
  282: which can use <literal>&lt;dialog&gt;</literal> as the root, and XUL
  283: documents loaded within other XUL containers, which can use
  284: <literal>&lt;page&gt;</literal>).
  285: </para>
  286: 
  287: <para>As in HTML, the root element defines the document into which all
  288: elements are drawn, but in XUL, that document is a piece of an
  289: application interface and not a web page. We'll have
  290: more to say about the window and some of its features in the second
  291: example.
  292: </para>
  293: 
  294: <para>A <literal>&lt;box&gt;</literal> element that <indexterm id="IXT-2-374"><primary>box
  295: element, XUL</primary></indexterm><indexterm id="IXT-2-375"><primary>button element,
  296: XUL</primary></indexterm>contains a <literal>&lt;button&gt;</literal>
  297: is inside the window in <link linkend="mozilla-CHP-2-EX-1">Example 2-1</link>. Although you
  298: can use attributes on the window element to lay out and position
  299: window children, it's never a bad idea to use the
  300: <literal>&lt;box&gt;</literal> as a container, particularly when you
  301: add new layout to your document, such as rows of buttons, grids,
  302: tabs, or other elements that need to be arranged precisely within the
  303: space of the window. The <literal>box</literal> is the basic element
  304: for layout in XUL.
  305: </para>
  306: 
  307: <para>The <literal>align</literal> attribute on the box specifies that the
  308: children do not stretch and center themselves in the middle of the
  309: available space. If the box was omitted and there were multiple
  310: children of the root window, they would be laid out vertically by
  311: default, one under the other. This setting can be overridden by
  312: adding the <literal>orient</literal> attribute to
  313: <literal>&lt;window&gt;</literal> and giving it a value of
  314: "horizontal."
  315: </para>
  316: 
  317: </sect2>
  318: <sect2 role="" id="mozilla-CHP-2-SECT-2.5" label="2.2.5">
  319: <title>Using XUL Windows</title>
  320: 
  321: <para>The foundation of an XPFE application is <indexterm id="IXT-2-376"><primary>XUL
  322: (XML-based User-interface
  323: Language)</primary><secondary>windows</secondary></indexterm><indexterm id="IXT-2-377"><primary>windows</primary><secondary>XUL</secondary></indexterm>a
  324: window. Each XUL document has to have at least one XUL
  325: <literal>&lt;window&gt;</literal> element, and it must be the root of
  326: the document -- the surrounding, outermost element in the XML
  327: document, set apart from the XML declaration itself and other
  328: processing "preambles." A basic
  329: window with no content looks like this:
  330: </para>
  331: 
  332: <programlisting>&lt;?xml version="1.0"?&gt;
  333: &lt;!DOCTYPE window&gt;
  334: &lt;window 
  335:     xmlns:html="http://www.w3.org/1999/xhtml"
  336:     xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;
  337: &lt;/window&gt;</programlisting>
  338: 
  339: <para>Commonly, an application has more than one window, with a number of
  340: dialogs and secondary windows. Each window is also
  341: <indexterm id="IXT-2-378"><primary>window element,
  342: XUL</primary></indexterm>contained within a
  343: <literal>&lt;window&gt;</literal> element (though recent additions to
  344: the XUL specification include the <literal>dialog</literal> and
  345: <literal>page</literal> elements, which are derived from
  346: <literal>window</literal> and can be used in its place as root
  347: elements in your XUL files).
  348: </para>
  349: 
  350: <para>As your application becomes more complex, you need a way to keep
  351: track of the windows and ensure that they can communicate with one
  352: another. In Mozilla, there is a way to do this by using
  353: <indexterm id="IXT-2-379"><primary>toOpenWindowByType( )
  354: function</primary></indexterm><indexterm id="IXT-2-380"><primary>functions</primary><secondary>toOpenWindowByType(
  355: )</secondary></indexterm>the <literal>type</literal> attribute
  356: identifier, which allows you to use special window-opening functions
  357: like <literal>toOpenWindowByType( )</literal> to manage particular
  358: window types.
  359: </para>
  360: 
  361: 
  362: 
  363: <tip id="ch02-4-fm2xml" role="ora">
  364: <para>As with any existing Mozilla functions referred to in this book, you
  365: can look up <literal>toOpenWindowByType</literal> by using the LXR
  366: web-based source code viewer, described in <link linkend="mozilla-APP-A">Appendix A</link> and available at <systemitem role="url">http://lxr.mozilla.org/</systemitem>.
  367: </para>
  368: </tip>
  369: 
  370: <sect3 role="" id="mozilla-CHP-2-SECT-2.5.1" label="2.2.5.1">
  371: <title>Window features</title>
  372: 
  373: <para>An <literal>id</literal> attribute is present on
  374: <indexterm id="IXT-2-381"><primary>XUL (XML-based User-interface
  375: Language)</primary><secondary>windows</secondary></indexterm><indexterm id="IXT-2-382"><primary>windows</primary><secondary>XML</secondary></indexterm>the
  376: <literal>&lt;window&gt;</literal> element. Using this
  377: <indexterm id="IXT-2-383"><primary>window element, XUL</primary><secondary>id
  378: attribute</secondary></indexterm>attribute is not necessary to run
  379: the windows system, but it is a good idea to give each window a
  380: unique identifier because it makes nodes easier to find from script
  381: (see the DOM method <literal>getElementByID</literal> in <link linkend="mozilla-CHP-5">Chapter 5</link> for information about how to get elements by
  382: identifier). This is how to set up an ID attribute:
  383: </para>
  384: 
  385: <programlisting>&lt;window 
  386:     xmlns:html="http://www.w3.org/1999/xhtml"
  387:     xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
  388:     id="xflyMain"&gt;</programlisting>
  389: 
  390: <para>Load event handlers such as <literal>onload</literal> and
  391: <literal>onunload</literal> are useful and <indexterm id="IXT-2-384"><primary>load
  392: event handlers, window element, XUL</primary></indexterm>necessary if
  393: you want to add behavior to a window, pass input to it, or manipulate
  394: its content depending on context:
  395: </para>
  396: 
  397: <programlisting>&lt;window 
  398:     xmlns:html="http://www.w3.org/1999/xhtml"
  399:     xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
  400:     id="xfly-main"
  401:     onload="startUp( )"
  402:     onunload="shutdown( )"
  403:     onclose="onClose( )"&gt;</programlisting>
  404: 
  405: <para>When you load a XUL file that begins in this way, the event handler
  406: attributes <literal>onload</literal> and <literal>onunload</literal>
  407: carry out the functions listed as values (<literal>startUp(
  408: )</literal> and <literal>shutdown( )</literal>). In addition, Mozilla
  409: provides an <literal>onclose</literal> event handler that intercepts
  410: the upcoming window closure to carry out any extra processing you
  411: need. The close event is fired before the <literal>unload</literal>
  412: event, so you can stop the window from closing in the
  413: <literal>onclose</literal> event handler if necessary. To stop window
  414: closure, the close event must return <filename>false</filename>.
  415: </para>
  416: 
  417: <para>Additional handlers are available for dialog windows. They are listed
  418: and their use is outlined in the section <link linkend="mozilla-CHP-3-SECT-2">Section 3.2</link> in <link linkend="mozilla-CHP-3">Chapter 3</link>. 
  419: </para>
  420: 
  421: </sect3>
  422: 
  423: <sect3 role="" id="mozilla-CHP-2-SECT-2.5.2" label="2.2.5.2">
  424: <title>Window properties</title>
  425: 
  426: <para>The window declaration is
  427: <indexterm id="IXT-2-385"><primary>windows</primary><secondary>XUL</secondary><tertiary>properties</tertiary></indexterm><indexterm id="IXT-2-386"><primary>properties</primary><secondary>windows,
  428: XUL</secondary></indexterm><indexterm id="IXT-2-387"><primary>XUL (XML-based
  429: User-interface
  430: Language)</primary><secondary>windows</secondary><tertiary>properties</tertiary></indexterm>expanding,
  431: but there is still plenty of room for more features. In addition to
  432: the <emphasis>attributes</emphasis> -- the event handlers, the ID,
  433: and the namespace that appear within the
  434: <literal>&lt;window&gt;</literal> tag itself -- a XUL window also
  435: has all of the properties of the DOM <literal>window</literal> object
  436: from HTML. These properties are listed below, along with additional
  437: properties for application specific tasks.
  438: </para>
  439: 
  440: <informaltable id="ch02-5-fm2xml">
  441: <tgroup cols="4">
  442: <colspec colnum="1" colname="col1"/>
  443: <colspec colnum="2" colname="col2"/>
  444: <colspec colnum="3" colname="col3"/>
  445: <colspec colnum="4" colname="col4"/>
  446: <thead>
  447: <row>
  448: <entry>
  449: <programlisting>Navigator</programlisting>
  450: </entry>
  451: <entry>
  452: <programlisting>Document</programlisting>
  453: </entry>
  454: <entry>
  455: <programlisting>window</programlisting>
  456: </entry>
  457: <entry>
  458: <programlisting>Parent</programlisting>
  459: </entry>
  460: </row>
  461: </thead>
  462: <tbody>
  463: <row>
  464: <entry>
  465: <programlisting>Top</programlisting>
  466: </entry>
  467: <entry>
  468: <programlisting>Scrollbars</programlisting>
  469: </entry>
  470: <entry>
  471: <programlisting>name</programlisting>
  472: </entry>
  473: <entry>
  474: <programlisting>ScrollX</programlisting>
  475: </entry>
  476: </row>
  477: <row>
  478: <entry>
  479: <programlisting>ScrollY</programlisting>
  480: </entry>
  481: <entry>
  482: <programlisting>ScrollTo</programlisting>
  483: </entry>
  484: <entry>
  485: <programlisting>scrollBy</programlisting>
  486: </entry>
  487: <entry>
  488: <programlisting>GetSelection</programlisting>
  489: </entry>
  490: </row>
  491: <row>
  492: <entry>
  493: <programlisting>ScrollByLines</programlisting>
  494: </entry>
  495: <entry>
  496: <programlisting>ScrollByPages</programlisting>
  497: </entry>
  498: <entry>
  499: <programlisting>Size
  500: ToContent</programlisting>
  501: </entry>
  502: <entry>
  503: <programlisting>Dump</programlisting>
  504: </entry>
  505: </row>
  506: <row>
  507: <entry>
  508: <programlisting>SetTimeout</programlisting>
  509: </entry>
  510: <entry>
  511: <programlisting>SetInterval</programlisting>
  512: </entry>
  513: <entry>
  514: <programlisting>Clear
  515: Timeout</programlisting>
  516: </entry>
  517: <entry>
  518: <programlisting>ClearInterval</programlisting>
  519: </entry>
  520: </row>
  521: <row>
  522: <entry>
  523: <programlisting>SetResizable</programlisting>
  524: </entry>
  525: <entry>
  526: <programlisting>CaptureEvents</programlisting>
  527: </entry>
  528: <entry>
  529: <programlisting>Release
  530: Events</programlisting>
  531: </entry>
  532: <entry>
  533: <programlisting>RouteEvent</programlisting>
  534: </entry>
  535: </row>
  536: <row>
  537: <entry>
  538: <programlisting>Enable
  539: External
  540: Capture</programlisting>
  541: </entry>
  542: <entry>
  543: <programlisting>DisableExternal
  544: Capture</programlisting>
  545: </entry>
  546: <entry>
  547: <programlisting>prompt</programlisting>
  548: </entry>
  549: <entry>
  550: <programlisting>Open</programlisting>
  551: </entry>
  552: </row>
  553: <row>
  554: <entry>
  555: <programlisting>OpenDialog</programlisting>
  556: </entry>
  557: <entry>
  558: <programlisting>Frames</programlisting>
  559: </entry>
  560: <entry>
  561: <programlisting>find</programlisting>
  562: </entry>
  563: <entry>
  564: <programlisting>self</programlisting>
  565: </entry>
  566: </row>
  567: <row>
  568: <entry>
  569: <programlisting>Screen</programlisting>
  570: </entry>
  571: <entry>
  572: <programlisting>History</programlisting>
  573: </entry>
  574: <entry>
  575: <programlisting>content</programlisting>
  576: </entry>
  577: <entry>
  578: <programlisting>Sidebar</programlisting>
  579: </entry>
  580: </row>
  581: <row>
  582: <entry>
  583: <programlisting>Menubar</programlisting>
  584: </entry>
  585: <entry>
  586: <programlisting>Toolbar</programlisting>
  587: </entry>
  588: <entry>
  589: <programlisting>Locationbar</programlisting>
  590: </entry>
  591: <entry>
  592: <programlisting>Personalbar</programlisting>
  593: </entry>
  594: </row>
  595: <row>
  596: <entry>
  597: <programlisting>Statusbar</programlisting>
  598: </entry>
  599: <entry>
  600: <programlisting>Directories</programlisting>
  601: </entry>
  602: <entry>
  603: <programlisting>closed</programlisting>
  604: </entry>
  605: <entry>
  606: <programlisting>Crypto</programlisting>
  607: </entry>
  608: </row>
  609: <row>
  610: <entry>
  611: <programlisting>pkcs11</programlisting>
  612: </entry>
  613: <entry>
  614: <programlisting>Controllers</programlisting>
  615: </entry>
  616: <entry>
  617: <programlisting>opener</programlisting>
  618: </entry>
  619: <entry>
  620: <programlisting>Status</programlisting>
  621: </entry>
  622: </row>
  623: <row>
  624: <entry>
  625: <programlisting>defaultStatus</programlisting>
  626: </entry>
  627: <entry>
  628: <programlisting>Location</programlisting>
  629: </entry>
  630: <entry>
  631: <programlisting>innerWidth</programlisting>
  632: </entry>
  633: <entry>
  634: <programlisting>InnerHeight</programlisting>
  635: </entry>
  636: </row>
  637: <row>
  638: <entry>
  639: <programlisting>outerWidth</programlisting>
  640: </entry>
  641: <entry>
  642: <programlisting>OuterHeight</programlisting>
  643: </entry>
  644: <entry>
  645: <programlisting>screenX</programlisting>
  646: </entry>
  647: <entry>
  648: <programlisting>ScreenY</programlisting>
  649: </entry>
  650: </row>
  651: <row>
  652: <entry>
  653: <programlisting>pageXOffset</programlisting>
  654: </entry>
  655: <entry>
  656: <programlisting>PageYOffset</programlisting>
  657: </entry>
  658: <entry>
  659: <programlisting>length</programlisting>
  660: </entry>
  661: <entry>
  662: <programlisting>FullScreen</programlisting>
  663: </entry>
  664: </row>
  665: <row>
  666: <entry>
  667: <programlisting>alert</programlisting>
  668: </entry>
  669: <entry>
  670: <programlisting>Confirm</programlisting>
  671: </entry>
  672: <entry>
  673: <programlisting>focus</programlisting>
  674: </entry>
  675: <entry>
  676: <programlisting>Blur</programlisting>
  677: </entry>
  678: </row>
  679: <row>
  680: <entry>
  681: <programlisting>back</programlisting>
  682: </entry>
  683: <entry>
  684: <programlisting>Forward</programlisting>
  685: </entry>
  686: <entry>
  687: <programlisting>home</programlisting>
  688: </entry>
  689: <entry>
  690: <programlisting>Stop</programlisting>
  691: </entry>
  692: </row>
  693: <row>
  694: <entry>
  695: <programlisting>print</programlisting>
  696: </entry>
  697: <entry>
  698: <programlisting>MoveTo</programlisting>
  699: </entry>
  700: <entry>
  701: <programlisting>moveBy</programlisting>
  702: </entry>
  703: <entry>
  704: <programlisting>ResizeTo</programlisting>
  705: </entry>
  706: </row>
  707: <row>
  708: <entry>
  709: <programlisting>resizeBy</programlisting>
  710: </entry>
  711: <entry>
  712: <programlisting>Scroll</programlisting>
  713: </entry>
  714: <entry>
  715: <programlisting>close</programlisting>
  716: </entry>
  717: <entry>
  718: <programlisting>UpdateCommands</programlisting>
  719: </entry>
  720: </row>
  721: <row>
  722: <entry>
  723: <programlisting>escape</programlisting>
  724: </entry>
  725: <entry>
  726: <programlisting>Unescape</programlisting>
  727: </entry>
  728: <entry>
  729: <programlisting>atob</programlisting>
  730: </entry>
  731: <entry>
  732: <programlisting>Btoa</programlisting>
  733: </entry>
  734: </row>
  735: <row>
  736: <entry>
  737: <programlisting>AddEvent
  738: Listener</programlisting>
  739: </entry>
  740: <entry>
  741: <programlisting>RemoveEvent
  742: Listener</programlisting>
  743: </entry>
  744: <entry>
  745: <programlisting>Dispatch
  746: Event</programlisting>
  747: </entry>
  748: <entry>
  749: <programlisting>GetComputed
  750: Style</programlisting>
  751: </entry>
  752: </row>
  753: </tbody>
  754: </tgroup>
  755: </informaltable>
  756: 
  757: <para>Special properties of the XUL window object include:</para>
  758: 
  759: <variablelist>
  760: <varlistentry><term>window.content</term>
  761: <listitem>
  762: <para>Using this property is a quick way <indexterm id="IXT-2-388"><primary>window.content
  763: property, window object</primary></indexterm>to access the content
  764: area of your window, if one exists. This property is useful only if
  765: your window uses one of the content elements, namely
  766: <literal>&lt;iframe&gt;</literal>,
  767: <literal>&lt;browser&gt;</literal>, and
  768: <literal>&lt;editor&gt;</literal>. Refer to the section <link linkend="mozilla-CHP-3-SECT-8">Section 3.8</link> in <link linkend="mozilla-CHP-3">Chapter 3</link> for a more detailed discussion. The
  769: <literal>content</literal> property is linked only to the frame you
  770: have explicitly declared as the primary area.
  771: </para>
  772: </listitem>
  773: </varlistentry>
  774: </variablelist>
  775: 
  776: <programlisting>&lt;browser type="content-primary" ...&gt;</programlisting>
  777: 
  778: <para>Subsequently, you can access and manipulate the content.</para>
  779: 
  780: <programlisting>window.content.focus( );</programlisting>
  781: 
  782: <variablelist>
  783: <varlistentry><term>window.sizeToContent( )</term>
  784: <listitem>
  785: <para>This property is used to ensure
  786: <indexterm id="IXT-2-389"><primary>window.sizeToContent( ) property, window
  787: object</primary></indexterm>intrinsic sizing, which is important in
  788: XUL application development, especially in dialog windows. Intrinsic
  789: sizing ensures that the window adapts and morphs to fit the content.
  790: This is preferable to constraining your window with a fixed width and
  791: height when the <literal>onload</literal> handler anticipates
  792: changeable content, depends on context, or takes input from another
  793: window. The colorpicker in the Mozilla Editor, for example, uses this
  794: function to make sure that the window displaying the chosen palette
  795: shrinks to fit that palette:
  796: </para>
  797: </listitem>
  798: </varlistentry>
  799: </variablelist>
  800: 
  801: <programlisting>function ChangePalette(palette)
  802: {
  803:   gDialog.ColorPicker.setAttribute("palettename", palette);
  804:   window.sizeToContent( );
  805: }</programlisting>
  806: 
  807: </sect3>
  808: 
  809: <sect3 role="" id="mozilla-CHP-2-SECT-2.5.3" label="2.2.5.3">
  810: <title>Interaction between windows</title>
  811: 
  812: <para>The <literal>nsIWindowMediator</literal> XPCOM component
  813: <indexterm id="IXT-2-390"><primary>nsIWindowMediator,
  814: XPCOM</primary></indexterm><indexterm id="IXT-2-391"><primary>XPCOM</primary><secondary>nsIWindowMediator</secondary></indexterm><indexterm id="IXT-2-392"><primary>windows</primary><secondary>XUL</secondary><tertiary>nsIWindowMeditor</tertiary></indexterm><indexterm id="IXT-2-393"><primary>XUL
  815: (XML-based User-interface
  816: Language)</primary><secondary>windows</secondary><tertiary>nsIWindowMediator</tertiary></indexterm>provides
  817: several routines for interacting with different windows. Though
  818: it's a little too early to discuss using a component
  819: like this in the Hello World examples, these routines include:
  820: </para>
  821: 
  822: <itemizedlist><listitem>
  823: <para>Getting the most recent window of a particular type</para>
  824: </listitem><listitem>
  825: <para>Enumerating all open windows</para>
  826: </listitem><listitem>
  827: <para>Registering and unregistering the window</para>
  828: </listitem><listitem>
  829: <para>Updating the window timestamp</para>
  830: </listitem><listitem>
  831: <para>Updating the window title</para>
  832: </listitem><listitem>
  833: <para>Setting the Z-order position</para>
  834: </listitem></itemizedlist>
  835: <para><link linkend="mozilla-CHP-8">Chapter 8</link> provides full details of how to
  836: understand and use XPCOM components.
  837: </para>
  838: 
  839: </sect3>
  840: 
  841: <sect3 role="" id="mozilla-CHP-2-SECT-2.5.4" label="2.2.5.4">
  842: <title>Window behavior</title>
  843: 
  844: <para>Mozilla supports the <indexterm id="IXT-2-394"><primary>XUL (XML-based
  845: User-interface
  846: Language)</primary><secondary>windows</secondary><tertiary>behaviors</tertiary></indexterm><indexterm id="IXT-2-395"><primary>windows</primary><secondary>XUL</secondary><tertiary>behaviors</tertiary></indexterm><indexterm id="IXT-2-396"><primary>window.open
  847: function
  848: (JavaScript)</primary></indexterm><indexterm id="IXT-2-397"><primary>functions</primary><secondary>JavaScript</secondary><tertiary>window.open</tertiary></indexterm><indexterm id="IXT-2-398"><primary>JavaScript</primary><secondary>functions</secondary><tertiary>window.open</tertiary></indexterm>standard
  849: <literal>window.open</literal> JavaScript function, which has its
  850: origins in the world of browser scripting and the launching of new
  851: browser windows. Mozilla extends the function to provide some
  852: features for application development. It also provides the
  853: <literal>window.openDialog</literal>
  854: <indexterm id="IXT-2-399"><primary>window.openDialog function,
  855: JavaScript</primary></indexterm><indexterm id="IXT-2-400"><primary>functions</primary><secondary>JavaScript</secondary><tertiary>window.OpenDialog</tertiary></indexterm><indexterm id="IXT-2-401"><primary>JavaScript</primary><secondary>functions</secondary><tertiary>window.openDialog</tertiary></indexterm>function
  856: for opening windows in the XPFE scripting environment. The latter
  857: function has become the more commonly used method to open a new XUL
  858: window, although the two are interchangeable.
  859: </para>
  860: 
  861: <para>The usage of <literal>window.open</literal> is:</para>
  862: 
  863: <programlisting>window.open (url, name, features);</programlisting>
  864: 
  865: <para><literal>window.openDialog</literal> extends this functionality with
  866: a new argument list passed to it, which is optional and can be any
  867: number of arguments as needed:
  868: </para>
  869: 
  870: <programlisting>window.openDialog (url, type, features, argument1, argument2);</programlisting>
  871: 
  872: <para>Here is a list of some of the features of a XUL window opened using
  873: <literal>window.openDialog</literal>:
  874: </para>
  875: 
  876: <variablelist>
  877: <varlistentry><term>close</term>
  878: <listitem>
  879: <para>The window can be created with or without a close widget.</para>
  880: </listitem>
  881: </varlistentry>
  882: 
  883: <varlistentry><term>chrome</term>
  884: <listitem>
  885: <para>The new window has to <indexterm id="IXT-2-402"><primary>chrome context, XUL
  886: windows</primary></indexterm><indexterm id="IXT-2-403"><primary>XUL (XML-based
  887: User-interface
  888: Language)</primary><secondary>windows</secondary><tertiary>chrome
  889: context</tertiary></indexterm><indexterm id="IXT-2-404"><primary>windows</primary><secondary>XUL</secondary><tertiary>chrome
  890: context</tertiary></indexterm>be treated as a window within the
  891: chrome context, rather than in the browser context. It gets its own
  892: top-level window. The window itself is the chrome URL passed to the
  893: function, and is not to be loaded in a browser window.
  894: </para>
  895: </listitem>
  896: </varlistentry>
  897: 
  898: <varlistentry><term>dependent</term>
  899: <listitem>
  900: <para>The new window belongs <indexterm id="IXT-2-405"><primary>dependence, XUL
  901: windows</primary></indexterm><indexterm id="IXT-2-406"><primary>windows</primary><secondary>XUL</secondary><tertiary>dependence</tertiary></indexterm><indexterm id="IXT-2-407"><primary>XUL
  902: (XML-based User-interface
  903: Language)</primary><secondary>windows</secondary><tertiary>dependence</tertiary></indexterm>to
  904: the calling window on operating systems that support this behavior.
  905: It "floats" on top of the opening
  906: window, and you can still access the parent window. It is minimized
  907: with its parent.
  908: </para>
  909: </listitem>
  910: </varlistentry>
  911: 
  912: <varlistentry><term>modal</term>
  913: <listitem>
  914: <para>The window will be run <indexterm id="IXT-2-408"><primary>modality, XUL
  915: windows</primary></indexterm><indexterm id="IXT-2-409"><primary>XUL (XML-based
  916: User-interface
  917: Language)</primary><secondary>windows</secondary><tertiary>modality</tertiary></indexterm><indexterm id="IXT-2-410"><primary>windows</primary><secondary>XUL</secondary><tertiary>modality</tertiary></indexterm>modally.
  918: Control is not given back to the parent window until this window has
  919: closed.
  920: </para>
  921: </listitem>
  922: </varlistentry>
  923: 
  924: <varlistentry><term>titlebar</term>
  925: <listitem>
  926: <para>The window can be created
  927: <indexterm id="IXT-2-411"><primary>windows</primary><secondary>XUL</secondary><tertiary>titlebars</tertiary></indexterm><indexterm id="IXT-2-412"><primary>XUL
  928: (XML-based User-interface
  929: Language)</primary><secondary>windows</secondary><tertiary>titlebar</tertiary></indexterm><indexterm id="IXT-2-413"><primary>titlebars,
  930: XUL windows</primary></indexterm>with or without a titlebar.
  931: </para>
  932: </listitem>
  933: </varlistentry>
  934: 
  935: <varlistentry><term>centerscreen</term>
  936: <listitem>
  937: <para>Open the window centered <indexterm id="IXT-2-414"><primary>centerscreen, windows
  938: (XUL)</primary></indexterm><indexterm id="IXT-2-415"><primary>windows</primary><secondary>XUL</secondary><tertiary>centerscreen</tertiary></indexterm><indexterm id="IXT-2-416"><primary>XUL
  939: (XML-based User-interface
  940: Language)</primary><secondary>windows</secondary><tertiary>centerscreen</tertiary></indexterm>on
  941: screen.
  942: </para>
  943: </listitem>
  944: </varlistentry>
  945: </variablelist>
  946: 
  947: <para>A comma delimits the features list and the entire list must be in
  948: quotes. The script that handles the new window accesses the arguments
  949: list:
  950: </para>
  951: 
  952: <programlisting>window.openDialog("chrome://xfly/content/utils/prompt.xul",
  953:                   "xFly_prompt",
  954:                   "chrome,dialog,modal",
  955:                   message);</programlisting>
  956: 
  957: <para>The window created in this example will be modal and use the message
  958: that was passed to it in the variable <emphasis>message</emphasis>.
  959: By default, Mozilla assumes that the <literal>chrome</literal>
  960: feature is on when you use either <literal>window.open</literal> or
  961: <literal>window.openDialog</literal> in a chrome environment, and
  962: creates a new window in the window hierarchy.
  963: </para>
  964: 
  965: </sect3>
  966: </sect2>
  967: </sect1>
  968: 
  969: <sect1 role="" id="mozilla-CHP-2-SECT-3" label="2.3">
  970: <title>Making Mozilla Work for You</title>
  971: 
  972: <para>The second "Hello World" sample,
  973: <indexterm id="IXT-2-417"><primary>Hello World XUL
  974: example</primary><secondary>JavaScript
  975: and</secondary></indexterm><indexterm id="IXT-2-418"><primary>XUL (XML-based
  976: User-interface Language)</primary><secondary>Hello World
  977: example</secondary><tertiary>JavaScript
  978: and</tertiary></indexterm>shown in <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link>, adds
  979: some important application features and begins to take advantage of
  980: the resources that Mozilla provides for you. This section goes over
  981: the ways you can import stylesheets and Mozilla scripts to make your
  982: XUL more sophisticated and modular. It also prepares you to make an
  983: actual application.
  984: </para>
  985: 
  986: <para>You can see this example in action by saving the code in <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link> to a file, <filename>hello2.xul</filename>,
  987: and then launching Mozilla and selecting File &gt; Open
  988: File from the browser. This displays the example
  989: as content in the Mozilla browser, as shown in <link linkend="mozilla-CHP-2-FIG-2">Figure 2-2</link>. 
  990: </para>
  991: 
  992: <example id="mozilla-CHP-2-EX-4" label="2-4">
  993: <title>Sample XUL window </title>
  994: <programlisting>&lt;?xml version="1.0"?&gt;
  995: &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;
  996: &lt;!DOCTYPE window&gt;
  997: &lt;window title="Hello xFly"
  998:   xmlns:html="http://www.w3.org/1999/xhtml"
  999:   xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
 1000:   style="background-color: white;"
 1001:   width="300"
 1002:   height="215"
 1003:   onload="centerWindowOnScreen( )"&gt;
 1004: &lt;script type="application/x-javascript"   
 1005:   src="chrome://global/content/dialogOverlay.js" /&gt;
 1006: &lt;vbox align="left"&gt;
 1007:   &lt;label style="font-weight: bold;"
 1008:       value="Hello, Welcome to the xFly" /&gt;
 1009:   &lt;image src="http://books.mozdev.org/xfly.gif" /&gt;
 1010:   &lt;button label="hello xFly" oncommand="alert('Hello World');" /&gt;
 1011: &lt;/vbox&gt;
 1012: &lt;/window&gt;</programlisting>
 1013: </example>
 1014: 
 1015: <para>The difference between <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link> and the first
 1016: example is the addition of new elements, including the
 1017: <literal>script</literal> element that brings in Mozilla JavaScript
 1018: functions for use, additional box layout properties, inline style
 1019: rules and processing instructions to import stylesheets, and the
 1020: <literal>DOCTYPE</literal> declaration, which we describe later in
 1021: this chapter in the section <link linkend="mozilla-CHP-2-SECT-5.5.3">Section 2.5.5.3</link>. 
 1022: </para>
 1023: 
 1024: <para>These extras make your XUL file work more like an application by
 1025: giving you access to services and features that already exist in
 1026: Mozilla. They can also help you organize your own work into reusable
 1027: parts, such as application stylesheets, widgets, and script
 1028: libraries, as described later in this chapter in the section <link linkend="mozilla-CHP-2-SECT-5">Section 2.5</link>. 
 1029: </para>
 1030: 
 1031: <figure id="mozilla-CHP-2-FIG-2" label="2-2">
 1032: <title>The second Hello xFly example loaded in the browser</title>
 1033: <graphic fileref="figs/moz_0202.png"/></figure>
 1034: 
 1035: <sect2 role="" id="mozilla-CHP-2-SECT-3.1" label="2.3.1">
 1036: <title>Importing Resources from Mozilla</title>
 1037: 
 1038: <para>The code in <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link> uses scripts
 1039: <indexterm id="IXT-2-419"><primary>resources</primary><secondary>importing from
 1040: Mozilla</secondary></indexterm><indexterm id="IXT-2-420"><primary>importing</primary><secondary>resources</secondary></indexterm>and
 1041: styles that are already defined in Mozilla. As
 1042: you'll see in examples in this book
 1043: <indexterm id="IXT-2-421"><primary>global.css
 1044: stylesheet</primary></indexterm><indexterm id="IXT-2-422"><primary>stylesheets</primary><secondary>global.css</secondary></indexterm>and
 1045: in the Mozilla source code, the <filename>global.css</filename>
 1046: stylesheet is where many basic styles <indexterm id="IXT-2-423"><primary>XUL
 1047: widgets</primary><secondary>styles</secondary></indexterm>
 1048: <indexterm id="IXT-2-424"><primary>widgets</primary><secondary>XUL</secondary><tertiary>styles</tertiary></indexterm>
 1049: <indexterm id="IXT-2-425"><primary>styles</primary><secondary>widgets,
 1050: XUL</secondary></indexterm>are defined for XUL widgets. Most XUL
 1051: widgets have some inherent style, as you can see in <link linkend="mozilla-CHP-2-EX-1">Example 2-1</link>, where the button has a button-like look
 1052: without any explicit style rules or stylesheet imports.
 1053: </para>
 1054: 
 1055: <para>As the XPFE has evolved, XUL widgets <indexterm id="IXT-2-426"><primary>XUL
 1056: widgets</primary><secondary>XBL and</secondary></indexterm>
 1057: <indexterm id="IXT-2-427"><primary>XBL (eXtensible Binding
 1058: Language)</primary><secondary>XUL widgets
 1059: and</secondary></indexterm>have used XBL internally to define some of
 1060: these inherent looks and behaviors, which has taken some of the
 1061: responsibility away from <filename>global.css</filename> and other
 1062: CSS files. But this stylesheet still contains important rules for
 1063: displaying basic XUL widgets. It's usually a good
 1064: idea to import this main stylesheet into your application, as
 1065: described here, and see what it gets you in terms of presentation. If
 1066: you load <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link> with and without the
 1067: <filename>global.css</filename> line, you can see the way that the
 1068: rules in the stylesheet provide styles for the widgets in the XUL.
 1069: </para>
 1070: 
 1071: <para>Similarly, scripts like <filename>globalOverlay.js</filename>,
 1072: <filename>tasksOverlay.js</filename>, and
 1073: <filename>dialogOverlay.js</filename>, imported in <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link>, provide basic functions you can use in your
 1074: applications.
 1075: </para>
 1076: 
 1077: <sect3 role="" id="mozilla-CHP-2-SECT-3.1.1" label="2.3.1.1">
 1078: <title>Loading stylesheets</title>
 1079: 
 1080: <para>In the second line of <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link>, the stylesheet
 1081: <indexterm id="IXT-2-428"><primary>stylesheets</primary><secondary>loading</secondary></indexterm>declaration
 1082: uses a <filename>chrome://</filename> URL to refer to and load the
 1083: <filename>global.css</filename> file. The style rules in that file
 1084: give the button widget its
 1085: "widgetness." You can use the
 1086: stylesheet <indexterm id="IXT-2-429"><primary>stylesheets</primary><seealso>CSS</seealso></indexterm>processing
 1087: instruction to load Mozilla stylesheets like
 1088: <filename>global.css</filename>, <filename>navigator.css</filename>,
 1089: <indexterm id="IXT-2-430"><primary>navigator.css stylesheet</primary></indexterm>
 1090: <indexterm id="IXT-2-431"><primary>toolbar.css stylesheet</primary></indexterm>
 1091: <indexterm id="IXT-2-432"><primary>stylesheets</primary><secondary>navigator.css</secondary></indexterm>
 1092: <indexterm id="IXT-2-433"><primary>stylesheets</primary><secondary>toolbar.css</secondary></indexterm>and
 1093: <filename>toolbar.css</filename>, or you can use it to load your own
 1094: application stylesheet. In both cases, the
 1095: <filename>chrome://</filename> URL allows you to refer to packaged
 1096: files in a flexible way.
 1097: </para>
 1098: 
 1099: <programlisting>&lt;!--import the navigator.css stylesheet 
 1100:     from the Mozilla navigator component--&gt;
 1101: &lt;?xml-stylesheet href="chrome://navigator/skin" type="text/css"?&gt;
 1102: &lt;!--import xfly.css stylesheet from the xFly package--&gt;
 1103: &lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;</programlisting>
 1104: 
 1105: <para>Also note the use of an inline style in <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link>.
 1106: The <literal>style</literal> property on the <literal>label</literal>
 1107: widget gives you a place to define CSS rules directly on widgets. In
 1108: this case, the label is given a bold font so that it shows up better
 1109: in the window. You could also define this style rule in an external
 1110: stylesheet and make that stylesheet part of the package for your
 1111: application, as we do later in this chapter in the section <link linkend="mozilla-CHP-2-SECT-5.5">Section 2.5.5</link>. 
 1112: </para>
 1113: 
 1114: </sect3>
 1115: 
 1116: <sect3 role="" id="mozilla-CHP-2-SECT-3.1.2" label="2.3.1.2">
 1117: <title>Accessing script in XUL</title>
 1118: 
 1119: <para>To access a script in XUL, use the <literal>script</literal> element
 1120: <indexterm id="IXT-2-434"><primary>XUL (XML-based User-interface
 1121: Language)</primary><secondary>scripts, access</secondary></indexterm>
 1122: <indexterm id="IXT-2-435"><primary>scripts</primary><secondary>XUL,
 1123: access</secondary></indexterm>and a URL value for its
 1124: <literal>src</literal> attribute:
 1125: </para>
 1126: 
 1127: <programlisting>&lt;script type="application/x-javascript"
 1128:    src="chrome://xfly/content/xfly.js" /&gt;</programlisting>
 1129: 
 1130: <para>The <literal>dialogOverlay.js</literal> script imported into
 1131: <indexterm id="IXT-2-436"><primary>dialogOverlay.js script</primary></indexterm>
 1132: <indexterm id="IXT-2-437"><primary>scripts</primary><secondary>dialogOverlay.js</secondary></indexterm>your
 1133: XUL file in <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link> provides access to the
 1134: <literal>CenterWindowOnScreen( )</literal> function. This
 1135: <indexterm id="IXT-2-438"><primary>CenterWindowOnScreen( ) function,
 1136: JavaScript</primary></indexterm>
 1137: <indexterm id="IXT-2-439"><primary>functions</primary><secondary>JavaScript</secondary><tertiary>CenterWindowOnScreen(
 1138: )</tertiary></indexterm>
 1139: <indexterm id="IXT-2-440"><primary>JavaScript</primary><secondary>functions</secondary><tertiary>CenterWindowOnScreen(
 1140: )</tertiary></indexterm>function is made available to your XUL file
 1141: with the line:
 1142: </para>
 1143: 
 1144: <programlisting>&lt;script type="application/x-javascript"   
 1145:   src="chrome://global/content/dialogOverlay.js" /&gt;</programlisting>
 1146: 
 1147: <para>All functions in <filename>dialogOverlay.js</filename> are imported
 1148: into the scope of the XUL file and can be called directly, as
 1149: <literal>CenterWindowOnScreen( )</literal> is in the
 1150: <literal>onload</literal> event handler for the XUL window. Note that
 1151: the functions contained in an imported JavaScript file are not
 1152: broadcast in any particular way (though you can see them if you use
 1153: the JavaScript Debugger). You may need to look around in the source
 1154: code or see how other applications import files to find the functions
 1155: you need, but the routines you want to use in your application code
 1156: are probably already available in Mozilla.<footnote label="1">
 1157: <para>Unfortunately, no good reference exists for the functions
 1158: defined in the various scripts files you can import. The functions
 1159: and their locations within the files continue to change, so finding
 1160: and using the right ones is sometimes a matter of luck, sometimes a
 1161: matter of whom you know, and often a matter of testing,
 1162: determination, and patience.</para> </footnote>
 1163: </para>
 1164: 
 1165: </sect3>
 1166: </sect2>
 1167: </sect1>
 1168: 
 1169: <sect1 role="" id="mozilla-CHP-2-SECT-4" label="2.4">
 1170: <title>Displaying XUL Files as Chrome</title>
 1171: 
 1172: <para><link linkend="mozilla-CHP-2-FIG-2">Figure 2-2</link> shows the XUL file
 1173: <indexterm id="IXT-2-441"><primary>XUL files</primary><secondary>displaying as
 1174: chrome</secondary></indexterm>
 1175: <indexterm id="IXT-2-442"><primary>chrome</primary><secondary>XUL files,
 1176: displaying</secondary></indexterm>in <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link>
 1177: loaded into the browser's main content area. The
 1178: example features a <literal>label</literal> widget and an
 1179: <literal>image</literal>, both situated within a
 1180: <literal>vbox</literal> that lays them out properly in the available
 1181: space. These widgets make up the chrome of your application, the
 1182: Mozilla user interface that can refer to itself and its resources
 1183: with the special <emphasis>chrome://</emphasis> URL.
 1184: </para>
 1185: 
 1186: <para>This example is starting to show off some of the nice features of
 1187: XPFE programming, but it still isn't an application
 1188: yet. Among other things, you probably don't want
 1189: your code to live inside the browser window forever. As it grows, you
 1190: may also want to divide it into sensible parts -- a XUL file, a
 1191: separate stylesheet, and a script file, for example. The rest of this
 1192: chapter explains how to organize and package the code in <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link> and launch it as a standalone window by using
 1193: the <literal>-chrome</literal> option when launching Mozilla.
 1194: </para>
 1195: 
 1196: <para>Launching a XUL file by using the chrome switch requires that you
 1197: register your application in the chrome registry so that Mozilla sees
 1198: and recognizes it. The <link linkend="mozilla-CHP-2-SECT-5.6">Section 2.5.6</link>
 1199: section later in this chapter provides more information about the
 1200: chrome environment and how to register this sample application.
 1201: </para>
 1202: 
 1203: <para>Although this example hasn't been registered yet, we
 1204: want to give you a preview of what it will look like when launched in
 1205: a standalone window so you can compare it with how the same XUL file
 1206: looks when loaded into the browser window. When you do launch the
 1207: example by using the <literal>-chrome</literal> option (as described
 1208: later in this chapter in the section <link linkend="mozilla-CHP-2-SECT-6">Section 2.6</link>), you will see the window
 1209: displayed in <link linkend="mozilla-CHP-2-FIG-3">Figure 2-3</link>.
 1210: </para>
 1211: 
 1212: <figure id="mozilla-CHP-2-FIG-3" label="2-3">
 1213: <title>The second Hello xFly example launched in its own window</title>
 1214: <graphic fileref="figs/moz_0203.png"/></figure>
 1215: 
 1216: <para>Using the <literal>-chrome</literal> option tells Mozilla to display
 1217: the specified file (in this case, the code from <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link>) as a standalone application rather than as
 1218: content within a browser window. The file itself is the same
 1219: regardless of how it is loaded, but the results differ depending on
 1220: what you tell Mozilla to do with the file.
 1221: </para>
 1222: 
 1223: <para>Displaying a XUL file in its own chrome window makes it more
 1224: independent and breaks the link to the browser content area that is
 1225: present when you use the File &gt; Open File... method.
 1226: Launching standalone windows, accompanied by the JavaScript
 1227: <literal>window.openDialog</literal> function explained later in this
 1228: chapter, opens up much more flexible window display options for your
 1229: application.
 1230: </para>
 1231: 
 1232: </sect1>
 1233: 
 1234: <sect1 role="" id="mozilla-CHP-2-SECT-5" label="2.5">
 1235: <title>Creating a Package</title>
 1236: 
 1237: <para>The previous two main sections
 1238: <indexterm id="IXT-2-443"><primary>chrome</primary><secondary>package
 1239: content</secondary></indexterm>
 1240: <indexterm id="IXT-2-444"><primary>packages</primary><secondary>chrome
 1241: and</secondary></indexterm>introduced the concept of chrome and the
 1242: prospect of creating standalone application windows. The next step is
 1243: to make the example into an actual package -- a modularized
 1244: collection of files that can be installed in Mozilla as a new
 1245: application.
 1246: </para>
 1247: 
 1248: <para>In the earlier section <link linkend="mozilla-CHP-2-SECT-3">Section 2.3</link>, you added features and
 1249: complexity to your XUL file. In this section, you pull those features
 1250: into separate files -- a CSS file, JS file, and a DTD
 1251: file -- register these files together, and make them installable
 1252: as a single package.
 1253: </para>
 1254: 
 1255: <para>Only when you have packaged your work will your files have access to
 1256: Mozilla files, such as CSS and scripts, be accessible from the
 1257: special <filename>chrome://</filename> type URLs, be able to accept
 1258: new themes, and be able
 1259: <indexterm id="IXT-2-445"><primary>packages</primary><secondary>CSS
 1260: and</secondary></indexterm>
 1261: <indexterm id="IXT-2-446"><primary>packages</primary><secondary>scripts
 1262: and</secondary></indexterm>
 1263: <indexterm id="IXT-2-447"><primary>packages</primary><secondary>themes
 1264: and</secondary></indexterm>
 1265: <indexterm id="IXT-2-448"><primary>packages</primary><secondary>XPCOM objects
 1266: and</secondary></indexterm><indexterm id="IXT-2-449"><primary>stylesheets</primary><secondary>packages
 1267: and</secondary></indexterm>
 1268: <indexterm id="IXT-2-450"><primary>scripts</primary><secondary>packages
 1269: and</secondary></indexterm>
 1270: <indexterm id="IXT-2-451"><primary>themes</primary><secondary>packages
 1271: and</secondary></indexterm>
 1272: <indexterm id="IXT-2-452"><primary>XPCOM</primary><secondary>methods</secondary><tertiary>JavaScript
 1273: implementation</tertiary></indexterm>to get to the XPCOM objects in
 1274: which much of the application for Mozilla is defined.
 1275: </para>
 1276: 
 1277: <para>Tools are available that help set up the files that form the basis of
 1278: a new package. <link linkend="mozilla-APP-B">Appendix B</link> provides information
 1279: about XULKit, which is a collection of scripts that automates part of
 1280: the package creation process. It is recommended that you try to set
 1281: up your own package by hand first to understand how packages are put
 1282: together before using the XULKit scripts.
 1283: </para>
 1284: 
 1285: <sect2 role="" id="mozilla-CHP-2-SECT-5.1" label="2.5.1">
 1286: <title>Architecture of a Chrome Package</title>
 1287: 
 1288: <para>The architecture of the
 1289: <indexterm id="IXT-2-453"><primary>packages</primary><secondary>architecture</secondary></indexterm><indexterm id="IXT-2-454"><primary>chrome</primary><secondary>packages</secondary><see>packages</see></indexterm>Mozilla
 1290: XPFE is component- or layer-based. One of the primary aims of the
 1291: design was the separation of each different component of an
 1292: application, namely content, functionality, and layout. This design
 1293: results in greater modularization, making it easy to create and
 1294: change a UI -- to change skins for your application, for example,
 1295: update the language in which the user interface is presented, or
 1296: bring in new script elements.
 1297: </para>
 1298: 
 1299: <para>When a package is modularized like it can be in Mozilla, design
 1300: determinations can be left to the designer, language in the user
 1301: interface can be left to writers, and the application framework
 1302: itself can be handled by software developers (though the programmer
 1303: handles all of these in many small- to medium-sized projects). The
 1304: next several sections provide more detail about each component and
 1305: its content and file types. The way basic packages fit components
 1306: together can be the basis for your own application development.
 1307: </para>
 1308: 
 1309: <para>A package is a group of directories and related files that make up a
 1310: Mozilla application. A small, typical package may include a single
 1311: XUL file, a script file (currently JavaScript, with implementations
 1312: for Perl, Python, Ruby, and other languages being developed), and a
 1313: CSS file. However, a single package might include dozens of these
 1314: files, and may also include XBL files, Image File Types (PNG, JPG,
 1315: GIF), DTD, HTML, and RDF files. Each has an important role to play in
 1316: the application.
 1317: </para>
 1318: 
 1319: </sect2>
 1320: <sect2 role="" id="mozilla-CHP-2-SECT-5.2" label="2.5.2">
 1321: <title>Package Components</title>
 1322: 
 1323: <para>As you will discover, each
 1324: <indexterm id="IXT-2-455"><primary>packages</primary><secondary>components</secondary></indexterm>component
 1325: in a package is independent. It is possible for your application to
 1326: exist with just one or two of these components. Yet they all tie
 1327: together when necessary to create a full featured application, and
 1328: they are all at your disposal to take advantage of.
 1329: </para>
 1330: 
 1331: <sect3 role="" id="mozilla-CHP-2-SECT-5.2.1" label="2.5.2.1">
 1332: <title>Chrome content</title>
 1333: 
 1334: <para>The content is
 1335: <indexterm id="IXT-2-456"><primary>packages</primary><secondary>chrome
 1336: content</secondary></indexterm>
 1337: <indexterm id="IXT-2-457"><primary>chrome</primary><secondary>package
 1338: content</secondary></indexterm> <indexterm id="IXT-2-458"><primary>XUL data,
 1339: packages</primary></indexterm> <indexterm id="IXT-2-459"><primary>XBL data,
 1340: packages</primary></indexterm>
 1341: <indexterm id="IXT-2-460"><primary>packages</primary><secondary>XUL
 1342: data</secondary></indexterm>
 1343: <indexterm id="IXT-2-461"><primary>packages</primary><secondary>XBL
 1344: data</secondary></indexterm>the XUL and XBL data, contained in one or
 1345: more files. This content is pulled in at runtime from files,
 1346: overlays, and bindings, for display in the window system. The
 1347: cross-platform implementation ensures consistency in the native
 1348: system, and fits into the "write once, run
 1349: anywhere" model. The XUL defines a single set of UI
 1350: elements for all platforms. The XUL parser is much less tolerant than
 1351: many HTML parsers; in fact, it's completely
 1352: intolerant. However, it needs to be because every element in XUL
 1353: impacts others and affects the layout of the UI -- especially in
 1354: the context of the Box Model, which <link linkend="mozilla-CHP-3">Chapter 3</link>
 1355: describes in detail.
 1356: </para>
 1357: 
 1358: <para>The widget set consists of simple widgets that display by drawing
 1359: themselves absolutely in their allotted space, and of more complex
 1360: widgets that act as containers, draw on top of others, or
 1361: <indexterm id="IXT-2-462"><primary>packages</primary><secondary>widget
 1362: set</secondary></indexterm>
 1363: <indexterm id="IXT-2-463"><primary>widgets</primary><secondary>packages</secondary></indexterm>accept
 1364: input. A <literal>&lt;label&gt;</literal> widget is an example of the
 1365: former, while <literal>&lt;stack&gt;</literal> is of the latter, more
 1366: complex group. If the parser does not find an element in the content
 1367: files, it fails to load and returns an error. Errors vary by type. An
 1368: XML syntax error, for example, displays in the window in place of the
 1369: expected content. It gives you the file the error originated in,
 1370: along with the line number and column number.
 1371: </para>
 1372: 
 1373: <para>Built as a complementary <indexterm id="IXT-2-464"><primary>XBL (eXtensible Binding
 1374: Language)</primary><secondary>widget
 1375: creation</secondary></indexterm>description language to XUL, XBL
 1376: allows you to create your own widgets or add new behavior to existing
 1377: XUL widgets. You may attach scripting and create (anonymous) content
 1378: in a single binding or in many. With a little imagination, you can
 1379: extend the content available to you infinitely by adding your own
 1380: styling and behavior with XBL.
 1381: </para>
 1382: 
 1383: </sect3>
 1384: 
 1385: <sect3 role="" id="mozilla-CHP-2-SECT-5.2.2" label="2.5.2.2">
 1386: <title>Chrome appearance</title>
 1387: 
 1388: <para>Loading up a XUL file with
 1389: <indexterm id="IXT-2-465"><primary>chrome</primary><secondary>appearance,
 1390: packages</secondary></indexterm>
 1391: <indexterm id="IXT-2-466"><primary>packages</primary><secondary>chrome
 1392: content</secondary><tertiary>appearance</tertiary></indexterm>no
 1393: styles attached
 1394: <indexterm id="IXT-2-467"><primary>styles</primary><secondary>packages</secondary></indexterm>
 1395: <indexterm id="IXT-2-468"><primary>packages</primary><secondary>styles</secondary></indexterm>to
 1396: the XUL elements will render the UI as a plain, disproportioned group
 1397: of widgets. While plain text on a web page can be effective for
 1398: simply relaying information, the situation is not analogous in user
 1399: interfaces.
 1400: </para>
 1401: 
 1402: <para>Mozilla user interfaces without style are not very usable. Even to
 1403: achieve the traditional plain gray interface that so many
 1404: applications use, you must use CSS to style the Mozilla front end,
 1405: and subtle effects, such as color grades or 3D button effects, often
 1406: make even the most basic interface look and work better.
 1407: </para>
 1408: 
 1409: <para>Themes and the ability to customize
 1410: <indexterm id="IXT-2-469"><primary>themes</primary><secondary>packages</secondary></indexterm>
 1411: <indexterm id="IXT-2-470"><primary>packages</primary><secondary>themes
 1412: and</secondary></indexterm>the look of an application are becoming
 1413: more prominent. Mozilla developers realized this prominence during
 1414: the design phase of Mozilla, and it's reflected in
 1415: the architecture: the appearance of the interface is almost entirely
 1416: separate from the structural representation in the content.
 1417: </para>
 1418: 
 1419: </sect3>
 1420: 
 1421: <sect3 role="" id="mozilla-CHP-2-SECT-5.2.3" label="2.5.2.3">
 1422: <title>Chrome behavior</title>
 1423: 
 1424: <para>Mozilla currently supports
 1425: <indexterm id="IXT-2-471"><primary>chrome</primary><secondary>package
 1426: content</secondary><tertiary>behavior</tertiary></indexterm>
 1427: <indexterm id="IXT-2-472"><primary>packages</primary><secondary>chrome
 1428: content</secondary><tertiary>behavior</tertiary></indexterm>only
 1429: JavaScript <indexterm id="IXT-2-473"><primary>JavaScript</primary><secondary>UI
 1430: and</secondary></indexterm>as the bridge between the UI and the
 1431: application code. JavaScript is the glue that binds the UI and the
 1432: back end functionality, which is almost entirely written in C++.
 1433: </para>
 1434: 
 1435: <para>Much of the infrastructure is in place for
 1436: <indexterm id="IXT-2-474"><primary>Python</primary></indexterm>
 1437: <indexterm id="IXT-2-475"><primary>Perl</primary></indexterm>the support of other
 1438: programming languages, however, and Python and Perl are currently
 1439: being proposed as the next languages to fit into the framework.
 1440: Currently, you will see JavaScript associated with XUL content via
 1441: the following declaration:
 1442: </para>
 1443: 
 1444: <programlisting>&lt;script type="application/x-javascript" src="xfly.js" /&gt;</programlisting>
 1445: 
 1446: <para><literal>type</literal> replaces the now deprecated
 1447: <literal>language</literal> attribute and expects a MIME type for its
 1448: value. As Mozilla matures and support for other languages arrives,
 1449: this value may become interchangeable -- which fits in with the
 1450: philosophy, common in open source projects, of there being More Than
 1451: One Way To Do It. Note that the behavior component of a Mozilla
 1452: application usually sits in the <filename>content</filename>
 1453: subdirectory of a package, as described later in the section <link linkend="mozilla-CHP-2-SECT-5.3">Section 2.5.3</link>. 
 1454: </para>
 1455: 
 1456: </sect3>
 1457: 
 1458: <sect3 role="" id="mozilla-CHP-2-SECT-5.2.4" label="2.5.2.4">
 1459: <title>Chrome locale</title>
 1460: 
 1461: <para>Localization is
 1462: <indexterm id="IXT-2-476"><primary>packages</primary><secondary>chrome
 1463: content</secondary><tertiary>locale</tertiary></indexterm>
 1464: <indexterm id="IXT-2-477"><primary>chrome</primary><secondary>package
 1465: content</secondary><tertiary>locale</tertiary></indexterm>the
 1466: modification of software to meet the language of a location and the
 1467: adaptation of resources, such as user interface and documentation,
 1468: for that region. Widgets such as menu items, buttons, window
 1469: titlebars, and alert dialogs commonly need to be localized. Beyond
 1470: these widgets, there can be other localizable content in an
 1471: application, from HTML pages to install packages.
 1472: </para>
 1473: 
 1474: <para>The formats used by Mozilla are:</para>
 1475: 
 1476: <itemizedlist><listitem>
 1477: <para>DTD (<filename>.dtd</filename>) files, which contain entities that
 1478: host the strings to be included in your XUL content.
 1479: </para>
 1480: </listitem><listitem>
 1481: <para>Property files (<filename>.properties</filename>), which contain
 1482: string bundles that are accessed by dynamic content in JavaScript and
 1483: C++ files or, theoretically, any language.
 1484: </para>
 1485: </listitem><listitem>
 1486: <para>HTML files for certain pages installed with the
 1487: application -- e.g., About Mozilla.
 1488: </para>
 1489: </listitem><listitem>
 1490: <para>RDF files.</para>
 1491: </listitem></itemizedlist>
 1492: </sect3>
 1493: </sect2>
 1494: <sect2 role="" id="mozilla-CHP-2-SECT-5.3" label="2.5.3">
 1495: <title>Directory Structure</title>
 1496: 
 1497: <para>Files can be organized
 1498: <indexterm id="IXT-2-478"><primary>directories</primary></indexterm>in many
 1499: different ways. If your application is small -- say a single
 1500: window with a simple structure that needs to be available only in one
 1501: language -- then having all your files in one directory may be
 1502: easier. As the size of an application goes over a certain threshold,
 1503: however, logically grouping your files into subdirectories is a good
 1504: practice to make the files more accessible.
 1505: </para>
 1506: 
 1507: <para>Most applications use a directory structure that mirrors the package
 1508: component descriptions described earlier: XUL and JavaScript
 1509: <indexterm id="IXT-2-479"><primary>directories</primary><secondary>content</secondary></indexterm>
 1510: <indexterm id="IXT-2-480"><primary>content directory</primary></indexterm>in a
 1511: <filename>content</filename> subdirectory, CSS and images in a
 1512: <filename>skin</filename> subdirectory, <indexterm id="IXT-2-481"><primary>skin
 1513: directory</primary></indexterm>
 1514: <indexterm id="IXT-2-482"><primary>directories</primary><secondary>skin</secondary></indexterm>and
 1515: DTDs and other resources for localizing the interface in a
 1516: <emphasis>locale</emphasis> subdirectory. <link linkend="mozilla-CHP-2-FIG-4">Figure 2-4</link> <indexterm id="IXT-2-483"><primary>locale
 1517: directory</primary></indexterm>
 1518: <indexterm id="IXT-2-484"><primary>directories</primary><secondary>locale</secondary></indexterm>shows
 1519: this common grouping.
 1520: </para>
 1521: 
 1522: <figure id="mozilla-CHP-2-FIG-4" label="2-4">
 1523: <title>A sample package layout in the directory system</title>
 1524: <graphic fileref="figs/moz_0204.png"/></figure>
 1525: 
 1526: <para>These three different directories usually contain the following type
 1527: of files:
 1528: </para>
 1529: 
 1530: <variablelist>
 1531: <varlistentry><term>content</term>
 1532: <listitem>
 1533: <para>The <filename>content</filename> directory is <indexterm id="IXT-2-485"><primary>XUL
 1534: files</primary><secondary>content directory</secondary></indexterm>
 1535: <indexterm id="IXT-2-486"><primary>content directory</primary><secondary>XUL
 1536: files</secondary></indexterm>the home for the XUL files that contain
 1537: the widgets to be drawn for you application. It is
 1538: <indexterm id="IXT-2-487"><primary>JavaScript</primary><secondary>files, content
 1539: directory</secondary></indexterm>common practice to also place files
 1540: related to behavior, namely JavaScript files, in this directory.
 1541: </para>
 1542: </listitem>
 1543: </varlistentry>
 1544: 
 1545: <varlistentry><term>locale</term>
 1546: <listitem>
 1547: <para>This directory contains <indexterm id="IXT-2-488"><primary>locale
 1548: directory</primary></indexterm>
 1549: <indexterm id="IXT-2-489"><primary>directories</primary><secondary>locale</secondary></indexterm>the
 1550: files <indexterm id="IXT-2-490"><primary>DTD</primary><secondary>locale
 1551: directory</secondary></indexterm>that contain localized strings for
 1552: your package. Most files are DTD files that contain the entities
 1553: referenced in XUL files. There is a subdirectory for each language,
 1554: and the naming convention is <emphasis>code-region</emphasis>, such
 1555: as <literal>en-US</literal>.
 1556: </para>
 1557: </listitem>
 1558: </varlistentry>
 1559: 
 1560: <varlistentry><term>skin</term>
 1561: <listitem>
 1562: <para>The term "skin" is an
 1563: <indexterm id="IXT-2-491"><primary>skin directory</primary></indexterm>
 1564: <indexterm id="IXT-2-492"><primary>directories</primary><secondary>skin</secondary></indexterm>internal
 1565: name <indexterm id="IXT-2-493"><primary>stylesheets</primary><secondary>skin
 1566: directory</secondary></indexterm>for a theme. The
 1567: <filename>skin</filename> directory contains all CSS files and images
 1568: that contribute to the appearance of the windows. This is a good
 1569: place to put the application images -- in their own subdirectory.
 1570: </para>
 1571: </listitem>
 1572: </varlistentry>
 1573: </variablelist>
 1574: 
 1575: <sect3 role="" id="mozilla-CHP-2-SECT-5.3.1" label="2.5.3.1">
 1576: <title>The xFly application directory structure</title>
 1577: 
 1578: <para>The structure of the directories in which <indexterm id="IXT-2-494"><primary>xFly
 1579: package</primary><secondary>directories</secondary></indexterm>an
 1580: application is defined (whether those directories are in the
 1581: filesystem or subdirectories in an archive such as a JAR file) is an
 1582: important part of that application's design and
 1583: relationship to Mozilla. Use the following steps to make your xFly
 1584: package self-contained, registerable, and adaptable.
 1585: </para>
 1586: 
 1587: <itemizedlist><listitem>
 1588: <para>On your computer, go to the directory where you have installed
 1589: Mozilla and create a new directory underneath the
 1590: <filename>chrome</filename> directory called
 1591: "<filename>xfly</filename>."
 1592: </para>
 1593: 
 1594: <para>All Mozilla applications live in the <filename>chrome</filename>
 1595: directory.
 1596: </para>
 1597: </listitem><listitem>
 1598: <para>Under that directory, create the three new directories,
 1599: <filename>content</filename>, <filename>locale</filename>, and
 1600: <filename>skin</filename>, as shown in <link linkend="mozilla-CHP-2-FIG-5">Figure 2-5</link>. 
 1601: The <filename>locale</filename> directory will have the default 'en-US' language pack structure.
 1602: </para>
 1603: </listitem></itemizedlist>
 1604: <figure id="mozilla-CHP-2-FIG-5" label="2-5">
 1605: <title>xFly package directory structure</title>
 1606: <graphic fileref="figs/moz_0205.png"/></figure>
 1607: 
 1608: </sect3>
 1609: </sect2>
 1610: <sect2 role="" id="mozilla-CHP-2-SECT-5.4" label="2.5.4">
 1611: <title>Package Manifests</title>
 1612: 
 1613: <para>Now that you have created the
 1614: <indexterm id="IXT-2-495"><primary>packages</primary><secondary>manifests</secondary></indexterm>
 1615: <indexterm id="IXT-2-496"><primary>manifests</primary><secondary>packages</secondary></indexterm>directories
 1616: for your package, you must tell Mozilla about them. All Mozilla
 1617: packages must include manifests that describe their contents and make
 1618: it possible to register them with Mozilla. A manifest is an RDF file
 1619: (or series of RDF files) that sits within the package and interacts
 1620: with Mozilla's <filename>chrome</filename>
 1621: directory. RDF files are XML files that describe data in a
 1622: machine-readable form.
 1623: </para>
 1624: 
 1625: <para>Each xFly package subdirectory needs its own manifest file. Mozilla
 1626: uses these files (in each case, called
 1627: <filename>contents.rdf</filename>) when registering the application.
 1628: These files are listed in Examples <link linkend="mozilla-CHP-2-EX-5">Example 2-5</link>,
 1629: <link linkend="mozilla-CHP-2-EX-6">Example 2-6</link>, and <link linkend="mozilla-CHP-2-EX-7">Example 2-7</link>.
 1630: Create these files in your xFly <filename>content</filename>,
 1631: <filename>skin</filename>, and <filename>locale</filename>
 1632: subdirectories, respectively.
 1633: </para>
 1634: 
 1635: <example id="mozilla-CHP-2-EX-5" label="2-5">
 1636: <title>chrome/xfly/content/contents.rdf file </title>
 1637: <programlisting>&lt;?xml version="1.0"?&gt;
 1638: &lt;RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 1639:          xmlns:chrome="http://www.mozilla.org/rdf/chrome#"&gt;
 1640:   &lt;!-- list all the packages being supplied --&gt;
 1641:   &lt;RDF:Seq about="urn:mozilla:package:root"&gt;
 1642:     <emphasis role="bold">&lt;RDF:li resource="urn:mozilla:package:xfly"/&gt;</emphasis>
 1643:   &lt;/RDF:Seq&gt;
 1644:   &lt;!-- package information --&gt;
 1645:   &lt;RDF:Description about="urn:mozilla:package:xfly"
 1646:         chrome:displayName="xFly"
 1647:         chrome:author="xfly.mozdev.org"
 1648:         chrome:name="xfly"&gt;
 1649:   &lt;/RDF:Description&gt;
 1650:  <emphasis role="bold">&lt;/RDF:RDF&gt;</emphasis></programlisting>
 1651: </example>
 1652: 
 1653: <para>In the content manifest in <link linkend="mozilla-CHP-2-EX-5">Example 2-5</link>, note the
 1654: <literal>chrome:name</literal>, <literal>chrome:author</literal>, and
 1655: the other metadata that the manifest provides to Mozilla. This
 1656: information can be used by others to identify what your application
 1657: is and who wrote it. For example, the name, author, and short
 1658: description information for each browser theme you have installed is
 1659: viewable by going to Preferences and selecting Appearance
 1660: &gt; Themes.
 1661: </para>
 1662: 
 1663: <para>In <link linkend="mozilla-CHP-2-EX-6">Example 2-6</link>, which describes
 1664: <indexterm id="IXT-2-497"><primary>skins</primary><secondary>xFly
 1665: application</secondary></indexterm>
 1666: <indexterm id="IXT-2-498"><primary>xFly</primary><secondary>skins</secondary></indexterm>the
 1667: skin for xFly only, note that new skin resources for the Classic
 1668: theme are all that is supplied, as indicated in the
 1669: <literal>RDF:Seq</literal>, which lists only
 1670: <literal>classic</literal> as affected by this new package.
 1671: </para>
 1672: 
 1673: <example id="mozilla-CHP-2-EX-6" label="2-6">
 1674: <title>chrome/xfly/skin/contents.rdf file </title>
 1675: <programlisting>&lt;?xml version="1.0"?&gt;
 1676: &lt;RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 1677:          xmlns:chrome="http://www.mozilla.org/rdf/chrome#"&gt;
 1678:   &lt;RDF:Seq about="urn:mozilla:skin:root"&gt;
 1679:     &lt;RDF:li resource="urn:mozilla:skin:classic/1.0" /&gt;
 1680:   &lt;/RDF:Seq&gt;
 1681:   &lt;RDF:Description about="urn:mozilla:skin:classic/1.0"&gt;
 1682:     &lt;chrome:packages&gt;
 1683:       &lt;RDF:Seq about="urn:mozilla:skin:classic/1.0:packages"&gt;
 1684:         <emphasis role="bold">&lt;RDF:li resource="urn:mozilla:skin:classic/1.0:xfly"/&gt;</emphasis>
 1685:       &lt;/RDF:Seq&gt;
 1686:     &lt;/chrome:packages&gt;
 1687:   &lt;/RDF:Description&gt;
 1688: &lt;/RDF:RDF&gt;</programlisting>
 1689: </example>
 1690: 
 1691: <para>In <link linkend="mozilla-CHP-2-EX-7">Example 2-7</link>, which shows the third kind of
 1692: manifest, for new locale information, the English language pack
 1693: (<literal>en-US</literal>) is augmented with the localizable
 1694: resources in the xFly package named there. The
 1695: <literal>RDF:Seq</literal> structure <indexterm id="IXT-2-499"><primary>RDF\:Seq
 1696: structure, manifests</primary></indexterm>in a manifest states,
 1697: "to the package listed here (i.e., the
 1698: <literal>en-US</literal> language pack), add the
 1699: following."
 1700: </para>
 1701: 
 1702: <example id="mozilla-CHP-2-EX-7" label="2-7">
 1703: <title>chrome/xfly/locale/contents.rdf file </title>
 1704: <programlisting>&lt;?xml version="1.0"?&gt;
 1705: &lt;RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 1706:          xmlns:chrome="http://www.mozilla.org/rdf/chrome#"&gt;
 1707:   &lt;RDF:Seq about="urn:mozilla:locale:root"&gt;
 1708:     &lt;RDF:li resource="urn:mozilla:locale:en-US"/&gt;
 1709:   &lt;/RDF:Seq&gt;
 1710:   &lt;!-- locale information --&gt;
 1711:   <emphasis role="bold">&lt;RDF:Description about="urn:mozilla:locale:en-US</emphasis>"
 1712:         <emphasis role="bold">chrome:displayName="English(US)</emphasis>"
 1713:         <emphasis role="bold">chrome:author="xfly.mozdev.org</emphasis>"
 1714:         <emphasis role="bold">chrome:name="en-US</emphasis>"
 1715:         <emphasis role="bold">chrome:previewURL="http://www.mozilla.org/locales/en-US.gif"&gt;</emphasis>
 1716:     &lt;chrome:packages&gt;
 1717:       &lt;RDF:Seq about="urn:mozilla:locale:en-US:packages"&gt;
 1718:         <emphasis role="bold">&lt;RDF:li resource="urn:mozilla:locale:en-US:xfly"/&gt;</emphasis>
 1719:       &lt;/RDF:Seq&gt;
 1720:     &lt;/chrome:packages&gt;
 1721:   &lt;/RDF:Description&gt;
 1722: &lt;/RDF:RDF&gt;</programlisting>
 1723: </example>
 1724: 
 1725: <para>Manifests are detailed in <link linkend="mozilla-CHP-6">Chapter 6</link>. For now,
 1726: it's enough to see that each manifest describes the
 1727: subdirectory in which it is located, and that the contents of those
 1728: subdirectories make up the package collectively.
 1729: </para>
 1730: 
 1731: <para>The content describes the content of the xFly package, the XUL, and
 1732: the JavaScript. The skin describes the theme of xFly, or the CSS and
 1733: images used to lay out the XUL. The third part describes the locale,
 1734: or the strings in the UI that can be localized or adapted for various
 1735: languages or locales.
 1736: </para>
 1737: 
 1738: </sect2>
 1739: <sect2 role="" id="mozilla-CHP-2-SECT-5.5" label="2.5.5">
 1740: <title>Separating the Files</title>
 1741: 
 1742: <para>Once you have a subdirectory structure set up
 1743: <indexterm id="IXT-2-500"><primary>packages</primary><secondary>file
 1744: separation</secondary></indexterm>
 1745: <indexterm id="IXT-2-501"><primary>files</primary><secondary>separating,
 1746: packages</secondary></indexterm> <indexterm id="IXT-2-502"><primary>separating
 1747: files, packages</primary></indexterm>in accordance with the package
 1748: component structure of your application, you can pull the pieces of
 1749: your XUL file out into their own files and modularize your
 1750: application. These separate files -- the basic XUL file and
 1751: separate CSS, JS, and DTD files -- are registered as a single
 1752: package and can then be launched as a standalone application.
 1753: </para>
 1754: 
 1755: <para>Though the files contain the information you've
 1756: already seen in the "Hello World"
 1757: sample shown in <link linkend="mozilla-CHP-2-EX-4">Example 2-4</link>, their interaction
 1758: demonstrates how packages can work together in Mozilla. Each step
 1759: taken to separate the different components requires editing the base
 1760: XUL file.
 1761: </para>
 1762: 
 1763: <sect3 role="" id="mozilla-CHP-2-SECT-5.5.1" label="2.5.5.1">
 1764: <title>The xFly CSS file</title>
 1765: 
 1766: <para>The inline style rule <indexterm id="IXT-2-503"><primary>xfly.css
 1767: file</primary></indexterm>
 1768: <indexterm id="IXT-2-504"><primary>stylesheets</primary><secondary>xfly.css
 1769: file</secondary></indexterm>
 1770: <indexterm id="IXT-2-505"><primary>packages</primary><secondary>xfly.css
 1771: file</secondary></indexterm>on the label widget can go almost
 1772: unadulterated into a separate text file called
 1773: <filename>xfly.css</filename>. Save the code in <link linkend="mozilla-CHP-2-EX-8">Example 2-8</link> in the <filename>chrome/xfly/skin/</filename>
 1774: directory.
 1775: </para>
 1776: 
 1777: <example id="mozilla-CHP-2-EX-8" label="2-8">
 1778: <title>The contents of the xfly.css file </title>
 1779: <programlisting>#xlabel { font-weight: bold; }
 1780: window  { background-color: white; }</programlisting>
 1781: </example>
 1782: 
 1783: <para>Using style rules from an external file is different because you have
 1784: to specify some way for the style rule to associate itself with the
 1785: appropriate tags in the XUL file. CSS provides a rich collection of
 1786: selectors, which bind style data to elements. In this case, where you
 1787: have two separate elements that need to pick up rules, the
 1788: <literal>id</literal> attribute on the XUL element is used to bind a
 1789: unique element to an external style rule and the other style rule is
 1790: bound by referring to the XUL element directly. <link linkend="mozilla-CHP-2-EX-8">Example 2-8</link> includes the selectors for the two elements,
 1791: and <link linkend="mozilla-CHP-2-EX-9">Example 2-9</link> shows the updated XUL that uses
 1792: <filename>xfly.css</filename>.
 1793: </para>
 1794: 
 1795: <example id="mozilla-CHP-2-EX-9" label="2-9">
 1796: <title>XUL using external style data </title>
 1797: <programlisting>&lt;?xml version="1.0"?&gt;
 1798: &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;
 1799: <emphasis role="bold">&lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;</emphasis>
 1800: &lt;!DOCTYPE window&gt;
 1801: &lt;window title="Hello xFly"
 1802:   xmlns:html="http://www.w3.org/1999/xhtml"
 1803:   xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
 1804:   width="300"
 1805:   height="215"
 1806:   onload="centerWindowOnScreen( )"&gt;
 1807:  &lt;script type="application/x-javascript"   
 1808:   src="chrome://global/content/dialogOverlay.js" /&gt;
 1809:  &lt;vbox align="left" <userinput>id="vb"</userinput>&gt;
 1810:   &lt;label <userinput>id="xlabel"</userinput>
 1811:       value="Hello, Welcome to the xFly" /&gt;
 1812:   &lt;image src="http://books.mozdev.org/xfly.gif" /&gt;
 1813:   &lt;button label="hello xFly" oncommand="alert('hello.');" /&gt;
 1814:  &lt;/vbox&gt;
 1815: &lt;/window&gt;</programlisting>
 1816: </example>
 1817: 
 1818: <para>Note the extra stylesheet import statement at the top and the use of
 1819: the new <literal>id</literal> attribute on the label. When you
 1820: register the new files in your package with Mozilla, the
 1821: <filename>xfly</filename> directory in that stylesheet processing
 1822: instruction will point into your application directory structure (at
 1823: the <filename>skin</filename> subdirectory, and at a file named after
 1824: the directory itself, <filename>xfly.css</filename>). The label will
 1825: pick up the style information in the file that was previously defined
 1826: directly in its <literal>style</literal> attribute.
 1827: </para>
 1828: 
 1829: </sect3>
 1830: 
 1831: <sect3 role="" id="mozilla-CHP-2-SECT-5.5.2" label="2.5.5.2">
 1832: <title>The xFly script file</title>
 1833: 
 1834: <para>The next step is to take <indexterm id="IXT-2-506"><primary>xfly.js
 1835: file</primary></indexterm>
 1836: <indexterm id="IXT-2-507"><primary>JavaScript</primary><secondary>xfly.js
 1837: file</secondary></indexterm>
 1838: <indexterm id="IXT-2-508"><primary>packages</primary><secondary>xfly.js
 1839: file</secondary></indexterm>the scripting portion, as simple as it
 1840: is, out of the XUL file and put it into an external JavaScript file.
 1841: <link linkend="mozilla-CHP-2-EX-10">Example 2-10</link> shows a XUL file that gets a function
 1842: for the button from an external script file, given here as
 1843: <filename>xfly.js</filename>.
 1844: </para>
 1845: 
 1846: <example id="mozilla-CHP-2-EX-10" label="2-10">
 1847: <title>XUL using an external script </title>
 1848: <programlisting>&lt;?xml version="1.0"?&gt;
 1849: &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;
 1850: &lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;
 1851: &lt;!DOCTYPE window&gt;
 1852: &lt;window title="Hello xFly"
 1853:   xmlns:html="http://www.w3.org/1999/xhtml"
 1854:   xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
 1855:   width="300"
 1856:   height="215"
 1857:   onload="centerWindowOnScreen( )"&gt;
 1858: &lt;script type="application/x-javascript"   
 1859:   src="chrome://global/content/dialogOverlay.js" /&gt;
 1860: <emphasis role="bold">&lt;script type="application/x-javascript</emphasis>"   
 1861:   <emphasis role="bold">src="chrome://xfly/content/xfly.js" /&gt;</emphasis>
 1862:  &lt;vbox align="left" id="vb"&gt;
 1863:   &lt;label id="xlabel" 
 1864:       value="Hello, Welcome to the xFly" /&gt;
 1865:   &lt;image src="http://books.mozdev.org/xfly.gif" /&gt;
 1866:   &lt;button label="hello xFly" oncommand="greet( );" /&gt;
 1867:  &lt;/vbox&gt;
 1868: &lt;/window&gt;</programlisting>
 1869: </example>
 1870: 
 1871: <para>Note that the function <literal>greet( )</literal> is used to name
 1872: the action that is performed when the button is clicked. The
 1873: <literal>greet( )</literal> function is now defined in the
 1874: <filename>xfly.js</filename> file that the XUL file picks up with the
 1875: script import statement:
 1876: </para>
 1877: 
 1878: <programlisting><emphasis role="bold">&lt;script type="application/x-javascript</emphasis>"   
 1879:   <emphasis role="bold">src="chrome://xfly/content/xfly.js" /&gt;</emphasis></programlisting>
 1880: 
 1881: <para><link linkend="mozilla-CHP-2-EX-11">Example 2-11</link> contains all of the code needed for the
 1882: <filename>xfly.js</filename> file.
 1883: </para>
 1884: 
 1885: <example id="mozilla-CHP-2-EX-11" label="2-11">
 1886: <title>The contents of the xfly.js file </title>
 1887: <programlisting>function greet( ) {
 1888:   alert("Hello World");
 1889: }</programlisting>
 1890: </example>
 1891: 
 1892: <para>Save <filename>xfly.js</filename> in the <filename>content</filename>
 1893: subdirectory of the xFly application
 1894: (<filename>chrome/xfly/content/</filename>). The script import
 1895: statement above uses the <filename>chrome://</filename> URL to locate
 1896: scripts from directories that were registered with Mozilla.
 1897: </para>
 1898: 
 1899: </sect3>
 1900: 
 1901: <sect3 role="" id="mozilla-CHP-2-SECT-5.5.3" label="2.5.5.3">
 1902: <title>The xFly DTD</title>
 1903: 
 1904: <para>The final step in a basic <indexterm id="IXT-2-509"><primary>xfly.dtd
 1905: file</primary></indexterm>
 1906: <indexterm id="IXT-2-510"><primary>DTD</primary><secondary>xfly.dtd
 1907: file</secondary></indexterm>application setup is to generalize parts
 1908: of the interface that are written in a particular language, such as
 1909: English. When you create a <filename>locale</filename> subdirectory
 1910: for your package and place a DTD file that contains the English
 1911: strings in the user interface, you can refer to and load that DTD
 1912: just as you do with the CSS and script files.
 1913: </para>
 1914: 
 1915: <para>For example, to localize the text of the label and button elements in
 1916: the "hello xFly" example, you can
 1917: use a special syntax to tell Mozilla to use an entity rather than a
 1918: string. Because that entity is defined in
 1919: <filename>xfly.dtd</filename> and located in the locale subdirectory,
 1920: it can easily be swapped for an entity from a different language pack
 1921: when the user switches languages in Mozilla.
 1922: </para>
 1923: 
 1924: <para>Once again, the external file you create can be very simple. <link linkend="mozilla-CHP-2-EX-12">Example 2-12</link> contains the code needed for the
 1925: <filename>xfly.dtd</filename> file, which you create and save in the
 1926: <filename>locale</filename> subdirectory.
 1927: </para>
 1928: 
 1929: <example id="mozilla-CHP-2-EX-12" label="2-12">
 1930: <title>The contents of the xfly.dtd file </title>
 1931: <programlisting>&lt;!ENTITY label.val       "Hello, Welcome to the xFly " &gt;
 1932: &lt;!ENTITY btn.lbl         "hello xFly " &gt;</programlisting>
 1933: </example>
 1934: 
 1935: <para>The updated XUL file that uses this external DTD, then, appears in
 1936: <link linkend="mozilla-CHP-2-EX-13">Example 2-13</link>. Once you have made the final changes in
 1937: the XUL to refer to the external files you've
 1938: created, save the code in <link linkend="mozilla-CHP-2-EX-13">Example 2-13</link> as
 1939: <filename>xfly.xul</filename> in the
 1940: <filename>chrome/xfly/content/</filename> directory.
 1941: </para>
 1942: 
 1943: <example id="mozilla-CHP-2-EX-13" label="2-13">
 1944: <title>XUL using an external DTD file </title>
 1945: <programlisting>&lt;?xml version="1.0"?&gt;
 1946: &lt;?xml-stylesheet href="chrome://global/skin" type="text/css"?&gt;
 1947: &lt;?xml-stylesheet href="chrome://xfly/skin" type="text/css"?&gt;
 1948: &lt;!DOCTYPE window SYSTEM "chrome://xfly/locale/xfly.dtd" &gt;
 1949: &lt;window title="Hello xFly"
 1950:   xmlns:html="http://www.w3.org/1999/xhtml"
 1951:   xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
 1952:   width="300"
 1953:   height="215"
 1954:   onload="centerWindowOnScreen( )"&gt;
 1955: &lt;script type="application/x-javascript"   
 1956:   src="chrome://global/content/dialogOverlay.js" /&gt;
 1957: &lt;script type="application/x-javascript"   
 1958:   src="chrome://xfly/content/xfly.js" /&gt;
 1959:  &lt;vbox align="left" id="vb"&gt;
 1960:   &lt;label id="xlabel" 
 1961:       <userinput>value="&amp;label.val;"</userinput> /&gt;
 1962:   &lt;image src="http://books.mozdev.org/xfly.gif" /&gt;
 1963:   &lt;button <userinput>label="&amp;btn.lbl;"</userinput> oncommand="greet( );" /&gt;
 1964:  &lt;/vbox&gt;
 1965: &lt;/window&gt;</programlisting>
 1966: </example>
 1967: 
 1968: <para>Like the CSS and script file imports, the updated
 1969: <literal>DOCTYPE</literal> definition at the top of the file tells
 1970: Mozilla to load additional entities as part of the xFly package.
 1971: Those entities -- the English strings that display in the user
 1972: interface -- are defined so they can be localized or
 1973: internationalized without affecting the
 1974: application's structure.
 1975: </para>
 1976: 
 1977: <para>All three of these imports use the <filename>chrome://</filename> URL
 1978: to refer to resources that are internal to the xFly package. These
 1979: type of URLs can also refer to resources elsewhere in Mozilla, such
 1980: as image resources, strings that have already been defined in
 1981: entities, and functions from scripts such as
 1982: <literal>centerWindowOnScreen( )</literal>.
 1983: </para>
 1984: 
 1985: <para>When you finish setting things up in the package directories, you
 1986: should have a structure that looks like the tree structure in <link linkend="mozilla-CHP-2-EX-14">Example 2-14</link>. 
 1987: </para>
 1988: 
 1989: <example id="mozilla-CHP-2-EX-14" label="2-14">
 1990: <title>Tree structure of a completed sample xFly package </title>
 1991: <programlisting>chrome/
 1992:        xfly/
 1993:            content/
 1994:                   xfly.xul
 1995:                   xfly.js
 1996:                   contents.rdf
 1997:            locale/
 1998:                  en-US/
 1999:                       xfly.dtd
 2000:                       contents.rdf
 2001:            skin/
 2002:                   xfly.css
 2003:                   contents.rdf</programlisting>
 2004: </example>
 2005: 
 2006: </sect3>
 2007: </sect2>
 2008: <sect2 role="" id="mozilla-CHP-2-SECT-5.6" label="2.5.6">
 2009: <title>Registering a Package</title>
 2010: 
 2011: <para>Registering packages in Mozilla
 2012: <indexterm id="IXT-2-511"><primary>packages</primary><secondary>registration</secondary></indexterm>
 2013: <indexterm id="IXT-2-512"><primary>registration</primary><secondary>packages</secondary></indexterm>can
 2014: be confusing at first, so don't worry about
 2015: understanding everything at this point. Later chapters provide more
 2016: detailed information about packaging and registration, and you can
 2017: always copy the examples given here to install your own application.
 2018: In general, to make your package registerable, create manifests that
 2019: describe your package in terms that Mozilla can understand.
 2020: </para>
 2021: 
 2022: <para>Although it's customary to make registration a part
 2023: of the installation process by using the XPInstall API and
 2024: installation
 2025: <indexterm id="IXT-2-513"><primary>XPInstall</primary><secondary>registration
 2026: and</secondary></indexterm>
 2027: <indexterm id="IXT-2-514"><primary>registration</primary><secondary>XPInstall
 2028: API</secondary></indexterm>scripts, you need a simple way to register
 2029: the xFly application so you can see your work and test it as it
 2030: develops. For this purpose, hacking the
 2031: <filename>installed-chrome.txt</filename> file living
 2032: <indexterm id="IXT-2-515"><primary>installed-chrome.txt file</primary></indexterm>in
 2033: Mozilla's <filename>chrome</filename> directory will
 2034: do.
 2035: </para>
 2036: 
 2037: <para>The <filename>installed-chrome.txt</filename> file is a list of
 2038: packages and package parts that Mozilla should find and register on
 2039: start up. When you add entries to this file, you point to your
 2040: package and tell Mozilla to register that package when it starts up.
 2041: </para>
 2042: 
 2043: <para>Append the entries in <link linkend="mozilla-CHP-2-EX-15">Example 2-15</link> to the bottom of
 2044: the <filename>installed-chrome.txt</filename> file in the main chrome
 2045: directory.
 2046: </para>
 2047: 
 2048: <example id="mozilla-CHP-2-EX-15" label="2-15">
 2049: <title>Additions to the installed-chrome.txt file </title>
 2050: <programlisting>content,install,url,resource:/chrome/xfly/content/
 2051: skin,install,url,resource:/chrome/xfly/skin/
 2052: locale,install,url,resource:/chrome/xfly/locale/en-US/</programlisting>
 2053: </example>
 2054: 
 2055: <para>When Mozilla starts up, it looks for the package manifests, reads
 2056: them, and registers the xFly package.
 2057: </para>
 2058: 
 2059: <para>When others install your application and use it on their machines
 2060: (but do not use the hack to
 2061: <filename>installed-chrome.txt</filename>), you can provide them with
 2062: a JavaScript installation file that downloads and registers your
 2063: package from a web page. See <link linkend="mozilla-CHP-6">Chapter 6</link> for more
 2064: information about these installation files and the XPInstall
 2065: technology they are based upon.
 2066: </para>
 2067: 
 2068: </sect2>
 2069: </sect1>
 2070: 
 2071: <sect1 role="" id="mozilla-CHP-2-SECT-6" label="2.6">
 2072: <title>Launching the Application</title>
 2073: 
 2074: <para>Once your package is registered, you can use these startup options to
 2075: access your package directly.
 2076: </para>
 2077: 
 2078: <sect2 role="" id="mozilla-CHP-2-SECT-6.1" label="2.6.1">
 2079: <title>Windows launch</title>
 2080: 
 2081: <para>In the Mozilla install directory, launch xFly at
 2082: <indexterm id="IXT-2-516"><primary>xFly</primary><secondary>Windows
 2083: launch</secondary></indexterm>
 2084: <indexterm id="IXT-2-517"><primary>Windows</primary><secondary>xFly
 2085: launch</secondary></indexterm>the command prompt with:
 2086: </para>
 2087: 
 2088: <programlisting>mozilla -chrome chrome://xfly/content/</programlisting>
 2089: 
 2090: <para>You can also launch xFly from a shortcut on your desktop by
 2091: right-clicking on the existing Mozilla icon and selecting Properties.
 2092: In the Target area of the Properties box, add the following text at
 2093: the end of the line:
 2094: </para>
 2095: 
 2096: <programlisting> -chrome chrome://xfly/content/</programlisting>
 2097: 
 2098: <para><link linkend="mozilla-CHP-2-FIG-6">Figure 2-6</link> shows what the new properties box should
 2099: look like.
 2100: </para>
 2101: 
 2102: <figure id="mozilla-CHP-2-FIG-6" label="2-6">
 2103: <title>Modified shortcut properties</title>
 2104: <graphic fileref="figs/moz_0206.png"/></figure>
 2105: 
 2106: <sect3 role="" id="mozilla-CHP-2-SECT-6.1.1" label="2.6.1.1">
 2107: <title>Unix launch</title>
 2108: 
 2109: <para>In the Mozilla install directory, launch xFly
 2110: <indexterm id="IXT-2-518"><primary>xFly</primary><secondary>Unix
 2111: launch</secondary></indexterm>
 2112: <indexterm id="IXT-2-519"><primary>Unix</primary><secondary>xFly
 2113: launch</secondary></indexterm>with:
 2114: </para>
 2115: 
 2116: <programlisting><userinput>./mozilla -chrome chrome://xfly/content/</userinput></programlisting>
 2117: 
 2118: </sect3>
 2119: 
 2120: <sect3 role="" id="mozilla-CHP-2-SECT-6.1.2" label="2.6.1.2">
 2121: <title>Macintosh launch</title>
 2122: 
 2123: <para>Start xFly by creating a text file on your desktop
 2124: <indexterm id="IXT-2-520"><primary>xFly</primary><secondary>Macintosh
 2125: launch</secondary></indexterm>
 2126: <indexterm id="IXT-2-521"><primary>Macintosh</primary><secondary>application
 2127: launch</secondary></indexterm>with the following content:
 2128: </para>
 2129: 
 2130: <programlisting><userinput>-chrome chrome://xfly/content/</userinput></programlisting>
 2131: 
 2132: <para>You can either drag this text file onto your Mozilla icon to launch
 2133: the application or set the text file's creator type
 2134: to <literal>MOZZ</literal>. If you change the creator type, you
 2135: should be able to double-click on the text file to launch Mozilla.
 2136: </para>
 2137: 
 2138: <para>Once you register your application, you are free to continue
 2139: developing it in the various component subdirectories and relaunching
 2140: it as it progresses. You can add new XUL files in the
 2141: <filename>content</filename> directory, for example, that are invoked
 2142: from buttons using <literal>window.openDialog( )</literal> event
 2143: handlers.
 2144: </para>
 2145: 
 2146: <para>You can add new widgets to <filename>xfly.xul</filename>, add new
 2147: styles to <filename>xfly.css</filename> that apply to the XUL, add
 2148: new functions to <filename>xfly.js</filename>, or use existing
 2149: functions in the Mozilla source code that you can find new ways to
 2150: use in your own application.
 2151: </para>
 2152: 
 2153: <warning id="" role="ora">
 2154: If you have trouble editing and relaunching the xFly application, 
 2155: there are a couple of platform specific culprits to look into. 
 2156: On Windows, the Quick Launch feature may prevent you from seeing changes to your files. 
 2157: On Unix, file permission conflicts can also cause problems viewing your files. 
 2158: Making sure that Quick Launch is disabled and double checking file permissions may help get xFly working on your system.
 2159: </warning>
 2160: 
 2161: <para>The steps described in this chapter -- creating a basic XUL file,
 2162: adding features, displaying that XUL file as a standalone window,
 2163: organizing the code into separate files and a package structure, and
 2164: registering and launching that package -- are the basic building
 2165: blocks of all Mozilla applications. When you get a feel for
 2166: what's going on here, you'll be
 2167: able to quickly understand and use the topics described in the rest
 2168: of the book.
 2169: </para>
 2170: 
 2171: 
 2172: 
 2173: </sect3>
 2174: </sect2>
 2175: </sect1>
 2176: </chapter>

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