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
- accesskey, alwaysopenpopup, autocompletesearch, autocompletesearchparam, autoFill, autoFillAfterMatch, autofill, completedefaultindex, crop, disableAutocomplete, disableautocomplete, disabled, disablehistory, enablehistory, focused, forceComplete, forcecomplete, highlightnonmatches, ignoreBlurWhileSearching, ignoreblurwhilesearching, inputtooltiptext, label, maxlength, maxrows, minResultsForPopup, minresultsforpopup, nomatch, onchange, onerrorcommand, oninput, onsearchcomplete, ontextcommand, ontextentered, ontextrevert, ontextreverted, open, readonly, searchSessions, showCommentColumn, showcommentcolumn, showpopup, size, tabindex, tabScrolling, tabscrolling, timeout, type, userAction, value
- Properties
- accessible, alwaysOpenPopup, autoFill, autoFillAfterMatch, completeDefaultIndex, crop, disableAutocomplete, disabled, editable, focused, forceComplete, highlightNonMatches, ignoreBlurWhileSearching, inputField, isSearching, isWaiting, label, maxLength, maxRows, minResultsForPopup, noMatch, open, popup, popupOpen, resultsPopup, searchCount, searchParam, searchSessions, selectionEnd, selectionStart, sessionCount, showCommentColumn, showPopup, size, tabIndex, tabScrolling, textLength, textValue, timeout, type, userAction, value
- Methods
- addSession, clearResults, getDefaultSession, getResultAt, getResultCount, getResultValueAt, getSession, getSessionByName, getSessionResultAt, getSessionStatusAt, getSessionValueAt, removeSession, select, setSelectionRange, syncSessions
Examples
(example needed)
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.
-
alwaysopenpopup
Obsolete since Gecko 1.9.1 - Type: boolean
-
Note: Applies to: Thunderbird and SeaMonkeyIf
true
, the autocomplete popup will be displayed even when there are no matches. Iffalse
, the default value, the popup will be hidden. This attribute is obsolete as of Gecko 1.9.1; to control the display of the popup, use theminresultsforpopup
attribute instead.
-
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.
-
autoFill
Obsolete since Gecko 1.9.1 - Type: boolean
-
Note: Applies to: Thunderbird and SeaMonkeyIf set to
true
, the best match will be filled into the textbox as the user types. Iffalse
, the default, the value will not be filled in until the user selects an item. As of Gecko 1.9.1, this attribute is now always specified in lower case.
-
autoFillAfterMatch
Obsolete since Gecko 1.9.1 - Type: boolean
-
If set to
true
, the entire text of the best match will be displayed at the end of the input. Iffalse
, only the text that hasn't been entered yet will be filled in. Thetextbox.autoFill
attribute must be set totrue
to use this feature. As of Gecko 1.9.1, this attribute is superseded by thecompletedefaultindex
attribute.
-
autofill
New in Thunderbird 3 Requires SeaMonkey 2.0 - Type: boolean
-
If set to
true
, the best match will be filled into the textbox as the user types. Iffalse
, the default, the value will not be filled in until the user selects an item.
-
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 tofalse
or omitted, the value must be selected from the list.
-
disableAutocomplete
Obsolete since Gecko 1.9.1 - Type: boolean
-
If
true
, the autocomplete behavior will be disabled. You might use a script to change this attribute. Iffalse
, the default, autocomplete is enabled. As of Gecko 1.9.1, this attribute is now always specified in lower case.
-
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. Iffalse
, 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 thecommand
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.
-
disablehistory
Obsolete since Gecko 2.0 - Type: boolean
-
Note: Applies to: Thunderbird and SeaMonkeyIf
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 istrue
, hiding the dropdown button. This attribute only works correctly in SeaMonkey 1.x; for Thunderbird and SeaMonkey 2.0 you should also set theenablehistory
attribute; as of Gecko 2.0 this attribute is completely superseded by it.
-
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
Obsolete since Gecko 1.9.1 - Type: boolean
-
If
true
, the textbox will be filled in with the best match when it loses the focus. Iffalse
, it will only be filled in when the user selects an item. As of Gecko 1.9.1, this attribute is now always specified in lower case.
-
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. Iffalse
, 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
Obsolete since Gecko 1.9.1 - Type: boolean
-
If
true
, blur events are ignored while searching, which means that the autocomplete popup will not disappear. As of Gecko 1.9.1, this attribute is now always specified in lower case.
-
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 themenulist
.value property upon user selection of themenuitem
.
-
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
Obsolete since Gecko 1.9.1 - Type: integer
- The minimum number of results that must be returned for the popup to be displayed. The default value is 1. A zero value will always open the popup unless the textbox is empty. This can be used to display additional items that are not autocomplete results. As of Gecko 1.9.1, this attribute is now always specified in lower case.
-
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="https://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>
-
onerrorcommand
- Type: script code
- This event handler is called when an error occurs when selecting a result from the popup.
-
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.
-
ontextcommand
Obsolete since Gecko 1.9.1 - Type: script code
-
Note: Applies to: Thunderbird, SeaMonkeyThis event handler is called when a result is selected for the textbox. As of Gecko 1.9.1, this attribute is superseded by the
ontextentered
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.
-
ontextrevert
Obsolete since Gecko 1.9.1 - Type: script code
-
Note: Applies to: Thunderbird, SeaMonkeyThis event handler is called when the user presses Escape to revert the textbox to its original uncompleted value. As of Gecko 1.9.1, this attribute is superseded by the
ontextreverted
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.
-
open
- Type: boolean
-
For the
menu
type
buttons, theopen
attribute is set totrue
when the menu is open. Theopen
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.
-
searchSessions
Obsolete since Gecko 26 - 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. Obsolete since Gecko 3addrbook
: The user's address book is searched. Obsolete since Gecko 3ldap
: The user's LDAP directories are searched. Obsolete since Gecko 25
-
showCommentColumn
Obsolete since Gecko 1.9.1 - 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. As of Gecko 1.9.1, this attribute is now always specified in lower case.
-
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.
showpopup
- Type: boolean
- Note: Applies to: Thunderbird, SeaMonkeyIf
true
, the popup will be shown. Iffalse
, the popup will not be shown, but the autocomplete results will still be available. You can set this tofalse
and set theautoFill
attribute totrue
to emulate a Communicator 4.x style autocomplete textbox. The default value istrue
.
-
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 highertabindex
are later in the tab sequence.
-
tabScrolling
Obsolete since Gecko 1.9.1 - Type: boolean
-
If
true
, the user may cycle through the results list by pressing the Tab key. Iffalse
, the default, the Tab key moves the focus to the next element.As of Gecko 1.9.1, this attribute is now always specified in lower case.
-
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. Iffalse
, 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
, andtextbox.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 totrue
, the command event is only fired if the user presses the search button or presses theEnter
key. You may specify grey text to appear when the search box is empty using theemptytext
attribute, and a timeout may be set for the command event using thetimeout
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 theEnter
key. Thetimed
type is deprecated in Gecko 1.9.1 and thesearch
textbox may be used instead.
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. 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
-
accessible
-
Type:
nsIAccessible
- Returns the accessibility object for the element.
-
alwaysOpenPopup
Obsolete since Gecko 1.9.1 - Type: boolean
-
Gets and sets the value of the
alwaysopenpopup
attribute.
-
autoFillAfterMatch
Obsolete since Gecko 1.9.1 - Type: boolean
-
Gets and sets the value of the
autoFillAfterMatch
attribute.
-
completeDefaultIndex
New in Thunderbird 3Requires SeaMonkey 2.0 - Type: boolean
-
Gets and sets the value of the
completedefaultindex
attribute.
disableAutocomplete
- Type: boolean
- Gets and sets the value of the
disableautocomplete
(ordisableAutocomplete
) attribute.
-
editable
- Type: boolean
-
Returns
true
if the element is editable. Autocomplete fields are editable so this property always returnstrue
for those.
forceComplete
- Type: boolean
- Gets and sets the value of the
forcecomplete
(orforceComplete
) 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
(orignoreBlurWhileSearching
) 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
-
Sets the
label
attribute. Gets thelabel
attribute if it is present and not empty. Otherwise it returns thevalue
of the associatedlabel
element, if applicable. Otherwise it returns theplaceholder
oremptyText
property. The getter is mostly useful for screen readers.Note: Prior to Firefox 3, and always in Thunderbird and SeaMonkey, the label property of an autocomplete textbox returns its value, for compatibility with themenulist
element.
-
maxLength
- Type: integer
- The maximum number of characters that the textbox allows to be entered.
minResultsForPopup
- Type: integer
- Gets and sets the value of the
minresultsforpopup
(orminResultsForPopup
) attribute.
-
noMatch
- Type: boolean
- This property will be set to
true
if the last search resulted in no matches.
-
popup
New in Thunderbird 14 Requires SeaMonkey 2.11 - Type: popup element
-
Should be set to the
popup
element that should appear when the user clicks on the textbox.
Note: This property is readonly in Thunderbird and SeaMonkey.
-
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.
-
resultsPopup
- Type: popup element
- This property is set to the popup element that displays the results.
-
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.
-
searchSessions
Obsolete since Gecko 26 - Type: space-separated list of session names
-
Gets the value of the
searchSessions
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 theselectionStart
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
(orshowCommentColumn
) attribute.
tabScrolling
- Type: boolean
- Gets and sets the value of the
tabscrolling
(ortabScrolling
) 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.
-
userAction
- Type: string
- Gets and sets the value of the
userAction
attribute.
-
value
- Type: string
-
Gets and sets the value of the
value
attribute. Fortextbox
and user editablemenulist
elements, the contents, as visible to the user, are read and set using theTextbox.value
and Menulist.value syntax.
Methods
-
addSession( session )
Obsolete since Gecko 26 -
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 )
Obsolete since Gecko 26 -
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 )
Obsolete since Gecko 26 -
Return type:
nsIAutoCompleteSession
-
Returns the session object with the given index. This will return an object of type
nsIAutoCompleteSession
.
-
getSessionByName( name )
Obsolete since Gecko 26 -
Return type:
nsIAutoCompleteSession
-
Returns the session object with the given name. This will return an object of type
nsIAutoCompleteSession
.
-
getSessionResultAt( session, index )
Obsolete since Gecko 26 - Return type: result item
- Returns the result item at the specified index for the specified session.
-
getSessionStatusAt( index )
Obsolete since Gecko 26 - Return type: Any value listed in nsIAutoCompleteStatus
- 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 <var>index</var> for a specific <var>session</var>.
-
removeSession( session )
Obsolete since Gecko 26 - Return type: void
-
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
- 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.
-
syncSessions( autoCompleteElement )
Obsolete since Gecko 26 - Return type: void
- Copy the sessions from another autocomplete element.
Related
- Interfaces
-
nsIAccessibleProvider
,nsIDOMXULMenuListElement