98
OPENOFFICE.ORG
9.1 Objekty v API Uvedli jsme, že pro objekty je charakteristické, že mají určité vlastnosti a metody. Na objekty je ovšem možno pohlížet i uživatelsky. Vytváříme je proto, aby nám poskytovaly nějaké služby. Tento pohled se prosadil v API. Specifikace objektů se zde nazývají službami. Každá služba popisuje objekt nebo jeho část prostřednictvím kombinace rozhraní a vlastností. Rozhraní představuje sadu metod, které společně definují určitý aspekt služby. Pro snadnější orientaci je v názvech rozhraní uvedeno vždy jako první písmeno X. Mezi objekty UNO a službami většinou není jednoznačný vztah. Objekty mohou současně podporovat i několik služeb. Kromě toho některé služby podporují další služby, takže se často získává prostřednictvím jednoho objektu přístup k celému spektru služeb.
9.2 Uspořádání informací Služby, které mají podobné určení nebo některé společné znaky, jsou seskupeny do modulů. Tyto moduly jsou dále sdruženy do skupinových modulů. Všechny skupinové moduly jsou součástí největšího modulu, který je označen názvem com.sun.star. Když otevřeme soubor module-ix.html a v horní nabídce klepneme na Overview, tak se zobrazí právě tento modul (viz obrázek 9.1).
Obr. 9.1: Popis API
Současně jsou zobrazeny názvy všech skupinových modulů, které jsou jeho součástí, spolu s krátkým popisem. Při klepnutí na název některého ze skupinových modulů se zobrazí obsah tohoto modulu. Modul bývá rozdělen do sekcí, jejichž názvy jsou uvedeny ve druhém řádku odshora. Pokud některá sekce není v daném modulu aktuální, zobrazí se její název bez
9. Popis API
Ukázka elektronické knihy, UID: KOS181142
OPENOFFICE.ORG
99
podtržení. Kromě těchto základních sekcí mohou být uvedeny i další doplňkové informace a odkazy na příbuzná témata nebo na související kapitoly v průvodci pro návrháře. Velmi účinným pomocníkem je rejstřík všech použitých výrazů. Do rejstříku vstoupíme klepnutím na Index v horním řádku. Po volbě počátečního písmena najdeme hledaný výraz. Po klepnutí na výraz se zobrazí související informace.
9.3 Prvky použité v API
9.3.1 Moduly Moduly (Modules) slouží pouze k uspořádání služeb a ostatních prvků API. Názvy modulů se objevují v úplných názvech prvků API.
Popis API
API pracuje s řadou prvků, které se v jazyku Basic přímo nevyskytují, a proto je v řadě případů nutný určitý specifický postup. API má rovněž vlastní definice základních typů, které se odlišují od typů používaných v jazyku Basic. Při běžném použití však tyto rozdíly většinou nepůsobí problémy. Bližší informace jsou uvedeny v průvodci pro návrháře. Dále uvedeme popis prvků významných z hlediska jazyku Basic a způsob práce s nimi.
9.3.2 Služby Služby (Services) představují specifikaci objektů. Často se ale označení služba zjednodušeně používá přímo pro objekty API. Úplný název služby zahrnuje názvy všech modulů. Například úplný název často používané služby Spreadsheet je com.sun.star.sheet.Spreadsheet. Pro vytvoření instance služby se používá nejčastěji metoda createUnoService. Instance služby je jeden konkrétní objekt vytvořený podle specifikace příslušné služby.
9.3.3 Rozhraní V každém rozhraní (Interface) jsou soustředěny metody, které spolu určitým způsobem logicky souvisejí. Například rozhraní XCellRange zahrnnuje tři metody getCellByPosition, getCellRangeByPosition a getCellRangeByName. Všechny tři metody umožňují získat různým způsobem objekt buňky nebo oblasti buněk
9.3.4 Výčtové typy a skupiny konstant Výčtové typy (Enumeration Types/Enums) se využívají pro určení všech hodnot, které připadají v daném kontextu do úvahy. Například výčtový typ com.sun.star.table.CellVertJustify popisuje všechny možnosti svislého zarovnání textu v buňce. Tyto možnosti jsou STANDARD, TOP, CENTER a BOTTOM. Svislé zarovnání textu v buňce je učováno vlastností VertJustify, kterou poskytuje služba com.sun.star.table.CellProperties. Pokud tedy vytvoříme objekt buňky, např. Bunka, potom zarovnání textu v buňce nahoru zajistíme zápisem: Bunka.VertJustify = com.sun.star.table.CellVertJustify.TOP V jazyku Basic existuje možnost vyjádřit hodnotu výčtového typu číslem. Zarovnání textu nahoru odpovídá hodnota 1, a proto stejný výsledek získáme zápisem: Bunka.VertJustify = 1
9.3 Prvky použité v API
Ukázka elektronické knihy, UID: KOS181142
100
OPENOFFICE.ORG
Pojmenované hodnoty z popisu API jsou však názornější a doporučuje se jejich přednostní užívání. Skupiny konstant (Groups of Constants) definují možné hodnoty pro vlastnosti, parametry, návratové hodnoty a členy struktur. Použití konstant je obdobné. Například podtržení textu v buňce je dáno hodnotou vlastnosti CharUnderline. Vlastnost může nabývat hodnot ze skupiny konstant com.sun.star.awt.FontUnderline. Dvojitému podtržení odpovídá hodnota DOUBLE. Jedná se opět o vlastnost objektu buňky, a proto zapíšeme: Bunka.CharUnderline = com.sun.star.awt.FontUnderline.DOUBLE Pojmenovanou konstantu je znovu možno nahradit číslem, jehož hodnotu zjistíme z popisu jednotlivých konstant. V našem případě konstantě DOUBLE odpovídá číslo 2, a proto je možno zapsat: Bunka.CharUnderline = 2 známka Po
Pokud v případě výčtových typů a skupin konstant zjišťujeme hodnotu vlastností, získáváme jako návratovou hodnotu pouze číselný údaj.
9.3.5 Struktury Struktury (Structs) umožňují zkombinovat několik hodnot různých typů do jedné proměnné. Můžeme si například představit strukturu Zamestnanec, která soustřeďuje informace o zaměstnanci. Jednotlivé hodnoty neboli členy struktury mohou být Jmeno, Funkce a Plat. Pro pana Nováka bychom přiřadili konkrétní hodnoty takto: Zamestnanec.Jmeno = "Jan Novák" Zamestnanec.Funkce = "manažer" Zamestnanec.Plat = 25000 Hodnotu např. platu zjistíme takto: VysePlatu = Zamestnanec.Plat a obdržíme hodnotu 25 000. Uvedená struktura slouží jen jako příklad a v API bychom ji marně hledali. V procedurách můžeme používat pouze struktury, které jsou v API definovány. Kromě toho je nutno strukturu vždy před prvním použití deklarovat. Například velmi často používaná struktura com.sun.star.beans.PropertyValue má čtyři členy Name, Handle, Value a State. Deklaruje se takto: Dim Vlastnost as new com.sun.star.beans.PropertyValue
9.3.6 Sekvence Sekvence (Sequence) představují homogenní kolekce hodnot typu UNO s proměnlivým počtem prvků. Se sekvencemi se v jazyku Basic pracuje jako s poli. Pro ukázku se můžeme vrátit ke struktuře Zaměstnanec a vytvořit fiktivní sekvenci Zamestnanci pro údaje o čtyřech zaměstnancích. Sekvence je nutno před použitím rovněž deklarovat. Dim Zamestnanci(3) as new com.sun.star.beans.NazevSekvence Zamestnanec(0).Jmeno = "Jan Novák"
9. Popis API
Ukázka elektronické knihy, UID: KOS181142