XFA and AcroForm Event Object Access
XFA forms are event-driven. Pretty much every action triggers an event and in that event (e.g. Initialize, Change, Click, etc.), you always have access to an xfa.event object (see the “eventPseudoModel” topic on page 63 of the Designer 8.2 Scripting Reference) and, depending on whether your form is running in Acrobat/Reader, you will also have access to an AcroForm event object.
I have discovered that in that event isn’t quite accurate. It should rather be stated as within the context of that event. That’s because any function calls that you make from the event handler (for instance, into a script object that contains other functions — maybe your event handler simply passes execution to a re-usable event handler function that you have defined in this script object) will have access to these very useful objects.
In essence, xfa.event and event (if defined) are, for lack of a better term, contextual objects that exist — and are valid — as long as you are within the context (where context is different from usual definition of scope) of an event handler.
I had a case, just recently, where I needed to access the event.target property (that is, the AcroForm Doc object provided by Acrobat when it’s the host) in a function located inside a script object which I was calling from a subform’s Initialize event. At first, I thought I needed to pass it in as a parameter:
// Subform Initialize Event handler code
utils.InitSubform(this, xfa.host.name == "Acrobat" ? event : null);
-----
utils Script Object
-----
function InitSubform(sf, hostEvent)
{
...
if (hostEvent != null)
{
// access AcroForm Doc object from parameter
var pdfDoc = hostEvent.target;
...
}
...
}Unfortunately, this would’ve required updates to many forms since the script object was being used as a script object fragment and many forms were already using that function with only the first parameter.
Since the event object is actually available at that point in time, given that the handler is executing in the context of the subform’s Initialize event, I didn’t have to pass it in as a parameter and so I didn’t have to update a bunch of forms:
// Subform Initialize Event handler code
utils.InitSubform(this);
-----
utils Script Object
-----
function InitSubform(sf)
{
...
if (xfa.host.name == "Acrobat")
{
// access AcroForm Doc object from in-context event object
var pdfDoc = event.target
...
}
...
}Just remember that the xfa.event and event objects are only valid for the duration of the event which was triggered (so you shouldn’t hold on to them for future use) and that the event object is only available to you if the host is Acrobat/Reader (testing for xfa.host.name == “Acrobat” works for both Acrobat and Reader).
Tested with Adobe Acrobat and Reader 9.0.
Posted by Stefan Cameron on January 14th, 2009
Filed under AcroForm Objects,Events,Scripting
