.. highlightlang:: us

.. _option_add:

option_add
==========

.. index:: option_add

.. us.tag  option_add NOTREADYENGLISH gui New560

:ref:`option_add` adds an option to the :ref:`toolsmore-options` dialog box. 
The option data is saved in the Windows registry or an INI file.

.. image:: S:/uniplot-obj/images/ToolsMoreOptions-en.*

.. function::  bool = option_add(ssCategory, ssName, ssSection, ssKey, ssDefault, ssDataType, ssHelpText, ssType)

.. us.return

**Return Value**

*bool* is TRUE (1) if the functions was successful and otherwise FALSE (0).

.. us.params

**Parameters**

.. uparam:: ssCategory

   *ssCategory* is the category name displayed in the left list box control
   of the option dialog box. If the category does not exits it will be added to
   the list.

.. uparam:: ssName

   *ssName* is the option name displayed in the left column of the right 
   list box.

.. uparam:: ssSection

   *ssSection* is the section name used to save the data in the Windows registry 
   or INI file.
   See also :ref:`WriteProfileString` and :ref:`WriteProfileInt`.

.. uparam:: ssKey

   *ssKey* is the key name used to save the data in the Windows registry or INI 
   file. See also :ref:`WriteProfileString` and :ref:`WriteProfileInt`.

.. uparam:: ssDefault

   *ssDefault* is the default value (alwasy a string even for integer values.) 
   This value is used if the value does not exists in the Windows registry.

.. uparam:: ssDataType

   *ssDataType* is the string "string" or "int".

.. uparam:: ssHelpText

   *ssHelpText* is the Help text displayed int the text box at the bottom of the 
   dialog box.

.. uparam:: ssType

   *ssType* is the option type or a type string with a callback function name.
   *ssType* can be one the following values:

   .. list-table::
      :header-rows: 0

      * - edit
        - Edit control (no callback function)
      * - checkbox
        - Check box (no callback function)
      * - buttonedit
        - Edit control with button. If a callback function is necessary it can be added to the type value as following: "buttonedit@_opt_my_callback"
      * - buttonstatic
        - Text with button. A callback function must be specified.
      * - combo
        - Combo Listbox control. A callback function must be specified.

   Callback function parameter list:

   ::

      def callback(svInit, iControl, iRow, iCol)
      {
          // svInit: Vektor with the contents of all dialogbox controls.
          // iControl: Index of the control
          // iRow: Row index in the list control
          // iCol: Column index in the list contol
          return val;
      }

   The function returns a scalar sting.

.. us.example

**Example**

Example for a combo box callback function:

::

   def __opt_ncfiletype(svInit, iControl, iRow, iCol)
   {
       svValue = ["netCDF","netCDF (PC-Byteorder)","netCDF-up","netCDF-up (compressed)"]
       if (nargsin() == 2) {
           if (iControl == 1) {
               idx = strtod(svInit[1])+1;
               if (idx[1] >= 1 && idx[1] <= len(svValue)) {
                   return svValue[idx];
               }
               return svValue[1];
           } else if (iControl == 2) {
               return sprintf("%d", find(svInit[1] == svValue)-1);
           } else {
               return TRUE;
           }
       }
       <ssMat, svSel> = GetListBoxText(svInit[iControl], FALSE);
       smMat = ReportControl_GetMatrix(ssMat);
       return CreateListBoxText(svValue, smMat[iRow; iCol]);
   }
   ssHelp = _s("Specifies the type of the netCDF file.\n\n" + ....
               "netCDF: Standard netCDF File\n" + ....
               "netCDF (PC-Byte order): netCDF file with little-endian byte order\n" + ....
               "netCDF-up: New file format for data files (UniPlot 5.6).\n" + ....
               "netCDF-up (compressed): Same as netCDF-up, but with better compression (a bit slower)\n\n" + ....
               "Find more information in the help system: \"Overview netCDF Files\"");
   option_add(_s("Import and Data Browser"), ..
       _s("netCDF Filetype"), ..
       "Settings", "standard-netcdf-files", "1", "int", ..
       ssHelp, "combo@__opt_ncfiletype");

Example for a button callback function to select a path name:

::

   // Die Option kann wie folgt in Ihrem Skript erfragt werden:
   // ssPath = GetProfileString("Settings", "My-directory");

   def __opt_my_directory(svInit, iControl, iRow, iCol)
   {
       if (nargsin() == 2) {
          ssDir = svInit[1];
          if (iControl == 3) {
             if (ssDir == "") {
                return TRUE;
             }
             nAttrib = GetDirectoryWriteAccess(ssDir);
             if (nAttrib == -1) {
                return sprintf(_s("The directory \"%s\" does not exist."), ssDir);
             } else if (nAttrib == 0) {
                return sprintf(_s("The directory \"%s\" is write protected."), ssDir);
             }
             return TRUE;
          }
          if (ssDir == "") {
             return "";
          }
          return _MakePathComplete(ssDir);
       }

       <smMat, smSel, rmSelRow> = ReportControl_GetMatrix(svInit[iControl]);
       ssDir = GetDirectoryDialog(smMat[iRow; iCol]);
       if (ssDir == "DLG_CANCEL") {
          return svInit;
       }
       nAttrib = GetDirectoryWriteAccess(ssDir);
       if (nAttrib == -1) {
          MessageBoxError(_s("The directory \"%s\" does not exist."), ssDir);
          return FALSE;
       } else if (nAttrib == 0) {
          MessageBoxError(_s("The directory \"%s\" is write protected."), ssDir);
          return FALSE;
       }
       smMat[iRow; iCol] = ssDir;
       svInit[iControl] = ReportControl_GetInit(smMat, TRUE, rmSelRow);
       return svInit;
    }

   Option_AddCategory("My Options");

   ssHelp = "Please choose the directory.\n" + ....
               "The directory should contain Excel files";
   option_add("My Options", ..
       "My directory", ..
       "Settings", "My-directory", "", "string", ..
       ssHelp, "buttonstatic@__opt_my_directory");

.. us.comment

**Comment**

The function is written in UniScript. The source code is found in the file
:file:`script\\uniplot\\tools-options.ic`.

.. us.history

**History**

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

   * - Version
     - Description
   * - 5.6.0
     - New

.. seealso::
   :ref:`overview-application-object`,
   :ref:`toolsmore-options`,
   :ref:`GetProfileString`,
   :ref:`GetProfileInt`,
   :ref:`WriteProfileString`,
   :ref:`WriteProfileInt`

:sub:`id-783960`