This chapter is from the book
This chapter is from the book
This chapter is from the book
Handling Events
GoLive 8 implements a WC3-compliant event-handling mechanism. THis mechanism defines event objects of various types, which encapsulate information about events, and event targets, GoLive objects in which events can occur. The following GoLive objects act as event targets:
app module document box menu menuItem window control
Each of these objects inherits the addEventListener function (page 373), which allows you to register a handler for a type of event that can occur in that object. When the event occurs in that object, your handler is passed a single argument, one of the Event Object Types (page 377), which encapsulates information about the event, such as where and when it occurred.
For example, a menuSignal event can occur in a menuItem object, and you can register a handler for that event that responds to the selection of a menu item that your extension added. Your handler is passed a menuEvent object (page 382).
- Your handlers for the menuSignal (page 363) and control events such as onClick (page 364) implement much of the UI functionality.
- Register handlers with the document Object (page 138) for document events such as selection and save (page 366).
- Register handlers with the app Object (page 53) for the open and new events (page 364), which occur when the user opens or creates a new document.
- Terminating the GoLive application generates the appterm event (page 360) in the app Object (page 53). You can register a handler for this event to do any cleanup that your extension requires.
- Other events allow more specialized responses, such as defining the appearance of a custom control when it needs to be redrawn.
For a complete list of events and the circumstances that generate them, see Chapter 6, “Events and Event Handlers.”
Defining and Registering Event Handlers
You must register a handler for a specific event in each event target object that should respond to that event. For example, if your extension defines two menu items, you could register a handler to respond to the menuSignal (page 363) in each of the menuItem Objects (page 225). Use the event target object’s addEventListener function (page 373) to register for a specific event in that object.
An event handler takes a single argument, the event object. You can define an event handler as a separate named function, or you can define it inline during registration. Inline code can be a locally defined function that takes the event-object argument, or a simple statement.
For example, supposing that your extension adds a menu item with the name doThisItem to the Hello menu, you can register an event handler for the item in any of the following ways:
- To define the handler as a separate function:
//define the handler function function doThisHandler (menuEvt) { Window.alert ("You chose" + menuEvt.name); } //register the handler for a target function initializeModule() { menubar['Hello'].items['doThisItem'].addEventListener( 'menuSignal', doThisHandler) } - To define the handler inline during registration:
// register a locally-defined function function initializeModule() { menubar['Hello'].items['doThisItem'].addEventListener( 'menuSignal', function (e) {'Window.alert ("You chose" + e.name);'}) } —or— // register inline source code function initializeModule() { menubar['Hello'].items['doThisItem'].addEventListener( 'menuSignal', 'Window.alert ("You chose the Do This menu item")') }
It is possible to register an event handler at any time. You can, for convenience, use your extension’s initialization function to register your handlers:
// Register event handler
function initializeModule() {
menubar['Hello'].items['doThisItem'].addEventListener(
'menuEvent',
doThisHandler)
}
It is not necessary to unregister handlers on termination; the shutdown process does so automatically. To unregister a handler before termination, use the target object’s removeEventListener function (page 373).
Nesting Event Handlers
When an event is generated for a child object in a hierarchy (such as a control in a tab panel in a window), GoLive goes through an event capture phase before executing the handler registered with the event trigger object, and then goes through a “bubbling” phase after executing that handler.
During the capture phase, GoLive looks for handlers for the event that are registered with ancestor objects of the target. It starts at the topmost level and runs the first handler it finds. It then runs any handler that is registered with the target object itself. After executing the target’s handler, it bubbles back out through the ancestor objects, running the first registered handler that it finds on the way out.
For example, suppose a dialog window contains a panel that contains a button. A script registers an event handler function for the mouseEvent at the window object, another handler at the panel object, and a third handler at the button object (the actual target). In this case, when the user clicks the button, the handler for the topmost parent (the window object) is called first, during the capture phase, then the target button object’s local handler. Finally, during the bubbling phase, GoLive calls the handler registered with the immediate parent, the panel object.
This allows you to execute multiple handlers for the same event occurrence, or to handle events at a higher level. For example, you could register a mouseEvent handler with a parent window object, instead of or in addition to handlers registered with the individual controls in the window.
If you define multiple handlers for the same event in nested objects, or use the same handler at different levels:
- Check the eventPhase property of the event object to see whether the handler has been invoked in the capture, at-target, or bubbling phase.
- Check the currentTarget property of the event object for the object where the currently executing handler was registered. In the capture and bubbling phase, this is an ancestor of the target object.