L_AnnSave

Summary

Saves annotations in the specified file.

Syntax

L_LTANN_API L_INT L_AnnSave(pFile, hObject, uFormat, fSelected, pSaveOptions)

Parameters

L_TCHAR * pFile

Character string containing the name of the file to save.

HANNOBJECT hObject

Handle to the root annotation object that includes all objects to save in the file. This typically is a container object.

L_UINT uFormat

Format for saving annotation data. Possible values are:

L_BOOL fSelected

Flag that indicates which objects to save. Possible values are:

pSAVEFILEOPTION pSaveOptions

Pointer to a SAVEFILEOPTION structure that contains optional extended save options. This information is used to add annotation pages or replace annotation pages in a multipage annotation file. Pass NULL to save a one page annotation file.

Returns

Comments

In version 15.0, the text based format ANNFMT_XML is replacing ANNFMT_NATIVE and ANNFMT_ENCODED. Note that ANNFMT_NATIVE and ANNFMT_ENCODED are no longer supported as options with L_AnnSave, L_AnnSaveOffset, and L_AnnSaveMemory.

For backward compatibility, this latest version of LEADTOOLS can read the discontinued formats (ANNFMT_NATIVE and ANNFMT_ENCODED) with the following functions:

• L_AnnLoad
• L_AnnLoadOffset
• L_AnnLoadMemory
• L_AnnDeletePage
• L_AnnDeletePageOffset
• L_AnnDeletePageMemory

The ANNFMT_XML format offers many advantages over the older annotation formats:

• Both forward and backward compatible.
• It is human readable.
• It can be easily modified using a standard text editor (i.e. notepad.exe).
• It can be easily parsed using any standard XML parser.
• It can be used with any of the growing number of utilities that work with XML

Save annotations in the WMF format only for use in another application. LEADTOOLS reads annotations only in the native format.

To retain scaling and positioning information, this function always saves the root container, along with the specified object or selected objects. Use the hObject and fSelected parameters as follows:

• To save the specified object, set hObject to that object and set fSelected to FALSE.
• To save only selected objects in a container, set hObject to the container and set fSelected to TRUE.
• To save all objects in a container, set hObject to the container and set fSelected to FALSE.
• To save an annotation to a TIF file as a tag, call L_AnnSaveTag.

The information in the SAVEFILEOPTION structure can be used to add new pages or replace existing pages in a multipage annotation file of type ANNFMT_XML. Note that all the pages of an annotation multipage file must be all of type ANNFMT_XML. An annotation file cannot contain pages of different format types.

To insert new pages to an annotation multipage file:

1. Declare a variable of type SAVEFILEOPTION.
2. Set the SAVEFILEOPTION.uFlags field to ESO_INSERTPAGE.
3. Set the SAVEFILEOPTION.PageNumber field to the location for insertion. The new page will be inserted in front of the page specified in the PageNumber field.

To replace an existing page in an annotation multipage file:

1. Declare a variable of type SAVEFILEOPTION.
2. Set the SAVEFILEOPTION.uFlags field to ESO_REPLACEPAGE.
3. Set the SAVEFILEOPTION.PageNumber field to the page to replace.

To delete a page from an annotation multipage file, use L_AnnDeletePage, L_AnnDeletePageMemory, L_AnnDeletePageOffset.

Required DLLs and Libraries

• LTANN
• For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Win32, x64.

See Also

Functions

• L_AnnDeletePage
• L_AnnDeletePageMemory
• L_AnnDeletePageOffset
• L_AnnFileInfo
• L_AnnFileInfoMemory
• L_AnnSaveMemory
• L_AnnSaveOffset
• L_AnnSaveTag
• L_AnnSetOptions
• L_AnnGetOptions

Topics

• Annotation Files
• Annotation Functions: Input and Output
• Implementing Annotations
• Implementing an Automated Annotation Program
• Implementing a Non-automated Annotation Program
• Annotation Features

Example

For another example, refer to L_AnnFileInfo.
This example saves currently selected annotations in a file.

L_INT AnnSaveExample(HANNOBJECT hContainer /* Container annotation object */) 
{ 
   L_INT nRet = L_AnnSave(MAKE_IMAGE_PATH("TEST.ANN"), hContainer, ANNFMT_XML, L_FALSE, NULL); 
   if (nRet == SUCCESS) 
      _tprintf(_T("%s"), TEXT("Notice: Annotations saved.")); 
 
   return nRet; 
}