XUL:preference

From MDC

« XUL Reference home [ Examples | Attributes | Properties | Methods | Related ]

Declares a preference that may adjusted in a prefpane. This element must be placed inside a preferences element. Each preference element corresponds to a preference which is stored in the user's preferences file. You can connect a user interface element such as a checkbox to a preference element using the user interface element's preference attribute.

More information is available in the Preferences System article.

Attributes: disabled, instantApply, inverted, name, onchange, readonly, tabindex, type

Properties: disabled, inverted, locked, name, preferences, readonly, tabIndex, type, value

Methods: hasUserValue, reset

[edit] Examples

(example needed)

[edit] Attributes

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

disabled: Type: boolean; Indicates whether the element is disabled or not. If this element is set to true the element is disabled. Disabled elements are usually drawn with grayed-out text. If the element is disabled, it does not respond to user actions, it cannot be focused, and the command event will not fire.

instantApply: Type: boolean; If true, the preference will be changed as soon as the user interface is modified.

inverted: Type: boolean; For boolean preferences, if this attribute is set to true, it indicates that the value of the preference is the reverse of the user interface element attached to it. For instance, checking the checkbox disables the preference instead of enabling it.

name: Type: string; The name of the preference to change. For example, the browser's home page is set with the preference browser.startup.homepage.

onchange: Type: script code; The code in the onchange attribute is called when the value of the element is changed.

readonly: Type: boolean; If set to true, then the user cannot change the value of the element. However, the value may still be modified by a script.

tabindex: Type: integer; The tab order of the element. The tab order is the order in which the focus is moved when the user presses the "tab" key. Elements with a higher tabindex are later in the tab sequence.

type: Type: one of the values below; The preference type which should be one of the following values.

bool: A boolean set to either true or false. Usually a checkbox would be connected to these preferences.
int: An integer
string: A string
unichar: A Unicode string
wstring: A localized string. In this situation the preference will save the path to a property file which contains the actual value of the preference.
file: A file. The file path will be stored in the preferences.

[edit] Properties

Inherited from XUL element
align, allowEvents, boxObject, builder, className, collapsed, contextMenu, controllers, currentItem, database, datasources, dir, flex, height, hidden, id, left, listBoxObject, maxHeight, maxWidth, menu, minHeight, minWidth, observes, ordinal, orient, pack, persist, ref, resource, statusText, style, tooltip, tooltipText, top, value, width

Inherited from DOM element
attributes, childNodes, cloneNode, firstChild, lastChild, localName, namespaceURI, nextSibling, nodeName, nodeType, nodeValue, ownerDocument, parentNode, prefix, previousSibling, tagName

disabled: Type: boolean; Gets and sets the value of the disabled attribute.

inverted: Type: boolean; Gets and sets the value of the inverted attribute.

locked: Type: boolean; If true, the preference has been locked and disabled in the system configuration, preventing the value from being changed. This property is read-only.

name: Type: string; The name of the preference to change. For example, the browser's home page is set with the preference browser.startup.homepage.

preferences: Type: element; Reference to the containing preferences element.

readonly: Type: boolean; If set to true, then the user cannot modify the value of the element.; This all-lowercase property is only used with the preference element and may be renamed to readOnly in later versions. Other elements use the readOnly property. The corresponding attribute name is all-lowercase readonly.

tabIndex: Type: integer; Gets and sets the value of the tabindex attribute.

type: Type: string; Gets and sets the value of the type attribute.

value: Type: string; Gets and sets the value of the value attribute.

[edit] Methods

hasUserValue(): Return type: boolean; Returns true if the preference has been changed from its default value.

reset(): Return type: no return value; Resets the preference to its default value.; For a textbox it also clears the undo transaction list (Gecko 1.9).

Inherited from XUL element
blur, click, doCommand, focus, getElementsByAttribute

Inherited from DOM element
addEventListener, appendChild, dispatchEvent, getAttribute, getAttributeNode, getAttributeNodeNS, getAttributeNS, getElementsByTagName, getElementsByTagNameNS, hasAttribute, hasAttributeNS, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeAttribute, removeAttributeNode, removeAttributeNS, removeChild, removeEventListener, replaceChild, setAttribute, setAttributeNode, setAttributeNodeNS, setAttributeNS