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

Povíme si o tom, jak operační systém PalmOS spouští programy, a pak zkusíme dát všechno, co jsme doteď probrali, dohromady a vytvoříme první program, který sice nebude dělat vůbec nic, ale zato to bude dělat správně :-)

1.9 Spuštění programu na Palm Pilotovi

Na počítačích vybavených operačním systémem PalmOS může být v každém okamžiku spuštěna jen jedna aplikace. Při používání Palm Pilota to sice vypadá, jako bychom se mohli mezi jednotlivými aplikacemi přepínat, ale to je jen zdání vyvolané tím, že si aplikace ukládá do paměti stav, ve kterém jsme ji opustili. Pokud tedy máte spuštěný MemoPad a stisknete tlačítko spouštějící aplikaci DateBook, dojde k následující posloupnosti akcí:

1. Aplikace MemoPad dostane příkaz skončit,
2. takže uloží rozdělaný text, pozici kursoru a kategorii
3. a skončí.
4. Je spuštěna aplikace DateBook,
5. proto nahraje datum a aktuální pohled na něj, aby měl uživatel pocit rozdělané práce
6. a zobrazí jej.

O tom, jak PalmOS sdělí aplikaci, že má skončit, si povíme později; teď je pro nás zajímavější se dozvědět, jak jsou aplikace spuštěny a co je k tomu zapotřebí.

Funkce PilotMain()

Vstupním bodem vašeho programu (podobně jako je v jazyce C/C++ funkce main()) je při psaní aplikací pro PalmOS funkce PilotMain(). Operační systém volá tuto funkci, když uživatel spustí aplikaci dotekem pera na ikoně nebo hardwarovým tlačítkem. Funkce PilotMain() je však volána i v řadě jiných případů: například když si uživatel přeje najít nějaká data pomocí globálního vyhledávání, jsou postupně spuštěny všechny aplikace (jsou volány všechny funkce PilotMain() všech aplikací) a dostanou možnost přidat do seznamu nalezených záznamů svá data. Podobně když uživatel změní čas nebo datum, tak jsou volány všechny aplikace (funkce PilotMain() všech aplikací) a dostanou možnost na tuto změnu zareagovat. Prototyp funkce PilotMain() je:

UInt32 PilotMain(UInt16 cmd, void *cmdPBP, UInt16 launchFlags);

Parametr	Význam
cmd	Kód spuštění programu, kterým operační systém informuje naši aplikaci o důvodu, proč byla její funkce PilotMain() zavolána. Kódy spuštění jsou uvedeny hned v následující tabulce.
cmdPBP	Ukazatel na blok parametrů předaný programu. Při normálním spuštění aplikace uživatelem můžete tento parametr bezpečně ignorovat.
launchFlags	Doplňující informace předaná programu, která jej -- v situaci, kdy je funkce PilotMain() volána přímo operačním systémem bez vědomí uživatele -- informuje o tom, zda jsou dostupné a inicializované globální proměnné, zda může program komunikovat s uživatelem prostřednictvím grafického rozhraní apod. Při normálním spuštění aplikace uživatelem můžete tento parametr bezpečně ignorovat.
návratová hodnota	Funkce PilotMain() vrací následující hodnoty: 0 - volání funkce PilotMain() skončilo bez chyb != 0 - číslo chyby (čísla chyb budou probrána v některé z následujících kapitol)

Prototyp funkce PilotMain()a kódy spuštění jsou definovány v souboru SystemMgr.h.

Nejdůležitější věcí, kterou musíte v jakékoliv aplikaci ve funkci PilotMain() udělat, je zkontrolovat parametr cmd. Pokud zjistíte, že je funkce PilotMain() volána na přání uživatele (hodnota parametru cmd je sysAppLaunchCmdNormalLaunch), můžete spustit program. Dokud parametr cmd neotestujete, nemůžete vědět, za jakých okolností a proč volá systém funkci PilotMain(), ani zda můžete používat uživatelské rozhraní nebo globální proměnné. Časem začneme různé nestandardní kódy spuštění aplikace využívat; pro prvních několik aplikací, které napíšeme, nás ale bude zajímat jen ten první z následující tabulky kódů spuštění programu:

Kód spuštění	Význam
sysAppLaunchCmdNormalLaunch	Normální start programu způsobený tím, že uživatel spustil program ukázáním na jeho ikonu, přes klávesovou zkratku nebo hardwarové tlačítko. Parametry cmdPBP a launchFlags je možné bezpečně ignorovat.
sysAppLaunchCmdAlarmTriggered	Funkce PilotMain() je spuštěna s tímto kódem spuštění několik málo vteřin před vypršením času, na který má aplikace nastavený čas spuštění (probuzení). Při tomto volání se aplikace nesmí příliš dlouho zdržovat - může udělat jen něco velmi rychlého a stejně rychle skončit. Například aplikace DateBook využívá toto volání ke krátkému pípnutí.
sysAppLaunchCmdDisplayAlarm	Aplikace je s tímto kódem spuštění aktivována v čase, který si předem nastavila (třeba jako budík), a může zobrazit okno s upozorněním pro uživatele. Na rozdíl od volání s předchozím kódem spuštění se můžeme nyní ve funkci PilotMain() zdržet delší dobu - přehrát melodii, počkat na potvrzení uživatelem apod.
sysAppLaunchCmdCountryChange	Uživatel změnil v nastavení Palm Pilota jméno a údaje o zemi. Všechny aplikace dostanou pomocí tohoto volání možnost na tuto změnu zareagovat.
sysAppLaunchCmdExgAskUser	Takto je aplikace spuštěna, když prostřednictvím infračerveného spojení přijdou data (beaming). Podle hodnoty, kterou funkce PilotMain() vrátí, jsou pak data buď přijata, nebo odmítnuta.
sysAppLaunchCmdExgReceiveData	Funkce PilotMain() je spuštěna, protože jsou prostřednictvím infračerveného spojení přijata data určená pro příslušnou aplikaci.
sysAppLaunchCmdFind	Aplikace je po stisknutí hardwarového tlačítka pro globální vyhledávání volána s požadavkem na vyhledání textového řetězce, který uživatel zadal, a může přidat do seznamu nalezených záznamů odkazy na svá data.
sysAppLaunchCmdGoto	Aplikace je spuštěna s požadavkem na zobrazení příslušného záznamu, jehož index je funkci PilotMain() předán. Takto je funkce PilotMain() volána například tehdy, pokud uživatel ukáže při globálním vyhledávání na záznam, který patří příslušné aplikaci.
sysAppLaunchCmdInitDatabase	Příkaz pro inicializaci databáze během procedury HotSync.
sysAppLaunchCmdLookup	Aplikace je spuštěna s požadavkem na vyhledání některého záznamu. Na rozdíl od sysAppLaunchCmdFind může vyhledávat interaktivně.
sysAppLaunchCmdNotify	Aplikace si může vyžádat upozornění na některé systémové události. Upozornění je jí zasláno voláním funkce PilotMain() s tímto parametrem. Funguje pouze tehdy, je-li tato funkce v systému implementována.
sysAppLaunchCmdSaveData	Požadavek na uložení dat (často rozesílaný všem aplikacím před požadavkem na vyhledání řetězce).
sysAppLaunchCmdSyncNotify	Aplikace je volána po skončení procedury HotSync, protože byla změněna její data.
sysAppLaunchCmdSystemReset	S tímto kódem jsou volány všechny aplikace před restartem systému.
sysAppLaunchCmdTimeChange	Aplikace je volána při změně systémového data a času.
sysAppLaunchCmdSystemLock	Toto je kód, se kterým je volána aplikace zabezpečující soukromá data při požadavku na zamknutí systému. Naše aplikace by měla zpracovat tenhle kód jen tehdy, pokud nahrazuje vestavěnou aplikaci Security.

Struktura funkce PilotMain() programu, který reaguje pouze na spuštění uživatelem (a to budou v prvních pěti kapitolách všechny naše programy), je v následujícím rámečku:

UInt32 PilotMain(UInt16 cmd, MemPtr cmdPBP, UInt16 launchFlags) { // Otestujeme parametr cmd if (cmd == sysAppLaunchCmdNormalLaunch) { // tady náš program ví, že je spuštěn // může inicializovat proměnné, komunikovat s // uživatelem atd. } // Vrátíme nulu jako příznak ukončení programu // bez chyb return 0; }

Program NIC

Nyní je tedy čas vytvořit náš první nicnedělající program. Potřebujeme k tomu následujících několik souborů:

1. ikonu - zatím jsme o formátu ikon nemluvili, ale napravíme to v dalši kapitole - ikona je černé kolečko 24 × 24 bodů uložené v černobílém obrázku velikosti 32 × 32 bodů:
2. registrovaný kód pro jednoznačnou identifikaci aplikace (použijeme kód 'NECO, který již je registrován pro aplikace z této knihy)
3. musíme napsat základní část souboru prostředků aplikace (o jehož formátu a obsahu bude velká část příští kapitoly), která definuje ikonu a jméno aplikace, a její verzi
4. napsat vlastní zdrojový text programu, ve kterém uvedeme funkci PilotMain() a ohlídáme kód spuštění programu
5. vytvořit soubor Makefile podle návodu, který byl uveden v této kapitole
6. nakonec pomocí příkazu make zahájit překlad aplikace
7. pokud překlad proběhne bez chyby, můžeme aplikaci nainstalovat do Palm Pilota nebo emulátoru POSE a podívat se, že nedělá skutečně vůbec nic.

POZOR: Před instalací jakékoliv vaší právě napsané aplikace na Palm Pilota zazálohujte všechna data i tehdy, pokud jste ji předtím desetkrát zkoušeli v emulátoru a pokaždé fungovala bez chyb.

Soubor prostředků aplikace

Z úvodu této kapitoly plyne, že v souboru prostředků aplikace musí být uvedeny alespoň:

• ikona
• jméno aplikace
• číslo verze
• jednoznačná identifikace aplikace

Příště si řekneme o souboru prostředků aplikace něco víc; nyní jej tu jen uvedu v plném znění:

// Soubor nic.rcp (šipkou dolů zobrazíte zbytek) ICON "ikona.bmp" APPLICATIONICONNAME ID 1000 "NIC" VERSION ID 1001 "1.0" APPLICATION ID 1002 "NECO"

Zdrojový text programu

Komentovaný zdrojový text programu, který uvádíme, využívá doporučení vývojářů společnosti Palm, Inc. ohledně členění na pomocné funkce. Kromě funkce PilotMain() tedy definujeme ještě tři následující funkce, které budou (ať už budou nebo nebudou využity) součástí každého našeho programu:

1. ZacatekProgramu() - do této funkce později soustředíme všechny příkazy pro inicializaci programu: otevření databází, nahrání dynamických knihoven, kontrola verze systému, výběr prvního zobrazeného formuláře. Pokud tato funkce vrátí hodnotu různou od nuly, budeme ji považovat za chybový kód a skončíme program.
2. KonecProgramu() - tato funkce bude protipól funkce předchozí. Bude volána těsně před ukončením programu. Součástí této funkce bude zavření databází, uvolnění dynamických knihoven apod..
3. ZpracovaniUdalosti() - bude základní funkce programu. Jejím obsahem bude smyčka pro obsluhu systémových událostí a jejich využití pro ovládání našeho programu. Podrobnosti o této funkci si uvedeme v následující kapitole; zatím tato funkce zůstane prázdná.

Zdrojový text hlavního souboru zdrojového textu je uveden v následujícím rámečku:

// Soubor nic.c (šipkou dolů zobrazíte zbytek) // Na začátku souboru vložíme hlavičkový soubor PalmOS.h, // který připojí k programu všechny prototypy funkcí a datových // typů pro PalmOS. #include <PalmOS.h> // Na začátek vložíme prototypy našich funkcí Err ZacatekProgramu(); void KonecProgramu(); void ZpracovaniUdalosti(); // Následuje vlastní definice funkcí pro začátek a konec // programu. Protože nevyžadujeme žádné zvláštní akce na začátku // ani na konci programu, mohou být tyto funkce prázdné. Err ZacatekProgramu() { // Vracíme hodnotu nula, která znamená že nedošlo k chybě return 0; } void KonecProgramu() { } // Vlastní funkce PilotMain() tak, jak byla popsána výše - // rozšířená o volání funkcí ZacatekProgramu() a KonecProgramu() UInt32 PilotMain(UInt16 cmd, MemPtr cmdPBP, UInt16 launchFlags) { Err chyba; if (cmd == sysAppLaunchCmdNormalLaunch) { chyba = ZacatekProgramu(); if(chyba) { return chyba; } ZpracovaniUdalosti(); KonecProgramu(); } return 0; } // Na konec následuje vlastní funkce, ve které budeme později // něco dělat: ve smyčce zpracovávat systémové události. Teď v ní // zatím nebudeme dělat nic. void ZpracovaniUdalosti() { }

soubor Makefile

S trochou fantazie a po přečtení této kapitoly byste už měli být schopni napsat soubor Makefile sami. Zkuste to. Připomenu jen následující:

• Zdrojový text programu je v souboru nic.c, soubor prostředků aplikace se jmenuje nic.rcp.
• Výstupem překladače bude objektový soubor nic.o, po spojení s knihovnami vznikne soubor nic (bez přípony).
• Pro vytvoření aplikace ze souborů *.grc (kód programu) a *.bin (prostředky) použijte buď popsaný trik se soubory bin.hotovo a grc.hotovo (nebo zkuste vymyslet, jak to udělat jinak - napovím vám: program m68k-palmos-obj-res vždy vytváří soubor code000.jméno_aplikace.grc).
• nakonec doporučuji uvést "falešný cíl" pro vymazání všech souborů příkazem make uklid

Popsaný soubor Makefile v celé své kráse je v následujícím rámečku:

# Soubor Makefile (šipkou dolů zobrazíte zbytek) nic.prc: bin.hotovo grc.hotovo build-prc nic.prc "Nic" "NECO" *.grc *.bin bin.hotovo: nic.rcp pilrc nic.rcp touch bin.hotovo nic.o: nic.c m68k-palmos-gcc -c nic.c -o nic.o nic: nic.o m68k-palmos-gcc nic.o -o nic grc.hotovo: nic m68k-palmos-obj-res nic touch grc.hotovo uklid: rm *.o *.grc *.bin *.hotovo nic

Přeložíme naši první aplikaci

Teď už zbývá se jen přesunout do adresáře, kde máme soubory ikona.bmp, nic.c, nic.rcp a Makefile, a napsat příkaz:

        make

a po několika vteřinách se -- pokud jsme neudělali chybu -- vytvoří soubor nic.prc, ve kterém bude náš první program. Tento soubor můžete vyzkoušet v emulátoru POSE - zjistíte, že skutečně při svém spuštění neudělá nic.

Pokud si budete přát vymazat všechny dočasné soubory z adresáře, ve kterém proběhl překlad, napište

        make uklid

a všechny pomocné soubory (objektové - *.o, součásti souboru aplikace - *.grc a *.bin, naše pomocné soubory *.hotovo a soubor bez přípony (nic), ve kterém je kód programu spojený s knihovnami) budou smazány.

---

Příště si uvedeme, jak PalmOS komunikuje s naší aplikací - metodu "zpracování událostí", popíšeme si některé funkce pro zpracování událostí, a dozvíme se, jak udělat první program, který dělá alespoň něco - zobrazí vaši fotku na displeji Palm Pilota.