XULPlanet.com has returned. Please refer to the documentation there as the information here may be out of date.

Previous Next

Adding Event Handlers

The find files dialog so far looks quite good. We haven't cleaned it up much but we have created a simple user interface easily. Next, we will show how to add scripts to it.

Responding to Events

To make the find files dialog functional, we need to add some scripts which will execute when the interacts with the dialog. We would want to add a script to handle the Find button, the Cancel button and to handle each menu command. We write this using JavaScript functions much in the same way as HTML.

If you know HTML, you may be able to guess how we make the buttons and other XUL elements respond to events. We can just add handlers such as onmousedown on the elements. Then we provide a script which executes the desired function.

You can use the script element to include scripts in XUL files. You can embed the script code directly in the XUL file in between the opening and closing script tags but it is much better to include code in a separate file. Your XUL window will load faster. Instead, we use the src attribute to link in an external script file.

Let's add a script to the find file dialog. Although it does not matter what the script file is called, usually it would be the same as the XUL file with a js extension. In this case, findfile.js will be used. Add the line below just after the opening window tag and before any elements. 

<script src="findfile.js"/>

We'll create the script file later when we know what we want to put it in it. We'll define some functions in the file and we can call them in event handlers.

Event handlers in XUL are done much in the same way as they are in HTML. The same event handlers are available plus some additional ones. To handle an event, simply add one of the attributes in the table below to an element. There are a number of other ones you can add also but we'll see those in later sections.

onclick Called when the mouse is pressed and released on an element. You should only use the onclick event when you have a reason to only respond to mouse clicks. For buttons, menu items and the like, you would use oncommand to respond, because it also catches users who use the keyboard or other devices.
onmousedown Called when a mouse button is pressed down on an element. The event handler will be called as soon as a mouse button is pressed, even if it hasn't been released yet.
onmouseup Called when a mouse button is released on an element
onmouseover Called when the mouse pointer is moved onto an element. You could use this to highlight the element, however CSS provides a way to do this automatically so you shouldn't do it with an event. You might, however, want to display some help text on a status bar.
onmousemove Called when the mouse pointer is moved while over an element. The event will be called many times if the user moves the mouse so you should try to avoid using this handler if you can.
onmouseout Called when the mouse pointer is moved off of an element. You might then unhighlight the element or remove status text.
oncommand This event is called when a button or menu item is selected. For menus, add this handler to the menuitem element. You should use this handler rather than handling the mouse yourself as the user might select the button or menu item with the mouse or by pressing the access key or keyboard shortcut.
onkeypress Called when a key is pressed and released when an element has the focus. You might use this to add extra shortcut key handling or to check for allowed characters in a field. We'll see how to create keyboard shortcuts in a later section.
onkeydown Called when a key is pressed down while an element has the focus. Note that the event will be called as soon as the key is pressed, even if it hasn't been released. You probably won't use this event very often as the other key events are more suitable.
onkeyup Called when a key is released while an element has the focus.
onfocus Called when an element receives the focus either by clicking with the mouse or by using the TAB key. You might use this event to highlight the element or display some help text.
onblur Called when an element loses the focus either by a user clicking on another element or by pressing TAB. You might use this to verify information or close popups. It is better to verify fields when the OK button is clicked however.
onload Called on a window when it first opens. You would usually add this event handler to a window tag in order to initialize a window. This would allow fields to be set to default values based on conditions contained in a script.
onunload Called when the window is closing. You would usually add this to the window tag to record information before the window closes.

The oncommand is the handler you will usually use to respond to respond to buttons and menus. You can put code here which is executed when the user clicks on the element, or activates it with the keyboard.

An oncommand handler can be placed on the Find and Cancel buttons in the file files dialog. Clicking the Find button should start the search. Because we aren't going to implement this part, we'll leave it out. However, clicking the Cancel button should close the window. The code below shows how to do this. While we're at it, let's add the same code to the Close menu item. 

<menuitem label="Close" accesskey="c" oncommand="window.close();"/>
...
  
<button id="cancel-button" label="Cancel"
     oncommand="window.close();"/>

Two handlers have been added here. The oncommand handler was added to the Close menu item. By using this handler, the user will be able to close the window by clicking the menu item or by selecting it with the keyboard. The oncommand handler was added to the Cancel button.

Similarly, we can respond to other mouse events and keyboard presses using the mouse and key event handlers. If you do not specify an event handler for a particular event, the element will handle it itself. This is usually what you want to have happen. Most XUL elements will have their own responses to mouse and keyboard events. For example, menuitems will respond to their access keys and popups will appear at the right time.

Event Model

XUL uses the same event model that is described in DOM2 Events. Briefly, an event is sent in two phases. In the capturing phase, an event such as a mouse click is first sent to the document and then it works its way down the hierarchy of element until its reaches the element that triggered the event. The bubbling phase occurs next which is the reverse. The event is sent back up the hierarchy to each element in turn.

Along the way, if the event is handled by an element, processing of the event stops. If that element does not handle the event, it continues to the next element until one does. If nothing handles the event, default processing is performed.

This means that you do not have to put the event handler on the element that you want to respond to the event. You can also put it on any parent element above the element. For example, instead of putting the event handler on the menuitem, you could put the handler on the menu element.

A handler should return true if the event has been handled or false if the event has not been handled. By returning false, you can do something but still have the default processing occur. This process is similar to how HTML events are handled.

You can get the element that the event was originally passed to by getting the target property of the event object. For example, if you add the following event handler to a window, an alert box will appear whenever you click on an element in the window. The alert will display which element was clicked on. 

<window
    onclick="alert(event.target.tagName); return false;"
    .
    .
    .
>

You can also add event handlers dynamically using the function addEventListener. 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.

(Next) Next, we'll look at using the Document Object Model with XUL elements.

Find files example so far: Source View

Previous Next
Copyright (C) 1999 - 2004 XULPlanet.com