# meter

### Funkce

Zobrazení číselné hodnotu nebo výsledku numerického výrazu pomocí ručkového přístroje, sloupcového indikátoru, grafu a číslicového zobrazovače, s možností přiřazení výsledku do výstupního datového elementu.

### Syntax

      meter meter_name;
        rem = string;
        bubble = string;
        timer = timer_name;
        owner = owner_name;
        position = integer, integer, integer, integer;
        win_disable = [identifier, . . . ];
        win_title = string;
        access = integer;
        tab_select = integer;
        send_same_data;
        expression = real_expression;
        blink = boolean_expression;
        blink_rate = identifier;
        mode = identifier;
        content = identifier;
        range_from = real;
        range_to = real;
        low_limit = real;
        high_limit = real;
        history = integer;
        dec_places = integer;
        real_step = integer;
        frame = integer;
        h_grid = integer;
        v_grid = integer;
        font = font_identifier, integer, style_identifier;
        mask = string;
        text_shift = integer;
        driver_exception = driver_name;
        disable_menu;
        colors
          border_ink = color;
          border_paper = color;
          top_shadow = color;
          bottom_shadow = color;
          ink = color;
          paper = color;
          value = color;
          low_limit = color;
          high_limit = color;
          h_grid = color;
          v_grid = color;
        end_colors;
        blink_colors
          border_ink = color;
          border_paper = color;
          top_shadow = color;
          bottom_shadow = color;
          ink = color;
          paper = color;
          value = color;
          low_limit = color;
          high_limit = color;
          h_grid = color;
          v_grid = color;
        end_blink_colors;
      end_meter;

### Specifické parametry přístroje

- expression
  Obsahem tohoto parametru je numerický výraz, jehož výsledek bude přístroj zobrazovat. Má-li meter přiřazovat výsledek výrazu do výstupního datového elementu, je možno nahradit klíčové slovo expression přímo identifikátorem tohoto datového elementu:

      	data_element = real_expression;

- 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
- mode
  Určuje grafickou podobu přístroje uvedením jednoho z názvů módu:
  pointer - ručkový přístroj
  digital - digitální výstup
  dot_digital - digitální výstup bodový
  vertical_bar - poměrná svislá barevná plocha
  horizontal_bar - poměrná vodorovná barevná plocha
  flow_graph - posunující se graf
  sweep_graph - stojící graf
  text_display - návěští s aktuální hodnotou
- content
  Má rovněž vliv na grafickou podobu přístroje. Může nabýva tří hodnot:
  max - maximum
  med - medium
  min - minimum
  V některých módech může být přístroj meter pomocí parametru content doplněn o číselnou indikaci a možnost nastavení mezí prostřednictvím numerického řádku. Pro všechny módy znamená nastavení content = max zobrazení kompletní podoby přístroje
- range_from a range_to
  Jsou číselné parametry udávající rozsah stupnice přístroje a tím i rozsah výstupních hodnot.
- low_limit a high_limit
  Zadání horního a dolního limitu. Podkročení a překročení limitu je signalizováno změnou barvy a případným voláním událostních precedur.
- history
  Udává počet pamatovaných a zobrazovaných hodnot v grafu. Je délkou zobrazovaného historického trendu.
- dec_places
  Je počet zobrazovaných desetinných míst na číslicovém zobrazovači.
- real_step
  Je krok nastavování limitních hodnot pomocí numerického řádku. Jeho velikost udává přírůstek nebo úbytek hodnoty při použití inkrementálních a dekrementálních šipek.
- frame
  Určuje výšku 3D efektu ráměčku, kladné hodnoty udávají hloubku rámečku, záporné naopak jeho výšku.
- h_grid a v_grid
  Jsou parametry umožňující zobrazení vodorovných a svislých čar rastru grafu. Velikost parametrů h_grid a v_grid udává počet čar rastru v daném směru.
- font
  Je parametr určující font při vypisování hodnoty v módu text_display. 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).
- mask
  Je šablona pro vypisování číselné hodnoty do libovolné textové masky v mode = text_display. V textovém zápisu se maska zadává v apostrofech, v inspektoru přístroje bez apostrofů. Může mít např. tvar mask = 'rychlost = ##.## km/h', kde znak # nebo @ udává umístění a přesnost zobrazované numerické hodnoty. Jsou-li použity znaky #, budou případné nevýznamné nuly před číslem nahrazeny mezerami, použijí-li se znaky @, budou v pevném formátu vypisovány i tyto nuly. Implicitně je tento parametr prázdný.
- text_shift
  Svislý posun textu v módu text_display. Záporná čísla posunují text nahoru a kladná dolů. Text je na zobrazovači standardně vertikálně centrován podle informace o výšce písma, která je obsažena v použitém fontu. Pomocí parametru text_shift je možno text posunout vzhledem k takto zjištenému umístění.
- driver_exception
  Jméno ovladače, od kterého budou přijímány výjimky časování.
- disable_menu
  Příznak pro odstranění menu pro přepínání módů, je-li přístroj v okně.
- colors
  Seznam částí kresby přístroje, kterým lze měnit nastavení barvy:
  border_ink - okrajová linka border_paper - podkladový papír top_shadow - horní stín bottom_shadow - dolní stín ink - linky přístroje paper - papír přístroje value - standardní barva čáry low_limit - barva čáry dolního limitu high_limit - barva čáry horního limitu h_grid - vodorovná síť grafu v_grid - svislá síť grafu

### Poznámka

Je–li přístroj v okně, lze pomocí menu měnit mód přístroje za běhu programu. V žádném módu se nemění princip funkce přístroje, mění se pouze způsob jeho zobrazení.

1. mode = pointer
   Mód pointer napodobuje ručkový přístroj zobrazující spojitou veličinu. Při content = max lze přístroji za běhu programu měnit limity pomocí numerických řádků a přístroj současně zobrazuje i numerickou hodnotu číslicovým zobrazovačem.
2. mode = vertical_bar, mode = horizontal_bar
   Oba módy představují barevnou plochu, která se zaplňuje aktuální barvou v poměru hodnoty výrazu expression ku maximálnímu rozsahu přístroje. Při content = max se ještě zobrazí numerická hodnota a editovací řádky pro nastavení limit.
3. mode = flow_graph, mode = sweep_graph
   Oba módy vykreslují graf historického trendu. Mód flow_graph vykresluje poslední hodnotu vždy nakonec grafu, přičemž se celý graf průběžně posouvá. Mód sweep_graph vykresluje vždy od začátku grafu, po dosažení konce začne přepisovat hodnoty opět od začátku, graf se neposouvá. Při content = max se opět zobrazí poslední číselná hodnota první položky a umožní se změna obou limit pomocí numerického řádku. V případě druhého grafu bylo použito zobrazení rastru pomocí v_grid = 7; a h_grid = 10;.
   Přístroj má kromě módů flow_graph a sweep_graph k dispozici ještě mód line_animation_graph, který se podobá módu flow_graph. V tomto módu ale není využíváno grafického posuvu části grafu, který je u moderních grafických karet velmi rychlý. Graf je po částech překreslován přímkami. To přináší možnost stojícího gridu při posunujícím se grafu. Nevýhodou tohoto módu je nutnost vykreslování vysokého počtu čar v každém časovém kroku a tím značná spotřeba času na překreslování.
4. mode = digital, mode = dot_digital
   Oba módy zobrazují hodnotu pomocí bodového nebo segmentového zobrazovače, jehož barvy se mění podle vztahu zobrazované veličiny k hodnotám parametrů low_limit a high_limit.
5. mode = text_display
   Jako jediný z módů přístroje meter dovoluje spolu s numerickou hodnotou vypsat libovolný text před i za jeho číselné zobrazení, nadefinovaný parametrem mask. Podle nastavených limit se mění barva jeho pozadí. Velikost a druh písma určuje parametr font.

Implicitně jsou nastaveny parametry:

      position = 0, 0, 180, 120;
      access = 4294967295;
      tab_select = 4294967295;
      mode = pointer;
      content = min;
      range_from = 0;
      range_to = 100;
      low_limit = 25;
      high_limit = 75;
      history = 2;
      dec_places = 2;
      real_step = 1;
      h_grid = 0;
      v_grid = 0;
      font = SYSTEM, 9, normal;

### Příklad

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

      meter zobrazovač;
        timer = časový_krok;
        owner = background;
        position = 25, 15, 180, 120;
        expression = proměnná;
      end_meter;

### Nativní procedury přístroje meter

    SetValue( Value : real )

Nastavení přístroje na novou hodnotu Value včetně případného zápisu této hodnoty do výstupního datového elementu.

    SetLowLimit( LowLimit : real )
    SetHighLimit( HighLimit : real )

Nastavení horní a dolní varovné meze zobrazovaných hodnot.

    SetRange( RealFrom : real, RealTo : real )

Nastavení rozsahu přístroje. Historické hodnoty uložené ve vyrovnávací paměti případně přesahující nový rozsah budou ořezány. Stejně tak budou případně upraveny i limity. V rámci této metody bude přístroj v nové podobě i překreslen.

    SetMode( Mode : number )

Pomocí této metody je možné za běhu přístroje nastavovat jeho vzhled. Čísla módů a jejich stručný popis uvádí tabulka:
0 - pointer - ručkový přístroj
1 - digital - digitální výstup bodový
2 - dot_digital - digitální výstup
3 - vertical_bar - poměrná svislá barevná plocha
4 - horizontal_bar - poměrná vodorovná barevná plocha
5 - flow_graph - posunující se graf včetně případného gridu
6 - sweep_graph - stojící graf
7 - line_animation_graph - posunující se graf s případným stojícím gridem
8 - text_display - návěští s aktuální hodnotou

    MoveTo( XPosition, YPosition : real )

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

    NewRect( XPosition, YPosition, Width, Depth : real )

Zavoláním metody je možné přístroji změnit současně jeho pozici a velikost. Velikosti hodnot XPosition, YPosition, Width, a Depth jsou v bodech obrazovky.

    Hide()

Skrytí viditelného přístroje.

    Show()

Zobrazení skrytého přístroje.

    SetNewValueColor( Red, Green, Blue : number )

Nastavení libovolné barvy pro zobrazování normální výstupní veličiny (tj. mimo varovné limity). Čtyřiadvacetibitová barva je zadána v podobě red, green a blue složky, kdy každá může nabývat hodnot od 0 do 255.

    SetDecPlaces( DecPlaces : number )

Nastavení nového počtu zobrazovaných desetinných míst. Pro módy digital a dot_digital není akceptována vyšší hodnota než 4.

    SetGrid( HorizontalLines, VerticalLines : number )

Nastavení počtu horizontálních a vertikálních čar rastru. Zobrazování rastru se vypne nastavením nulových hodnot.

    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 meter

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 : real )

Procedura je zavolána po každém vyhodnocení výrazu před každým zobrazením a před každým případným zápisem do výstupního datového elementu. V proměnné Output je hodnota, která bude přístrojem zobrazena a která bude případně 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: real )

Procedura je zavolána jen při změně výsledku vyhodnocovaného výrazu oproti výsledku předchozímu. Proměnná Output je naplněna hodnotou, která bude přístrojem zobrazena a která bude případně po dokončení procedury zapsána do výstupního datového elementu. Toto hodnotu je možno v proceduře změnit.

    OnBelowLowLimit( Output: real )

Procedura je zavolána, jestliže výsledkek vyhodnocovaného výrazu v daném časovém kroku podkročil dolní limit. V proměnné Output je hodnota, která bude bude po dokončení procedury zobrazena a případně zapsána do výstupního datového elementu. Tuto hodnotu je možno v proceduře změnit.

    OnAboveHighLimit( Output: real )

Procedura je zavolána, jestliže výsledkek vyhodnocovaného výrazu v daném časovém kroku překročil horní limit. V proměnné Output je hodnota, která bude bude po dokončení procedury zobrazena a případně zapsána do výstupního datového elementu. Tuto hodnotu je možno v proceduře změnit.

    OnBelowRange( Output: real )

Procedura je zavolána, jestliže výsledkek vyhodnocovaného výrazu v daném časovém kroku podkročil dolní mez rozsahu přístroje a bude proto ořezán. V proměnné Output je hodnota před ořezáním. Tuto hodnotu je možno v proceduře změnit.

    OnAboveRange( Output: real )

Procedura je zavolána, jestliže výsledkek vyhodnocovaného výrazu v daném časovém kroku překročil horní mez rozsahu přístroje a bude proto ořezán. V proměnné Output je hodnota před ořezáním. Tuto hodnotu je možno v proceduře změnit.