# table

### Funkce

Dynamická výměna dat s tabulkovým kalkulátorem a jeho kompletní ovládání prostředky systému Control Web. Přístroj table umožňuje přímo zapisovat data do buněk tabulky, vyvolávat přepočet tabulky a zpětně číst data z buněk do systému. Tabulka zobrazuje "živá" data a případně i jejich grafické vyjádření.

### Syntax

      table table_name;
        rem = string;
        bubble = string;
        timer = timer_name;
        owner = owner_name;
        position = integer, integer;
        win_disable = [ identifier, . . . ];
        win_title = string;
        access = integer;
        tab_select = integer;
        driver_exception = driver_name;
        table_description
          editable;
          table_look = table_look_list;
          template_file = file_name;
          save_file_name = string_expression;
          visible = boolean_expression;
          save_file = boolean_expression;
          print = boolean_expression;
          printing = boolean_name;
        end_table_description;
        item_expr
          condition = boolean_expression;
          layer = real_expression;
          row = real_expression;
          column = real_expression;
          recalculate;
          expression = real_expression;
        end_item_expr;
        item_expr
          . . .
        end_item_expr;
        item_element
          get_data;
          condition = boolean_expression;
          layer = real_expression;
          row = real_expression;
          column = real_expression;
          recalculate;
          data_element = real_expression;
          arrays_access = array_access_identifier;
          index_from = real_expression;
          index_to = real_expression;
        end_item_element;
        item_element
          . . .
        end_item_element;
        errors
          receivers = receiver_name_list;
          error_layer = number_name;
          error_row = number_name;
          error_column = number_name;
          cp_type = number_name;
          table_type = number_name;
          item = number_name;
          index = number_name;
        end_errors;
    end_table;

### Specifické parametry přístroje

- editable
  parametr určující způsob práce tabulky. Není-li uveden, což je implicitní nastavení, pracuje tabulka jako zobrazovač protokolů a je možné do ní předávat data ze systému Control Web. Je-li naopak parametr definován, pracuje tabulka v módu vstupního formuláře, a je možné do ní data zapisovat ručně. Schopnost čtení dat z tabulky do aplikace v systému Control Web je zachována v obou případech nastavení editable. Pro explicitní nastavování parametrů je možné použít nativní procedury SetEditable a GetEditable.
- table_look
  parametr obsahující popis vzhledu tabulky. Seznam obsahuje části tabulky, které se mají zobrazovat. Jednotlivé prvky seznamu musí být odděleny čárkou. Tabulka může obsahovat následující části:
    container - tabulka bude umístěna v kontejneru DataView, bude tedy kolem sebe mít rolovací lišty a pravítka s popisem sloupců a řádků
    menu - bude zobrazeno menu tabulky
    tool_bar - bude zobrazena lišta s nástroji
    status_bar - bude zobrazen stavový řádek tabulky
- template_file
  jméno souboru s `TBW` dokumentem. Tento dokument je použit jako maska a při inicializaci přístroje je nahrán do tabulky. Do něj jsou během práce přístroje vkládána data z aplikačního programu. Dokument s aktuálními daty je posléze možné ukládat pod jinými jmény do souborů. Příprava dokumentu je možná v tabulkovém procesoru InCalc, který je k tabulkovému přístroji standardně přiložen.
- save_file_name
  řetězcový výraz pro jméno ukládaného souboru. Při požadavku uložení aktuálního stavu tabulky je výraz vyhodnocen a dokument uložen do souboru s takto získaným jménem. Cesta k novému souboru bude určena podle aktuálního stavu souboru s přesměrováním (*.RED).
- visible
  logický výraz určující viditelnost tabulky. Je-li jeho hodnota true, je tabulka zobrazena, nabývá-li hodnoty false, je tabulka skryta. Přístroj reaguje na změnu hodnoty tohoto výrazu.
- save_file
  logický výraz pro uložení aktuálního stavu tabulky. Dokument je uložen do souboru se jménem definovaným výrazem parametru save_file_name. Není-li parametr save_file_name definován, je dokument uložen do souboru 'TBL_DUMP.TBW'.
- print a printing
  tyto dva parametry slouží k řízení tisku tabulky. Je-li hodnota logického výrazu print true, a nezpracovává-li zrovna tabulka předchozí požadavek na tisk, je dokument vytištěn na aktuální tiskárně. Při zahájení tisku je na datový element definovaný parametrem printing nastavena hodnota true, při ukončení tisku hodnota false. Tabulka je vytištěna pouze je-li viditelná.
- condition
  podmínka pro práci s aktuální položkou seznamu tabulky. Je-li hodnota tohoto výrazu true, je položka zpracovávána a data v ní popsaná jsou čtena a zapisována do tabulky. Nabývá-li výraz hodnoty false, je při běhu přístroje tato položka přeskočena.
- layer, row a column
  tyto tři výrazy definují pozici políčka v tabulce, se kterým položka pracuje. Hodnoty jsou před přístupem upraveny, aby odpovídaly maximálním rozměrům tabulky. Minimální hodnota pro vrstvu, řádek i sloupec je 1. Je-li hodnota výrazu layer rovna 0, pracuje se s vybranou vrstvou. Zapisují-li se nebo čtou-li se datové elementy pole nebo buffery, definují tyto parametry pozici prvního políčka v tabulce, od kterého se budou data do tabulky zapisovat nebo z ní číst. Způsob uložení polí a bufferů definuje parametr arrays_access. Není-li některá souřadnice definována, je použita standardní hodnota - 0 pro vrstvu (aktuální vrstva), 1 pro sloupec a řádek.
- recalculate
  je-li parametr uveden, bude po vložení položky tabulka přepočítána. Při přepočtu se spočítají všechny výrazy v tabulce a nastaví se správné hodnoty do grafů zobrazujících data v tabulce. Není-li parametr uveden, nedochází při vložení položky k přepočtu a tabulka je pouze překreslena; tím se v tabulce změní pouze políčka, která mají přímou vazbu na data aplikačního programu.
- expression
  vlastní výraz, jehož výsledná hodnota je při splnění podmínky condition zapsána do políčka tabulky definovaného parametry layer, row a column.
- get_data
  je-li parametr uveden, jsou z tabulky z definovaného políčka přečteny hodnoty a jsou zkopírovány do datového elementu definovaného parametrem data_element. Není-li parametr uveden, jsou data z datového elementu čtena a do tabulky na definovaná políčka zapisována.
- data_element
  jméno jakéhokoli datového elementu, který se má do tabulky zapsat, nebo který se má plnit daty z tabulky. Směr toku dat se určuje parametrem get_data.
- arrays_access
  je-li datový element definovaný parametrem data_element pole nebo buffer, je nutné určit, jakým způsobem se bude do tabulky zapisovat nebo z tabulky číst. V principu je možné data do tabulky ukládat do sloupců, řádků nebo vrstev. Hodnota tohoto parametru může být jedno z následujících klíčových slov:
    layers - zápis (a čtení) do vrstev
    rows - zápis (a čtení) do řádku
    columns - zápis (a čtení) do sloupce
- index_from a index_to
  pro datové elementy pole a buffer je nutné definovat první a poslední index, popřípadě vzorek. Obsahem parametrů jsou výrazy a je proto možné dynamicky za běhu zapisovaný nebo čtený rozsah měnit.
- errors a end_errors
  klíčová slova ohraničující sekci pro definici chybového stavu tabulkového přístroje. Při čtení dat z tabulky může nastat situace, kdy se z tabulky získají data, která svým typem neodpovídají datovému elementu v systému Control Web, do něhož se data zapisují. V takovém případě tabulka přejde do stavu detekované chyby. Tento stav je možné po zpracování chybového vstupu změnit zpět na stav pracovní pomocí nativní procedury ClearError().

  Pro zjištění buňky tabulky, která způsobila chybný vstup a pro definici dalšího zpracování slouží následující parametry:

    receivers = seznam přístrojů, kterým bude poslána zpráva v okamžiku detekce chybného vstupu
    error_layer = vrstva buňky s chybnými daty
    error_row = řádek buňky s chybnými daty
    error_column = sloupec buňky s chybnými daty
    cp_type = datový typ elementu systému Control Web, do kterého se nepodařilo zapsat
    table_type = typ dat v tabulce, které způsobily nekompatibilitu
    item = pořadí bloku tabulky (item_expression či item_element, při jehož zpracování chyba nastala
    index = index prvku pole, je-li čtený prvek pole, do kterého se nepodařilo v důsledku chyby zapsat

  Datový typ v prvcích cp_type a table_type může nabývat následujících hodnot: error = 1, boolean = 2, shortcard = 3, cardinal = 4, longcard = 5, shortint = 6, integer = 7, longint = 8, real = 9, longreal = 10, string = 11, buffer = 12, unknown = 13.

### Poznámky

- Více informací o tabulkovém kalkulátoru je možné nalézt v kapitolách Tabulkový procesor InCalc a Prohlížeč grafů.
- Implicitní nastavení parametrů:
    position = 0, 0;
    table_look = ;
    template_file = ;

### Příklad

Příklad nastavení parametrů přístroje:

      table table;
        position = 132, 22;
        table_description
          table_look = window;
          template_file = PROT.TBW;
          save_file_name = Save_name;
          visible = Visibility;
          save_file = Save;
          print = Print;
          printing = Printing;
        end_table_description;
        item_element
          condition = true;
          row = 4;
          column = 2;
          recalculate;
          data_element = Pole;
          arrays_access = columns;
          index_from = 1;
          index_to = 7;
        end_item_element;
        item_element
          get_data;
          condition = true;
          row = 4;
          column = 2;
          recalculate;
          data_element = ReadPole;
          arrays_access = columns;
          index_from = 1;
          index_to = 7;
        end_item_element;
      end_table;

### Nativní procedury přístroje

    ShowTable()

Zobrazí skrytou tabulku.

    HideTable()

Skryje viditelnou tabulku.

    Minimize()

Minimalizuje okno s tabulkou, je-li tabulka viditelná.

    Restore()

Metoda obnoví původní velikost okna s tabulkou, je-li okno viditelné a minimalizované.

    NewRect( x, y, width, depth : real )

Zavoláním metody je možné přístroji změnit současně jeho pozici a velikost. Velikosti hodnot x, y, width, a depth jsou v bodech obrazovky.

    MoveTo( x, y : real )

Posunutí přístroje na pozici x, y. Velikosti hodnot x a y jsou v bodech obrazovky.

    SetEditable( Editable : boolean )

Povolí editaci tabulky. Tím se umožní zadávání dat do tabulky a tabulku je možné použít jako vstupní formulář. Přestanou se ovšem kopírovat hodnoty ze systému Control Web do tabulky. V opačném případě (Editable = false) není možné do tabulky data zadávat ručně, pracuje však přenos dat do tabulky. Čtení dat z tabulky do systému Control Web pracuje vždy.

    GetEditable( VAR Editable : boolean )

Metoda naplní proměnnou Editable aktuální hodnotou tohoto parametru.

    SetDVLogPos( x_pos, y_pos : real )

Tabulka bude posunuta na logické souřadnice (sloupec, řádek) x_pos, y_pos.

    SetActivePos( layer, row, column : number )

Metoda nastaví jako aktuální vrstvu vrstvu layer, a v této vrstvě kursor přemístí na buňku row, column. Je-li hodnota parametru layer rovna 0, bude provedeno nastavení v právě aktuální vrstvě.

    PrintTable()

Vytiskne aktuální stav dokumentu tabulky na aktuální tiskárnu. Stav tisku je možné zjistit pomocí metody IsPrinting.

    IsPrinting( VAR IsPrinting : boolean )

Metoda nastaví do proměnné IsPrinting aktuální stav tisku tabulky. Je-li zrovna tabulka tisknuta, vrátí metoda hodnotu true, v opačném případě vrátí hodnotu false.

    SaveTable( Path : string )

Uloží aktuální stav dokumentu do souboru jména Path. Součástí jména může být i cesta.

    OpenTable( Path : string; VAR ok : boolean )

Otevře nový template dokument. Součástí jména může být i cesta.

    GetCellType( L, R, C : number; VAR Type : real )

V proměné Type vrátí typ buňky. Popis parametrů:

- L, R, C
  Souřadnice buňky (L=vrstva, R=řádek, C=sloupec), jejíž typ se zjišťuje. Souřadnice jsou automaticky přizpůsobeny aktuálnímu rozměru tabulky. Vrstvy, řádky i sloupce jsou číslovány od 1, číslo vrstvy 0 znamená právě vybranou vrstvu tabulky.
- Type
  Typ buňky:
    0 - prázdná buňka
    2 - logická buňka
    10 - numerická buňka
    11 - textová buňka

    SetRealValue( L, R, C : number; V : real; Recalculate, PaintG : boolean )
    SetBooleanValue( L, R, C : number; V : boolean; Recalculate, PaintG : boolean )
    SetStringValue( L, R, C : number; V : string; Recalculate, PaintG : boolean )

Metody sloužící k nastavení dat do tabulky. Popis parametrů:

- L, R, C
  Souřadnice buňky (L=vrstva, R=řádek, C=sloupec), do které se má zapsat požadovaná hodnota. Souřadnice jsou automaticky přizpůsobeny aktuálnímu rozměru tabulky. Vrstvy, řádky i sloupce jsou číslovány od 1, číslo vrstvy 0 znamená právě vybranou vrstvu tabulky.
- V
  Hodnota zapisovaná na dané souřadnice. Podle metody může být typu boolean, real, string nebo buffer.
- Recalculate
  Tabulka je po vložení dat přepočítána. Při přepočtu se vyčíslí všechny výrazy v dokumentu a nastaví se aktuální hodnoty do grafů zobrazujících data tabulky.
- PaintG
  V tabulce jsou po vložení dat překresleny všechny grafy.

    GetRealValue( L, R, C : number; VAR V : real )
    GetBooleanValue( L, R, C : number; VAR V : boolean )
    GetStringValue( L, R, C : number; VAR V : string )

Metody sloužící ke čtení dat z tabulky. Popis parametrů:

- L, R, C
  Souřadnice buňky (L=vrstva, R=řádek, C=sloupec), ze které se má číst požadovaná hodnota. Souřadnice jsou automaticky přizpůsobeny aktuálnímu rozměru tabulky. Vrstvy, řádky i sloupce jsou číslovány od 1, číslo vrstvy 0 znamená právě vybranou vrstvu tabulky.
- V
  Hodnota přečtená z dané souřadnice. Podle metody může být typu boolean, real, string nebo buffer.

    PaintGraphs()

Metoda způsobí překreslení všech grafů celé tabulky. Během překreslování nedochází k přepočtu tabulky.

    Recalculate()

Metoda způsobí přepočítání celé tabulky. Vzorce obsažené v dokumentu jsou znova vyčísleny a do grafů zobrazujících data tabulky jsou přeneseny aktuální hodnoty.

    ClearError()

Při čtení dat z tabulkového přístroje může nastat situace, kdy se z tabulky získají data typu, který neodpovídá typu proměnné v systému Control Web. V takové případě tabulka přejde do režimu detekované chyby a na svých výstupech nastaví hodnoty popisující chybu. Po zpracování chyby (odstranění chybného typu z tabulky, konverze dat...) je tabulku nutné uvést zpět do pracovního režimu, právě touto nativní procedurou ClearError().

    SetColor( Layer, Row, Column, Red, Green, Blue : real )
    GetColor( &Layer, &Row, &Column, &Red, &Green, &Blue : real )

Metody umožňují nastavit nebo přečíst barvu pozadí vybrané buňky.

    SetPrintArea( Layer, Row1, Column1, Row2, Column2 : real )

Metoda nastavuje tiskovou oblast.

    SetGraphType( GraphName : string; GraphType : real )

Nastaví typ grafu. Parametr GraphName udává jméno grafu jehož parametr se má nastavovat. Parametr GraphType určuje typ grafu. Možné hodnoty jsou:

  0 - Bodový graf
  1 - Plošný graf
  2 - Spojnicový graf
  3 - Spojnicový graf s vyznačením bodů
  4 - XY graf
  5 - Spojnicový XY graf
  6 - Sloupcový graf
  7 - Pruhový graf
  8 - Kumulovaný sloupcový graf
  9 - Kumulovaný pruhový graf
  10 - Sloupcový graf překryvný
  11 - Pruhový graf překryvný
  12 - Výsečový graf
  13 - Sloupcový graf s třírozměrnými prvky
  14 - Pruhový graf s třírozměrnými prvky
  15 - Kumulovaný sloupcový graf s třírozměrnými prvky
  16 - Kumulovaný pruhový graf s třírozměrnými prvky

    SetGraphArea( GraphName : string; Layer, Row1, Column1, Row2, Column2 : real )

Nastaví oblast dat (vrstva, levý horní, pravý dolní roh) tabulky, které budou zobrazeny v grafu. Parametr GraphName udává jméno grafu jehož parametr se má nastavovat.

    GetGraphArea( GraphName : string; &Layer, &Row1, &Column1, &Row2, &Column2 : real )

Vrací oblast dat (vrstva, levý horní, pravý dolní roh) tabulky, které jsou zobrazeny v grafu. Parametr GraphName udává jméno grafu.

    GraphSerieVisible( GraphName : string; Order : real; Visible : boolean )

Zapíná/vypíná zobrazování průběhu zadaného parametrem Order. Závislosti se číslují od hodnoty 1. Parametr GraphName udává jméno grafu.

    SetGraphSerieColor( GraphName : string; Order, Red, Green, Blue : real )

Nastavuje barvu průběhu grafu zadaného parametrem Order. Závislosti se číslují od hodnoty 1. Parametr GraphName udává jméno grafu.

    GraphLegendVisible( GraphName : string; Visible : boolean )

Zapíná/vypíná zobrazování legendy. Parametr GraphName udává jméno grafu.

    GraphTitleVisible( GraphName : string; Visible : boolean )

Zapíná/vypíná zobrazování titulku grafu. Parametr GraphName udává jméno grafu.

    SetUserDepAxis( GraphName : string; Item, Value : real )

Nastavuje uživatelskou hodnotu zvoleného parametru osy závisle proměnné. Parametr GraphName udává jméno grafu. Parametr Item udává, která hodnota se bude nastavovat. Možné hodnoty jsou:

  0 - dolní mez
  1 - horní mez
  2 - hlavní krok
  3 - vedlejší krok

    SetUserIndepAxis( GraphName : string; Item, Value : real )

Nastavuje uživatelskou hodnotu zvoleného parametru osy nezávisle proměnné. Parametr GraphName udává jméno grafu. Parametr Item udává, která hodnota se bude nastavovat. Možné hodnoty jsou:

  0 - dolní mez
  1 - horní mez
  2 - hlavní krok
  3 - vedlejší krok

Tato metoda se uplatní pouze u XY grafů.

    SetAutoDepAxis( GraphName : string; Item : real )

Hodnotu zvoleného parametru osy závisle proměnné určená parametrem Item bude počítána automaticky z hodnot tabulky. Parametr GraphName udává jméno grafu. Možné hodnoty parametru Item jsou:

  0 - dolní mez
  1 - horní mez
  2 - hlavní krok
  3 - vedlejší krok

    SetAutoIndepAxis( GraphName : string; Item : real )

Hodnotu zvoleného parametru osy nezávisle proměnné určená parametrem Item bude počítána automaticky z hodnot tabulky. Parametr GraphName udává jméno grafu. Možné hodnoty parametru Item jsou:

  0 - dolní mez
  1 - horní mez
  2 - hlavní krok
  3 - vedlejší krok

Tato metoda se uplatní pouze u XY grafů.

### Událostní procedury přístroje

Přístroj může volat standardní událostní procedury:

    OnActivate()
    OnMouseDown( MouseX, MouseY : integer; LeftButton, MiddleButton, RightButton : boolean )
    OnMouseUp( MouseX, MouseY : integer; LeftButton, MiddleButton, RightButton : boolean )
    OnSelect()
    OnDeselect()
    OnShow()
    OnHide()
    OnNewPosition( RectX, RectY, RectW, RectD : integer )
    OnWindowMinimize()
    OnWindowMaximize()
    OnWindowRestore( WasMinimized, WasMaximized : boolean )
    OnWindowClose()

Podrobnější informace k těmto procedurám lze nalézt v kapitole Programování a procedury.