Popup menus for Acrobat

Scope: Acrobat 5 and later
Skill Level: Intermediate
Prerequisites: Know how to enter scripts into Acrobat and use the JavaScript Console.

Acrobat 5.0 introduced a new user-interface item, the popup menu. This item is perfect for giving the user a quick list of choices. It’s similar to the combo box (drop-down list) form field, but it’s not a form field and has a couple advantages over the combo box. Popup menus are created dynamically through the App Object so they don’t take up any space on the PDF, a definite plus in many situations. Another big advantage over the combo box field is the ability to create hierarchical lists of choices, making popup menus more useful for many types of applications.

Popup Menu Examples
Examples for this tip are contained in the PDF below.
Download [PDF, 39KB]

To display a popup menu, open a PDF in Acrobat then enter and run the following code in the JavaScript Console (see “The Acrobat JavaScript Console”)

var cRtn = app.popUpMenu("Apples","Oranges","-","Beans","Corn");

When this code is executed, the menu will appear over top of the current document at the current cursor location. If the JavaScript Console is obscuring the document, then it will appear over top of it, as in Figure 1. This is an important point. The menu always appears over an open PDF document. If no documents are open in Acrobat, the menu will not appear and the function will immediately return a null value.

Figure 1- Simple popup menu executed from the JavaScript Console
See larger image

The app.popUpMenu() function is a blocking function--it will not return until the user selects an item, clicks outside of the menu or presses the Esc key. If the user selects an item, the item name is returned, exactly as it’s shown on the menu. If the user exits the menu without selecting an item, it returns a null value. Always test the return value before using it, as shown in the following code.

var cRtn = app.popUpMenu("Apples","Oranges","-","Beans","Corn"); if(cRtn != null) this.getField("Myfld").value = cRtn;

A common place to put this code would be in an Action script for a button or link on a PDF. In this example, menu selection is used to set the value of a text field (also on the PDF), but it could be used to populate an entire set of fields or for any other task where a user selection is needed.

Notice there are five input arguments to the app.popUpMenu() function but only four items are displayed on the menu in Figure 1. The dash, “-“, is used as a separator. The user can’t select the separator; it is just a convenience for organizing menu items.

Another way to organize the entries is to present them in a selection tree. This is the most important and useful feature of the app.popUpMenu() function. A JavaScript array is used to create the tree structure. The first entry of the array is the parent item, and all the following array entries are the child items. For example, let’s split the entries in the previous example into 2 categories, “fruits” and “vegetables.” The code for doing this is shown below.

var aFruits = ["Fruits","Apples","Oranges"];
var aVeggies = ["Vegetables","Beans","Corn"];
var cRtn = app.popUpMenu(aFruits, aVeggies);

Figure 2 – Hierarchical (or tree) style menu

Figure 2 shows the result of this code. Now what if we want to show different types of oranges, i.e., add another level of hierarchy? The answer is to simply replace the expanded entry with another array. The modified script and its results are shown below.

var aFruits = ["Fruits","Apples",["Oranges","navel","valencia"]];
var aVeggies = ["Vegetables","Beans","Corn"];
var cRtn = app.popUpMenu(aFruits, aVeggies);

Figure 3 – Three-level menu created using nested arrays of items

In the previous examples the number of top-level menu items are determined by the number of arguments to the app.popUpMenu() function. This is fixed at the time the code is written. But what if the number of top-level items is unknown and needs to be figured out dynamically at runtime? For example, if the number of top-level items is determined by a set of check boxes. Acrobat JavaScript does not provide us with an answer for this, but Core JavaScript does.

There is a little known or understood feature in JavaScript for calling a function indirectly. This is the apply() function. One aspect of this function is that it allows us to pass function arguments as an array. This isn’t the main purpose of the apply() function, but it does allow argument lists to be built dynamically, which is what we want to do. The code below uses this technique to add another top level entry to the previous menu example, and the result is shown in Figure 4.

var aFruits = ["Fruits","Apples",["Oranges","navel","valencia"]];
var aVeggies = ["Vegetables","Beans","Corn"];
// Create an array to hold the top level menu entries
var aTopItems = [aFruits, aVeggies];
// Place Additional entry at end of the Top Level Item Array
var aBerries = ["Berries","Huckle","Goose"];
aTopItems.push(aBerries);
var cRtn = app.popUpMenu.apply(app, aTopItems);

The first argument to the apply() function is app. This is a reference to the Acrobat JavaScript App Object, which is where the popUpMenu() function is called from. Don’t change this argument. The second argument, aTopItems is our array of top level items. To the apply() function this array is the list of input arguments to be used in the calling function.

The app.popUpMenu() function provides a useful, but very basic type of hierarchical menu. It does not allow menu items to be marked or disabled. It is also limited in that it can only return the name of the menu item, rather than a unique value. Acrobat 6.0 introduced a much more sophisticated popup-menu function, app.popUpMenuEx() that addresses these shortcomings. It is more difficult to use and will be explored in a future tip. More information on both of these functions can be found in the Acrobat JavaScript Reference¹.

¹ Acrobat JavaScript Reference
http://www.adobe.com/devnet/acrobat/