
#############################
A3DPDFDocumentAddImageAsIcon2
#############################

.. c:function:: A3DStatus A3DPDFDocumentAddImageAsIcon2(A3DPDFDocument *pDoc, const A3DPDFImage *pImage, const A3DUTF8Char *pcInIconId, A3DUTF8Char **ppcOutIconId)

   .. rst-class:: sig-pretty-signature
   
      | :c:enum:`~A3DStatus` A3DPDFDocumentAddImageAsIcon2(:c:type:`~A3DPDFDocument`\ \* **pDoc**\ , *const* :c:type:`~A3DPDFImage`\ \* **pImage**\ , *const* :c:type:`~A3DUTF8Char`\ \* **pcInIconId**\ , :c:type:`~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 :c:func:`~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);
   
   
   **Parameters**
   
   
      **pDoc**\ : The Document object to work with.
   
      **pImage**\ : The image to store as icon in the Document.
   
      **pcInIconId**\ : 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**\ : The identifier as a string. NULL is accepted if this information is not useful.
   
   
   **Returns**
   
   
      A3D_SUCCESS in case of success or an error code
   
   




