# string_switch

### Funkce

Nastavení textu do výstupního datového elementu. Text je možno editovat pomocí editovacího řádku nebo vybírat z rolovacího seznamu s předdefinovanými řetězci znaků.

### Syntax

      string_switch string_switch_name;
        rem = string;
        bubble = string;
        owner = owner_name;
        position = integer, integer, integer, integer;
        win_disable = [ identifier, . . . ];
        win_title = string;
        access = integer;
        tab_select = integer;
        send_same_data;
        output = string_dataelement;
        index_output = number_dataelement;
        blink = boolean_expression;
        blink_rate = identifier;
        sound = file_name;
        enter_button;
        receivers = [ identifier, . . . ];
        item
          text = string;
          selected;
        end_item;
        item
          . . .
        end_item;
        font = font_identifier, integer, style_identifier;
        colors
          top_shadow = color;
          bottom_shadow = color;
          ink = color;
          paper = color;
          selected_ink = color;
          selected_paper = color;
          border = color;
        end_colors;
        blink_colors
          top_shadow = color;
          bottom_shadow = color;
          ink = color;
          paper = color;
          selected_ink = color;
          selected_paper = color;
          border = color;
        end_blink_colors;
      end_string_switch;

### Specifické parametry přístroje

- output
  Udává jméno datového elementu, kam se bude hodnota zadaná přístrojem string_switch zapisovat.
- index_output
  Udává jméno výstupního datového elementu, kam se bude zapisovat index aktuální položky nastavené v přístroji.
- blink
  Parametr uvádí logický výraz, jehož výsledek rozhoduje o tom, bude-li přístroj blikat -- tedy periodicky se překreslovat se střídavým použitím barevných sad colors a blink_colors. Po zastavení blikání se přístroj vždy vrátí do základní barevné sady colors.
- blink_rate
  Určuje frekvenci blikání přístroje uvedením jednoho z identifikátorů:
  slow - blikání s periodou 2 sekundy
  normal - blikání s periodou 1 sekunda
  quick - blikání s periodou 0.5 sekundy
- sound
  Obsahuje název souboru "*.WAV" se zvukovým doprovodem akce. Není–li tento parametr zadán, nebude zadávání textů doprovázeno žádnými zvuky.
- enter_button
  Je příznakem rozhodujícím o zobrazení potvrzovacího tlačítka. Tlačítko je umístěno na konci řádku. Není–li zde umístěno tlačítko (implicitní stav, kdy není tento parametr uveden), lze hodnotu potvrdit pouze z klávesnice klávesou <Enter>. Je–li tlačítko uvedeno (enter_button;), pak je možno poslat hodnotu i pomocí myši. Rozdíl ukazují obrázky:
  - přístroj jen s tlačítkem výběru
- receivers
  Obsahuje seznam všech přístrojů, kterým je posílána zpráva při změně stavu přístroje.
- item a end_item
  Klíčová slova, která uzavírají parametry položek přístroje string_switch.
- text
  Jsou parametry obsahující libovolné řetězce znaků, jejichž nabídka se zobrazí vždy při vyvolání seznamu přístroje. Právě zvolená hodnota bude mít barvu vybrané položky – viz obr.:
  - zobrazení seznamu myší
  - je zvýrazněna poslední vybraná položka, která byla ale před otevřením seznamu změněna. - zobrazení seznamu myší
  - je zvýrazněna poslední vybraná položka, která byla ale před otevřením seznamu změněna.
- selected
  Příznak vybrané položky při inicializaci. Bude–li selected u více položek, zvolí se první v pořadí, nebude–li zvoleno selected u žádné, bude při inicializaci aktuální první položka v pořadí.
- font
  Je parametr určující font. Má vždy tři parametry. První z nich font_identifier určuje typ písma (např. TIMES, SYSTEM, aj.), druhý určuje jeho velikost v tiskových bodech a třetí parametr style_identifier rozhoduje o tom, zda bude písmo normální (normal), tučné (bold) nebo skloněné (italic).
- colors a blink_colors
  Seznam prvků přístroje, kterým lze měnit nastavení barvy:
  top_shadow - horní stín
  bottom_shadow - dolní stín
  ink - text
  paper - pozadí textu
  selected_ink - text při zadávání
  selected_paper - pozadí textu při zadávání
  border - pozadí tlačítka potvrzení

### Poznámka

Hlavní předností přístroje string_switch je možnost výběru jeho aktuální hodnoty z více předem zadaných variant. Přitom jeho editační řádek si zachovává všechny editační vlastnosti, což kromě výběru umožňuje i libovolné editační zásahy.
Přístroj je vždy aktivován obsluhou. Navíc může být také aktivován také např. časovačem nebo jiným přístrojem, kdy se může automaticky nastavovat podle hodnoty ve svém výstupním datovém elementu nebo cokoliv realizovat ve své proceduře OnActivate().
Implicitně jsou nastaveny parametry:

      position = 0, 0, 200, 18;
      access = 4294967295;
      tab_select = 4294967295;
      font = SYSTEM, 10, bold;

### Příklad

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

      string_switch
        owner = background;
        position = 100, 200, 200, 18;
        output = jmeno;
        item
          text = 'Nováková';
        end_item;
        item
          text = 'Svoboda'
        end_item;
      end_string_switch;

### Nativní procedury přístroje string_switch

    Update()

Nastavení přístroje podle aktuálního stavu výstupního datového elementu.

    Update( SetOutput : boolean )

Nastavení přístroje podle aktuálního stavu jeho výstupního datového elementu. Parametr SetOutput určuje, budou-li nová data zpětně zapsána do výstupního datového elementu.

    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.

    Show()

Zobrazení skrytého přístroje.

    Hide()

Skrytí viditelného přístroje.

    ClearText()

Odstranění všech položek přístroje a smazání celého aktuálního seznamu textů.

    ClearItem( Index : number )

Odstranění textové položky určené parametrem Index.

    AddText( String : string )

Přidání nové textové položky na konec aktuálního seznamu položek.

    Select()

Vybrání přístroje. Do vybraného přístroje směřují veškeré události od klávesnice.

    ShowListBox()

Zobrazení výběrového seznamu položek přístroje. V takto zobrazeném seznamu je možno se pohybovat kursorovými klávesami a určitou položku poté zvolit klávesou Enter. Upozornění: Výběrový seznam běží modálně, nemůže tedy být spuštěn současně s jiným modálně běžícím dialogovým oknem.

    HideListBox( SetSelect : boolean )

Skrytí výběrového seznamu položek přístroje.

    SetIndex( Index : number )

Volba položky přístroje podle parametru Index.

    InsertText( Index : number; String : string )

Vložení nové textové položky do aktuálního seznamu položek před položku určenou parametrem Index.

    DisableEditable()

Vypnutí možnosti editace vybrané položky. Implicitně je editace povolena.

    EnableEditable()

Zapnutí možnosti editace vybrané položky. Implicitně je editace povolena.

    Blink( BlinkingActive : boolean )

Zapnutí a vypnutí blikání. Voláním procedury Blink s parametrem BlinkingActive nastaveným na true začne přístroj blikat (tj. střídavě se překreslovat s použitím barevných sad colors a blink_colors). Blikání je možno zastavit voláním procedury Blink s parametrem BlinkingActive nastaveném na hodnotu false. Frekvence blikání je dána parametrem přístroje blink_rate.

    ToggleBlink()

Přepnutí vzhledu přístroje do alternativní sady barev, tedy z colors do blink_colors nebo naopak podle okamžitého stavu. Po zastavení blikání se přístroj vždy vrátí do standardní barevné sady bez ohledu na předchozí volání procedury ToggleBlink.

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

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

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

### Specifické událostní procedury přístroje

    OnOutput( Output : string )

Procedura je zavolána před každým zápisem do výstupního datového elementu. V proměnné Output je hodnota, které bude bude po dokončení procedury zapsána do výstupního datového elementu. Toto hodnotu je možno v proceduře změnit.

    OnOutputChanged( Output: string )

Procedura je zavolána pouze před takovým zápisem do výstupního datového elementu, kdy se nová hodnota liší od hodnoty ve výstupním datovém elementu. Proměnná Output je naplněna hodnotou, která bude bude po dokončení procedury zapsána do výstupního datového elementu. Toto hodnotu je možno v proceduře změnit.