Programování pro PalmOS počítače krok za krokem (61)

V tomto dílu si povíme, co jsou to výzvy, jak je definujeme a využíváme v našich programech.

5.2. Výzvy

Výzvy (anglicky alerts) bývají zobrazeny ve spodní části displeje. Umožňují informovat uživatele o důležitých krocích programu (třeba vytvoření databáze), varovat jej před nevratnými operacemi (vymazání databáze) nebo nechat jej učinit jednoduchá rozhodnutí. Na displeji může výzva vypadat například takto:

V souboru prostředků aplikace je výzva definována pomocí klíčového slova ALERT. Pro úplný popis definice se podívejte do druhé kapitoly. Zde si uvedeme jen dva příklady definice:

Definice	Výzva
ALERT ID VyzvaPokus INFORMATION BEGIN TITLE "Informace" MESSAGE "Zajimavy text." BUTTONS "OK" END
ALERT ID VyzvaPokus HELPID TextNapovedy DEFAULTBUTTON 1 WARNING BEGIN TITLE "Informace" MESSAGE "Prvni radek.\n" "Druhy radek." BUTTONS "ANO" "NE" END

Můžeme mít čtyři typy výzev. Tyto typy jsou odlišeny ikonou, která je zobrazena vlevo v rámečku. Výzvy mohou být:

•  Informace - slouží ke zpravení uživatele o akcích naší aplikace, které nemohou poškodit data. Příkladem je informace o autorovi programu nebo o tom, že je databáze prázdná (klíčové slovo je INFORMATION). Tyto výzvy mají většinou jen jedno tlačítko, označené OK.
   
•  Dotaz - ptá se uživatele na akce, při kterých nemohou být poškozena data. Tento druh výzev většinou mívá více tlačítek, kterými uživatel může vybrat požadovanou akci. Za příklad může sloužit potvrzení při kopírování záznamu z jedné databáze do druhé.
   
•  Varování - upozorňuje uživatele na to, že se aplikace chystá provést nevratnou operaci, které však uživatel může zabránit. Obvykle bývají vespod dvě tlačítka, označená ANO-NE. U tohoto typu výzev nesmíme nikdy zapomenout uvést správné číslo tlačítka za DEFAULTBUTTON - stisk tohoto tlačítka bude simulován v případě, že uživatel ukončí naši aplikaci v okamžiku zobrazení výzvy.
   
•  Chyba - informuje uživatele o chybě, která v programu nastala. Většinou se tento druh výzev používá pro závažnější chyby, ke kterým dojde při běhu aplikace.

Funkce pro zobrazení výzvy na displeji je velmi přímočará:

UInt16 FrmAlert(UInt16 cislo) Zobrazí na displeji výzvu a čeká na stisknutí tlačítka.
Vstupní parametry	cislo - jednoznačná identifikace výzvy
Vrácená hodnota	pořadové číslo stisknutého tlačítka počítáno zleva

Použití funkce FrmAlert() je jednoduché. Chceme-li zobrazit výzvu na displeji, voláme funkci FrmAlert() s požadovaným číslem výzvy tak, jak byla definována v souboru prostředků aplikace. Funkce vrátí index stisknutého tlačítka - první tlačítko zleva má číslo 0, druhé 1 a třetí 2.

Výzva zůstane na displeji až do okamžiku, kdy uživatel stiskne některé z tlačítek. Ukončíme-li aplikaci v okamžiku, kdy je výzva zobrazena, záleží na nastavení simulovaného stisku tlačítka za příkazem DEFAULTBUTTON. Pokud je simulovaný stisk tlačítka nastaven, program nečeká na akci uživatele a simuluje stisknutí příslušného tlačítka. Prohlédněte si následující definici výzvy v rámečku a zamyslete se nad tím, co je špatně:

ALERT ID VyzvaPokus
DEFAULTBUTTON 0
WARNING
BEGIN
    TITLE "Smazání databáze"
    MESSAGE "Přejete si smazat databázi (není možné vrátit!)"
    BUTTONS "ANO" "NE" 
END

Pokud se tato výzva objeví na displeji a uživatel stiskne tlačítko s obrázkem domečku, které slouží pro opuštění aplikace, stane se velmi nepěkná věc. Operační systém bude simulovat stisk tlačítka za DEFAULTBUTTON, v tomto případě tlačítka číslo O a textem "ANO". Aplikace, ve které se tato výzva vyskytuje, nepozná, že stisk tlačítka byl pouze simulován operačním systémem, a smaže databázi. Potom bude teprve zpracována událost appStopEvent a aplikace se ukončí.

5.3 Výzva s uživatelským textem

Výzvy, které jsme definovali v předchozí části, nemůžeme během běhu naší aplikace měnit. Operační systém PalmOS nám však poskytuje možnost, jak do textu výzvy vkládat jeden až tři řetězce přímo za chodu programu. Stačí kdekoliv v textu výzvy uvést kombinace znaků ^1, ^2 nebo ^3 a pro zobrazení výzvy využít funkci FrmCustomAlert().

UInt16 FrmCustomAlert(UInt16 cislo, const Char *s1, const Char *s2, const Char *s3)
Vstupní parametry	cislo - jednoznačná identifikace výzvy s1 - řetězec, kterým bude nahrazena kombinace znaků ^1 v textu výzvy nebo NULL s2 - řetězec, kterým bude nahrazena kombinace znaků ^2 v textu výzvy nebo NULL s3 - řetězec, kterým bude nahrazena kombinace znaků ^3 v textu výzvy nebo NULL
Vrácená hodnota	pořadové číslo stisknutého tlačítka počítáno zleva

Funkce FrmCustomAlert() je velmi citlivá na chyby programátora. Pokud uvedeme v textu výzvy kombinaci znaků stříška a číslice 1 až 3, tak musíme uvést příslušný parametr s1 až s3. Naopak, pokud danou kombinaci znaků neuvedeme, tak musí mít příslušný parametr hodnotu NULL. Pokud uvedeme špatnou kombinaci parametrů a speciálních kombinací v textu výzvy, může dojít k havárii operačního systému PalmOS.

Nahrazení kombinace znaků stříška a písmeno funguje jen v textu výzvy. V současné verzi PalmOS není způsob, jak za běhu programu měnit text, který se zobrazuje v titulku výzvy. Příklad definice výzvy s možností vložit uživatelský text je v následujícím rámečku:

ALERT ID VyzvaPokus
INFORMATION
DEFAULTBUTTON 0
HELPID TextNapovedy
BEGIN
    TITLE "Informace"
    MESSAGE "Toto je text" ^1 (^2)"
    BUTTONS "OK" 
END

V našem programu můžeme volat například funkci FrmCustomAlert(VyzvaPokus, "Pokus", "druhy", NULL) a dostaneme výzvu stejnou jako ta, která je na následujícím obrázku:

Pro svoji jednoduchost jsou výzvy často používány v aplikacích pro operační systém PalmOS. Můžeme jejich prostřednictvím sdělovat uživatelům důležité informace, nebo je nechat rozhodovat o důležitých akcích programu. Nejčastější dvě chyby při jejich použití jsou špatný počet nenulových parametrů u funkce FrmCustomAlert() a neuvedení správné deklarace DEFAULTBUTTON při definici výzvy.

---

Příště si povíme o různých chybách, které mohou nastat při běhu programu, a o způsobech, jak se s nimi vypořádat.