XUL Tutorial - Focus and Selection

The section will describe how to handle the focus and selection of elements.

Focused Elements

The focused element refers to the element which currently receives input events. If there are three textfields on a window, the one that has the focus is the one that the user can enter text into. Only one element per window has the focus at a time.

The user can change the focus by clicking an element with the mouse or by pressing the TAB key. When the TAB key is pressed, the next element is given the focus.

The focus event is used to respond when the focus is given to an element. The blur event is used to respond when the focus is removed from an element. You can respond by adding an onfocus or onblur attribute on the element. They work just like their HTML counterparts. You might use these event handlers to highlight the element or display text on a status bar.

Unfortunately, they don't work quite yet in Mozilla. However, this is a simple workaround that allows you to add focus and blur event handlers using the DOM2 event functions. Focus and blur event handlers are not all that common so it shouldn't be much of a problem.

The function addEventListener can be used to add an event handler dynamically to an element. You can use it for any element and event type. It takes three parameters, the event type, a function to execute when the event occurs and a boolean indicating whether to capture or not.

The following example can be used to apply a function to handle a focus event.

XUL:

<window id="focus-test" title="Focus Test"
   xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
   onload="Init()">

<textfield id="tfield1"/>
<textfield id="tfield2"/>
<text id="sbar" value=""/>

</window>

Script:

function Init()
{
  var elem=document.getElementById('tfield2');
  elem.addEventListener('focus',displayFocus,true);
}

function displayFocus()
{
  var elem=document.getElementById('sbox');
  elem.setAttribute('value','Enter your phone number.');
}

In this example, the Init function is called when the page has loaded. The addEventListener function adds a focus event handler to the second textfield. This event, when it occurs, will call the displayFocus function. This function will change the value of the text label. We could extend this example to remove the text when the blur event occurs.

You can call the focus method of XUL elements to set the focus on a particular element. The blur method can be used to remove it. The following example demonstrates this:

<textfield id="addr"/>

<button value="Focus" onclick="document.getElementById('addr').focus()"/>

For textfields, a special attribute, focused is added whenever the element has the focus. You can check for the presence of this attribute to determine if the element has the focus, either from a script or with-in a style sheet. It will have the value true. If the text field does not have the focus, the attribute will not be present. This extra feature applies only to textfields, not to other elements.

Text Selection

The text with-in a textfield may be selected by the user. When working with textfields, you may wish to retreive not the entire contents of a field but only what the user has selected. Or, you may wish to change the current selection.

XUL textfields support a way to retreive and modify the selection. The simplest one is to select all of the text in a textfield. This involves using the select method of the textfield.

tfield.select();

However, you may wish to select only part of the text. To do this you can use the setSelectionRange function. It takes two parameters, the first is the starting character and the second is the character after the last one that you want to have selected. Values are zero-based, so the first character is 0, the second is 1 and so on.

tfield.setSelectionRange(4,8);

This example will select the fifth character displayed, as well as the sixth, seventh and eighth. If there were only six characters entered into the field, only the fifth and sixth characters would be selected. No error would occur.

If you use the same value for both parameters, the start of the selection changes and the end changes to the same position. This results in changing the cursor position with-in the text field. For example, the line below can be used to move the cursor to the beginning of the text.

tfield.setSelectionRange(0,0);

You can retrieve and modify the contents of the textfield by using the value attribute.

You can retreive the current selection by using the selectionStart and selectionEnd properties. These properties are set to the starting and ending positions of the current selection respectively. If both are set to the same value, no text is selected, but the values will be the current cursor position. Once you have the start and end positions, you can pull out the substring from the whole text.

One additional useful property of textfields is the textLength property, which holds the total number of characters in the field.

(Next) We've seen how to get and set the selection for textfields. Next, we'll find out to get and set the selection for trees.