Tài liệu Creating Applications with Mozilla-Chapter 3. XUL Elements and Features- P1 ppt

XUL Elements and Features- P1 The XML-based User-interface Language XUL includes all of the basic widgets you need to build application user interfaces.. Other types of document objects

Chapter 3 XUL Elements and Features- P1

The XML-based User-interface Language (XUL) includes all of the basic widgets you need to build application user interfaces These interfaces

include tabs, text areas, buttons, and menus, as well as handy interfaces you may not have thought you needed, such as the <stack> widget or

<colorpicker>

Chapter 2 introduced some of the XUL elements that make up a window and basic applications This chapter examines XUL elements and features in more detail, describing the rationale behind them, their look and behavior, and common usage Though not comprehensive, the chapter provides more than enough information about XUL to get you started on building your own Mozilla applications, particularly when used in conjunction with the XUL reference in Appendix C

The elements described here, such as menus, buttons, trees, and boxes, are needed in almost any type of application, and most of the examples are generic, so you can plug them into any application or customize them to your needs We've packed a lot of information in this chapter and it will be a useful reference as you begin to develop your applications

3.1 The XUL Document Object

At the core of a XUL file is the document object As in HTML,

document is an object that represents the XUL document itself the

content as opposed to the window that surrounds it The document

provides methods for getting individual elements, manipulating the structure

of the document, or updating style rules

A document object provides methods such as getElementById,

getElementsByTagName, createElement, and

createTextNode for DOM querying and manipulation of the actual document Further details about the DOM are available in Chapter 5

Other types of document objects include the width and height of the

window, a popupNode property that accesses the elements currently

displaying a pop up (a XUL widget that attaches to another widget and appears above it holding some content), a tooltipNode property that accesses the element currently displaying a tooltip, and a

documentElement property that accesses the body of the document: var docEl = document.documentElement;

var secondLevelNodes = new Array( );

for (var I=0; I<docEl.childNodes.length;I++) { secondLevelNodes[I] = docEl.childNodes[I];

}

This example creates an array of all the second-level nodes in relation to the document, and could be extended to walk to the whole tree Using nodes in the structural representation of the document to get to other nodes in this way allows you to quickly access and change any part of a document with script

The document object is global only for the particular scope that you are working in, so every window, dialog, and page has its own document object To access it, just use the document prefix followed by the name of the property you want to access:

var title = document.getElementById("bookTitle");

It is possible to access document outside the current scope for example, the window that opened another one using window.opener:

var title =

window.opener.document.getElementById("bookTitle");

3.1.1 XUL Parsing and the Document Object Model

Mozilla runs XUL documents through the Expat XML parser to check that they are well-formed Expat is an XML parser library, written in C, that was integrated into Mozilla at the early stages of the code rewrite when the

source was made open

During parsing, a content model based on the Document Object Model

(DOM) is built, allowing access to the content in a way that facilitates

dynamic manipulation Once the XML tags are in the correct namespaces, Mozilla parses the document a second time to ensure that XUL tags

themselves are valid If this fails, or if the document does not conform to the syntax rules, an error appears in your window so you can address the

problem

The parsing process builds an internal tree structure that can be used as a handle for querying, modifying, and copying documents the structure

represents Chapter 5 describes in more detail the relationship between

JavaScript (the main scripting engine used in Mozilla) and the DOM, and it goes further with examples of commonly used methods for querying and modifying a XUL document To view that internal tree, you can use a tool called the DOM Inspector, which is a Mozilla application that lets you view

and manipulate the document object model of any XUL file or web page For more information about the DOM Inspector, see Appendix B

3.2 Application Windows

<window> is just one of the possible root elements of a XUL document, the others being <overlay>, <dialog>, <page>, and <wizard>

Overlays play an especially important role in managing and modularizing the code in your XUL application, so the section Section 3.11, later in this chapter, is dedicated to them

The remaining root elements all have the XUL namespace and XUL window attributes and properties All have a XUL document object Yet, added features exist for each Which element you choose for the XUL document depends on the purpose of the window A <window> is typically top-level,

a <dialog> is secondary, appearing above another window, a <page> is

a document that appears in a frame, and a <wizard> stores a set of

subsections for loading one at a time through a step-by-step process

3.2.1 Dialogs

Dialogs usually carry out specific functions like displaying a message or getting information from the user The <dialog> element was created relatively late in the XUL toolkit development cycle to cater for some

special needs of dialog windows, including their position relative to other windows (particularly the main application window) and the existence of buttons for accepting or rejecting a particular operation A dialog in XUL appears in Example 3-1

Example 3-1 XUL dialog

<dialog id="turboDialog" buttons="accept"

buttonpack="center"

xmlns="http://www.mozilla.org/keymaster/gatekeeper/ there.is.only.xul"

title="Empty the Cache"

onunload="SetTurboPref( );">

As you can see, the dialog includes the XUL namespace and the id and title attributes However, some attributes, such as buttons and

buttonpack, don't appear in a regular window context

Dialogs commonly require the user to take some action or make a choice, so the button attributes are provided for this purpose In addition to buttons and buttonpack, there are special event handlers on the dialog element ondialogaccept, ondialogcancel, and ondialoghelp that correspond to the buttons typically displayed and can execute code in

response to user input As with onunload, you can place a function in the ondialogaccept event handler that executes when the user clicks the

OK button:

<dialog id="flush" buttons="accept"

buttonpack="center"

xmlns="http://www.mozilla.org/keymaster/gatekeeper/ there.is.only.xul"

title="&exitWarningTitle.label;"

ondialogaccept="doCacheFlush( );">

3.2.2 Pages

The <page> element is designed specifically for documents that are loaded

in a frame of a higher-level document They are not top-level windows themselves In Mozilla, the page element is used often in the preferences dialog to represent the various preference panels

As with the dialog in Example 3-1, the <page> element in Example 3-2 includes the familiar namespace attribute (xmlns) and load handler

(onload) The headertitle attribute is also used for the top of the page, which itself gets loaded into another window that has its own title

Example 3-2 XUL page

<page

xmlns="http://www.mozilla.org/keymaster/gatekeeper/ there.is.only.xul"

onload="parent.initPanel('chrome://communicator/con tent/pref/pref-fonts.xul');"

headertitle="&lHeader;">

An application of the page element in Mozilla is in the global preferences for the whole suite of Mozilla applications Figure 3-1 shows the layout of this preferences panel In Example 3-2, the entity in the header title,

&lHeader;, resolves to "Languages" and be displayed above the

individual preference panel page

The main preferences window is a XUL dialog, and the content is split in two On the left is a tree from an overlay that contains the preference topics, and on the right is a XUL page loaded into an <iframe>

<iframe id="panelFrame" name="panelFrame"

style="width:0px" flex="1"/>

Figure 3-1 Preferences panel loaded as a page

As shown in Figure 3-1, selecting one of the topics in the left panel changes the page that is loaded into the frame Although the changeover requires quite a bit of scripting in practice, at a basic level, it is just a case of

changing the src attribute on the frame:

"src", "chrome://communicator/content/pref/pref-navigator.xul" );

3.2.3 Wizards

This type of window is designed for a very specific type of functionality

to walk the user through a step-by-step process, with each step represented

by a different screen Using one window after another can create

inconsistencies, including different sizes and performance issues These can

be especially bad when you try to create an interface that guides the user through a new process, such as setting up an account of some kind Thus, the wizard element was adapted from the wizard paradigm now common in some native toolkits Example 3-3 shows how Mozilla handles wizard

dialogs

Example 3-3 A XUL wizard

<wizard id="NewAccount" title="Account Set-up"

onwizardcancel="return Cancel( );"

onwizardfinish="return Finish( );"

onload="onLoad( );"

width="44em" height="30em"

xmlns="http://www.mozilla.org/keymaster/gatekeeper/ there.is.only.xul"

xmlns:nc="http://home.netscape.com/NC-rdf#">

<wizardpage id="wPage1" pageid="page-1"

label="New Account"

onpageshow="return acctNamePageInit( );"

onpageadvanced="nextPage(this)">

<vbox flex="1">

<description>Welcome and enjoy the

wizardry</description>

<image src="page1.png"/>

</vbox>

</wizardpage>

<wizardpage id="wPage2"/>

<wizardpage id="wPage3"/>

</wizard>

A wizardpage is similar to a page because it has a surrounding window into which it is loaded The difference, as shown in Example 3-3, is that in the wizard, the pages exist as a set within the window-level <wizard> element Order wizardpages in the sequence you want them to appear on the screen When the user accepts one page, the next one is loaded In Example 3-3, the content of the first page is text and an image, and the other pages define only id attributes (though this is exactly how you might set them up

if their actual content were overlaid into this wizard at runtime) You can use the wizard code in Example 3-3 by including the <?xml

version="1.0"?> preamble at the top, adding label attributes to

pages two and three, and seeing the pages advance as you click the buttons that guide the wizard process when you load the XUL file into the browser

3.3 Application Widgets

Like most applications, yours may rely on menus and toolbars as part of the basic user interface Menus and toolbars are common, multipurpose widgets that are familiar to most users Menus often appear as part of a menu bar that organizes all of the capabilities of the program, or they can be single menus for presenting a simple list of choices Buttons provide quick access to the most commonly used tasks and help get information back from the user Beyond these basics, however, XUL provides widgets for creating almost any kind of interface (and the flexibility of Mozilla's presentation layer means you can make even the most prosaic menus look any way you want)

3.3.1 The Toolbox

As your applications grow in complexity and provide more services to the user, the toolbox can be a good way to organize menus, toolbars, and other widgets A <toolbox> is a special container for holding one or more toolbars and/or menu bars A Mozilla toolbar implements a

toolbargrippy and a box that contains children The

toolbargrippy is a bar on the lefthand side used for collapsing and expanding the bar This useful method allows users to control the space that

is available to them onscreen

3.3.1.1 Toolbars

The <toolbar> element shown in Example 3-4 contains buttons used to carry out various application functions Buttons are the most common

children of a toolbar, but they are by no means the only widgets or content you can put in there

Example 3-4 Toolbar with buttons and spacing

<toolbox>

<toolbar id="fixed-toolbar"

class="toolbar-primary"

tbautostretch="always" persist="collapsed"> <toolbarbutton id="newfileBtn" label="New"

oncommand="doNew( );" />

<toolbarseparator />

<toolbarbutton id="openfileBtn" label="Open" oncommand="doOpen( );" />

<spacer flex="1" />

</toolbar>

</toolbox>

To apply spacing between elements, the <spacer> element can be used In Example 3-4, all space that remains after the buttons are drawn goes after the buttons because the spacer there is flexible and the buttons are not Space added elsewhere with other <spacer> elements is determined by ratio of the flex values on the elements competing for layout space Extending the toolbar in Example 3-4, you can add a print button on the far right:

<toolbarbutton id="newfileBtn" label="New"

oncommand="doNew( );" />

<toolbarseparator />

<toolbarbutton id="openfileBtn" label="Open"

oncommand="doOpen( );" />

<spacer flex="1" />

<toolbarbutton id="printBtn" label="Print"

oncommand="doPrint( );" />

The <toolbarseparator> element does not create additional spacing between the first two toolbarbuttons, but there is space between them and the print button, which is pushed to the far right because the flex attribute of the spacer in between is set to 1

3.3.1.2 Menu bar

Among the other most common nested elements within a toolbox is a XUL

<menubar> <menubar> is a container much like the toolbar that has one

or more menus as its children

<menubar id="fixed-menubar">

<menu label="Quantity" />

<menu label="Color" />

</menubar>

//FIXME did we loose content here?

There is one caveat in menubar behavior that you should be aware of

On the Mac OS, application menu bars appear at the top of the screen

If you have any nonmenu elements contained in your menu bar widget, they are ignored because the OS does not know how to display them