Thom Parker February 12, 2009
Was this tutorial useful to you?
Scope: Acrobat 5 and later
Skill Level: Intermediate
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]
var cRtn = app.popUpMenu("Apples","Oranges","-","Beans","Corn");
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.
var aFruits = ["Fruits","Apples","Oranges"]; var aVeggies = ["Vegetables","Beans","Corn"]; var cRtn = app.popUpMenu(aFruits, aVeggies);
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);
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);