.. highlightlang:: us

.. _option_add:

option_add
==========

.. index:: option_add

.. us.tag  option_add NOTREADYGERMAN gui New560

:ref:`option_add` fügt dem Dialog :ref:`extrasweitere-optionen` eine Option zu. Der
Wert der Option wird in der Registierdatenbank von Windows gespeichert.

.. image:: S:/uniplot-obj/images/ExtrasWeitereOptionen.*

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

.. us.return

**Returnwert**

*bool* ist TRUE (1), wenn die Funktion erfolgreich ausgeführt werden konnte und 
sonst FALSE (0).

.. us.params

**Parameter**

.. uparam:: ssCategory

   *ssCategory* ist die Zeichenkette, die in der linken Listbox des Dialogfeldes
   angezeigt wird. Falls die Kategorie nicht existiert, wird sie zugefügt.

.. uparam:: ssName

   *ssName* ist der Name der Option die in der linken Spalte des Property-Elements
   angezeigt wird.

.. uparam:: ssSection

   *ssSection* ist der Abschnittsname in der Registrierdatenbank oder der INI-Datei 
   in den der Wert der Option geschrieben wird. Siehe :ref:`WriteProfileString` und
   :ref:`WriteProfileInt`.

.. uparam:: ssKey

   *ssKey* ist der Schlüsselname in der Registrierdatenbank oder der INI-Datei 
   in den der Wert der Option geschrieben wird. Siehe :ref:`WriteProfileString` und
   :ref:`WriteProfileInt`.

.. uparam:: ssDefault

   *ssDefault* ist der Defaultwert (immer als Zeichenkette, auch bei Integerwerten).

.. uparam:: ssDataType

   *ssDataType* ist entweder "string" oder "int".

.. uparam:: ssHelpText

   *ssHelpText* ist der Hilfe-Text, der im unteren Teil des Dialogfeldes angezeigt 
   wird.

.. uparam:: ssType

   *ssType* enthält den Typ des Dialogfeldes und optional den Namen einer 
   Callback-Funktion. *ssType* kann folgende Werte annehmen:

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

      * - edit
        - Editierfeld (keine Callback-Funktion)
      * - checkbox
        - Checkbox (keine Callback-Funktion)
      * - buttonedit
        - Editierfeld mit Schaltfläche. Es ist eine Callback-Funktion
          erforderlich, der Name in der Form "buttonedit@_opt_my_callback"
          angegeben wird. Siehe Beispiel.
      * - buttonstatic
        - Textfeld mit Schaltfläche.  Callbackfunktion erforderlich.
      * - combo
        - Kombinationsfeld. Callbackfunktion erforderlich.

   Aufbau der Callback-Funktion:

   .. code-block:: us

      def callback(svInit, iControl, iRow, iCol)
      {
         return val;
      }

   Die Funktion gibt einen skalaren String zurück.

.. us.example

**Beispiel**

Beispiel für eine Combo box Option::

   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");

Beispiel für eine Schaltflächen-Option::

   // 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

**Kommentar**

Die Funktion ist in UniScript geschrieben. Den Quelltext befindet sich in der 
Datei :file:`script\\uniplot\\tools-options.ic`.

.. us.history

**History**

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

   * - Version
     - Beschreibung
   * - 5.6.0
     - Neu.

.. seealso::
   :ref:`uberblick-application-objekt`,
   :ref:`extrasweitere-optionen`,
   :ref:`GetProfileString`,
   :ref:`GetProfileInt`,
   :ref:`WriteProfileString`,
   :ref:`WriteProfileInt`

:sub:`id-783960`