.. highlightlang:: us

.. index:: TableAddFormat

.. _tableaddformat:

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

.. us.tag  TableAddFormat table.format New400

:ref:`TableAddFormat` adds a format string and cell type to a table object. 

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

.. us.return

**Return Value**

*nFormatIndex* is the index of the added format description.
:ref:`TableSetFormatIndex` is used to set the format for the cells.

.. us.params

**Parameters**

.. uparam:: hTable

   Identifies the table object.

.. uparam:: nType

   *nType* is one of the following values:

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

      * - Value
        - Type
        - Meaning
      * - 1
        - Text
        - The cell text is printed without formatting.
      * - 2
        - Number
        - The cell text will be formatted as a number.
      * - 3
        - Date/Time
        - The cell text will be formatted to a date/time value.
      * - 4
        - Percent
        - The cell text will be formatted as a percent value. The numerical 
          value is multiplied by 100 and displayed with a percentage sign (%).

.. uparam:: ssFormat

   *ssFormat* is a scalar string with the format description. For the cell type
   **Text** this parameter is ignored. It can be any valid string, e.g "".
   For the cell type **Number** the text will be formatted as a number. The
   parameter is described in the function :ref:`printf`. Example: "%.2lf" will
   create 2 decimal places. For the cell type **Date/Time** the parameter is
   described in the function :ref:`DT_Format`. 

.. us.example

**Example**

The following example creates a document with a table object.

::

   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:`overview-table`,
   :ref:`TableCreate`

:sub:`id-1210380`