Mozilla XUL Element and Script Reference

Contents  Quick Reference

Event Handlers

The following describes the event handlers that are valid for most XUL elements.

Event Handler Attributes:

onblur

The opposite of the focus event, the blur event is passed just as an element loses the focus.

onbroadcast

The event handler should be placed on an observer. The broadcast event is sent when the attributes of the broadcaster being listened to are changed.

onclick

This event is sent when a mouse button is pressed and released. You can determine which mouse button was clicked by retrieving the button property of the event object. This event is also sent when the user double-clicks with the mouse. The detail property specifies how many clicks occured. You can also check for triple-clicks in a similar manner. For buttons and menus, you should use oncommand instead.

onclose

This event is sent when a request has been made to close the window, for example, when the user presses the close button. If you place an event handler on the window element, you can trap the window close. If you return false from the onclose handler, the window will not close. Return true to have it close normally.

oncommand

This event handler is called when an element is activated. How it is activated varies for each element and in many cases, there are several ways to activate an element. For example, a button can be activated by clicking on it with the mouse or by pressing ENTER while it has the focus. Menus can be activated by selecting them with the mouse or by pressing a shortcut key. You should always use the oncommand event instead of onclick because it will be called in all of the needed cases.

oncommandupdate

This event occurs when a command update occurs. You would use this to update the disabled status of items.

oncontextmenu

This event is sent to an element when the user requests to open the context menu for the element. The action to do this varies by platform, but it will typically be a right click. This handler is usually used to dynamically set the commands on a menu when the user requests to display it, or you can use onpopupshowing event. Returning false from this event handler prevents the popup from appearing.

ondblclick

This event is like the click event except it is only sent when the user double clicks with the mouse. This is an alternative to checking the detail property in the click event.

ondragdrop

This event is sent when the user releases the mouse button to drop an object being dragged. The element, if it accepts the drop, should respond in some manner such inserting the dragged object into itself.

ondragenter

The dragenter event is sent when the mouse pointer first moves over an element during a drag. It is similar to the mouseover event but occurs while dragging.

ondragexit

This event is sent when the mouse pointer moves away from an element during a drag. It is also called after a drop on an element. It is similar to the mouseout event but occurs during a drag.

ondraggesture

This event is sent when the user starts dragging the element, usually by holding down the mouse button and moving the mouse.

ondragover

Related to the mousemove event, this event is sent while something is being dragged over an element. The handler should indicate whether the object being dragged can be dropped.

onfocus

The focus event is sent to an element when it receives the focus. Once an element has the focus, keyboard events are sent to it. The focus can be changed by clicking on an element or by pressing TAB to switch to the next element is sequence.

oninput

This event is sent when a user enters text in a textbox. This event is only called when the text displayed would change, thus it is not called when the user presses non-displayable keys.

onkeydown

The keydown event is sent to an element that has the focus and a key is pressed but not released.

onkeypress

The keypress event is sent to an element that has the focus and a key is pressed and released. When the user presses a key, the keydown event is first sent, followed by the keypress event and then the keyup event. In a textbox, a user normally can hold down a key to repeat a character In this case, multiple sets of key events are sent as if the user rapidly pressed the same key repeatedly.

onkeyup

The keyup event is sent to an element that has the focus and a key is released.

onload

This event is sent to the window after it has been fully loaded. You should place this event handler on the window element. This event may also be used on the image element, or an element that accepts an image attribute, and will be fired when the image has finished loading. For images, this event does not bubble up the element tree, so it will not conflict with the window's onload event.

onmousedown

This event is sent when the mouse is pressed on an element but not released.

onmousemove

This event is sent repeatedly as the mouse is moved over an element.

onmouseout

This mouseout event is sent to an element when the user moves the mouse outside the element. This event is the reverse of onmouseover.

onmouseover

This event is sent to an element when the mouse first moves over an element. You can use this event to provide feedback to the user.

onmouseup

This event is sent when the mouse is released on an element.

onoverflow

This event is sent to a box or other layout element when there is not enough space to display it at full size. This might be the result of maximum sizes on elements. For example, if a box has a maximum size of 100 pixels, and only enough space for 80 pixels is available, the overflow event will be sent to the box. If the size changes, for example, by the user resizing the window, you can use the onunderflow event handler to determine when enough space is available.

onoverflowchanged

onpopuphidden

This event is sent to a popup after it has been hidden.

onpopuphiding

This event is sent to a popup when it is about to be hidden.

onpopupshowing

This event is sent to a popup just before it is popped open. This handler is usually used to dynamically set the contents when the user requests to display it.

onpopupshown

This is event is sent to a popup after it has been opened, much like the onload event is sent to a window when it is opened.

onunderflow

This event is sent to an element when there becomes enough space to display it at full size. This applies to boxes and other layout elements.

onunload

This event is sent to a window when the window has closed. This is done after the close event. You should place this event handler on the window element.