Creating a close-all-docs menu item with Acrobat X

Learn how to create a Close-all menu item that will enable you to close all currently open documents.

By Thom Parker – August 23, 2011

 

Some software applications include an option for closing all currently open documents. This is a way of cleaning off the slate, so to speak. It is a common feature in creative applications, such as Adobe Photoshop, where the user typically works with many files at once. There are times when Acrobat is used in this way, but Acrobat does not have such an option.

Not to worry. In this tutorial, we’ll walk through the process of creating a “Close-all” menu item. Even if you don’t have an immediate need for it, you’ll find the information useful and instructive for many other types of automation activities in Acrobat.

Defining a solution

Closing all the open documents sounds simple enough, but there are some details that need to be defined. Here is a list of the desired characteristics.

• A “Close-all-docs” menu item is placed on the File menu immediately below the “Close” item.
• The menu item is disabled when there are no open documents.
• The menu item should have a keyboard accelerator (shortcut).
• When pressed, each open PDF is closed.
• If a PDF has been modified, the user is asked if they would like to save it.
• The menu item works in both Acrobat and Reader.
• The menu item works on both Windows and Macintosh platforms.
• To the user, the menu item appears as just another option.

All these requirements can be satisfied by an Acrobat automation tool written in JavaScript. The JavaScript model is cross-platform and includes a function for adding a menu item to Acrobat and one for closing a document. Both functions operate in Acrobat and Adobe Reader, and provide the options needed to satisfy the other requirements.

As with any automation tool, there are really two parts to the solution-- the user interface and the business logic. The menu item is the user interface. It will be handled separately from the code for closing the documents, which is the business end of the tool. We’ll start out with the business logic.

The close-all-docs script

The function for closing a document is doc.closeDoc(), where doc is a pointer to the current document. Figure 1 shows the entry for this function in the Acrobat JavaScript Reference.

Figure 1 – The Close Doc function works in both Acrobat and Reader.

The “Rights Bar” at the top of the entry shows that this function was introduced in Acrobat 5 and that it requires Save Rights. However, the text below indicates that Save Rights are not necessary at all. They are only used to prompt the user to save a modified PDF.

There is a single input to this function. It is a Boolean value that indicates whether the user should be prompted to save a modified file, or the file should be closed without saving. For our purposes, we need the user to be prompted. This is the default value, so our code does not need to use the parameter at all, as will be seen below.

Now that we can close a document with a script, the next step is to acquire all of the currently open documents. For that there is an application-level property named app.activeDocs. Figure 2 shows the entry for this function in the Acrobat JavaScript Reference.

Figure 2 – The open documents can only be acquired from a privileged context

This property is an array of document objects. The “S” in the third column of the Rights Bar indicates it can only be accessed from a privileged context. If you read the complete entry in the JavaScript Reference, you’ll see that this restriction is not quite as severe as the Rights Bar would indicate. But for our purposes, the business logic will need to be placed into a trusted function so that the script has privilege and gets full access to all the docs listed in the app.activeDocs property.

Now, we are ready to write the script.

var DoCloseAllDocs = app.trustedFunction(function() {
	app.beginPriv();
	var len = app.activeDocs.length;
	for(var i=len-1;i>=0;i--)
	app.activeDocs[i].closeDoc();
	app.endPriv();
});

Note that the loop is run backwards through the app.activeDocs document array. This technique is necessary because elements are being removed from the array as the loop is run. This same technique should always be used when elements are being deleted from any object that is being looped on because the removal of an element will cause the next element to be skipped if the loop is run in the forward direction.

The user interface (i.e. adding the menu item)

Menu items are added to Acrobat with the app.addMenuItem() function. Figure 3 shows the entry for this function in the Acrobat JavaScript Reference.

Figure 3 – Menu items can only be added to Acrobat from a privileged context.

Note that this function also requires privilege to operate, and that a better explanation of what privilege means is given in the note below the Rights Bar, specifically that it only works during “Application Initialization.” The phrase refers to code in a Folder Level script. These are JavaScript files that are loaded by Acrobat at startup. All of the code shown in this article will only work if it is placed in a Folder Level script file. It will not operate in a document. Of course, this makes perfect sense. The Folder Level script places the menu item at startup, so to the user, it looks and operates just like any other menu item.

Here’s the code for creating the menu item:

app.addMenuItem({
	cName:"Close All PD&Fs",
	cParent:"File",
	nPos:"Close",
	cExec:"DoCloseAllDocs()",
	cEnable:"event.rc = app.doc != null"
});

For the menu item to work as required, there are five parameters that must be provided to the function. The first one is the name of the menu item. This is the text that appears on the File menu. Notice the ampersand in front of the “F” in PDFs. The ampersand, when used in a menu item name, indicates the keyboard accelerator character for the menu item. This means if the File menu is open, then pressing the “f” key will run the menu item. Keyboard accelerators are case insensitive, so pressing either “F” or “f” will work. The ampersand is not shown on the menu. Instead, the “F” is underlined (Figure 4). You have to be careful when selecting a keyboard accelerator not to choose one that is already taken. In fact, I chose to use the word “PDFs” in the name because all the letters in “Close All” were already used by other items in the File menu.

The next parameter, cParent, is the parent menu for the new item. It is set to the main File menu. The following parameter, nPos, is the position on the “File” menu where the new entry will be located. Originally this parameter was the index number of the new item. It is much easier to place a menu item by name, so in Acrobat 6 this parameter can also specify the name of existing menu item after which the item will be positioned, which is what is done here. The new item will appear after the “Close” menu item.

The last two parameters are scripts that control the behavior of the menu item. The cExec parameter is the script the menu item will execute when selected. In this case, it is the function defined earlier for closing all documents. The cEnable parameter is a script that enables and disables the menu item. The undocumented app.doc property returns the current document object. It is null when no documents are open, so the script disables the menu item when no documents are open. Note that the result of this operation is returned to Acrobat in the event.rc property. This is a common technique used by event scripts in the AcroForm model.

Figure 4 – The new menu item looks just like any other.

One last note: As explained in the Folder Level Script article, Acrobat uses two different JavaScript folders. One is for the application and one is specific to the user. Scripts placed in the application folder are visible to all users on the system. Scripts placed in the user folder are only visible to the specific user. The user folder has one other special property. It is shared with Adobe Reader. It doesn’t matter whether the user has Acrobat Pro or Adobe Reader installed or both, when the script is installed into the user folder, the menu item will be placed on whichever application is open. Since there is normally only one real user per system (i.e. personal computer), there is no issue with the script being visible to only one user.

You can download the full script here. There are several free scripts listed on this page. Select the one titled “Close All Docs Menu Item.” Two bonus variations are provided in the script.