.. highlightlang:: us

.. index:: UserBar_Add

.. _userbar_add:

UserBar_Add
===========

.. us.tag  UserBar_Add ENGLISH Toolbar New300

:ref:`UserBar_Add` adds a new command to the user toolbar. The command must be
registered with :ref:`RegisterCommand`.

.. function::  bool = UserBar_Add(ssFunctionName)

.. us.return

**Return Value**

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

.. us.params

**Parameters**

.. uparam:: ssFunctionName

   *ssFunctionName* is the name of the function which will be called if the user
   selects the correponding button on the user tool bar. This function should not
   have any  parameters. The function name is given without parentheses ``"()"``.

.. us.comment

**Comment**

The commands can be added to the user toolbar in the dialog box
:ref:`tools-customize-user-toolbar`.

.. us.example

**Example**

The following example shows how a simple function for the user
toolbar is defined and registered.

::

   RegisterCommand("2D-Dataset", "MyScaleFunc", "2D-My Scaling");
   UserBar_Add("MyScaleFunc");
   def MyScaleFunc()
   {
      hvHandle = GetActiveXYHandles(); // defined in ic_util.ic
      if (hvHandle[1] == 0) {
         return;
      }
      rmXY = XYGetData(hvHandle[4]);
      rmXY[;2] = rmXY[;2] * 1.034 + 0.123;
      XYSetData(hvHandle[4], rmXY[;1], rmXY[;2]);
   }

.. seealso::
   :ref:`tools-customize-user-toolbar`,
   :ref:`RegisterCommand`

:sub:`id-1419623`