ThumbnailXpress 6 for .NET - User Guide > How To > Render Thumbnails with Annotations |
You can easily render associated annotation data for your thumbnails by simply connecting ThumbnailXpress to an instance of NotateXpress. If an image has annotation data (such as text, lines, shapes, etc.), ThumbnailXpress will call on NotateXpress to include the annotations in the thumbnail rendering.
The first step in rendering annotations in your thumbnails is to connect your instance of ThumbnailXpress to an instance of NotateXpress. You do this by passing the NotateXpress.InstanceHandle property to the ThumbnailXpress.NotateXpressInstance property.
For example, if you had an instance of ThumbnailXpress named thumbnailXpress, and an instance of NotateXpress named notateXpress, you would do this:
C# Example |
Copy Code
|
---|---|
thumbnailXpress.NotateXpressInstance = notateXpress.InstanceHandle; |
If you don't do anything else, ThumbnailXpress will automatically render internal image annotation data that NotateXpress supports (NotateXpress, Imaging for Windows, and XFDF formats).
If, however, you need to render annotations stored in external files, you'll need to teach ThumbnailXpress how to find the data using annotation search rules.
Instead of telling ThumbnailXpress where to find annotation data for each individual image that it needs to thumbnail, ThumbnailXpress allows you to give it a list of rules that define where it should search for annotation data. This special annotation rules list is kept in the ThumbnailXpress.AnnotationSearchOrder property.
As an image is being thumbnailed, ThumbnailXpress will iterate through its rules list to find associated annotation data. The first rule that succeeds will be used as the source of annotation data for that particular image (if no rule succeeds, then ThumbnailXpress concludes that the image does not have associated annotations and renders a thumbnail without any associated annotations). The entire process repeats when ThumbnailXpress moves on to thumbnail the next image - the search for annotations starts over, and the first rule on the list that returns annotation data "wins."
By default, any new instance of ThumbnailXpress will have pre-loaded this list with three rules:
This allows you to render internal annotations by simply connecting ThumbnailXpress to NotateXpress.
But if you were to clear the rules list and set it up manually yourself, here's how you would do it:
C# Example |
Copy Code
|
---|---|
thumbnailXpress.AnnotationSearchOrder.Clear(); thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.ImagingForWindows)); thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.NotateXpress)); thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.Xfdf)); |
Or, if you know you only internally need annotation data of a particular type (let's say PDF), you could redefine the search rules to only look for this particular type of annotation data:
C# Example |
Copy Code
|
---|---|
thumbnailXpress.AnnotationSearchOrder.Clear();
thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.Xfdf));
|
Where the annotation search rules really become important is when your image annotation data is stored externally to the image file. In this case, you must provide a custom set of annotation search rules to ThumbnailXpress in order to teach it how to find your external annotation data.
Before explaining how you do this, it's important to understand that ThumbnailXpress does impose a few requirements on your annotation files:
With that in mind, you define external annotation search rules by constructing new instances of the ExternalAnnotationSearchRule class. An instance of this class must specify the external annotation type, whether the annotation file is named with a prefix or suffix, and whether the annotation file does or does not include the extension of its associated image file. The following examples illustrate how this works (consult the API documentation for details).
Imagine you have a variety of JPEG files with associated NotateXpress annotation data stored in a file of the same name except the ".jpg" extension has been replaced with ".nxp", like so:
You can "teach" ThumbnailXpress to use the Form1.nxp annotation data with the Form1.jpg file, the Form2.nxp annotation data with the Form2.jpg file, etc., by setting up the following annotation search rule:
C# Example |
Copy Code
|
---|---|
thumbnailXpress.AnnotationSearchOrder.Add( new ExternalAnnotationSearchRule( ExternalAnnotationType.NotateXpress, //the type of annotation null, //no prefix is added to the annotation filename ".nxp", //the annotation file ends with ".nxp" false)); //but the annotation file does not include the original ".jpg" extension |
With one line of code, you have "taught" ThumbnailXpress where it should look for external annotation data. As long as the .nxp files are present, they will be used to render the annotations.
In the example above, we added a rule that allowed ThumbnailXpress to use annotation data stored in external .nxp files.
Now imagine that our directory contains the following files:
In this case, we have a TIFF file with its own internal annotations, as well as a similarly-named external annotation file. The question is, which one will ThumbnailXpress use for its annotation data?
Since any new instance of ThumbnailXpress will automatically add internal annotation search rules to the search list by default, if we only add an external annotation rule to the list, then we have essentially told ThumbnailXpress: "I'd like you to look for annotations in this external file, but only if you don't find any internal annotations." So, in the example above, when ThumbnailXpress is rendering Form1.tiff, it will find its internal annotation data and use it; the external annotation data in Form1.nxp will not be used.
If what you really want is for ThumbnailXpress to ignore internal annotation data and always use external annotations, you should first clear the annotation search rules:
C# Example |
Copy Code
|
---|---|
thumbnailXpress.AnnotationSearchOrder.Clear();
thumbnailXpress.AnnotationSearchOrder.Add(new ExternalAnnotationSearchRule(...));
...
|
Imagine you have a variety of image and annotation files, like so:
And let's also imagine that you do not want internal Imaging for Windows annotations to ever be rendered.
In this case, here is one way you could set up the ThumbnailXpress annotation search rules:
C# Example |
Copy Code
|
---|---|
//First, clear the pre-defined internal annotation search rules //(because, for this example, we want to be more selective with which internal //annotation types are allowed) thumbnailXpress.AnnotationSearchOrder.Clear(); //Allow internal NXP thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.NotateXpress)); //Allow internal XFDF thumbnailXpress.AnnotationSearchOrder.Add(new InternalAnnotationSearchRule(InternalAnnotationType.Xfdf)); //.xml for NXP XML annotation files thumbnailXpress.AnnotationSearchOrder.Add( new ExternalAnnotationSearchRule( ExternalAnnotationType.NotateXpressXml, //the type of annotation null, //no prefix is added to the annotation filename ".xml", //the annotation file ends with ".nxp" true)); //the original image file extension is part of the annotation filename //"xfdf-" prefix for XFDF annotation files thumbnailXpress.AnnotationSearchOrder.Add( new ExternalAnnotationSearchRule( ExternalAnnotationType.Xfdf, //the type of annotation "xfdf-", //the annotation filename begins with an "xfdf-" prefix null, //no suffix is added to the annotation filename true)); //the original image file extension is part of the annotation filename //.annotations for NXP annotation files thumbnailXpress.AnnotationSearchOrder.Add( new ExternalAnnotationSearchRule( ExternalAnnotationType.NotateXpress, //the type of annotation null, //no prefix is added to the annotation filename ".annotations", //a ".annotations" suffix is added to the annotation filename false)); //the original image file extension is not part of the annotation filename |
This effectively amounts to saying to ThumbnailXpress:
If you only need ThumbnailXpress to render annotation data embedded in the image file itself, you simply need to connect your instance of ThumbnailXpress to an instance of NotateXpress. But if you want more control over where ThumbnailXpress should look to find associated annotation data for an image (particularly if you are using external annotation data), you'll need to "teach" ThumbnailXpress where it should search for associated annotation data by customizing the annotation search rules.