• Programmiertool
• A-Z
• Anzeigeseiten
• Simulator
• Tabellen
• Scripte
• 

Tabelle (Anzeigetyp)

(nur in bestimmten programmierbaren Terminals verfügbar, z.B. MKT-View III / IV)

Inhalt

1. Anzeige-Element Typ 'Tabelle'
   1. Einleitung
2. Eigenschaften einer Tabelle (und Komponenten des Script-Datentyps 'tTable')
3. Zählung von Zeilen und Spalten in einer Tabelle
4. Datenquellen (für die Anzeige einer Tabelle)
   1. Array als Datenquelle
   2. Selbstdefinierte Funktion als Datenquelle
   3. Erzwungenes Neu-Zeichnen der Tabelle (nach Änderungen in der Datenquelle)
   4. Ausrichten des Textes innerhalb einer Zelle (linksbündig, zentriert, rechtsbündig)
   5. Anzeige von Sonderzeichen, z.B. Checkboxen und Häkchen, in einer Zelle
5. Ereignisse (von einer Tabelle ausgelöst, und per Script verarbeitbar)
   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. Beispiele zur Verwendung des Anzeige-Elements 'Tabelle'
7. Syntax einer Tabellen-Definition in einer Backslash-Sequenz

Siehe auch:

• Handbuch des Programmiertools (allgemein)
• Handbuch zur Script-Sprache (zum Definieren des Inhalts einer Tabelle)
• Übersicht der vom UPT unterstützten Anzeige-Elemente

---

Anzeige-Element Typ 'Tabelle'

Einleitung

Das hier beschriebene Anzeige-Element "Tabelle" ist nur in Displays mit Script-Sprache und 32-Bit-Prozessor (z.B. MKT-View III,IV) und Firmware ab Februar 2015 verfügbar.
Eine Tabelle kann z.B. mit dem graphischen Editor auf einer Anzeigeseite eingefügt, verschoben, oder vergrößert/verkleinert werden.

Tabellen können als scrollbare 'Datenanzeige', aber auch als Auswahlliste oder ähnliches interaktives Bedienelement dienen:

(Screenshot aus Applikation 'programs\script_demos\TableTest.cvt',
'überfrachtet' um viele Möglichkeiten der Darstellung zu demonstrieren)

Eine Tabelle wird durch verschiedene Eigenschaften charakterisiert, die im unteren Teil der Registerkarte 'Display Line Properties' definiert werden können:

(Eigenschaften einer 'Tabellen-Definition' im UPT-Programmiertool.
Am unteren Ende der 'Property-Liste',   hier nicht sichtbar,
finden Sie auch die Namen der optionalen Event-Handler )

Allgemeine Eigenschaften wie Position und Größe der Tabelle (auf der UPT-Anzeigeseite), Farben, Zeichensatz, Zeichengröße, usw sind im allgemeinen Handbuch beschrieben.
Eigenschaften wie 'Access' (Zugriffsrechte: Schreib/Lesezugriff) und die Option 'operable via touchscreen' / 'per Touch bedienbar' führen dazu, daß eine 'Tabelle' vom reinen Anzeige- zum Bedienelement wird, d.h. dass bestimmte Zellen in der Tabelle selektier- oder editierbar sind.

Am rechten und unteren Rand der Tabelle können optional Scrollbalken eingeblendet werden, z.B. wenn der Platz auf dem Bildschirm nicht für die Anzeige der gesamten Tabelle ausreicht. Eine einspaltige Tabelle eignet sich daher sehr gut als Auswahlliste. Die Reaktion (bei Auswahl einer bestimmten Tabellenzeile durch den Bediener) erfolgt dann, wie üblich, im Script. Details zur Verarbeitung von durch die Tabelle ausgelösten Ereignissen folgen in einem späteren Kapitel.

Der Inhalt einer Tabelle wird nicht auf der oben gezeigten Registerkarte 'Tabelle' definiert, sondern während der Laufzeit per Script-Sprache erzeugt. Als Bindeglied zwischen der auf dem Bildschirm angezeigten Tabelle und einer 'Datenquelle' (z.B. einem in der Script-Sprache deklarierten Array) dient eine als tTable deklarierte Variable, die im weiteren Verlauf dieser Beschreibung 'MyTable' ("Meine Tabelle") genannt wird. Die Deklaration einer Tabelle (im Script) könnte folgendermaßen aussehen:

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;

Der Text in einer Zelle der Tabelle auf verschiedene Weisen ausgerichtet werden, z.B. rechtsbündig ("\ar" = align right).
Details zur Verbindung zwischen sichtbarer Tabelle und Datenquelle folgen in einem der nächsten Kapitel.

---

Eigenschaften einer Tabelle

Die folgenden Eigenschaften einer Tabelle können beim Design einer UPT-Anzeige-Seite im Programmiertool definiert werden, oder/und per Script (als Komponente einer Script-Variablen vom Typ 'tTable') modifiziert werden:

Eigenschaft bzw Komponente	Beschreibung
tTable	Name der mit der Tabelle verbundenen Script-Variablen vom Typ 'tTable'. Dieser muss in der Definition des Anzeige-Elementes enthalten sein, um eine eindeutige Zuordnung zwischen Anzeige-Element und Script-Variable zu gewährleisten (denn in einer Applikation könnte eine Vielzahl verschiedener Tabellen enthalten sein).
DataSource	Name oder Adresse der Datenquelle. Diese kann auch per Script gesetzt werden, und ermöglicht z.B. die Umschaltung der Anzeige verschiedener 'Quellen' in einer einzelnen Tabelle zur Laufzeit.
RowCount	Anzahl Zeilen (Rows). In 'RowCount' ist auch die optionale 'Titelzeile' enthalten.
ColCount	Anzahl Spalten (Columns). In 'ColCount' ist auch die optionale Spalte mit den 'Zeilennummern' enthalten.
BorderStyle	Stil zum Zeichnen des äußeren Rahmens. Die möglichen Werte stehen auch als Konstanten in der Script-Sprache zur Verfügung:     bsPlain : die Tabelle hat keinen äußeren Rahmen     bsFramed : Tabelle mit einem einfachen Rahmen (dünne Linie)     bs3D : Rahmen im '3-D'-Stil     bsRounded : abgerundeter Rahmen, ähnlich wie bei 'Buttons' .
LineWidth	Breite der vertikalen und horizontalen Trennlinien. Gemessen in Pixel. Sinnvolle Werte liegen zwischen 1 und 3.
Scrollbars	Definiert, ob, wann, und welche Scrollbalken am rechten und unteren Rand der Tabelle sichtbar sein sollen. Im Designer stehen die folgenden Werte in einer Auswahlliste zur Verfügung:     ssNone : keine Scrollbalken anzeigen     ssHorizontal : nur einen horizontalen Scrollbalken     ssVertical : nur einen vertikalen Scrollbalken     ssBoth : beide Scrollbalken anzeigen (immer)     ssAuto : Scrollbalken nur anzeigen wenn nötig         (d.h. wenn der Platz nicht zum Anzeigen der gesamten Tabelle ausreicht)
FixedRow	Definiert, was in der ersten "festen" Zeile angezeigt werden soll:     no fixed row : nichts (keine "feste" Titelzeile)     show colum titles: Feste Überschriften (Title[0]..Title[N], s.U.)     show user data: per Script vorgegebene Überschriften Der Typ der so definierten "festen Zeile" wirkt sich auch auf die Numerierung der scrollbaren Zeilen (iRow) aus !
FixedColumn	Definiert, was in der ersten "festen" Spalte angezeigt werden soll:     no fixed column : nichts (keine "feste" Spalte)     show row numbers : Zeilennummern ( 1 .. N) anzeigen     show user data: per Script vorgegebene Texte Der Typ der so definierten "festen Spalte" wirkt sich auch auf die Numerierung der scrollbaren Spalten (iColumn) aus !
FgColor /   "Normal foreground colour"	Vordergrundfarbe für Text in 'normalen' Zellen und Trennlinien. Dies ist ein Design-Parameter, der im Gegensatz zu CurrFgColor nicht in OnGetCellText modifiziert werden darf.
BgColor /   "Normal background colour"	Hintergrundfarbe für alle 'normalen' Zellen. Dies ist ein Design-Parameter, der im Gegensatz zu CurrBgColor nicht in OnGetCellText modifiziert werden darf.
BgGradient /   "Normal background gradient"	Zweite Hintergrundfarbe für optionalen Farbverlauf in 'normalen' Zellen. Dieser Design-Parameter darf im Gegensatz zu CurrBgGradient nicht in OnGetCellText modifiziert werden.
TitleFgColor /   "Fixed cell foreground colour"	Vordergrundfarbe für Text in den nicht-scrollenden Zellen (z.B. Titelzeile und Spalte mit Zeilennummern).
TitleBgColor /   "Fixed cell background colour"	Hintergrundfarbe für die nicht-scrollenden Zellen.
TitleBgGradient /   Fixed cell bkgnd gradient	Zweite Hintergrundfarbe für einen Farbverlauf in den nicht-scrollenden Zellen.
SelectedFgColor /   "Selected cell fg colour"	Vordergrundfarbe für die momentan selektierte oder editierte Zelle.
SelectedBgColor /   "Selected cell bg colour"	Hintergrundfarbe für die momentan selektierte oder editierte Zelle.
Selected cell bknd gradient	Zweite Hintergrundfarbe für einen Farbverlauf in der/den selektierten Zelle[n].
Title[0..9]	Spaltenüberschriften (für die nicht-scrollende "Titelzeile")
ColumnWidth[0..9]	Spaltenbreiten, gemessen in Pixel. Fehlt diese Angabe (im Designer), so wird der verbleibende Platz 'gleichmäßig' verteilt, d.h. alle Spalten ohne extra definierte Breite haben die gleiche Breite.
SelRow	Nummer (Index) der momentan selektierten Tabellenzeile. Wie bei Array-Indizes üblich, beginnt die Zählung i.A. bei Null. Siehe auch: Hinweise zur Zählung von Zeilen und Spalten in einer Tabelle.
SelColumn	Nummer (Index) der momentan selektierten Tabellenspalte. Wie bei Array-Indizes üblich, beginnt die Zählung i.A. bei Null. Siehe auch: Hinweise zur Zählung von Zeilen und Spalten in einer Tabelle.
SelMode	Selektions-Modus (z.B. für die Navigation per Drehknopf, Cursortasten, Touchscreen). Mögliche Werte: smOff : Die aktuelle Selektion (SelRow, SelColum) ist nicht sichtbar, und kann nicht vom Bediener geändert werden smCell : Es wird nur eine einzelne Zelle selektiert (Drehknopf navigiert "vertikal") smRow : Es wird immer eine komplette Zeile selektiert (Drehknopf navigiert "horizontal") smColumn : Es wird immer eine komplette Spalte selektiert

Zusätzlich zu den oben aufgeführten, per Designer (Registerkarte "Seite #x", "Eigenschaften eines Anzeigeelements", "Tabelle") einstellbaren Eigenschaften kann per Script auch auf die folgenden Eigenschaften des Datentyps 'tTable' zugegriffen werden:

X	Position des linken Rands der Tabelle auf dem Bildschirm. Gemessen in Pixel. Im Designer finden Sie diesen Parameter (u.A.) im oberen Teil der Registerkarte "Eigenschaften eines Anzeigeelements".
Y	Position des oberen Rands der Tabelle auf dem Bildschirm. Gemessen in Pixel.
Width	Gesamte Breite der Tabelle, gemessen in Pixel.
Height	Gesamte Höhe der Tabelle, gemessen in Pixel.
RedrawFlags	Flags zum (erzwungenen) Neu-Zeichnen der Tabelle, z.B. wenn per Script der Inhalt der mit der Tabelle verbundenen Datenquelle modifiziert wurde. Der an 'RedrawFlags' zugewiesene Wert ist eine bitweise Kombination aus ... cRedrawCells : alle momentan sichtbaren Zellen der Tabelle neu zeichnen cRedrawSelection : nur die aktuell selektierte Zelle neu zeichnen cRedrawBackgnd : den Tabellen-Hintergrund neu zeichnen (inkl. Rahmen, Gitterlinien, Scrollbalken) cRedrawAll : alles neu zeichnen (auch alle zukünftigen Erweiterungen)
CurrFgColor	Aktuelle Vordergrundfarbe beim Zeichnen einer einzelnen Zelle. Diese Komponente von tTable kann nur im Event-Handler OnGetCellText modifiziert werden. Die Voreinstellung für tTable.CurrFgColor hängt vom Zustand der Zelle ab: Bei normalen Zellen FgColor, bei nicht-scrollenden Zellen TitleFgColor, bei selektierten Zellen SelectedFgColor.
CurrBgColor	Aktuelle erste Hintergrundfarbe beim Zeichnen einer einzelnen Zelle. Diese Komponente von tTable kann nur im Event-Handler OnGetCellText modifiziert werden. Die Voreinstellung für tTable.CurrBgColor hängt vom Zustand der Zelle ab: Bei normalen Zellen BgColor, bei nicht-scrollenden Zellen TitleBgColor, bei selektierten Zellen SelectedBgColor.
CurrBgGradient	Zweite Hintergrundfarbe beim Zeichnen eines Farbverlaufs der aktuellen Zelle. Diese Komponente von tTable kann nur im Event-Handler OnGetCellText modifiziert werden. Die Voreinstellung für tTable.CurrBgGradient hängt vom Zustand der Zelle ab: Bei normalen Zellen BgGradient, bei nicht-scrollenden Zellen TitleBgGradient, bei selektierten Zellen SelectedBgGradient.

---

Zählung von Zeilen und Spalten in einer Tabelle

Grundsätzlich gilt : Die Zählung von Datenzeilen und Datenspalten beginnt bei Null, wie bei zweidimensionalen Arrays in der Script-Sprache.
Zellen im Datenbereich werden daher über ihre Null-basierten Indizes adressiert.

Da die optionalen "Tabellenüberschriften" und "Zeilenummern" i.A. nicht als "Werte" aus dem Array bzw der Datenquelle gelesen werden sollen, gilt für die festen (nicht scrollenden) Zellen am linken und oberen Rand der Tabelle:

• Mit der Option FixedRow = 'show user data' erhält die nicht-scrollende Zeile am oberen Rand der Tabelle den Index Null (damit sie wie die 'normalen' Datenzeilen aus dem Array gelesen werden kann);
• Mit der Option FixedRow = 'show column titles' erhält die nicht-scrollende ("Titel-")Zeile am oberen Rand der Tabelle beim Aufruf von Event-Handlern wie z.B. OnGetCellText den Index iRow = -1 (minus Eins).
  
  
• Mit der Option FixedColumn = 'show user data' erhält die nicht-scrollende Spalte am linken Rand der Tabelle den Index Null (damit sie wie die 'normalen' Datenzeilen aus dem Array gelesen werden kann);
• Mit der Option FixedColumn = 'show row numbers' erhält die nicht-scrollende Spalte am linken Rand der Tabelle beim Aufruf von Event-Handlern wie z.B. OnGetCellText den Index iColumn = -1 (minus Eins).

Datenquellen (für die Anzeige einer Tabelle)

Arrays als Datenquelle für Tabellen

Im einfachsten Fall dient ein ein- oder zweidimensionales String-Array als Datenquelle.
Beispiel:

var
   string MyData[5][3];  // Daten, die als Tabelle mit 5 Zeilen und 3 Spalten angezeigt werden
endvar;

In der Definition eines UPT-Anzeigeelementes vom Typ 'Tabelle' würde die Variable 'MyData' dann als Eigenschaft 'DataSource' definiert (siehe Screenshot in der Einleitung).

Mit dem obigen Beispiel wird ein zweidimensionales Array namens 'MyData' deklariert.
Dieses hätte bei der Anzeige als Tabelle mit 5 Zeilen (rows), und 3 Spalten (columns) pro Zeile folgenden Aufbau:

	iColumn = 0	iColumn = 1	iColumn = 2
iRow = 0	MyData[0][0]	MyData[0][1]	MyData[0][2]
iRow = 1	MyData[1][0]	MyData[1][1]	MyData[1][2]
iRow = 2	MyData[2][0]	MyData[2][1]	MyData[2][2]
iRow = 3	MyData[3][0]	MyData[3][1]	MyData[3][2]
iRow = 4	MyData[4][0]	MyData[4][1]	MyData[4][2]

Hinweis:

Wie in vielen (aber leider nicht allen) Programmiersprachen üblich,
beginnt die Zählung von Array-Indizes auch hier bei Null.
Beim oben verwendeten zweidimensionalen Array entspricht der erste Index der Zeilen-, der zweite der Spaltennummer.
Im Gegensatz zu Borland Delphi ("TStringGrid::OnSelectCell(..ACol,ARow,..") wird die Reihenfolge
      "erst die Zeile, dann die Spalte"
hier auch bei der Übergabe von 'iRow' und 'iColumn' an Event-Handler beibehalten, z.B.:
      func OnMyTableGetCellText( tTable ptr pTable, int iRow, int iColumn, string ptr sText )
Siehe auch: Zählung von Zeilen und Spalten im Datenbereich einer Tabelle.

Jedes Element im Array kann in diesem Beispiel eine Zeichenkette (string) speichern.
Andere für die direkte Anzeige in der Tabelle geeignete Datentypen sind z.B. Integer (int) und Fliesskomma (float).


Für die Anzeige anderer Datentypen, die nicht direkt für die Anzeige in der Tabelle geeignet sind, kann als Alternative zu den oben erwähnten Arrays eine Script-Funktion als Datenquelle definiert werden (Details im folgenden Kapitel). Diese wird dann beim Zeichnen der Tabelle für jede auf dem Display sichtbare Zelle aufgerufen, wobei die Zeilen- und Spaltennummer als Funktionsargument (Parameter 'row' und 'column' als Integer) übergeben wird.
Aus dem Grund listet das Programmiertool nur die Script-Funktionen in der Auswahlliste unter 'DataSource' auf, die sich -basierend auf der Parameterliste- prinzipiell als Datenquelle eignen könnten.
Dazu muss natürlich bei der Definition der Anzeige bereits ein compiliertes Script vorhanden sein.

Selbstdefinierte Funktion als Datenquelle

Bei umfangreichen Tabellen ist es nicht ökonomisch, die Werte für alle Zellen der Tabelle ständig als mehrdimensionales Array vorrätig zu halten. Wenn z.B. der sichtbare Bereich der Tabelle nur einen Bruchteil des scrollbaren Bereiches (mit hunderten von Zeilen) umfasst, empfiehlt sich der Einsatz einer selbstdefinierten Funktion (im Script) als Datenquelle.
Die Funktion wird als OnGetCellText-Handler bei jedem Neu-Zeichnen der Tabelle aufgerufen, und liefert den Text für alle momentan sichtbaren Zellen.
Mit einer Funktion als Datenquelle kann eine Tabelle auch als 'Checkliste' verwendet werden.

Erzwungenes Neu-Zeichnen der Tabelle

Nach Script-gesteuerten Änderungen in der Datenquelle ist es i.A. nötig, die Tabelle neu zu zeichnen. Speziell bei der Verwendung einer selbstdefinierten Funktion als Datenquelle wird diese nicht ständig neu aufgerufen um zu testen, ob sich der Inhalt der Tabelle geändert hat.
Stattdessem kann das Script durch Setzen von tTable.RedrawFlags das Neu-Zeichnen der Tabelle veranlassen.
Ein Beispiel, in dem das Neu-Zeichnen der Tabelle per Script erzwungen wird, finden Sie hier.

Ausrichten des Textes innerhalb einer Zelle

Der Text in einer Zelle der Tabelle auf verschiedene Weisen ausgerichtet werden. Dabei spielt es keine Rolle, ob die am Anfang dieses Kapitels vorgestellte Datenquelle ein Array oder eine selbstdefinierte Funktion ist. Ohne explizite Angaben zur Ausrichtung werden feste Zellen (z.B. Überschriften und Zeilennummern) horizontal zentriert ausgerichtet, der Text in normale Datenzellen wird per Default linksbündig angezeigt.
Wenn nötig, kann eine andere Ausrichtung durch Vorsatz einer entsprechenden Backslash-Sequenz erzwungen werden:

\al (align left)

Ausrichtung am linken Rand der Zelle.
Dies ist die Default-Einstellung für normale (scrollbare) Datenzellen.

\ar (align right)

Ausrichtung am rechten Rand der Zelle.

\ac (align center)

Ausrichtung in der Mitte der Zelle.
Dies ist die Default-Einstellung für 'feste' Zellen (Überschriften, Zeilennummern).

Hinweis: Die oben aufgezählten Backslash-Sequenzen zum Ausrichten des Textes in einer Zelle müssen am Anfang der Zeichenkette stehen.

Anzeige von Sonderzeichen, z.B. 'Checkboxen' und 'Häkchen', in den Zellen einer Tabelle

Per Backslash-Sequenz können in einer Tabellen-Zelle auch die folgenden Sonderzeichen angezeigt werden:

\cm (checkmark, ✓ )

Zeichnet ein 'Häkchen' (ohne Box).
Entspricht in Unicode dem 'CHECK MARK' (U+2713)

\CM (checkmark, ✔ )

Zeichnet ein 'fettes Häkchen' (ohne Box).
Entspricht in Unicode dem 'HEAVY CHECK MARK' (U+2714)

\cb (checked box, ☑ )

Zeichnet ein 'Häkchen im Kasten' (mit Box).
Entspricht in Unicode einer 'BALLOT BOX WITH CHECK' (U+2611)

\ce (checkbox, empty ☐ )

Zeichnet eine 'leere Checkbox' (Kasten ohne Häkchen, wie "\be", U+2610).

\be (box, empty; ☐)

Zeichnet einen 'Kasten' ('Box') ohne Checkmark.
Entspricht in Unicode einer 'BALLOT BOX' (U+2610)

\bc (box, checked; ☑)

Zeichnet ein 'Häkchen im Kasten', wie "\cb".
Entspricht in Unicode einer 'BALLOT BOX WITH CHECK' (U+2611)

\bx (box with X, ☒)

Zeichnet einen 'Kasten' ('Box') mit Kreuz.
Entspricht in Unicode einer 'BALLOT BOX WITH X' (U+2612)

Die oben gezeigten Sonderzeichen sind so breit wie zwei Leerzeichen im aktuell eingestellten Zeichensatz.
Um z.B. ein Häkchen in einer bestimmten Zelle der Tabelle anzuzeigen, empfiehlt sich der Einsatz eines OnGetCellText-Handlers, der ein entsprechendes Symbol vor dem eigentlichen Text einfügt, wie "\cb Coffee":

Beispiel: Tabelle als 'Checkliste'

Um aus einer 'Tabelle mit Checkboxen' ein interaktives Bedienelement zu machen, bietet sich ein entsprechender OnTableClick-Handler an, der bei jedem "Anklicken" der Zelle die Checkbox setzt oder löscht (bzw. die damit verbundene Variable).

Hinweis

Die bei 'normalen' (nicht-tabellarischen) Anzeige-Elementen verfügbaren Backslash-Sequenzen funktionieren beim Zeichnen einer Tabellenzelle nicht. Dazu zählt u.A. auch die Anzeige 'beliebiger' Sonderzeichen per \chr( <Zeichencode> ), was z.B. bei 'Buttons mit Checkbox' (Häkchen) verwendet wird.

Ereignisse (von einer Tabelle ausgelöst, und per Script verarbeitbar)

Für spezielle Anwendungen können im Script Funktionen definiert werden, die beim Auftreten eines bestimmten Ereignisses (im Zusammenhang mit dem Anzeige-Element 'Tabelle') aufgerufen werden.
Die Namen dieser optionalen Event-Handler werden beim Design der Tabelle ausgewählt.
Falls im (compilierten) Script bereits geeignete Funktionen vorhanden sind, können diese in der unten gezeigten 'Property-Liste' ausgewählt werden. Eine Liste geeigneter, bereits im Script vorhandener Funktionen wird per Mausklick auf das "nach unten zeigende Dreieck" ( ▼ ) im Eingabefeld für den Namen aufgeklappt.
Wenn für ein bestimmtes Ereignis bereits ein Handler in der unten gezeigten Property-Liste existiert, so kann per Doppelklick auf den Namen des Handlers zu dessen Implementierung im Script-Quelltext umgeschaltet werden.

(Auswahl von Event-Handlern am Ende der Property-Liste im Programmiertool)

Die in der oben gezeigten Property-Liste anwählbaren Event-Handler werden in den folgenden Kapiteln vorgestellt.

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

Dieser Handler wird aufgerufen, wenn der Bediener z.B. per Touchscreen oder durch Drücken des Drehknopfes die angegebenene Tabellenzelle "angeklickt" hat. Nicht zu verwechseln mit dem 'Selektieren' (-> OnSelectCell) einer anderen Zelle durch Drehen des Drehknopfes am MKT-View !
Um Fehlbedienungen per Touchscreen zu vermeiden, gilt eine Zelle nur dann als 'angeklickt', wenn die Koordinate beim Loslassen des Touchscreens noch innerhalb der gleichen Zelle wie bei der ersten Berührung liegt. Auch 'Wischbewegungen' zu benachbarten Zellen (ohne den Stift bzw Finger vom Touchscreen abzuheben) führen dazu, dass der "OnTableClick"-Handler beim Loslassen des Fingers nicht aufgerufen wird.
Beispiel für einen "OnTableClick"-Handler (aus aus Applikation 'programs\script_demos\TableTest.cvt') :

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()

Das obige Beispiel verwendet ein einfaches Array (int Checked[200]) zum Speichern der Zustände aller Checkboxen (bzw. deren 'Häkchen'). Diese werden im (hier nicht gezeigten) OnGetCellText-Handler verwendet, um ein entsprechendes Sonderzeichen vor dem eigentlichen Text in der Zelle anzuzeigen.

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

Dieser Handler wird aufgerufen, wenn der Bediener z.B. per Scrollbalken den auf dem Bildschirm sichtbaren Bereich der Tabelle verschoben hat.
Die angegebene "Zell-Koordinate" (iNewTopRow, iNewTopColumn) bezieht sich auf die erste sichtbare Datenzelle, die links oben am Rand der Tabellengrafik sichtbar wird.

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

Dieses Ereignis tritt auf, wenn der Bediener durch Drehen des Drehknopfes, aber auch durch Antippen einer Zelle im Datenbereich der Tabelle eine andere Zelle anwählt, d.h. die aktuelle Selektion geändert wurde.
Hinweis: Durch Scrollen der Tabelle ändert sich die aktuelle Selektion nicht !
Die selektierte Zelle kann per Scrollbalken 'ausserhalb des sichtbaren Bereiches' gelangen.
Wird allerdings die momentan selektierte Zelle durch Drehen des Drehknopfes geändert, oder (bei Geräten mit Cursortasten) die Selektion per Tastendruck geändert, dann wird die Scroll-Position automatisch (per Firmware) so angepasst, dass die selektierte Zelle wieder im sichtbaren Bereich der Anzeige liegt.
Eine 'selbstprogrammierte' Reaktion auf das 'OnSelectCell'-Ereignis ist daher in den meisten Fällen unnötig.
Ein typische Anwendung für 'OnSelectCell' wäre z.B. das Anzeigen zusätzlicher Informationen über die momentan selektierte Zelle ("irgendwo ausserhalb der Tabelle").

Siehe auch: OnTableClick .

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

Mit diesem Ereignis kann das Script den in einer bestimmten Zelle anzuzeigenden Text, der normalerweise (ohne dieses Event) aus der Datenquelle gelesen würde, "überstimmen". Wenn vorhanden, wird der OnGetCellText-Handler bei jedem Neu-Zeichnen der Tabelle mehrmals aufgerufen (abhängig davon, welche Zellen momentan sichtbar sind). Liefert der Event-Handler den Wert FALSE zurück, dann gilt das Event als nicht verarbeitet, und die Firmware zeigt für die Zelle in Spalte 'iColumn', Zeile 'iRow' den Wert aus der Datenquelle an. Liefert der Event-Handler dagegen den Wert TRUE zurück, dann wird in der entsprechenden Zelle statt dem Wert aus der Datenquelle der vom Event-Handler im vierten Argument übergebene String (sText) angezeigt.

Beispiel (zeigt in der ersten Spalte, in den ersten vier Zeilen 'feste' Texte an, statt der Werte aus der Datenquelle):

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()

Hinweis: Die Reihenfolge der Übergabe von 'row' und 'column' in der Argumentenliste ist bewusst nicht kompatibel mit Borland Delphi's TStringGrid ! In den Event-Handlern gilt:
    "erst die Zeile, dann die Spalte" (vgl. Kapitel Datenquellen).


Seit 07/2016 kann das Script per OnGetCellText-Handler auch die Farben einzelner Zellen individuell steuern. Weisen Sie dazu im OnGetCellText-Handler die gewünschte Vorder- oder/und Hintergrundfarbe an die entsprechenden Komponenten
  pTable.CurrFgColor ("Vordergrundfarbe der aktuell zu zeichnenden Zelle"),
  pTable.CurrBgColor ("Hintergrundfarbe der aktuell zu zeichnenden Zelle"),
  pTable.CurrBgGradient ("Zweite Farbe für den Farbverlauf im Hintergrund der aktuell zu zeichnenden Zelle").
Ein einfaches, wenn auch sinnloses Beispiel finden Sie in programs/script_demos/TableTest.cvt:

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()

Seit 08/2016 eignet sich der OnGetCellText-Handler auch zur Anzeige von Sonderzeichen wie z.B. Checkboxen in beliebigen Zellen der Tabelle. Hier der entsprechende Ausschnitt aus dem OnGetCellText-Handler in programs/script_demos/TableTest.cvt:

  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;

Resultierende Anzeige aus dem obigen Beispiel
nach Anwahl einiger Einträge in der Tabelle

Eine Tabelle wird (wie jedes andere Anzeige-Element) normalerweise nur neu gezeichnet, wenn dies aus Sicht des Display-Interpreters nötig ist. Da der Handler im oben gezeigten Beispiel erst beim Zeichnen der Tabelle aufgerufen wird, wird im Beispiel mit der folgenden Anweisung das Neu-Zeichnen der Tabelle erzwungen:

  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 )

Geplant (für zukünftige Versionen) :
OnGetEditText() wird aufgerufen, kurz bevor eine Zelle in den Modus Editieren umgeschaltet wird.
Das Script hat dadurch die Möglichkeit, beim Editieren einen anderen 'Vorgabewert' zu definieren, abweichend vom momentan in der Datenquelle vorhandenen 'Ist-Wert'.

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

Geplant (für zukünftige Versionen) :
OnSetEditText() wird aufgerufen, wenn der in der angegebenen Zelle editierte Wert wieder in die Datenbank (eigentlich "Datenquelle", hier aber eher "Datensenke") übernommen werden soll.
Wie der Wert aus der editierten Zelle wieder in die Datenbank "zurückgeschrieben" wird, ist einzig und allein Sache des Scripts.

---

Beispiele zur Verwendung des Anzeige-Elements 'Tabelle'

Im Installationsarchiv (unter programs/script_demos) enthaltene Beispielapplikationen mit Tabellen:

TableTest.cvt

Einfaches Beispiel, aus dem die meisten Screenshots in dieser Dokumentation stammen.
Mit Event-Handlern für OnSelectCell, OnTableClick, und OnGetCellText zur Anzeige von Checkboxen.

ReadDir.cvt

Beispiel zum Lesen des Inhaltsverzeichnisses einer Speicherkarte mit Anzeige als Tabelle.

AppSel_1.cvt

Im 'App-Selektor' wird eine Tabelle zur Anzeige aller auf der Speicherkarte gefundenen *.cvt - Dateien verwendet. Der Bediener kann per Touchscreen oder Drehknopf einen Eintrag auswählen (-> die 'App' starten)

---

Syntax einer Tabellendefinition in einer Backslash-Sequenz

(nur für Entwickler und fortgeschrittene Anwender)

Intern wird die Definition einer Tabelle als Backslash-Sequenz codiert. Der in der UPT-Firmware enthaltene Interpreter analysiert diese Sequenz als Teil des Format-Strings in einer Displayzeilen-Definition. Falls Sie es vorziehen, den "Quelltext" für eine Anzeigeseite per Texteditor zu schreiben statt die Tabelle mit der Property-Liste im Programmiertool zu definieren, hier die Syntaxbeschreibung: ! ! ! t.b.d. ! ! !

Syntax:

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

Nach dem Namen der in der Tabelle anzuzeigenden Script-Variablen (Typ tTable) folgt eine optionale Liste aus Schlüsselwort/Werte-Paaren, mit je einem Gleichheitszeichen als Trennung zwischen Schlüsselwort (Key) und Wert (Value).
Beispiel:

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

In der Backslash-Sequenz werden i.A. mit ein bis drei Buchstaben abgekürzte Schlüsselwörter verwendet:

Eigenschaft	Kürzel	Beschreibung
DataSource	ds	Datenquelle (mit den "in der Tabelle anzuzeigenden WERTEN")
RowCount	rc	Anzahl Zeilen (Rows)
ColCount	cc	Anzahl Spalten (Columns)
BorderStyle	bs	Stil zum Zeichnen des äußeren Rahmens
LineWidth	lw	Breite der 'Gitterlinien' innerhalb der Tabelle
FixedRow	fr	Definiert, ob und wie die erste Zeile als 'fest' (nicht scrollend) verwendet werden soll
FixedColumn	fc	Definiert, ob und wie die erste Spalte als 'fest' (nicht scrollend) verwendet werden soll
FixedRowHeight	frh	Höhe der ersten Zeile (i.e. "Titelzeile") in Pixel
DataRowHeight	drh	Höhe aller weiteren Zeilen (i.e. "Datenzeilen") in Pixel
Scrollbars	ss	Definiert, ob und welche Scrollbalken am Rand der Tabelle angezeigt werden sollen
Title[0..9]	t0 .. t9	Spaltenüberschrift (Title)
ColumnWidth[0..9]	w0 .. w9	Spaltenbreite in Pixel
	otc	Name des optionalen "OnTableClick"-Handlers
	ots	Name des optionalen "OnTableScroll"-Handlers
	osc	Name des optionalen "OnSelectCell"-Handlers
	ogc	Name des optionalen "OnGetCellText"-Handlers
	oge	Name des optionalen "OnGetEditText"-Handlers
	ose	Name des optionalen "OnSetEditText"-Handlers

Im Interesse der Kompatibilität mit zukünftigen Erweiterungen werden unbekannte Key/Value-Paare vom Parser überlesen (ignoriert); erfolgt also keine Fehlermeldung bei Schreibfehlern. Das UPT-Programmiertool stellt die Liste von Key/Value-Paaren automatisch aus dem Property-Listen-Editor auf der Registerkarte 'Tabelle' (s.O.) zusammen; Schreibfehler können dabei nicht auftreten.

Wie in den meisten Programmiersprachen beginnt die Zählung von Array-Indizes auch hier bei Null (nicht Eins).
Stellt man sich die Tabelle als zweidimensionales Array mit 'Y' Zeilen und 'X' Spalten vor, dann ist y=0 "die erste Zeile" (i.A. die Zeile mit den Spalten-Titeln) und x=0 "die erste Spalte" (ganz links).

Beispiele:

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

Definiert eine mit der Script-Variablen 'MyTable' verbundene Tabelle mit 5 Zeilen (RowCount), 3 Spalten (ColCount), und drei vordefinierten 'Überschriften' (t0=Titel der ersten Spalte, etc).
Da keine Spalten-Breiten definiert sind, erhalten alle drei Spalten die gleiche Breite, passend zur Breite der gesamten Tabelle.

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

Definiert eine mit der Script-Variablen 'MyTable' verbundene Tabelle mit 5 Zeilen (RowCount), 3 Spalten (ColCount), ohne vordefinierten 'Überschriften'.
Die Breiten für die ersten beiden Spalten sind fest definiert (hier: 80 bzw 20 Pixel), die Breite der dritten Spalte wird daher automatisch bei der Anzeige berechnet (gesamte Tabellenbreite minus Breite der festen Spalten, minus Breite des optionalen vertikalen Scrollbalkens).

Hinweis:

Versuchen Sie nicht, innerhalb einer Tabellen-Definitions-Zeile außer dem "\table"-Element noch weitere Elemente (z.B. vorlaufenden oder nachlaufenden Text) zu platzieren.

Die Höhe und Breite einer Tabelle sind keine spezifischen Eigenschaften eines Anzeige-Elements, sondern eine Eigenschaft die (fast) alle Anzeige-Elemente aufweisen.
Alle nicht 'tabellen-spezifischen' Eigenschaften (z.B. Position, Größe, Farbe) werden nicht in der geklammerten Argumentenliste (nach dem Schlüsselwort "\table") definiert, sondern im oberen Teil der Registerkarte Eigenschaften einer Anzeige-Zeile.

---

Letzte Änderungen:
2016-08-16: Sonderzeichen und Text-Ausrichtung per Backslash-Sequenz.
2015-01-27: Implementierung und Dokumentation der Event-Handler.
2014-09-29: Beginn der Entwicklung des 'table'-Elements.

• Tabellen: Inhalt
• Einleitung
• Eigenschaften
• Datenquellen
• Text ausrichten
• Ereignisse
• Beispiele
•