• Programming Tool
• A-Z
• Pages
• Simulator
• Tables
• Scripts
• 

Table (display element)

(only available for devices with a 32-bit CPU, like MKT-View III / IV)

Contents

1. Display element type 'Table'
   1. Introduction
2. Properties of a table (and components of the script data type 'tTable')
3. Numbering of rows and columns in a table
4. Data sources (defining 'what to display' in a table)
   1. Array as a data source
   2. User-defined script function as a data source
   3. Forced update (redraw) of a table (after modifications in the data source)
   4. Text alignment within a cell (left aligned, centered, or right aligned)
   5. Displaying special characters, e.g. checkmarks and checkboxes
5. Events (generated by the 'table' element, handled in your script)
   1. OnTableClick( tTable ptr pTable, int iColumn, int iRow )
   2. OnTableScroll( tTable ptr pTable, int iNewTopColumn, int iNewTopRow )
   3. OnSelectCell( tTable ptr pTable, int iColumn, int iRow )
   4. OnGetCellText( tTable ptr pTable, int iColumn, int iRow, string ptr sText )
   5. OnGetEditText( tTable ptr pTable, int iColumn, int iRow, string ptr sText )
   6. OnSetEditText( tTable ptr pTable, int iColumn, int iRow, string ptr sText )
6. Examples using the 'Table' element
7. Syntax of a table-definition in a backslash sequence

See also:

• Manual of the UPT programming tool
• Manual for the script language (to define the contents of a table)
• Overview of other display elements supported by the 'User Programmable Terminals' (UPTs)

Display element type 'Table'

Introduction

The 'table' display element described in this document is only available in devices with a 32-bit CPU, and only in combination with the script language. These features are available, for example, in the MKT-View III and IV since February 2015.
A table can be inserted or edited (moved, resized) on a display page with the graphic page editor.

Tables may look as follows:

(Screenshot from application 'programs\script_demos\TableTest.cvt')

A table's appearance on the screen is controlled by a lot of properties which can be modified in the lower part of the tabsheet titled 'Display Line Properties' in the programming tool:

(Properties of a 'Table' in the UPT programming tool.
At the lower end of the 'Property-Liste',   not visible in this screenshot,
are the names of the optional event handlers of a particular table )

General properties like position and size of the table (in a UPT display page), colours, font, font size, etc are described in the UPT manual.
Properties like 'Access' (access rights: Read/Write or Read-Only) and the option 'operable via touchscreen' can turn the 'table' display element into a versatile, interactive controlelement, e.g. certain lines, row, or cells of the table may become selectable or even editable by the operator.

At the right and lower edge of a table, optional scroll bars may appear, for example if the space on the screen is not sufficient to show the entire content of the table. A single-column table can be used as a selection list (there is no extra control element of this type in the UPT firmware). The reaction ('what to do' when the operator selects a certain table row) is usually implemented as an 'event handler' in the script. Details about the events originating from a table are subject of a later chapter in this document.

The content of a table is not specified on the tabsheet shown above. Instead, the table's contents are generated at runtime via script. The link between the visual 'table' (on the screen) and the 'data source' (e.g. an array declared in your script) is a script variable declared as tTable. In the examples presented below, we will use the name 'MyTable' for that object. The declaration of the table (in the script) may look as follows:

var // global script variables ...
   tTable MyTable;       // control object for a 'visual' table element
   string MyData[5][3];  // an array of strings which will be displayed in a table [5 rows][3 columns]
endvar;

Properties of a table

Counting (numbering) rows and columns in a table

General rule: The numbers (indices) of data rows and data columns in a table start at zero, as in a two-dimensional array in the script language.
Thus, cells in the data area are addressed by their zero-based indices.

Because the optional "column titles" and "row numbers" are usually not read as "values" from the array or data shource, those fixed (non-scrolling) cells at the left and upper edge of the table are numbered as follows:

• With the option FixedRow = 'show user data', the non-scrolling "title"-row at the top of the table is accessable as row index zero (so it can be addressed like a 'normal' data row from the array aka 'data source');
• With the option FixedRow = 'show column titles', the non-scrolling "title"-row at the top of the table will have a 'dummy row index' of -1 (minus one) when calling an event handler like OnGetCellText.
  
  
• With the option FixedColumn = 'show user data', the fixed (non-scrolling) column at the left edge of the table is accessable as column index zero (so it can be addressed like a 'normal' data column from the array aka 'data source');
• With the option FixedColumn = 'show row numbers', the non-scrolling "numbering"-column at the left edge of the table will have a 'dummy column index' of -1 (minus one) when calling an event handler like OnGetCellText.
  

Data sources (for the display in a table)

Arrays as data source for a table

In the most simple case, a table's data source is just an array of text strings.

Example:

var
   string MyData[5][3];  // array displayed in a table [5 rows][3 columns]
endvar;

Note:

As common in most (unfortunately not all) programming languages,
we start counting array indices at zero here.
In the two-dimensional array shown above, the first index is the row (~line), followed by the column index.
Much in contrast to Borland Delphi ("TStringGrid::OnSelectCell(..ACol,ARow,.."), the sequence
      "row first, column second"
will also be used when passing those indices as 'iRow' and 'iColumn' to Event Handles, e.g.:
      func OnMyTableGetCellText( tTable ptr pTable, int iRow, int iColumn, string ptr sText )
See also: Numbering principle of rows and columns in a table's data area.

Self-defined script functions as data source for a table

For large tables, it's not economical to keep the values (display strings) for all cells as a multi-dimensional array up-to-date in memory (all the time). For example, if the visible table area only contains a dozen lines, but hundreds of other lines are scrolled 'out of view', it's advisable to use a self-defined function (in the script) as the table's data source.
This function (in geek speak: the table's OnGetCellText-handler) will only be called to retrieve the text for all visible lines, when the table needs to be redrawn.
With a function as data source, a table can also be used as a 'checklist'.

Forced redrawing of a table

After script-controlled modifications in the data source, or similar events which may affect the appearance of anything shown in the table (e.g. checkmarks), it may be necessary to redraw the table. Especially if a self defined function acts as a data source, that function will not be periodically be called by the system (firmware) just to find out if 'anything has changed'.
Instead, the script can initiate re-painting of the table 'as soon as possible' by setting the flag tTable.RedrawFlags.

Aligning text within a cell

\al (align left)

First character at the left edge of the cell.
This is the default for normal (scrollable) cells.

\ar (align right)

Last character at the right edge of the cell.

\ac (align center)

Text aligned in the center of the cell.
This is the default for all 'fixed' (non-scrolling) cells, e.g. column titles and line numbers.

Displaying special characters, like checkmarks and checkboxes

\cm (checkmark, ✓ )

Draws a checkmark without a box.
Equivalent to the Unicode character 'CHECK MARK' (U+2713)

\CM (checkmark, ✔ )

Draws a 'heavy' (bold) checkmark, without a box.
Equivalent to the Unicode character 'HEAVY CHECK MARK' (U+2714)

\cb (checked box, ☑ )

Draws a 'checkmark in a box'.
Equivalent to the Unicode character 'BALLOT BOX WITH CHECK' (U+2611)

\ce (checkbox, empty ☐ )

Draws an 'empty checkbox' (box without checkmark, like "\be", U+2610).

\be (box, empty; ☐)

Draws an 'empty checkbox' (box without a checkmark).
Equivalent to the Unicode character 'BALLOT BOX' (U+2610)

\bc (box, checked; ☑)

Draws a checkmark in a box, like "\cb".
Equivalent to the Unicode character 'BALLOT BOX WITH CHECK' (U+2611)

\bx (box with X, ☒)

Draws a box with an 'X' (cross) inside.
Equivalent to the Unicode character 'BALLOT BOX WITH X' (U+2612)

Example: Table used as a script-controlled 'checklist'

Note

Other backslash sequences which you possibly know from other (non-tabular) display elements,
like 'printing' characters via \chr( <char-code> ), do not work in the text drawn in a table cell.
See also: Check Buttons (single checkable buttons).

Events (originating from user actions in a table, processable via script)

(Selection of event handlers at the end of a table's property list in the programming tool)

OnTableClick( tTable ptr pTable, int iRow, int iColumn )

var
   int Checked[200];  // array with our own 'checked'/'unchecked' flags shown in the table
endvar;

       ...

func OnTable1Click( tTable ptr pTable, int iRow, int iColumn )
  if( iColumn==0 ) and (iRow>=0) then        // data column with a checkbox ?
     Checked[ iRow ] := not Checked[ iRow ]; // invert checkmark state
     pTable.RedrawFlags := cRedrawAll;       // update the table's display a.s.a.p.
     return TRUE; // TRUE -> "have processed the event HERE" (don't call the default handler)
  endif;
  return FALSE;   // FALSE -> "let the system process this event"
endfunc; // OnTable1Click()

OnTableScroll( tTable ptr pTable, int iNewTopRow, int iNewTopColumn )

Will be invoked when the operator (user) moves any of the table's scrollbars.
The "cell coordinate" (iNewTopRow, iNewTopColumn) passed as a function argument applies to the first visible data cell, appearing near the table's upper left corner.

OnSelectCell( tTable ptr pTable, int iRow, int iColumn )

This handler will be called when the operator selects a new cell, either by turning the rotary encoder knob, or by touching a new (different) cell in the table's data area, i.e. whenever the selection changes.
Note: Just scrolling the table doesn't modify the current selection
    - the selected cell may even be scrolled 'out of view' by the operator !
When selecting a different cell by turning the encoder knob, or (on devices with a real keyboard) via cursor keys, then the table will automatically be 'scrolled into view' to make the new selection visible.
Thus, there is usually no need for a self programmed 'OnSelectCell'-handler in your script.
A typical use for an 'OnSelectCell'-handler could be to show additional information about the currently selected cell 'somewhere else' (outside the table).

See also: OnTableClick .

OnGetCellText( tTable ptr pTable, int iRow, int iColumn, string ptr sText )

With this event handler, a script can 'override' the text shown in any cell of the table, regardless of what is currently in the data source. When implemented, the OnGetCellText-handler will be invoked many times (for each visible cell) when re-painting the table on the display. If the handler returns FALSE, the system considers the event was not handled, and shows the normal value (string, integer or whatever) from the data source or array associated with the table. If the handler returns TRUE, the table will show the string passed back from the handler in the 4th function argument (sText).

Example (from programs/script_demos/TableTest.cvt):

func OnMyTableGetCellText( tTable ptr pTable, int iRow, int iColumn, string ptr sText )
  if( iColumn==0 ) then // first data column ?
    select iRow
      case 0:  sText := "Zero";   return TRUE;
      case 1:  sText := "One";    return TRUE;
      case 2:  sText := "Two";    return TRUE;
      case 3:  sText := "Three";  return TRUE;
    endselect; // iRow
  endif; // iColumn==0 ?
  return FALSE;  // FALSE -> "let the system provide the cell text"
                 // (usually by reading it from the associated ARRAY)
endfunc; // OnMyTableGetCellText()

func OnMyTableGetCellText( tTable ptr pTable, int iRow, int iColumn, string ptr sText )
  // ...
  // Simple test for "individually coloured cells" (since 2016-07-26) :
  if( iColumn==iRow ) then
     pTable.CurrFgColor := clBlue;   // override the 'current' foreground colour when painting this cell
     pTable.CurrBgColor := clYellow; // override the 'current' background colour when painting this cell
     pTable.CurrBgGradient:= clRed;  // 2nd background colour for a colour gradient when painting this cell
  endif;
  // ...
endfunc; // OnMyTableGetCellText()

  if((iColumn==0 ) or (iColumn>=4)) and (iRow>=0) then // here: a colum with interactive checkmarks
    if( Checked[iRow] bit_and (1<<iColumn) ) then   // array with our own checked/unchecked flags
       sText := "\cb" + MyData[iRow][iColumn];  // "\cb" = checked box
    else 
       sText := "\ce" + MyData[iRow][iColumn];  // "\ce" = checkbox, empty
    endif;
    return TRUE;   // use sText, not the normal cell text from the data source
  endif;

Resulting display (example)
after 'checking' a few items

  MyTable.RedrawFlags := cRedrawAll; // table data have been modified, update the table's display a.s.a.p.

OnGetEditText( tTable ptr pTable, int iRow, int iColumn, string ptr sText )

Planned (for future releases) :
OnGetEditText() will be called shortly before a cell is switched into Edit mode.
With this handler, the script has the chance to update the 'default value', different from the value currently stored in the table's data source.

OnSetEditText( tTable ptr pTable, int iRow, int iColumn, string ptr sText )

Planned (for future releases) :
OnSetEditText() will be called when the edited value (edited in a cell of the table) shall be written back into the data source (which, after editing, becomes a 'data sink', i.e. destination).
If and how the edited value will be 'written back' is entirely under control of your script.

Examples using the 'Table' display element

The installer contains a few examples using the 'table' element (subdirectory programs/script_demos):

TableTest.cvt

A simple example, used for most screenshots in this document.
Contains event handlers for OnSelectCell, OnTableClick, and OnGetCellText to show normal text and interactive checkboxes in a table.

ReadDir.cvt

This example reads the memory card's root directory and lists it as a table.

AppSel_1.cvt

The 'App-Selector' uses a table to show all *.cvt files found on the memory card.
The operator (user) can select one of those applications via touchscreen or rotary encoder to launch it.

Syntax of a table definition in a backslash sequence / 'display definition line'

Internally, the entire table definition (design parameters) are encoded as a backslash sequence. The display interpreter (part of the UPT device firmwar) parses this sequence from the format strings, as in any other display line definition.
If you prefer to create display pages for your application with a text editor, instead of defining them with the dialogs, panels, and property lists in the programming tool, here is the general syntax of a 'table' element: ! ! ! t.b.d. ! ! !

Syntax:

\table( <Script-Variable> [, <key> = <value>, ... ] )

The first argument (after the opening parenthesis) is the name of the script variable (type tTable). It is followed by a list of key/value pairs, most of them optional, separated with an equal sign (=) between key (name) and value.
Example:

\table(MyTable,ds=MyData,rc=200,cc=10,lw=3, ....  ,t0="Row #",t1="Sig Name", .... ,osc=OnMyTableSelectCell)

Examples:

\table( MyTable, rc=5,cc=2,t0="Parameter",t1="Unit",t2="Value")

Draws a table using script variable 'MyTable', with 5 lines (RowCount), 3 columns (ColCount), and three pre-defined column titles (t0=titel of the first column; array indices begin at zero), etc).
Since no column widths are defined, all columns will have the same witdth, approximately one third of the entire table width.

\table( MyTable, rc=5,cc=2,w0=80,w1=20)

Draws a table, again using script variable 'MyTable', ... , without predefined column titles.
The widths of the first two columns are fixed (here: 80 and 20 pixel), thus the width of the third column will be automatically determined ( ~ table width minus width of the other columns, minus width of the optional vertical scrollbar).

Note:

Don't try to place other display elements in the same definition line (besides the /table).

The total width and height of the table is not a specific property of the 'table' element, but a property which (almost) all other display elements have.
Such non-table-specific properties (position, size, font) are not encoded in the argument list after "\table", but (for example) in the upper part of the tabsheet Display Line Properties.

• Tables: Contents
• Introduction
• Properties
• Data Sources
• Text Alignment
• Events
• Examples
•