XUL Tutorial: Defining Events for XBL elements

Original title: XUL tutorial-bindings-adding Events

Original Author: Neil Deakin

Original address: http://www.xulplanet.com/tutorials/xultu/xblevents.html

The following is the translation of the original text:

In this section, we'll learn how to add an event handler to the XBL element.

event handler (handlers)

As you would expect, the elements in the anonymous content support mouse clicks, keyboard pressing and inferior events. But you might want to use a special way to trigger events and handlers. If you want, you can add an event handler to an element in the anonymous content. The last example in the previous section actually demonstrates this. In that example, several buttons were added to the OnCommand event handler.

But you may want to add an event handler for all elements under the content tag. This is especially useful when triggering focus events and blur events. Define an event handler using the handler element. Each event handler corresponds to an action, and if necessary, you can define multiple event handlers. If an event does not match any of the defined handlers, it is automatically passed to the internal content in the normal steps.

The general syntax for an event handler is as follows:

<binding id="binding-name">
</binding>

All event handlers are placed under the handlers element, and each handler element corresponds to the action of a particular event, defined by the event attribute. Only the types of events that are supported by XUL and JavaScript are valid, such as click events and Focus events. Note that there is no "on" in front of the event name.

The most common use of event handlers is the need to modify the custom properties when the event is triggered. For example, when a user clicks on a custom check box, it automatically modifies its checked properties:

When the user clicks on the checkbox and releases the mouse button, the MouseUp event is triggered and the handler for the event is invoked, resulting in the reversal of the value of the checked property. Similarly, you may want to modify the value of one of the attributes when an element is activated, so you need to add an event handler so that you can respond either through the keyboard or the mouse input.

For mouse-related events, you can set the button attribute to be triggered only in certain situations. If you do not set this feature, you will trigger the event regardless of the mouse button being pressed, but only when a specific key is pressed. Set the button feature to 0 for the left mouse button, set to 1 for the right mouse button, set to 2 to represent the middle mouse button.

For keyboard-related events, there are a number of features that can be used to limit the conditions in which an event is triggered. For example, a key element can be limited to a specific key combination. We can extend the previous example so that the checked property of the check box is modified when the SPACEBAR is pressed.

You can also use the KeyCode feature to qualify those nonprinting characters. A detailed description of this is presented in this article. You can set a secondary key by using the modifiers attribute, which can be set to one of the following values:

Alt

The user must press the ALT key at the same time.

Control

The user must press the CTRL key at the same time.

Meta

The user must press the META key at the same time.

Shift

The user must press the SHIFT key at the same time.

Accel

The user must press a specific secondary key. This feature is platform-dependent and corresponds to the most commonly used auxiliary keys for the platform when defining shortcut keys. (Translator Note: Corresponds to CTRL under the Windows platform)

If this feature is set, the handler will be qualified to be triggered only when the auxiliary key is pressed. You can set up multiple auxiliary keys at the same time, using a space between the keys.

If there are many code within the event handler, you can use the following syntax instead of the action attribute:

<binding id="binding-name">
-- handler code goes here --
</binding>