.. highlightlang:: us

.. index:: ObjGetUserData

.. _objgetuserdata:

ObjGetUserData
==============

.. us.tag  ObjGetUserData ENGLISH New5120

:ref:`ObjGetUserData` returns a data-object, set with :ref:`ObjSetUserData`.

.. function::  obj = ObjGetUserData(handle)
    obj = ObjGetUserData(handle, ssObjectName)

.. us.return

**Return Value**

*obj* is an object created with :ref:`obj_create`. If an
error occurs or the object does not contain an object, *obj* is 0.

.. us.params

**Parameters**

.. uparam:: handle

   *handle* identifies the object.

.. uparam:: ssObjectName

   *ssObjectName* is a name of a data object. If the name does not exist, the
   function returns the value 0.
   If the parameter is not specified, the function returns an object that
   contains all data objects.

.. us.comment

**Comment**

With ``ObjSetUserData(hObj, obj)`` a data-object can be added to an 
UniPlot-object for example a dataset, diagram or drawing object.

To ensure that the data is saved in the IPW-document you must invoke 
``ObjSaveUserData(hObj)`` every time you modify the data object.

.. us.example

**Example**

Example for using a data-object:

::

       // The following function is a user defined function that will be invoked
       // if the mouse cursor is a data point of a 2D dataset and the dataset
       // contains a data-object with the name datatooltip.
       // The function has two parameters: hData is the dataset handle and iPoint
       // is the point index 
       def MyTooltip_callback(hData, iPoint)
       {
           otip = ObjGetUserData(hData, "datatooltip");
           if (otip != 0) {
               if (otip.has_key(iPoint)) {
                   return otip[iPoint];
               }
           }
           return "";
       }

       // Create a dataset:
       h = plot([1:10], rand(1,10));
       hData = h[3];

       // Create an object and add some text for a number of points:
       o = [.];
       o[1] = "Info: P1";
       o[2] = "Info: P2";
       o[3] = "Info: P3";
       o[10] = ["Title", "Info: P10"];
       // Add the object o under the name datatooltip to the dataset
       // Specify the callback function. In this version a callback function
       // is only invoked for the object name datatooltip.
       ObjSetUserData(hData, "datatooltip", o, "MyTooltip_callback");
       // Make sure to invoke ObjSaveUserData:
       ObjSaveUserData(hData);

.. us.history

**History**

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

   * - Version
     - Description
   * - 5.12.0
     - New

.. seealso::
   :ref:`overview-objects`,
   :ref:`ObjCreate`,
   :ref:`ObjSetName`,
   :ref:`ObjSetUserData`,
   :ref:`ObjSaveUserData`

:sub:`id-279857`