Home > Element Reference : XUL Element

Contents

### XUL Element

A XUL element. The following lists attribute and properties common to all XUL elements. Some only have any meaning in particular situations such as when placed inside a template or overlay.

#### Attributes:

Attributes inherited from Element

align

The align attribute specifies how child elements of the box are aligned, when the size of the box is larger than the total size of the children. For boxes that have horizontal orientation, it specifies how its children will be aligned vertically. For boxes that have vertical orientation, it is used to specify how its children are algined horizontally. The pack attribute is related to the alignment but is used to specify the position in the opposite direction. You can also specify the value of align using the style property '-moz-box-align'.

- start: Child elements are aligned starting from the left or top edge of the box. If the box is larger than the total size of the children, the extra space is placed on the right or bottom side.
- center: Extra space is split equally along each side of the child elements, resulting the children being placed in the center of the box.
- end: Child elements are placed on the right or bottom edge of the box. If the box is larger than the total size of the children, the extra space is placed on the left or top side.
- baseline: This value applies to horizontally oriented boxes only. It causes the child elements to be aligned so that their text labels are lined up.
- stretch: The child elements are stretched to fit the size of the box. For a horizontal box, the children are stretched to be the height of the box. For a vertical box, the children are stretched to be the width of the box. If the size of the box changes, the children stretch to fit. Use the flex attribute to create elements that stretch in the opposite direction.
- left: (Deprecated) The elements are aligned on their left edges.
- center: (Deprecated) The elements are centered horizontally.
- right: (Deprecated) The elements are aligned on their right edges.

allowevents

If true, events are passed to children of the element. Otherwise, events are passed to the element only.

allownegativeassertions

Valid on any element that has a datasources attribute. When multiple datasources are used, one may override an assertion from another. This attribute, if true, which is the default, allows a datasource to negate an earlier assertion.

class

The style class of the element. Multiple classes may be specified by separating them with spaces.

coalesceduplicatearcs

Valid on any element that has a datasources attribute. Because RDF holds a graph of resources, it is possible for there to be several pointers to the same node. If this attribute is true, which is the default, duplicate references are skipped. If false, duplicate references will appear.

collapsed

If true, then the element is collapsed and does not appear. It is equivalent to setting the CSS visibility property to 'collapsed'.

container

Set to true if the element is to act as a container which can have child elements. This would be used for folders. This will be set by the template builder as needed.

containment

This attribute specifies RDF properties that indicate that a resource is a container. When generating content from a template this is used to determine which resources from the datasource are containers and thus can have child nodes and which ones are not containers.

This attribute should be placed on the same element that the datasources and the ref attribute is on. It may be set to a space-separated list of RDF properties or resources.

contextmenu
datasources

A space-separated list of datasources that an element's template will use for content generation. These can be either internal datasources such as rdf:bookmarks or a URL of an RDF file. The datasources attribute may be placed on most elements, although it will usually be found on trees and menupopups. The element should have a template element as a child.

The specified datasources are combined into a single composite datasource which holds the data from all of the datasources. This composite datasource is accesssible via a script through the database property.

If you plan on adding a datasource to an element but don't want one to be added right away, set this attribute to 'rdf:null'. This will make the element so that its contents can be generated from a datasource. Otherwise, you cannot add one later.

debug

If true, extra borders are drawn around the element and all its descendants. This can be used to determine orientation and where flexible elements are. If debug mode is enabled for a box, horizontal oriented boxes are displayed with a blue border and vertical boxes are displayed with a red border. The border above the element will be straight for non-flexible elements and wavy for flexible elements.

dir

The direction in which the child elements of the element are placed.

- ltr: The elements are placed left to right or top to bottom in the order they appear in the XUL code.
- rtl: The elements are placed right to left or bottom to top. This is reverse of the order in which they appear in the XUL code.

empty

Set to true if the element is a container that contains no children. This will be set by the template builder as needed.

equalsize

This attribute can be used to make the children of the element equal in size.

- always: For a horizontally oriented element, this will make its children all have the width of the widest child. For a vertically oriented element, this will make its children all have the height of the tallest child.
- never: All of the children are displayed at the size required by the content or as specified by the width and height attributes or by the CSS width and height properties.

flags

A set of flags used for miscellaneous purposes. Two flags are defined, which may be the value of this attribute.

- dont-test-empty: For template generated content, the builder will not check that a container is empty.
- dont-build-content: This flag may be used on a tree to indicate that content elements should not be generated. This results in a performace enhancement, but you will not be able to use the DOM functions to retreive the tree rows.

flex

Indicates the flexibility of the element. Flexible elements grow and shrink to fit their given space. The actual value is not relevant unless there are other flexible elements within the same container. Elements with larger flex values will grow more than elements with lower flex values, at the ratio determined by the two elements.

flexgroup

This property is used to group flexible elements together and should be set to an integer. Elements with a lower flexgroup are flexed first. When those elements have reached their maximum sizes, the elements with the next higher flexgroup are flexed. This process continues until there are no more elements remaining. The same process occurs when decreasing the size, except in the other direction.

height

The height of the element in pixels. It is recommended that the CSS height property be used instead.

hidden

If set to hidden, the element is not displayed. This is similar to setting the CSS display property to 'none'.

id

A unique identifier so that you can identify the element with. You can use this as a parameter to getElementById and other DOM functions and to reference the element in style sheets.

insertafter

When an element is in an overlay, the insertafter attribute specifies the id of the element in the base window that the element should appear after. This attribute overrides the insertbefore attribute. This value may be a comma-separated list of ids, which are scanned and the first one found in the window is used.

insertbefore

When an element is in an overlay, the insertbefore attribute specifies the id of the element in the base window that the element should appear before. This value may be a comma-separated list of ids, which are scanned and the first one found in the window is used.

left

For elements placed within a stack, specifies the position of the left edge of the element.

maxheight

The maximum height of the element. This corresponds to the max-height CSS property.

maxwidth

The maximum width of the element. This corresponds to the max-width CSS property.

menu
minheight

The minimum height of the element. This corresponds to the min-height CSS property.

minwidth

The minimum width of the element. This corresponds to the min-width CSS property.

observes

Set to an id of a broadcaster element that is being observed by the element. If an attribute changes in the broadcaster it is also changed in the observer.

ordinal

An integer which specifies the position of the element within its parent. By default, elements appear in the order they appear in the XUL code. The ordinal attribute can be used to change this.

orient

Used to specify whether the children of the element are oriented horizontally or vertically. The default value depends on the element. You can also use the '-moz-box-orient' style property.

- horizontal: Child elements of the element are placed next to each other in a row in the order that they appear in the XUL source.
- vertical: Child elements of the element are placed under each other in a column in the order that they appear in the XUL source.

pack

The pack attribute specifies where child elements of the box are placed when the box is larger that the size of the children. For boxes with horizontal orientation, it is used to indicate the position of children horizontally. For boxes with vertical orientation, it is used to indicate the position of children vertically. The align attribute is used to specify the position in the opposite direction. You can also specify the value of pack using the style property '-moz-box-pack'.

- start: Child elements are placed starting from the left or top edge of the box. If the box is larger than the total size of the children, the extra space is placed on the right or bottom side.
- center: Extra space is split equally along each side of the child elements, resulting the children being placed in the center of the box.
- end: Child elements are placed on the right or bottom edge of the box. If the box is larger than the total size of the children, the extra space is placed on the left or top side.

persist

A space separated list of attributes that are maintained when the window is closed. When the window is re-opened, the values of persistant attributes are restored. In Mozilla, persistant attributes are stored in the per-profile file localstore.rdf. Persistence can also be stored using the document.persist function.

position

When an element is in an overlay, the position is an index of which child appears at. The position is one-based, so use a value of 1 to place the element at the beginning. This attribute is ignored if either an insertbefore or insertafter attribute matches an element.

ref

For template generated elements, this attribute is used to specify the root RDF node where content generation begins. This will correspond to the value of an about attribute on an RDF container. This attribute should be placed alongside the datasources attribute.

removeelement

When placed on an element in an overlay, it indicates that the element in the base file should be removed from the window.

statustext

Used to set the text that appears on the status bar when the user moves the mouse over the element.

style

CSS style rules to be applied to the element. Syntax is as in the HTML style attribute. It is preferred to put style rules in style sheets.

template

For template generated elements, this attribute may optionally be placed on the root node (the element with the datasources attribute) to refer to a template that exists elsewhere in the XUL code. This template attribute should be set to the ID of the template element. This might be used to share a single template between multiple trees or menus. If this attribute is not specified, there should be a template element directly inside the node.

tooltip

Should be set to the value of the id of the popup element that should be used as a tooltip window when the mouse hovers over the element for a moment. The tooltip will automatically disappear when the mouse is moved.

tooltiptext

Used to set the text which appears in the tooltip when the user moves the mouse over the element. This can be used instead of setting the tooltip to a popup for the common case where it contains only text.

top

For elements placed within a stack, specifies the position of the top edge of the element.

uri

For template-generated content, the attribute should be placed on the element where content generation should begin. Thus, it should be placed on an element that is a descendant of a template. The value should be set to rdf:*.

Elements that appear inside the element with the attribute will be repeated for each node in the RDF datasource. Elements outside will appear only once.

width

The width of the element in pixels. It is recommended that the CSS width property be used instead.

#### Properties and Methods:

Properties and Methods inherited from Element

addBroadcastListener ( attribute, element )

Adds a event listener to an broadcaster which listens for broadcast events. It is like adding a new observes element to an element. The first argument should be the attribute to observe and the second attribute should be the element to add an observer to. When the broadcaster has the attribute given by the attribute argument, the broadcast event is fired. You can use '*' as the attribute argument to mean all attributes on the element (except the id attribute).

addEventListener ( type , listener , capture )

Adds a new event listener for the event specified by type to an element. The type should be the same as the attribute event handler without the 'on' prefix, for example 'click' or 'keydown'. The listener is the name of a function. If capture is set to true, the event will capture.

align

Gets and sets the value of the align attribute.

allowEvents

Gets and sets the value of the allowevents attribute.

boxObject

This property is available for elements that are derived from boxes, which is most displayable elements. The boxObject contains four properties, x, y, width and height, which can be used to retrieve the position and size of the element. The x and y position is relative to the document's upper-left corner.

builder

For content generated from a template, this is the XPCOM object that is responsible for generating the content. For scripts it is only necessary in case you want to force the template content to be regenerated. You may need to do this if you have adjusted the rules manually. To rebuild the content call the builder's rebuild method.

For example, given a reference to a tree myTree, this example will rebuild its content:

myTree.builder.rebuild();

className

Gets and sets the value of the class attribute.

collapsed

Gets and sets the value of the collapsed attribute.

contextmenu

Gets and sets the value of the contextmenu attribute.

controllers
createEvent
database

Returns the composite datasource created when all the datasources of an element are combined. Set to null for elements that do not have a datasources attribute.

dir

Gets and sets the value of the dir attribute.

flex

Gets and sets the value of the flex attribute.

flexgroup

Gets and sets the value of the flexgroup attribute.

getElementsByAttribute ( attrib , value )

Returns an array of all the child elements of the element that have the attribute given by the first argument attrib set to the value given by the second argument val.

height

Gets and sets the value of the height attribute.

hidden

Gets and sets the value of the hidden attribute.

id

Gets and sets the value of the id attribute.

maxHeight

Gets and sets the value of the maxheight attribute.

maxWidth

Gets and sets the value of the maxwidth attribute.

menu

Gets and sets the value of the menu attribute.

minHeight

Gets and sets the value of the minheight attribute.

minWidth

Gets and sets the value of the minwidth attribute.

observes

Gets and sets the value of the observes attribute.

ordinal

Gets and sets the value of the ordinal attribute.

orient

Gets and sets the value of the orient attribute.

pack

Gets and sets the value of the pack attribute.

persist

Gets and sets the value of the persist attribute.

removeBroadcastListener ( attribute, element )

Removes a broadcast listener from an element. Only the observer for the element given by the element argument and the attribute given by the attribute argument is removed. You can use '*' as the attribute argument to mean all attributes.

removeEventListener ( type , listener , capture )

Removes an event listener from an element. The listener specified by the type and listener argument is removed.

resource
statusText

Gets and sets the value of the statustext attribute.

style

Gets and sets the value of the style attribute.

tooltip

Gets and sets the value of the tooltip attribute.

tooltipText

Gets and sets the value of the tooltiptext attribute.

width

Gets and sets the value of the width attribute.

Copyright (C) 1999 - 2002 XULPlanet.com