Difference between revisions of "HU/Documentation/BASIC Guide/StarDesktop"

Revision as of 14:37, 15 May 2009

BASIC útmutató

{{{parttitle}}}

[[{{{PrevPart}}}|< Parte anterior]]

[[{{{NextPart}}}|Próxima parte >]]

• Az Apache OpenOffice Basic nyelv

• Egy Basic-program áttekintése
• Változókkal végzett munka
• Karakterláncok
• Számok
• Logikai értékek
• Dátum és idő
• Tömbök
• Változók hatásköre és élettartama
• Állandók
• Operátorok
• Elágazások
• Ciklusok
• Eljárások és függvények
• Hibakezelés
• Egyéb utasítások

• A futásidejű programkönyvtár

• Konverziós függvények
• Karakterláncok
• Dátum és idő
• Fájlok és könyvtárak
• Üzenet- és beviteli ablakok
• Egyéb függvények

• Bevezetés az API használatába

• Universal Network Objects (UNO, univerzális hálózati objektumok)
• Tulajdonságok és metódusok
• Modulok, szolgáltatások és felületek
• Az UNO-val végzett munka eszközei
• A főbb felületek áttekintése

• Munka a dokumentumokkal

• A StarDesktop
• Sablonok

• Szöveges dokumentumok

• A szöveges dokumentumok felépítése
• Szöveges dokumentumok szerkesztése
• Több, mint szöveg

• Munkafüzet-dokumentumok

• A munkafüzetek felépítése
  • Sorok és oszlopok
  • Cellák és tartományok
  • Munkafüzet-dokumentumok formázása
• Munkafüzet-dokumentumok szerkesztése

• Rajzok és bemutatók

• A rajzok felépítése
• Rajzobjektumok szerkesztése
• Bemutatók

• Diagramok (grafikonok)

• Diagramok használata munkafüzetekben
• A diagramok felépítése
• Diagramtípusok

• Adatbázisok

• SQL: lekérdezési nyelv
• Adatbázis-hozzáférési típusok
• Adatforrások
• Adatbázisok elérése

• Párbeszédablakok

• A párbeszédablakok használata
• Tulajdonságok
• Események
• Párbeszédablakok vezérlőelemei

• Űrlapok

• Munka az űrlapokkal
• Űrlap-vezérlőelemek
• Adatbázisűrlapok

< Előző oldal

Következő oldal >

Amikor dokumentumokkal dolgozunk, leggyakrabban két szolgáltatást használunk:

• Az egyik a com.sun.star.frame.Desktop szolgáltatás, amely hasonlít az Apache OpenOffice főszolgáltatására. Ez a szolgáltatás biztosítja az Apache OpenOffice keretobjektumának funkcióit, amely alá tartozik az összes dokumentumablak. A dokumentumok is ezzel az objektummal hozhatók létre, nyithatók meg és importálhatók.
• A másik szolgáltatás az egyes dokumentumobjektumok alapfunkcionalitását biztosító com.sun.star.document.OfficeDocument. Ez a szolgáltatás biztosítja a dokumentumok mentését, exportálását és nyomtatását végző metódusokat.

A com.sun.star.frame.Desktop szolgáltatás automatikusan létrejön az Apache OpenOffice indításakor. Ezt a szolgáltatást az Apache OpenOffice Basicben a StarDesktop globális név használatával címezhetjük meg.

A StarDesktop legfontosabb felülete a com.sun.star.frame.XComponentLoader. Ez tulajdonképpen a loadComponentFromURL metódust fedi le, amely felelős a dokumentumok létrehozásáért, importálásáért és megnyitásáért.

A StarDesktop objektum neve a StarOffice 5 programból származik, ahol minden dokumentumablak egyetlen közös, StarDesktop nevű alkalmazásba volt beágyazva. Az Apache OpenOffice jelenlegi verziójában a látható StarDesktop objektum már nem használt. Ennek ellenére a StarDesktop név megmaradt az Apache OpenOffice keretobjektuma számára, mert ez egyértelműen jelzi, hogy ez a teljes alkalmazás keretobjektuma.

A StarDesktop objektum a StarOffice 5 Application objektumának szerepét tölti be, amely a régebbi verzióban a gyökérobjektum volt. De a régi Application objektummal ellentétben a StarDesktop elsődlegesen az új dokumentumok megnyitásáért felelős. A régi Application objektumban megtalálható, az Apache OpenOffice megjelenítését végző függvények (például a FullScreen, FunctionBarVisible, Height, Width, Top, Visible) már nem használtak.

Template:Documentation/Note

ThisComponent

A ThisComponent globális név általában ugyanazt az objektumot adja vissza, mint a StarDesktop.CurrentComponent, de van egy fontos előnye. Ha a BASIC IDE-ben dolgozunk a makró futtatása, hibakeresése vagy böngészése közben, akkor a StarDesktop a BASIC IDE-t adja vissza. Ez valószínűleg nem az, amit szeretnénk. A ThisComponent az utoljára aktív dokumentumot adja vissza.

Alapvető információk az Apache OpenOffice-dokumentumokról

AzApache OpenOffice-dokumentumokkal végzett munka során hasznos lehet, ha ismerjük a dokumentumok alapvető kezelését az Apache OpenOffice programban. Ez magában foglalja az Apache OpenOffice-dokumentumok fájlnevei strukturálásának módját, akárcsak a nem mentett fájlok formátumát.

Fájlnevek URL-jelölésben

Mivel az Apache OpenOffice egy platformfüggetlen alkalmazás, ezért URL-jelölést használ (amely független az operációs rendszertől), amely a fájlnevekről szóló RFC 1738-as internetszabványban van definiálva. A fájlnevek ebben a rendszerben a file:/// előtaggal kezdődnek, amelyet a helyi elérési út követ. Ha a fájlnév alkönyvtárakat tartalmaz, akkor ezek törtjellel elválasztva szerepelnek, és nem fordított törtjellel, ahogy azt a Windows használja általában. A következő elérési út a C: meghajtó doc könyvtárának test.odt fájljára hivatkozik.

file:///C:/doc/test.odt

A helyi fájlnevek URL-lé történő konvertálásához az Apache OpenOffice a ConvertToUrl függvényt biztosítja. Egy URL helyi fájlnévvé történő konvertálásához az Apache OpenOffice a ConvertFromUrl függvényt biztosítja.

MsgBox ConvertToUrl("C:\doc\test.odt") 
  ' a file:///C:/doc/test.odt elérési utat jeleníti meg
MsgBox ConvertFromUrl("file:///C:/doc/test.odt")    
  '  a c:\doc\test.odt elérési utat jeleníti meg (Windows alatt)

Ez a példa konvertálja a helyi fájlnevet URL-lé, és megjeleníti azt egy üzenetablakban. Ezután konvertálja az URL-t helyi fájlnévvé, és azt is megjeleníti.

Az RFC 1738-as internetszabvány, amelyen ez alapul, a 0-9, a-z</literal> és <tt>A-Z karakterek használatát engedélyezi. Az összes többi karakter vezérlőkódként lesz beszúrva az URL-ekbe. Ehhez át lesznek konvertálva az UTF-8 kódolás szerinti hexadecimális értékükre, és egy százalékjel előzi meg őket. Például a szóköz a fájlnevekben a %20 karakterláncra lesz konvertálva az URL-ekben.

Az XML fájlformátum

Az Apache OpenOffice-dokumentumokat az XML fájlformátumon alapulnak. Az XML-alapú fájlok más programokkal is megnyithatók és szerkeszthetők.

Fájlok tömörítése

Mivel az XML normál szövegfájlokon alapul, az eredmény általában meglehetősen nagy méretű. Éppen ezért az Apache OpenOffice tömöríti a fájlokat, és ZIP-fájlként menti őket. A storeAsURL metódus használatával lehetőség van közvetlenül az eredeti XLM-fájlok mentésére. Lásd alább: storeAsURL metódus.

Dokumentumok létrehozása, megnyitása és importálása

A dokumentumok megnyitását, importálását és létrehozását a következő metódus végzi

StarDesktop.loadComponentFromURL(URL, Frame, SearchFlags, FileProperties)

A loadComponentFromURL első paramétere az adott fájl URL-jét adja meg.

Második paraméterként a loadComponentFromURL az Apache OpenOffice által belsőleg létrehozott ablak keretobjektumának a nevét várja. Általában ez az előre definiált _blank név, amelynek hatására az Apache OpenOffice egy új ablakot hoz létre. Megadható még a _hidden név is, amely lehetővé teszi, hogy az adott dokumentum betöltődjön, de rejtve maradjon.

Ezekkel a paraméterekkel a felhasználó megnyithat egy Apache OpenOffice-dokumentumot, mert az utolsó két paraméterként helyfoglalók (üres értékek) is megadhatók:

Dim Doc As Object   
Dim Url As String
Dim Dummy() 'A PropertyValues (tulajdonságértékek) üres tömbje
 
Url = "file:///C:/test.odt"
 
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy)

Ez a metódushívás megnyitja a text.odt fájlt, és megjeleníti egy új ablakban.

Tetszőleges számú dokumentum megnyitható így az Apache OpenOffice Basicben, majd szerkeszthető a visszaadott dokumentumobjektum használatával.

Template:Documentation/Note

A dokumentumablak tartalmának lecserélése

A _blank és a _hidden érték a Frame paraméterben azt eredményezi, hogy az Apache OpenOffice új ablakot hoz létre a loadComponentFromURL minden meghívásakor. Néhányszor hasznos lehet egy meglévő ablak tartalmának lecserélése. Ebben az esetben az ablak keretobjektumának egy nevet kell tartalmaznia. Ez a név nem kezdődhet aláhúzással. Ezenfelül a SearchFlags paramétert úgy kell beállítani, hogy a megfelelő keretobjektum létrejöjjön, ha még nincs létrehozva. A SearchFlags megfelelő állandója a következő:

SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
              com.sun.star.frame.FrameSearchFlag.ALL

A következő példa bemutatja, hogyan cserélhető le egy megnyitott ablak tartalma a keretparaméter és a SearchFlags használatával:

Dim Doc As Object   
Dim Dummy() 
Dim Url As String
Dim SearchFlags As Long
 
SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
              com.sun.star.frame.FrameSearchFlag.ALL
Url = "file:///C:/test.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "SajátKeret", SearchFlags, Dummy)
MsgBox "Nyomja meg az OK gombot a második dokumentum megjelenítéséhez."
 
Url = "file:///C:/test2.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "SajátKeret", _
      SearchFlags, Dummy)

Ez a példa először megnyitja a test.odt fájlt egy új, SajátKeret nevű ablakban. Ha a felhasználó jóváhagyja az üzenetpanelt, a program lecseréli az ablak tartalmát a test2.odt fájllal.

A loadComponentFromURL metódus lehetőségei

A loadComponentFromURL metódus negyedik paramétere egy PropertyValue adatmező, amely az Apache OpenOffice számára számos lehetőséget biztosít dokumentumok megnyitásához és létrehozásához. Az adatmezőnek biztosítania kell egy PropertyValue struktúrát minden lehetőséghez, amelyben a lehetőség neve van mentve karakterláncként, valamint a hozzá tartozó érték.

A loadComponentFromURL a következő lehetőségeket támogatja:

AsTemplate (logikai érték)

ha true (igaz), akkor betölt egy új, névtelen dokumentumot a megadott URL-ről. Ha false (hamis), akkor sablonfájlokat tölt be szerkesztéshez.

CharacterSet (karakterlánc)

megadja, milyen karakterkészleten alapul a dokumentum.

FilterName (karakterlánc)

megad egy speciális szűrőt a loadComponentFromURL függvény számára. Az elérhető szűrőnevek a \share\config\registry\instance\org\openoffice\office\TypeDetection.xml fájlban vannak definiálva.

FilterOptions (karakterlánc)

további lehetőségeket definiált a szűrők számára.

JumpMark (karakterlánc)

amikor egy dokumentum megnyílik, a program a JumpMark által megadott helyre ugrik.

Password (karakterlánc)

átad egy jelszót egy védett fájlnak.

ReadOnly (logikai érték)

betölt egy csak olvasható dokumentumot.

A következő példa bemutatja, hogyan nyitható meg egy vesszővel elválasztott fájl az Apache OpenOffice Calc programban a FilterName használatával.

Dim Doc As Object
Dim FileProperties(1) As New com.sun.star.beans.PropertyValue
Dim Url As String
 
Url = "file:///C:/doc.csv"
FileProperties(0).Name = "FilterName"
FileProperties(0).Value ="Text - txt - csv (StarCalc)"
FileProperties(1).Name = "FilterOptions"
FileProperties(1).value  = "44,34,0,1"
 
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, FileProperties())

A FileProperties adatmező csak egyetlen értéket fed le, mivel csak egy lehetőséget tartalmaz. A Filtername tulajdonság megadja, hogy az Apache OpenOffice egy Apache OpenOffice Calc-szövegszűrőt használjon-e a fájlok megnyitásához.

Új dokumentumok létrehozása

Az Apache OpenOffice automatikusan létrehoz egy új dokumentumot, ha az URL-ben megadott dokumentum egy sablon.

Ha viszont csak egy üres dokumentumra van szükségünk mindenféle igazítás nélkül, akkor megadhatjuk a private:factory URL-t:

Dim Dummy() 
Dim Url As String
Dim Doc As Object   
 
Url = "private:factory/swriter"
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())

Ez a metódushívás létrehoz egy üres Apache OpenOffice Writer-dokumentumot.

Dokumentumobjektumok

Az előző részben bemutatott loadComponentFromURL függvény egy dokumentumobjektumot ad vissza. Ez támogatja a com.sun.star.document.OfficeDocument szolgáltatást, amely viszont két fő felületet biztosít:

• a com.sun.star.frame.XStorable felületet, amely felelős a dokumentumok mentéséért, valamint
• a com.sun.star.view.XPrintable felületet, amely tartalmazza a dokumentumok nyomtatásához szükséges metódusokat.

Dokumentumok mentése és exportálása

Az Apache OpenOffice-dokumentumokat közvetlenül a dokumentumobjektumon keresztül lehet menteni, A com.sun.star.frame.XStorable felület store metódusa használható erre a célra:

Doc.store()

Ez a metódushívás így működik, feltéve, hogy a dokumentumhoz már hozzá van rendelve egy memóriatartomány. Ez viszont nem így van új dokumentumoknál. Ebben a helyzetben a storeAsURL metódust kell használni. Ez a metódus a com.sun.star.frame.XStorable felületben is definiálva van, és a dokumentum helyének megadására használható:

Dim URL As String
Dim Dummy()
 
Url = "file:///C:/test3.odt"
Doc.storeAsURL(URL, Dummy())

Az előbbi metódusokon felül a com.sun.star.frame.XStorable felület biztosít néhány segítő metódust, amelyek hasznosak lehetnek dokumentumok mentésekor. Ezek a következők:

hasLocation()

megadja, hogy a dokumentumhoz van-e már rendelve URL.

isReadonly()

megadja, hogy a dokumentum csak olvasható-e.

isModified()

megadja, hogy a dokumentumot módosították-e az utolsó mentése óta.

A dokumentum mentéséhez használt kód kiegészíthető ezekkel a lehetőségekkel, így például megadható, hogy a dokumentum csak akkor legyen mentve, ha az objektum ténylegesen módosult, és a fájlnév csak akkor legyen lekérdezve, ha arra tényleg szükség van:

If (Doc.isModified) Then
  If (Doc.hasLocation And (Not Doc.isReadOnly)) Then
    Doc.store()
  Else 
    Doc.storeAsURL(URL, Dummy())
  End If
End If

A példaprogram először ellenőrzi, hogy az adott dokumentum módosult-e az utolsó mentése óta. Csak akkor folytatja a mentési folyamatot, ha ez igaz. Ha a dokumentumhoz már hozzá van rendelve egy URL, és a dokumentum nem írásvédett, akkor a program menti a meglévő URL-lel. Ha nem rendelkezik URL-lel, vagy csak olvashatóként van megnyitva, akkor a program egy új URL-lel menti.

A storeAsURL metódus lehetőségei

Ahogy a loadComponentFromURL metódusnál is, úgy a storeAsURL metódus használatánál is megadható néhány lehetőség egy PropertyValue adatmező formájában. Ezek meghatározzák az Apache OpenOffice által használt dokumentummentési folyamatot. A storeAsURL metódus a következő lehetőségekkel rendelkezik:

CharacterSet (karakterlánc)

megadja, milyen karakterkészleten alapul a dokumentum.

FilterName (karakterlánc)

megad egy speciális szűrőt a loadComponentFromURL függvény számára. Az elérhető szűrőnevek a \share\config\registry\instance\org\openoffice\office\TypeDetection.xml fájlban vannak definiálva.

FilterOptions (karakterlánc)

további lehetőségeket definiált a szűrők számára.

Overwrite (logikai érték)

lehetővé teszi, hogy a program rákérdezés nélkül felülírjon egy létező fájlt.

Password (karakterlánc)

átadja a jelszót egy védett fájlnak.

Unpacked (logikai érték)

alkönyvtárakba menti a dokumentumot (tömörítés nélkül).

A következő példa bemutatja, hogyan használható az Overwrite lehetőség a storeAsURL metódussal együtt:

Dim Doc As Object   
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String
' ... a dokumentum inicializálása  
 
Url = "file:///c:/test3.odt"
FileProperties(0).Name = "Overwrite"
FileProperties(0).Value = True
Doc.storeAsURL(Url, FileProperties())

Ezután a példaprogram menti a Doc objektumot a megadott fájlnévvel, ha már létezik ilyen nevű fájl.

Dokumentumok nyomtatása

A mentéshez hasonlóan a dokumentumokat közvetlenül a dokumentumobjektummal lehet kinyomtatni. A com.sun.star.view.Xprintable felület Print metódusa használható erre a célra: A legegyszerűbb formájában a nyomtatás így néz ki:

Dim Dummy()
 
Doc.print(Dummy())

Ahogy a loadComponentFromURL metódus esetében is, úgy itt is a Dummy paraméter egy PropertyValue adatmező, amelyen keresztül az Apache OpenOffice számos lehetőséget meg tud adni a nyomtatáshoz.

A print metódus lehetőségei

A print metódus egy PropertyValue adatmezőt vár paraméterként, amely az Apache OpenOffice Nyomtatás párbeszédablakának beállításait tartalmazza:

CopyCount (egész szám)

a kinyomtatandó példányok számát adja meg.

FileName (karakterlánc)

a megadott fájlba nyomtatja a dokumentumot.

Collate (logikai érték)

arra utasítja a nyomtatót, hogy válogassa szét a kinyomtatott példányok lapjait.

Sort (logikai érték)

rendezi a példányokat több példány nyomtatásánál (CopyCount > 1).

Pages (karakterlánc)

a kinyomtatandó oldalak listáját tartalmazza (a szintaxis a Nyomtatás párbeszédablakéval azonos).

A következő példa bemutatja, hogyan nyomtatható ki több oldal a Pages lehetőséggel:

Dim Doc As Object   
Dim PrintProperties(0) As New com.sun.star.beans.PropertyValue
 
PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"
Doc.print(PrintProperties())

Nyomtatókiválasztás és -beállítások

A com.sun.star.view.XPrintable felület biztosítja a Printer tulajdonságot, amely kijelöli a nyomtatót. Ez a tulajdonság egy PropertyValue adatmezőt kap a következő beállításokkal:

Name (karakterlánc)

megadja a nyomtató nevét.

PaperOrientation (enumeráció)

megadja a papír tájolását (a com.sun.star.view.PaperOrientation.PORTRAIT érték jelenti az álló tájolást, a com.sun.star.view.PaperOrientation.LANDSCAPE pedig a fekvőt).

PaperFormat (enumeráció)

megadja a papír formátumát (például a com.sun.star.view.PaperFormat.A4 a DIN A4 méretű papírt jelenti, a com.sun.star.view.PaperFormat.Letter pedig az amerikai Letter szabványút).

PaperSize (méret)

megadja a papír méretét századmilliméterben.

A következő példa bemutatja, hogyan módosítható a nyomtató, és hogyan állítható be a papírméret a Printer tulajdonsággal.

Dim Doc As Object   
Dim PrinterProperties(1) As New com.sun.star.beans.PropertyValue
Dim PaperSize As New com.sun.star.awt.Size
 
PaperSize.Width = 20000   ' 20 cm
PaperSize.Height = 20000   ' 20 cm
PrinterProperties (0).Name="Name"
PrinterProperties (0).Value="Irodai HP Laserjet"
PrinterProperties (1).Name="PaperSize"
PrinterProperties (1).Value=PaperSize
Doc.Printer = PrinterProperties()

Ez a példa definiál egy PaperSize nevű objektumot, amely com.sun.star.awt.Size típusú. Ez a papírméret megadásához szükséges. Ezenfelül a program létrehoz egy PrinterProperties nevű adatmezőt a két PropertyValue elem számára. Ezután inicializálja ezt az adatmezőt a Printer tulajdonság beállítani kívánt értékeivel. Az UNO szemszögéből nézve a Printer nem egy valódi tulajdonság, hanem egy imitált tulajdonság.