2010-04-16

Get Document that Triggered Event

The correct document isn't always the one in front...

Event handlers are ways to run scripts when certain key events happen in Adobe InDesign or Adobe InCopy. Most things can be caught if there is a menu version of that function. Adobe's documentation does a decent job of explaining the common events, but not what to do with the 'event' itself, and is downright poor at the rest of the event handler issues.

But below is a very simple function that you can call inside the event handlers for 'open' and for 'close' event. Imagine you had multiple documents open. Now imagine that the windows are stacked so that you can see the close button for all the windows. Now assume you have an event handler that will do something useful (like look for overset text, preflight, adjust folios, for log a version comment). Well your event handler needs to know which document you just tried to close. That is where this function comes into play.

Event handlers always reference a function. But the function is a specified only in name. You can't pass it anything. Well your event handler will always receive a single argument -- an event. And the event has a property called .target and that .target property has another property .name. And the name of the target of the event is the name of the document.


//
function docRefFromEvent (event) {
//-------------------------------------------------------------------------
//-- D O C R E F F R O M E V E N T
//-------------------------------------------------------------------------
//-- Generic: Yes for ExtendScript CS3, CS4, etc.
//-------------------------------------------------------------------------
//-- Purpose: To return the document triggering the event handler or the
//-- default of the frontmost document.
//-------------------------------------------------------------------------
//-- Arguments: event: the event which triggered some other function which
//-- in turn called this function. Likely it would be an open or a close
//-- function so that you can catch the correct document. For example,
//-- you need this for open handlers becasue if you have two documents
//-- open, documents[0] or .activeDocument will point to the first doc
//-- and not the document you just opened. Likewise with closing files,
//-- your windows could be tiled and you can close a file other than the
//-- active or the documents[0].
//-------------------------------------------------------------------------
//-- Calls: Nothing.
//-------------------------------------------------------------------------
//-- Returns: Either a reference to the front document or the document that
//-- triggered the passed event.
//-------------------------------------------------------------------------
//-- Written: 2010.04.06 by Jon S. Winters of electronic publishing support
//-- eps@electronicpublishingsupport.com
//-------------------------------------------------------------------------
//-- Created for version 3.52
if ((event != undefined) && event.hasOwnProperty ('target') && event.target.hasOwnProperty ('name')) {
var testDocRef = app.documents.itemByName (event.target.name) ;
if (testDocRef != null) {
return testDocRef ;
}
}
return app.documents[0] ;
}
//