L_AnnSaveOffset

#include "l_bitmap.h"

L_INT EXT_FUNCTION L_AnnSaveOffset(fd, nOffset, puSizeWritten, hObject, uFormat, fSelected, pSaveOptions)

L_INT fd;

/* Windows file handle of the file to save */

L_INT32 nOffset;

/* where to embed the saved annotation file */

L_UINT32 L_FAR * puSizeWritten;

/* address of the variable to be updated */

HANNOBJECT hObject;

/* handle to the annotation object */

L_UINT uFormat;

/* file format for saving annotation data */

L_BOOL fSelected;

/* flag that indicates which objects to save */

pSAVEFILEOPTION pSaveOptions;

/* pointer to optional extended save options */

Saves the specified annotations at a specified position in an existing file. This function is available in the Document/Medical Toolkits.

Parameter

Description

fd

The Windows file handle of the file to save.

nOffset

The offset within the specified file to embed the saved annotation file. For example, if you specify 5, then 5 bytes of other data will precede the embedded file.

puSizeWritten

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

hObject

Handle to the annotation 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 is being replaced by ANNFMT_XML.

 

ANNFMT_WMF

[0x0001] Use the Windows WMF format.

 

ANNFMT_ENCODED

[0x0004] Save as a binary format. This file size is smaller and upward compatible. It also provides better security.

 

ANNFMT_XML

[0x0005] Save as an XML text format. This is LEAD’s 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.

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 14.5, the new text based format ANNFMT_XML is being introduced. It has many advantages over ANNFMT_NATIVE and ANNFMT_ENCODED including:

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.

This function overwrites existing data at the specified location in the file. You can use this function to update an image that you loaded with the L_AnnLoadOffset function. The offset is specified in bytes. You must open the file and get a Windows file handle before calling this function.

Before calling this function, you must declare a variable of data type L_UINT32. Then, pass the address of the variable in the puSizeWritten parameter. This function will update the variable with the size of the embedded file.

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_NATIVE, ANNFMT_ENCODED or ANNFMT_XML. Note that all the pages of an annotation multi-page file must be all of type ANNFMT_NATIVE or all of type ANNFMT_ENCODED or 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.

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 95 / 98 / Me, Windows 2000 / XP.

See Also

Functions:

L_AnnDeletePage, L_AnnDeletePageMemory, L_AnnDeletePageOffset, L_AnnFileInfo, L_AnnFileInfoMemory, L_AnnFileInfoOffset, L_AnnSave, L_AnnSaveMemory, L_AnnSetOptions, L_AnnGetOptions

Topics:

Annotation Files

 

Annotation Functions: Input and Output

 

Implementing Annotations

 

New Annotation Features of Version 14.5

Example

For another example, refer to L_AnnFileInfoOffset.

void TestAnnSaveOffset(HANNOBJECT hContainer)
{
   HFILE NewFile; /* File handle */
   int nRet;

   L_UINT32 SizeWritten; /* Variable to be updated with the size written */
   /* Create a file */
   #ifdef UNICODE

NewFile = _wcreat(TEXT("E:\\LEAD Technologies, Inc\\LEADTOOLS\\images\\TOFFSET.ANN"), 0);

#else

NewFile = _lcreat("E:\\LEAD Technologies, Inc\\LEADTOOLS\\images\\TOFFSET.ANN", 0);

#endif

   /* Write header information -- 29 characters and a terminator */
   _lwrite(NewFile, "This is a 29-character string", 30);
   /* Save the file with an offset */
   nRet = L_AnnSaveOffset(NewFile, 30, &SizeWritten, hContainer, ANNFMT_NATIVE, FALSE, NULL);
   if (nRet == SUCCESS)
    MessageBox(NULL, TEXT("File saved with offset"), TEXT("Notice"), MB_OK);
   /* Close the file */
   _lclose(NewFile);
   return;
}