Yesterday I promised that we would talk a bit about how to put up dialogs from PDF forms
based on user action. Here, the key is to know a little bit about the App Object,
which is one of the objects Adobe defined, on top of core JavaScript, in Acrobat 4.0. Space
doesn’t permit an exhaustive discussion of the App Object here. The important thing for now
is to note that if you want to do dialogs at runtime, you’ll need to get familiar with App
Object methods.
The alert() method takes one mandatory argument (the string that you want the user
to see) plus up to two optional arguments. There is also a response() method for
two-way communication, which we’ll get to in a minute.
To call the alert method, you do something like:
i = app.alert('Are you sure you want overnight shipping? You live in
Russia.', 2, 2);
This line of code, exactly as shown, will pop an alert showing the Are you sure…
text, with a warning icon and two response buttons, labelled Yes and No.
Sample alert window
The first numeric argument specifies the kind of icon to show. There are four
possibilities:
0 = Error icon1 = Warning icon2 = Question icon3 = Status icon
These icons differ by operating system, as you might expect. On the Macintosh, the Zero
icon is a stop sign with a hand in it; icons 1 and 2 are the same as shown above; and icon 3
is the profile view of the little cartoon-guy face, an icon that’s been around since the
Lisa (circa 1983).
The second numeric argument gives you a change to specify the types of buttons you want
in your dialog. The default (zero) is an OK button and nothing else. The values 1, 2, and 3
correspond (in turn) to OK and Cancel, Yes and No, or Yes and No and Cancel.
The Alert Return Value
You may have noticed that app.alert() returns a numeric value. This will be one of
the following:
0 = Error1 = OK2 = Cancel3 = No4 = Yes
In other words, if you specify a button group (see above), you can determine which type
of button the user pressed by examining the return value from app.alert(). Pretty handy.
Will just the popup suffice?
It’s nice to be able to pop an alert when a user seems to be entering incorrect data, has
made a nonsensical choice, etc. But sometimes, an alert isn’t really enough. Sometimes you
need to be able to ask the user a specific question, and analyze (or maybe just stash) his
answer. We’ll talk about how to do that another time.