by Thom Parker of WindJack Solutions.
Copyright © 2004 by WindJack Solutions
 

Icons in Acrobat:
       Acrobat JavaScript defines two types of icon objects,  Icon Generic Objects and Icon Stream Generic Objects.  An Icon Generic Object is a representation of an icon already available in the document.  All functions that get or set an icon at the document level or below will use either one of these objects or the index of a built-in Acrobat icon .  An Icon Stream Generic Object is an icon that can be defined by the user. Two functions take these objects as an argument,  the app.addToolButton() and Collab.addStateModel().  Both of these functions operate above the document level. I know of only one object that returns an Icon Stream Generic Object. This object is a newly created Annotation which contains the very poorly documented property "uiIcon". This property doesn't exist on an Annotation object acquired with the doc.getAnnot() function. To create Toolbar Buttons or Custom State images you must use an Icon Stream Generic Object.

The Icon Stream Generic Object is a simple JavaScript object with 3 properties: width, height, and a function to feed image data to Acrobat.  It's the function that poses a problem to developers.  The function must return image data in a particular format(4 byte ARGB) and encoded as a hexadecimal string. For a 20x20 icon that's 1600 bytes or 3200 hexadecimal characters.  Not something you want to type into a simple text editor.

PDF CanOpener will generate the JavaScript code for an Icon Stream Generic Object from any XObject.  Virtually every image, field, and Annotation are represented internally in a PDF document as XObjects.  You can create an icon from an image already on a document, but the easiest way to get the image you want at the correct scaling is to create a form button and import the image into this button.

Procedure:

         CREATE Button with Image on it: Start here to use an external image file.

1. In Acrobat, on any PDF document, use the "Button Tool" on the "Advanced Editing" toolbar to create a button.
2. From the properties dialog for this button select the "Options" tab. Set the layout to "Icon Only" and use the "Choose Icon..." button to load your image.
3. Set the document Zoom to 100% and Resize the button to your liking.  Don't make it too large or it will crowd out the other toolbar buttons. If the zoom is correct then button size should match the final icon size on the Acrobat Toolbar.

   LOCATE the XObject: Start Here to convert any XObject to an icon
   
   
   (Screen Shot of PDF CanOpener Display Showing Annotation XObject location in Cos Obj Tree)

4. Activate the PDF CanOpener Object Selector Tool .
5. Locate the XObject containing the image you want in the PDF CanOpener Display.
   1. If you have created a button with your image on it, click the tool twice on the button.  This action will select and expand the button's Annotation dictionary in the PDF CanOpener display.  Scroll down and find the "AP" entry in the Annotation's dictionary.  Expand this node and select the "N" entry.  This XObject is the Annotation's appearance stream, which contains the graphical description of the image displayed on the button's face.
   2. Otherwise, XObjects can be located in several different locations in the document.  But chances are that it, or a reference to it resides on the page that it's displayed on.  If it is in an Annotation you can find it by clicking twice on the Annotation with the PDF CanOpener Selector Tool and looking for the "AP" entry in the Annotation dictionary.  The XObject may also be part of the page's content, in which case it is probably located in the "Resources" entry of the page dictionary.  Finally, XObjects can be named objects.  All named objects are located in the "Names" entry of the Document Catalog (the root object of the documents object tree).  Look for the "AP" entry in "Names" dictionary.
   3. You can verify that the XObject shown in the PDF CanOpener Display is in fact the image you want by right clicking on the node and selecting "Draw Node" from the context menu.
6. Edit the selected XObject from the PDF CanOpener Display by either right clicking on it and selecting "Edit" from the context menu or by double clicking on it. Either action activates the Stream Editor.
7. Push the "Save To File..." button, which displays the "Save Stream Data As" dialog.
8. Select "JavaScript Icon for Acrobat".
9. If you would like to create an alpha channel mask for this icon select the "Use Mask" option.
10. Select "OK", then enter the location and name of the new JavaScript file
11. If you selected the "Use Mask" option the "Mask Color Selection" Dialog will popup.  Use this dialog to select colors off the image to create a mask.  Use the tool to add colors to the mask and the tool to remove previously selected colors.  If there is some variation in the colors you want to use for the mask, use the "Fuzziness" control to include these pixels. However, it is best to use images with solid colors to avoid a choppy looking mask.
12. Voilà!,  You now have the JavaScript for the Icon Stream Object of your choice.

  Results:  
     The file you just created has three basic parts.

1. The Image Data: This is a huge string that starts like this
       var strLongHexData =
       "FFC1C1C1FFC1C1C100C1C1C100C1C1C100C1C1C1...
2. The function that feeds this data to Acrobat, named "ReadIconData". This function works well but is not the most efficient and you may want to play around with it.
3. The Icon Stream object variable and definition, named "oIconData" 

   Insert the text from this file at the top of the Folder Level JavaScript file you want to use it in.  If you create more than one icon you will need to rename all the variables and functions to reduce name crashes.  Since this is all happening at the folder level, you will need to do the renaming even if the icons are used in different files.

We hope this material was helpful to you.  If you have any questions or comments for us or want more info on PDF CanOpener, please send email to info@windjack.com.