L_AnnSaveOffset

Summary

Saves the specified annotations at a specified position in an existing file.

Syntax

#include "l_bitmap.h"

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

Parameters

L_HFILE fd

The Windows file handle of the file to save.

L_SSIZE_T 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.

L_SIZE_T *puSizeWritten

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

HANNOBJECT hObject

Handle to the annotation object.

L_UINT uFormat

Format for saving annotation data. Possible values are:

Value Meaning
ANNFMT_EMF [0x0006] Use the Windows EMF format.
ANNFMT_ENCODED [0x0004] Save as a binary format. NOTE: This format has been replaced by ANNFMT_XML, and is no longer supported.
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_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.

L_BOOL 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.

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

Value Meaning
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:

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

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:

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 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

Platforms

Win32, x64.

See Also

Functions

Topics

Example

This sample saves the contents of hContainer into a file pszFile at offset 30

#include <tchar.h> 
extern "C" L_INT AnnSaveOffsetExample(L_TCHAR * pszFile, HANNOBJECT hContainer) 
{ 
   L_HANDLE hFileNew       = 0; /* File handle */ 
   DWORD    dwBytesWritten = 0; 
   L_INT    nRet           = SUCCESS; 
 
   if (!pszFile) 
      return ERROR_NO_MEMORY; 
 
   L_SIZE_T SizeWritten = 0; 
 
   // Create a file 
   hFileNew = CreateFile(pszFile, GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, 0); 
 
   // Write header information -- 29 characters and a terminator 
   //_write(NewFile, "This is a 29-character string", 30); 
   WriteFile(hFileNew, "This is a 29-character string", 30, &dwBytesWritten, NULL); 
 
   // Save the file with an offset 
   nRet = L_AnnSaveOffset((L_HFILE)hFileNew, 30, &SizeWritten, hContainer, ANNFMT_XML, L_FALSE, NULL); 
   if (nRet != SUCCESS) 
      return nRet; 
 
   _tprintf(_T("%s"), TEXT("Notice: File saved with offset.")); 
 
   // Close the file 
   CloseHandle(hFileNew); 
 
   return SUCCESS; 
} 

Help Version 22.0.2023.7.11
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Raster Imaging C API Help
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.