advertisement
Events Working with eventListeners 78
Property
Bubbles
Cancelable
Captures
Description
If true, the event
propagates to scripting objects above the object initiating the event
.
If true, the default behavior of the event
on its target
can be canceled. To do this, use the PreventDefault method.
If true, the event
may be handled by eventListeners
registered to scripting objects above the target object of the event during the capturing phase of event propagation. This means an eventListener
on the application, for example, can respond to a document event before an eventListener is triggered.
CurrentTarget
DefaultPrevented
TimeStamp
The current scripting object processing the event
. See target
in this table.
If true, the default behavior of the event
on the current target
(see target
in this table) was prevented, thereby cancelling the action.
The current stage of the event
propagation process.
EventPhase
EventType
The type of the event
, as a string (for example,
"beforeNew"
).
PropagationStopped
If true, the event
has stopped propagating beyond the current target
(see target in this table). To stop event propagation, use the stopPropagation method.
Target
The object from which the event
originates. For example, the target
of a beforeImport
event is a document; of a beforeNew
event, the application.
The time and date the event occurred.
Working with eventListeners
When you create an eventListener
, you specify the event type (as a string) the event handler (as a
JavaScript function or file reference), and whether the eventListener can be triggered in the capturing phase of the event. The following script fragment shows how to add an eventListener
for a specific event (for the complete script, see AddEventListener).
#targetengine "session" main(); function main(){ var myEventListener = app.addEventListener("afterNew", myDisplayEventType, false);
} function myDisplayEventType(myEvent){ alert("This event is the " + myEvent.eventType + " event.");
}
To remove the eventListener
created by the above script, run the following script (from the
RemoveEventListener tutorial script): app.removeEventListener("afterNew", myDisplayEventType, false);
When an eventListener
responds an event, the event may still be processed by other eventListeners that might be monitoring the event (depending on the propagation of the event). For example, the
Events Working with eventListeners 79 afterOpen
event can be observed by eventListeners
associated with both the application and the document.
eventListeners
do not persist beyond the current InCopy session. To make an eventListener
available in every InCopy session, add the script to the startup scripts folder (for more on installing scripts, see
). When you add an eventListener script to a document, it is not saved with the document or exported to INX.
N OTE : If you are having trouble with a script that defines an eventListener , you can either run a script that removes the eventListener
or quit and restart InCopy.
eventListeners that use handler functions defined inside the script (rather than in an external file) must use
#targetengine "session"
. If the script is run using
#targetengine "main"
(the default), the function is not available when the event occurs, and the script generates an error.
An event can trigger multiple eventListeners
as it propagates through the scripting object model. The following sample script demonstrates an event triggering eventListeners
registered to different objects
(for the full script, see MultipleEventListeners):
#targetengine "session" main(); function main(){ var myApplicationEventListener = app.eventListeners.add("beforeImport", myEventInfo, false); var myDocumentEventListener = app.documents.item(0).eventListeners.add
("beforeImport", myEventInfo, false);
} function myEventInfo(myEvent){ var myString = "Current Target: " + myEvent.currentTarget.name; alert(myString);
}
When you run the preceding script and place a file, InCopy displays alerts showing, in sequence, the name of the document, then the name of the application.
The following sample script creates an eventListener
for each supported event and displays information about the event in a simple dialog box. For the complete script, see EventListenersOn.
main() function main(){ app.scriptPreferences.version = 5.0; var myEventNames = [
"beforeQuit", "afterQuit",
"beforeNew", "afterNew",
"beforeOpen", "afterOpen",
"beforeClose", "afterClose",
"beforeSave", "afterSave",
"beforeSaveAs", "afterSaveAs",
"beforeSaveACopy", "afterSaveACopy",
"beforeRevert", "afterRevert",
"beforePrint", "afterPrint",
"beforeExport", "afterExport",
"beforeImport", "afterImport"
] ; for (var myCounter = 0; myCounter < myEventNames.length; myCounter ++){ app.addEventListener(myEventNames[myCounter], myEventInfo, false);
}
} function myEventInfo(myEvent){
advertisement