.. highlightlang:: us

.. _oncommand:

OnCommand
=========

.. index:: OnCommand

.. us.tag  OnCommand ENGLISH Menu New300

:ref:`OnCommand` is used here as a placeholder for a function
that is called when a user clicks a button on
the user toolbar or selects the function from a menu.

.. function::  OnCommand()

.. us.return

**Return Value**

:ref:`OnCommand` does not return a value.

.. us.comment

**Comment**

Creating a new command
......................

This is an example for creating a new command:

We would like to to add a command that can be used
to rename a text object. All objects in UniPlot have names. The command
should be inserted into the text object menu that is displayed
if the user right clicks a text object.

Here is the function that will be used to rename a text object:

::

   def ObjRenameDlg(handle)
   {
       ssName = ObjGetName(handle);

       svRet = DialogBox("Name:  |                           |", ssName, "Rename");
       if (svRet[1] == "DLG_CANCEL") {
           return FALSE;
       }
       return ObjSetName(handle, svRet[1]);
   }

The first parameter of **ObjRenameDlg** is the handle of
the object. The function is using the handle to retrieve the
object name (:ref:`ObjGetName`). The name is displayed in
a dialog box and can be edited (:ref:`DialogBox`).
If the user clicks on the OK button the new name
is assigned to the text object, using the :ref:`ObjSetName` function.

The next function is the :ref:`OnCommand` function.
We choose the name **OnRename**. The function retrieves the
object handle of all selected drawing objects of the active page.

::

   def OnRename()
   {
       handle = GetSelectedObjects();
       ObjRenameDlg(handle[1]);
   }

The :ref:`MenuInsertCommands` function inserts the new function
**OnRename** into the text object menu.

::

   MenuInsertCommands("OBJ_TB", "OnRename", -1);

The :ref:`MnSetCommand` function specifies the text that will be displayed for the command
**OnRename**.

::

   MnSetCommand(("OnRename", "Rename");

::

   def OnOleRenameUI()
   {
       handle = GetSelectedObjects();
       if (len(handle) > 1) {
           return "@g";
       }
       return "";
   }

.. seealso::
   :ref:`overview-menus`,
   :ref:`MenuInsertCommands`,
   :ref:`MnSetCommand`,
   :ref:`OnCommandUI`

:sub:`id-1145178`