Apache OpenOffice Wiki - User contributions [en]

Documentation/BASIC Guide/Editing Text Documents

2010-01-17T11:33:13Z

Andrewb: /* Navigating within a Text */ whitespace defnition improved. Thanks to TJ Frazier

{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Structure of Text Documents
|NextPage=Documentation/BASIC Guide/More Than Text
|textdocs=block
}}
{{DISPLAYTITLE:Editing Text Documents}}
__NOTOC__
The previous section has already discussed a whole range of options for editing text documents, focusing on the <idl>com.sun.star.text.TextPortion</idl> and <idl>com.sun.star.text.Paragraph</idl> services, which grant access to paragraph portions as well as paragraphs. These services are appropriate for applications in which the content of a text is to be edited in one pass through a loop. However, this is not sufficient for many problems. {{OOo}} provides the <idl>com.sun.star.text.TextCursor</idl> service for more complicated tasks, including navigating backward within a document or navigating based on sentences and words rather than <tt>TextPortions</tt>.

== The TextCursor ==

A <tt>TextCursor</tt> in the {{OOo}} API is comparable with the visible cursor used in a {{OOo}} document. It marks a certain point within a text document and can be navigated in various directions through the use of commands. The <tt>TextCursor</tt> objects available in {{OOo}} Basic should not, however, be confused with the visible cursor. These are two very different things.

{{Documentation/VBAnote|Terminology differs from that used in VBA: In terms of scope of function, the Range object from VBA can be compared with the TextCursor object in {{OOo}} and not — as the name possibly suggests — with the Range object in {{OOo}}.}}

The TextCursor object in {{OOo}}, for example, provides methods for navigating and changing text which are included in the Range object in VBA (for example, MoveStart, MoveEnd, InsertBefore, InsertAfter). The corresponding counterparts of the TextCursor object in {{OOo}} are described in the following sections.

=== Navigating within a Text ===

The <tt>TextCursor</tt> object in {{OOo}} Basic acts independently from the visible cursor in a text document. A program-controlled position change of a <tt>TextCursor</tt> object has no impact whatsoever on the visible cursor. Several <tt>TextCursor</tt> objects can even be opened for the same document and used in various positions, which are independent of one another.

A <tt>TextCursor</tt> object is created using the <tt>createTextCursor</tt> call:

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor()
</source>

The Cursor object created in this way supports the <tt>com.sun.star.text.TextCursor</tt> service, which in turn provides a whole range of methods for navigating within text documents. The following example first moves the <tt>TextCursor</tt> ten characters to the left and then three characters to the right:

<source lang="oobas">Cursor.goLeft(10, False)
Cursor.goRight(3, False)</source>

A <tt>TextCursor</tt> can highlight a complete area. This can be compared with highlighting a point in the text using the mouse. The <tt>False</tt> parameter in the previous function call specifies whether the area passed over with the cursor movement is highlighted. For example, the <tt>TextCursor</tt> in the following example

<source lang="oobas">
Cursor.goRight(10, False)
Cursor.goLeft(3, True)
</source>

first moves ten characters to the right without highlighting, and then moves back three characters and highlights this. The area highlighted by the <tt>TextCursor</tt> therefore begins after the seventh character in the text and ends after the tenth character.

Here are the central methods that the <idl>com.sun.star.text.TextCursor</idl> service provides for navigation:

;<tt>goLeft (Count, Expand)</tt>
:jumps Count characters to the left.
;<tt>goRight (Count, Expand)</tt>
:jumps Count characters to the right.
;<tt>gotoStart (Expand)</tt>
:jumps to the start of the text document.
;<tt>gotoEnd (Expand)</tt>
:jumps to the end of the text document.
;<tt>gotoRange (TextRange, Expand)</tt>
:jumps to the specified <tt>TextRange</tt>-Object.
;<tt>gotoStartOfWord (Expand)</tt>
:jumps to the start of the current word.
;<tt>gotoEndOfWord (Expand)</tt>
:jumps to the end of the current word.
;<tt>gotoNextWord (Expand)</tt>
:jumps to the start of the next word.
;<tt>gotoPreviousWord (Expand)</tt>
:jumps to the start of the previous word.
;<tt>isStartOfWord ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the start of a word.
;<tt>isEndOfWord ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the end of a word.
;<tt>gotoStartOfSentence (Expand)</tt>
:jumps to the start of the current sentence.
;<tt>gotoEndOfSentence (Expand)</tt>
:jumps to the end of the current sentence.
;<tt>gotoNextSentence (Expand)</tt>
:jumps to the start of the next sentence.
;<tt>gotoPreviousSentence (Expand)</tt>
:jumps to the start of the previous sentence.
;<tt>isStartOfSentence ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the start of a sentence.
;<tt>isEndOfSentence ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the end of a sentence.
;<tt>gotoStartOfParagraph (Expand)</tt>
:jumps to the start of the current paragraph.
;<tt>gotoEndOfParagraph (Expand)</tt>
:jumps to the end of the current paragraph.
;<tt>gotoNextParagraph (Expand)</tt>
:jumps to the start of the next paragraph.
;<tt>gotoPreviousParagraph (Expand)</tt>
:jumps to the start of the previous paragraph.
;<tt>isStartOfParagraph ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the start of a paragraph.
;<tt>isEndOfParagraph ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the end of a paragraph.

The text is divided into sentences on the basis of sentence symbols. Periods are, for example, interpreted as symbols indicating the end of sentences. (In English, at least, they must be followed by a space, tab, or return for this to work.)

The <tt>Expand</tt> parameter is a Boolean value which specifies whether the area passed over during navigation is to be highlighted. All navigation methods furthermore return a Boolean parameter which specifies whether the navigation was successful or whether the action was terminated for lack of text.

The following is a list of several methods for editing highlighted areas using a <tt>TextCursor</tt> and which also support the <idl>com.sun.star.text.TextCursor</idl> service:

;<tt>collapseToStart ()</tt>
:resets the highlighting and positions the <tt>TextCursor</tt> at the start of the previously highlighted area.
;<tt>collapseToEnd ()</tt>
:resets the highlighting and positions the <tt>TextCursor</tt> at the end of the previously highlighted area.
;<tt>isCollapsed ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> does not cover any highlighting at present.

=== Formatting Text with TextCursor ===

The <idl>com.sun.star.text.TextCursor</idl> service supports all the character and paragraph properties that were presented at the start of this chapter.

The following example shows how these can be used in conjunction with a <tt>TextCursor</tt>. It passes through a complete document and formats the first word of every sentence in bold type.

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor

Do
Cursor.gotoEndOfWord(True)
Cursor.CharWeight = com.sun.star.awt.FontWeight.BOLD
Proceed = Cursor.gotoNextSentence(False)
Cursor.gotoNextWord(False)
Loop While Proceed
</source>

The example first creates a document object for the text that has just been opened. Then it iterates through the entire text, sentence by sentence, and highlights each of the first words and formats this in bold.

=== Retrieving and Modifying Text Contents ===

If a <tt>TextCursor</tt> contains a highlighted area, then this text is available by means of the <tt>String</tt> property of the <tt>TextCursor</tt> object. The following example uses the <tt>String</tt> property to display the first words of a sentence in a message box:

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor

Do
Cursor.gotoEndOfWord(True)
MsgBox Cursor.String
Proceed = Cursor.gotoNextSentence(False)
Cursor.gotoNextWord(False)
Loop While Proceed
</source>

The first word of each sentence can be modified in the same way using the <tt>String</tt> property:

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor

Do
Cursor.gotoEndOfWord(True)
Cursor.String = "Ups"
Proceed = Cursor.gotoNextSentence(False)
Cursor.gotoNextWord(False)
Loop While Proceed
</source>

If the <tt>TextCursor</tt> contains a highlighted area, an assignment to the <tt>String</tt> property replaces this with the new text. If there is no highlighted area, the text is inserted at the present <tt>TextCursor</tt> position.

=== Inserting Control Codes ===

In some situations, it is not the actual text of a document, but rather its structure that needs modifying. {{OOo}} provides control codes for this purpose. These are inserted in the text and influence its structure. The control codes are defined in the <idl>com.sun.star.text.ControlCharacter</idl> group of constants. The following control codes are available in {{OOo}}:

;<tt>PARAGRAPH_BREAK</tt>:paragraph break.
;<tt>LINE_BREAK</tt>:line break within a paragraph.
;<tt>SOFT_HYPHEN</tt>:possible point for syllabification.
;<tt>HARD_HYPHEN</tt>:obligatory point for syllabification.
;<tt>HARD_SPACE</tt>:protected space that is not spread out or compressed in justified text.

To insert the control codes, you need not only the cursor but also the associated text document objects. The following example inserts a paragraph after the 20th character of a text:

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor
Cursor.goRight(20, False)
Doc.Text.insertControlCharacter(Cursor, _
com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False)
</source>

The <tt>False</tt> parameter in the call of the <tt>insertControlCharacter</tt> method ensures that the area currently highlighted by the <tt>TextCursor</tt> remains after the insert operation. If the <tt>True</tt> parameter is passed here, then <tt>insertControlCharacter</tt> replaces the current text.

== Searching for Text Portions ==

In many instances, it is the case that a text is to be searched for a particular term and the corresponding point needs to be edited. All {{OOo}} documents provide a special interface for this purpose, and this interface always functions in accordance with the same principle: Before a search process, what is commonly referred to as a <tt>SearchDescriptor</tt> must first be created. This defines what {{OOo}} searches for in a document. A <tt>SearchDescriptor</tt> is an object which supports the <tt>com.sun.star.util.</tt> <tt>SearchDescriptor</tt> service and can be created by means of the <tt>createSearchDescriptor</tt> method of a document:

<source lang="oobas">
Dim SearchDesc As Object
SearchDesc = Doc.createSearchDescriptor
</source>

Once the <tt>SearchDescriptor</tt> has been created, it receives the text to be searched for:

<source lang="oobas">
SearchDesc.searchString="any text"
</source>

In terms of its function, the <tt>SearchDescriptor</tt> is best compared with the search dialog from {{OOo}}. In a similar way to the search window, the settings needed for a search can be set in the <tt>SearchDescriptor</tt> object.

The properties are provided by the <idl>com.sun.star.util.SearchDescriptor</idl> service:

;<tt>SearchBackwards (Boolean)</tt>:searches through the text backward rather than forward.
;<tt>SearchCaseSensitive (Boolean)</tt>:takes uppercase and lowercase characters into consideration during the search.
;<tt>SearchRegularExpression (Boolean)</tt>:treats the search expression like a regular expression.
;<tt>SearchStyles (Boolean)</tt>:searches through the text for the specified paragraph template.
;<tt>SearchWords (Boolean)</tt>:only searches for complete words.

The {{OOo}} <tt>SearchSimilarity</tt> (or “fuzzy match”) function is also available in {{OOo}} Basic. With this function, {{OOo}} searches for an expression that may be similar to but not exactly the same as the search expression. The number of additional, deleted and modified characters for these expressions can be defined individually. Here are the associated properties of the <tt>com.sun.star.util.SearchDescriptor</tt> service:

;<tt>SearchSimilarity (Boolean)</tt>:performs a similarity search.
;<tt>SearchSimilarityAdd (Short)</tt>:number of characters which may be added for a similarity search.
;<tt>SearchSimilarityExchange (Short)</tt>:number of characters which may be replaced as part of a similarity search.
;<tt>SearchSimilarityRemove (Short)</tt>:number of characters which may be removed as part of a similarity search.
;<tt>SearchSimilarityRelax (Boolean)</tt>:takes all deviation rules into consideration at the same time for the search expression.

Once the <tt>SearchDescriptor</tt> has been prepared as requested, it can be applied to the text document. The {{OOo}} documents provide the <tt>findFirst</tt> and <tt>findNext</tt> methods for this purpose:

<source lang="oobas">
Found = Doc.findFirst (SearchDesc)

Do Until IsNull(Found)
' Edit search results...
Found = Doc.findNext( Found.End, SearchDesc)
Loop
</source>

The example finds all matches in a loop and returns a <tt>TextRange</tt> object, which refers to the found text passage.

=== Example: Similarity Search ===

This example shows how a text can be searched for the word "turnover" and the results formatted in bold type. A similarity search is used so that not only the word “turnover”, but also the plural form "turnovers" and declinations such as "turnover's" are found. The found expressions differ by up to two letters from the search expression:

<source lang="oobas">
Dim SearchDesc As Object
Dim Doc As Object

Doc = ThisComponent
SearchDesc = Doc.createSearchDescriptor
SearchDesc.SearchString="turnover"
SearchDesc.SearchSimilarity = True
SearchDesc.SearchSimilarityAdd = 2
SearchDesc.SearchSimilarityExchange = 2
SearchDesc.SearchSimilarityRemove = 2
SearchDesc.SearchSimilarityRelax = False
Found = Doc.findFirst (SearchDesc)

Do Until IsNull(Found)
Found.CharWeight = com.sun.star.awt.FontWeight.BOLD
Found = Doc.findNext( Found.End, SearchDesc)
Loop
</source>

{{Documentation/VBAnote|The basic idea of search and replace in {{OOo}} is comparable to that used in VBA. Both interfaces provide you with an object, through which the properties for searching and replacing can be defined. This object is then applied to the required text area in order to perform the action. Whereas the responsible auxiliary object in VBA can be reached through the Find property of the Range object, in {{OOo}} Basic it is created by the <tt>createSearchDescriptor</tt> or <tt>createReplaceDescriptor</tt> call of the document object. Even the search properties and methods available differ.}}

As in the old API from {{OOo}}, searching and replacing text in the new API is also performed using the document object. Whereas previously there was an object called <tt>SearchSettings</tt> especially for defining the search options, in the new object searches are now performed using a <tt>SearchDescriptor</tt> or <tt>ReplaceDescriptor</tt> object for automatically replacing text. These objects cover not only the options, but also the current search text and, if necessary, the associated text replacement. The descriptor objects are created using the document object, completed in accordance with the relevant requests, and then transferred back to the document object as parameters for the search methods.

== Replacing Text Portions ==

Just as with the search function, the replacement function from {{OOo}} is also available in {{OOo}} Basic. The two functions are handled identically. A special object which records the parameters for the process is also first needed for a replacement process. It is called a <tt>ReplaceDescriptor</tt> and supports the <idl>com.sun.star.util.ReplaceDescriptor</idl> service. All the properties of the <tt>SearchDescriptor</tt> described in the previous paragraph are also supported by <tt>ReplaceDescriptor.</tt> For example, during a replacement process, case sensitivity can also be activated and deactivated, and similarity searches can be performed.

The following example demonstrates the use of <tt>ReplaceDescriptors</tt> for a search within a {{OOo}} document.

<source lang="oobas">
Dim I As Long
Dim Doc As Object
Dim Replace As Object
Dim BritishWords(5) As String
Dim USWords(5) As String

BritishWords() = Array("colour", "neighbour", "centre", "behaviour", _
"metre", "through")
USWords() = Array("color", "neighbor", "center", "behavior", _
"meter", "thru")

Doc = ThisComponent
Replace = Doc.createReplaceDescriptor

For I = 0 To 5
Replace.SearchString = BritishWords(I)
Replace.ReplaceString = USWords(I)
Doc.replaceAll(Replace)
Next I
</source>

The expressions for searching and replacing are set using the <tt>SearchString</tt> and <tt>ReplaceString</tt> properties of the <tt>ReplaceDescriptors</tt>. The actual replacement process is finally implemented using the <tt>replaceAll</tt> method of the document object, which replaces all occurrences of the search expression.

=== Example: searching and replacing text with regular expressions ===

The replacement function of {{OOo}} is particularly effective when used in conjunction with regular expressions. These provide the option of defining a variable search expression with place holders and special characters rather than a fixed value.

The regular expressions supported by {{OOo}} are described in detail in the online help section for {{OOo}}. Here are a few examples:

* A period within a search expression stands for any character. The search expression sh.rt therefore can stand for both for <tt>shirt</tt> and for <tt>short</tt>.
* The character ^ marks the start of a paragraph. All occurrences of the name <tt>Peter</tt> that are at the start of a paragraph can therefore be found using the search expression <tt>^Peter</tt>.
* The character $ marks a paragraph end. All occurrences of the name <tt>Peter</tt> that are at the end of a paragraph can therefore be found using the search expression <tt>Peter$</tt>.
* A * indicates that the preceding character may be repeated any number of times. It can be combined with the period as a place holder for any character. The <tt>temper.*e</tt> expression, for example, can stand for the expressions <tt>temperance</tt> and <tt>temperature</tt>.

The following example shows how all empty lines in a text document can be removed with the help of the regular expression ^$:

<source lang="oobas">
Dim Doc As Object
Dim Replace As Object
Dim I As Long

Doc = ThisComponent
Replace = Doc.createReplaceDescriptor
Replace.SearchRegularExpression = True
Replace.SearchString = "^$"
Replace.ReplaceString = ""

Doc.replaceAll(Replace)
</source>

{{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/Editing Text Documents}}
{{PDL1}}

Documentation/BASIC Guide/Editing Text Documents

2010-01-17T06:15:12Z

Andrewb: /* Navigating within a Text */ clarified definition of a period as sentence marker

{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Structure of Text Documents
|NextPage=Documentation/BASIC Guide/More Than Text
|textdocs=block
}}
{{DISPLAYTITLE:Editing Text Documents}}
__NOTOC__
The previous section has already discussed a whole range of options for editing text documents, focusing on the <idl>com.sun.star.text.TextPortion</idl> and <idl>com.sun.star.text.Paragraph</idl> services, which grant access to paragraph portions as well as paragraphs. These services are appropriate for applications in which the content of a text is to be edited in one pass through a loop. However, this is not sufficient for many problems. {{OOo}} provides the <idl>com.sun.star.text.TextCursor</idl> service for more complicated tasks, including navigating backward within a document or navigating based on sentences and words rather than <tt>TextPortions</tt>.

== The TextCursor ==

A <tt>TextCursor</tt> in the {{OOo}} API is comparable with the visible cursor used in a {{OOo}} document. It marks a certain point within a text document and can be navigated in various directions through the use of commands. The <tt>TextCursor</tt> objects available in {{OOo}} Basic should not, however, be confused with the visible cursor. These are two very different things.

{{Documentation/VBAnote|Terminology differs from that used in VBA: In terms of scope of function, the Range object from VBA can be compared with the TextCursor object in {{OOo}} and not — as the name possibly suggests — with the Range object in {{OOo}}.}}

The TextCursor object in {{OOo}}, for example, provides methods for navigating and changing text which are included in the Range object in VBA (for example, MoveStart, MoveEnd, InsertBefore, InsertAfter). The corresponding counterparts of the TextCursor object in {{OOo}} are described in the following sections.

=== Navigating within a Text ===

The <tt>TextCursor</tt> object in {{OOo}} Basic acts independently from the visible cursor in a text document. A program-controlled position change of a <tt>TextCursor</tt> object has no impact whatsoever on the visible cursor. Several <tt>TextCursor</tt> objects can even be opened for the same document and used in various positions, which are independent of one another.

A <tt>TextCursor</tt> object is created using the <tt>createTextCursor</tt> call:

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor()
</source>

The Cursor object created in this way supports the <tt>com.sun.star.text.TextCursor</tt> service, which in turn provides a whole range of methods for navigating within text documents. The following example first moves the <tt>TextCursor</tt> ten characters to the left and then three characters to the right:

<source lang="oobas">Cursor.goLeft(10, False)
Cursor.goRight(3, False)</source>

A <tt>TextCursor</tt> can highlight a complete area. This can be compared with highlighting a point in the text using the mouse. The <tt>False</tt> parameter in the previous function call specifies whether the area passed over with the cursor movement is highlighted. For example, the <tt>TextCursor</tt> in the following example

<source lang="oobas">
Cursor.goRight(10, False)
Cursor.goLeft(3, True)
</source>

first moves ten characters to the right without highlighting, and then moves back three characters and highlights this. The area highlighted by the <tt>TextCursor</tt> therefore begins after the seventh character in the text and ends after the tenth character.

Here are the central methods that the <idl>com.sun.star.text.TextCursor</idl> service provides for navigation:

;<tt>goLeft (Count, Expand)</tt>
:jumps Count characters to the left.
;<tt>goRight (Count, Expand)</tt>
:jumps Count characters to the right.
;<tt>gotoStart (Expand)</tt>
:jumps to the start of the text document.
;<tt>gotoEnd (Expand)</tt>
:jumps to the end of the text document.
;<tt>gotoRange (TextRange, Expand)</tt>
:jumps to the specified <tt>TextRange</tt>-Object.
;<tt>gotoStartOfWord (Expand)</tt>
:jumps to the start of the current word.
;<tt>gotoEndOfWord (Expand)</tt>
:jumps to the end of the current word.
;<tt>gotoNextWord (Expand)</tt>
:jumps to the start of the next word.
;<tt>gotoPreviousWord (Expand)</tt>
:jumps to the start of the previous word.
;<tt>isStartOfWord ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the start of a word.
;<tt>isEndOfWord ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the end of a word.
;<tt>gotoStartOfSentence (Expand)</tt>
:jumps to the start of the current sentence.
;<tt>gotoEndOfSentence (Expand)</tt>
:jumps to the end of the current sentence.
;<tt>gotoNextSentence (Expand)</tt>
:jumps to the start of the next sentence.
;<tt>gotoPreviousSentence (Expand)</tt>
:jumps to the start of the previous sentence.
;<tt>isStartOfSentence ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the start of a sentence.
;<tt>isEndOfSentence ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the end of a sentence.
;<tt>gotoStartOfParagraph (Expand)</tt>
:jumps to the start of the current paragraph.
;<tt>gotoEndOfParagraph (Expand)</tt>
:jumps to the end of the current paragraph.
;<tt>gotoNextParagraph (Expand)</tt>
:jumps to the start of the next paragraph.
;<tt>gotoPreviousParagraph (Expand)</tt>
:jumps to the start of the previous paragraph.
;<tt>isStartOfParagraph ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the start of a paragraph.
;<tt>isEndOfParagraph ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> is at the end of a paragraph.

The text is divided into sentences on the basis of sentence symbols. Periods are, for example, interpreted as symbols indicating the end of sentences. (In English, at least, they must be followed by a space for this to work.)

The <tt>Expand</tt> parameter is a Boolean value which specifies whether the area passed over during navigation is to be highlighted. All navigation methods furthermore return a Boolean parameter which specifies whether the navigation was successful or whether the action was terminated for lack of text.

The following is a list of several methods for editing highlighted areas using a <tt>TextCursor</tt> and which also support the <idl>com.sun.star.text.TextCursor</idl> service:

;<tt>collapseToStart ()</tt>
:resets the highlighting and positions the <tt>TextCursor</tt> at the start of the previously highlighted area.
;<tt>collapseToEnd ()</tt>
:resets the highlighting and positions the <tt>TextCursor</tt> at the end of the previously highlighted area.
;<tt>isCollapsed ()</tt>
:returns <tt>True</tt> if the <tt>TextCursor</tt> does not cover any highlighting at present.

=== Formatting Text with TextCursor ===

The <idl>com.sun.star.text.TextCursor</idl> service supports all the character and paragraph properties that were presented at the start of this chapter.

The following example shows how these can be used in conjunction with a <tt>TextCursor</tt>. It passes through a complete document and formats the first word of every sentence in bold type.

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor

Do
Cursor.gotoEndOfWord(True)
Cursor.CharWeight = com.sun.star.awt.FontWeight.BOLD
Proceed = Cursor.gotoNextSentence(False)
Cursor.gotoNextWord(False)
Loop While Proceed
</source>

The example first creates a document object for the text that has just been opened. Then it iterates through the entire text, sentence by sentence, and highlights each of the first words and formats this in bold.

=== Retrieving and Modifying Text Contents ===

If a <tt>TextCursor</tt> contains a highlighted area, then this text is available by means of the <tt>String</tt> property of the <tt>TextCursor</tt> object. The following example uses the <tt>String</tt> property to display the first words of a sentence in a message box:

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor

Do
Cursor.gotoEndOfWord(True)
MsgBox Cursor.String
Proceed = Cursor.gotoNextSentence(False)
Cursor.gotoNextWord(False)
Loop While Proceed
</source>

The first word of each sentence can be modified in the same way using the <tt>String</tt> property:

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor

Do
Cursor.gotoEndOfWord(True)
Cursor.String = "Ups"
Proceed = Cursor.gotoNextSentence(False)
Cursor.gotoNextWord(False)
Loop While Proceed
</source>

If the <tt>TextCursor</tt> contains a highlighted area, an assignment to the <tt>String</tt> property replaces this with the new text. If there is no highlighted area, the text is inserted at the present <tt>TextCursor</tt> position.

=== Inserting Control Codes ===

In some situations, it is not the actual text of a document, but rather its structure that needs modifying. {{OOo}} provides control codes for this purpose. These are inserted in the text and influence its structure. The control codes are defined in the <idl>com.sun.star.text.ControlCharacter</idl> group of constants. The following control codes are available in {{OOo}}:

;<tt>PARAGRAPH_BREAK</tt>:paragraph break.
;<tt>LINE_BREAK</tt>:line break within a paragraph.
;<tt>SOFT_HYPHEN</tt>:possible point for syllabification.
;<tt>HARD_HYPHEN</tt>:obligatory point for syllabification.
;<tt>HARD_SPACE</tt>:protected space that is not spread out or compressed in justified text.

To insert the control codes, you need not only the cursor but also the associated text document objects. The following example inserts a paragraph after the 20th character of a text:

<source lang="oobas">
Dim Doc As Object
Dim Cursor As Object
Dim Proceed As Boolean

Doc = ThisComponent
Cursor = Doc.Text.createTextCursor
Cursor.goRight(20, False)
Doc.Text.insertControlCharacter(Cursor, _
com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False)
</source>

The <tt>False</tt> parameter in the call of the <tt>insertControlCharacter</tt> method ensures that the area currently highlighted by the <tt>TextCursor</tt> remains after the insert operation. If the <tt>True</tt> parameter is passed here, then <tt>insertControlCharacter</tt> replaces the current text.

== Searching for Text Portions ==

In many instances, it is the case that a text is to be searched for a particular term and the corresponding point needs to be edited. All {{OOo}} documents provide a special interface for this purpose, and this interface always functions in accordance with the same principle: Before a search process, what is commonly referred to as a <tt>SearchDescriptor</tt> must first be created. This defines what {{OOo}} searches for in a document. A <tt>SearchDescriptor</tt> is an object which supports the <tt>com.sun.star.util.</tt> <tt>SearchDescriptor</tt> service and can be created by means of the <tt>createSearchDescriptor</tt> method of a document:

<source lang="oobas">
Dim SearchDesc As Object
SearchDesc = Doc.createSearchDescriptor
</source>

Once the <tt>SearchDescriptor</tt> has been created, it receives the text to be searched for:

<source lang="oobas">
SearchDesc.searchString="any text"
</source>

In terms of its function, the <tt>SearchDescriptor</tt> is best compared with the search dialog from {{OOo}}. In a similar way to the search window, the settings needed for a search can be set in the <tt>SearchDescriptor</tt> object.

The properties are provided by the <idl>com.sun.star.util.SearchDescriptor</idl> service:

;<tt>SearchBackwards (Boolean)</tt>:searches through the text backward rather than forward.
;<tt>SearchCaseSensitive (Boolean)</tt>:takes uppercase and lowercase characters into consideration during the search.
;<tt>SearchRegularExpression (Boolean)</tt>:treats the search expression like a regular expression.
;<tt>SearchStyles (Boolean)</tt>:searches through the text for the specified paragraph template.
;<tt>SearchWords (Boolean)</tt>:only searches for complete words.

The {{OOo}} <tt>SearchSimilarity</tt> (or “fuzzy match”) function is also available in {{OOo}} Basic. With this function, {{OOo}} searches for an expression that may be similar to but not exactly the same as the search expression. The number of additional, deleted and modified characters for these expressions can be defined individually. Here are the associated properties of the <tt>com.sun.star.util.SearchDescriptor</tt> service:

;<tt>SearchSimilarity (Boolean)</tt>:performs a similarity search.
;<tt>SearchSimilarityAdd (Short)</tt>:number of characters which may be added for a similarity search.
;<tt>SearchSimilarityExchange (Short)</tt>:number of characters which may be replaced as part of a similarity search.
;<tt>SearchSimilarityRemove (Short)</tt>:number of characters which may be removed as part of a similarity search.
;<tt>SearchSimilarityRelax (Boolean)</tt>:takes all deviation rules into consideration at the same time for the search expression.

Once the <tt>SearchDescriptor</tt> has been prepared as requested, it can be applied to the text document. The {{OOo}} documents provide the <tt>findFirst</tt> and <tt>findNext</tt> methods for this purpose:

<source lang="oobas">
Found = Doc.findFirst (SearchDesc)

Do Until IsNull(Found)
' Edit search results...
Found = Doc.findNext( Found.End, SearchDesc)
Loop
</source>

The example finds all matches in a loop and returns a <tt>TextRange</tt> object, which refers to the found text passage.

=== Example: Similarity Search ===

This example shows how a text can be searched for the word "turnover" and the results formatted in bold type. A similarity search is used so that not only the word “turnover”, but also the plural form "turnovers" and declinations such as "turnover's" are found. The found expressions differ by up to two letters from the search expression:

<source lang="oobas">
Dim SearchDesc As Object
Dim Doc As Object

Doc = ThisComponent
SearchDesc = Doc.createSearchDescriptor
SearchDesc.SearchString="turnover"
SearchDesc.SearchSimilarity = True
SearchDesc.SearchSimilarityAdd = 2
SearchDesc.SearchSimilarityExchange = 2
SearchDesc.SearchSimilarityRemove = 2
SearchDesc.SearchSimilarityRelax = False
Found = Doc.findFirst (SearchDesc)

Do Until IsNull(Found)
Found.CharWeight = com.sun.star.awt.FontWeight.BOLD
Found = Doc.findNext( Found.End, SearchDesc)
Loop
</source>

{{Documentation/VBAnote|The basic idea of search and replace in {{OOo}} is comparable to that used in VBA. Both interfaces provide you with an object, through which the properties for searching and replacing can be defined. This object is then applied to the required text area in order to perform the action. Whereas the responsible auxiliary object in VBA can be reached through the Find property of the Range object, in {{OOo}} Basic it is created by the <tt>createSearchDescriptor</tt> or <tt>createReplaceDescriptor</tt> call of the document object. Even the search properties and methods available differ.}}

As in the old API from {{OOo}}, searching and replacing text in the new API is also performed using the document object. Whereas previously there was an object called <tt>SearchSettings</tt> especially for defining the search options, in the new object searches are now performed using a <tt>SearchDescriptor</tt> or <tt>ReplaceDescriptor</tt> object for automatically replacing text. These objects cover not only the options, but also the current search text and, if necessary, the associated text replacement. The descriptor objects are created using the document object, completed in accordance with the relevant requests, and then transferred back to the document object as parameters for the search methods.

== Replacing Text Portions ==

Just as with the search function, the replacement function from {{OOo}} is also available in {{OOo}} Basic. The two functions are handled identically. A special object which records the parameters for the process is also first needed for a replacement process. It is called a <tt>ReplaceDescriptor</tt> and supports the <idl>com.sun.star.util.ReplaceDescriptor</idl> service. All the properties of the <tt>SearchDescriptor</tt> described in the previous paragraph are also supported by <tt>ReplaceDescriptor.</tt> For example, during a replacement process, case sensitivity can also be activated and deactivated, and similarity searches can be performed.

The following example demonstrates the use of <tt>ReplaceDescriptors</tt> for a search within a {{OOo}} document.

<source lang="oobas">
Dim I As Long
Dim Doc As Object
Dim Replace As Object
Dim BritishWords(5) As String
Dim USWords(5) As String

BritishWords() = Array("colour", "neighbour", "centre", "behaviour", _
"metre", "through")
USWords() = Array("color", "neighbor", "center", "behavior", _
"meter", "thru")

Doc = ThisComponent
Replace = Doc.createReplaceDescriptor

For I = 0 To 5
Replace.SearchString = BritishWords(I)
Replace.ReplaceString = USWords(I)
Doc.replaceAll(Replace)
Next I
</source>

The expressions for searching and replacing are set using the <tt>SearchString</tt> and <tt>ReplaceString</tt> properties of the <tt>ReplaceDescriptors</tt>. The actual replacement process is finally implemented using the <tt>replaceAll</tt> method of the document object, which replaces all occurrences of the search expression.

=== Example: searching and replacing text with regular expressions ===

The replacement function of {{OOo}} is particularly effective when used in conjunction with regular expressions. These provide the option of defining a variable search expression with place holders and special characters rather than a fixed value.

The regular expressions supported by {{OOo}} are described in detail in the online help section for {{OOo}}. Here are a few examples:

* A period within a search expression stands for any character. The search expression sh.rt therefore can stand for both for <tt>shirt</tt> and for <tt>short</tt>.
* The character ^ marks the start of a paragraph. All occurrences of the name <tt>Peter</tt> that are at the start of a paragraph can therefore be found using the search expression <tt>^Peter</tt>.
* The character $ marks a paragraph end. All occurrences of the name <tt>Peter</tt> that are at the end of a paragraph can therefore be found using the search expression <tt>Peter$</tt>.
* A * indicates that the preceding character may be repeated any number of times. It can be combined with the period as a place holder for any character. The <tt>temper.*e</tt> expression, for example, can stand for the expressions <tt>temperance</tt> and <tt>temperature</tt>.

The following example shows how all empty lines in a text document can be removed with the help of the regular expression ^$:

<source lang="oobas">
Dim Doc As Object
Dim Replace As Object
Dim I As Long

Doc = ThisComponent
Replace = Doc.createReplaceDescriptor
Replace.SearchRegularExpression = True
Replace.SearchString = "^$"
Replace.ReplaceString = ""

Doc.replaceAll(Replace)
</source>

{{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/Editing Text Documents}}
{{PDL1}}

Non-code extensions

2009-11-19T06:05:07Z

Andrewb: /* AutoText Extensions */ very small colloquialisations

{{Extensions}}
[[Category:Extensions]]
__TOC__

= OOo Extensions: Basic Principles =

OpenOffice.org was designed to be extendable from its very beginning. At first every extension was something that contained code (e.g. written in Java or OOo Basic). It was integrated into OOo by our component technology called UNO, so the file containing such an extension was called a "UNO package". Meanwhile OOo extension have reached the world of end users and so we thought that it's time to change our terminology a bit. The following documentation takes this into account. It tries to avoid the more technical term "UNO package" where possible as the purpose of this documentation is to provide an overview and an explanation of the basic concepts. If you want to learn more about UNO you can check our [http://wiki.services.openoffice.org/wiki/Uno UNO wiki] or the web pages of the [http://udk.openoffice.org UDK project].

The OpenOffice.org extension concept is not limited to code, it also allows to install other things like templates, autotexts etc. in handy single files. Here's a short explanation how this basically works. It is targeted to advanced end users, administrators and development newbies. All information provided here describes what is found in OpenOffice.org 2.0.4. Differences to older versions are not explained though it is explicitly mentioned when something has been added in 2.0.4 first.

If you are not interested in development at all you might want to skip the section about code extensions.

The section about the Configuration Manager gives you some ideas how you can use OOo extensions for customization purposes.

If you are only interested in knowing how to create non-code extensions without really knowing how this works you can go right to the section about "Path Settings". You should read at least this introducing section though.

Please send feedback to [[Image:Ooo-email.PNG]].
In case you have an account for this wiki you can of course also use the "Discussion" tab at the top of this page.

OOo Extensions are more or less zip containers with some additional data and meta data describing its content. They can be deployed by the built-in Extension Manager GUI (“Tools – Package Manager”, it will become renamed to "Tools-Extension Manager" in 2.0.5). It installs the extension for the current user using OpenOffice.org. The same can be done by using the command line tool “unopkg” that is located in the OOo program folder. This tool also allows to deploy an extension not only for a single user but for all of them by using the “--shared” parameter.

When extensions are installed their content is copied to some well defined though private places below “share/uno_packages” or “user/uno_packages”, depending on the scope of the extension installation (whole installation or single user). "Private" means: don't write any code that relies on the particular structure of an unpacked extension, access to unpacked files must use a defined API that handles the details for the caller. Files outside the "uno_packages" folders are not touched at all, with a single exception that can be seen as a [http://www.openoffice.org/issues/show_bug.cgi?id=70283 bug]: Basic macros in OOo extensions still need to be registered in xlc-files in one of the "basic" directories.

OOo extensions also support "Live deployment". This is different to e.g. Firefox where you always have to restart the application to make the extension available. In OpenOffice.org you can basically use the extension right after its installation. There is a restriction though: it is possible that the OpenOffice.org code using whatever is installed by the extension might "cache" what it finds when it is executed the first time and does not update this cached information when external influences (like the installation of an extension) actually would make it invalid. So at least either opening a new window or document or restarting the application can be necessary. In most cases this can be seen as a bug. As an example, in OpenOffice.org 2.0.4 templates extensions can be installed whenever wanted, but gallery extensions should be installed before the gallery is used the first time.

== Extensions containing UNO services (code) ==

If an OOo extension contains a UNO component written in Java, C++ or Python this component must publish its functionality to become usable for OpenOffice.org. In UNO based development a defined set of functionality is called a "service". A service is identified and accessed by its service name. So a component implementing such services must tell the world how they are named. Nowadays all components export a function that unopkg can call to force the component to write the necessary information into a service registry file that is created and maintained inside the „uno_packages“ folder. When OpenOffice.org uses its Service Manager to look for available UNO services it will scan not only the service registry (services.rdb) in its program directory (containing information about all "internal" services) but also all registry files inside the “uno_packages” folders.

Of course OOo can only instantiate UNO services by their names if it knows them. This is easy for services that replace already existing "internal" ones as OOo surely knows them and uses them, but as most components provide new services there must be something else that enables OOo to use them though they are not known at its compile time. So in these cases UNO components must provide additional data about when a particular service they implement should be loaded. The „additional component data“ is provided in OOo configuration files.

An example for this is a document filter component where the additional data that needs to be provided is (amongst other things) the file type that the filter can load. A particular filter component might register itself for being able to load Word Perfect files. So if a user selected this filter to load a file OOo would find the registered data by searching for any data containing the desired file type (wps), instantiate the filter component by its service name found in this data and use it to load the file. Each built-in filter has its own configuration data and document filters in extensions provide their own configuration data that extends the preinstalled data. So the Configuration Manager must be able to locate them and integrate their content in the suitable way.

== Extension support in the Configuration Manager ==
The Configuration Manager has a similar ability as the UNO Service Manager, it can scan a set of folders for data and puts them all together. The list of folders is extendable itself (through configmanager.ini) so that the Config Manager can get additional "layers". It even has the ability to use other backends than the file system for additional layers but I leave this out here.

The configuration data is arranged in a tree structure, data can be filled into this structure in every layer. The Configuration Manager scans the layers (folders) in a way that the data in "higher" layers either replaces or extends the data in "lower" layers, pretty much like the Windows registry does. Whether data is replaced or extended depends on the type of the data and is explained in the discussion of the [[Configuration_schema_path_settings|configuration schema for our path settings.]]

By default OpenOffice.org has two layers you already know: "share" and "user". The former contains preinstalled data, the latter takes all settings a particular users created by himself. Configuration files in OOo extensions create two new layers, "share/uno_packages" and "user/uno_packages". They lie in between the default layers, in the obvious order of priority "share" - "share/uno_packages" - "user/uno_packages" - "user".

So an extension can extend or change the OpenOffice.org configuration by providing xcu files that overwrite or extend (merge) configuration settings of OpenOffice.org. It can also have its own configuration settings if it provides schema (xcs) files for them.

There is another (pretty obvious) use case for the layering concept of the Configuration Manager: overwriting the preinstalled OpenOffice.org configuration settings on the "all users" level. An administrator can customize the OpenOffice.org installation in his own account, take the created xcu files containing these customizations and bundle them in an extension that he installs with "unopkg add --shared" each time he installs, reinstalls or updates OpenOffice.org. No need to edit the xcu files in "share/registry" by hand!

The layering concept of the service registry and the configuration are the basic principles that create the power of OOo extensions.

= Path Settings =
Some data in OpenOffice.org is not stored in xcu configuration files but somewhere else in the file system, e.g. document templates, autotexts, gallery content etc. Of course this content also should be deployable as extensions, so the access to these files must have a layering concept that allows extensions to meddle in the access to the files. OpenOffice.org has some components that manage the access to the files. We could have extended these components in the same way as we have extended the Configuration Manager or the Service Manager (by enabling them to use layers explicitly), but we decided to reuse the already available capability of the Configuration Manager.

The place where these files are looked for is defined in the configuration, in our path settings. Each "path" in any OOo version prior to 2.0.4 either was a single string describing a folder or a list of strings describing a list of folders ("multipath"). Unfortunately such a list can only be '''overwritten''' in upper layers, but not '''extended''', so we needed a [[Configuration_schema_path_settings|new configuration schema]] for paths that uses "sets" of strings instead of "string lists" as sets are extendable. We use this new schema for path settings starting with [http://specs.openoffice.org/appwide/options_settings/OOoPaths.odt OpenOffice.org 2.0.4]. We kept the old schema and its data for compatibility reasons and migrate its settings to the new data. The old schema will be removed in OpenOffice.org 3.0.

In earlier versions of OOo you usually could see the two "templates" folders in the "share" and "user" trees of OpenOffice.org. You also could see any additional folders that either the user of the administrator might have added.

If you look on the “Paths” settings in the “Options” Dialog in OOo2.0.4 you will notice that not all parts of the multipaths are shown here, only the folders from the "UserPaths" and "WritePath" elements from the [[Configuration_schema_path_settings|new configuration schema]]. As the former is empty in a default installation usually only one folder is visible per path setting.

'''Dialog Tools - Options - Paths'''
[[Image:Dialog_Tools_Options_204.png]]

Have a look on the path for templates. You can see "user/template" as this is the "WritePath" element and another folder ("g:\Departement Templates") that has been added as part of the "UserPaths" element, either by an administrator or by the user himself. You don't see the "share/templates" folder here as it is part of the "InternalPaths" element whose content intentionally isn't shown in the dialog. This element is the extendable part of the path setting and it contains all folders that are added either by the OOo installation itself or by the installation of an extension. As they have been added by deployement they shouldn't be controlled by the user, removing them is a task for those who have added them.

An improvement for the users as well as for the OpenOffice.org code is that now the folder that a user can put own data in is selected explicitly by marking it with a radio button. In older versions it was always a little bit unclear which folder OpenOffice.org whould choose. In most cases it was the last one of the list but now everything is unmistakable.

'''Dialog Tools - Options - Paths - Edit'''
[[Image:Dialog_Tools_Options_Edit_204.png]]

= Templates Extensions =

An extension for document templates is quite simple. It mainly contains just the templates, organized in directories that define template categories for the Document Templates Manager. Additionally a Paths.xcu file has to be provided that registers the extension in the set of document templates folders. This file contains the URL of the folder where the templates in the extension will be unpacked to. As this is something that isn't known the creation time of the extension a variable is used in the URL that is replaced by the extension manager when he copies the xcu file to the final location. The good thing is that this variable will always be the same for each templates extension so there is no need for the creator of such an extension to create by himself:

'''Paths.xcu'''
<source lang="xml">
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office"
oor:name="Paths" xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template" oor:op="fuse"/>
</node>
</node>

</node>
</oor:component-data>
</source>

If you compare this data with the data in [[Configuration_schema_path_settings#Data_based_on_new_schema|the installation]] you can see that both files contain something in the "InternalPaths" that the configuration merges into its name container representing this element. Merging is caused by the "fuse" keyword that defines the operation "add me to the container or create a new container if it doesn't exist".

== Example ==
[http://framework.openoffice.org/files/documents/25/3702/TemplatePackage.oxt Here] is an "empty extension" for document templates that is ready to be filled with templates.

The zip container has a folder called “templates”. Any sub folder of it you create will appear as a template category in the OOo templates dialogs. Templates can be put into those sub folders. The title of the template will be taken from the document metadata (document properties) or from the file name if the title in the metadata is not set. If one of your sub folders has the same name as an existing template category the templates in the extension will be merged into this category by the OpenOffice.org templates component. Just try it out, it's simpler to do it than to explain it.

== Localization of templates and template categories ==
The titles of the categories and templates can be taken from the file and folder names. These names can be localized and use any characters that the zip container and the target file systems(s) allow. It is possible that templates are installed on file systems that have problems with localized category (=folder) names so the Document Templates component allows to provide these localized names in a different file. The localized document template names can be stored in the document meta data (Document Properties) so they don't create a problem here.

The localization file is called "groupuinames.xml" and it is placed in the "templates" sub directory of the zip container. Its content is pretty straightforward. Here's an example for a german localization of some folders that use english file names:

'''groupuinames.xml'''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<groupuinames:template-group-list xmlns:groupuinames="http://openoffice.org/2006/groupuinames">
<groupuinames:template-group groupuinames:name="educate"
groupuinames:default-ui-name="Bildung" />
<groupuinames:template-group groupuinames:name="layout"
groupuinames:default-ui-name="Präsentationshintergründe" />
<groupuinames:template-group groupuinames:name="misc"
groupuinames:default-ui-name="Diverses" />
<groupuinames:template-group groupuinames:name="officorr"
groupuinames:default-ui-name="Geschäftliche Korrespondenz" />
<groupuinames:template-group groupuinames:name="offimisc"
groupuinames:default-ui-name="Sonstige geschäftliche Dokumente" />
<groupuinames:template-group groupuinames:name="personal"
groupuinames:default-ui-name="Private Korrespondenz und Dokumente" />
<groupuinames:template-group groupuinames:name="presnt"
groupuinames:default-ui-name="Präsentationen" />
</groupuinames:template-group-list>
</source>

== Multi language templates extensions ==
Multi language templates extensions are also possible, they need a small modification in line no. 13 of the Paths.xcu file:

'''Paths.xcu'''
<source lang="xml">
<?xml version='1.0' encoding='UTF-8'?>

<oor:component-data oor:package="org.openoffice.Office" oor:name="Paths"
xmlns:install="http://openoffice.org/2004/installation"
xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<node oor:name="Paths">

<node oor:name="Template" oor:op="fuse">
<node oor:name="InternalPaths">
<node oor:name="%origin%/template/$(vlang)" oor:op="fuse"/>
</node>
</node>

</node>

</oor:component-data>

</source>

and additional directories need to be created be the "templates" folder that have the ISO language codes supported by the OOo language packs as their names. I have created a [http://framework.openoffice.org/files/documents/25/3706/MultiLanguageTemplatePackage.oxt second empty extension file] that provides the infrastructure. Take it and put german templates into the "de" folder, english ones into "en-US", french ones into "fr" etc. Empty folders are not a problem. The localization files (groupuinames.xml) now need to be placed into the language specific folders, not directly into the "templates" folder as in the single language extension.

If you create an extension this way you can always only use the templates of the current GUI language. This is caused by the "$(vlang)" variable in the path. A solution that allows to switch the template language independently is [http://qa.openoffice.org/issues/show_bug.cgi?id=72005 still missing].

= AutoText Extensions =

Everything said about extensions for templates also applies to extensions for autotexts. The Paths.xcu of course now doesn't contain a value for the "Template" path but for the "AutoText" path. Again [http://framework.openoffice.org/files/documents/25/3710/AutoTextPackage.oxt here] is an example that can be filled with autotext files. Since there is currently no exporter you can manually copy any ".bau" files you have created into the extension. Creating extensions with localized autotexts works the same way: put the files into sub folders with names created from ISO language codes like you can see in the "share/autotext" folder. Unlike the template path the autotext path doesn't need to contain "$(vlang)" for multi language extensions as the autotext management component implements the language dependent access internally.

There is a tricky part here when you deploy autotext extensions: currently the autotext GUI allows to save autotexts to arbitrary locations. This is a [http://www.openoffice.org/issues/show_bug.cgi?id=70410 bug] that needs to be fixed. Any changes applied to autotexts in an extension will get lost when the extension is deinstalled. Extension content is not meant to be changed directly!

= Gallery Extensions =

Everything told about templates extensions also applies to extensions for gallery items. The Paths.xcu of course now doesn't contain a value for the "Template" path but for the "Gallery" path. Again [http://framework.openoffice.org/files/documents/25/3711/GalleryPackage.oxt here] is an example that can be filled with gallery themes you have created by yourself. As this is a little bit tricky and the gallery code currently is prone to name clashes of the theme files it is not recommended to use gallery extensions until the [http://www.openoffice.org/issues/show_bug.cgi?id=70412 issue] about these problems is fixed.

Another unsolved problem is the [http://qa.openoffice.org/issues/show_bug.cgi?id=71705 localization of gallery items].

= Extensions for dictionaries =

The linguistic tools and dictionaries configuration has been reworked and now dictionaries as extensions are possible. In the upcoming OOo3.0 beta both ways (dictionaries as extensions, dictionaries as single files installed by dictionary.lst) are supported but support for dictionary.lst will be dropped in OOo 3.0 final. More can be found [[Extension_Dictionaries | here]].

OOo 3 Beta feedback

2008-05-27T05:06:38Z

Andrewb: /* bugs */

= OpenOffice.org 3.0 Beta feedback =

The intention of this page is to collect the beta feedback from the various mailing list, forums, press, issues and come at the end to a prioritized list of most import bugs we need to fix for 3.0.

Also this is the chance to collect complains of most missed features so that we are able to develop a roadmap for the upcoming releases.

== good stuff ==

<blockquote>
I wonder if you might like to include on your marketing page OOo
3.0's concerted attempt to finally get word count right. This has
been a major bugbear for professional writers, and work is underway
right now to get OOo to mimic MS Word in this regard. This is a huge
deal for a significant portion of your user base, and a major
success worth trumpeting.

The master bug for this issue is 80815, if you're interested.
</blockquote>

== bugs ==

* File -> Save As in Vista SP1 broken => http://www.openoffice.org/issues/show_bug.cgi?id=87244
* MS Office 2007 XML filter issues
* Impress drag text box not working http://www.openoffice.org/issues/show_bug.cgi?id=89484
* Strange 600% limitation in Chart2, when changing space width between rectangles , like on this Snapshot [http://www.progressioo.fr/Capture.png]
* [Mac Aqua] writer crashes opening word documents with comments inside {{issue|89243}}
* There's [http://www.openoffice.org/issues/show_bug.cgi?id=87092 a nasty confirmed regression] in the search and replace which should be fixed before this is released. "x"s are randomly added at the end of replacement strings when formatting is changed.

== MS-O 2007 support ==
* [http://arstechnica.com/news.ars/post/20080507-first-look-openoffice-org-3-0-beta-a-big-step-forward.html file format support a mixed bag]
* [http://www.pcworld.com/article/id,145667-c,starofficeopenofficeorg/article.html OpenOffice.org Beta Fails the Office 2007 Test]
* [http://blogs.zdnet.com/hardware/?p=1822&page=1 what I’m seeing now doesn’t give me much hope that I’ll be able to replace Microsoft Office 2007 with OO.o 3.0]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html converted this reference .docx document with mediocre quality]... ([http://katana.oooninja.com/w/reference_sample_documents the document])

== missing features ==

* Outline mode writer
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207459620000#c279673438955276192 OpenType font support] is limited
* MacOSX: use system spell checking
* 1rst startup performance
* svg import
* 64k row limit in Calc needs to get extended.
* polish up mailmerge and mailmerge perfomance [http://www.openoffice.org/issues/show_bug.cgi?id=87104 issue].
* copy table from Calc to writer and vice versa.
* Add a '''place''' to the gallery (place could be a local folder or a website)
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206470580000#c5668163814393029595 envelope printing]

== Microsoft Office 2003 compatibility ==
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207485720000#c975697398253531650 Please better compatibility with .doc, .xls and .ppt files! ]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205936040000#c8960868027842246741 you must have 99.9% compatibility in a business setting. ]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205972700000#c2373903312098222544 JUST FIX ALL THE COMPATIBILITY ISSUES!]

== interface ==

* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206380760000#c8706859352622147396 Interface, when I see OO, I think, OMG this sucks! Office 2007 is really brilliant in this.]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205959680000#c3178094417039109525 when will the interface look more modern?]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205966640000#c539276019792587786 i thought OOo were going to improve the interface. but it looks identical to me!]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206181380000#c3180074046942643850 Ugly, none intuitive interface.]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206296040000#c839572984313633681 I don't like the OpenOffice interface, it seems to poor for me.]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206387900000#c126994644901918987 the interface could be more modern...]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207156980000#c2313822810772180354 MS Office 2007 interface is one of the best I've ever seen - please, implement this kind of interface in 3.0..]
** [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207252980000#c3008808206925922967 Oh no!!! Please not!]
* etc etc

OOo 3 Beta feedback

2008-05-27T05:04:44Z

Andrewb: /* MS-O 2007 support */

= OpenOffice.org 3.0 Beta feedback =

The intention of this page is to collect the beta feedback from the various mailing list, forums, press, issues and come at the end to a prioritized list of most import bugs we need to fix for 3.0.

Also this is the chance to collect complains of most missed features so that we are able to develop a roadmap for the upcoming releases.

== good stuff ==

<blockquote>
I wonder if you might like to include on your marketing page OOo
3.0's concerted attempt to finally get word count right. This has
been a major bugbear for professional writers, and work is underway
right now to get OOo to mimic MS Word in this regard. This is a huge
deal for a significant portion of your user base, and a major
success worth trumpeting.

The master bug for this issue is 80815, if you're interested.
</blockquote>

== bugs ==

* File -> Save As in Vista SP1 broken => http://www.openoffice.org/issues/show_bug.cgi?id=87244
* MS Office 2007 XML filter issues
* Impress drag text box not working http://www.openoffice.org/issues/show_bug.cgi?id=89484
* Strange 600% limitation in Chart2, when changing space width between rectangles , like on this Snapshot [http://www.progressioo.fr/Capture.png]
* [Mac Aqua] writer crashes opening word documents with comments inside {{issue|89243}}

== MS-O 2007 support ==
* [http://arstechnica.com/news.ars/post/20080507-first-look-openoffice-org-3-0-beta-a-big-step-forward.html file format support a mixed bag]
* [http://www.pcworld.com/article/id,145667-c,starofficeopenofficeorg/article.html OpenOffice.org Beta Fails the Office 2007 Test]
* [http://blogs.zdnet.com/hardware/?p=1822&page=1 what I’m seeing now doesn’t give me much hope that I’ll be able to replace Microsoft Office 2007 with OO.o 3.0]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html converted this reference .docx document with mediocre quality]... ([http://katana.oooninja.com/w/reference_sample_documents the document])

== missing features ==

* Outline mode writer
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207459620000#c279673438955276192 OpenType font support] is limited
* MacOSX: use system spell checking
* 1rst startup performance
* svg import
* 64k row limit in Calc needs to get extended.
* polish up mailmerge and mailmerge perfomance [http://www.openoffice.org/issues/show_bug.cgi?id=87104 issue].
* copy table from Calc to writer and vice versa.
* Add a '''place''' to the gallery (place could be a local folder or a website)
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206470580000#c5668163814393029595 envelope printing]

== Microsoft Office 2003 compatibility ==
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207485720000#c975697398253531650 Please better compatibility with .doc, .xls and .ppt files! ]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205936040000#c8960868027842246741 you must have 99.9% compatibility in a business setting. ]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205972700000#c2373903312098222544 JUST FIX ALL THE COMPATIBILITY ISSUES!]

== interface ==

* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206380760000#c8706859352622147396 Interface, when I see OO, I think, OMG this sucks! Office 2007 is really brilliant in this.]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205959680000#c3178094417039109525 when will the interface look more modern?]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205966640000#c539276019792587786 i thought OOo were going to improve the interface. but it looks identical to me!]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206181380000#c3180074046942643850 Ugly, none intuitive interface.]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206296040000#c839572984313633681 I don't like the OpenOffice interface, it seems to poor for me.]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206387900000#c126994644901918987 the interface could be more modern...]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207156980000#c2313822810772180354 MS Office 2007 interface is one of the best I've ever seen - please, implement this kind of interface in 3.0..]
** [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207252980000#c3008808206925922967 Oh no!!! Please not!]
* etc etc

OOo 3 Beta feedback

2008-05-27T05:04:05Z

Andrewb: /* MS-O 2007 support */

= OpenOffice.org 3.0 Beta feedback =

The intention of this page is to collect the beta feedback from the various mailing list, forums, press, issues and come at the end to a prioritized list of most import bugs we need to fix for 3.0.

Also this is the chance to collect complains of most missed features so that we are able to develop a roadmap for the upcoming releases.

== good stuff ==

<blockquote>
I wonder if you might like to include on your marketing page OOo
3.0's concerted attempt to finally get word count right. This has
been a major bugbear for professional writers, and work is underway
right now to get OOo to mimic MS Word in this regard. This is a huge
deal for a significant portion of your user base, and a major
success worth trumpeting.

The master bug for this issue is 80815, if you're interested.
</blockquote>

== bugs ==

* File -> Save As in Vista SP1 broken => http://www.openoffice.org/issues/show_bug.cgi?id=87244
* MS Office 2007 XML filter issues
* Impress drag text box not working http://www.openoffice.org/issues/show_bug.cgi?id=89484
* Strange 600% limitation in Chart2, when changing space width between rectangles , like on this Snapshot [http://www.progressioo.fr/Capture.png]
* [Mac Aqua] writer crashes opening word documents with comments inside {{issue|89243}}

== MS-O 2007 support ==
* [http://arstechnica.com/news.ars/post/20080507-first-look-openoffice-org-3-0-beta-a-big-step-forward.html file format support a mixed bag]
* [http://www.pcworld.com/article/id,145667-c,starofficeopenofficeorg/article.html OpenOffice.org Beta Fails the Office 2007 Test]
* [http://blogs.zdnet.com/hardware/?p=1822&page=1 what I’m seeing now doesn’t give me much hope that I’ll be able to replace Microsoft Office 2007 with OO.o 3.0]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html converted this reference .docx document with mediocre quality]... ([http://katana.oooninja.com/w/reference_sample_documents the document])
* There's [http://www.openoffice.org/issues/show_bug.cgi?id=87092 a nasty regression] in the search and replace which should be fixed before this is released.

== missing features ==

* Outline mode writer
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207459620000#c279673438955276192 OpenType font support] is limited
* MacOSX: use system spell checking
* 1rst startup performance
* svg import
* 64k row limit in Calc needs to get extended.
* polish up mailmerge and mailmerge perfomance [http://www.openoffice.org/issues/show_bug.cgi?id=87104 issue].
* copy table from Calc to writer and vice versa.
* Add a '''place''' to the gallery (place could be a local folder or a website)
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206470580000#c5668163814393029595 envelope printing]

== Microsoft Office 2003 compatibility ==
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207485720000#c975697398253531650 Please better compatibility with .doc, .xls and .ppt files! ]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205936040000#c8960868027842246741 you must have 99.9% compatibility in a business setting. ]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205972700000#c2373903312098222544 JUST FIX ALL THE COMPATIBILITY ISSUES!]

== interface ==

* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206380760000#c8706859352622147396 Interface, when I see OO, I think, OMG this sucks! Office 2007 is really brilliant in this.]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205959680000#c3178094417039109525 when will the interface look more modern?]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1205966640000#c539276019792587786 i thought OOo were going to improve the interface. but it looks identical to me!]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206181380000#c3180074046942643850 Ugly, none intuitive interface.]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206296040000#c839572984313633681 I don't like the OpenOffice interface, it seems to poor for me.]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1206387900000#c126994644901918987 the interface could be more modern...]
* [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207156980000#c2313822810772180354 MS Office 2007 interface is one of the best I've ever seen - please, implement this kind of interface in 3.0..]
** [http://www.oooninja.com/2008/03/openofficeorg-30-new-features.html?showComment=1207252980000#c3008808206925922967 Oh no!!! Please not!]
* etc etc

PyUNO samples

2008-03-18T12:44:03Z

Andrewb:

{{Documentation/Candidate}}
OpenOffice.org comes with a set of scripts that work as a sample on how to programmatically generate certain tasks using PyUNO.

=== Hello World.py ===
This script print a Hello World in an Writer document. This uses the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText] interface, the actual content is on the String value of the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XTextRange.html XTextRange].

First step we define the HelloWorldPython() class, then we call the XSCRIPTCONTEXT which will let us work within a sub-environment from UNO. Notice we didn't import uno and we don't need to connect to OOo through the socket. Also we have the uno enviroment by calling getDocument().

Then we call the XText interface to call on the END and STRING methods to write up the "Hello World (in Python)".
<source lang=python>
# HelloWorld python script for the scripting framework

def HelloWorldPython( ):
"""Prints the string 'Hello World(in Python)' into the current document"""
#get the doc from the scripting context which is made available to all scripts
model = XSCRIPTCONTEXT.getDocument()
#get the XText interface
text = model.Text
#create an XTextRange at the end of the document
tRange = text.End
#and set the string
tRange.String = "Hello World (in Python)"
return None
</source>

=== Capitalize.py ===
This script will show how to modify existing content in a document. More specifically manipulate the format values from the text. We use common python string menthods like '''isupper, upper, len and lower'''. And we use XSCRIPTCONTEXT (Learn about the [http://api.openoffice.org/docs/DevelopersGuide/ScriptingFramework/ScriptingFramework.xhtml XSCRIPTCONTEXT]) for the positioning of the text ([http://api.openoffice.org/docs/common/ref/com/sun/star/text/XText.html XText] and [http://api.openoffice.org/docs/common/ref/com/sun/star/text/XTextRange.html XTextRange] ), the control of the cursor ([http://api.openoffice.org/docs/common/ref/com/sun/star/text/XWordCursor.html xWordCursor]).

<source lang=python>
# helper function
def getNewString( theString ) :
if( not theString or len(theString) ==0) :
return ""
# should we tokenize on "."?
if theString[0].isupper() and len(theString)>=2 and theString[1].isupper() :
# first two chars are UC => first UC, rest LC
newString=theString[0:1].upper() + theString[1:].lower();
elif theString[0].isupper():
# first char UC => all to LC
newString=theString.lower()
else: # all to UC.
newString=theString.upper()
return newString;

def capitalisePython( ):
"""Change the case of a selection, or current word from upper case, to first char upper case, to all lower case to upper case..."""
import string

# The context variable is of type XScriptContext and is available to
# all BeanShell scripts executed by the Script Framework
xModel = XSCRIPTCONTEXT.getDocument()

#the writer controller impl supports the css.view.XSelectionSupplier interface
xSelectionSupplier = xModel.getCurrentController()

#see section 7.5.1 of developers' guide
xIndexAccess = xSelectionSupplier.getSelection()
count = xIndexAccess.getCount();
if(count>=1): #ie we have a selection
i=0
while i < count :
xTextRange = xIndexAccess.getByIndex(i);
#print "string: " + xTextRange.getString();
theString = xTextRange.getString();
if len(theString)==0 :
# sadly we can have a selection where nothing is selected
# in this case we get the XWordCursor and make a selection!
xText = xTextRange.getText();
xWordCursor = xText.createTextCursorByRange(xTextRange);
if not xWordCursor.isStartOfWord():
xWordCursor.gotoStartOfWord(False);
xWordCursor.gotoNextWord(True);
theString = xWordCursor.getString();
newString = getNewString(theString);
if newString :
xWordCursor.setString(newString);
xSelectionSupplier.select(xWordCursor);
else :

newString = getNewString( theString );
if newString:
xTextRange.setString(newString);
xSelectionSupplier.select(xTextRange);
i+= 1

# lists the scripts, that shall be visible inside OOo. Can be omitted, if
# all functions shall be visible, however here getNewString shall be surpressed
g_exportedScripts = capitalisePython,
</source>

=== TableSample.py ===

On this script we abandon the XSCRIPTCONTEXT and use the UNO module. We also use nested modules from Text, AWT, and LANG. Since we using the UNO module we have to import what we need straight from the com.sun.star path.

The first step is to get the functions for generating the document, and the other for manipulating the content. The document and content is under the '''createTable()''', while '''insertTextIntoCell()''' will handle the positioning within the table.

<source lang=python>
import uno

# a UNO struct later needed to create a document
from com.sun.star.text.ControlCharacter import PARAGRAPH_BREAK
from com.sun.star.text.TextContentAnchorType import AS_CHARACTER
from com.sun.star.awt import Size

from com.sun.star.lang import XMain

def insertTextIntoCell( table, cellName, text, color ):
tableText = table.getCellByName( cellName )
cursor = tableText.createTextCursor()
cursor.setPropertyValue( "CharColor", color )
tableText.setString( text )

def createTable():
"""creates a new writer document and inserts a table with some data (also known as the SWriter sample)"""
ctx = uno.getComponentContext()
smgr = ctx.ServiceManager
desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx)

# open a writer document
doc = desktop.loadComponentFromURL( "private:factory/swriter","_blank", 0, () )

text = doc.Text
cursor = text.createTextCursor()
text.insertString( cursor, "The first line in the newly created text document.\n", 0 )
text.insertString( cursor, "Now we are in the second line\n" , 0 )

# create a text table
table = doc.createInstance( "com.sun.star.text.TextTable" )

# with 4 rows and 4 columns
table.initialize( 4,4)

text.insertTextContent( cursor, table, 0 )
rows = table.Rows

table.setPropertyValue( "BackTransparent", uno.Bool(0) )
table.setPropertyValue( "BackColor", 13421823 )
row = rows.getByIndex(0)
row.setPropertyValue( "BackTransparent", uno.Bool(0) )
row.setPropertyValue( "BackColor", 6710932 )

textColor = 16777215

insertTextIntoCell( table, "A1", "FirstColumn", textColor )
insertTextIntoCell( table, "B1", "SecondColumn", textColor )
insertTextIntoCell( table, "C1", "ThirdColumn", textColor )
insertTextIntoCell( table, "D1", "SUM", textColor )

values = ( (22.5,21.5,121.5),
(5615.3,615.3,-615.3),
(-2315.7,315.7,415.7) )
table.getCellByName("A2").setValue(22.5)
table.getCellByName("B2").setValue(5615.3)
table.getCellByName("C2").setValue(-2315.7)
table.getCellByName("D2").setFormula("sum <A2:C2>")

table.getCellByName("A3").setValue(21.5)
table.getCellByName("B3").setValue(615.3)
table.getCellByName("C3").setValue(-315.7)
table.getCellByName("D3").setFormula("sum <A3:C3>")

table.getCellByName("A4").setValue(121.5)
table.getCellByName("B4").setValue(-615.3)
table.getCellByName("C4").setValue(415.7)
table.getCellByName("D4").setFormula("sum <A4:C4>")

cursor.setPropertyValue( "CharColor", 255 )
cursor.setPropertyValue( "CharShadowed", uno.Bool(1) )

text.insertControlCharacter( cursor, PARAGRAPH_BREAK, 0 )
text.insertString( cursor, " This is a colored Text - blue with shadow\n" , 0 )
text.insertControlCharacter( cursor, PARAGRAPH_BREAK, 0 )

textFrame = doc.createInstance( "com.sun.star.text.TextFrame" )
textFrame.setSize( Size(15000,400))
textFrame.setPropertyValue( "AnchorType" , AS_CHARACTER )

text.insertTextContent( cursor, textFrame, 0 )

textInTextFrame = textFrame.getText()
cursorInTextFrame = textInTextFrame.createTextCursor()
textInTextFrame.insertString( cursorInTextFrame, "The first line in the newly created text frame.", 0 )
textInTextFrame.insertString( cursorInTextFrame, "\nWith this second line the height of the rame raises.",0)
text.insertControlCharacter( cursor, PARAGRAPH_BREAK, 0 )

cursor.setPropertyValue( "CharColor", 65536 )
cursor.setPropertyValue( "CharShadowed", uno.Bool(0) )

text.insertString( cursor, " That's all for now !!" , 0 )

g_exportedScripts = createTable,
</source>

First step to understand is that the UNO module will give us the IDL binding from the API. We will then import specific things from the UNO module. For tht we need to specify the path from com.sun.star and import the interfaces and services.

The nested modules [http://api.openoffice.org/docs/common/ref/com/sun/star/text/module-ix.html text] we had: [http://api.openoffice.org/docs/common/ref/com/sun/star/text/ControlCharacter.html ControlCharacter], [http://api.openoffice.org/docs/common/ref/com/sun/star/text/TextContentAnchorType.html TextContentAnchorType] and import [http://api.openoffice.org/docs/common/ref/com/sun/star/text/ControlCharacter.html#PARAGRAPH_BREAK PARAGRAPH_BREAK], [http://api.openoffice.org/docs/common/ref/com/sun/star/text/TextContentAnchorType.html#AS_CHARACTER AS_CHARACTER].

From [http://api.openoffice.org/docs/common/ref/com/sun/star/awt/module-ix.html awt] which is a user interface toolkit had: [http://api.openoffice.org/docs/common/ref/com/sun/star/awt/Size.html Size]

Finally [http://api.openoffice.org/docs/common/ref/com/sun/star/lang/module-ix.html lang] nested module which is about , we import [http://api.openoffice.org/docs/common/ref/com/sun/star/lang/XMain.html XMain].

<source lang=python>
import uno

# a UNO struct later needed to create a document
from com.sun.star.text.ControlCharacter import PARAGRAPH_BREAK
from com.sun.star.text.TextContentAnchorType import AS_CHARACTER
from com.sun.star.awt import Size

from com.sun.star.lang import XMain
</source>

==== createTable() ====

We can divide this class into the process of:
* creating a new window
* creating a writer document
* inserting text (previously seen on the Hello World Script).
* Creating a table within the writer document
* manipulate the format and finally the content
* Then we insert a frame with text in it
* insert a string

This let us analyze in more detail the interfaces and methods from the cursor, table, text, textFrame and textInTextFrame. All this documentation can be found on the IDL reference. Following this script will allow us to use the IDL to our benefit and explore other nested modules for different porpouse.

The following values goes extract from the following:

* doc = desktop.'''loadComponentFromURL( "private:factory/swriter","_blank", 0, () )'''
* text = doc.Text
* cursor = text.'''createTextCursor()'''
* table = doc.'''createInstance( "com.sun.star.text.TextTable" )'''

The '''loadcomponentFromURL()''' creates and load the Writer document by generating the variable. Text is a variable that will get the document object with the module of Text. The function of '''createTextCursor()''' acording with the IDL ''a new instance of a TextCursor service which can be used to travel in the given text context''.
<source lang=python>
"""creates a new writer document and inserts a table with some data (also known as the SWriter sample)"""
ctx = uno.getComponentContext()
smgr = ctx.ServiceManager
desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx)

# open a writer document
doc = desktop.loadComponentFromURL( "private:factory/swriter","_blank", 0, () )

text = doc.Text
cursor = text.createTextCursor()
text.insertString( cursor, "The first line in the newly created text document.\n", 0 )
text.insertString( cursor, "Now we are in the second line\n" , 0 )</source>
The next instance is the creation of the table instance within the table variable. We use the function of '''createTextCursor()''', the path to the module is '''com.sun.star.text.TextTable'''.
<source lang=python>
# create a text table
table = doc.createInstance( "com.sun.star.text.TextTable" )
</source>
We create our table by using the method '''initialize''' on the line 35 of the code '''table.initialize( 4,4)'''. Now we will deal with the properties of the table as well as the methods and objects from the table like rows, cursor and values. First step after initialize the table, we use the function '''insertTextContent( cursor, table, 0 )''', if you think that this will put a cursor in the table, then you are RIGHT. TextContent is basically an object which can be anchored in a text, like instances of TextFrame or TextFields. In our case we will deal with Cells rather than Frames or Fields.
<source lang=python>

# with 4 rows and 4 columns
table.initialize( 4,4)

text.insertTextContent( cursor, table, 0 )
rows = table.Rows</source>
The next point is we will focus on the '''styles''' of the table and have methods such as '''setPropertyValue''' which could might as well be setStyleValue being implemented to the text, for example '''setPropertyValue( "BackTransparent", uno.Bool(0) )''' or '''setPropertyValue( "BackColor", 6710932 )'''.
<source lang=python>
table.setPropertyValue( "BackTransparent", uno.Bool(0) )
table.setPropertyValue( "BackColor", 13421823 )
row = rows.getByIndex(0)
row.setPropertyValue( "BackTransparent", uno.Bool(0) )
row.setPropertyValue( "BackColor", 6710932 )</source>
The next step is to get the header of the table which will use the other class and will insert the values that we need, we get '''insertTextIntoCell( table, "A1", "FirstColumn", textColor )''' put color and content into the specific cells from the table object. The syntax is rather straight forward by stating object, cell position, text content and finally text color value which in this cas is a variable of the hex color 16777215.
<source lang=python>
textColor = 16777215

insertTextIntoCell( table, "A1", "FirstColumn", textColor )
insertTextIntoCell( table, "B1", "SecondColumn", textColor )
insertTextIntoCell( table, "C1", "ThirdColumn", textColor )
insertTextIntoCell( table, "D1", "SUM", textColor )</source>
Now we will insert the content of our table including the numerical value and '''formula'''. We use an array of values and then generate a series of inserting the '''values()''' within the the '''getCellByName()''', '''setValue()''' and '''setFormula'''.
<source lang=python>
values = ( (22.5,21.5,121.5),
(5615.3,615.3,-615.3),
(-2315.7,315.7,415.7) )
table.getCellByName("A2").setValue(22.5)
table.getCellByName("B2").setValue(5615.3)
table.getCellByName("C2").setValue(-2315.7)
table.getCellByName("D2").setFormula("sum <A2:C2>")</source>

==== insertTextIntoCell() ====
This is a sub-process class which brings the services and methods for the table manipulation. The function uses the method getCellbyName, createTextCursor and createPropertyValue.

This insertTextIntoCell() function will bring a structure to format the header of the table.

[[Category:Python]]
[[Category:Uno]]
[[Category:Tutorial]]

PyUNOServer

2008-03-17T08:31:56Z

Andrewb: code to source tags

[[image:Py-uno_128.png|right|PyUNO Logo]]
The PyUNOServer is a script that works as an XML server for OpenOffice.org Calc where it can exchange data through XML calls. This means that can get data from other apps that are XML compliant. You can download the script from [http://es.openoffice.org/files/documents/73/2929/pyUnoServer.tar.gz this mirror] since the original site seems to be down.

The zip file contains 3 files:
* '''PyUNOServerV2.py''' - The Python Script
* '''PyUNOServerV2.pyc''' - compiled version
* '''PyUNOServer.sh2''' - the script to conect to the service

The script have just 1 script called '''PyUNOServerV2.py''' however there is a faster, bytecode-compiled script. It also includes a bash script which loads the path to the openoffice.org application.

'''NOTE: This script will work on just certain distros since the location of OpenOffice.org might vary. We recomend to load the path manually.'''

This script uses the following libraries:

* '''OS''' - This module provides a more portable way of using operating system dependent functionality than importing a operating system dependent built-in module like posix or nt.
* '''UNO''' - Python UNO implementation module, this can used by python 2.3.4 '''only''' which is the python provided within openoffice.org. It provides all the interfaces from OpenOffice.org into python.
* '''SYS''' - This module provides access to some variables used or maintained by the interpreter and to functions that interact strongly with the interpreter. It is always available.
* '''time''' - This module provides various time-related functions. It is always available, but not all functions are available on all platforms. Most of the functions defined in this module call platform C library functions with the same name. It may sometimes be helpful to consult the platform documentation, because the semantics of these functions varies among platforms.
* '''logging''' - Logging is performed by calling methods on instances of the Logger class (hereafter called loggers). Each instance has a name, and they are conceptually arranged in a name space hierarchy using dots (periods) as separators.
* '''urllib''' - This module provides a high-level interface for fetching data across the World Wide Web. In particular, the urlopen() function is similar to the built-in function open(), but accepts Universal Resource Locators (URLs) instead of filenames. Some restrictions apply -- it can only open URLs for reading, and no seek operations are available.
* '''SimpleXMLRPCServer''' - The SimpleXMLRPCServer module provides a basic server framework for XML-RPC servers written in Python. Servers can either be free standing, using SimpleXMLRPCServer, or embedded in a CGI environment, using CGIXMLRPCRequestHandler.

<source lang=python>
# -*- coding: iso-8859-1 -*-
#
# pyUnoServer - version 2.0
from SimpleXMLRPCServer import SimpleXMLRPCServer, SimpleXMLRPCRequestHandler
import os
import uno
import sys
import time
import logging
import urllib

class PyUNOServer(SimpleXMLRPCServer):

def _dispatch(self, method, params):

try:
func = getattr(self, '' + method)
except:
self.logger.error("El Metodo '"+method+"' no esta soportado!")
raise Exception('method "%s" is not supported' % method)
else:
try:
ret = func(*params)
self.logger.info("Llamada: "+str(method)+str(params)+" | Retorno: "+str(ret))
return ret
except:
self.logger.info("Llamada: "+str(method)+str(params))
self.logger.error("Error: "+str(sys.exc_type)+":"+str(sys.exc_value))

def init(self):
"""
This method starts an Openoffice session and initializes the XMLRPC server
"""

# Generate some useful constants
self.EMPTY = uno.Enum("com.sun.star.table.CellContentType", "EMPTY")
self.TEXT = uno.Enum("com.sun.star.table.CellContentType", "TEXT")
self.FORMULA = uno.Enum("com.sun.star.table.CellContentType", "FORMULA")
self.VALUE = uno.Enum("com.sun.star.table.CellContentType", "VALUE")

# Generate a Logger
self.logger = logging.getLogger('pyUnoServer')
hdlr = logging.FileHandler('./pyUnoServer.log')
formatter = logging.Formatter('%(asctime)s %(levelname)s -- %(message)s')
hdlr.setFormatter(formatter)
self.logger.addHandler(hdlr)
self.logger.setLevel(logging.INFO)

self.sessions = []
self.sessionSerial = 0

# Start Calc and grep the PID
self.PID = os.spawnlp(os.P_NOWAIT,"/usr/bin/oocalc","","-accept=socket,host=localhost,port=2002;urp;")

self.logger.info("OOCalc Iniciado con el PID "+str(self.PID))

while 1:
try:
localContext = uno.getComponentContext()
resolver = localContext.ServiceManager.createInstanceWithContext("com.sun.star.bridge.UnoUrlResolver", localContext )
smgr = resolver.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ServiceManager" )
remoteContext = smgr.getPropertyValue( "DefaultContext" )
self.desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",remoteContext)
self.logger.info("Sistema conectado al socket de UNO")
break
except:
time.sleep(0.5)

def openSession(self, session):
"""
This method opens a new session.
Sample usage from PHP:
- $sessionString is your a session ID provided by your program):

$openSession = array( new XML_RPC_VALUE($sessionString, "string"));
$sessionID = queryXMLRPC($client, "openSession", $openSession);
return $sessionID;
"""

currentSerial = -1

for i in range(0,len(self.sessions)):
if self.sessions[i][0] == session:
currentSerial = i
break

if currentSerial == -1:
self.sessions.append([session,[]])
currentSerial = len(self.sessions)-1

return currentSerial

def getSessions(self):
return self.sessions

def openBook(self, session, bookPath):
"""
This method opens a new Openoffice spreadsheet book.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $path is the path to the book in the server's filesystem

$openBookQuery = array( new XML_RPC_VALUE($sessionID, "int"), new XML_RPC_VALUE($path,"string") );
$bookID = queryXMLRPC($client, "openBook", $openBookQuery);
return $bookID;
"""

currentSerial = session
bookPath = bookPath.strip()
print bookPath

exists = os.path.exists(bookPath)
if exists == False:
raise Exception('El libro %s no existe', bookPath)
else:
self.logger.info("se ha encontrado el libro!")

currentBook = -1

for i in range(0, len(self.sessions[currentSerial][1])):
try:

book = self.sessions[currentSerial][1][i]

bookname = book[0]
bookhandler = book[1]
bookmodtime = book[2]

if bookname == bookPath:
modtime = os.path.getmtime(bookPath)
if (modtime > bookmodtime):
book[1].dispose()
self.sessions[currentSerial][1].remove(book)
else:
currentBook = i
break
except:
self.logger.error("El libro "+currentBook+" no existe!")

if (currentBook < 0 ):
handler = self.desktop.loadComponentFromURL( "file://" + bookPath ,"_blank",0,())

if(handler == None):
raise Exception('El libro no existe o tiene caracteres extraños...')

modtime = os.path.getmtime(bookPath)

estruct = [bookPath,handler,modtime]
self.sessions[currentSerial][1].append(estruct)
currentBook = len(self.sessions[currentSerial][1])-1

return currentBook

def closeBook(self, sessionID, bookID):

books = self.sessions[sessionID][1]

# Close the document. It doesn't look very elegant but thats the way is documented.
books[bookID][1].dispose()
self.sessions[sessionID][1].remove(books[bookID])

return 1

def getBookSheets(self, sessionID, bookID):
"""
This method return an array with the book's worksheets.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()

$sheetsQuery = array( new XML_RPC_VALUE($sessionID, "int"), new XML_RPC_VALUE($bookID, "int") );
$sheets = queryXMLRPC($client, "getBookSheets" , $sheetsQuery);
return $sheets;
"""

sheets = self.sessions[sessionID][1][bookID][1].getSheets().createEnumeration()

container = []
while(sheets.hasMoreElements()):
currentSheet = sheets.nextElement()
container.append(currentSheet.getName().encode("UTF-8"))

return container

def getCellValue (self,sheet,x,y):

cell = sheet.getCellByPosition(x,y)
cellType = cell.getType()

if cellType == self.TEXT :
data = cell.getString().encode("UTF-8")
if data == None:
return ""
return data.encode("UTF-8")

if cellType == self.FORMULA or cellType == self.VALUE :
data = cell.getValue()
if data == None:
return 0
return cell.getValue()

if cellType == self.EMPTY :
return ""

def getCell(self, session, book, sheet, x, y):
"""
This method returns the content of a cell.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()
- $sheet is the sheet's ID as returned by getBookSheets()

$query = array(
new XML_RPC_Value($sessionID, "int"),
new XML_RPC_VALUE($bookID, "int"),
new XML_RPC_VALUE($sheet, "int"),
new XML_RPC_Value($x, "int"),
new XML_RPC_Value($y, "string")
);

$result = queryXMLRPC($client, "getCell", $query);
return $result;
"""

sheetref = self.sessions[session][1][book][1].getSheets().getByIndex(sheet)
valor = self.getCellValue(sheetref,x,y)
return valor

def setCell(self,session,book,sheet,x,y,value):
"""
This method sets the content of a cell.
Sample usage from PHP:
- $sessionID is the session's ID returned by openSession()
- $bookID is the book's ID returned by openBook()
- $sheet is the sheet's ID as returned by getBookSheets()

$query = array(
new XML_RPC_Value($sessionID, "int"),
new XML_RPC_VALUE($bookID, "int"),
new XML_RPC_VALUE($sheet, "int"),
new XML_RPC_Value($x, "int"),
new XML_RPC_Value($y, "int"),
new XML_RPC_Value($value, "string")
);

$result = queryXMLRPC($client, "setCell", $query);
return $result;
"""

bookObject = self.sessions[session][1][book][1]
cell = bookObject.getSheets().getByIndex(sheet).getCellByPosition(x,y)
cell.setValue(value)
return 1

#what will change? mmm...
def massiveSetCell(self, data):
for valores in data:
session,sheetid,x,y,valor = valores.split("|")
code = self.setCell(self.trim(session),self.trim(sheetid),self.trim(x),self.trim(y),valor)
if code < 0:
return code
return 1

def getSheetPreview(self,session,book,sheet):

sheet = self.sessions[session][1][book][1].getSheets().getByIndex(sheet)
range = sheet.getCellRangeByPosition(0,0,8,23).getDataArray()
return range

def trim(self, cadena):
return cadena.strip()

server = PyUNOServer(("localhost", 8000))

server.init()
server.logger.info("Servicio Inicializado...")

try:
server.serve_forever()
except KeyboardInterrupt:
server.logger.info("Cerrando el socket...")
server.server_close()
os.kill(server.PID,1)
server.logger.info("Socket cerrado.")
</source>

==startPyUnoServer.sh2==
<source lang=bash>
#!/bin/bash
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/openoffice/program/
export PYTHONPATH=$PYTHONPATH:/usr/lib/openoffice/program
export DISPLAY=localhost:1
echo "Logging en pyUnoServer.log"
python pyUnoServerV2.py
echo "Ciao!"
</source>

[[Category:Python]]

PyUNO bridge

2008-03-17T08:26:58Z

Andrewb: replace <code> woth <source> markup

==Translations ==

Find here a shortened Spanish version of this document.
===Introduction===

The Python-UNO bridge allows to
* use the standard OpenOffice.org API from the well known python scripting language.
* to develop UNO components in python, thus python UNO components may be run within the OpenOffice.org process and can be called from Java, C++ or the built in StarBasic scripting language.
* create and invoke scripts with the office scripting framework (OOo 2.0 and later).

You can find the most current version of this document from http://udk.openoffice.org/python/python-bridge.html
=====Download =====

You can also download this documentation for offline work.

Download [http://udk.openoffice.org/python/pyuno-doc.zip pyuno-doc.zip] ( less than 0.5 MB).
=====State =====

The '''Python-UNO bridge''' is feature complete, but has not been used extensively, so it may contain some bugs. It is now integrated in the OpenOffice.org source trees. (OpenOffice.org 1.0.x is not supported.)

The documentation in its current state is targeted at developers who have already some experience with '''OpenOffice.org API''' and with some other programming language (Java/C++/StarBasic). It is recommended that you read that some background information from the '''developer manual''' before looking at the specifics of python.

===PyUNO tutorial for OpenOffice.org ===
This tutorial shows, how the '''PyUNO bridge''' can be used to automate OpenOffice.org. This is not an OpenOffice.org tutorial, there is lots of resources available in the office development kit and the developer manual.
=====PyUNO Installation =====
Since OpenOffice.org 1.1, '''PyUNO''' is included in the default installation.
=====PyUNO bridge modes =====

PyUNO can be used in three different modes:
* Inside the OpenOffice.org process within the scripting framework (OOo 2.0 and later only !!),
* Inside the python executable (and outside the OOo process)
[[Image:Mode_ipc.png]]

Use this mode, when you
* begin to use PyUNO (as it is the more intuitive approach).
* want to trigger script execution by starting a separate process (e.g. a cgi-script within a http-server).
* want the shortest turnaround times (code - execute - code - execute ...)

=====Hello World =====

Make sure, that OpenOffice.org is not running (note that on windows you must also terminate the '''quick starter''' in the '''system tray''' at the right bottom of your desktop). Start a '''system shell''' ( cmd on Win NT/2000/XP, command on Win9x, '''tcsh or bash''' on Unix). Switch to the '''Office program directory''' (e.g. C:\Program Files\OpenOffice.org 2.4\program ) and start the office with the following '''command line''' parameters

c:\Program Files\OpenOffice.org 2.4\program> soffice "-accept=socket,host=localhost,port=2002;urp;"

Now use your favourite text editor to create the following '''hello_world.py''' sample program:

<source lang=python>
import uno

""" Here is the sequence of things the lines do:
1. get the uno component context from the PyUNO runtime
2. create the UnoUrlResolver
3. get the central desktop object
4. Declare the ServiceManager
5. get the central desktop object
6. access the current writer document
7. access the document's text property
8. create a cursor
9. insert the text into the document """

localContext = uno.getComponentContext()
resolver = localContext.ServiceManager.createInstanceWithContext(
"com.sun.star.bridge.UnoUrlResolver", localContext )
ctx = resolver.resolve( "uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext" )
smgr = ctx.ServiceManager
desktop = smgr.createInstanceWithContext( "com.sun.star.frame.Desktop",ctx)
model = desktop.getCurrentComponent()
text = model.Text
cursor = text.createTextCursor()

text.insertString( cursor, "Hello World", 0 )

""" Do a nasty thing before exiting the python process. In case the
last call is a oneway call (e.g. see idl-spec of insertString),
it must be forced out of the remote-bridge caches before python
exits the process. Otherwise, the oneway call may or may not reach
the target object.
I do this here by calling a cheap synchronous call (getPropertyValue)."""
ctx.ServiceManager
</source>

Now start the above script with the '''python script''' located in the program directory

c:\Program Files\OpenOffice1.1\program> .\python hello_world.py

Note: You must use the script/batch file in the program directory to '''start python''', simply starting the '''python executable''' in the runtime directory (or from '''python installation''' installed somewhere else on your machine) will not work.

This scripts prints "Hello World" into the '''current writer document'''.

[[Image:Mode_component.png]]
[[Category:Python]]

PrinttoWriter.py

2008-03-17T08:21:56Z

Andrewb: changed [code] to <source> markup

==Danny.OOo.PrintToWriter.py ==

This makes it easy and convenient to '''print''' a bunch of text into a Writer document.

See the example routine in the module that shows how easy this module is to use, and how useful it can be.

<source lang=python>
#**********************************************************************
# If you make changes, please append to the change log below.
#
# Change Log
# Danny Brewer Revised 2004-06-05-01
#
#**********************************************************************

# OOo's libraries
import uno

# Danny's libraries
from Danny.OOo.OOoLib import StarDesktop

com_sun_star_text_ControlCharacter_PARAGRAPH_BREAK = uno.getConstantByName( "com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK" )
com_sun_star_text_ControlCharacter_LINE_BREAK = uno.getConstantByName( "com.sun.star.text.ControlCharacter.LINE_BREAK" )
com_sun_star_text_ControlCharacter_HARD_HYPHEN = uno.getConstantByName( "com.sun.star.text.ControlCharacter.HARD_HYPHEN" )
com_sun_star_text_ControlCharacter_SOFT_HYPHEN = uno.getConstantByName( "com.sun.star.text.ControlCharacter.SOFT_HYPHEN" )
com_sun_star_text_ControlCharacter_HARD_SPACE = uno.getConstantByName( "com.sun.star.text.ControlCharacter.HARD_SPACE" )
com_sun_star_text_ControlCharacter_APPEND_PARAGRAPH = uno.getConstantByName( "com.sun.star.text.ControlCharacter.APPEND_PARAGRAPH" )

class PrintToWriter:
"""A class which allows conveniently printing stuff into a Writer document.
Very useful for debugging, general output purposes, or even for creating reports."""
def __init__( self ):
self.oWriterDoc = StarDesktop.loadComponentFromURL( "private:factory/swriter", "_blank", 0, () )
self.oWriterText = self.oWriterDoc.getText()
self.oWriterCursor = self.oWriterText.createTextCursor()

def writeLn( self, *args ):
if len( args ) > 0:
apply( self.write, args )
self.writeParagraphBreak()

def write( self, arg1, *argsRest ):
self.writeOne( arg1 )
for arg in argsRest:
self.writeTab()
self.writeOne( arg )

def writeOne( self, arg, bAbsorb=False ):
self.writeString( str( arg ), bAbsorb )

def writeTab( self, bAbsorb=False ):
self.writeString( "\t", bAbsorb )

def writeParagraphBreak( self, bAbsorb=False ):
self.writeControlCharacter( com_sun_star_text_ControlCharacter_PARAGRAPH_BREAK, bAbsorb )

def writeString( self, cString, bAbsorb=False ):
self.oWriterText.insertString( self.oWriterCursor, cString, bAbsorb )

def writeControlCharacter( self, nCtrlChar, bAbsorb=False ):
self.oWriterText.insertControlCharacter( self.oWriterCursor, nCtrlChar, bAbsorb )

def example_PrintToWriter():
"""An example of how to use the PrintToWriter class to trivially create
a new Writer document, and write out text into it."""
oOutput = PrintToWriter()
oOutput.writeLn( "Hello World" )
oOutput.write( "String", 123, 456.23, True )
oOutput.writeLn()
oOutput.writeLn()

oOutput.writeLn( "Tab delimited values..." )

oOutput.write( 123 )
oOutput.writeTab()
oOutput.write( 456 )
oOutput.writeTab()
oOutput.write( 789 )
oOutput.writeLn()

oOutput.write( 465 )
oOutput.writeTab()
oOutput.write( 522 )
oOutput.writeTab()
oOutput.write( 835 )
oOutput.writeLn()

oOutput.write( 886 )
oOutput.writeTab()
oOutput.write( 164 )
oOutput.writeTab()
oOutput.write( 741 )
oOutput.writeLn()
</source>
== How it Works ==
PrintToWriter.py code is really just a way to:
* create the enviroment
* create a document
* generate the content
* insert it within a document

So first we need to create the '''enviroment''' so that we don't generate a verbose code, we need to insert it into variable.

To create the enviroment we need a couple of things, first we import a library, which already save us a bunch of code in order to reference to UNO. The next step is to choose the fomat element we will need to input. For tha we use the uno.getConstantByName and point to the [http://api.openoffice.org/docs/common/ref/com/sun/star/text/ControlCharacter.html ControlCharacter] component which includes all the format we need.

* Paragraph Break - Insert a paragraph break
* Line Break - Inserts a line break inside of the paragraph
* Hard Hyphen - A character that appears like a dash, but prevents hyphenation at its position
* Soft Hyphen - Marks a preferred position for hyphenation
* Hard Space - A character that appears like a space, but prevents hyphenation at this point
* Append Paragraph - A new paragraph is appended

The next step is to generate the class for '''PrintToWriter''', this is the class that this file is about. Then we need to load the writer component, on like 59. We use the '''getText()''' function so we can access the text area from the writer's component. Once we are there, we explicity activate the Cursor.

We go on using the following functions:

* writeLn = Insert a break on end of Line
* write =
* writeOne = Write String
* writeTab = Insert a '''\t''' value as a string
* writeParagraphBreak = we call on the PARAGRAPH_BREAK component
* writeString = We use cString after the Cursor
* writeControlCharacter = nCtrlChar

The example_PrinterToWrite is basically we execute the functtons we create under the '''PrintToWriter class'''. This will be enough for you to see how we can use the functions to insert content and how it works the different funmction.

[[Category:Python]]

Python as a macro language

2008-03-17T08:04:03Z

Andrewb: minor grammar cleanups. One question added.

Pyuno supports the OOo scripting framework which first shipped with OOo 2.0. The current support is limited to the '''core framework''', meaning that execution and assigning of macros via the standard Tools/Macro dialog works fine, but editing and debugging macros is not integrated in OpenOffice.org's UI (simply because of the lack of development resources). Use your favourite text editor to create and modify python scripts.

== Script Location ==
Scripts to be excuted in OpenOffice.org can be stored within the following locations:
[[Image:Macro_run_dlg.PNG]]

===OpenOffice.org's user directory===

This is the standard place for self written python scripts. The script files are simply stored within the file system. On windows, the directory can typically be found in:

* windows - '''C:\Documents and Settings\<current-user\>Application Data\OpenOffice.org 2.0\user\Scripts\python'''
* unix - '''~/.openoffice.org.2.0/user/Scripts/python'''

Note, that the last python subdirectory may need to be created initially. Make sure, the python is completly written lowercase. You can add arbitrary deeply nested subdirectories, the names of these directories are reflected in the UI.

Example: The [http://udk.openoffice.org/python/scriptingframework/dynamicDialog.py dynamicDialog.py] file can simply be placed in the above directory. Afterwards, open the ''Tools/Macros/Run macro dialog'' and navigate to the position shown in the above picture. Click on Run to execute the python script, which opens another dialog with a push button and a label field. Clicking the button will increase the number within the label field. The dialog can be closed by pressing ESC.

===OpenOffice.org's share directory===

Scripts that shall be shared throughout all users of a concrete OpenOffice.org installation can be stored with the share directory. All default scripts coming with OpenOffice.org are located here. In general, this directory should not be used for script deployment (see later uno-packages).

The script files are simply stored within the file system. The directory can typically be found in
* windows '''C:\Program Files\OpenOffice.org 2.0\share\Scripts\python'''
* unix '''/usr/lib/openoffice/share/Scripts/python'''

===Embedded within an OpenOffice.org's document===

An OpenOffice.org document is a zip-File, which contains different files. Python scripts within documents are stored in Scripts/python subdirectory.

If you want to ship your self written python scripts within a document, you should first develop your scripts in the (above mentioned) user directory and then finally move the scripts into the document with your favorite zip tool. However, note that you must reassign every binding you did before to the script instances in the document. Ideally, you move away the scripts from the user directory and do a regression test on the document's functionality.

After moving the script files into the document, you have to add some lines (boldly printed) to the ''META-INF/manifest.xml'' file:
<source lang=xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.oasis.opendocument.text" manifest:full-path="/"/>
<manifest:file-entry manifest:media-type="application/vnd.sun.xml.ui.configuration" manifest:full-path="Configurations2/"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Pictures/"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="content.xml"/>
<manifest:file-entry :media-type="text/xml" manifest:full-path="styles.xml"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="meta.xml"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/thumbnail.png"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="settings.xml"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Scripts/python/push_me.py"/>
<manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/python/"/>
<manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/"/>
</manifest:manifest>
</source>
When you open the document afterwards, the OpenOffice.org's UI should warn you about script content within the document (when this is not the case, you either have switched off the warning in the options or you did something wrong).

Example:To see how it works, download push_me_python4.odt. The document contains a push button and a multi line edit control. Pressing the button adds a new line with the current time stamp to the multi line edit control.

===Embedded within a uno-package in OpenOffice.org's user directory (read only)===

Often, distributing scripts in documents is not what you want (for instance when you want to modify the application itself or you want to use the same scripts with multiple documents ). Therefor you can place your scripts simply within uno-packages.

A uno-package is a zip-file. Its name must end with .pkg, otherwise it does not work. file, where you must define the subdirectory (required!) that shall contain scripts. For instance the sample [http://udk.openoffice.org/python/scriptingframework/pyhello2.uno.pkg pyhello2.uno.pkg] has the following file structure:
<source lang=bash>
META-INF/
META-INF/manifest.xml
package/
package/hallo.py
</source>
The hallo.py contains the scripts. How to write scripts is explained below. However, in order to make a script work within a uno package, you must add some dummy code.
<source lang=python>
# ... here is the python script code

# this must be added to every script file (the
# name org.openoffice.script.DummyImplementationForPythonScripts should be changed to something
# different (must be unique within an office installation !)
# --- faked component, dummy to allow registration with unopkg, no functionality expected
import unohelper
g_ImplementationHelper = unohelper.ImplementationHelper()
g_ImplementationHelper.addImplementation( \
None,"org.openoffice.script.DummyImplementationForPythonScripts", \
("org.openoffice.script.DummyServiceForPythonScripts",),)
</source>
By default, every .py-file is interpreted as a UNO component. Not having the above lines within the .py file would raise errors during deployment.

The directory name (here package) can be choosen freely. A uno-package with a python script must contain a META-INF/manifest.xml, which needs to point to the freely chosen directory name.
<source lang=xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.sun.star.framework-script" manifest:full-path="package"/>
</manifest:manifest>
</source>
Every user can add packages via the package manager (Tools/Package manager). Note, that content within the package is by design readonly, it is really a pure deployment, not a development mechanism. This might be the reason, why scripts in packages cannot be viewed via Tools/Macros/Organize macros/Python dialog.
Embedded within a uno-package in OpenOffice.org's share directory (read only)

Packages can be added by an administrator to a complete OpenOffice.org installation, so that every user can use run the macros located within the package. This can be done with the unopkg tool.

==Script coding==
A python script within the OpenOffice.org's scripting framework is a function (introduced by the def keyword) within a .py file. For execution via the ''Tools/Macros/Run macro dialog'', the script must have an empty argument list. For typical event listeners, the function must have exactly one argument (the event). In general, the number of arguments depend on the context where the function shall be used. Currently, the .py file must use unix line feeds, this will be changed in future.

A single .py file may contain an arbitrary number of function definitions. By default, all function definitions are exported ( = shown in the macro selection dialog). As this may become tedious, exports can be limited to a smaller set of functions by having a global variable named g_exportedScripts, which is a tuple of function definitions.

At the current integration level, .py files can only import python modules which are within the python PYTHONPATH. By default this is just the python runtime with its standard libraries and the uno bridge files. This means that python macros cannot reference other python macro files. This limitation may be changed in future but exists currently. Python macros can, of course, import from any module you place in the PYTHONPATH; but you must do that yourself and the results will not be portable.

''(a reader wonders: couldn't the pythonloader automatically append the OOo scripting dirs to PYTHONPATH?)''

Before executing the source code within the module, the global variable XSCRIPTCONTEXT is inserted as global variable within the module (this variable also exists e.g. for javascript and beanshell, it is offered here for consistency reasons). It has three members (Document,Desktop and ComponentContext).

The comment of a function (introduced and ended by three ") is shown as description in the macros' selection dialog.

The compiled python script files are not added to sys.modules. There may exist multiple instances of the same module at the same time.
Example:
<source lang=python>
# HelloWorld python script for the scripting framework

def HelloWorldPython( ):
"""Prints the string 'Hello World(in Python)' into the current document"""
#get the doc from the scripting context which is made available to all scripts
model = XSCRIPTCONTEXT.getDocument()
text = model.Text
cursor = text.createTextCursor()
text.insertString( cursor, "Hello World(in Python)", 0 )
</source>
==Error handling and debugging==
Errors during compilation or execution of the scripts are passed as exceptions to the scripting framework where possible. The scripting framework in general opens a popup box and displays the message of the thrown exception.

However, sometimes this is not possible and an error gets silently ignored. The user realizes these errors, when
* his python script file does not appear where it is expected to be
* the name of the script file appears, but it does not contain any scripts
* only part of the script gets executed.

You can get to know these problems by changing some flags in the '''OpenOffice.org 2.0/program/pythonscript.py''' file :

<source lang=python>
# Configuration ----------------------------------------------------
LogLevel.use = LogLevel.NONE # alternavly use LogLevel.ERROR or LogLevel.DEBUG
LOG_STDOUT = False # True, writes to stdout
# False, writes to user/Scripts/python/log.txt
ENABLE_EDIT_DIALOG=False # offers a minimal editor for editing.
</source>
Attaching a python debugger is currently not supported.

==Credits==
The python binding of the scripting framework is developed and maintained by Joerg Budischewski in his spare time. Many, many thanks to Tomas O'Connor from Sun for his great support and his code additions to the framework which made this binding possible. Please put low level questions about the binding to dev@udk.openoffice.org. Questions about the OpenOffice.org's API should be put to dev@api.openoffice.org.

[[Category:Python]]
[[Category:Uno]]

Python as a macro language

2008-03-16T20:47:43Z

Andrewb:

Pyuno supports the OOo scripting framework, that is first shipped with OOo 2.0. The current support is limited to the '''core framework''', meaning that execution and assigning of macros via the standard Tools/Macro dialog works fine, but editing and debugging macros is not integrated in OpenOffice.org's UI (simply because of the lack of development resources). Use your favourite text editor to create and modify python scripts.

== Script Location ==
Scripts to be excuted in OpenOffice.org can be stored within the following locations:
[[Image:Macro_run_dlg.PNG]]

===OpenOffice.org's user directory===

This is the standard place for self written python scripts. The script files are simply stored within the file system. On windows, the directory can typically be found in:

* windows - '''C:\Documents and Settings\<current-user\>Application Data\OpenOffice.org 2.0\user\Scripts\python'''
* unix - '''~/.openoffice.org.2.0/user/Scripts/python'''

Note, that the last python subdirectory may need to be created initially. Make sure, the python is completly written lowercase. You can add arbitrary deeply nested subdirectories, the names of these directories are reflected in the UI.

Example: The [http://udk.openoffice.org/python/scriptingframework/dynamicDialog.py dynamicDialog.py] file can simply be placed in the above directory. Afterwards, open the ''Tools/Macros/Run macro dialog'' and navigate to the position shown in the above picture. Click on Run to execute the python script, which opens another dialog with a push button and a label field. Clicking the button will increase the number within the label field. The dialog can be closed by pressing ESC.

===OpenOffice.org's share directory===

Scripts that shall be shared throughout all users of a concrete OpenOffice.org installation can be stored with the share directory. All default scripts coming with OpenOffice.org are located here. In general, this directory should not be used for script deployment (see later uno-packages).

The script files are simply stored within the file system. The directory can typically be found in
* windows '''C:\Program Files\OpenOffice.org 2.0\share\Scripts\python'''
* unix '''/usr/lib/openoffice/share/Scripts/python'''

===Embedded within an OpenOffice.org's document===

An OpenOffice.org document is a zip-File, which contains different files. Python scripts within documents are stored in Scripts/python subdirectory.

If you want to ship your self written python scripts within a document, you should first develop your scripts in the (above mentioned) user directory and then finally move the scripts into the document with your favorite zip tool. However, note that you must reassign every binding you did before to the script instances in the document. Ideally, you move away the scripts from the user directory and do a regression test on the document's functionality.

After moving the script files into the document, you have to add some lines (boldly printed) to the ''META-INF/manifest.xml'' file:
<source lang=xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.oasis.opendocument.text" manifest:full-path="/"/>
<manifest:file-entry manifest:media-type="application/vnd.sun.xml.ui.configuration" manifest:full-path="Configurations2/"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Pictures/"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="content.xml"/>
<manifest:file-entry :media-type="text/xml" manifest:full-path="styles.xml"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="meta.xml"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/thumbnail.png"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="settings.xml"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Scripts/python/push_me.py"/>
<manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/python/"/>
<manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/"/>
</manifest:manifest>
</source>
When you open the document afterwards, the OpenOffice.org's UI should warn you about script content within the document (when this is not the case, you either have switched off the warning in the options or you did something wrong).

Example:To see how it works, download push_me_python4.odt. The document contains a push button and a multi line edit control. Pressing the button adds a new line with the current time stamp to the multi line edit control.

===Embedded within a uno-package in OpenOffice.org's user directory (read only)===

Often, distributing scripts in documents is not what you want (for instance when you want to modify the application itself or you want to use the same scripts with multiple documents ). Therefor you can place your scripts simply within uno-packages.

A uno-package is a zip-file. Its name must end with .pkg, otherwise it does not work. file, where you must define the subdirectory (required!) that shall contain scripts. For instance the sample [http://udk.openoffice.org/python/scriptingframework/pyhello2.uno.pkg pyhello2.uno.pkg] has the following file structure:
<source lang=bash>
META-INF/
META-INF/manifest.xml
package/
package/hallo.py
</source>
The hallo.py contains the scripts. How to write scripts is explained below. However, in order to make a script work within a uno package, you must add some dummy code.
<source lang=python>
# ... here is the python script code

# this must be added to every script file (the
# name org.openoffice.script.DummyImplementationForPythonScripts should be changed to something
# different (must be unique within an office installation !)
# --- faked component, dummy to allow registration with unopkg, no functionality expected
import unohelper
g_ImplementationHelper = unohelper.ImplementationHelper()
g_ImplementationHelper.addImplementation( \
None,"org.openoffice.script.DummyImplementationForPythonScripts", \
("org.openoffice.script.DummyServiceForPythonScripts",),)
</source>
By default, every .py-file is interpreted as a UNO component. Not having the above lines within the .py file would raise errors during deployment.

The directory name (here package) can be choosen freely. A uno-package with a python script must contain a META-INF/manifest.xml, which needs to point to the freely chosen directory name.
<source lang=xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.sun.star.framework-script" manifest:full-path="package"/>
</manifest:manifest>
</source>
Every user can add packages via the package manager (Tools/Package manager). Note, that content within the package is by design readonly, it is really a pure deployment, not a development mechanism. This might be the reason, why scripts in packages cannot be viewed via Tools/Macros/Organize macros/Python dialog.
Embedded within a uno-package in OpenOffice.org's share directory (read only)

Packages can be added by an administrator to a complete OpenOffice.org installation, so that every user can use run the macros located within the package. This can be done with the unopkg tool.

==Script coding==
A python script within the OpenOffice.org's scripting framework is a function (introduced by the def keyword) within a .py file. For execution via the ''Tools/Macros/Run macro dialog'', the script must have an empty argument list. For typical event listeners, the function must have exactly one argument (the event). In general, the number of arguments depend on the context where the function shall be used. Currently, the .py file must use unix line feeds, this will be changed in future.

A single .py file may contain an arbitrary number of function definitions. By default, all function definitions are exported ( = shown in the macro selection dialog). As this may become tedious, exports can be limited to a smaller set of functions by having a global variable named g_exportedScripts, which is a tuple of function definitions.

At the current integration level, .py files can only import python modules, which are within the python PYTHONPATH, by default this is just the python runtime and the uno bridge files. This means, that it cannot reference other python macro files. This limitation may be changed in future but exists currently.

Before executing the source code within the module, the global variable XSCRIPTCONTEXT is inserted as global variable within the module (this variable also exists e.g. for javascript and beanshell, it is offered here for consistency reasons). It has three members (Document,Desktop and ComponentContext).

The comment of a function (introduced and ended by three ") is shown as description in the macros' selection dialog.

The compiled python script files are not added to sys.modules. There may exist multiple instances of the same module at the same time.
Example:
<source lang=python>
# HelloWorld python script for the scripting framework

def HelloWorldPython( ):
"""Prints the string 'Hello World(in Python)' into the current document"""
#get the doc from the scripting context which is made available to all scripts
model = XSCRIPTCONTEXT.getDocument()
text = model.Text
cursor = text.createTextCursor()
text.insertString( cursor, "Hello World(in Python)", 0 )
</source>
==Error handling and debugging==
Errors during compilation or execution of the scripts are passed as exceptions to the scripting framework where possible. The scripting framework in general opens a popup box and displays the message of the thrown exception.

However, sometimes this is not possible and an error gets silently ignored. The user realizes these errors, when
* his python script file does not appear where it is expected to be
* the name of the script file appears, but it does not contain any scripts
* only part of the script gets executed.

You can get to know these problems by changing some flags in the '''OpenOffice.org 2.0/program/pythonscript.py''' file :

<source lang=python>
# Configuration ----------------------------------------------------
LogLevel.use = LogLevel.NONE # alternavly use LogLevel.ERROR or LogLevel.DEBUG
LOG_STDOUT = False # True, writes to stdout
# False, writes to user/Scripts/python/log.txt
ENABLE_EDIT_DIALOG=False # offers a minimal editor for editing.
</source>
Attaching a python debugger is currently not supported.

==Credits==
The python binding of the scripting framework is developed and maintained by Joerg Budischewski in his spare time. Many, many thanks to Tomas O'Connor from Sun for his great support and his code additions to the framework which made this binding possible. Please put low level questions about the binding to dev@udk.openoffice.org. Questions about the OpenOffice.org's API should be put to dev@api.openoffice.org.

[[Category:Python]]
[[Category:Uno]]

Python as a macro language

2008-03-16T20:45:59Z

Andrewb: cleaned code markup

Pyuno supports the OOo scripting framework, that is first shipped with OOo 2.0. The current support is limited to the '''core framework''', meaning that execution and assigning of macros via the standard Tools/Macro dialog works fine, but editing and debugging macros is not integrated in OpenOffice.org's UI (simply because of the lack of development resources). Use your favourite text editor to create and modify python scripts.

== Script Location ==
Scripts to be excuted in OpenOffice.org can be stored within the following locations:
[[Image:Macro_run_dlg.PNG]]

===OpenOffice.org's user directory===

This is the standard place for self written python scripts. The script files are simply stored within the file system. On windows, the directory can typically be found in:

* windows - '''C:\Documents and Settings\<current-user\>Application Data\OpenOffice.org 2.0\user\Scripts\python'''
* unix - '''~/.openoffice.org.2.0/user/Scripts/python'''

Note, that the last python subdirectory may need to be created initially. Make sure, the python is completly written lowercase. You can add arbitrary deeply nested subdirectories, the names of these directories are reflected in the UI.

Example: The [http://udk.openoffice.org/python/scriptingframework/dynamicDialog.py dynamicDialog.py] file can simply be placed in the above directory. Afterwards, open the ''Tools/Macros/Run macro dialog'' and navigate to the position shown in the above picture. Click on Run to execute the python script, which opens another dialog with a push button and a label field. Clicking the button will increase the number within the label field. The dialog can be closed by pressing ESC.

===OpenOffice.org's share directory===

Scripts that shall be shared throughout all users of a concrete OpenOffice.org installation can be stored with the share directory. All default scripts coming with OpenOffice.org are located here. In general, this directory should not be used for script deployment (see later uno-packages).

The script files are simply stored within the file system. The directory can typically be found in
* windows '''C:\Program Files\OpenOffice.org 2.0\share\Scripts\python'''
* unix '''/usr/lib/openoffice/share/Scripts/python'''

===Embedded within an OpenOffice.org's document===

An OpenOffice.org document is a zip-File, which contains different files. Python scripts within documents are stored in Scripts/python subdirectory.

If you want to ship your self written python scripts within a document, you should first develop your scripts in the (above mentioned) user directory and then finally move the scripts into the document with your favorite zip tool. However, note that you must reassign every binding you did before to the script instances in the document. Ideally, you move away the scripts from the user directory and do a regression test on the document's functionality.

After moving the script files into the document, you have to add some lines (boldly printed) to the ''META-INF/manifest.xml'' file:
<source lang=xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.oasis.opendocument.text" manifest:full-path="/"/>
<manifest:file-entry manifest:media-type="application/vnd.sun.xml.ui.configuration" manifest:full-path="Configurations2/"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Pictures/"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="content.xml"/>
<manifest:file-entry :media-type="text/xml" manifest:full-path="styles.xml"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="meta.xml"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/thumbnail.png"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/"/>
<manifest:file-entry manifest:media-type="text/xml" manifest:full-path="settings.xml"/>
<manifest:file-entry manifest:media-type="" manifest:full-path="Scripts/python/push_me.py"/>
<manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/python/"/>
<manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/"/>
</manifest:manifest>
</source>
When you open the document afterwards, the OpenOffice.org's UI should warn you about script content within the document (when this is not the case, you either have switched off the warning in the options or you did something wrong).

Example:To see how it works, download push_me_python4.odt. The document contains a push button and a multi line edit control. Pressing the button adds a new line with the current time stamp to the multi line edit control.

===Embedded within a uno-package in OpenOffice.org's user directory (read only)===

Often, distributing scripts in documents is not what you want (for instance when you want to modify the application itself or you want to use the same scripts with multiple documents ). Therefor you can place your scripts simply within uno-packages.

A uno-package is a zip-file. Its name must end with .pkg, otherwise it does not work. file, where you must define the subdirectory (required!) that shall contain scripts. For instance the sample [http://udk.openoffice.org/python/scriptingframework/pyhello2.uno.pkg pyhello2.uno.pkg] has the following file structure:
<code>[bash]
META-INF/
META-INF/manifest.xml
package/
package/hallo.py</code>
The hallo.py contains the scripts. How to write scripts is explained below. However, in order to make a script work within a uno package, you must add some dummy code.
<source lang=python>
# ... here is the python script code

# this must be added to every script file (the
# name org.openoffice.script.DummyImplementationForPythonScripts should be changed to something
# different (must be unique within an office installation !)
# --- faked component, dummy to allow registration with unopkg, no functionality expected
import unohelper
g_ImplementationHelper = unohelper.ImplementationHelper()
g_ImplementationHelper.addImplementation( \
None,"org.openoffice.script.DummyImplementationForPythonScripts", \
("org.openoffice.script.DummyServiceForPythonScripts",),)
</source>
By default, every .py-file is interpreted as a UNO component. Not having the above lines within the .py file would raise errors during deployment.

The directory name (here package) can be choosen freely. A uno-package with a python script must contain a META-INF/manifest.xml, which needs to point to the freely chosen directory name.
<source=xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.sun.star.framework-script" manifest:full-path="package"/>
</manifest:manifest>
</source>
Every user can add packages via the package manager (Tools/Package manager). Note, that content within the package is by design readonly, it is really a pure deployment, not a development mechanism. This might be the reason, why scripts in packages cannot be viewed via Tools/Macros/Organize macros/Python dialog.
Embedded within a uno-package in OpenOffice.org's share directory (read only)

Packages can be added by an administrator to a complete OpenOffice.org installation, so that every user can use run the macros located within the package. This can be done with the unopkg tool.

==Script coding==
A python script within the OpenOffice.org's scripting framework is a function (introduced by the def keyword) within a .py file. For execution via the ''Tools/Macros/Run macro dialog'', the script must have an empty argument list. For typical event listeners, the function must have exactly one argument (the event). In general, the number of arguments depend on the context where the function shall be used. Currently, the .py file must use unix line feeds, this will be changed in future.

A single .py file may contain an arbitrary number of function definitions. By default, all function definitions are exported ( = shown in the macro selection dialog). As this may become tedious, exports can be limited to a smaller set of functions by having a global variable named g_exportedScripts, which is a tuple of function definitions.

At the current integration level, .py files can only import python modules, which are within the python PYTHONPATH, by default this is just the python runtime and the uno bridge files. This means, that it cannot reference other python macro files. This limitation may be changed in future but exists currently.

Before executing the source code within the module, the global variable XSCRIPTCONTEXT is inserted as global variable within the module (this variable also exists e.g. for javascript and beanshell, it is offered here for consistency reasons). It has three members (Document,Desktop and ComponentContext).

The comment of a function (introduced and ended by three ") is shown as description in the macros' selection dialog.

The compiled python script files are not added to sys.modules. There may exist multiple instances of the same module at the same time.
Example:
<source lang=python>
# HelloWorld python script for the scripting framework

def HelloWorldPython( ):
"""Prints the string 'Hello World(in Python)' into the current document"""
#get the doc from the scripting context which is made available to all scripts
model = XSCRIPTCONTEXT.getDocument()
text = model.Text
cursor = text.createTextCursor()
text.insertString( cursor, "Hello World(in Python)", 0 )
</source>
==Error handling and debugging==
Errors during compilation or execution of the scripts are passed as exceptions to the scripting framework where possible. The scripting framework in general opens a popup box and displays the message of the thrown exception.

However, sometimes this is not possible and an error gets silently ignored. The user realizes these errors, when
* his python script file does not appear where it is expected to be
* the name of the script file appears, but it does not contain any scripts
* only part of the script gets executed.

You can get to know these problems by changing some flags in the '''OpenOffice.org 2.0/program/pythonscript.py''' file :

<source lang=python>
# Configuration ----------------------------------------------------
LogLevel.use = LogLevel.NONE # alternavly use LogLevel.ERROR or LogLevel.DEBUG
LOG_STDOUT = False # True, writes to stdout
# False, writes to user/Scripts/python/log.txt
ENABLE_EDIT_DIALOG=False # offers a minimal editor for editing.
</source>
Attaching a python debugger is currently not supported.

==Credits==
The python binding of the scripting framework is developed and maintained by Joerg Budischewski in his spare time. Many, many thanks to Tomas O'Connor from Sun for his great support and his code additions to the framework which made this binding possible. Please put low level questions about the binding to dev@udk.openoffice.org. Questions about the OpenOffice.org's API should be put to dev@api.openoffice.org.

[[Category:Python]]
[[Category:Uno]]

UNO component packaging

2008-03-08T18:30:58Z

Andrewb: code prettied; rewrote and corrected note about importing classes

=Python UNO component=
This page shows you how to pack and deploy already written UNO component. I'm using my ''Wavelet'' class as an example of a very simple component.

More detailed info is in the [[http://api.openoffice.org/docs/DevelopersGuide/Components/Components.htm Developers Guide]].

=Python loader=
The Python loader is not able load classes that are not it its own path. Thus it's necessary to copy any classes or modules you will use into the OPenOffice Python lib directory, and it may be necessary to restart OOo before they are picked up.

=Sample Python component=

==Wavelet class==
We will use my sample ''Wavelet'' class which replaces space with non breaking space before the Czech prepositions. Put the following code in the ''Wavelet.py'' file.

<source lang=python>

import uno
import unohelper
import string
from com.sun.star.task import XJobExecutor

class Wavelet( unohelper.Base, XJobExecutor ):
def __init__( self, ctx ):
self.ctx = ctx

def trigger( self, args ):
desktop = self.ctx.ServiceManager.createInstanceWithContext(
"com.sun.star.frame.Desktop", self.ctx )

doc = desktop.getCurrentComponent()

try:
search = doc.createSearchDescriptor()
search.SearchRegularExpression = True
search.SearchString = "\\<(k|s|v|z|o|u|i|a) "

found = doc.findFirst( search )
while found:
found.String = string.replace( found.String, " ", u"\xa0" )
found = doc.findNext( found.End, search)

except:
pass
</source>

==Wavelet class registration==
You have to tell the OpenOffice.org what is the main class of your component. Put the following code at the end of your ''Wavelet.py'' file.

<source lang=python>
g_ImplementationHelper = unohelper.ImplementationHelper()
g_ImplementationHelper.addImplementation(
Wavelet,
"name.vojta.openoffice.Wavelet",
("com.sun.star.task.Job",),)
</source>

=Component integration=

==Icons==
You can create your own icons for the Menu item or the Toolbar button. The easiest way is to create two true color BMP files - the first one should be 26×26 and the second one should be 16×16.

If you want to use alpha (transparent color), use ''#FF00FF'' (RGB) color.

This possibility is optional and you're not forced to create icons.

==Addons.xcu==
Component integration configuration is in the ''Addons.xcu'' file.

===Header===
The header of this file should contain:

<source lang=xml>
<?xml version="1.0" encoding="UTF-8"?>
<oor:component-data xmlns:oor="http://openoffice.org/2001/registry"
xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons"
oor:package="org.openoffice.Office">

<node oor:name="AddonUI">
</source>

===Office Menu Bar===
Following part creates new menu item ''Czech'' (or ''Cestina'', depends on the UI language) and the ''Wavelet'' menu item.

This menu item is associated with the ''name.vojta.openoffice.Wavelet?execute'' ''URL''. It means, that when you click on the menuitem, ''Wavelet.trigger'' method will be executed with the ''execute'' as an argument.

This menu will be visible in the OpenOffice.org Writer only.

<source lang=xml>
<node oor:name="OfficeMenuBar">
<node oor:name="name.vojta.openoffice.Wavelet" oor:op="replace">
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Czech</value>
<value xml:lang="cs">Cestina</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="ImageIdentifier" oor:type="xs:string">
<value/>
</prop>
<node oor:name="Submenu">
<node oor:name="m1" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>service:name.vojta.openoffice.Wavelet?execute</value>
</prop>
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Wavelet</value>
<value xml:lang="cs">Vlnka</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value>com.sun.star.text.TextDocument</value>
</prop>
</node>
</node>
</node>
</node>
</source>

===Office Toolbar===
Following part creates new toolbar (with name ''Add-on 1'', ''Add-on 2'', …) and one button. This button is associated with the ''name.vojta.openoffice.Wavelet?execute'' ''URL''. It means that the ''Wavelet.trigger'' method will be executed when you click on the button on the toolbar. ''execute'' will be passed as an argument.

'''Note:''' You can't rename the toolbar. It's due to the backwards compatibility with the 1.1.x version.

<source lang=xml>
<node oor:name="OfficeToolBar">
<node oor:name="name.vojta.openoffice.Wavelet" oor:op="replace">
<node oor:name="m1" oor:op="replace">
<prop oor:name="URL" oor:type="xs:string">
<value>service:name.vojta.openoffice.Wavelet?execute</value>
</prop>
<prop oor:name="ImageIdentifier" oor:type="xs:string">
<value/>
</prop>
<prop oor:name="Title" oor:type="xs:string">
<value/>
<value xml:lang="en-US">Wavelet</value>
<value xml:lang="cs">Vlnka</value>
</prop>
<prop oor:name="Target" oor:type="xs:string">
<value>_self</value>
</prop>
<prop oor:name="Context" oor:type="xs:string">
<value>com.sun.star.text.TextDocument</value>
</prop>
</node>
</node>
</node>
</source>

===Icons===
You can associate your icons with any ''URL''. We will associate our icons with ''name.vojta.openoffice.Wavelet?execute'' ''URL''. It means that all controls (menu item, button, …) associated with the same ''URL'' will use these icons.

'''Note:''' %origin% is the UNO component package. We will explain it later.

<source lang=xml>
<node oor:name="Images">
<node oor:name="name.vojta.openoffice.Wavelet.image1" oor:op="replace">
<prop oor:name="URL">
<value>service:name.vojta.openoffice.Wavelet?execute</value>
</prop>
<node oor:name="UserDefinedImages">
<prop oor:name="ImageSmallURL" oor:type="xs:string">
<value>%origin%/images/WaveletSmall.bmp</value>
</prop>
<prop oor:name="ImageBigURL" oor:type="xs:string">
<value>%origin%/images/WaveletBig.bmp</value>
</prop>
</node>
</node>
</node>
</source>

===Footer===
Close all opened sections.

<source lang=xml>
</node>
</oor:component-data>
</source>

=UNO component package=
UNO component package is a simple ZIP file. Obviously it contains the ''Addons.xcu'' file, ''images'' directory with icons and the Python component implementation.

==Packing==
You can pack our sample package with the following command:

<source lang=bash>
zip -r Wavelet.uno.zip Addons.xcu Wavelet.py images
</source>
The final ''Wavelet.uno.zip'' package should contain these files:

<source lang=bash>
Wavelet.uno.zip
Addons.xcu
Wavelet.py
images/WaveletBig.bmp
images/WaveletSmall.bmp
</source>
'''Note:''' The ''%origin%'' is ''Wavelet.uno.zip'', thus the ''%origin%/images/WaveletBig.bmp'' points to the ''WaveletBig.bmp'' file in your ''Wavelet.uno.zip'' file.

==Installation==
You can install your UNO component with the Extension manager (somewhere in the ''Tools'' menu) or with the ''unopkg'' tool.

<source lang=bash>
/opt/openoffice.org1.9.103/program/unopkg add Wavelet.uno.zip
</source>

==Uninstallation==
You can uninstall your UNO component with the Extension manager (somewhere in the ''Tools'' menu) or with the ''unopkg'' tool.

<source lang=bash>
/opt/openoffice.org1.9.103/program/unopkg remove Wavelet.uno.zip
</source>

=Python component testing=
It's not necessary to install the Python UNO component to test it. You can connect to the running OpenOffice.org instance and test your UNO component directly.

==Code==
Append the following code at the end of the ''Wavelet.py'' file.

<source lang=python>
if __name__ == "__main__":
import os

# Start OpenOffice.org, listen for connections and open testing document
os.system( "/etc/openoffice.org-1.9/program/soffice '-accept=socket,host=localhost,port=2002;urp;' -writer ./WaveletTest.odt &" )

# Get local context info
localContext = uno.getComponentContext()
resolver = localContext.ServiceManager.createInstanceWithContext(
"com.sun.star.bridge.UnoUrlResolver", localContext )

ctx = None

# Wait until the OO.o starts and connection is established
while ctx == None:
try:
ctx = resolver.resolve(
"uno:socket,host=localhost,port=2002;urp;StarOffice.ComponentContext" )
except:
pass

# Trigger our job
wavelet = Wavelet( ctx )
wavelet.trigger( () )
</source>

==Testing==
To test your UNO component, just run your ''Wavelet.py'' in the Python interpreter.

<source lang=bash>
/opt/openoffice.org1.9.103/program/python ./Wavelet.py
</source>

==Resume==
This part does this:

starts OpenOffice.org and opens the ''WaveletTest.odt'' file

loop until the connection will be established

start your component in the running OpenOffice.org context

'''Note:''' Do not forget to remove this part before real UNO component packaging. Or comment it out.

=See also=
* [http://api.openoffice.org/docs/DevelopersGuide/Extensions/Extensions.xhtml Extensions] chapter of the Developers Guide
* Using C++ with OOo SDK : [[Constructing_Components| Constructing Component in C++]]
*[[Tutorial_UNO_Library|UNO tutorial]]
*[[Tutorial_UNO_IDL|UNO IDL]]
* [[Uno/Article/Types%26Reflection]]
* Daniel Bölzle's [http://udk.openoffice.org/cpp/man/component_tutorial.html tutorial] : Writing a simple UNO component.
* [[UNO_component_packaging|Component with Python]]

[[Category:Uno]]
[[Category:Extensions]]