A szöveges dokumentumok felépítése

From Apache OpenOffice Wiki
Jump to: navigation, search
Book.png

Egy szöveges dokumentum lényegében négyféle típusú információt tartalmazhat:

  • magát a szöveget;
  • sablonokat a karakterek, bekezdések és oldalak formázásához;
  • nem szöveges elemeket, például táblázatokat, ábrákat és rajzobjektumokat;
  • a szöveges dokumentum globális beállításait.

Ez a szakasz főleg a szöveg- és a hozzá tartozó formázási lehetőségekkel foglalkozik.

Bekezdések és bekezdésrészek

A szöveges dokumentum alapja a bekezdések sorozatából áll. Ezek nincsenek elnevezve vagy indexelve, ezért nincs lehetőség az egyes bekezdések egyenkénti elérésére. Ennek ellenére a bekezdéseken végig lehet lépdelni az Enumeration objektum használatával a Bevezetés az API használatábacímű fejezetben ismertetett módon. Ez lehetővé teszi a bekezdések szerkesztését.

Az Enumeration objektummal végzett munka során azonban figyelnünk kell egy speciális helyzetre: nem csak a bekezdéseket adja vissza, hanem a táblázatokat is (szigorúan véve az Apache OpenOffice Writerben a táblázat is egy speciális bekezdés). Ezért, mielőtt dolgozni kezdenénk a visszaadott objektummal, ellenőriznünk kell, hogy az a com.sun.star.text.Paragraph szolgáltatást támogatja a bekezdések számára, vagy a com.sun.star.text.TextTable szolgáltatást a táblázatok számára.

A következő példa végiglépdel egy szöveges dokumentum tartalmán egy ciklusban, és minden objektumról egy üzenetben kiírja, hogy az táblázat vagy bekezdés.

Dim Doc As Object   
Dim Enum As Object
Dim TextElement As Object
 
' Dokumentumobjektum létrehozása   
Doc = StarDesktop.CurrentComponent
' Enumerációobjektum létrehozása 
Enum = Doc.Text.createEnumeration
' ciklus végig a szöveges elemeken
 
While Enum.hasMoreElements
  TextElement = Enum.nextElement
 
  If TextElement.supportsService("com.sun.star.text.TextTable") Then
    MsgBox "A jelenlegi blokk egy táblázatot tartalmaz."
  End If
 
  If TextElement.supportsService("com.sun.star.text.Paragraph") Then
    MsgBox "A jelenlegi blokk egy bekezdést tartalmaz."
  End If
 
Wend

Ez a példa létrehoz egy Doc nevű dokumentumobjektumot, amely az aktuális Apache OpenOffice-dokumentumra hivatkozik. A Doc objektum segítségével a program létrehoz egy Enumeration nevű objektumot, amely végiglépdel a szöveg egyes részein (bekezdéseken és táblázatokon), és hozzárendeli az adott elemet a TextElement objektumhoz. A példa a supportsService metódust használja annak megállapítására, hogy a TextElement objektum bekezdés vagy táblázat.

Bekezdések

A com.sun.star.text.Paragraph szolgáltatás hozzáférést biztosít a bekezdés tatalmához. A bekezdés szövege String tulajdonság használatával olvasható be és módosítható:

Dim Doc As Object   
Dim Enum As Object
Dim TextElement As Object
 
Doc = StarDesktop.CurrentComponent
Enum = Doc.Text.createEnumeration
 
While Enum.hasMoreElements
  TextElement = Enum.nextElement
 
  If TextElement.supportsService("com.sun.star.text.Paragraph") Then
    TextElement.String = Replace(TextElement.String, "úgynevezett", "ún.") 
    TextElement.String = Replace(TextElement.String, "satöbbi", "stb.")
    TextElement.String = Replace(TextElement.String, "Tisztelt", "T.") 
  End If
 
Wend

Ez a példa megnyitja az aktuális szövegdokumentumot, és végiglépdel rajta az Enumeration objektum segítségével. A TextElement.String tulajdonság segítségével hozzáfér a bekezdések szövegéhez, és lecseréli az úgynevezett, satöbbi és Tisztelt szót az ún., stb. és T. rövidítésre. A cserére használt Replace függvény nem része az Apache OpenOffice Basic nyelvnek. Ez a Keresés és csere fejezetben leírt példafüggvény egy példánya.

Documentation note.png Az itt ismertetett, szöveg bekezdéseihez való hozzáférést biztosító eljárás tartalma hasonló a VBA-ban használt Paragraphs listához, amely az ott rendelkezésre álló Range és Document objektumon keresztül érhető el. Míg a VBA-ban a bekezdésekhez a számuk alapján lehet hozzáférni (például a Paragraph(1) függvénnyel), az Apache OpenOffice Basicben az előbbiekben ismertetett Enumeration objektumot kell használni.

Az Apache OpenOffice Basicben nincs közvetlen megfelelője a VBA-ban rendelkezésre álló Characters, Sentences és Words listáknak. Viszont megvan a lehetőségünk, hogy átváltsunk egy TextCursor objektumra, amellyel lehetővé válik a karakter-, szó- és mondatszintű navigáció.

Bekezdésrészek

Lehet, hogy az előző példa megfelelően lecseréli a szöveget, de néha előfordulhat, hogy elrontja a formázást.

Ez azért fordulhat elő, mert egy bekezdés különálló alobjektumokból áll. Ezek mindegyike saját formázási információkat tartalmaz. Ha például a bekezdés közepe egy félkövér szót tartalmaz, akkor ez az Apache OpenOffice programban három bekezdésrészként fog megjelenni: a félkövér betűtípus előtti rész, majd a félkövér szó, és végül a félkövér betűtípus utáni rész, amely normálként ismét jelenik meg.

Ha most a bekezdés szövegét módosítjuk a bekezdés String tulajdonságával, akkor az Apache OpenOffice először törli a régi bekezdésrészeket, majd egy új bekezdésrészt szúr be. Az eredeti rész formázása ezután el fog tűnni.

Ha meg akarjuk tartani a formázást, elérhetjük az adott bekezdésrészeket is a teljes bekezdése helyett. A bekezdések rendelkeznek saját Enumeration objektummal ebből a célból. A következő példa egy dupla ciklust mutat be, amely végiglépdel a szöveges dokumentum összes bekezdésén és azok bekezdésrészein, majd alkalmazza az előző példában megismert cseréket:

Dim Doc As Object   
Dim Enum1 As Object
Dim Enum2 As Object
Dim TextElement As Object
Dim TextPortion As Object
 
Doc = StarDesktop.CurrentComponent
Enum1 = Doc.Text.createEnumeration
 
' a ciklus végiglépdel az összes bekezdésen
While Enum1.hasMoreElements
  TextElement = Enum1.nextElement
 
  If TextElement.supportsService("com.sun.star.text.Paragraph") Then
    Enum2 = TextElement.createEnumeration
    ' a ciklus végiglépdel az összes bekezdésrészen 
 
    While Enum2.hasMoreElements
      TextPortion = Enum2.nextElement
      MsgBox "'" & TextPortion.String & "'"
      TextPortion.String = Replace(TextPortion.String, "úgynevezett", "ún.") 
      TextPortion.String = Replace(TextPortion.String, "satöbbi", "stb.")
      TextPortion.String = Replace(TextPortion.String, "satöbbi", "stb.") 
    Wend
 
  End If
Wend

A példa egy kettős ciklussal lépdel végig a szöveges dokumentumon. A külső ciklus a szöveg bekezdésein lépdel végig. A belső ciklus ezeknek a bekezdéseknek a részeit dolgozza fel. A példában bemutatott kód módosítja a bekezdésrészek tartalmát a bekezdésrész String tulajdonságának használatával, akárcsak az előző példa a bekezdésekkel. Viszont mivel itt közvetlenül a bekezdésrészeket módosítja a program, így a formázásuk megmarad a szöveg cseréje után.

Formázás

A szöveget többféleképpen formázhatjuk. A legegyszerűbb mód, ha a formázási tulajdonságokat közvetlenül egy szövegrészhez rendeljük. Ezt hívják közvetlen formázásnak. A közvetlen formázás főleg a rövid szövegeknél használatos, mert ott a felhasználó az egérrel el tudja végezni a formázást. Például kiemelhetünk egy szót a szövegen belül a félkövér betűtípussal, vagy középre igazíthatunk egy vonalat.

A közvetlen formázás mellett, formázhatjuk a szöveget sablonok használatával is. Ezt hívják közvetett formázásnak. A közvetett formázásnál egy előre definiált sablont rendelünk az adott szövegrészhez. Ha a szöveg megjelenését később módosítani kell, csak a sablont kell módosítanunk, az Apache OpenOffice ezután módosítja az összes olyan szövegrész megjelenését, amely ezt a sablont használja.

Documentation note.png A VBA-ban egy objektum formázási tulajdonságai általában több alobjektum között oszlanak szét (például Range.Font, Range.Borders, Range.Shading és Range.ParagraphFormat). A tulajdonságokat kaszkádolt kifejezések formájában lehet elérni (például Range.Font.AllCaps). Ezzel szemben az Apache OpenOffice Basicben a formázási tulajdonságok közvetlenül, a megfelelő objektumok használatával érhetők el (TextCursor, Paragraph stb.). A következő két szakasz áttekintést nyújt az Apache OpenOffice program karakter- és bekezdéstulajdonságairól.
Documentation note.png A formázási tulajdonságok megtalálhatók minden objektumban (Paragraph, TextCursor stb.), és közvetlenül alkalmazhatók.

Karaktertulajdonságok

Azokat a formázási tulajdonságokat, amelyek az egyes karakterekre vonatkoznak, karaktertulajdonságoknak nevezik. Ezek magukban foglalják a félkövér típust és a betűtípust. Az olyan objektumoknak, amelyek lehetővé teszik a karaktertulajdonságok beállítását, támogatniuk kell a com.sun.star.style.CharacterProperties szolgáltatást. A szolgáltatások széles skáláját felismeri, amelyek támogatják ezt a szolgáltatást. Ezek közé tartozik az előzőekben ismertetett, bekezdésekhez használható com.sun.star.text.Paragraph szolgáltatásai és a bekezdésrészekhez használható com.sun.star.text.TextPortion szolgáltatásai.

A com.sun.star.style.CharacterProperties szolgáltatás nem nyújt semmilyen felületet, csak tulajdonságokat, amelyeken keresztül a karaktertulajdonságok megadhatók és meghívhatók. A karaktertulajdonságok teljes listája megtalálható az Apache OpenOffice API-referenciában. A következő lista ismerteti a legfontosabb tulajdonságokat:

CharFontName (karakterlánc)
a kijelölt betűtípus neve.
CharColor (hosszú egész szám)
a szöveg színe.
CharHeight (lebegőpontos érték)
a karaktermagasság pontban (pt) megadva.
CharUnderline (állandócsoport)
az aláhúzás típusa (a com.sun.star.awt.FontUnderline tulajdonságnak megfelelő állandók).
CharWeight (állandócsoport)
a betűsúly (a com.sun.star.awt.FontWeight tulajdonságnak megfelelő állandók).
CharBackColor (hosszú egész szám)
a háttérszín.
CharKeepTogether (logikai érték)
az automatikus sortörés kikapcsolása.
CharStyleName (karakterlánc)
a karaktersablon neve.

Bekezdéstulajdonságok

Az olyan formázási tulajdonságok, amelyek nem az egyes karakterekre vonatkoznak, hanem a teljes bekezdésre, azok a bekezdéstulajdonságok. Ezek magukban foglalják a bekezdés távolságát az oldal szélétől, valamint sortávolságot is. A bekezdéstulajdonságok a com.sun.star.style.ParagraphProperties szolgáltatáson keresztül érhetők el.

A bekezdéstulajdonságok is számos objektumban elérhetők. Minden olyan objektum, amely támogatja a com.sun.star.text.Paragraph szolgáltatást, támogatja a com.sun.star.style.ParagraphProperties objektumban megtalálható tulajdonságokat is.

A bekezdéstulajdonságok teljes listája megtalálható az Apache OpenOffice API-referenciában. A leggyakrabban használt bekezdéstulajdonságok a következők:

ParaAdjust (enumeráció)
szöveg függőleges tájolása (a com.sun.star.style.ParagraphAdjust objektumnak megfelelő állandók).
ParaLineSpacing (struktúra)
sortávolság (a com.sun.star.style.LineSpacing tulajdonságnak megfelelő struktúra).
ParaBackColor (hosszú egész szám)
a háttérszín.
ParaLeftMargin (hosszú egész szám)
bal margó századmilliméterben.
ParaRightMargin (hosszú egész szám)
jobb margó századmilliméterben.
ParaTopMargin (hosszú egész szám)
felső margó századmilliméterben.
ParaBottomMargin (hosszú egész szám)
alsó margó századmilliméterben.
ParaTabStops (struktúratömb)
a tabulátorok típusa és helye (com.sun.star.style.TabStop típusú struktúrák tömbje).
ParaStyleName (karakterlánc)
a bekezdéssablon neve.

Példa: egyszerű HTML-exportálás

A következő példa bemutatja a formázási információkkal végzett munkát. Végig lépked egy szöveges dokumentumon, és létrehoz egy egyszerű HTML-fájlt. Minden bekezdést a <P> HTML-parancs jelöl. A félkövér bekezdésrészeket a <B> HTML-parancs jelöli exportáláskor.

Dim FileNo As Integer, Filename As String, CurLine As String
Dim Doc As Object      
Dim Enum1 As Object, Enum2 As Object
Dim TextElement As Object, TextPortion As Object
 
Filename = "c:\text.html"
FileNo = FreeFile
Open Filename For Output As #FileNo      
Print #FileNo, "<HTML><BODY>"
Doc = StarDesktop.CurrentComponent
Enum1 = Doc.Text.createEnumeration
 
' a ciklus végiglépdel az összes bekezdésen
While Enum1.hasMoreElements
  TextElement = Enum1.nextElement
 
  If TextElement.supportsService("com.sun.star.text.Paragraph") Then
    Enum2 = TextElement.createEnumeration
    CurLine = "<P>"
 
    ' a ciklus végiglépdel az összes bekezdésrészen
    While Enum2.hasMoreElements
      TextPortion = Enum2.nextElement
 
      If TextPortion.CharWeight = com.sun.star.awt.FontWeight.BOLD THEN
        CurLine = CurLine & "<B>" & TextPortion.String & "</B>"
      Else 
        CurLine = CurLine & TextPortion.String
      End If
 
    Wend
 
    ' sor kiírása
    CurLine = CurLine & "</P>"
    Print #FileNo, CurLine
  End If
 
Wend
 
' HTML-lábléc kiírása 
Print #FileNo, "</BODY></HTML>"
Close #FileNo

A példa alapja az előzőekben bemutatott módszerhez hasonló, amikor a program végiglépked a szöveg bekezdésrészein. Ehhez a kódhoz lett hozzáadva a HTML-fájl írására szolgáló kód és a bekezdésrészletek betűsúlyát megvizsgáló kód, amely a félkövér bekezdésrészeket ellátja a szükséges HTML-paranccsal.

A karakter- és bekezdéstulajdonságok alapértelmezett értékei

A közvetlen formázás mindig elsőbbséget élvez a közvetett formázással szemben. Más szóval a sablonokat használó formázás hozzárendelése kisebb prioritású, mint a közvetlen formázásé.

Annak megállapítása, hogy egy adott dokumentumszakasz közvetlenül vagy közvetetten van formázva, nem egyszerű. Az Apache OpenOffice eszköztárán láthatók a leggyakoribb szövegtulajdonságok, mint például a betűtípus, -súly és –méret. De az, hogy az adott beállítások sablonokon vagy közvetlen formázáson alapulnak ebből nem látható.

Az Apache OpenOffice Basic rendelkezik egy getPropertyState metódussal, amellyel a programozó meg tudja állapítani, egy adott tulajdonság hogyan van formázva. A metódusnak paraméterként a tulajdonság nevét kell megadni, és visszaad egy állandót, amely információt nyújt a formázás eredetéről. A következő, com.sun.star.beans.PropertyState enumerációjában megadott visszatérési értékek lehetségesek:

com.sun.star.beans.PropertyState.DIRECT_VALUE
a tulajdonság közvetlenül a szövegben van megadva (közvetlen formázás);
com.sun.star.beans.PropertyState.DEFAULT_VALUE
a tulajdonságot egy sablon formázza (közvetett formázás);
com.sun.star.beans.PropertyState.AMBIGUOUS_VALUE
a tulajdonság formázása nem egyértelmű. Ez akkor lehetséges, ha például beolvassuk egy bekezdés félkövér-tulajdonságát, amely félkövér és normál szavakat is tartalmaz.

A következő példa bemutatja, hogyan szerkeszthetők a formázási tulajdonságok az Apache OpenOffice programban. A program megkeresi a szövegben a félkövérként megjelenő bekezdésrészleteket, amelyeket közvetlen formázással formáztak. Ha talál ilyen bekezdésrészletet, akkor törli a közvetlen formázást a setPropertyToDefault metódussal, és hozzárendeli a Félkövér karaktersablont az adott bekezdésrészhez.

Dim Doc As Object   
Dim Enum1 As Object
Dim Enum2 As Object
Dim TextElement As Object
Dim TextPortion As Object
 
Doc = StarDesktop.CurrentComponent
Enum1 = Doc.Text.createEnumeration
 
' a ciklus végiglépdel az összes bekezdésen
While Enum1.hasMoreElements
  TextElement = Enum1.nextElement
 
  If TextElement.supportsService("com.sun.star.text.Paragraph") Then
    Enum2 = TextElement.createEnumeration
    ' a ciklus végiglépdel az összes bekezdésrészen
 
    While Enum2.hasMoreElements
      TextPortion = Enum2.nextElement
 
      If TextPortion.CharWeight = _
        com.sun.star.awt.FontWeight.BOLD AND _
        TextPortion.getPropertyState("CharWeight") = _
        com.sun.star.beans.PropertyState.DIRECT_VALUE Then
          TextPortion.setPropertyToDefault("CharWeight")
          TextPortion.CharStyleName = "Félkövér" 
      End If
    Wend
  End If
Wend


Content on this page is licensed under the Public Documentation License (PDL).
Personal tools