XUL:textbox (Mozilla autocomplete)

From MDC

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

This element is created by setting the type attribute of a textbox to autocomplete. It is used to create a textbox with a popup containing a list of possible completions for what the user has started to type.

The autocomplete functionality is handled through one of more session objects, each of which can return a set of results given the current value of the textbox. The sessions can be set using the searchSessions attribute or by calling the addSession method.

Attributes: alwaysopenpopup, autoFill, autoFillAfterMatch, crop, disableAutocomplete, disabled, disablehistory, focused, forceComplete, ignoreBlurWhileSearching, inputtooltiptext, label, maxlength, maxrows, minResultsForPopup, nomatch, onerrorcommand, ontextcommand, ontextrevert, open, searchSessions, showCommentColumn, showpopup, size, tabScrolling, tabindex, timeout, type, userAction, value

Properties: accessible, alwaysOpenPopup, autoFill, autoFillAfterMatch, crop, disableAutocomplete, disabled, editable, focused, forceComplete, ignoreBlurWhileSearching, inputField, isSearching, isWaiting, label, maxLength, maxRows, minResultsForPopup, noMatch, open, resultsPopup, searchSessions, selectionEnd, selectionStart, sessionCount, showCommentColumn, showPopup, size, tabIndex, tabScrolling, textLength, timeout, type, userAction, value

Methods: addSession, clearResults, getDefaultSession, getResultAt, getResultCount, getResultValueAt, getSession, getSessionByName, getSessionResultAt, getSessionStatusAt, getSessionValueAt, removeSession, select, setSelectionRange, syncSessions

[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

alwaysopenpopup: Type: boolean; If true, the autocomplete popup will be displayed even when there are no matches. If false, the default value, the popup will be hidden.

autoFill: Type: boolean; If set to true, the best match will be filled into the textbox as the user types. If false, the default, the value will not be filled in until the user selects an item.

autoFillAfterMatch: Type: boolean; If set to true, the entire text of the best match will be displayed at the end of the input. If false, only the text that hasn't been entered yet will be filled in. The autoFill attribute must be set to true to use this feature.

crop: Type: one of the values below; If the label of the element is too big to fit in its given space, the text will be cropped on the side specified by the crop attribute. An ellipsis will be used in place of the cropped text. If the box direction is reversed, the cropping is reversed.

start: The text will be cropped on its left side.
end: The text will be cropped on its right side.
left: Deprecated The text will be cropped on its left side.
right: Deprecated The text will be cropped on its right side.
center: The text will be cropped in the middle, showing both the start and end of the text normally.
none: The text will be not be cropped using an ellipsis. However, the text will simply be cut off if it is too large. The side depends on the CSS text alignment.

disableAutocomplete: Type: boolean; If true, the autocomplete behavior will be disabled. You might use a script to change this attribute. If false, the default, autocomplete is enabled.

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.

disablehistory: Type: boolean; If false, an arrow button will appear on the end of the textbox which will open a dropdown menu of all available results. The default value is true, hiding the dropdown button.

focused: Type: boolean; This attribute is true if the element is focused.

forceComplete: Type: boolean; If true, the textbox will be filled in with the best match when it loses the focus. If false, it will only be filled in when the user selects an item.

ignoreBlurWhileSearching: Type: boolean; If true, blur events are ignored while searching, which means that the autocomplete popup will not disappear.

inputtooltiptext: Type: string; The tooltip text for the textbox.

label: Type: string; The label that will appear on the element. If this is left out, no text appears.

maxlength: Type: integer; The maximum number of characters that the textbox allows to be entered.

maxrows: Type: integer; The number of rows to show in the results list at a time. A scrollbar will appear so the user can scroll through the remaining items.

minResultsForPopup: Type: integer; The minimum number of results that must be returned for the popup to be displayed.

nomatch: Type: boolean; This attribute will be set to true if the last search resulted in no matches.

onerrorcommand: Type: script code; This event handler is called when an error occurs when selecting a result from the popup.

ontextcommand: Type: script code; This event handler is called when a result is selected for the textbox.

ontextrevert: Type: script code; This event handler is called when the user presses Escape to revert the textbox to its original uncompleted value.

open: Type: boolean; For the menu type buttons, the open attribute is set to true when the menu is open. The open attribute is not present if the menu is closed.

searchSessions: Type: space-separated list of session names; Set to a keyword indicating what type of data to look up for autocomplete. You may set multiple types by separating their names by spaces. The following values are possible, although custom components may be installed which add others.

history: The user's URL history is searched.
addrbook: The user's address book is searched.
ldap: The user's LDAP directories are searched.

showCommentColumn: Type: boolean; If true, a comment column appears in the popup. For the URL history, the comment column will contain the page titles associated with each URL. If this attribute is not specified, the comment column doesn't appear.

showpopup: Type: boolean; If true, the popup will be shown. If false, the popup will not be shown, but the autocomplete results will still be available. You can set this to false and set the autoFill attribute to true to emulate a Communicator 4.x style autocomplete textbox. The default value is true.

size: Type: integer; The number of characters that can be displayed in the textbox.

tabScrolling: Type: boolean; If true, the user may cycle through the results list by pressing the Tab key. If false, the default, the Tab key moves the focus to the next element.

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.

timeout: Type: integer; For timed textboxes, the number of milliseconds before the timer fires a command event. The timer starts after the user types a character. If the user types another character, the timer resets.

type: Type: one of the values below; You can set the type attribute to one of the values below for a more specialized type of textbox. Don't set the type if you wish to use a regular textbox.

autocomplete: A textbox that supports autocomplete. For more information about autocomplete textboxes, see the autocomplete documentation (Mozilla) (Firefox)
number: A textbox that only allows the user to enter numbers. In addition, arrow buttons appear next to the textbox to let the user step through values. There are several attributes that allow the number textbox to be configured, including min, max, increment, wraparound, and hidespinbuttons. New in Firefox 3
password: A textbox that hides what is typed, used for entering passwords.
timed: This textbox will fire a command event after the user types characters and a certain time has passed. The delay is set with the timeout attribute. You might use this type, for instance, to update information elsewhere in the window as the user types, without the need for continuous updates since the timer will not fire if the user types more keys in the meantime. The command event will also fire if the user presses the Enter key.

userAction: Type: one of the values below; This attribute will be set to the action the user is currently performing. Possible values:

none: The user is not interacting with the textbox.
typing: The user is typing into the textbox.
scrolling: The user is scrolling through the textbox.

value: Type: string; The string attribute allows you to associate a data value with an element. It is not used for any specific purpose, but you can access it with a script for your own use.

[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

accessible: Type: nsIAccessible; Returns the accessibility object for the element.

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

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

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

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

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

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

editable: Type: boolean; Autocomplete fields are editable so this property always returns true.

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

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

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

inputField: Type: textbox element; In Mozilla, the XUL textbox is implemented as a wrapper around an HTML input element. This read only property holds a reference to this inner input element.

isSearching: Type: boolean; This property is set to true while a search is occuring.

isWaiting: Type: boolean; This property is set to true during the period while waiting for the timeout between the time when a user has pressed a key and a search is performed.

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

maxLength: Type: integer; The maximum number of characters that the textbox allows to be entered.

maxRows: Type: integer; Gets and sets the value of the maxrows attribute.

minResultsForPopup: Type: integer; Gets and sets the value of the minresultsforpopup attribute.

noMatch: Type: boolean; This property will be set to true if the last search resulted in no matches.

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

resultsPopup: Type: popup element; This property is set to the popup element that displays the results.

searchSessions: Type: space-separated list of session names; Set to a keyword indicating what type of data to look up for autocomplete. You may set multiple types by separating their names by spaces. The following values are possible, although custom components may be installed which add others.

history: The user's URL history is searched.
addrbook: The user's address book is searched.
ldap: The user's LDAP directories are searched.

selectionEnd: Type: integer; Get or set the end of the selected portion of the field's text. Use in conjuction with the selectionStart property. The value specifies the index of the character after the selection. If this value is equal to the value of the selectionStart property, no text is selected, but the value indicates the position of the caret (cursor) within the textbox.

selectionStart: Type: integer; Get or set the beginning of the selected portion of the field's text. Use in conjuction with the selectionEnd property. The value specifies the index of the first selected character.

sessionCount: Type: integer; Holds the number of sessions.

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

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

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

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

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

textLength: Type: integer; Holds the length of the text entered in the textbox. This property is read-only.

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

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

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

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

[edit] Methods

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

addSession( session ): Return type: nsIAutoCompleteSession; Adds a new session object to the autocomplete widget. This can be used to create a customized autocomplete results list. The argument should be an object which implements the nsIAutoCompleteSession interface. This method returns the object passed in.

clearResults(): Return type: ???; Clears the results list.

getDefaultSession: Return type: session name; Returns the name of the first session with available results.

getResultAt( index ): Return type: nsIAutoCompleteItem; Returns the result item at the specified index. The item will be a value of type nsIAutoCompleteItem.

getResultCount( session ): Return type: ???; Returns the number of results. (The session argument is currently ignored.)

getResultValueAt( index ): Return type: result value; Returns the result value at the specified index. The item will correspond to the text of that item that appears in the popup.

getSession( index ): Return type: nsIAutoCompleteSession; Returns the session object with the given index. This will return an object of type nsIAutoCompleteSession.

getSessionByName( name ): Return type: nsIAutoCompleteSession; Returns the session object with the given name. This will return an object of type nsIAutoCompleteSession.

getSessionResultAt( session, index ): Return type: result item; Returns the result item at the specified index for the specified session.

getSessionStatusAt( index ): Return type: ???; Returns the status for the session object with the given index.

getSessionValueAt( session, index ): Return type: result value; Returns the result value at the specified index for a specific session.

removeSession( session ): Return type: ???; Removes a session object from the autocomplete widget. The argument should be an object which implements the nsIAutoCompleteSession interface.

select(): Return type: no return value; Select all the text in the textbox.

setSelectionRange( start, end ): Return type: no return value; Sets the selected portion of the textbox, where the start argument is the index of the first character to select and the end argument is the index of the character after the selection. Set both arguments to the same value to move the cursor to the corresponding position without selecting text.