References > " . "Element Reference"; $pagetitle="XUL Element"; $customsidebar = "elemref-sidebar.php"; include "header.php"; ?>

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.

The XUL Element object implements the following interfaces:

nsIDOMElement   nsIDOMEventTarget   nsIDOMNode   nsIDOMXULElement  

Attributes:

align allowevents allownegativeassertions class coalesceduplicatearcs
collapsed container containment context contextmenu
datasources debug dir empty equalsize
flags flex height hidden id
insertafter insertbefore left maxheight maxwidth
menu minheight minwidth observes ordinal
orient pack persist popup position
ref removeelement sortDirection sortResource sortResource2
statustext style template tooltip tooltiptext
top uri wait-cursor width

Style Classes:

box-inset box-padded groove-bottom groove-left groove-right
groove-top inset outset outset-top-bottom

Properties and Methods:

align allowEvents blur boxObject boxObject.element
boxObject.getLookAndFeelMetric boxObject.height boxObject.screenX boxObject.screenY boxObject.width
boxObject.x boxObject.y builder className click
collapsed contextMenu controllers database datasources
dir doCommand flex focus getElementsByAttribute
height hidden id left maxHeight
maxWidth menu minHeight minWidth observes
ordinal orient pack persist ref
resource statusText style tooltip tooltipText
top width

Attributes:

align

Type: one of the values below

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'.

allowevents

Type: boolean

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

allownegativeassertions

Type: boolean

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

Type: string

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

coalesceduplicatearcs

Type: boolean

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

Type: boolean

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

container

Type: boolean

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

Type: URI of an RDF predicate

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.

context

Type: popup element id

Should be set to the value of the id of the popup element that should appear when the user context-clicks on the element. A context-click varies on each platform. Usually it will be a right click. You can use the special value '_child' to indicate the first menupopup child of the element.

contextmenu

Type: popup element id

Alternate name for the context attribute, but also has a corresponding script property 'contextmenu'.

datasources

Type: space separated list of datasource URIs

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

Type: boolean

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

Type: one of the values below

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

empty

Type: boolean

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

equalsize

Type: one of the values below

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

flags

Type: space separated list of the values below

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

flex

Type: integer

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.

height

Type: integer

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

hidden

Type: boolean

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

id

Type: element id, must be unique in the window

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

Type: element id

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

Type: element id

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

Type: integer

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

maxheight

Type: integer

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

maxwidth

Type: integer

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

menu

Type: popup element id

Alternate name for the popup attribute, but also has a corresponding script property 'menu'.

minheight

Type: integer

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

minwidth

Type: integer

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

observes

Type: broadcaster element id

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

Type: integer

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 the order. You can retrieve the displayed order by using the properties of the boxObject of the container.

orient

Type: one of the values below

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.

pack

Type: one of the values below

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'.

persist

Type: space separated list of attribute names

A space separated list of attributes that are maintained when the window is closed. When the window is re-opened, the values of persistent attributes are restored. In Mozilla, persistent attributes are stored in the per-profile file localstore.rdf. Persistence can also be stored using the document.persist function. In order for persistence to work, the element must also have an id.

popup

Type: popup element id

Should be set to the value of the id of the popup element that should appear when the user clicks on the element.

position

Type: integer

When an element is in an overlay, the position is an index where the child is inserted. 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

Type: URI of an RDF resource

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

Type: element id

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

sortDirection

Type: one of the values below

Set this attribute to set the direction that template-generated content is sorted. Use the sortResource attribute to specify the sort key.

sortResource

Type: URI of an RDF predicate

For template-generated content, this specifies the sort key, if you would like the content to be sorted. The key should be the full URI of the resource to sort by, for example 'http://home.netscape.com/NC-rdf#Name'. Place this attribute on the same element as the datasources attribute. Use sortResource2 to specify a secondary sort key.

sortResource2

Type: URI of an RDF predicate

A secondary key for sorted content.

statustext

Type: string

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

style

Type: CSS inline 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

Type: element id

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

Type: tooltip element id

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. If this attribute is set to '_child', the first tooltip child element inside the element is used.

tooltiptext

Type: string

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. The toolitp is displayed in a default tooltip which only displays only a label, however the default tooltip may be changed by setting the default attribute on a tooltip element.

top

Type: integer

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

uri

Type: string

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.

wait-cursor

Set this attribute to true to have the cursor switch to a waiting cursor while the mouse is hovering over it. Usually, you would only use this on the window element or other top-level elements.

width

Type: integer

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


Style Classes:

The following classes may be used to style the element. These classes should be used instead of changing the style of the element directly since they will fit more naturally with the user's selected theme.

box-inset

The element is drawn with an inset border around it similar to the inset type except more noticeable. It will generally have borders like those that appear around a control such as listbox, with the background white, assuming the default theme.

box-padded

A box with a small amount of padding on each side.

groove-bottom

An element with a groove along its bottom edge.

groove-left

An element with a groove along its left edge.

groove-right

An element with a groove along its right edge.

groove-top

An element with a groove along its top edge.

inset

The element is drawn with an inset border around it. This causes the element area to appear inset from the rest of the content.

outset

The element is drawn with an outset border around it. This causes the element area to appear outset from the rest of the content.

outset-top-bottom

The element is drawn with an outset border along the top and bottom edges. This class might be used when the element is part of a set of items in a row, since borders do not appear between them.


Properties and Methods:

Inherited from Element:

addEventListener
appendChild
attributes
childNodes
cloneNode
dispatchEvent
firstChild
getAttribute
getAttributeNS
getAttributeNode
getAttributeNodeNS
getElementsByTagName
getElementsByTagNameNS
hasAttribute
hasAttributeNS
hasAttributes
hasChildNodes
insertBefore
isSupported
lastChild
localName
namespaceURI
nextSibling
nodeName
nodeType
nodeValue
normalize
ownerDocument
parentNode
prefix
previousSibling
removeAttribute
removeAttributeNS
removeAttributeNode
removeChild
removeEventListener
replaceChild
setAttribute
setAttributeNS
setAttributeNode
setAttributeNodeNS
tagName

align

Type: string

Gets and sets the value of the align attribute.

allowEvents

Gets and sets the value of the allowevents attribute.

blur ( )

Return Type: no return value

If the focus is on the element, it is removed. The focus is not automatically placed on any other element. Essentially, this is used to call the onblur handler.

boxObject

Type: nsIBoxObject

This property is available for elements that are derived from boxes, which is most displayable XUL elements. You can retrieve the boxObject for non-XUL elements using the document.getBoxObjectFor method. The boxObject contains a number of properties, described below.

boxObject.element

Type: element

A reference to the element itself.

boxObject.getLookAndFeelMetric ( property )

Return Type: string

Returns a platform-specific setting named by the property argument. Typically these would be settings the user would set in their operating system preferences. Two values can be used:

boxObject.height

Type: integer

The displayed height of the element.

boxObject.screenX

Type: integer

The horizontal position of the element on the screen.

boxObject.screenY

Type: integer

The vertical position of the element on the screen.

boxObject.width

Type: integer

The displayed width of the element.

boxObject.x

Type: integer

The horizontal position of the element on the window. The x and y position is relative to the window's upper-left corner, or if the XUL is loaded in a frame, the upper-left corner of the frame.

boxObject.y

Type: integer

The vertical position of the element on the window.

builder

Type: nsIXULTemplateBuilder

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.

click ( )

Return Type: no return value

Calls the onclick handler for the element.

collapsed

Type: boolean

Gets and sets the value of the collapsed attribute.

contextMenu

Gets and sets the value of the contextmenu attribute.

controllers

Type: nsIControllers

A controllers list attached to the element. The controllers are used to respond to commands. The document's command dispatcher will locate controllers to handle a command by using the focused element's controllers list.

database

Type: nsIRDFCompositeDataSource

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.

datasources

Type: space separated list of datasource URIs

Gets and sets the value of the statusbar attribute. In newer versions of Mozilla (1.7), the datasources will be reloaded and the template updated.

dir

Type: string

Gets and sets the value of the dir attribute.

doCommand ( )

Return Type: no return value

Executes the command event for the element.

flex

Type: integer

Gets and sets the value of the flex attribute.

focus ( )

Return Type: no return value

Assigns the focus to the element, if it can accept the focus. The onfocus handler is called.

getElementsByAttribute ( attrib , value )

Return Type: DOM NodeList

Returns an array of all the child elements of the element that have the attribute given by the first argument set to the value given by the second argument. If second argument is '*', the attribute may be set to any value.

height

Type: integer

Gets and sets the value of the height attribute.

hidden

Type: boolean

Gets and sets the value of the hidden attribute.

id

Type: element id, must be unique in the window

Gets and sets the value of the id attribute.

left

Type: integer

Gets and sets the value of the left attribute.

maxHeight

Gets and sets the value of the maxheight attribute.

maxWidth

Gets and sets the value of the maxwidth attribute.

menu

Type: popup element id

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

Type: broadcaster element id

Gets and sets the value of the observes attribute.

ordinal

Type: integer

Gets and sets the value of the ordinal attribute.

orient

Type: string

Gets and sets the value of the orient attribute.

pack

Type: string

Gets and sets the value of the pack attribute.

persist

Type: space separated list of attribute names

Gets and sets the value of the persist attribute.

ref

Type: URI of an RDF resource

Gets and sets the value of the ref attribute.

resource

Type: nsIRDFResource

Returns an RDF resource with the value of the element's ref attribute. If the ref attribute is not specified, the id attribute is used instead.

statusText

Gets and sets the value of the statustext attribute.

style

Type: CSS inline style

Gets and sets the value of the style attribute.

tooltip

Type: tooltip element id

Gets and sets the value of the tooltip attribute.

tooltipText

Gets and sets the value of the tooltiptext attribute.

top

Type: integer

Gets and sets the value of the top attribute.

width

Type: integer

Gets and sets the value of the width attribute.