L_AnnSaveMemory

#include "l_bitmap.h"

L_LTANN_API L_INT L_AnnSaveMemory(hObject, uFormat, fSelected, phMem, puMemSize, pSaveOptions)

HANNOBJECT hObject;

/* handle to the root annotation */

L_UINT uFormat;

/* file format for saving annotation data */

L_BOOL fSelected;

/* flag that indicates which objects to save */

HGLOBAL *phMem;

/* address of the memory handle */

L_SIZE_T *puMemSize;

/* address of the variable to be updated */

pSAVEFILEOPTION pSaveOptions;

/* pointer to optional extended save options */

Saves the specified annotations to a file in memory. This function is available in the Document/Medical Toolkits.

Parameter

Description

hObject

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

uFormat

Format for saving annotation data. Possible values are:

 

Value

Meaning

 

ANNFMT_NATIVE

[0x0000] Use LEAD's own format for annotations. NOTE: This format has been replaced by ANNFMT_XML, and is no longer supported

 

ANNFMT_WMF

[0x0001] Use the Windows WMF format.

 

ANNFMT_TIFFTAG

[0x0002] Save all annotation properties, including those not supported by the Wang specification as an ANNTAG_TIFF tag.

 

ANNFMT_WANGTAG

[0x0003] Save only the annotation properties supported by the Wang specification as an ANNTAG_TIFF tag.

 

ANNFMT_ENCODED

[0x0004] Save as a binary format. NOTE: This format has been replaced by ANNFMT_XML, and is no longer supported.

 

ANNFMT_XML

[0x0005] Save as an XML text format. This is LEADs new text based format which is upward compatible. It should be used instead of ANNFMT_NATIVE.

fSelected

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

 

Value

Meaning

 

TRUE

Save all objects that have the selected property set to TRUE. For getting and setting the selected property, use the L_AnnGetSelected and L_AnnSetSelected functions.

 

FALSE

Save only the specified object.

phMem

Address of a variable to be updated with the memory handle. This function uses the handle to allocate the memory. It unlocks the memory upon completion of the save.

puMemSize

Address of a variable to be updated with the size of the file.

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 multi-page annotation file. Pass NULL to save a one page annotation file.

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

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:

image\sqrblit.gif Both forward and backward compatible.

image\sqrblit.gif It is human readable.

image\sqrblit.gif It can be easily modified using a standard text editor (i.e. notepad.exe).

image\sqrblit.gif It can be easily parsed using any standard XML parser.

image\sqrblit.gif 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:

image\sqrblit.gif To save the specified object, set hObject to that object and set fSelected to FALSE.

image\sqrblit.gif To save only selected objects in a container, set hObject to the container and set fSelected to TRUE.

image\sqrblit.gif To save all objects in a container, set hObject to the container and set fSelected to FALSE.

image\sqrblit.gif L_AnnSaveTag is an alternative to L_AnnSaveMemory and L_AnnSetTag, if you are going to save it as a TIF or WANG tag format

Both the ANNFMT_TIFFTAG and the ANNFMT_WANGTAG can be saved inside a TIFF file using L_SetTag with uTag set to ANNTAG_TIFF and uType set to TAG_BYTE.

To detect whether a TIF file has annotation information, you should call L_ReadFileTag and see if ANNTAG_TYPE is present.

If uFormat is ANNFMT_XML, phMem is updated with a memory handle to the annotation file in memory.

If uFormat is ANNFMT_TIFFTAG or ANNFMT_WANGTAG, phMem is updated with a memory handle to the tag.

If you save a memory handle to a tag in TIF or WANG format, using L_AnnSaveMemory, you must write the memory handle to the tag into a file using L_SetTag and L_SaveBitmapMemory before you can load it using the L_AnnLoadMemory function.

If this function returns SUCCESS and phMem is updated with NULL, there are no annotations objects to save.

The information in the SAVEFILEOPTION structure can be used to add new pages or replace existing pages in a multi-page annotation file of type ANNFMT_XML. Note that all the pages of an annotation multi-page 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 multi-page file:

1.

Declare a variable of type SAVEFILEOPTION.

2.

Set the uFlags field of the SAVEFILEOPTION structure to ESO_INSERTPAGE.

3.

Set the PageNumber field of the SAVEFILEOPTION structure 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 multi-page file:

1.

Declare a variable of type SAVEFILEOPTION.

2.

Set the uFlags field of the SAVEFILEOPTION structure to ESO_REPLACEPAGE.

3.

Set the PageNumber field of the SAVEFILEOPTION structure to the page to replace.

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

When adding or replacing an annotation page in an existing memory file, pass the address of a valid HGLOBAL hMem (non zero). When creating a new memory file, declare a variable of type HGLOBAL and set it to zero before passing the address to L_AnnSaveMemory.

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

Windows 2000 / XP/Vista.

See Also

Functions:

L_AnnDeletePage, L_AnnDeletePageMemory, L_AnnDeletePageOffset, L_AnnFileInfo, L_AnnFileInfoMemory, L_AnnFileInfoOffset, L_AnnSave, 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_AnnFileInfoMemory.

 L_INT AnnSaveMemoryExample(HWND       hWnd,HANNOBJECT hContainer)
{
   HANNOBJECT  TmpContainer;  /* Temporary container for the annotations */
   HGLOBAL     hTag;          /* Memory handle */
   L_SIZE_T    zMemSize;      /* Size of the data in memory */
   L_UCHAR*    pData;         /* Pointer to the data in memory */
   L_INT       nRet;
   HDC         hdc;
   RECT        rAnnBounds;
   RECT        rAnnBoundsName;

   /* Load the initial annotations  */
   nRet = L_AnnLoad(TEXT("C:\\Program Files\\LEAD Technologies\\LEADTOOLS 15\\Images\\TEST.ANN"), &TmpContainer, NULL);
   if(nRet != SUCCESS)
      return nRet;
   /* Save the annotations as a TIFF TAG in memory */
   hTag = 0;
   nRet = L_AnnSaveMemory(TmpContainer, ANNFMT_TIFFTAG, FALSE, &hTag, &zMemSize, NULL);
   if(nRet != SUCCESS)
      return nRet;

   /* Get the pointer to the memory-resident tag */
   pData = (L_UCHAR*) GlobalLock (hTag);

   /* Set the tag so when the bitmap is saved as TIFF, the tag
      is also saved */
   nRet = L_SetTag(ANNTAG_TIFF, TAG_BYTE, (L_UINT) zMemSize, pData);
   if(nRet != SUCCESS)
      return nRet;

   /* Destroy the temporary container */
   nRet = L_AnnDestroy(&TmpContainer, ANNFLAG_RECURSE);
   if(nRet != SUCCESS)
      return nRet;

   /* Load the new file from memory  */
   nRet = L_AnnLoadMemory(pData, zMemSize, &TmpContainer, NULL);
   
   if (nRet == SUCCESS)
   {
     /* Insert the annotations  into the main container, hContainer, so they will be active. */
     nRet = L_AnnInsert(hContainer, TmpContainer, TRUE);
     if(nRet != SUCCESS)
        return nRet;
     hdc = GetDC(hWnd);
     nRet = L_AnnGetBoundingRect(hContainer, &rAnnBounds, &rAnnBoundsName);
     if(nRet != SUCCESS)
        return nRet;
     nRet = L_AnnDraw(hdc, &rAnnBounds, hContainer);
     if(nRet != SUCCESS)
        return nRet;
   }
   else
      return nRet;

   /* Clean up */
   GlobalUnlock (hTag);
   GlobalFree (hTag);
   return SUCCESS;
}