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

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