textbox (Toolkit autocomplete)

In This Article

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

This element is created by setting the type attribute of the 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.

Toolkit applications (such as Firefox) use a different autocomplete mechanism than the Mozilla suite. The example below will create an autocomplete textbox that will search the user's history.

Attributes: accesskey, autocompletepopup, autocompletesearch, autocompletesearchparam, completedefaultindex, completeselectedindex,crop, disableautocomplete, disabled, disablekeynavigation, enablehistory, focused, forcecomplete, highlightnonmatches, ignoreblurwhilesearching, inputtooltiptext, label, maxlength, maxrows, minresultsforpopup, nomatch, onchange, oninput, onsearchcomplete, ontextentered, ontextreverted, open, readonly,showcommentcolumn, showimagecolumn, size, tabindex, tabscrolling, timeout, type, value

Properties: accessibleType, completeDefaultIndex, controller, crop, disableAutoComplete, disableKeyNavigation, disabled, editable, focused, forceComplete, highlightNonMatches, ignoreBlurWhileSearching, inputField, label, maxLength, maxRows, minResultsForPopup, open, popup, popupOpen, searchCount, searchParam, selectionEnd, selectionStart, showCommentColumn, showImageColumn,size, tabIndex, tabScrolling, textLength, textValue, timeout, type, value

Methods: getSearchAt, onSearchComplete, onTextEntered, onTextReverted, select, setSelectionRange

Examples

<textbox type="autocomplete" autocompletesearch="history"/>

Attributes

accesskey: Type: character; This should be set to a character that is used as a shortcut key. This should be one of the characters that appears in the label label for the element.

autocompletepopup: Type: id; The id of a popup element used to hold autocomplete results for the element.

autocompletesearch New in Thunderbird 2Requires SeaMonkey 1.1: Type: space-separated list of values; A space-separated list of search component names, each of which implements the nsIAutoCompleteSearch interface. The components are created using the name @mozilla.org/autocomplete/search;1?name= where name is listed in this attribute.

search-autocomplete Requires SeaMonkey 2.1: The user's default search engine's suggestions are searched.
places-tag-autocomplete Requires SeaMonkey 2.1: The user's Places tags are searched.
mydomain New in Thunderbird 3 Requires SeaMonkey 2.0: The user's email domain is suggested.
history Requires SeaMonkey 2.0: The user's URL history is searched.
form-history Requires SeaMonkey 2.0: Search the values that the user has entered into form fields.
file (Linux only): The local file system is searched.
gloda New in Thunderbird 3
addrbook New in Thunderbird 3 Requires SeaMonkey 2.0: The user's address book is searched.
ldap New in Thunderbird 25 Requires SeaMonkey 2.22: The user's LDAP directory is searched.

autocompletesearchparam New in Thunderbird 2 Requires SeaMonkey 1.1: Type: string; A string which is passed to the search component.

completedefaultindex New in Thunderbird 3 Requires SeaMonkey 2.0: Type: boolean; If true, the best match value will be filled into the textbox as the user types. If set to false or omitted, the value must be selected from the list.

completeselectedindex: Type: boolean; If true, the text in the text field will be autocompleted as the user selects from the popup list.

crop: Type: boolean; This attribute is not used and is only provided for compatibility with the menulist element.

disableautocomplete New in Thunderbird 3Requires SeaMonkey 2.0: 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.; Visible controls have a disabled property which, except for menus and menuitems, is normally preferred to use of the attribute, as it may need to update additional state.

disableKeyNavigation: Type: boolean; If this attribute is not used, the user can navigate to specific items within the element by pressing keys corresponding to letters in the item's label. This is done incrementally, so typing more letters with select more specific items. This feature may be disabled by setting this attribute to true.

Note: For SeaMonkey 2.0 and all versions of Thunderbird prior to 3.0 you also need to provide the disablehistory attribute.

enablehistory New in Thunderbird 1Requires SeaMonkey 2.0: Type: boolean; If true, an arrow button will appear on the end of the textbox which, when pressed, will open a dropdown menu of all available results.

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

forcecomplete New in Thunderbird 3Requires SeaMonkey 2.0: 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.

highlightnonmatches New in Thunderbird 3 Requires SeaMonkey 2.0: Type: boolean; If true, then the autocomplete field will be highlighted when no match has been found.

ignoreblurwhilesearching New in Thunderbird 3Requires SeaMonkey 2.0: 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. For an editable menuitem element the value of this attribute is copied to the menulist.value property upon user selection of the menuitem.

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 New in Thunderbird 3Requires SeaMonkey 2.0: Type: integer; The minimum number of results that must be returned for the popup to be displayed. The default value is 1. Firefox 21New in Thunderbird 3Requires SeaMonkey 2.0 A zero value will always open the popup. This can be used to display additional items that are not autocomplete results.

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

Overview

An onchange attribute is an event listener to the object for the Event change. A change event is fired in different ways for different XUL Input Elements as listed below:

onchange: Type: script code

TextBox	When Enter key is pressed
Radio/Check Box	When the state is changed
Select List	When the selected item is changed

What is accessible

The script context at this point can only access the following things:

Global Values/Functions i.e. window, document, or any of the functions/objects/variables bound to the window object
Event object

Example

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css"?>
<window
    id="findfile-window"
    title="Find Files"
    orient="horizontal"
    xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <script type="text/javascript">
  function myFunction(e){
    /*
      Do something cool here or just say the below
    */
    alert(e.target.nodeName);
  }
  </script>
  <textbox id="find-text" onchange="return myFunction(event);"/>
</window>

oninput: Type: script code; This event is sent when a user enters text in a textbox. This event is only called when the text displayed would change, thus it is not called when the user presses non-displayable keys.

onsearchbegin: Type: script code; This event handler is called when the autocomplete search begins.

Note: For Firefox 12 and above, this event handler must be set as an initial attribute.

onsearchcomplete New in Thunderbird 3Requires SeaMonkey 2.0: Type: script code; This event handler is called when the autocomplete search is finished and results are available.

Note: For Firefox 12 and above, this event handler must be set as an initial attribute.

ontextentered New in Thunderbird 3Requires SeaMonkey 2.0: Type: script code; This event handler is called when a result is selected for the textbox.

Note: For Firefox 12 and above, this event handler must be set as an initial attribute.

ontextreverted New in Thunderbird 3Requires SeaMonkey 2.0: Type: script code; This event handler is called when the user presses Escape to revert the textbox to its original uncompleted value.

Note: For Firefox 12 and above, this event handler must be set as an initial attribute.

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.

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.

showcommentcolumn New in Thunderbird 3Requires SeaMonkey 2.0: 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.

showimagecolumn: Type: boolean; If true, an image column appears in the popup. There is no default styling of this image, but the class name returned by the results appears in the property list for the column. If this attribute is not specified, the image column doesn't appear.

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

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.

tabscrolling New in Thunderbird 3Requires SeaMonkey 2.0: 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.

timeout: Type: integer; For autocomplete textboxes, the number of milliseconds before the textbox starts searching for completions. The default is 50 milliseconds. For search textboxes, the number of milliseconds before the timer fires a command event. The default is 500 milliseconds. For timed textboxes, the number of milliseconds before the timer fires a command event. There is no default. 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 (XPFE [Thunderbird/SeaMonkey]) (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 decimalplaces, min, max, increment, wraparound, hidespinbuttons, and textbox.value.
password: A textbox that hides what is typed, used for entering passwords.
search: A textbox intended for searching. The command event will fire as the user modifies the value. A listener for the command event should update search results. If the searchbutton attribute is set to true, the command event is only fired if the user presses the search button or presses the Enter key. You may specify grey text to appear when the search box is empty using the emptytext attribute, and a timeout may be set for the command event using the timeout attribute (defaults to 500).
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. The command event will fire if the user presses the Enter key. The timed type is deprecated in Gecko 1.9.1 and the search textbox may be used instead.

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. Be aware, however, that some elements, such as textbox will display the value visually, so in order to merely associate data with an element, you could 1) Use another attribute like "value2" or "data-myAtt" (as in the HTML5 draft), as XUL does not require validation (less future-proof); 2) Use setAttributeNS() to put custom attributes in a non-XUL namespace (serializable and future-proof); 3) Use setUserData() (future-proof and clean, but not easily serializable). For user editable menulist elements, the contents, as visible to the user, are read and set using the Menulist.value syntax. For those elements, setAttribute("value", myValue) and getAttribute("value") do not access or affect the contents displayed to the user.

Properties

accessibleType: Type: integer; A value indicating the type of accessibility object for the element.

completeDefaultIndex New in Thunderbird 3Requires SeaMonkey 2.0: Type: boolean; Gets and sets the value of the completedefaultindex attribute.

controller: Type: nsIAutoCompleteController; Returns the controller for the auto complete element.

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

disableAutocomplete: Type: boolean; Gets and sets the value of the disableautocomplete (or disableAutocomplete) attribute.

disableKeyNavigation: Type: boolean; Gets or sets the value of the disableKeyNavigation attribute.

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

editable: Type: boolean; Returns true if the element is editable. Autocomplete fields are editable so this property always returns true for those.

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

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

highlightNonMatches New in Thunderbird 1 Requires SeaMonkey 1.0: Type: boolean; Gets and sets the value of the highlightnonmatches attribute.

ignoreBlurWhileSearching: Type: boolean; Gets and sets the value of the ignoreblurwhilesearching (or 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.

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 (or minResultsForPopup) attribute.

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

popupOpen New in Thunderbird 15 Requires SeaMonkey 2.12: Type: boolean; Indicates whether the popup is open or not. Set this property to open or close the popup.

searchCount New in Thunderbird 15 Requires SeaMonkey 2.12: Type: integer; Returns the number of search components used. This property is read only.

searchParam New in Thunderbird 15 Requires SeaMonkey 2.12: Type: string; Gets and sets the value of the autocompletesearchparam attribute.

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.

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

showImageColumn: Type: boolean; Gets and sets the value of the showimagecolumn 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 (or tabScrolling) attribute.

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

textValue New in Thunderbird 15 Requires SeaMonkey 2.12: Type: string; Returns the content of the textbox. Equivalent to the value property.

Note: Setting the value causes an input event to be generated without triggering autocompletion.

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

type: Type: string; Set to the value autocomplete to have an autocomplete textbox.

value: Type: string; Gets and sets the value of the value attribute. For textbox and user editable menulist elements, the contents, as visible to the user, are read and set using the Textbox.value and Menulist.value syntax.

Methods

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature(), getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData

getSearchAt( index ): Return type: string; Returns the search component with the given index. The components are set with the autocompletesearch attribute.

onSearchComplete(): Return type: no return value; Calls the onsearchcomplete event handler. You should not call this method yourself.

onTextEntered(): Return type: event result; Calls the ontextentered event handler. You should not call this method yourself.

onTextReverted(): Return type: event result; Calls the ontextreverted event handler. You should not call this method yourself.

select(): Return type: no return value; Selects 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.

Interfaces: nsIAccessibleProvider, nsIAutoCompleteInput, nsIDOMXULMenuListElement

Articles: How to implement custom autocomplete search component

Document Tags and Contributors

Tags:

Contributors to this page: Sheppy, wsha, Imphil, Neil, flx, trevorh, markovskiydima, Enn, Marsf, Mgjbot, Ptak82, Dria

Last updated by: Sheppy, Apr 14, 2014, 10:34:44 AM