Chapter 3. XUL Elements and Features- P2 Figure 3-3. Visual comparison of menu widgets 3.3.2.1. Menus Menus are much more flexible than they first appear to be. They can appear anywhere in the UI, for one thing, and needn't be stuck at the top of the window. They can be in buttons, trees, or just out on their own. Example 3-6 shows the basic structure of a menu. Example 3-6. A sample menu <menu label="Quantity"> <menupopup> <!-- menuitems here --> </menupopup> </menu> There is a rigid ordering of nesting in a menu. A menu contains a <menupopup>, which in turn contains one or more menu items. Optionally, you can segregate groups of menu items by using a <menuseparator> in the pop up, which draws a thin line between items. 3.3.2.2. Pop ups The pop up manifests as either a <menupopup> or a <popup> element. The latter can be used in a number of different ways, but Example 3-7 focuses on its common use in context menus. Example 3-7. Context menu using pop up <popup id="FlyContext" onpopupshowing="return doThis( );" onpopuphiding=" return doThat( );"> <!-- menuitems here --> </popup> A couple of extra steps are needed to prepare a context pop up for activation. First, you must attach the popup element to a widget in the UI by using the id of the pop up that must correspond to the context of the widget: <toolbar id="main-toolbar" context="FlyContext" /> When the toolbar is clicked, the pop up that corresponds to that value appears. You can have some script execute when you show and/or hide the pop up by using the onpopupshowing and onpopuphiding methods, as when you show and hide items in a dynamic menu. The second step includes the pop up in a set of pop ups, enclosed in a <popupset> element. Though not strictly necessary as a container for pop ups, the pop-up set helps organize the free-floating[1] pop-up windows in your application and makes it easy to overlay them or overlay into them as the situation requires. 3.3.2.3. Menu lists Another manifestation of the pop up is in the use of menu lists. A menu list is a choice of options presented to solicit a single choice, usually in the form of a drop-down menu, for which XUL provides the <menulist> element. Example 3-8 presents a straightforward menu list with a selection of items to choose from. As in the other pop-up examples, selecting an item executes the code defined in the oncommand event handler for that item (e.g., changeF(1) for the menu item "Tachinidae"). Example 3-8. XUL menu list <menulist id="FlyInput"> <menupopup> <!-- menuitems here --> </menupopup> </menulist> The menulist widget provides functionality beyond that of a regular menu. The menu list can be made editable when the user should be allowed to enter a value not represented in the menu items. In this case, the menulist element definition in Example 3-8 would change to something such as: <menulist id="FlyInput" editable="true" oninput="onInputFly( );" onchange="onChangeFly( );"> A true value on the editable attribute allows input in the list. Input can be validated immediately by using the oninput attribute. The addition of the onchange attribute can be used to carry out an extra script when a new selection is made. Notes [1] Free-floating because their location in the interface is not determined by their position in the XUL markup, as it usually is for items like menus and buttons. 3.4. Tabular and Hierarchical Information Many options exist to display hierarchical information in your user interface. The most common are tree-like and table-like structures, both of which are represented by elements in Mozilla's XPFE toolkit. In this section, we look at list boxes, trees, and grids. With the exception of the tree, these elements are not limited in regard to the content they can contain. Currently, the tree only holds text and image content and grids are designed for holding the more diverse content as shown in upcoming examples. 3.4.1. List Boxes <listbox> is used to display tabular data. Example 3-9 shows a listbox widget with all the basic features, including the definition of the number of columns (listcol), the listbox header (listhead), and a list item (listitem). Example 3-9. Listbox widget <listbox rows="5" class="list" id="FlyTree" onselect="SelectFly( )"> <listcols> <listcol flex="1"/> <splitter class="tree-splitter"/> <listcol flex="1"/> </listcols> <listhead> <listheader label="Name" /> <listheader label="Type" /> </listhead> <listitem id="type-d"> <listcell label="Syrphidae" /> <listcell label="flower" /> </listitem> <!-- More Items --> </listbox> The first thing of note in the markup in Example 3-9 is the rules for the nesting of elements within a listbox structure. The number of columns needs to be set, each with a <listcol> element, and all have to be wrapped in a <listcols> set. Example 3-9 has two columns. They are separated by a draggable grippy item, which also acts as a column separator in the header row. The cells for those columns are contained in a <listitem> grouping. The header is optional and has the same structure as a list item. Once you've put a hierarchy like this in place, you can put the content you want into the tabular structure. The listbox does not support multilevel/nested rows. Also note that the class attribute example above is what gives the tree much of its particular appearance. Listboxes and trees often use class-based style rules for their appearance and positioning (e.g., the column splitter in Example 3-9 ). Example 3-9 creates the listbox in Figure 3-4. Figure 3-4. Listbox 3.4.2. High Performance Trees The <listbox> widget is suitable only for certain kinds of content. For better scalability and multilevel capabilities, the <tree> was created. <tree> is an advanced tree widget that was originally designed for the Mail/News component in Mozilla. In its first incarnation, it was called the outliner widget. The tree is designed for high performance in large lists, such as newsgroups, message folders, and other applications where the volume of data is expected to be high. The tree widget has a simpler, more lightweight layout, but it is more difficult to use, requiring the addition of special "views" in order to display data. 3.4.2.1. Tree features The implementation of the tree widget is unique in the XUL universe in that it displays its content only when it comes into view, which makes it very efficient for long lists of data. Table 3-1 lists some of the main features of the tree. Table 3-1. Main features of the tree Row features Column features Visual features Plain or hierarchical rows Multicolumn Each cell can display an image preceding text Multiselection based on selection ranges Resizing using mouse dragging Look of each element (row, cell, image, etc.) is defined in CSS Drag and drop, either on a row or in between rows Column hiding using pop-up menu in top- right corner Appearance of the drop feedback during drag- and-drop can be styled Reordering using drag- and-drop Spring loaded containers that open after hovering over a closed container for a second Sorting by clicking on a column header; custom views can implement their own sorting Even with this rich set of features, however, a tree can display only text and image content. The listbox is more flexible in the type of content that appears in its cells. 3.4.2.2. Tree views In the tree widget, a view is a model for the population and display of data. The view is a flexible feature of the tree that can handle everything from simple data in a content view to more dynamic data from a custom view or an RDF datasource (builder view). Table 3-2 shows the main features of each, using general categories of datasource, speed, and type of usage. Table 3-2. Tree views Content view Builder view Custom view Rows are built from a content model. Rows are built from an RDF datasource. Consumer provides its own tree view implementation. Fast but not as memory efficient (bigger footprint). Still fast and efficient. The fastest and most efficient way. Suitable for small trees; easiest to use. Relatively easy to use. Most difficult to implement. As already mentioned, the tree is used in the Mail/News thread pane, but there are plenty of other places to look for it in Mozilla. Custom views and tree widgets are implemented for the Address Book results, JS Debugger, DOM Inspector, Bookmarks, and for autocomplete. You can see builder views in History and a content view implementation in Preferences. 3.4.2.3. The tree content model The content in a tree is defined with <tree>, <treecols>, <treecol>, and <treechildren> tags. Example 3-10 shows a basic column number definition (two in this instance) and a treechildren placeholder that defines the tree body. Example 3-10. Tree base model <tree id="tree" flex="1"> <treecols> <treecol id="Col1" label="Col1" flex="1"/> <treecol id="Col2" label="Col1" flex="1"/> </treecols> <treechildren/> </tree> As in the listbox, a well-defined hierarchy of elements has to be observed. This hierarchy is part of the content model for a tree. The organization of content within a tree enforced by the specific tree elements is listed below. Unlike listbox, nested children are possible for multilevel trees. An example of nested children appears later in this chapter in Example 3- 11. <treeitem> This element contains a single top-level row and all its descendants. The container attribute is used to mark this row as a container and is optional. The open attribute is used for expanded containers. <treerow> The row is contained in the <treeitem> element. You may optionally set the properties attribute on the <treerow> to a whitespace-separated list of properties. <treeseparator> A special element used to draw a horizontal separating line. The properties attribute is used to compute the properties that apply to the separator. <treecell> The <treecell> element must appear within the <treerow> element. It specifies the text and properties that apply for a cell. The label attribute is used to set the text for the cell. The optional properties attribute is used to compute the properties that apply to the cell. The ref attribute correlates a cell within an <treerow> to the column in the tree and is optional. Tying the concepts presented in this section together allows us to present Example 3-11 , which shows a multilevel tree with two columns and two top-level rows. Example 3-11. Multilevel tree content view <tree id="tree" hidecolumnpicker="true" flex="1"> <treecols> [...]... Second level row > To create a new sublevel, create another element; inside of it, place a , which, in turn, contains one or more rows and cells Figure 3-5 illustrates the result of this hierarchy . Chapter 3. XUL Elements and Features- P2 Figure 3- 3. Visual comparison of menu widgets 3. 3.2.1. Menus Menus are much more flexible. Example 3- 9 is the rules for the nesting of elements within a listbox structure. The number of columns needs to be set, each with a <listcol> element, and