Difference between revisions of "NL/Documentation/BASIC Guide/Structure of Text Documents"
(Created page with "{{NL/Documentation/BASICGuideTOC/v2 |ShowPrevNext=block |ShowPrevPage=block |PrevPage=NL/Documentation/BASIC Guide/Text Documents |NextPage=NL/Documentation/BASIC Guide/Editin...") |
(→Alinea's en gedeelten van alinea's) |
||
Line 18: | Line 18: | ||
== Alinea's en gedeelten van alinea's == | == Alinea's en gedeelten van alinea's == | ||
− | + | De kern van een tekstdocument bestaat uit een reeks van alinea's. Deze worden niet benoemd, noch geïndexeerd en er is daarom geen mogelijke manier van directe toegang tot individuele alinea's. De alinea's kunnen echter reeksmatig worden benaderd met behulp van het object <tt>Enumeration</tt>, beschreven in [[Documentation/BASIC Guide/API Intro|Introductie voor de API]]. Dit maakt het mogelijk dat de alinea's kunnen worden bewerkt. | |
− | + | Bij het werken met het object <tt>Enumeration</tt>, moet echter met één speciaal scenario, rekening worden gehouden: het geeft niet alleen alinea's weer, maar ook tabellen (strikt gesproken is, in {{OOo}} Writer, een tabel een speciaal type alinea). Voordat u toegang zoekt tot een weergegeven object, zou u daarom moeten controleren of het weergegeven object de service <idl>com.sun.star.text.Paragraph</idl> voor alinea's of de service <idl>com.sun.star.text.TextTable</idl> voor tabellen ondersteunt. | |
− | + | Het volgende voorbeeld gaat, in een lus, door de inhoud van een tekst en gebruikt voor elk item een bericht om de gebruiker te informeren of het betreffende object een alinea of een tabel is. | |
<source lang="oobas"> | <source lang="oobas"> | ||
Dim Doc As Object | Dim Doc As Object | ||
Dim Enum As Object | Dim Enum As Object | ||
− | Dim | + | Dim TekstElement As Object |
− | ' | + | ' Maak het documentobject |
Doc = ThisComponent | Doc = ThisComponent | ||
− | ' | + | ' Maak het object voor de nummering |
Enum = Doc.Text.createEnumeration | Enum = Doc.Text.createEnumeration | ||
− | ' | + | ' lus door alle tekstelementen |
While Enum.hasMoreElements | While Enum.hasMoreElements | ||
− | + | TekstElement = Enum.nextElement | |
− | If | + | If TekstElement.supportsService("com.sun.star.text.TextTable") Then |
− | MsgBox " | + | MsgBox "Het huidige blok bevat een tabel." |
End If | End If | ||
− | If | + | If TekstElement.supportsService("com.sun.star.text.Paragraph") Then |
− | MsgBox " | + | MsgBox "Het huidige blok bevat een alinea." |
End If | End If | ||
Line 49: | Line 49: | ||
</source> | </source> | ||
− | + | Het voorbeeld maakt een documentobject <tt>Doc</tt> dat verwijst naar het huidige document van {{OOo}}. Met de hulp van <tt>Doc</tt> maakt het voorbeeld dan een object <tt>Enumeration</tt> aan dat door de individuele gedeelten van de tekst (alinea's en tabellen) gaat en aan het huidige element het object <tt>TekstElement</tt> toewijst. Het voorbeeld gebruikt de methode <tt>supportsService</tt> om te controleren of het <tt>TekstElement</tt> een alinea of een tabel is. | |
− | === | + | === Alinea's === |
− | + | De service <idl>com.sun.star.text.Paragraph</idl> geeft toegang tot de inhoud van een alinea. De tekst in de alinea kan worden gevonden en gewijzigd met behulp van de eigenschap String: | |
<source lang="oobas"> | <source lang="oobas"> | ||
Dim Doc As Object | Dim Doc As Object | ||
Dim Enum As Object | Dim Enum As Object | ||
− | Dim | + | Dim TekstElement As Object |
Doc = ThisComponent | Doc = ThisComponent | ||
Line 64: | Line 64: | ||
While Enum.hasMoreElements | While Enum.hasMoreElements | ||
− | + | TekstElement = Enum.nextElement | |
− | If | + | If TekstElement.supportsService("com.sun.star.text.Paragraph") Then |
− | + | TekstElement.String = Replace(TextElement.String, "you", "U") | |
− | + | TekstElement.String = Replace(TextElement.String, "twee", "2") | |
− | + | TekstElement.String = Replace(TextElement.String, "vier", "4") | |
End If | End If | ||
Line 75: | Line 75: | ||
</source> | </source> | ||
− | + | Het voorbeeld opent het huidige tekstdocument en gaat daar doorheen met behulp van het object Enumeration. Het gebruikt de eigenschap <tt>TextElement.String</tt> in alle alinea's om toegang te krijgen tot de relevante alinea's en vervangt de tekenreeksen <tt>you, twee en vier</tt> door de tekens <tt>U, 2 en 4</tt>. | |
+ | De functie <tt>Replace</tt>, die wordt gebruikt voor de vervangingen, valt niet binnen het standaard-taalkundig bereik van {{OOo}} BASIC. Dit is een item van de voorbeeldfunctie, die wordt beschreven in [[NL/Documentation/BASIC Guide/Strings_%28Runtime_Library%29|Zoeken en evrvangen]]. | ||
− | {{Documentation/VBAnote| | + | {{Documentation/VBAnote|De inhoud van de hier beschreven procedure voor toegang tot de alinea's van een tekst is vergelijkbaar met de opsomming Paragraphs, gebruikt in VBA, die wordt verschaft in de daar beschikbare objecten <tt>Range</tt> en <tt>Document</tt>. Waar in VBA de toegang tot de alinea's wordt verkregen via hun nummer (bijvoorbeeld, bij de aanroep Paragraph(1)), zou in {{OOo}} BASIC het hiervoor beschreven object <tt>Enumeration</tt> moeten worden gebruikt.}} |
− | + | Er zijn geen identieke objecten in {{OOo}} BASIC voor de opsommingen <tt>Characters, Sentences</tt> en <tt>Words</tt> zoals die voorkomen in VBA. U heeft echter de optie om over te schakelen naar een <tt>TextCursor</tt> welke het u mogelijk maakt om te navigeren op het niveau van tekens, zinnen en woorden. | |
− | === | + | === Gedeelten van alinea's === |
− | + | Het vorige voorbeeld kan de tekst veranderen zoals gewenst, maar het kan soms ook de opmaak vernielen. | |
− | + | Dit komt omdat een alinea op zijn beurt uit individuele subobjecten bestaat. Elk van deze subobjecten bevat zijn eigen opmaak-informatie. Als het centrum van een alinea, bijvoorbeeld, een woord bevat dat is afgedrukt in vet, dan wordt het in {{OOo}} weergegeven door drie gedeelten van een alinea: het gedeelte vóór het type vet, het vette woord en tenslotte het gedeelte achter het type vet, dat normaal wordt weergegeven. | |
− | + | Als de tekst van de alinea nu wordt veranderd met de eigenschap <tt>String</tt>, dan verwijdert {{OOo}} eerst de oude gedeelten van de alinea en voegt nieuwe gedeelten voor een alinea in. De opmaak van de vorige gedeelten gaat dan verloren. | |
− | + | Om dit effect te voorkomen, kan de gebruiker beter toegang zoeken tot de de geassocieerde alinea-gedeelten, in plaats van tot de gehele alinea. Alinea's verschaffen voor dit doel hun eigen object <tt>Enumeration</tt>. Het volgende voorbeeld toont een dubbele lus die door alle alinea's van een tekstdocument gaat en de alinea-gedeelten die zij bevatten en past het vervangings-proces uit het voorgaande voorbeeld daar op toe: | |
<source lang="oobas"> | <source lang="oobas"> | ||
Line 95: | Line 96: | ||
Dim Enum1 As Object | Dim Enum1 As Object | ||
Dim Enum2 As Object | Dim Enum2 As Object | ||
− | Dim | + | Dim TekstElement As Object |
− | Dim | + | Dim TekstDeel As Object |
Doc = ThisComponent | Doc = ThisComponent | ||
Enum1 = Doc.Text.createEnumeration | Enum1 = Doc.Text.createEnumeration | ||
− | ' | + | ' ga door alle alinea's |
While Enum1.hasMoreElements | While Enum1.hasMoreElements | ||
− | + | TekstElement = Enum1.nextElement | |
− | If | + | If TekstElement.supportsService("com.sun.star.text.Paragraph") Then |
− | Enum2 = | + | Enum2 = TekstElement.createEnumeration |
− | ' | + | ' ga door alle gedeelten van alinea's |
While Enum2.hasMoreElements | While Enum2.hasMoreElements | ||
− | + | TekstDeel = Enum2.nextElement | |
− | MsgBox "'" & | + | MsgBox "'" & TekstDeel.String & "'" |
− | + | TekstDeel.String = Replace(TekstDeel.String, "you", "U") | |
− | + | TekstDeel.String = Replace(TekstDeel.String, "twee", "2") | |
− | + | TekstDeel.String = Replace(TekstDeel.String, "vier", "4") | |
Wend | Wend | ||
Line 121: | Line 122: | ||
</source> | </source> | ||
− | + | Het voorbeeld gaat door een tekstdocument in een dubbele lus. De buitenste lus refereert aan de alinea's van de tekst. De binnenste lus verwerkt de gedeelten van de alinea's in de alinea's. De voorbeeld-code wijzigt de inhoud in elk van deze gedeelten van alinea's met behulp van de eigenschap <tt>String</tt> van de tekenreeks, zoals het geval is in het voorgaande voorbeeld voor alinea's. Omdat echter de gedeelten van de alinea's direct worden bewerkt, blijft hun informatie voor de opmaak behouden bij het vervangen van de tekenreeks. | |
=== Formatting === | === Formatting === |
Revision as of 13:36, 9 February 2013
- De structuur van tekstdocumenten
- Tekstdocumenten bewerken
- Meer dan alleen tekst
Een tekstdocument kan in principe vier typen van informatie bevatten:
- De eigenlijke tekst
- Sjablonen voor opmaak van tekens, alinea's en pagina's
- Niet-tekstelementen zoals tabellen, afbeeldingen en teken-objecten
- Globale instellingen voor het tekstdocument
Dit gedeelte richt zich speciaal op de tekst en de daarbij behorende opties voor opmaak.
Contents
Alinea's en gedeelten van alinea's
De kern van een tekstdocument bestaat uit een reeks van alinea's. Deze worden niet benoemd, noch geïndexeerd en er is daarom geen mogelijke manier van directe toegang tot individuele alinea's. De alinea's kunnen echter reeksmatig worden benaderd met behulp van het object Enumeration, beschreven in Introductie voor de API. Dit maakt het mogelijk dat de alinea's kunnen worden bewerkt.
Bij het werken met het object Enumeration, moet echter met één speciaal scenario, rekening worden gehouden: het geeft niet alleen alinea's weer, maar ook tabellen (strikt gesproken is, in Apache OpenOffice Writer, een tabel een speciaal type alinea). Voordat u toegang zoekt tot een weergegeven object, zou u daarom moeten controleren of het weergegeven object de service com.sun.star.text.Paragraph voor alinea's of de service com.sun.star.text.TextTable voor tabellen ondersteunt.
Het volgende voorbeeld gaat, in een lus, door de inhoud van een tekst en gebruikt voor elk item een bericht om de gebruiker te informeren of het betreffende object een alinea of een tabel is.
Dim Doc As Object Dim Enum As Object Dim TekstElement As Object ' Maak het documentobject Doc = ThisComponent ' Maak het object voor de nummering Enum = Doc.Text.createEnumeration ' lus door alle tekstelementen While Enum.hasMoreElements TekstElement = Enum.nextElement If TekstElement.supportsService("com.sun.star.text.TextTable") Then MsgBox "Het huidige blok bevat een tabel." End If If TekstElement.supportsService("com.sun.star.text.Paragraph") Then MsgBox "Het huidige blok bevat een alinea." End If Wend
Het voorbeeld maakt een documentobject Doc dat verwijst naar het huidige document van Apache OpenOffice. Met de hulp van Doc maakt het voorbeeld dan een object Enumeration aan dat door de individuele gedeelten van de tekst (alinea's en tabellen) gaat en aan het huidige element het object TekstElement toewijst. Het voorbeeld gebruikt de methode supportsService om te controleren of het TekstElement een alinea of een tabel is.
Alinea's
De service com.sun.star.text.Paragraph geeft toegang tot de inhoud van een alinea. De tekst in de alinea kan worden gevonden en gewijzigd met behulp van de eigenschap String:
Dim Doc As Object Dim Enum As Object Dim TekstElement As Object Doc = ThisComponent Enum = Doc.Text.createEnumeration While Enum.hasMoreElements TekstElement = Enum.nextElement If TekstElement.supportsService("com.sun.star.text.Paragraph") Then TekstElement.String = Replace(TextElement.String, "you", "U") TekstElement.String = Replace(TextElement.String, "twee", "2") TekstElement.String = Replace(TextElement.String, "vier", "4") End If Wend
Het voorbeeld opent het huidige tekstdocument en gaat daar doorheen met behulp van het object Enumeration. Het gebruikt de eigenschap TextElement.String in alle alinea's om toegang te krijgen tot de relevante alinea's en vervangt de tekenreeksen you, twee en vier door de tekens U, 2 en 4. De functie Replace, die wordt gebruikt voor de vervangingen, valt niet binnen het standaard-taalkundig bereik van Apache OpenOffice BASIC. Dit is een item van de voorbeeldfunctie, die wordt beschreven in Zoeken en evrvangen.
Er zijn geen identieke objecten in Apache OpenOffice BASIC voor de opsommingen Characters, Sentences en Words zoals die voorkomen in VBA. U heeft echter de optie om over te schakelen naar een TextCursor welke het u mogelijk maakt om te navigeren op het niveau van tekens, zinnen en woorden.
Gedeelten van alinea's
Het vorige voorbeeld kan de tekst veranderen zoals gewenst, maar het kan soms ook de opmaak vernielen.
Dit komt omdat een alinea op zijn beurt uit individuele subobjecten bestaat. Elk van deze subobjecten bevat zijn eigen opmaak-informatie. Als het centrum van een alinea, bijvoorbeeld, een woord bevat dat is afgedrukt in vet, dan wordt het in Apache OpenOffice weergegeven door drie gedeelten van een alinea: het gedeelte vóór het type vet, het vette woord en tenslotte het gedeelte achter het type vet, dat normaal wordt weergegeven.
Als de tekst van de alinea nu wordt veranderd met de eigenschap String, dan verwijdert Apache OpenOffice eerst de oude gedeelten van de alinea en voegt nieuwe gedeelten voor een alinea in. De opmaak van de vorige gedeelten gaat dan verloren.
Om dit effect te voorkomen, kan de gebruiker beter toegang zoeken tot de de geassocieerde alinea-gedeelten, in plaats van tot de gehele alinea. Alinea's verschaffen voor dit doel hun eigen object Enumeration. Het volgende voorbeeld toont een dubbele lus die door alle alinea's van een tekstdocument gaat en de alinea-gedeelten die zij bevatten en past het vervangings-proces uit het voorgaande voorbeeld daar op toe:
Dim Doc As Object Dim Enum1 As Object Dim Enum2 As Object Dim TekstElement As Object Dim TekstDeel As Object Doc = ThisComponent Enum1 = Doc.Text.createEnumeration ' ga door alle alinea's While Enum1.hasMoreElements TekstElement = Enum1.nextElement If TekstElement.supportsService("com.sun.star.text.Paragraph") Then Enum2 = TekstElement.createEnumeration ' ga door alle gedeelten van alinea's While Enum2.hasMoreElements TekstDeel = Enum2.nextElement MsgBox "'" & TekstDeel.String & "'" TekstDeel.String = Replace(TekstDeel.String, "you", "U") TekstDeel.String = Replace(TekstDeel.String, "twee", "2") TekstDeel.String = Replace(TekstDeel.String, "vier", "4") Wend End If Wend
Het voorbeeld gaat door een tekstdocument in een dubbele lus. De buitenste lus refereert aan de alinea's van de tekst. De binnenste lus verwerkt de gedeelten van de alinea's in de alinea's. De voorbeeld-code wijzigt de inhoud in elk van deze gedeelten van alinea's met behulp van de eigenschap String van de tekenreeks, zoals het geval is in het voorgaande voorbeeld voor alinea's. Omdat echter de gedeelten van de alinea's direct worden bewerkt, blijft hun informatie voor de opmaak behouden bij het vervangen van de tekenreeks.
Formatting
There are various ways of formatting text. The easiest way is to assign the format properties directly to the text sequence. This is called direct formatting. Direct formatting is used in particular with short documents because the formats can be assigned by the user with the mouse. You can, for example, highlight a certain word within a text using bold type or center a line.
In addition to direct formatting, you can also format text using templates. This is called indirect formatting. With indirect formatting, the user assigns a pre-defined template to the relevant text portion. If the layout of the text is changed at a later date, the user only needs to change the template. Apache OpenOffice then changes the way in which all text portions which use this template are depicted.
Character Properties
Those format properties that refer to individual characters are described as character properties. These include bold type and the font type. Objects that allow character properties to be set have to support the com.sun.star.style.CharacterProperties service. Apache OpenOffice recognizes a whole range of services that support this service. These include the previously described com.sun.star.text.Paragraph services for paragraphs as well as the com.sun.star.text.TextPortion services for paragraph portions.
The com.sun.star.style.CharacterProperties service does not provide any interfaces, but instead offers a range of properties through which character properties can be defined and called. A complete list of all character properties can be found in the Apache OpenOffice API reference. The following list describes the most important properties:
- CharFontName (String)
- name of font type selected.
- CharColor (Long)
- text color.
- CharHeight (Float)
- character height in points (pt).
- CharUnderline (Constant group)
- type of underscore (constants in accordance with com.sun.star.awt.FontUnderline ).
- CharWeight (Constant group)
- font weight (constants in accordance with com.sun.star.awt.FontWeight).
- CharBackColor (Long)
- background color.
- CharKeepTogether (Boolean)
- suppression of automatic line break.
- CharStyleName (String)
- name of character template.
Paragraph Properties
Formatting information that does not refer to individual characters, but to the entire paragraph is considered to be a paragraph property. This includes the distance of the paragraph from the edge of the page as well as line spacing. The paragraph properties are available through the com.sun.star.style.ParagraphProperties service.
Even the paragraph properties are available in various objects. All objects that support the com.sun.star.text.Paragraph service also provide support for the paragraph properties in com.sun.star.style.ParagraphProperties.
A complete list of the paragraph properties can be found in the Apache OpenOffice API reference. The most common paragraph properties are:
- ParaAdjust (enum)
- vertical text orientation (constants in accordance with com.sun.star.style.ParagraphAdjust ).
- ParaLineSpacing (struct)
- line spacing (structure in accordance with com.sun.star.style.LineSpacing).
- ParaBackColor (Long)
- background color.
- ParaLeftMargin (Long)
- left margin in 100ths of a millimeter.
- ParaRightMargin (Long)
- right margin in 100ths of a millimeter.
- ParaTopMargin (Long)
- top margin in 100ths of a millimeter.
- ParaBottomMargin (Long)
- bottom margin in 100ths of a millimeter.
- ParaTabStops (Array of struct)
- type and position of tabs (array with structures of the type com.sun.star.style.TabStop ).
- ParaStyleName (String)
- name of the paragraph template.
Example: simple HTML export
The following example demonstrates how to work with formatting information. It iterates through a text document and creates a simple HTML file. Each paragraph is recorded in its own HTML element <P> for this purpose. Paragraph portions displayed in bold type are marked using a <B> HTML element when exporting.
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 = ThisComponent Enum1 = Doc.Text.createEnumeration ' loop over all paragraphs While Enum1.hasMoreElements TextElement = Enum1.nextElement If TextElement.supportsService("com.sun.star.text.Paragraph") Then Enum2 = TextElement.createEnumeration CurLine = "<P>" ' loop over all paragraph portions 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 ' output the line CurLine = CurLine & "</P>" Print #FileNo, CurLine End If Wend ' write HTML footer Print #FileNo, "</BODY></HTML>" Close #FileNo
The basic structure of the example is oriented towards the examples for running though the paragraph portions of a text already discussed previously. The functions for writing the HTML file, as well as a test code that checks the font weight of the corresponding text portions and provides paragraph portions in bold type with a corresponding HTML tag, have been added.
Default values for character and paragraph properties
Direct formatting always takes priority over indirect formatting. In other words, formatting using templates is assigned a lower priority than direct formatting in a text.
Establishing whether a section of a document has been directly or indirectly formatted is not easy. The symbol bars provided by Apache OpenOffice show the common text properties such as font type, weight and size. However, whether the corresponding settings are based on template or direct formatting in the text is still unclear.
Apache OpenOffice Basic provides the getPropertyState method, with which programmers can check how a certain property was formatted. As a parameter, this takes the name of the property and returns a constant that provides information about the origin of the formatting. The following responses, which are defined in the com.sun.star.beans.PropertyState enumeration, are possible:
- com.sun.star.beans.PropertyState.DIRECT_VALUE
- the property is defined directly in the text (direct formatting)
- com.sun.star.beans.PropertyState.DEFAULT_VALUE
- the property is defined by a template (indirect formatting)
- com.sun.star.beans.PropertyState.AMBIGUOUS_VALUE
- the property is unclear. This status arises, for example, when querying the bold type property of a paragraph, which includes both words depicted in bold and words depicted in normal font.
The following example shows how format properties can be edited in Apache OpenOffice. It searches through a text for paragraph portions which have been depicted as bold type using direct formatting. If it encounters a corresponding paragraph portion, it deletes the direct formatting using the setPropertyToDefault method and assigns a MyBold character template to the corresponding paragraph portion.
Dim Doc As Object Dim Enum1 As Object Dim Enum2 As Object Dim TextElement As Object Dim TextPortion As Object Doc = ThisComponent Enum1 = Doc.Text.createEnumeration ' loop over all paragraphs While Enum1.hasMoreElements TextElement = Enum1.nextElement If TextElement.supportsService("com.sun.star.text.Paragraph") Then Enum2 = TextElement.createEnumeration ' loop over all paragraph portions 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 = "MyBold" End If Wend End If Wend
Content on this page is licensed under the Public Documentation License (PDL). |