.. highlightlang:: us

.. _xythresholdcreate:

XYThresholdCreate
=================

.. index:: XYThresholdCreate

.. us.tag  XYThresholdCreate ENGLISH New6002

:ref:`XYCreate` creates a new 2D dataset from a single value as a horizontal
or vertical line or from a min/max value as a horizontal or vertical range (bar).

.. function::  hData = XYThresholdCreate(ssName, rsValue, nType)
               hData = XYThresholdCreate(ssName, rvRangeValue, nType)

.. us.return

**Return Value**

If the function succeeds, the return value is the handle of the
newly created 2D dataset. If the function fails, the return value is 0.

.. us.params

**Parameters**

.. uparam:: ssName

   *ssName* is the name for the dataset.

.. uparam:: rsValue

   *rsValue* is a scalar value with x-coordinate or y-coordinate.

.. uparam:: rvRangeValue

   *rvRangeValue* is a vector with two elements to define the range.

.. uparam:: nType

   *nType* sets the type. For a vertical line the value
   is XY_THRESHOLD_XCONST and for a horizontal line the value is XY_THRESHOLD_YCONST

.. us.example

**Example**

To create a threshold line::

   * hData = XYThresholdCreate("Test", 12, XY_THRESHOLD_YCONST); // line
   * hLayer = LayerCreate();
   * hDoc = DocCreate();
   * hPage = PageCreate();
   * DocAddPage(hDoc, hPage);
   * PageAddLayer(hPage, hLayer);
   * LayerAddDataset(hLayer, hData);
   * LayerAutoScale(hLayer);
   * PageReplot(hPage);

To create a threshold range::

   rsMin = 27;
   rsMax = 34;
   hData = XYThresholdCreate("Test", [rsMin, rsMax], XY_THRESHOLD_YCONST); // range
   // ! means without an item in the legend
   //  XYSetLegendText(hData, "!" + svRet[obj.id.LegendText]);
   XYSetLegendText(hData, "NOx range");
   XYSetFillColor(hData, [127,255,0,0];  // red with 50% transparency
   LayerAddDataset(hLayer, hData);
   LayerMoveDataset(hLayer, hData, 0); // send to beginning of list (background).

To modify a threshold range::

   rvX = [rsMin, rsMin, rsMax, rsMax];
   rvY = [rsMin, rsMin, rsMax, rsMax];
   XYSetData(hData, rvX, rvY);

.. us.history

**History**

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

   * - Version
     - Description
   * - R2018.2
     - Threshold range added.

.. seealso::
   :ref:`overview-xy-datasets`,
   :ref:`DocCreate`,
   :ref:`LayerCreate`

:sub:`id-1203610`