Part 4: Working with Thumbnails
Working with Thumbnails
Introduction:
The focus of this article, from a development perspective, is to show you how to add the necessary code to your navigator to display thumbnail images of items in the PDF Portfolio you attach it to. In Acrobat 9, thumbnails can be created by Acrobat itself for PDF files (of course) and most image formats. Thumbnails for other file types such as .DOC or .PPT may be generated by the operating system so their maximum dimensions are also limited by the operating system. Thumbnails for .SWF and .FLV are not created; 32 x 32 pixel icons are used for these file types. I'll also discuss the icon property of an IAttachment in this article as well.
The two properties of an IAttachment that are bitmaps are the icon and the thumbnail. Both are read-only For all file types other than .SFW and .FLV, the icons are supplied by the operating system. Acrobat has thumbnails built in for .SWF and .FLV.
Using Thumbnails:
What is a thumbnail:
The IAttachment.thumbnail property is a bitmap representing the attachment. For document formats, it represents the first page. By default, the value is a cached image from the collection which means that you can't really depend on a fixed default size; another navigator may have resized the default before your navigator gets loaded. The requestThumbnail() function can be called to request a thumbnail with particular dimensions.
Note: The thumbnail property is available almost immediately after the navigator has been initialized but the value, even for the default, may be initially null. To make that a little easier to deal with, this property can be used as the source for data binding and then you don't even have to think about it. An MXML tag might look something like this, though that's not how I'm using it in the code sample...
<mx:Image source="{myItem.thumbnail}"/>
Sizing a thumbnail:
As I mentioned above, when you want to generate a thumbnail with a specific dimension, the requestThumbnail() function can be called with a maximum width or height of 2048 pixels. This will result in a thumbnail being dynamically generated for the IAttachment rather than a cached thumbnail being used. The new thumbnail will be delivered asynchronously. Depending on the file type, file size, the operating system, available memory, etc., the creation of the new thumbnail can take some time (milliseconds really - but it matters). If you are not using data binding to display the thumbnail in your user interface, you'll need to add an event listener "thumbnailChanged" to the IAttachment and then update the display when that event occurs. If this method is called twice in succession with the same dimensions, only one thumbnail update will follow. If this method is called twice in succession with different dimensions, and if the second call is made before the first request has been completed, then the first thumbnail may not be delivered. If this seems confusing, just remember data binding is your friend. It's like those ads on late night TV; just set it, and forget it! Bind your image object to the thumbnail property and you're good to go.
What to Expect from the requestThumbnail() function:
The table below lists what you can expect from the requestThumbnail() function in different scenarios.
| PDF files | You'll get the thumbnail at the size that you requested. |
| Secured PDF files |  If a password or other type of login is required to open the PDF, you will see a 90 x 90 pixel image like the one on the right. |
| Image files | You can request a thumbnail of an image file at any dimension but Acrobat will not return an image thumbnail that is larger in any dimension than the original image. So, if you request a thumbnail 350 x 350 pixel thumbnail of an image that is 100 x 200 pixels, you'll get back a thumbnail that is 100 x 200. |
| .SWF files | The thumbnail is the same as the icon, a 32 x 32 icon representing a SWF file. |
| .FLV files | The thumbnail is the same as the icon, a 32 x 32 icon representing an FLV file. |
| Other file types | Here's where the fun starts. Thumbnail generation for other file types is operating system dependent.For this reason, a PDF Portfolio may display thumbnails of these file types differently on different systems. OSX: If you are on a Macintosh, Preview will be the application that generates the thumbnails for Acrobat, so if you can see a preview of a file in Finder, you should be able to see it in a PDF Portfolio. Windows: If you have the file previewers set up on XP or Vista, Windows will be able to generate thumbnails for you, however, it will only generate thumbnails to a maximum dimension of 256 pixels so asking for anything larger will not give you the thumbnail you want.If the file previewers are not set up, you'll see the system icon for that file type. |
The "Working with Thubnails" example project:
In the "Working with Thubnails" example project I don't actually follow my own advice on the data binding. In this case, I want the image on the right to change based on the item in the data grid that I roll over. The showThumbnail() function is called by the data grid's itemRollOver event.
private function showThumbnail(event:ListEvent):void
{
var row:int = event.rowIndex;
var item:IAttachment = IAttachment(currentItems.getItemAt(row));
//Use the thumbnail bitmap as the source for an image object.
thumb.source = new Bitmap(item.thumbnail.bitmapData.clone());
}
The requestThumbnail() function is called within the label function of the second column, that's more as a convenience than any other reason, there are probably better places to put it. In this case, I'm asking for a maximum dimension of 350 pixels.
IAttachment(item).requestThumbnail(350, 350);
Next Steps:
This article just covers the basics of working with thumbnails.I've created navigators that allow the display of user selected images to represent file types other than PDF and images and also to supply your own images for .SWF and .FLV content. I'll discuss those in future articles and when published will update this page with links.
Files:
The Acrobat 9 ActionScript SDK
The Working with Thumbnails Project