How To Articles
by Thom Parker of WindJack Solutions.
by WindJack Solutions
Icons in Acrobat:
icon objects, Icon Generic Objects
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
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.
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
PDF CanOpener will generate
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.
Button with Image on it:
Start here to use an external image file.
- In Acrobat, on any PDF document, use the "Button Tool" on
the "Advanced Editing" toolbar to create a button.
- 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.
- 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
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)
- Activate the PDF CanOpener Object Selector Tool
- Locate the XObject containing the image you want in the
PDF CanOpener Display.
- 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.
- 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.
- 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
- 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.
- Push the "Save To File..." button, which displays the
"Save Stream Data As" dialog.
- If you would like to create an alpha channel mask for this
icon select the "Use Mask" option.
- Select "OK", then enter the location and name of the new
- 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
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
- Voilà!, You
Object of your choice.
The file you just created has three basic parts.
- The Image Data: This is a huge string that starts like
- 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.
- The Icon Stream object variable and definition, named "oIconData"
Insert the text from this file at the top of the
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
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