Icon Image Module

Detailed Description

group a3d_pdf_iconimage_module

(HOOPS Publish Advanced) Module to define icon image used for interactivity.

This module describes the functions that allows to define an icon image that can be used for interactivity.

Icon images are stored into the document on a way that is accessible for interactivity. An icon image is referenced by its identifier during interactivity. Identifier must be unique in the document. An Icon image can be set as button icon, which can be set by javascript. Also, icons can be set interactively on widgets populated by data model (Button or Scrolltable).

Function Documentation

A3DStatus A3DPDFDocumentAddImageAsIcon2(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcInIconId, A3DUTF8Char **ppcOutIconId)

Function to store an image in the document in a way it can be used as an icon for interactive widgets.

Stored in that way, the image can be dynamically retrieved by the Acrobat JavaScript document function ‘getIcon’. For example, if the function is called with A3DPDFDocumentAddImageAsIcon2(pimage, “myicon”,NULL), then the following JavaScript code might be used on the document to dynamically set the icon on a button : var but = this.getField("buttonfieldtopopulate"); var icon = this.getIcon("myicon"); but.buttonSetIcon(icon);

Also, the icon can be used in widgets automatically handled with data model. For this, the icon must be stored in the document with A3DPDFDocumentAddImageAsIcon2, and the icon id must be used into data table.

Memory Management

If successful and a new icon id is generated, the ppcOutIconId pointer contains heap-allocated memory for which you are responsible. To free the memory in ppcOutIconId, call A3DPDFDocumentAddImageAsIcon2 with pImage and pDoc set to 0: 

A3DPDFDocumentAddImageAsIcon2(0, 0, 0, &ppcOutIconId);

Version
10.2

Parameters:
  • pDoc – [inout] The Document object to work with.
  • pImage – [in] The image to store as icon in the Document.
  • pcInIconId – [in] The icon identifier. If provided, this is the internal id used into PDF document to name the icon. Warning, the name should be unique into the document! If NULL is specified, a unique id is automatically generated. The unique id is returned in ppcOutIconId argument.
  • ppcOutIconId – [out] The identifier as a string. NULL is accepted if this information is not useful.
Return values:

A3D_SUCCESS –

Returns:

A3D_SUCCESS in case of success or an error code
A3DStatus deprecated_A3DPDFDocumentAddImageAsIcon(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcIconName)

Function to store an image in the document in a way it can be used as an icon for interactive widgets.

Deprecated:

This function is deprecated. Please use A3DPDFDocumentAddImageAsIcon2 instead. This will be removed in version 2026.1.0.

Stored in that way, the image can be dynamically retrieved by the Acrobat JavaScript document function ‘getIcon’. For example, if the function is called with A3DPDFDocumentAddImageAsIcon(pimage, “myicon”), then the following JavaScript code might be used on the document to dynamically set the icon on a button : var but = this.getField("buttonfieldtopopulate"); var icon = this.getIcon("myicon"); but.buttonSetIcon(icon);

Version
6.1

Parameters:
  • pDoc – [inout] The Document object to work with.
  • pcIconName – [in] The icon name that will be used to identify the image.
  • pImage – [in] The image.
Return values:

A3D_SUCCESS –

Returns:

A3D_SUCCESS in case of success or an error code