.. highlightlang:: us

.. index:: Attachments

.. _attachments:
.. _attachments-overview:

Attachments
================

Attachments are files saved in the UniPlot document similar to attachments 
in e-mails. Only IPZ files can save attachments. The files can be embedded
or linked.

Attachments can be used to display image files (png, jpg, bmp, ...)
in text objects. Script files, text, Excel or PDF documents or data files
can be added to a ipz document. The :ref:`edit-attachments` command can add
or remove attachments.

.. _att_open:

att_open
--------------

.. us.tag  att_open NOTREADYENGLISH New5900 attachments

:ref:`att_open` opens the document attachments or external attachment files.

.. function:: atts = att_open(hDoc)
              atts = att_open(ssAttachmentFilename)

.. ------------------------------------------------------------------------------

.. us.example

**Example**

::

   a = att_open("d:/test.ipz");
   att_dir(a, "*.jpg");
   att_close(a)

::

   a = att_open("d:/test.ipz");
   a.dir("*.jpg");
   a.close()
   // att_close(a)

.. index:: att_close

.. _att_close:

att_close
--------------

.. us.tag  att_close NOTREADYENGLISH New5900 attachments

:ref:`att_close` closes the attachments. Before a document is saved, the 
attachments must be closed.

If the *atts* pointer is set to 0 (*atts* = 0) or *atts* is a local variable,
:ref:`att_close` will be invoked automatically.

.. function:: bool = att_close(atts)

.. ------------------------------------------------------------------------------

.. index:: att_add_file

.. _att_add_file:

att_add_file
-----------------------

.. us.tag  att_add_file NOTREADYENGLISH New5900 attachments

:ref:`att_add_file` copies a file from the hard drive into the attachments.
If *bLink* is TRUE (1) only a link will be created. *ret* is
TRUE (1) or an error object (see :ref:`error_create`).

.. function:: ret = att_add_file(atts, ssFile, name)
              ret = att_add_file(atts, ssFile, name, bLink)

.. ------------------------------------------------------------------------------

.. index:: att_add_data

.. _att_add_data:

att_add_data
-----------------------

.. us.tag  att_add_data NOTREADYENGLISH New5900 attachments

:ref:`att_add_data`

.. function:: bool = att_add_data(atts, ssData, name)

.. ------------------------------------------------------------------------------

.. index:: att_get_data

.. _att_get_data:

att_get_data
-----------------------

.. us.tag  att_get_data NOTREADYENGLISH New5900 attachments

:ref:`att_get_data`

.. function:: ssData = att_get_data(atts, name)

.. ------------------------------------------------------------------------------

.. index:: att_get_props

.. _att_get_props:

att_get_props
-----------------------

.. us.tag  att_get_props NOTREADYENGLISH New5900 attachments

:ref:`att_get_props` returns the name/value pairs of the file by the name *name*. 

The following four values should be included in the returned object:

.. list-table::
   :header-rows: 1

   * - Name
     - Value
   * - Path
     - The complete file name with path, for example ``"C:\\Images\\Test.png"``.
   * - Link
     - ``"0"``: File is embedded. ``"1"``: File is linked.
   * - FileSize
     - Number of bytes (as a string).
   * - FileTime
     - String in the form: ``"%Y-%m-%d %H:%M:%S"``, see :ref:`DT_Format`. 
       Example: ``"2017-04-27 10:43:13,45"``.

.. function:: oProps = att_get_props(atts, name)

.. ------------------------------------------------------------------------------

.. index:: att_set_props

.. _att_set_props:

att_set_props
-----------------------

.. us.tag  att_set_props NOTREADYENGLISH New5900 attachments

:ref:`att_set_props`

.. function:: bool = att_set_props(atts, name, oProps)

.. ------------------------------------------------------------------------------

.. index:: att_dir

.. _att_dir:

att_dir
-----------------------

.. us.tag  att_dir NOTREADYENGLISH New5900 attachments

:ref:`att_dir`

.. function:: svDir = att_dir(atts)
              svDir = att_dir(atts, ssPattern)

.. ------------------------------------------------------------------------------

.. index:: att_rename

.. _att_rename:

att_rename
-----------------------

.. us.tag  att_rename NOTREADYENGLISH New5900 attachments

:ref:`att_rename` renames an attachment.

.. function:: bool = att_rename(atts, name, new_name)

.. ------------------------------------------------------------------------------

.. index:: att_move

.. _att_move:

att_move
-----------------------

.. us.tag  att_move NOTREADYENGLISH New5900 attachments

:ref:`att_move` moves an attachment into a different directory.

.. function:: bool = att_move(atts, name, path)

.. ------------------------------------------------------------------------------

.. index:: att_delete

.. _att_delete:

att_delete
-----------------------

.. us.tag  att_delete NOTREADYENGLISH New5900 attachments

:ref:`att_delete` removes an attachment.

.. function:: bool = att_delete(atts, name)

.. ------------------------------------------------------------------------------

.. index:: att_export

.. _att_export:

att_export
-----------------------

.. us.tag  att_export NOTREADYENGLISH New5900 attachments

:ref:`att_export` saves the given attachments in a specified path on the 
hard drive.

.. function:: bool = att_export(atts, svNames, ssPath [, options])

::

   options = [. flat = 1, bFailIfExists = 1, bWriteEvent = 1]

.. ------------------------------------------------------------------------------

.. index:: att_save

.. _att_save:

att_save
-----------------------

.. us.tag  att_save NOTREADYENGLISH New5900 attachments

:ref:`att_save` saves a file in an attachment file or IPZ document.

.. function:: bool = att_save(atts, svNames, ssAttachFile, bOverwrite)

.. ------------------------------------------------------------------------------

.. index:: att_load

.. _att_load:

att_load
-----------------------

.. us.tag  att_load NOTREADYENGLISH New5900 attachments

:ref:`att_load` copies an attachment from the attachment file *attsSource* 
into the open file. If *bOverwrite* is TRUE (1) (default value is FALSE (0))
attachments with identical names are overwritten. Otherwise they will be
ignored.

.. function:: bool = att_load(atts, svNames, attsSource)
              bool = att_load(atts, svNames, attsSource, bOverwrite)

.. us.example

**Example**

::

   a = att_open(hDoc);
   aSrc = att_open("d:/test.ipz");
   svNames = aSrc.dir("*.jpg");
   a.load(svNames, aSrc);
   a = aSrc = 0; // close

.. ------------------------------------------------------------------------------

.. index:: att_dialog

.. _att_dialog:

att_dialog
-----------------------

.. us.tag  att_dialog NOTREADYENGLISH New5900 attachments

:ref:`att_dialog` displays the attachment dialog box.

.. function:: bool = att_dialog(atts)
              bool = att_dialog(atts, ssPattern)

.. ------------------------------------------------------------------------------

.. us.example

**Beispiel**

::

   def test_attachments()
   {
   }

.. us.comment

**Comment**

...

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2017
     - New.

.. seealso::
   :ref:`overview-documents`

:sub:`id-686295`