A StarOffice API bemutatása

A StarOffice API egy univerzális programozási felület a StarOffice programhoz. A StarOffice API használatával létrehozhatunk, megnyithatunk, módosíthatunk és kinyomtathatunk StarOffice-dokumentumokat. Segítségével kibővíthetjük a StarOffice funkcionalitását egyéni makrókkal, és saját párbeszédablakokat hozhatunk létre.

A StarOffice API nem csak a StarOffice Basic programmal használható, de már programozási nyelvekkel is, mint például a Java és a C++. Ezt egy Universal Network Objects (UNO, univerzális hálózati objektumok) nevű technológia teszi lehetővé, amely felületet biztosít számos programozási nyelvhez.

Ez a fejezet bemutatja, hogyan használható a StarOffice a StarOffice Basic programban az UNO segítségével. Ismerteti az UNO fő koncepcióját a StarOffice Basic-programozó szemszögéből. A StarOffice API különböző részeivel végzett munkáról bővebb részleteket a következő fejezetekben találhatunk.

Universal Network Objects (UNO, univerzális hálózati objektumok)

A StarOffice rendelkezik egy programozási felülettel, amely a Universal Network Objects (UNO, univerzális hálózati objektumok). Ez egy objektumorientált programozási felület, amelyet a StarOffice számos olyan objektumra oszt fel, amelyek programvezérlésű hozzáférést biztosítanak az irodai programcsomag adott részeihez.

Mivel a StarOffice Basic egy eljárásvezérelt programozási nyelv, számos nyelvi elemet kell hozzáadni, amelyek lehetővé teszik az UNO használatát.

Ha egy UNO-objektumot akarunk használni a StarOffice Basic programban, változódeklarációt kell megadnunk az adott objektumhoz. A deklarációt a Dim utasítással végezhetjük el (lásd: Fejezet 2, A StarOffice Basic nyelve). Az Object típusmeghatározást kell használni egy objektumváltozó deklarálásához:

Dim Obj As Object

Ez az utasítás deklarál egy Obj nevű objektumváltozót.

A létrehozott objektumváltozót ezután inicializálni kell a használat előtt. Ezt a createUnoService függvénnyel végezhetjük el:

Obj = createUnoService("com.sun.star.frame.Desktop")

Ez a függvényhívás az Obj változóhoz rendeli az újonnan létrehozott objektumra mutató hivatkozást. A com.sun.star.frame.Desktop egy objektumtípus, de az UNO-ban "szolgáltatásnak" hívják, nem típusnak. Az UNO filozófiájával összhangban az Obj egy olyan objektumra mutató hivatkozás, amely támogatja a com.sun.star.frame.Desktop szolgáltatást. Ezért a StarOffice Basic programban használt "szolgáltatás" kifejezés a más programozási nyelvek típus és osztály kifejezésének felel meg.

Viszont van egy fontos különbség: egy UNO-objektum egyszerre több szolgáltatást is támogathat. Néhány UNO-szolgáltatás viszont más szolgáltatásokat támogat, így egyetlen objektumon keresztül számos szolgáltatást elérhetünk. Például a már említett objektum, amely a com.sun.star.frame.Desktop szolgáltatáson alapul, tartalmazhat más szolgáltatásokat is, például dokumentumok betöltéséhez vagy a program bezárásához.

Megjegyzés - Míg a VBA-ban az objektum struktúráját az az osztály határozza meg, amelyhez tartozik, addig a StarOffice Basic programban a struktúrát azok a szolgáltatások határozzák meg, amelyekhez tartozik. Egy VBA-objektum mindig pontosan egy osztályhoz van rendelve. Ezzel szemben egy StarOffice Basic-objektum számtalan szolgáltatást támogat.

Tulajdonságok és metódusok

Egy StarOffice Basic-objektum több tulajdonságot és metódust is biztosít, amelyek meghívhatók az objektum által.

Tulajdonságok

A tulajdonságok olyanok, mint egy objektum tulajdonságai; például a Document objektum Filename és Title tulajdonsága.

A tulajdonságok egy egyszerű hozzárendeléssel állíthatók be:

Document.Title = "StarOffice 8 Basic programozói útmutató"

Document.Filename = "progman.sxv"

A tulajdonságnak - akárcsak egy változónak - van típusa, amely meghatározza, milyen értékeket tárolhat. Az imént említett Filename és Title tulajdonság karakterlánc típusú.

Igazi tulajdonságok és imitált tulajdonságok

A StarOffice Basic programban egy objektum legtöbb tulajdonságát a szolgáltatás UNO-leírása határozza meg. Ezeken az "igazi" tulajdonságokon felül vannak olyan tulajdonságok is a StarOffice Basic programban, amelyek az UNO-szint két metódusából állnak. Ezek egyikével lehet a tulajdonság értékét beolvasni, a másikkal pedig beállítani (get és set metódus). A tulajdonságot virtuálisan imitálja két metódus. Például az UNO karakterobjektumai rendelkeznek egy getPosition és egy setPosition tulajdonsággal, amellyel a beszúrási pont beolvasható, illetve módosítható. A StarOffice Basic-programozó a Position tulajdonságon keresztül érheti el az értékeket. Ettől függetlenül az eredeti metódusok is használhatók (a példában a getPosition és a setPosition).

Metódusok

A metódusok olyan függvények, amelyek közvetlenül egy objektumhoz kapcsolódnak, és amelyekkel ez az objektum meghívható. Az előző Document objektum például rendelkezhet egy Save metódussal, amelyet a következőképpen lehet meghívni:

Document.Save()

A metódusok, akárcsak a függvények, tartalmazhatnak paramétereket, és visszaadhatnak értékeket. Az ilyen metódushívások szintaxisa a klasszikus függvények irányába mutat. Az

Ok = Document.Save(True)

hívás a True (igaz) paramétert is megadja a dokumentumobjektum számára a Save metódus meghívásakor. Ha a metódus befejeződött, a Save tárolja a visszatérési értéket az Ok változóban.

Modulok, szolgáltatások és felületek

A StarOffice több száz szolgáltatást biztosít. A szolgáltatások áttekinthetőségéhez azok modulokba vannak csoportosítva. A StarOffice Basic-programozó számára nem bírnak egyéb jelentőséggel a modulok. Egy szolgáltatás nevének megadásakor csak a modulnév az, ami fontos, mert azt meg kell adni a névben. Egy szolgáltatás teljes neve a következőkből áll: a com.sun.star kifejezésből (amely meghatározza, hogy ez egy StarOffice-szolgáltatás), amelyet a modulnév követ (például frame), majd végül a szolgáltatás neve (például Desktop). A fenti példában a teljes név a következő:

com.sun.star.frame.Desktop

A modulokon és a szolgáltatásokon felül az UNO-ban létezik egy harmadik fogalom is, a "felület". A fogalom ismerős lehet a Java-programozók számára, viszont Basicben nem használják.

A felület több metódusból áll. Szigorúan véve az UNO nem támogat egyetlen metódust sem, csak felületeket, amelyek viszont különböző metódusokkal rendelkeznek. Más szóval a metódusok vannak (kombinációként) hozzárendelve a szolgáltatáshoz a felületekben. Ez a részleg főleg a Java- vagy C++-programozók számára lehet fontos, mert ezekben a nyelvekben a felület szükséges egy metódus meghívásához. A StarOffice Basic programban ez nem lényeges. Itt a metódusokat közvetlenül az adott objektum használatával kell meghívni.

Az API megértéséhez hasznos lehet, ha ismerjük a metódusok hozzárendeléseit különböző felületekhez, mivel a szolgáltatások számos felületet használnak. Ha ismerünk egy felületet, az egyik szolgáltatással megszerzett tudásunkat hasznosíthatjuk egy másik szolgáltatásnál is.

Néhány főbb felületet olyan gyakran használunk, hogy ismét olvashatunk róluk a fejezet végén, ahogy néhány szolgáltatás használja őket.

Az UNO-val végzett munka eszközei

A kérdés továbbra is az, hogy melyik objektum -- azaz szolgáltatás, ha az UNO-terminológián belül akarunk maradni -- melyik tulajdonságot, metódust és felületet támogatja, és ez hogyan állapítható meg. Az útmutatóban közölt leíráson felül az objektumokról további információkat kaphatunk a következő forrásokból: a supportsService metódus, a hibakeresési metódusok, a Fejlesztői útmutató és az API-referencia.

A supportsService metódus

Számos UNO-objektum támogatja a supportsService metódust, amellyel meg tudjuk állapítani, hogy egy objektum támogat-e egy adott szolgáltatást. Az

Ok = TextElement.supportsService("com.sun.star.text.Paragraph")

metódushívás például meghatározza, hogy a TextElement objektum támogatja-e a com.sun.star.text.Paragraph szolgáltatás.

Hibakeresési tulajdonságok

Minden UNO-objektum a StarOffice Basic programban tudja, milyen tulajdonságokat, metódusokat és felületeket tartalmaz. Tartalmaz olyan tulajdonságokat, amelyek ezt visszaadják egy lista formájában. Ezek a tulajdonságok a következők:

DBG_properties - visszaadja egy objektum összes tulajdonságát egy karakterláncban.

DBG_methods - visszaadja egy objektum összes metódusát egy karakterláncban.

DBG_supportetInterfaces - visszaadja azokat a szolgáltatásokat egy karakterláncban, amelyek támogatják az adott objektumot.

A következő példakód bemutatja, hogyan használható valódi alkalmazásokban a DBG_properties és a DBG_methods tulajdonság. Először létrehozza a com.sun.star.frame.Desktop szolgáltatást, majd üzenetablakokban megjeleníti a támogatott tulajdonságokat és metódusokat.

Dim Obj As Object

Obj = createUnoService("com.sun.star.frame.Desktop")



MsgBox Obj.DBG_Propierties

MsgBox Obj.DBG_methods

A DBG_properties tulajdonság használatánál figyeljünk oda, hogy a függvény visszaadja az összes olyan tulajdonságot, amelyet egy szolgáltatás elméletileg támogathat. Viszont semmi sem garantálja, hogy az adott objektum használni is tudja ezeket. Éppen ezért egy tulajdonság használata előtt hívjuk meg az IsEmpty függvényt, amellyel ellenőrizhetjük, hogy az adott tulajdonság ténylegesen elérhető-e.

API-referencia

Az elérhető szolgáltatásokról és azok felületeiről, metódusairól és tulajdonságairól további információkat a StarOffice API referenciájában találunk. Ez az www.openoffice.org webhelyen érhető el:

http://api.openoffice.org/docs/common/ref/com/sun/star/module-ix.html

A főbb felületek áttekintése

Néhány StarOffice-felület megtalálható a StarOffice API számos részében. Adott feladatok metódusait definiálják, amelyek számos problémára alkalmazhatók. Az alábbiakban áttekintést találunk ezekről a leggyakoribb felületekről.

Az objektumok eredetéről az útmutató későbbi részében olvashatunk bővebben. Itt jelenleg csak az objektumoknak egy bizonyos megközelítése kerül ismertetésre, amelyekhez a StarOffice API néhány fő felületet biztosít.

Környezetfüggő objektumok létrehozása

A StarOffice API két lehetőséget biztosít az objektumok létrehozásához. Az egyik a fejezet elején említett createUnoService függvényben található. A createUnoService létrehoz egy objektumot, amely univerzálisan használható. Az ilyen objektumok és szolgáltatások környezetfüggetlen szolgáltatásokként ismertek.

A környezetfüggetlen szolgáltatásokon felül vannak környezetfüggő szolgáltatások is, amelyek objektumai csak más objektumokkal együtt használhatók. Például egy táblázatdokumentum rajzobjektuma ezért csak ezzel a dokumentummal együtt létezhet.

A com.sun.star.lang.XMultiServiceFactory felület

A környezetfüggő objektumokat általában egy objektummetódus hozza létre, amelytől az objektum függ. Általában az XMultiServiceFactory felület által definiált createInstance metódust használjuk a dokumentumobjektumokban.

Az előbb említett rajzobjektum például létrehozható a következő módon, a táblázatobjektummal:

Dim RectangleShape As Object



RectangleShape = _

   Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")

A szöveges dokumentumban a bekezdéssablont is ugyanígy lehet létrehozni:

Dim Style as Object

Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")