Creating Applications with Mozilla-Chapter 3. XUL Elements and Features- P4

This flexibility has the nice effect of letting you get the buttons in a particular area by using the getElementsByTagName method with, for example, the tag name "button." A common form

Chapter 3 XUL Elements and Features- P4

Figure 3-7 Checkbox widget

Clicking on the box sets the checked attribute, for which the check

indicates a positive value You can set this attribute in script to give the checkbox an initial value

3.6.3 Buttons

A button is a multipurpose widget that commonly lives in toolbars and

dialog boxes The two button elements, <button> and

<toolbarbutton>, are essentially the same Often only the class attribute values distinguish the two You can use a <toolbarbutton> outside a toolbar or use a <button> inside a toolbar, though in practice, the two usually stay in their respective domains This flexibility has the nice effect of letting you get the buttons in a particular area by using the

getElementsByTagName method with, for example, the tag name

"button."

A common form of the button contains text and an image, with image on the left and the text to the right by default However, you may want to take advantage of some of the classes available in Mozilla to define a different orientation, or you can simply write your own style rules for your buttons.[1]

The text that appears on the button is contained in the label attribute and shown in this example:

<button id="newfileBtn"

tooltiptext="New File"

oncommand="doNew( )"

label="New"/>

You can associate the image with the button using the src attribute, but the

more common way is to use the list-style-image style rule in CSS,

as in the following snippet of code that uses the id style selector:

#newfileBtn

{

list-style-image:

url("chrome://editor/skin/images/newfile.gif");

}

3.6.3.1 Button types

Mozilla provides more than the standard "click" and "go" buttons in its

toolkit Table 3-3 describes the various button types in Mozilla

Table 3-3 Button types

Type Usage Description

Menu integrated into the button with small arrow icon

Dual Menu type= "menu-button"

Menu appears distinct from the button, in separate clickable area Checkbox type= "checkbox" When selected, remains

Type Usage Description

in a depressed state and toggles back to its natural state when selected again

Designed to be part of a group; only one button is selectable at a time

Disclosure dlgtype= "disclosure" Shows/Hides a portion

of a dialog window

Default dlgtype= "accept" Performs the default

action for a dialog

Closes the dialog and does not carry out the default action

Help dlgtype= "help" Activates

context-sensitive help

Taking one of the button types in Table 3-3 as a mini-case study, you could

use a button with the type menu-button to display more than one option

at a time The default orientation for this type of button is for the menu to be

to the right of the button Mozilla uses buttons of type menu-button for

its back and forward buttons, in which the menu items hold previously

visited pages Figure 3-8 shows the appearance of the browser's back button displaying the last several pages viewed

Figure 3-8 menu-button for browser's back functionality

Other possible uses include options for different variations of the same feature, such as a New button that displays New File, New Project, or New Template options The button action is the default option and the

menuitems contain the rest of the choices

3.6.3.2 Dialog buttons

The last four items in Table 3-3 are button types that make most sense in, and were designed especially for, dialog windows The easiest way to

include them in dialogs is to use the buttons attribute on the <dialog> element, which displays them automatically, as shown here:

<dialog

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

buttons="accept,cancel,help"

buttonpack="center"

ondialogaccept="return onAccept( );"

ondialogcancel="return onCancel( );"

ondialoghelp="return doHelpButton( );">

The functions activated when these buttons are clicked on are defined in the ondialogaccept, ondialogcancel, and ondialoghelp event handler attributes These event handler shortcuts are best if you simply want

to inherit the default button text (Ok, Cancel, and Help) In cases when you want your own text, or want some extra control over the scripting, you can define your own button with the dlgtype attribute:

<button dlgtype="accept"

label="Go For It!"

oncommand="doExtraFunction( )"/>

The buttonpack attribute determines whether the buttons appear on the right, left, or center of the window If no value is given, the default platform orientation takes effect On Windows, the default is the right, and on Unix, it's the center

Notes

[1] Unfortunately, button skins and the class attributes that associate them with button widgets change too often to list here Some classes like

"toolbar-primary" tend to be reused often for buttons in Mozilla, but the best way to find and use classes is to consult the source code itself or to

create your own

3.7 Widget Interaction

At a level above the use of widgets for different, singular functions in the application interface, Mozilla provides tools for hooking things together and creating application logic that can make your interfaces work more

consistently and handle more complex tasks If you have different elements

in your application that execute the same function, for example, the

command and observer system is the ideal way to facilitate reuse Or you can use command sets to define command sets and key sets that can be

overlaid and made available in different parts of your application, similar to how the cut and paste commands and others are spread over the Mozilla user interface but defined in a centralized file

3.7.1 Broadcaster and Observers

Broadcasters and observers are a mechanism for making any number of elements aware of state and event information from a single, "broadcasting" element That broadcasting element can be an actual <broadcaster> or a regular element that broadcasts its state with special attributes A common example of broadcasting is the disabling of a group of elements a menu item and a separate button for viewing source, for example when the

source for a web page is not available

The state of a broadcaster has to be changed explicitly for its observers to be updated:

<broadcasterset>

<broadcaster id="save_command" disabled="false"/>

</broadcasterset>

Once a broadcaster is defined, a XUL file may define elements that observe the broadcast command:

<button id="new" label="Save File"

observes="save_command"/>

<key id="key_new" xulkey="true" key="s"

observes="save_command" />

<menuitem id="new_menuitem" label="New"

observes="save_command"/>

Observing elements can also be more specific about the attribute they want

to mimic This is done by using the <observes> element:

<menuitem id="new_menuitem" value="New"

observes="open_new"/>

<observes element="open_new"

attribute="disabled"/>

</menu>

The element attribute associates the broadcaster and attribute tells the <menuitem> element to mimic the behavior of the broadcaster's

"disabled" attribute

3.7.2 Commands

Any number of commands can be contained in a <commandset>, and multiple sets can exist for different events in your application It is also possible for sets to contain other command sets, mixed with commands or on their own The idea is that there will be one base set that all other sets must

inherit from; this base set can be defined in the top-level XUL file for your application The following code has a command set that has its own

commands and that pulls in a second set defined elsewhere

(moreEditItems)

<commandset id="EditItems"

oncommandupdate="updateCommandsetItems(this)"

commandupdater="true" events="select">

<commandset id="moreEditItems" />

<command id="cmd_cut"

oncommand="goDoCommand('cmd_cut');"/>

<command id="cmd_copy"

oncommand="goDoCommand('cmd_copy');"/>

<command id="cmd_delete"

oncommand="goDoCommand('cmd_delete');"/>

</commandset>

The command updater is the mechanism used to pass command events between widgets in the UI When an event is carried out, the message filters through to the command sets Thus in the example above, if the select event is activated, all UI elements in this commandset become active For example, setting the disabled attribute on a command set for saving disables all functional elements depending on it such as a menu item, a toolbar button, or a pop-up menu

There are a number of ways to trigger the command updater First, associate

a widget with a particular command by using the command attribute:

<button id="cut-item" label="Cut" command="cmd_cut"

enabled="true"/>

When this button is clicked, the command (cmd_cut) is located and carried out, firing the goDoCommand routine for that particular command

Alternatively, your application might have a select event for a text element

or an image When the select event is fired, the message filters through to the command set, which, in turn, updates (by using oncommandupdate) the widgets-associated button with the commands

The <keyset> element is a container for key elements Key elements are used to execute commands from a keystroke combination The keys Ctrl-Shift-s can be defined to execute a Save As command in your application (and that command can actually be defined in a command element):

<key id="key_saveas" key="s"

modifiers="control,shift" command="cmd_saveas"/> The key element has various special attributes like key, which is used to set

an identifier shortcut key, or the modifiers attribute to set the trigger key For example, modifiers="accel" would be the Ctrl key on Windows and GTK Unix platforms and the command button on Macintosh

Example 3-15 shows a simple window that you can load up that has all

element sets: commands, broadcasters, and keys

Example 3-15 Shortcut keys with command observers

<?xml version="1.0"?>

<window id="hello-goodbye"

title="Hello Goodbye"

xmlns:html="http://www.w3.org/1999/xhtml"

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

style="min-width:100px;min-height:100px;background-color:white;">

<broadcasterset id="broadcasterset">

<broadcaster id="cmd_hello"

oncommand="alert('Hello There!');" />

</broadcasterset>

<keyset id="keyset">

<key id="key_h" key="H" observes="cmd_hello" modifiers="accel,shift" />

<key id="key_g" key="G" command="cmd_goodbye" modifiers="accel,shift" />

</keyset>

<commandset id="commandset">

<command id="cmd_goodbye"

oncommand="alert('Goodbye!');" />

</commandset>

<spacer flex="1"/>

<label value="hello/goodbye"/>

<textbox value="type ctl+shft+h"/>

<textbox value="type ctl+shft+g"/>

<spacer flex="1"/>

</window>

3.8 Content Panels

Content widgets allow you to load content into the UI for display These widgets browser and editor provide a window into which you can load In the standard browser, these documents can be written in HTML, XML, text, or other supported content types

3.8.1 Browser and IFrame

The <browser> element displays online content and provides full

browsing capabilities to your application, such as navigation features or maintaining a history

<browser id="content" type="content-primary"

src="ch3.html"/>

The behind-the-scenes implementation for browser gives you access to certain interfaces that can be used in your scripts These interfaces include:

• nsIDocShell

• nsIWebNavigation

• nsIMarkupDocumentViewer

• nsIContentViewerEdit

• nsIContentViewerFile

• nsIWebBrowserFind

• nsIDocumentCharsetInfo

Without going into detail, these interfaces all provide sophisticated

functionality for web browsing and other browser-like services, and are made available to JavaScript in the application interface You can explore them further by looking at the interfaces themselves at the IDL files of the same name in the Mozilla source tree

If you would like to learn more about these available interfaces, the best place to look is the source code The two recommended files to start with are browser.xml, which shows how the interfaces are exposed, and navigator.js, which shows how they are used Both files can

be browsed on the online Mozilla Cross Reference, at

http://lxr.mozilla.org

An alternative to <browser> is the <iframe> It's similar to the browser widget in appearance, but better suited for simple or ephemeral content It's often used as a preview window in HTML/XML editors and other

WYSIWYG applications iframes can also be good for dynamic document editing, as in the following example, in which the frame provides access to the document loaded as content This can then be written to:

<iframe id="simple-content" />

The document's open( ), write( ), and close( ) methods, which are standard in the JavaScript engine, are used to write to the document: var doc = window.frames[1].document;

doc.open( );

doc.write("<html><body>Come fly with me

</body></html>");

doc.close( );

In this code snippet, you get a handle to the particular frame that you want

by using window.frames, which returns an array of all frames contained

in a document There can be multiple frames in a document, which are

indexed Here it is assumed that we get the second (1 in a zero-based array) frame The doc variable has a reference to the content area and uses the methods available on the document object to write content in this case, HTML

Ideas for using content panels include:[1]

• Create HTML or XML help pages for your application and upload them in a ready-made help browser

• Create a previewer: test your XML, HTML, or CSS layout and styling

in Gecko one of the most standards-compliant layout engines

around

• A slight variation of the previous use, you could use mini-versions inline in dialogs to load up examples that change depending on the selection of the user from a number of choices (a font previewer, for example)

• Pop ups contained in a window for display of web content

3.8.2 Editor