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

Chapter 3. XUL Elements and Features- P3 Figure 3-5. Multilevel tree hierarchy 3.4.2.4. Using trees in XUL templates XUL templates are special built-in structures that allow dynamic updating of XUL elements and that are often used with trees and list boxes. Templates harness the power of the Resource Description Framework (RDF) to pull data from external datasources and dynamically create or update content in the UI. The following code extract shows the basic structure of a XUL template for displaying the browser history in Mozilla: <template> <rule> <treechildren> <treeitem uri="rdf:*" rdf:type="rdf:http://www.w3.org/1999/02/22-rdf- syntax- ns#type"> <treerow> <treecell label="rdf:http://home.netscape.com/NC-rdf#Name"/> <treecell label="rdf:http://home.netscape.com/NC-rdf#URL"/> <treecell label="rdf:http://home.netscape.com/NC-rdf#Date"/> <!-- further cells --> </treerow> </treeitem> </treechildren> </rule> </template> For each entry or row in the browser history, the template extracts information from the datasource and renders it in a treecell. It then updates it each time a page is visited. For a more detailed discussion, refer to Chapter 9 . 3.4.2.5. Custom tree views Custom views extend upon the static presentation of data in a tree with more flexibility, different ways to present the same data, and interfaces for defining behavior related to content. The functions include intercepting a treeitem selection and carrying out some functionality, populating or getting values from the tree, and returning the number of rows currently in the tree. The first thing you have to do to build a custom view is instantiate your tree and then associate a view object with it, commonly known as a view. document.getElementById('main- tree').treeBoxObject.view=mainView; In this example, the view that is exposed in the nsITreeView XPCOM object is essentially the lifeline for the tree, supplying the data that populates the view. The view is assigned to the code object that contains all the functions available to it and your implementation of what you need to do when they are activated. Here is a large subset of the functions available to the view object: setTree(tree) Called during initialization and used to connect the tree view to the front end. This connection ensures that the correct tree is associated with the view. getCellText (row,column) Returns the text of a particular cell, or an empty string if there's just an image in it. rowCount Set up the number of rows that you anticipate for your tree. cycleHeader(index) Called when you click on the header of a particular column. toggleOpenState Put code in here to be carried out when the view is expanded and collapsed. setCellText (row, colID, value) Called when the contents of the cell have been edited. performAction (action) An event from a set of commands can be invoked when you carry out a certain action on the outliner. The tree invokes this method when certain keys are pressed. For example, when the ENTER key is pressed, performAction calls with the "enter" string. There are more local conveniences in the form of PerformActionOnRow and performActionOnCell. selectionChanged Should be hooked up to the onselect handler of the <tree> element in the XUL content. 3.4.3. Grid A <grid> is another XUL table structure, designed to be more flexible with the content it can hold than the other tabular widgets. Example 3-12 shows a two-column grid that holds text input boxes and labels for them. Example 3-12. XUL grid <grid> <columns><column flex="1"/><column flex="2"/></columns> <rows> <row align="center"> <label value="Title"/> <textbox id="title-text" oninput="TextboxInput(this.id)"/> </row> <row align="center"> <label value="Author"/> <textbox id="author-text" oninput=" TextboxInput(this.id)"/> </row> <row align="center"> <label value="About"/> <textbox id="about-text" oninput=" TextboxInput(this.id)"/> </row> </rows> </grid> In a grid, the number of columns needs to be defined and placed in a <columns> set. In Example 3-12 , the first column holds the labels and the second contains the text boxes. These two columns are horizontal to each other and in rows for easy association. The flex is greater on the second column, allowing more space for the text input boxes. As with all examples in this chapter, you can see Example 3-12 in action by adding the XML processing instruction at the top and surrounding the grid in a basic window root element. 3.5. Words and Pictures The text widgets described here are used to label other widgets, or simply to display messages or instructions to the user in the interface and include a text input widget. Images can be displayed with the main image element or in various ways on other elements, such as buttons or menus. 3.5.1. Text Input The <textbox> element is a text input box not unlike the HTML <textarea> element. The default <textbox> element has a single line. <textbox id="singleFlyInput" /> However, setting the multiline attribute makes it into a larger text area. <textbox id="multiFlyInput" value="Fly Name" multiline="true" rows="4" /> A multiline textbox defaults to three lines unless constricted by a fixed size on a container or stretched out with flex. To force the number of lines, use the rows attribute. If you want to restrict the number of characters inputted, set the size attribute to a numeric value. <textbox id="holdtheFlyInput" cols="3" rows="2" /> The initial value of an input widget is blank if no value is specified. Setting the readonly attribute to true or false can control editing access. 3.5.1.1. Autocomplete Autocompletion is the process of automatically finishing a user's input by offering possible choices, or completions, when something is typed in. In Mozilla, this mechanism is simply known as autocomplete, and the textbox widget is used for this process in such places as the browser URL bar and in the address area of the mail compose window. Example 3-13 shows the code from the Open Web Location dialog, which provides autocompletion. Example 3-13. Text autocomplete <textbox id="dialog.input" flex="1" type="autocomplete" searchSessions="history" timeout="50" maxrows="6" disablehistory="false" oninput="doEnabling( );"> <menupopup id="ubhist-popup" class="autocomplete- history-popup" popupalign="topleft" popupanchor="bottomleft" onpopupshowing="createUBHistoryMenu(event.target);" oncommand="useUBHistoryItem(event.target)"/> </textbox> The first thing to note is the nested <menupopup>. This pop up holds the choices in a drop-down format. The relevant attribute in this example is type on the <textbox>, which has a value of autocomplete. Figure 3-6 shows the autocomplete widget. As the user types the URL into the textbox, auto completion kicks in and the values are retrieved to show in the pop-up list, from which the user can then choose. When similar values are input regularly, autocomplete can be a great time-saving feature. Figure 3-6. Autocomplete for Open Web Location 3.5.2. Text Display Three tags available in XUL handle basic text display in the UI, and each has its own context for use. They include a <caption>, a <label>, and a <description> element. The caption is designed specifically for the text that appears inline in the border of a group box. You can control where the caption appears by putting the caption element above or below the other content in the group box: <groupbox id="textWidgetsBox"> <caption id="textTitle" label="Text Widgets"/> <!-- content here --> </groupbox> label is more flexible than caption because it isn't tied to a particular widget and can even be used as a standalone. For longer text, the <description> element is best. You can embed text in the description element and have it wrap to the maximum size of the containing element: <description> The mozdev.org site provides free project hosting for the Mozilla community. You are welcome to take a look at the more than 60 projects hosted on the site or to start your own development project. </description> Or you can use the value attribute when you're sure the text will not overflow. In this case, <description> is interchangeable with the <label> element for use in identifying other items in the UI: <description value="Start a project today." /> 3.5.3. Images XUL supports the display of images in the native web formats of JPEG, PNG, and GIF. Most images you will find in the Mozilla UI are GIF files, which retain the best quality when compressed. Chapter 4 discusses theme issues and considerations in more detail. The basic syntax for displaying an image is: <image src="myImage.png" /> The <image> element is analogous to the HTML <img> element. The image to be displayed is directly associated with the element using the src attribute. You can also use list-style-image, which is a CSS2 property used to associate an image with an element. To do this, you need a style selector -- in this case, the id. <image id="foo" /> The style property takes a value of src, which has one parameter, the image, or a chrome or resource URL pointing to the image. #foo { list-style-image: url("myImage.png"); } src is good for single images and for convenience, but in general, using the CSS property is recommended because it follows the principal of separating functionality from presentation and it better fits into a theme-swapping architecture, as used in the Mozilla suite. Many in the open source community feel that PNG would have been a more natural choice for the project because it is a free format. Efforts to make this switch have been held up by a bug in gamma-corrected CSS color values and specified in both CSS1 and CSS2. 3.5.3.1. Images in other XUL elements Image display is not the sole province of the image element. Using the list-style-image property, you can attach images to almost any element. For example, the tree widget has a couple of its own special [...]... incorporate HTML when you use the correct namespace, the existence of XUL widgets such as the textbox, checkbox and radio group selector obviates the need for HTML elements 3.6 .1 Radio Radio groups are useful UI controls that present the user with a choice of options in XUL In HTML, radio choices are represented by the element with the type attribute set to the value of radio, all wrapped in a... group="flyTypes" label="Syrphidae" oncommand="chooseType(this);"/> The options must be enclosed in the element, and each one is represented by a element The important attributes are the id on the and the group attribute on the elements These attributes have to be... to make radio group choices in XUL Example 3-14 A radio group choice of options group="flyTypes" In this case, the class attribute is used as a selector for associating the element with the style rule in which the image is referenced: tabbies { list-style-image: url("chrome://xfly/skin/images/tab.gif"); } 3.6 Form Controls In the HTML world, the textbox is one of the most commonly used elements in a form control While the XPFE toolkit... -moz-tree-image defines images contained in a cell, and it takes input parameters that let you specify the id of the specific column and row to which the image should be applied: treechildren:-moz-tree-image(col-id,row-id) { list-style-image: url("chrome://xfly/skin/images/outliner.gif"); } Also, -moz-tree-twisty allows you define an image for the twisty that is used to open and close a level in a tree treechildren:-moz-tree-twisty... option at a time can be chosen The this keyword in JavaScript lets you access the selected item in a straightforward way In this case, it sends the node to the script every time an option is selected 3.6 .2 Checkbox A checkbox is a simpler widget that needn't be part of a selection group It is often used to indicate if some functionality should be turned on or off, as shown in Figure 3-7 . Chapter 3. XUL Elements and Features- P3 Figure 3- 5. Multilevel tree hierarchy 3. 4.2.4. Using trees in XUL templates XUL templates are special. onselect handler of the <tree> element in the XUL content. 3. 4 .3. Grid A <grid> is another XUL table structure, designed to be more flexible with