General XUL attributes

A number of attributes are common to all XUL widgets and can be imagined as being inherited from an anonymous base class. This section describes those common attributes.
 
 

id uniquely identifies an element in a XUL file.

<element id="string">

<menu id="file_men">
  <menupopup>
    <menuitem id="new_item" value="New" disabled="true" />
    <menuitem value="Open" />
    <menuitem value="Exit" />
  </menupopup>
</menu>

All XUL widgets can use the id attribute. Use id to access and manipulate DOM elements in XUL. For example, the following javascript function retrieves the New menuitem above, which can then be interrogated for its state, attributes, etc.:

is_new = document.getElementById("new_item");
current_state = is_new.getAttribute("disabled");
if (current_state = true) { ... } 

The id attribute can also be used to identify structures in overlay files that will overlay the basic UI defined in a XUL file. For example, when subtrees such as menus are defined in an overlay and given an id (e.g., id="file_menu") identical to a node in the base file, those subtrees are interpolated into the structure of the XUL interface. See overlays for more information.
 
 

class is an optional attribute used for styling XUL widgets. 

Syntax

<element class="string">

Example

<box class="borderless">

Notes

The class attribute works exactly like the class attribute in HTML. As in HTML, the XUL class attribute corresponds to the class selector in style definitions. For example, the element <box class="mybox"> will pick up style information defined in box.mybox {style statements...} where an unclassed <box> element will not. The class attribute can be used to style almost any XUL widget. XUL also provides the ability to provide style information for any elements of a particular class. In other words, you can define style information for an anonymous class (i.e., .myClass {style statements...}) in a stylesheet, and any element that uses the attribute class="myClass" will pick up that style information.

style specifies style sheet information in-line with a widget.

<element style="style statement[ ; style statement2; style statement3; ]">

<menu value="Edit" style="background-color:lightblue">

Though this is a legal attribute for most widgets, in general it's preferable to specify all style information in the .css files located in the skin subdirectory of a particular package. This allows interfaces to be "skinned" consistently.
Warning:  When a style is specified in-line, more global and critical style information can be overwritten to the detriment of the overall look of the UI.

persist specifies which attributes of a widget are to be stored persistently, so that they can be recalled as user preferences when the application is restarted.

<element persist="attribute1 [ attribute2 attribute3 etc.]">

<window id="main-window" xmlns:html="http://www.w3.org/1999/xhtml"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
  onload="Startup()"
  onunload="Shutdown()"
  title="&mainWindow.title;" 
  windowtype="navigator:browser"
  align="vertical"
  width="640" height="480"
  x="10" y="10"
  persist="width height x y"
  ondraggesture="return GeneralDrag(event);"> 

The persisted values are separated by spaces only. The persist attribute is often used to preserve the size and location of the root window and other positionable, non-modal XUL windows. The example above preserves the width, height, horizontal position, and vertical position on the screen, respectively. But the persist attribute can be used to persist any attribute on any element in XUL. Examples of other attributes that can be persisted include the state of menus (e.g., checked or not), the visibility of particular toolbars, and the relative size of elements within the main window.

popup is an optional attribute that specifies the id of a popup associated with the element.

<element popup="popup element id">

<menu value="Edit" popup="editor_popup">

The popup identified with this attribute can be either a menu or a window type popup. The content of the popup subtree is displayed when the user left clicks the element. The popup uses its own popupalign and popupanchor attributes to position the popup content in relation to the element.

popupanchor is an optional attribute for specifying where popup content should be anchored on the element. 

<element popupanchor="none | topleft | topright | bottomleft | bottomright" />

<element id="edit-context"
   popup="editor-popup" popupanchor="topleft"
   popupalign="bottomright" />

The popupanchor attribute can be used to specify that the popup content should come up anchored to one of the four corners of the content object (e.g., the button popping up the content). If omitted, no anchoring occurs. Instead the popup content comes up directly underneath the mouse event coordinates. This point (either directly under the mouse or attached to one of the four corners) is called the originating point. 

By default the popup content appears with its top left point located directly underneath the point at which the user's mouse goes down (on tooltips the content is displaced by the height of the mouse cursor). popupanchor works in conjunction with popupalign to position the popup content on the element. The default value for both popupanchor and popupalign is "none."
 

popupalign is an optional attribute for specifying which side of the popup content should be attached to the popupanchor. 

<element popupalign="none | topleft | topright | bottomleft | bottomright" />

<element id="edit-context"
   popup="editor-popup" popupanchor="topleft"
   popupalign="bottomright" />

The popupalign attribute can be used to specify which corner of the popup content is tied to the originating point. If omitted, the default is topleft. The example below shows how to create the traditional buttons with attached left mouse menus that exist in the 4.x Communicator product. If omitted, no anchoring occurs. Instead the popup content comes up directly underneath the mouse event coordinates. This point (either directly under the mouse or attached to one of the four corners) is called the originating point. 

By default the popup content appears with its top left point located directly underneath the point at which the user's mouse goes down (on tooltips the content is displaced by the height of the mouse cursor). The default value for both popupanchor and popupalign is "none."
 
 
 

chromeclass is an optional attribute for specifying what type of chrome is being loaded. 

<element chromeclass="string">

<splitter id="sidebar-splitter" collapse="before" persist="state hidden" 
    chromeclass="extrachrome" onclick="dumpStats();">>

chromeclass is used to label an element as belonging to a certain class of chrome objects, e.g., "toolbar", "menubar", etc.This is used as a hint to the window.open method, which takes flags that can be used to show/hide elements of chrome, e.g., toolbars, menubars, status bars, etc. Because the chrome is totally configurable using XUL, some kind of hint needs to be supplied to the window.open implementation so that it knows how to locate specific chrome elements. 

context is an optional attribute for specifying what type of chrome is being loaded. 

<element context="string">

<box context="context" flex="100%">

XXX

ondraggesture is an event listener for the draggesture event. draggesture is fired every time the user appears to be beginning a drag operation.

<element ondraggesture="event handler code">

<menu value="Edit" ondraggesture="GetExtraImg()">

It can be difficult to detect drag gestures. The draggesture event is fired when the user holds the mouse down and moves some distance without letting up on the mouse button. It is up to the application developer to decide whether the gesture constitutes a real drag and whether to use it or not. See ondragdrop, ondragover, and ondragexit for more information on drag and drop functionality in XUL.

ondragdrop is an event listener for the dragdrop event. 

<element ondragdrop="event handler code">

<toolbar id="PersonalToolbar" chromeclass="toolbar" persist="collapsed" 
  dragdroparea="innermostBox"
    ondraggesture="return BeginDragPersonalToolbar(event);"
    ondragdrop="return DropPersonalToolbar(event);"
    ondragover="return DragOverPersonalToolbar(event);">

A widget's dragdrop event is fired when the user drops an item onto that widget. See ondraggesture, ondragover, and ondragexit for more information on drag and drop functionality in XUL.

ondragover is an event listener for the dragover event.

<element ondragover="event handler code">

<toolbar id="PersonalToolbar" chromeclass="toolbar" persist="collapsed" 
  dragdroparea="innermostBox"
    ondraggesture="return BeginDragPersonalToolbar(event);"
    ondragdrop="return DropPersonalToolbar(event);"
    ondragover="return DragOverPersonalToolbar(event);">

dragover is fired when an object is dragged over the top of an element. For example, if you drag an object over a toolbar with the intention of dropping it onto a bookmark window, the toolbar's ondragover event handler attribute receives the dragover event. Events of this kind can be used to create styles for drag-aware widgets over which elements are dragged. See ondraggesture, ondragdrop, and ondragexit for more information on drag and drop functionality in XUL.

ondragexit is an event listener for the dragexit event. 

<element ondragexit="event handler code">

<menu value="Edit" ondragexit="doDragDone()">

dragexit is fired when a drag operation has been completed. See ondraggesture, ondragdrop, and ondragover for more information on drag and drop functionality in XUL.