.. highlightlang:: us

.. index:: auto_xy_LabelDataPoints

.. _auto_xy_labeldatapoints:

auto_xy_LabelDataPoints
=======================

.. us.tag  auto_xy_LabelDataPoints NOTREADYENGLISH auto_xy Changed5151 Changed5500

:ref:`auto_xy_LabelDataPoints` labels the data points of a 1D or 2D dataset with
its y value. If the dataset contains more than 50 data points, 50 labels will be
distributed evenly over the data points.

.. function::  bool = auto_xy_LabelDataPoints(hData)
    bool = auto_xy_LabelDataPoints(hData, rvOffsetCM)
    bool = auto_xy_LabelDataPoints(hData, rvOffsetCM, ssStart)
    bool = auto_xy_LabelDataPoints(hData, rvOffsetCM, ssStart, ssEnd)
    bool = auto_xy_LabelDataPoints(hData, rvOffsetCM, ssStart, ssEnd, ssFormat)
    bool = auto_xy_LabelDataPoints(hData, rvOffsetCM, ssStart, ssEnd, ssFormat, bShowHelpLine)
    bool = auto_xy_LabelDataPoints(hData, rvOffsetCM, ssStart, ssEnd, ssFormat, bShowHelpLine, bHorizontal)
    bool = auto_xy_LabelDataPoints(hData, rvOffsetCM, ssStart, ssEnd, ssFormat, bShowHelpLine, bHorizontal, bExt)

.. us.return

**Return Value**

If the function succeeds, the return value is TRUE (1); otherwise it is FALSE (0).

.. us.params

**Parameters**

.. uparam:: hData

   *hData* is the handle of a 1D or 2D dataset. If *hData* is a vector of two
   datasets, the data of the second dataset is used to label the first dataset. In
   this case both datasets must have the same number of data points. See example.

.. uparam:: rvOffsetCM

   *rvOffsetCM* is a vector with two elements:

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

      * - Value
        - Meaning
      * - rvOffsetCM[1]
        - Offset of the text in x direction in centimeters.
      * - rvOffsetCM[2]
        - Offset of the text in y direction in centimeters.

.. uparam:: ssStart

   *ssStart* is a start text e.g. ``"y="``.

.. uparam:: ssEnd

   *ssEnd* is an end text e.g. ``" Nm"``.

.. uparam:: ssFormat

   *ssFormat* is the number format. For more, see :ref:`printf`.

.. uparam:: bShowHelpLine

   If *bShowHelpLine* is TRUE (1) a line will be drawn from a data point to the
   text.

.. uparam:: bHorizontal

   If *bHorizontal* is TRUE (1) the labels are displayed horizontal. If
   *bHorizontal* is FALSE (0) the labels are displayed vertical. Default value is
   FALSE (0).

.. uparam:: bExt

   This parameter specifies if the function will access the original data
   or the filtered data.

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

      * - Value
        - Description
      * - 1
        - If filtered data is available it will access filtered data, otherwise it will access original data. Default value is 1.
      * - 0
        - Access original data.

.. us.example

**Example**

This example used the data of a second dataset to label the data points.

::

   auto_AddToUI("Examples", "Example 6: WOT 1", "RS_Example6");
   def RS_Example6()
   {
       MessageBox("In the following dialog please select the file VOLLAST.ASC");
       auto_SetFileNameDialogInit("*.asc; *.nc", GetRootDirectory() + "samples/");
       svFile = auto_GetFileNameDialog(3);
       if (svFile[1] == "DLG_CANCEL") {
           return;
       }
       NumberOfFiles = len(svFile);
       hPage = auto_LoadTemplate("example");
       for (i in 1:NumberOfFiles) {
           svFile[i] = auto_ImportData(svFile[i]);
           hData1 = auto_LoadDataset("Diagramm 1", "N", "MEFF");
           hData2 = auto_LoadDataset("Diagramm 1", "N", "EWGLST");
           auto_xy_LabelDataPoints([hData1, hData2], [0, 0.3], "p=", "kW");
           XYShow(hData2, FALSE);
       }
       auto_ScaleAxes();
       auto_ReplaceTextDialog(svFile[1]);
       auto_UpdatePage(TRUE);
   }

.. us.history

**History**

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

   * - Version
     - Description
   * - R2013
     - New parameter *bExt*.
   * - 5.15.1
     - New parameter *bHorizontal*.

.. seealso::
   :ref:`overview-automation`,
   :ref:`auto_LoadTemplate`,
   :ref:`auto_LoadDataset`

:sub:`id-689640`