Mozilla XUL Element and Script Reference

Contents  Quick Reference

Textbox(autocomplete)

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:

Attributes inherited from textbox

autoFill

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
crop

If the label of the textbox is too small to fit in its given space, the text will be cropped on the side specified by the crop attribute. An ellipsis will be placed in place of the cropped text. If the box direction is right to left (rtl), the cropping is reversed.

disableAutocomplete

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

flexPopup

If true, the default value, the popup will be stretched to the width of the textbox. If false, you must set the width of the popup yourself.

focused
forceComplete

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.

hideHistory
label

The label that will appear on the textbox. If this is left out, no text appears.

maxrows

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.

oninit

This event handler is called when the textbox is displayed.

ontextcommand

This event handler is called when a result is selected for the textbox.

ontextrevert

This event handler is called when the user presses Escape to revert the textbox to its original uncompleted value.

open

If true, the popup is showing. You can change this value to show or hide the popup.

searchSessions

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.

showCommentColumn

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. The default value of this property is false.

showPopup

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.

tabScrolling

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

Set to the number of milliseconds to wait between when the users presses a key and the results list updates. The default value is 50, which is very fast.

userAction

This attribute will be set to the action the user is currently performing. Possible values:

Properties and Methods:

Properties and Methods inherited from textbox

addSession ( session )

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.

autoFill

Gets and sets the value of the autoFill attribute.

autoFillAfterMatch

Gets and sets the value of the autoFillAfterMatch attribute.

clearResults ( )

Clears the results list.

crop

Gets and sets the value of the crop attribute.

disableAutocomplete

Gets and sets the value of the disableAutocomplete attribute.

flexPopup

Gets and sets the value of the flexPopup attribute.

focused

Gets and sets the value of the focused attribute.

forceComplete

Gets and sets the value of the forceComplete attribute.

getDefaultSession ( )

Returns the name of the first session with available results.

getResultAt ( index )

Returns the result item at the specified index. The item will be a value of type nsIAutoCompleteItem.

getResultCount ( session )

Returns the number of results. (The session argument is currently ignored).

getResultValueAt ( index )

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 )

Returns the session object with the given index. This will return an object of type nsIAutoCompleteSession.

getSessionByName ( name )

Returns the session object with the given name. This will return an object of type nsIAutoCompleteSession.

getSessionResultAt ( session , index )

Returns the result item at the specified index for a specific session.

getSessionValueAt ( session , index )

Returns the result value at the specified index for a specific session.

hideHistory

Gets and sets the value of the hideHistory attribute.

isSearching

This property is set to true while a search is occuring.

isWaiting

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

Gets and sets the value of the label attribute.

maxRows

Gets and sets the value of the maxrows attribute.

noMatch

This property will be set to true if the last search resulted in no matches.

open

Gets and sets the value of the open attribute.

removeSession ( session )

Removes a session object from the autocomplete widget. The argument should be an object which implements the nsIAutoCompleteSession interface.

resultsPopup

This property is set to the popup element that displays the results.

searchSessions

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.

sessionCount

showCommentColumn

Gets and sets the value of the showCommentColumn attribute.

showPopup

Gets and sets the value of the showPopup attribute.

syncSessions ( session )

tabScrolling

Gets and sets the value of the tabScrolling attribute.

timeout

Gets and sets the value of the timeout attribute.

userAction

Gets and sets the value of the userAction attribute.