Element Listbox

This element is used to create a list of items where one or more of the items may be selected. A listbox may contain multiple columns. There are numerous methods which allow the items in the listbox to be retrieved and modified.

Extends

XULSelectElement

Members Table

The following table lists the members exposed by the Listbox object.

Show inherited members (marked with *)

Show: Attributes Properties Methods Events Pseudo-classes

Attribute Description 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 aligned horizontally Acceptable values: Value Description 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 in 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. 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. aml:content * Name of locale key to substitute element's content. aml:draggable * Specifies wether element can be dragged by user. Acceptable values: Value Description true Element can be dragged. false Element can not be dragged. aml:droppable * Specifies wether element can be used as drop target. Acceptable values: Value Description true Element can be used as drop target. false Element can not be used as drop target. aml:resizable * Specifies whether element boundaries can be modified by user. Acceptable values: Value Description true Elements boundaries can be modified. false Elements boundaries can not be modified. aml:resize-edges * Specifies what edges can be resized. The attribute value is a space separated list of "top", "right", "bottom" and "left" tokens. aml:selectable * Enables/disables text selection on element. Acceptable values: Value Description true Text selection is enabled on element false Text selection is disabled on element inherit Text selection behavior is inherited from its parent container. aml:values * Semicolon-separated list of name:locale key pairs to substitute element's attributes or properties. For example: value:key_value;.innerHTML:key_innerHTML class * Element class. command * Set to the id of a command element that is being observed by the element. context * Should be set to the value of the id of the popup element that should appear when the user context-clicks on the element. debug * Draws a debug border around the box. Acceptable values: Value Description true For horizontally drawn elements the red border is shown, for vertically - the blue one. false flex * Indicates the flexibility of the element, which indicates how an element's container distributes remaining empty space among its children. Flexible elements grow and shrink to fit their given space. Elements with larger flex values will be made larger than elements with lower flex values, at the ratio determined by the two elements. The actual value is not relevant unless there are other flexible elements within the same container. Once the default sizes of elements in a box are calculated, the remaining space in the box is divided among the flexible elements, according to their flex ratios. Specifying a flex value of 0 has the same effect as leaving the flex attribute out entirely. height * The preferred height of the element in pixels. hidden * If set to true, the element is not displayed. This is similar to setting the CSS display property to 'none'. Acceptable values: Value Description true Element is visible. false Element is invisible. id * Element identifier. maxheight * The maximum height of the element. maxwidth * The maximum width of the element. minheight * The minimum height of the element. minwidth * The minimum width of the element. 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. on*** * Enables in-line handler for *** event. orient * Used to specify whether the children of the element are oriented horizontally or vertically. Acceptable values: Value Description 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 * he 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. Acceptable values: Value Description 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. stretch The child elements are stretched to fit the size of the box. popup * Should be set to the value of the id of the popup element that should appear when the user clicks on the element. seltype * Used to indicate whether multiple selection is allowed. Acceptable values: Value Description single Only one row may be selected at a time. multiple Multiple rows may be selected at once. 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. tooltiptext * Used to set the text which appears in the tooltip when the user moves the mouse over the element. type Adds a control element at the beginning of every row. Acceptable values: Value Description radio Will show a radio element at the beginning of every row. checkbox Will show a checkbox element at the beginning of every row. width * The preferred width of the element in pixels. xml:base * Retrieves baseURI for the object. xml:space * Instructs DOM implementation on weather to preserve whitespace text nodes. Acceptable values: Value Description preserve All whitespaces will be preserved in the document. default Standard processing of whitespaces Property Type Readonly Description $draggable * Boolean false If true, element is draggable. $droppable * Boolean false If true, element is a valid drag target. $resizable * Boolean false Keeps a flag indicating whether element size can be modified. $selectable * Boolean false Keeps a flag indicating whether element's text content can be selected. attributes * Object true A collection containing the attributes of this node (if it is an Element) or null otherwise. baseURI * String true The absolute base URI of this node or null if the implementation wasn't able to obtain an absolute URI. body Element true Contains a reference to listbody element. childNodes * NodeList true A NodeList that contains all direct children of this node. contentFragment * DocumentFragment false UI element definition API. A reference to the anonymous subtree. The subtree should be created in element constructor. currentItem * Element true Returns the last selected item in the list box, which is only useful in a multiple selection list box. firstChild * Node true Retrieves a reference to the first child for the object. head Element true Contains a reference to listcols element. items NodeList true Contains a collection of listitem child elements. lastChild * Node true Retrieves a reference to the last child for the object. localName * String true Retrieves the local name of node. namespaceURI * String true Retrieves the namespace URI. nextSibling * Node true Retrieves a reference to the next child of the parent for the object. nodeName * String true Retrieves the name of a particular type of node. nodeType * Number true Retrieves the type of the requested node. nodeValue * String true Retrieves the value of a node. ownerDocument * Document true Retrieves the Document object associated with the node. parentNode * Node true Retrieves the parent object in the object hierarchy. prefix * String true Retrieves the namespace prefix specifief for the node. previousSibling * Node true Retrieves a reference to the previous child of the parent for the object. selectedItems * NodeList false Returns an array of the selected items in the list. style * CSSStyleDeclaration true Return style declaration obejct. tabIndex * Number false Sets value used to specify control position in tab sequence. When value is set to 0, control will be accessed in the document order, when -1, control will not be accessible at all. tagName * String true Retrieves the tag name of the object. Method Returns Description $activate * Void Activates element by dispatching DOMActivate event to the element. Sytaxis: object.$activate() $getContainer * HTMLElement UI element definition API. Returns a pointer to a (pseudo-) element in the shadow content. Sytaxis: object.$getContainer([pseudoElement]) Arguments: Name Type O/R Description pseudoElement String Optional Name of pseudo-element. $getTagClose * String UI element definition API. Provide your function to return shadow content to be inserted after element children. Sytaxis: object.$getTagClose() $getTagOpen * String UI element definition API. Provide your function to return shadow content to be inserted before element children. Sytaxis: object.$getTagOpen() $isAccessible * Boolean UI element definition API. Indicates wether element can be focused. Sytaxis: object.$isAccessible() $mapAttribute * Void UI element definition API. Provide your function to map attribute value to shadow tree. Not called for id, class and style attributes. Sytaxis: object.$mapAttribute(name, value) Arguments: Name Type O/R Description name String Required Attribute name value String Required Attribute value. null if attribute is being removed. $setPseudoClass * Void UI element definition API. Applies the pseudo class to an element. Sytaxis: object.$setPseudoClass(name, state, [pseudoElement]) Arguments: Name Type O/R Description name String Required Name of CSS pseudoclass state Boolean Required Flag indicating wether pseudoclass should be set or reset. pseudoElement String Optional Name of pseudo-element. addEventListener * Void This method allows the registration of an event listener in the default group and, depending on the useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases. Sytaxis: object.addEventListener(type, listener, useCapture) Arguments: Name Type O/R Description type String Required Specifies the Event.type associated with the event for which the user is registering. listener Function Required Function to be called when the event occurs. useCapture Boolean Required If true, user wishes to add the event listener for the capture phase only, if false - for target and bubbling phases. addItemToSelection * Void Selects the given item, without deselecting any other items that are already selected. Sytaxis: object.addItemToSelection(item) Arguments: Name Type O/R Description item Element Required Item to be added. appendChild * Node Appends a child element to the object. Sytaxis: object.appendChild(node) Arguments: Name Type O/R Description node Node Required The node to add. blur * Void Removes focus from the element. Sytaxis: object.blur() canDispatch * Void Tests wether event of the specified namespace and type can be dispatched. Sytaxis: object.canDispatch(namespaceURI, type) Arguments: Name Type O/R Description namespaceURI String Required NamespaceURI of the event to be tested. type String Required Event type. clearSelection * Void Deselects all of the items. A select event is sent before the items are deselected. Sytaxis: object.clearSelection() cloneNode * Node Creates a copy of node and returns it. Sytaxis: object.cloneNode(deep) Arguments: Name Type O/R Description deep Boolean Required Indicates wether the childnodes are also to be cloned. compareDocumentPosition * Number Compares the reference node, i.e. the node on which this method is being called, with a node, i.e. the one passed as a parameter, with regard to their position in the document and according to the document order. Sytaxis: object.compareDocumentPosition(node) Arguments: Name Type O/R Description node Node Required The node to compare against the reference node. dispatchEvent * Boolean This method allows the dispatch of events into the implementation's event model. Return value indicates whether any of the listeners which handled the event called preventDefault method on Event object. Sytaxis: object.dispatchEvent(event) Arguments: Name Type O/R Description event Event Required The event to be dispatched. focus * Void Moves focus to the element. Sytaxis: object.focus() getAttribute * String Retrieves the value of the specified attribute. Sytaxis: object.getAttribute(name) Arguments: Name Type O/R Description name String Required Attribute name getAttributeNS * String Retrieves the value of the specified attribute from the specified namespace. Sytaxis: object.getAttributeNS(namespaceURI, localName) Arguments: Name Type O/R Description namespaceURI String Required Namespace URI localName String Required Attribute name getBoundingClientRect * TextRectangle Returns an object with top, right, bottom, left members keeping the absolute coordinates of the object in the screen. Sytaxis: object.getBoundingClientRect() getElementsByTagName * NodeList Retrieves a NodeList collection of Element objects based on the specified element name. Sytaxis: object.getElementsByTagName(name) Arguments: Name Type O/R Description name String Required Element name. getElementsByTagNameNS * NodeList Retrieves a NodeList collection of Element objects based on the specified element name from the given namespace. Sytaxis: object.getElementsByTagNameNS(namespaceURI, localName) Arguments: Name Type O/R Description namespaceURI String Required Namespace URI. URI пространства имен элемента. localName String Required Element name. hasAttribute * Boolean Returns a value that indicates whether the object has specified attribute. Sytaxis: object.hasAttribute(name) Arguments: Name Type O/R Description name String Required Attribute name. hasAttributeNS * Boolean Returns a value that indicates whether the object has specified attribute from the given namespace. Sytaxis: object.hasAttributeNS(namespaceURI, localName) Arguments: Name Type O/R Description namespaceURI String Required Namespace URI. localName String Required Attribute name. hasAttributes * Boolean Retrieves true if the node has any attributes. Sytaxis: object.hasAttributes() hasChildNodes * Boolean Returns a value that indicates whether the object has children. Sytaxis: object.hasChildNodes() insertBefore * Node Inserts a chlid element after the specifyed element to the object. Sytaxis: object.insertBefore(node, before) Arguments: Name Type O/R Description node Node Required The node to insert. before Node Required The reference node, i.e., the node before which the new node must be inserted. isDefaultNamespace * String This method checks if the specified namespaceURI is the default namespace or not. Sytaxis: object.isDefaultNamespace(namespaceURI) Arguments: Name Type O/R Description namespaceURI String Required The namespace URI to look for. lookupNamespaceURI * String Look up the namespace URI associated to the given prefix, starting from this node. Sytaxis: object.lookupNamespaceURI(prefix) Arguments: Name Type O/R Description prefix String Required The prefix to look for. If this parameter is null, the method will return the default namespace URI if any. lookupPrefix * String Look up the prefix associated to the given namespace URI, starting from this node. Sytaxis: object.lookupPrefix(namespaceURI) Arguments: Name Type O/R Description namespaceURI String Required The namespace URI to look for. normalize * Void Puts all Text nodes in the full depth of the sub-tree underneath this Node, including attribute nodes, into a "normal" form Sytaxis: object.normalize() querySelector * Element Returns Element that matches CSS query. Sytaxis: object.querySelector(selector, [NSResolver]) Arguments: Name Type O/R Description selector String Required CSS query. NSResolver Function Optional Resolver function used to resolve namespace prefixes used in query. querySelectorAll * NodeList Returns NodeList of Element that match CSS query. Sytaxis: object.querySelectorAll(selector, [NSResolver]) Arguments: Name Type O/R Description selector String Required CSS query. NSResolver Function Optional Resolver function used to resolve namespace prefixes used in query. releaseCapture * Void Removes mouse capture from the object in the current document. Sytaxis: object.releaseCapture() removeAttribute * Void Removes the given attribute from the element. Sytaxis: object.removeAttribute(name) Arguments: Name Type O/R Description name String Required Attribute name. removeAttributeNS * Void Removes the given attribute from the given namespace from the element. Sytaxis: object.removeAttributeNS(namespaceURI, name) Arguments: Name Type O/R Description namespaceURI String Required Namespace URI. name String Required Attribute name. removeChild * Node Removes a child node from the object. Sytaxis: object.removeChild(child) Arguments: Name Type O/R Description child Node Required The node being removed. removeEventListener * Void This method allows the removal of event listeners from the default group. Sytaxis: object.removeEventListener(type, listener, useCapture) Arguments: Name Type O/R Description type String Required Specifies the Event.type for which the user registered the event listener. listener Function Required Listener to be removed. useCapture Boolean Required Specifies whether the EventListener being removed was registered for the capture phase or not. removeItemFromSelection * Void Deselects the specified item without deselecting other items. Sytaxis: object.removeItemFromSelection(item) Arguments: Name Type O/R Description item Element Required Element to be removed from selection. replaceChild * Node Replaces the given child node by another node. Sytaxis: object.replaceChild(new, child) Arguments: Name Type O/R Description new Node Required The new node to put in the child list. child Node Required The node being replaced in the list. scrollIntoView * Void Causes the object to scroll into view, aligning it either at the top or bottom of the window. Sytaxis: object.scrollIntoView(top) Arguments: Name Type O/R Description top Boolean Required If value is true, scrolls the object so that top of the object is visible at the top of the window. scrollToIndex * Void Scrolls the element to the specified index. Sytaxis: object.scrollToIndex(index) Arguments: Name Type O/R Description index Number Required Element index. selectAll * Void Selects all of the items. A select event is sent after the selection is made. Sytaxis: object.selectAll() selectItem * Void Deselects all of the currently selected items and selects the given item. A select event is sent after the selection is made. Sytaxis: object.selectItem(item) Arguments: Name Type O/R Description item Element Required Element to be selected. selectItemRange * Void Selects the items between the two items given as arguments, including the start and end items. All other items are deselected. This method does nothing for single-selection list boxes. A select event is sent after the selection is made. Sytaxis: object.selectItemRange(item, itemTo) Arguments: Name Type O/R Description item Element Required First element from range. itemTo Element Required Last element from range. setAttribute * Void Sets the value of the specified attribute. Sytaxis: object.setAttribute(name, value) Arguments: Name Type O/R Description name String Required Attribute name value String Required Attribute value setAttributeNS * Void Sets the value of the specified attribute from the given namespace. Sytaxis: object.setAttributeNS(namespaceURI, name, value) Arguments: Name Type O/R Description namespaceURI String Required Namespace URI name String Required Attribute name value String Required Attribute value setCapture * Void Sets the mouse capture to the object that belongs to the current document. Sytaxis: object.setCapture([containerCapture]) Arguments: Name Type O/R Description containerCapture Boolean Optional A Boolean that specifies capture mode. toXML * String Serializes Node to string. Sytaxis: object.toXML() toggleItemSelection * Void If the specified item is selected, it is deselected. If it is not selected, it is selected. Other items in the list box that are selected are not affected, and retain their selected state. Sytaxis: object.toggleItemSelection(item) Arguments: Name Type O/R Description item Element Required Element whose selection state to be inverted. Event B C Interface Description DOMActivate * + + UIEvent An activation behavior requested from element. DOMAttrModified * + - MutationEvent Occurs after Attr.value has been modified and after an Attr node has been added to or removed from an Element. DOMFocusIn * + - UIEvent An object receives focus. The focus is given to the element before the dispatch of this event type. This event type is dispatched after the event type focus. DOMFocusOut * + - UIEvent An object loses focus. The focus is taken from the element before the dispatch of this event type. This event type is dispatched after the event type blur. DOMNodeInserted * + - MutationEvent A node has been added as a child of another node or, in case of Attr nodes, has been added to an Element. DOMNodeInsertedIntoDocument * - - MutationEvent A node has been inserted into a document. DOMNodeRemoved * + - MutationEvent A node is being removed from its parent node or, in case of Attr nodes, removed from its ownerElement. DOMNodeRemovedFromDocument * - - MutationEvent A node is being removed from a document. abort * - - Event Fires when the loading of a resource has been aborted. blur * - - UIEvent Fires when element looses focus. capture * + - UIEvent Fires when user clicks outside element set to receive capture. click * + + MouseEvent A pointing device button is clicked over an element. contextmenu * + + MouseEvent Fires when the user clicks the right mouse button in the client area, opening the context menu. dblclick * + + MouseEvent Fires when the user double-clicks the object. drag * + + DragEvent Fires on the source object continuously during a drag operation. dragend * + + DragEvent Fires on the source object when the user releases the mouse at the close of a drag operation. dragenter * + + DragEvent Fires on the target element when the user drags the object to a valid drop target. dragleave * + + DragEvent Fires on the target object when the user moves the mouse out of a valid drop target during a drag operation. dragover * + + DragEvent dragstart * + + DragEvent Fires on the source object when the user starts to drag an object. drop * + + DragEvent Fires on the target object when the mouse button is released during a drag-and-drop operation. effectend * - - Event Fires when effect is ended. effectstart * - - Event Fires when effect is started. error * - - Event Fires when a resource failed to load. focus * - - UIEvent Fires when element receives focus. gesturechange * + + GestureEvent Sent when fingers are moved during a gesture. gestureend * + + GestureEvent Sent when the gesture ends (when there are 1 or 0 fingers touching the surface). gesturestart * + + GestureEvent Sent when two or more fingers touch the surface. keydown * + + KeyboardEvent A key is pressed down. keypress * + + KeyboardEvent It is recommended that you use textInput event instead. keyup * + + KeyboardEvent A key is released. load * - - Event Fires after the DOM implementation finishes loading the resource. localechange * - - CustomEvent Fires when locale has been successfully changed. The detail property keeps the new locale name name. losecapture * - - UIEvent Fires when the object is losing the mouse capture. modal * + - UIEvent Fires when user clicks outside element set as modal. mousedown * + + MouseEvent A pointing device button is pressed over an element. mouseenter * - - MouseEvent Fires when the user moves the mouse pointer into the object. mouseleave * - - MouseEvent Fires when the user moves the mouse pointer outside the boundaries of the object. mousemove * + + MouseEvent A pointing device is moved while it is over an element. mouseout * + + MouseEvent A pointing device is moved away from an element. mouseover * + + MouseEvent A pointing device is moved onto an element. mouseup * + + MouseEvent A pointing device button is released over an element. mousewheel * + + WheelEvent Fires when the user wheels the mouse within the boundaries of the object. resize * + + ResizeEvent Fires continuously while user is resizing object. resizeend * + + ResizeEvent Fires when user ends resizing an object. resizestart * + + ResizeEvent Fires when user starts resizing an object. select * + + Event Fires when selection changes. textinput * + + TextEvent User typed in a character. touchcancel * + + TouchEvent Sent when the system cancels tracking for the touch. touchend * + + TouchEvent Sent when a given event lifts from the surface. touchmove * + + TouchEvent Sent when a given event moves on the surface. touchstart * + + TouchEvent Sent when a finger for a given event touches the surface. unload * - - Event Fires before the DOM Implementation removes from the environment the resource. Pseudo-class Description drag * Applied to the drag source during operation drop * Applied to the drop target when it is allowed focus * Applied to the element when it has focus hover * Applied to the element while mouse is over load * Applied to the element being loaded resize * Applied to the element being resized selected * Applied to element when it is selected. Constant Value Description