Návod pre programátorov: Ako pridať udalosť do kalendára

Najnovšia verzia programovacích nástrojov (SDK) pre Android s kódovým označením Ice Cream Sandwich je dostupná od minulého týždňa. Prináša mnoho vylepšení, medzi ktorými je aj priamy prístup k aplikácii Kalendár. Jednou z častých úloh, ktoré programátori potrebujú spraviť, je pridávanie nových udalostí do kalendára, a v tomto článku vysvetlíme krok za krokom ako na to s novým API.

Kalendár je jedna z často používaných aplikácií, na ktoré sa majitelia Android smartfónov spoliehajú pri organizovaní svojho pracovného, či súkromného života. Aplikácie môžu ku dátam v Kalendári pristupovať pomocou nového API dostupného v Androide 4.0. Pridávanie udalostí je jednoduché a nevyžaduje od aplikácie žiadne špeciálne oprávnenie.

Poznámka: Používatelia si samozrejme musia aplikáciu Kalendár prepojiť s nejakým kalendárovým účtom ako napr. Google Kalendár či Microsoft Exchange.

Krok 0: Príprava

Pre potreby tohto tutoriálu potrebujete mať vytvorený projekt s podporou Android 4.0 (API Level 14) a najnovšie kompilačné nástroje. Toto všetko je obsiahnuté v rámci ADT pluginu pre Eclipse. Predpokladáme, že máte nakonfigurovanú aplikáciu kalendár v emulovanom Android zariadení, prípadne v telefóne a Androidom ICS, ak patríte medzi tých, čo sa už k nejakému dostali.

Krok 1: Vytvorenie Intent-u

Na to, aby ste mohli z aplikácie umožniť vytvorenie udalosti v kalendári, potrebuje vytvoriť príslušný Intent. Tento Intent spustí aplikáciu Kalendár na obrazovke pre vytvorenie novej udalosti. Používateľ musí však novú udalosť potvrdiť, pričom môže pridať, prípadne zmeniť detaily udalosti.

Nasledujúci kód vytvorí spomenutý Intent:

Intent calIntent = new Intent(Intent.ACTION_INSERT);
calIntent.setData(CalendarContract.Events.CONTENT_URI);
startActivity(calIntent);

Tento kúsok kódu spustí prázdny Intent, s novou udalosťou nie sú spojené žiadne detaily.

Krok 2: Pridanie podrobností

Detaily kalendárovej udalosti sa dajú nastaviť cez extra parametre na vytvorenom objekte Intent. Parametre môžu reprezentovať popis udalosti, jej čas a dátum, prípadne ďalšie užitočné údaje – napr. či je udalosť verejná alebo súkromá, prípadne či vás má zobraziť počas udalosti ako zaneprázdneného. Nasledujúci kód je príklad na nastavenie názvu, popisu a lokality udalosti:

Intent calIntent = new Intent(Intent.ACTION_INSERT);
calIntent.setType("vnd.android.cursor.item/event");
calIntent.putExtra(Events.TITLE, "Lyžovačka 2011");
calIntent.putExtra(Events.EVENT_LOCATION, "Santa Cristina, Taliansko");
calIntent.putExtra(Events.DESCRIPTION, "Pravidelná jarná lyžovačka s kamošmi");
startActivity(calIntent);

Podrobnosti udalosti, ktoré sme zobrazili cez parametre (extras) Intentu budú automaticky vložené do formulára pridania novej udalosti, ktorý sa zobrazí používateľovi.

Krok 3: Nastavenie času a dátumu

Každá kalednárová udalosť je ohraničená určitými dátumami. Niektoré udalosti sú zadefinované časom začiatku a konca udalosti, iné môžu byť celodenné. Počiatočný aj konečný čas/dátum sa nastaví pomocou extra parametrov, podobne ako už spomenuté údaje udalosti.

Intent calIntent = new Intent(Intent.ACTION_INSERT);
calIntent.setType("vnd.android.cursor.item/event");
calIntent.putExtra(Events.TITLE, "Lyžovačka 2011");
calIntent.putExtra(Events.EVENT_LOCATION, "Santa Cristina, Taliansko");
calIntent.putExtra(Events.DESCRIPTION, "Pravidelná jarná lyžovačka s kamošmi");
GregorianCalendar calDate = new GregorianCalendar(2012, 2, 3);
calIntent.putExtra(CalendarContract.EXTRA_EVENT_ALL_DAY, true);
calIntent.putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, calDate.getTimeInMillis());
calIntent.putExtra(CalendarContract.EXTRA_EVENT_END_TIME, calDate.getTimeInMillis());
startActivity(calIntent);

V tomto príklade sme vytvorili celodennú udalosť na 3. marca 2012. Konkrétnejší čas konca aj začiatku môžete nastaviť pomocou parametrov CalendarContract.EXTRA_EVENT_BEGIN_TIME a CalendarContract.EXTRA_EVENT_END_TIME.

Krok 4: Ostatné nastavenia

Existujú ešte ďalšie parametre udalosti, ktoré je možné nastaviť. Patrí medzi ne napríklad nastavenie viditeľnosti udalosti (úroveň prístupu pre ostatných používateľov) a nastavenie dostupnosti počas trvania udalosti.

calIntent.putExtra(Events.ACCESS_LEVEL, Events.ACCESS_PRIVATE);
calIntent.putExtra(Events.AVAILABILITY, Events.AVAILABILITY_BUSY);

V tomto príklade sme nastavili udalosť ako privátnu a aby zobrazila používateľa ako zaneprázdneného (udalosť sa nemôže prekrývať so žiadnou inou udalosťou). Toto nastavenie zohľadňujú kalendáre napr. pri plánovaní stretnutí viacerých ľudí.

Krok 5: Vytvorenie opakujúcej sa udalosti

Sú udalosti, ktoré sa uskutočnia len raz ako napr. “Ocinova 50-ka,” a potom udalosti, ktoré sa opakujú, ako napr. pravidelné dvojtýždenné stretnutia na zhodnotenie pokroku na projekte. Nové API umožňuje nastaviť aj interval opakovania aplikácie, a to takto:

calIntent.putExtra(Events.RRULE, “FREQ=WEEKLY;COUNT=10;WKST=SU;BYDAY=TU,TH”);

Parameter RULE je vyjadrený v štandardnom formáte pre definíciu opakovania – iCalendar (viď RFC 5544 pre viac podrobností). V našom prípade sme nastavili opakovanie v pondelok a štvrtok po dobu 5 týždňov.

Záver

Aplikácia Kalendár bola súčasťou Android platformy už dlhšie, ale doteraz nebolo dostupné zdokumentované API pre prácu s ním. Android 4.0 (API Level 14) obsahuje kompletného poskytovateľa obsahu Kalendára, ktorý umožňuje prístup k údajom v kalendári používateľa za predpokladu, že aplikácia má potrebné práva. Avšak na jednoduché úkony, akým je aj pridávanie novej udalosti, nepotrebuje aplikácia žiadne dodatočné práva, a ich implementácia je veľmi jednoduchá.

Preložené z originálu: Android Essentials: Adding Events to the User’s Calendar (Shane Conder & Lauren Darcey)