.. highlightlang:: us

.. index:: TableAddFormat

.. _tableaddformat:

TableAddFormat
==============

.. us.tag  TableAddFormat table.format New400

:ref:`TableAddFormat` fügt eine Formatzeichenkette und Typ einer Tabelle zu. 
Über die Formatzeichenkette kann der Formatierung des Zelleninhalts 
festgelegt werden.

.. function::  nFormatIndex = TableAddFormat(hTable, nType, ssFormat)

.. us.return

**Returnwert**

*nFormatIndex* ist der Index der zugefügten Formatbeschreibung. Damit das 
neue Format für die gewünschten Zellen verwendet werden kann, muss
der Index über die Funktion :ref:`TableSetFormatIndex` gesetzt
werden.
.. us.params

**Parameter**

.. uparam:: hTable

   *hTable* ist die Zugriffsnummer (Handle) des mit :ref:`TableCreate` erzeugten
   Tabellen-Objekts.

.. uparam:: nType

   *nType* ist einer der folgenden Werte:

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

      * - Wert
        - Typ
        - Bedeutung
      * - 1
        - Text
        - Bei diesem Format wird der Formatstring ignoriert.
      * - 2
        - Zahl
        - Bei diesem Format kann die Anzahl der Nachkommastellen festgelegt werden.
      * - 3
        - Datum/Zeit
        - Bei diesem Format wird der Text in ein Datum umgewandelt.
      * - 4
        - Prozent
        - Der Zellentext wird als Prozentwert formatiert. Der Zahlenwer wird
          mit 100 multipliziert und mit einem Prozentzeichen (%) angezeigt.

.. uparam:: ssFormat

   *ssFormat* ist eine skalare Zeichenkette, die das Format für die Ausgabe des
   Zellenwertes festlegt.
   Beim Typ **Text** wird der Wert des Parameters ignoriert. Es kann also ein
   beliebiger Text übergeben werden.
   Beim Typ **Zahl** wird der Text der Zelle in eine Zahl umgewandelt und dann über
   den angegebenen Formatstring ausgegeben. Die Formatierungsmöglichkeiten entsprechen
   der Funktion :ref:`printf`. Um beispielsweise den Wert mit 2 Nachkommastellen
   auszugeben, kann als Formatstring der Wert "%.2lf" übergeben werden.
   Beim Typ **Datum/Zeit** kann über den Formatstring die Formatierung des Datums
   festgelegt werden. Hinweise zur Formatierung finden Sie in der Beschreibung der
   Funktion :ref:`DT_Format`. Für diesen Zelltyp muss die Zelle einen String enthalten,
   der die Tage seit dem 30.1.1899 enthält. Die Nachkommastellen enthalten den
   Bruchteil eines Tages.

.. us.example

**Beispiel**

Die folgende Beispielfunktion erzeugt ein Dokument mit einer Tabelle.

::

   def Test()
   {
       smText = strempty(3, 2);
       smText[1;1] = "Name";
       smText[2;1] = "Date";
       smText[3;1] = "Weight";
       smText[1;2] = "Schmidt";
       smText[2;2] = sprintf("%.10lf", DT_ParseDateTime("12.03.2003 12:23:59"));
       smText[3;2] = "82.09876";
       hTable = TableCreate(smText);
       iDat = TableAddFormat(hTable, 3, "%#c");
       iNum = TableAddFormat(hTable, 2, "%.1lf kg");
       idx = TableGetFormatIndex(hTable);
       idx[2;2] = iDat;
       idx[3;2] = iNum;
       TableSetFormatIndex(hTable, idx);
       // Autosize and clip text on cellborder 
       rmAttrib = zeros(3,2);
       rmAttrib = rmAttrib + (TABLE_CLIPTEXT | TABLE_AUTOSIZE_WIDTH | TABLE_AUTOSIZE_HEIGHT)
       TableSetAttrib(hTable, rmAttrib);
       hDoc = DocCreate();
       hPage = PageCreate();
       DocAddPage(hDoc, hPage);
       hLayer = PageGetAllLayers(hPage);
       LayerAddObjects(hLayer[1], hTable);
   }

.. seealso::
   :ref:`uberblick-tabellenobjekt`,
   :ref:`TableCreate`

:sub:`id-1210380`