XulPlanet.com - Textbox (Mozilla Auto Complete) Reference

Textbox (Mozilla Auto Complete)

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.

The textbox (Mozilla Auto Complete) element implements the following interfaces:

nsIAccessibleProvider nsIDOMXULMenuListElement

Attributes:

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 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 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 on both sides.
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 textbox is disabled or not. If this attribute is set to true, the textbox is disabled. This is usually drawn with the text in grey. If the textbox is disabled, it does not respond to user actions. The element cannot be focused and the command event will not fire. The element will still respond to mouse events. To enable the textbox, leave the attribute out entirely as opposed to setting the value to false.

disablehistory

If false, an arrow button will appear on the end of the textbox which, when pressed, will open a dropdown menu of the history items. The default value is true, which will hide the dropdown button.

focused

Type: boolean

This attribute is set to true if the textbox 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 textbox. If this is left out, no text appears.

maxlength

Type: integer

The maximum number of characters that the textbox allows to be entered.

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.

minResultsForPopup

Type: integer

The minimum number of results that must be returned for the popup to be displayed.

nomatch

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

onerrorcommand

This event handler is called when an error occurs when selecting a result from the popup.

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

Type: boolean

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

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

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 order sequence.

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.

type

Type: string

Set to the value 'autocomplete' to have an autocomplete textbox.

userAction

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 default value entered in the textbox. The attribute only holds the default value and is never modified when the user enters text. To get the updated value, use the value property.

Properties and Methods:

Inherited from XUL Element:

align
allowEvents
blur
boxObject
boxObject.element
boxObject.getLookAndFeelMetric
boxObject.height
boxObject.screenX
boxObject.screenY
boxObject.width
boxObject.x
boxObject.y
builder
className
click
collapsed
contextMenu
controllers
database
datasources
dir
doCommand
flex
focus
getElementsByAttribute
height
hidden
id
left
maxHeight
maxWidth
menu
minHeight
minWidth
observes
ordinal
orient
pack
persist
ref
resource
statusText
style
tooltip
tooltipText
top
width

Inherited from Element:

addEventListener
appendChild
attributes
childNodes
cloneNode
dispatchEvent
firstChild
getAttribute
getAttributeNS
getAttributeNode
getAttributeNodeNS
getElementsByTagName
getElementsByTagNameNS
hasAttribute
hasAttributeNS
hasAttributes
hasChildNodes
insertBefore
isSupported
lastChild
localName
namespaceURI
nextSibling
nodeName
nodeType
nodeValue
normalize
ownerDocument
parentNode
prefix
previousSibling
removeAttribute
removeAttributeNS
removeAttributeNode
removeChild
removeEventListener
replaceChild
setAttribute
setAttributeNS
setAttributeNode
setAttributeNodeNS
tagName

accessible

Type: nsIAccessible

Returns the accessibility object for the 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.

alwaysOpenPopup

Gets and sets the value of the alwaysopenpopup attribute.

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

Type: string

Gets and sets the value of the crop attribute.

disableAutocomplete

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

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.

getSessionStatusAt ( index )

Returns the status for the session object with the given index.

getSessionValueAt ( session , index )

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

ignoreBlurWhileSearching

Type: boolean

If true, blur events are ignored while searching, which means that the autocomplete popup will not disappear.

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

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

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

Gets and sets the value of the maxrows attribute.

minResultsForPopup

Gets and sets the value of the minResultsForPopup 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

Type: space separated list of session names

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

select ( )

Return Type: no return value

Select all the text in the textbox.

selectionEnd

Type: integer

Get or modify the end of the selected portion of the field's text. Use in conjuction with the selectionEnd property. The value specifies the index of the character after the selection. If this value is equal to 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 modify 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

Holds the number of sessions.

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.

tabIndex Mozilla 1.8

Type: integer

Get and sets the value of the tabindex attribute.

accessible	addSession	alwaysOpenPopup	autoFill	autoFillAfterMatch
clearResults	crop	disableAutocomplete	disabled	editable
focused	forceComplete	getDefaultSession	getResultAt	getResultCount
getResultValueAt	getSession	getSessionByName	getSessionResultAt	getSessionStatusAt
getSessionValueAt	ignoreBlurWhileSearching	inputField	isSearching	isWaiting
label	maxLength	maxRows	minResultsForPopup	noMatch
open	removeSession	resultsPopup	searchSessions	select
selectionEnd	selectionStart	sessionCount	setSelectionRange	showCommentColumn
showPopup	size	syncSessions	tabIndex	tabScrolling
textLength	timeout	type	userAction	value