Apache OpenOffice Wiki - User contributions [en]

Bibliographic/Hints and Tips

2007-06-06T23:16:05Z

Iannz: /* How to load Zotero reference data into Openoffice. */

[[Bibliographic_Project | Back to Bibliographic Index]]
==How do I preserve my Bibliographic Table format settings ?==

When you have done all that hard work in setting up the bibliographic table with all the field entries and formatting set to your document style, I suggest that you select and copy the Bibliographic table and save it in a other document.

The reason I suggest this is that, if you accidentally delete the Bibliographic Table, then all your work in formatting the table will be deleted too. To use your Bibliographic Table formatting in an other document, just copy that table into new document, it does not matter that the references are different, just right click over the table and select 'Update Index/Table' for it to be regenerated with that documents' citations and your previously defined Bibliographic Table format.

==I edit my citations but the changes are not applied.==

When you modify a citation (Bibliography Entry) by double-clicking on the citation, and selecting edit and modifying the entry. You also need to click on the 'Modify' button to apply the changes before you select the 'Close' button.

==How do I correct the citations in my document?==

If you have inserted a citation (Bibliography Entry) may times in a document and need to correct it. Correcting it in the database is not enough. The changes are NOT automatically made in the document. In fact each citation has complete copy of the citation data and must be correct for each citation. You have several options:

1. Find each citation, delete it and reinsert it (after correcting it in the database). If you need to synchronize all your citations in the document with the ones in the database, you can use a keystroke macro recorder supporting auto-repitition of macros (e.g. [http://www.jitbit.com/macrorecorder.aspx JitBit Macro Recorder]). Record a macro for the "Insert Bibliography Entry" dialog to insert a single bibliography entry (and clicking "Yes", if it ought to be updated), finishing with progressing to the next entry. This macro can then be applied in a repetitive manner to the dialog to synchronize all citations. However, note, that this way you may pollute your document by adding all bibliography entries from the database.

2. Find each citation, double-clicking on the citation, select edit, make the corrections, close the edit panel, click the 'Modify' button to apply the changes before you select 'Close'.

3. If you have too many citations to change in this way then you can edit the save file. Make a backup of your file. Rename your xxx.odt file xxx.zip, open the zip archive and extract the contents.xml file, open that file in a writer. '''Very carefully''' do a global find and replace for your corrections. Save the contents.xml back into the zip archive. Rename xxx.zip xxx.odt. Hoping you have not destroyed your file, open it and check.

==Having your bibliography index automatically numbered==

To use numbered references like e.g. [1], which is common for scientific documents, you can change the formatting of the reference anchors / entries in the document by setting "Number entries" under Insert->Index and Tables->Index/Table. Your actual generated bibliography however will ''not'' be automatically numbered just by checking this field. This also cannot be activated in the "Entries" dialog (while the idea of inserting the "Number" Type in front of an entry looks tempting, this will not yield the correct result). Instead, you have to activate numbering on the corresponding bibliography style. In most cases this will be "Bibliography 1". Activate "Numbering" on the Paragraph Style pane.

== How can I Join multiple references? ==

Is there any (automatic) way to coalesce multiple bibliographic references onto a single one? I mean, something like [1-3,56,99] instead of [1][2][3][56][99]. As far as I have seen, there is no option in OOo to do that.[[User:Andvaranaut|CP]] 19:40, 22 May 2006 (CEST)

'''Answer'''
Yes, but not as automatically as you may like. There is an option in Inset->Indexes and Tables->Indexes and Tables:Type=Bibliography an option under the heading 'Formatting the entries' a pick-list for 'Brackets'. You can select NONE.

If you select Brackets=NONE then [1][2][3][56][99] becomes 1 2 3 56 99 and you can then manually insert the brackets and the commas to get the desired [1,2,3,56,99]. However there is currently no automatic support for specifying a range of citations like [1-3]. The problem is that if you manually deleted the citation 2 and put in a dash, the citation 2 may disappear from the Bibliography list if there are no other references to it. However, you could place citation 2 in a 'Hidden Paragraph' to ensure it stays in the Bibliography list for that document. See some [http://www.linuxjournal.com/node/9053/print instructions] on Hidden Paragraphs. [[User:Dnw|David Wilson]]

==Converting footnotes to endnotes==
It is easy to convert footnotes on the same page to endnotes at the end of the document by changing the 'Position' option on the Tools->Foot
notes..->Tab=Footnotes panel.

However, if you do this, there is some good advice from Judith Butcher, ''Copy-Editing, The Cambridge Handbook'', (Cambridge: CUP, 1975)-

"More information may have to be given in the notes now that they will not appear on the same page as the relevant text. A book title and a page number - or just a publication place and date - may be sufficient in a footnote if the other details are mentioned in the text; but it is irritating to have to keep checking back to the text from the endnotes if one is looking through the notes for a book mentioned earlier." p156

==How can I import or export Bibliographic data?==

[http://download.openoffice.org/2.0.4/index.html OpenOffice 2.0.4] Writer now includes a BibTeX export filter for citations in a document. You can access it at
File->Export->File Format='Bibtex (.bib)'.

If you are using a earlier version of OpenOffice OpenOffice you can add it yourself - [http://www.math.umd.edu/~dcarrera/openoffice/misc/bibtex/filter.html bibtex export filter]. If you need to convert other bibliographic formats use [[Bibliographic_Software_and_Standards_Information#Bibutils | bibutils]].

[[User:Dnw|David Wilson]] has written a bibliographic database filter to export the data in RIS format [http://bibliographic.openoffice.org/files/documents/124/3781/OOoRSIExport-1.py OOoRISExport.py] . It is my first python program so is not very good but seems to work. See the wiki page [[OOoRISExport.py]] for details

If you can download/export RIS (reference manager) format references from your data source, then the utility [http://bibliographic.openoffice.org/files/documents/124/3078/RISImport.py RISImport.py] may work better than a BibTeX utility. It is a Python script for importing RIS format reference(s), RISImport.py. Possibly of some value as it hashes out some RIS details on mapping between fields, and suggests "sensitive" mapping for different reference types." For more hints see [[Bibliographic_Hints_and_Tips#How_to_load_Zotero_reference_data_into_Openoffice |How to load Zotero reference data into Openoffice]] below.

If this is not suitable then an option is to use a third-party bibliographic application that will export to an OpenOffice Bibliographic database in the text bibliographic database CSV format. (OpenOffice looks for a database called Bibliography with the correct fields - it does not care what type of database it is.) I have used [[Bibliographic_Software_and_Standards_Information#JabRef | Jabref]] and [[Bibliographic_Software_and_Standards_Information#B3 | B3]]. [[Bibliographic_Software_and_Standards_Information#Bibus | Bibus]] is another possibility. [[User:Dnw|David Wilson]]

You may also use [[Bibliographic_Software_and_Standards_Information#refbase | refbase]] to [http://openoffice.refbase.net/ export your references] directly to an OpenOffice Bibliographic database in OpenDocument spreadsheet (.ods) format.

===Avoiding duplicate bibliographic records in the database===

The RISImport.py bibliographic data import program does not check for duplicates. If there is more than one bibliographic database entry with the same identifier the OOo bibliographic functions will only find the first occurrence. To avoid this confusion I suggest that you modify your database table to add unique index using the identifier as a key. This will prevent the adding of duplicate entries. Instructions on how to do this and how to increase the size of the database fields can found in
[http://bibliographic.openoffice.org/files/documents/124/1284/HOWTO-increaseFieldSizes-V2.odt HOWTO-increaseFieldSizes-V2.odt]

===Import from .odt-file===

'''Q:''' I have an OOoWriter document containing large amount of citations and very big bibliographic table. Can I automatically add all bibliographic entries to my database? [[User:FLegmatik|fLegmatik]]

'''A:''' There is no direct and simple mechanism. But there is a an indirect method - You can use the [http://www.math.umd.edu/~dcarrera/openoffice/misc/bibtex/filter.html bibtex export filter] mentioned below, to export the bibliographic data from you document. Then to import that BibTeX data into the database you could use the bibutils data conversion programs and method also described [[Bibliographic_Hints_and_Tips#How_to_use_Zotero_to_format_your_OOo_Bibliography | below]]. I have not tested this very well so I do not know how accurate the conversion process will be. [[User:Dnw|David Wilson]]

===Importing bibtex (or other) formats to the Bibliography manager using JabRef===

This was a better solution for me than the scripts mentioned below (since I am on a windows machine and couldn't get them to work anyway). This is described in the [http://jabref.sourceforge.net/help/OpenOfficeHelp.html JabRef documentation] (http://jabref.sourceforge.net/help/OpenOfficeHelp.html) and works well. ''Note - I had a problem with exporting to the spreadsheet because of a random character having slipped into my bibtex file. If the export doesn't work - check the records for wierd chars and delete them.''

==How to load Zotero reference data into Openoffice.==

[http://www.zotero.org zotero] [zoh-TAIR-oh] is a free, easy-to-use Firefox extension to help you collect, manage, and cite your research sources. It lives right where you do your work — in the web browser itself.

As an alternative to the below approach an OOo extension is being developed. It currently works with the development branch for Zotero ([http://forums.zotero.org/discussion/640/development-xpi/]]). It is available from [https://www.zotero.org/trac/ticket/524]. Thanks to the University of Southern Queensland for financial assistance with this project.

*Install [http://bibliographic.openoffice.org/files/documents/124/3078/RISImport.py RISmport.py] which reads RIS format files containing one or more references and inserts them into the default OpenOffice.org Bibliography/'biblio' database. [http://bibliographic.openoffice.org/files/documents/124/3077/RISImport_Instructions.odt instructions.odt] (Copy it into the /openoffice.org2.0/program/ directory)
*Select the Zotero titles you want to export to the OOo database
*Select Tools->’Export Library’ (from the gear icon), select Format=RIS and save the temp.ris file.
*Start OpenOffice.org
*Import the RIS data using RISmport.py, with a command like:
cd /openoffice.org2.0/program/python.sh RISmport.py /your-path-to/temp.ris
*The reference details should now be in the default bibliographic database.

To automate this a bit more, add a batch file to your path, called something like 'import_ris'. This is the linux version, could someone add a windows version.

# import_ris calls RISImport.py to read a RIS file and
# inserts the data into the OOo bibliographic database
#!/bin/sh
# put the path of your openoffice.org program directory on the next line.
cd /opt/openoffice.org2.0/program
echo "Importing RIS data from " $1
echo
./python.sh RISImport.py $1

To import BibTeX data I use [[Bibliographic_Software_and_Standards_Information#Bibutils |bibutils]] data conversion programs and the following script, import_bib -

# import_bib calls uses bibutils to convert BibTex data to
# RIS format and then call RISImport.py to read a RIS file and
# inserts the data into the OOo bibliographic database
# the bibutils programs bib2xml and xml2ris need to be in the
# program search path
#!/bin/sh
cd /opt/openoffice.org2.0/program
echo "importing BibTeX data from " $1
echo
bib2xml $1 | xml2ris > /tmp/bibtmp777
./python.sh RISImport.py /tmp/bibtmp777
rm /tmp/bibtmp777

You can easily add COPAC, endnote, ISI web of science, Pubmed import as these are also supported by the bibutils data converter. Just replace the bib2xml in the script with copac2xml, end2xml, isi2xml or med2xml.

If you are more adventurous and want to add this import function as menu items in Writer you could try loading these [[Bibliographic Import Macros | OOoBasic macros]].

==How to use Zotero to format your OOo Bibliography==

* If your version of OOo is less than 2.0.4, install the add-on module [http://www.hj-gym.dk/~hj/writer2latex/ writer2latex041] into OOo. (This export filter is included in [http://download.openoffice.org/2.0.4/index.html OOo 2.0.4]). It provides LateX and BibTeX export filters. The one we are interested in is the BibTeX export which exports the bibliographic data from the current document, (not the database), in BibteX format. (Instructions for installation on the web site).
*Open a OOo document with citations.
*Export your document bibliography data using: File->Export->File type='BibTex Data File (.bib)' (i.e. temp.bib)
*In Zotero create a new Collection folder and select it.
*In Zotero import your temp.bib file by using the 'gear' icon [[Image:gear-icon.png]] and Tools->Import.
*Select all the titles you want to use for the bibliography (probably all the references you imported), right-click and select 'Create Bibliography from Selected Items' from the context menu.
*Select the citation Style and 'Copy to Clipboard'
*Paste bibliography text into your OOo document.
*Voila !

'''Note: in my test the 'Chicago Manual of Style (Note)' - a numbered reference list was not in the correct citation order.

==How do I move my Bibliographic database==

The data base file is called biblio.dbf and it is located on my linux system
in the directory:

~/.openoffice.org2/user/database/biblio>

on Windows

C:\Program Files\OpenOffice.org x.x.x\presets\database

So importing the bibliography is just a matter of copying the old biblio.dbf to the location of the new database.

To change the location of the bibliographic database, first, understand that the bibliographic application looks for a database called 'Bibliography' and a table called 'biblio' in that database. (This is why it is easy to set up the bibliographic database on an other database sever, it does not matter if it mySQL or postgres or even a text file, it is the names 'Bibliography' and 'biblio' that matter.)

In the case of the standard Xbase (.dbf) bibliographic database the "database" is actually a directory called /biblio and the "table" is a .dbf file in that directory called biblio.dbf

You can change the location of the database by using the File->New->Database wizard. Create a new database called, say 'Bibliography-new'

Then using the menu option-

Tools->Options->OpenOffice.org Base->Database

You should now have at least two databases listed, the original Bibliography and Bibliography-new. In that Panel edit the original Bibliography to change its name to 'Bibliography-old' and change 'Bibliography-new' to 'Bibliography'.

==I want a better thesaurus==

The OpenOffice English language thesaurus is based on [http://wordnet.princeton.edu/ Wordnet]. The full Wordnet provides comprehensive information on word usage. Try it [http://wordnet.princeton.edu/perl/webwn online]

Install wordnet and add a small shell script to set the WNHOME and working directory and to pass on the selected word as a parameter (that is what the $1 does).

#!/bin/bash
# a small script file called my_wnb at /home/dnw/my_wnb
WNHOME=/usr/local/WordNet-2.1
cd /usr/local/WordNet-2.1/bin
/usr/local/WordNet-2.1/bin/wnb $1

add the following OOBasic macro into OpenOffice, this macro selects the word the cursor is on and passes it to wordnet for a lookup.

Sub wordnet
Dim sel As String
Dim oSelect As object
oSelect = thiscomponent.CurrentController.Selection
for i = 0 to oSelect.getCount() - 1
oRange = oSelect.getByIndex(i)
sel = oRange.String
next i
Shell("/home/dnw/my_wnb",1,sel)
End Sub

You can then assing the macro to a toolbar, shortcut-key or menu item.

==Your question is not answered here ?==
Try the [[Bibliographic FAQ]]

'''I feel I am going around in circles and I can not find what I need.'''

You could post add a question to this page or send a question to the Bibliographic Project user's mail list at
[mailto://users@bibliographic.openoffice.org users@bibliographic.openoffice.org]

==You are invited to add more Hints and Tips==

Add a FAQ here or just ask a question on the [http://wiki.services.openoffice.org/mwiki/index.php?title=Talk:Bibliographic_Hints_and_Tips&action=edit discussion page]. [[User:Dnw|David Wilson]]

[[Category:Bibliographic]]

Current selection

2007-03-12T02:24:29Z

Iannz: Fixed link

'''Current Selection in Text Documents'''

Also see [[Extensions_development_basic]].

Having made sure that text is selected, it is common to create a loop to do something to all of the currently selected text. But, remember that the first element of the array is either the current selection when there is only one selection, or the insertion point when there is more than one selection. Thus the following common code:

<code>[oobas]
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
if nCount = 1 then
oTextRange = oCurSelection.getByIndex(0)
'Do some action on oTextRange
else
for i = 0 to nCount - 1
oTextRange = oCurSelection.getByIndex(i)
'Do some action on oTextRange
next
end if
end if
</code>

Spreadsheet common

2006-05-31T23:10:23Z

Iannz: Added example showing how to deal with multiple selections

=Common spreadsheet operations=
See also [[ working_with_documents]]

==Current document==
<code>[oobas]
Dim oDoc As Object
oDoc = ThisComponent
</code>

==Load existing document==
<code>[oobas]
Dim oDoc As Object
oDoc = StartDesktop.loadComponentFromURL( ConvertToURL( "/home/robert/abc.xls" ), "_blank", _
0, Array() )
</code>
Document type check:

<code>[oobas]
Function IsSpreadsheetDocument( oDoc As Object ) As Boolean
IsSpreadsheetDocument = oDoc.supportsService( "com.sun.star.sheet.SpreadsheetDocument" )
End Function
</code>

=Working with sheets=

==Active sheet==
<code>[oobas]
Function fnActiveSheet
ThisComponent.getCurrentController.getActiveSheet
end function
</code>

==Number of sheets==
<code>[oobas]
thisComponent.getSheets.getCount
</code>

==Get sheet by index==
<code>[oobas]
Dim oSheet As Object

oSheet = thisComponent.getSheets.getByIndex( 0 )
' or in OOo BASIC
oSheet = oDoc.Sheets( 0 )
</code>

==Get sheet by name==
<code>[oobas]
Dim oSheet As Object

oSheet = thisComponent.getSheets.getByName( "Sheet1" )
</code>

==Iterate over all sheets==
<code>[oobas]
'iterate over all sheets
Dim oSheet As Object
Dim eSheets As Object
eSheets = oDoc.getSheets.createEnumeration

While eSheets.hasMoreElements
oSheet = eSheets.nextElement()

' here you can work your sheet
MsgBox "Next sheet name is " & oSheet.getName & "."
Wend
</code>

==Create new sheet==
<code>[oobas]
' create new sheet
oDoc = thisComponent
oSheet = oDoc.createInstance( "com.sun.star.sheet.Spreadsheet" )
oDoc.Sheets.insertByName( "new sheet", oSheet )
</code>

=Working with rows, columns=

==Row, Column selection==
<code>[oobas]
Dim oRow As Object
Dim oColumn As Object

' get first row
oRow = oSheet.getRows.getByIndex( 0 )

' get column B
oColumn = oSheet.getColumns.getByIndex( 1 )
</code>

==Column Properties==
<code>[oobas]
' column width (in 100ths of mm)
oColumn.setPropertyValue("Width", 100)

' optimal width
oColumn.setPropertyValue("OptimalWidth", True)

' hidden / visible
oColumn.setPropertyValue("IsVisible", False)

' page break?
oColumn.setPropertyValue("IsStartOfNewPage", False)
</code>

==Row properties==
<code>[oobas]
' row height (in 100ths of mm)
oRow.setPropertyValue("Height", 100)

' optimal height
oRow.setPropertyValue("OptimalHeight", True)

' hidden / visible
oRow.setPropertyValue("IsVisible", False)

' page break?
oRow.setPropertyValue("IsStartOfNewPage", False)

</code>

==Insert, delete row==
<code>[oobas]
' insert 2 rows at the 4th position (still counting from 0)
oSheet.getRows.insertByIndex( 3, 2 )

' remove 3 lines from the 7th line
oSheet.getRows.removeByIndex( 6, 3 )
</code>

==Insert, delete column==
<code>[oobas]
' insert 2 columns into the fourth (D) column
oSheet.getColumns.insertByIndex( 3, 2 )

' remove 3 columns from the G column
oSheet.getColumns.removeByIndex( 6, 3 )
</code>

=Working with cells=

==Cell object==
<code>[oobas]
Dim oCell As Object

' select A1 (first number = column, second number = row)
oCell = oSheet.getCellByPosition( 0, 0 )

'Activecell (error check in case the current selection isn't a cell)
on error resume next
oCell = ThisComponent.getCurrentSelection

'Get a named cell - in this case the name is "Date"
oCell = thisComponent.NamedRanges.getByName("Date").getReferredCells
</code>
Each cell can contain text, number or formula:

<code>[oobas]
' modify text
oCell.String = "This is A1 cell"
' Old form: oCell.setPropertyValue("String", "This is A1 cell" )

' modify number
oCell.Value = 100
' Old form: oCell.setPropertyValue("Value", 100)

'Setting a cell to a fixed date and time (format the cell for date and/or time as desired)
oCell.Value = now
' Old form: oCell.setPropertyValue("Value", now)

' modify formula
oCell.Formula = "=A2+A3"
' Old form: oCell.setPropertyValue("Formula", "=A2+A3")
</code>

==Content type detection==
<code>[oobas]
Select Case oCell.Type
Case com.sun.star.table.CellContentType.EMPTY
' oCell is empty

Case com.sun.star.table.CellContentType.VALUE
' oCell contains number

Case com.sun.star.table.CellContentType.TEXT
' oCell contains string

Case com.sun.star.table.CellContentType.FORMULA
' oCell contains formula
End Select
</code>

=Cell range=
CellRangeAddress is a simple structure with five elements:
*Sheet
*StartColumn
*StartRow
*EndColumn
*EndRow

CellRangeAddress is obviously used to modify more than one cell.

==Insert cells==
Following example insert cells at B2:C3 range. Any existing values in the specified range are moved downwards.

<code>[oobas]
Dim oRange As New com.sun.star.table.CellRangeAddress

' first sheet and B2:C3 range
oRange.Sheet = 0
oRange.StartColumn = 1
oRange.StartRow = 1
oRange.EndColumn = 2
oRange.EndRow = 2

oSheet.insertCells( oRange, com.sun.star.sheet.CellInsertMode.DOWN )
</code>
Possible values for the second argument are:
*NONE
*DOWN the cells are moved downwards
*RIGHT the cells are moved to the right
*ROWS the rows are moved downwards
*COLUMNS the columns are moved to the right

==Remove cells==
Following example remove cells at B2:C3 range. Any existing values in the specified range are moved upwards.

<code>[oobas]
Dim oRange As New com.sun.star.table.CellRangeAddress

' first sheet and B2:C3 range
oRange.Sheet = 0
oRange.StartColumn = 1
oRange.StartRow = 1
oRange.EndColumn = 2
oRange.EndRow = 2

oSheet.removeCells( oRange, com.sun.star.sheet.CellInsertMode.UP )
</code>
Possible values for the second argument are:
*NONE
*UP the cells are moved upwards
*LEFT the cells are moved to the left
*ROWS the rows are moved upwards
*COLUMNS the columns are moved to the left

==Move, copy cells==
CellAddress is a new object, which will helps you identify the cell address and contains three elements:

*Sheet
*Column
*Row

Following example will move the A2:B3 cells to the A1.

<code>[oobas]
oRange As New com.sun.star.table.CellRangeAddress

' A2:B3 on the first sheet
oRange.Sheet = 0
oRange.StartColumn = 1
oRange.StartRow = 1
oRange.EndColumn = 2
oRange.EndRow = 2

Dim oAddress As New com.sun.star.table.CellAddress

' A1 on the first sheet
oAddress.Sheet = 0
oAddress.Column = 0
oAddress.Row = 0

' move the selected range to new position
oSheet.moveRange( oAddress, oRange )

' copy the selected range to new position
oSheet.copyRange( oAddress, oRange )
</code>

==Range selection by name==
You can create range address with cell names:

<code>[oobas]
oRange = oSheet.getCellRangeByName( "B2:C3" )
</code>
You can select cells from the range in the same way as from the sheet. Following example returns cell B2:

<code>[oobas]
oCell = oRange.getCellByPosition( 0, 0 )
</code>
The cell position is counted from the upper left corner of the range, not of the sheet.

==Content deletion==
<code>[oobas]
Dim nFlags As Long

oRange = oSheet.getCellRangeByName( "B2:C3" )

nFlags = com.sun.star.sheet.CellFlags.STRING + _
com.sun.star.sheet.CellFlags.STYLES

oRange.clearContents( nFlags )
</code>
Available flags listed below:

*VALUE numerical value
*DATETIME date or time
*STRING strings
*ANNOTATION comments
*FORMULA formulas
*HARDATTR direct formatting of cells
*STYLES indirect formatting
*OBJECTS drawing objects connected to cells
*EDITATTR formatting that applies to parts of the cells

=Formatting=
The following examples can be applied to either a Cell or a RangeAddress.

See [[working_with_styles#number_formats]] for information on changing number formats.

==Background color, shadows==
Shadow is defined in the structure com.sun.star.table.ShadowFormat, which has four elements.

*Color shadow color
*Location shadow location
*ShadowWidth shadow width
*IsTransparent shadow transparency

Possible values for Location are:
*NONE
*TOP_LEFT
*TOP_RIGHT
*BOTTOM_LEFT
*BOTTOM_RIGHT

<code>[oobas]
' cell background color
oCell.setPropertyValue( "CellBackColor", RGB( 0, 0, 0 ) )

' cell background transparency
oCell.setPropertyValue( "IsCellBackgroundTransparent", False )

' cell shadow
Dim oShadow As New com.sun.star.table.ShadowFormat

oShadow.Location = com.sun.star.table.ShadowLocation.BOTTOM_RIGHT
oShadow.Color = RGB(255, 255, 0)
oShadow.ShadowWidth = 50
oShadow.IsTransparent = False

oCell.setPropertyValue( "ShadowFormat", oShadow )
</code>

==Justification==

===Horizontal===
Each cell contains property HoriJustify with possible values (com.sun.star.table.CellHoriJustify):
*STANDARD
*LEFT
*CENTER
*RIGHT
*BLOCK
*REPEAT

<code>[oobas]
' horizontal justification - right
oCell.setPropertyValue( "HoriJustify", com.sun.star.table.CellHoriJustify.RIGHT )
</code>

===Vertical===
Each cell contains property VertJustify with possible values (com.sun.star.table.CellVertJustify):
*STANDARD
*TOP
*CENTER
*BOTTOM

<code>[oobas]
' vertical justification - center
oCell.setPropertyValue( "VertJustify", com.sun.star.table.CellVertJustify.CENTER )
</code>

===Orientation===
Each cell contains property Orientation with possible values (com.sun.star.table.CellOrientation):
*STANDARD
*TOPBOTTOM
*BOTTOMTOP
*STACKED

<code>[oobas]
' orientation - STACKED
oCell.setPropertyValue( "Orientation", com.sun.star.table.CellOrientation.STACKED )
</code>

===Wrapping, rotation===
Each cell contains property IsTextWrapped (Boolean) and RotateAngle (Long) for better justification.

<code>[oobas]
' wrapped text
oCell.setPropertyValue( "IsTextWrapped", True )

' vertical text
oCell.setPropertyValue( "RotateAngle", 90 )
</code>

=Example: Setting currently selected cells to current date and time=
<code>[oobas]
sub subSetDate
oDoc = thisComponent
oSelection = oDoc.getCurrentSelection
nFormat = fnGetNumberFormatId(oDoc,"DD/MM/YY")
if HasUnoInterfaces(oSelection, "com.sun.star.lang.XServiceInfo") then
if oSelection.supportsService("com.sun.star.sheet.SheetCellRanges") then
'More than one range selected
subSetRanges(oSelection, vValue, nFormat)
elseif oSelection.supportsService("com.sun.star.table.CellRange") then
'Only one range but more than one cell
subSetRange(oSelection, now, nFormat)
elseif oSelection.supportsService("com.sun.star.sheet.SheetCell") then
'only one cell selected
subSetCell(oSelection, now, nFormat)
end if
end if
end sub

sub subSetRanges(oRanges, vValue, nFormat)
for i = 0 to oRanges.getCount -1
subSetRange(oRanges.getByIndex(i), vValue, nFormat)
next
end sub

sub subSetRange(oRange, vValue, nFormat)
for i = 0 to oRange.getColumns.getCount - 1
for j = 0 to oRange.getRows.getCount - 1
subSetCell(oRange.getCellByPosition(i,j), vValue, nFormat)
next
next
end sub

sub subSetCell(oCell, vValue, nFormat)
oCell.value=vValue
oCell.setPropertyValue("NumberFormat", nFormat)
end sub

function fnGetNumberFormatId(oDoc, sNumberFormat)
sCharLocale = oDoc.getPropertyValue("CharLocale")
nFormatId = oDoc.getNumberFormats.queryKey(sNumberFormat, sCharLocale, false)
if nFormatId = -1 then 'Not yet defined
nFormatId = oDoc.getNumberFormats.addNew(sNumberFormat, sCharLocale)
end if
fnGetNumberFormatId = nFormatId
end function
</code>

[[Category:Basic:Tutorials]]

CookBook

2006-05-02T01:51:57Z

Iannz:

The material in this tutorial style cookbook builds upon the material covered in [[Extensions_development_basic|Starting in Basic]].

=General Guides=
[[Working with documents]]

[[Working with properties]]

[[Sorting and searching]]

[[Working with styles]]

=Component specific guides=
[[Working with Text Documents]]

[[Working with Spreadsheets]]

UNO component packaging

2006-05-02T01:41:30Z

Iannz:

=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=
Python loader is not able load classes from more than one file. Thus it's necessary to put all classes in one python source file. (Honestly, I read it somewhere and I didn't test this.)

=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.

<code>[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
</code>

==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.

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

=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:

<code>[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">
</code>

===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.

<code>[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>
</code>

===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.

<code>[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>
</code>

===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.

<code>[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>
</code>

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

<code>[xml]
</node>

</oor:component-data>
</code>

=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:

<code>[shell]
zip -r Wavelet.uno.zip Addons.xcu Wavelet.py images
</code>
The final ''Wavelet.uno.zip'' package should contain these files:

<code>[shell]
Wavelet.uno.zip
Addons.xcu
Wavelet.py
images/WaveletBig.bmp
images/WaveletSmall.bmp
</code>
'''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 package manager (somewhere in the ''Tools'' menu) or with the ''unopkg'' tool.

<code>[shell]
/opt/openoffice.org1.9.103/program/unopkg add Wavelet.uno.zip
</code>

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

<code>[shell]
/opt/openoffice.org1.9.103/program/unopkg remove Wavelet.uno.zip
</code>

=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.

<code>[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( () )
</code>

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

<code>[shell]
/opt/openoffice.org1.9.103/program/python ./Wavelet.py
</code>

==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.

Python

2006-05-02T01:33:15Z

Iannz: /* Ressources */

{{Extensions}}
=== Python specific information for Extension creation ===

=== Ressources ===
* [http://udk.openoffice.org/python/scriptingframework/index.html Python as a macro language in OpenOffice.org 2.x]
* [http://udk.openoffice.org/python/python-bridge.html pyUNO bridge]
* [http://blogs.nuxeo.com/sections/blogs/laurent_godard/2006_04_13_testing-pyuno-programs-with-doctests Introduction on testing pyUNO programs with doctests]
*[[UNO component packaging]]
[[Category:Extensions]]

Custom functions

2006-05-02T01:29:01Z

Iannz:

=Simple functions=

==Cell as an argument==
<code>[oobas]
Function Cube( c1 )
Cube = c1 * c1 * c1
End Function
</code>
You can put ''=Cube(A1)'' in any cell.

==More cells as the arguments==
<code>[oobas]
Function SimpleSum( c1, c2 )
SimpleSum = c1 + c2
End Function
</code>
You can put ''=SimpleSum(A1;A2)'' in any cell.

==Cells range as an argument==
<code>[oobas]
Function MySum( oRange As Variant )
If Not IsArray( oRange ) Then
If IsNumeric( oRange ) Then
MySum = oRange
else
MySum = 0
End If
Exit Function
End If

Dim nSum As double

nSum = 0

For i = 1 To ubound( oRange, 1 )
For j = 1 To ubound( oRange, 2 )

If IsNumeric( oRange( i, j ) ) Then
nSum = nSum + oRange( i, j )
End If
Next j
Next i

MySum = nSum
End Function
</code>
You can put ''=MySum(A1:A3)'' in any cell.

It is not possible to write to custom function that uses a cell range that spans sheets. E.g. <tt>=Sheet1.A2:Sheet2.A2</tt> instead you would have to have separate parameters for each sheet.

Data pilots

2006-05-02T01:23:15Z

Iannz:

The last I looked it was not possible to access a DataPilot based on external data via the API - so these routines are for DataPilots based on data within the spreadsheet.

=Current data pilot=
<code>[oobas]
Function fnCurDataPilot(oCursor as object) as object

'Returns the first data pilot that intersects with oCursor
'If no data pilot intersects it returns null

dim oEnum as object, oDP as object

oEnum = thisComponent.getCurrentController.getActiveSheet.getDataPilotTables.createEnumeration
While oEnum.hasMoreElements()
oDP = oEnum.nextElement()
if oCursor.queryIntersection(oDP.outputRange).getCount > 0 then
fnCurDataPilot = oDp
exit function
end if
wend
'fnCurDataPilot = null
end function
</code>
Example of calling the above function:

<code>[oobas]
oDoc = thisComponent
oCurSelection = oDoc.CurrentSelection
oSheet = oDoc.CurrentController.ActiveSheet
oCursor = oSheet.createCursorbyRange(oCurSelection)
oDataPilot = fnCurDataPilot(oCursor)
</code>

=Delete datapilot=
<code>[oobas]
sub subDeleteDataPilot(oDoc, oDataPilot)
oDoc.getsheets.getByIndex(oDataPilot.getOutputRange.sheet).getDataPilotTables.removeByName(oDataPilot.Name)
end sub
</code>

Calc/API/Dialogs

2006-05-02T01:19:59Z

Iannz:

For general information on creating dialogs see the OOo on line help for create dialog..

A common task when presenting a dialog in a spreadsheet is to request a cell range. The following routines allow a user to select a cell range. Unfortunately, the user has to click a button to activate the routines (i.e. still to do is a routine to activate these routines when the user clicks outside the dialog).

The dialog has the following requirements:
*A button or buttons with Initiate event set to subEventShrink
*The above button(s) have the tag field set to the name of the corresponding text field
*For each button a corresponding text field for the range address

<code>[oobas]
' The dialog is kept in a global variable so that other subroutines can access it (below).
Private oDialog As Object

' oDestField is kept in a global variable so that it is available to the the range selection listener
' routine, and it knows which edit box is the destination for the selection string.
private oDestField as object

' bSelecting is the variable whose value gets changed so that a loop can be exited when selecting a range
' has finished.
private bSelecting as boolean

' This variable is so that the dialog can be endExecuted under program control, so that the range selection listener
' will work under both Windows and Linux, and reactivated when required.
private bDialogFinished as boolean

Sub Main()
' Make sure this library, with its dialog is loaded.
DialogLibraries.LoadLibrary( "SignificantDigits" )

' Create the dialog object.
oDialog = createUnoDialog( DialogLibraries.GetByName( "SignificantDigits" ).GetByName( "SigDigitsDlg" ) )

'Other code for setting up the dialog goes here

' Display the dialog.
' This routine call does not return until the dialog is dismissed.

do
bDialogFinished = true
oDialog.Execute()
loop until bDialogFinished
' Execution does not reach this point until the dialog is dismissed.
End Sub

'The following routines for range selection were improved (actually made to work)
'with input from Jim Thompson and with concepts in a thread by Danad:
'http://www.oooforum.org/forum/viewtopic.php?t=6160

sub subEventShrink (oEvent)
'Called when Rng button clicked
'Uses module variables: oDialog, oRangeSelectionListener, oDestRange
dim mRangeSelection, sField as string

sField = oEvent.source.model.tag
oDestField = oDialog.getControl(sField)
subAddPropertyValue( mRangeSelection, "InitialValue", oDestField.text)
subAddPropertyValue( mRangeSelection, "Title", oDialog.title & " " & sField )
subAddPropertyValue( mRangeSelection, "CloseOnMouseRelease", true )

'The order of starting the range selection and hiding the dialog is important it must be as follows
oDocCtrl = thisComponent.getCurrentController()

oRangeSelectionListener = CreateUnoListener( "RangeSelectionListener_","com.sun.star.sheet.XRangeSelectionListener" )
oDocCtrl.addRangeSelectionListener( oRangeSelectionListener ) ' Register the listener
bSelecting = true
bDialogFinished = false
oDialog.endExecute

oDocCtrl.startRangeSelection(mRangeSelection )
while bSelecting
wend
oDocCtrl.removeRangeSelectionListener(oRangeSelectionListener)
end sub

Sub RangeSelectionListener_done(oRangeSelectionEvent as new com.sun.star.sheet.RangeSelectionEvent)
'Uses module variables: bSelecting, oRangeSelectionEvent, oDestField, oDialog
'Called when the range selection is done (clicking the icon at right end)

oDestField.text= oRangeSelectionEvent.RangeDescriptor
bSelecting = false
'oDialog.visible=true
'oDialog.enable = true
end sub

Sub RangeSelectionListener_aborted(oRangeSelectionEvent as new com.sun.star.sheet.RangeSelectionEvent)
'Uses module variables: bSelecting, oDialog
'Called when the range selection is cancelled (clicking X at top right)
bSelecting = false
'oDialog.visible=true
'oDialog.enable = true
end sub

Sub RangeSelectionListener_disposing()
'nothing to do
end sub
</code>

For a working example see: [[http://homepages.paradise.net.nz/hillview/OOo/SignificantDigits-2004-12-19-17.sxc| significantdigits]].

Spreadsheet common

2006-05-02T01:10:38Z

Iannz:

Working with Spreadsheets

2006-05-02T00:54:21Z

Iannz:

[[Spreadsheet common|Working with spreadsheet documents, sheets, rows, columns, cells, ranges, formatting]]

[[Spreadsheet dialogs]]

[[Data pilots]]

[[Custom functions]]

Writer/API/TextRange

2006-05-02T00:51:47Z

Iannz:

'''Working with Text Ranges'''

The [[ Current selection]], the [[ View cursor]] and not visible [[ Text cursor]]s all provide the [[ TextRange]] service.

As does <tt>thisComponent.text</tt>, and to make life more incestous text portion enumerations.

It is this service which provides the methods and properties for changing the text.

=Inserting text=
Inserting text is accomplished with the method <tt>insertString</tt>. The parameters to this function are the location in the text range to insert the string at, the string itself, and whether the text at the specified location gets replaced.

The following routine inserts text at the view cursor.

<code>[oobas]
sub subInsertString(oDoc, sString, bReplace)
oVC = oDoc.getCurrentController.getViewCursor
oText = oVC.text
oText.insertString(oVC, sString, bReplace)
end sub
</code>
The following example inserts the text "Some sample text" to the left of the current selection, leaving the orginal selection still selected.

<code>[oobas]
subInsertString(thisComponent, "Some sample text", false)
</code>

=Inserting control codes=
<code>[oobas]
sub subInsertParagraphMarker(oDoc)
oVC = oDoc.getCurrentController.getViewCursor
oText = oVC.text
oText.insertControlCharacter(oVC, com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False)
end sub
</code>
The control codes are:

{| border="1"
|0
|com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK
|This control character starts a new paragraph.
|-
|1
|com.sun.star.text.ControlCharacter.LINE_BREAK
|This control character starts a new line in a paragraph.
|-
|2
|com.sun.star.text.ControlCharacter.HARD_HYPHEN
|This control character equals a dash but prevents this position from being hyphenated.
|-
|3
|com.sun.star.text.ControlCharacter.SOFT_HYPHEN
|This control character defines a special position as a hyphenation point. If a word containing a soft hyphen must be split at the end of a line, then this position is preferred.
|-
|4
|com.sun.star.text.ControlCharacter.HARD_SPACE
|This control character is used to link two words and prevents this concatenation from being hyphenated. It is printed as a space.
|-
|5
|com.sun.star.text.ControlCharacter.APPEND_PARAGRAPH
|This control character appends a new paragraph at the end of the current paragraph.
|-
|}

Although you can insert control codes by inserting the equivalent string (e.g. chr(10) for LINE_BREAK), it is safer to use <tt>insertControlCharacter</tt> as the screen gets updated properly.

=Changing properties=
To change the properties of a piece of text, select the text e.g. with a cursor, and then use the <tt>setPropertyValue</tt> method.

See [[ working with styles]] for an example.

=Paragraphs=
It is possible to create an enumeration of paragraphs (and text tables) from an object with service [[ TextRange]].

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText.createEnumeration
'or thisComponent.getCurrentSelection.getByIndex(i).createEnumeration

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>

=Text Portions=
A paragraph consists of text portions. A text portions is a block of text within a paragraph with identical formatting.

The following function counts the number of portions in a paragraph.

<code>[oobas]
function fnNoPortions(oPara)

oPortionEnum = oPara.createEnumeration
i = 0
while oPortionEnum.hasMoreElements
i = i + 1
oPortionEnum.nextElement
wend
fnNoPortions = i
end function
</code>
An example of calling this function is:

<code>[oobas]
thisComponent.getCurrentSelection.getByIndex(i).createEnumeration
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The paragraph contains " & fnNoPortions(oTextElement) & "text portions"
end if
wend
</code>
For more routines see [[ Working with properties]].

Working with Text Documents

2006-05-02T00:48:13Z

Iannz:

This section is about working with the Writer component. It builds upon the material covered in [[Extensions_development_basic]] and the generic guides in the [[CookBook]].

=Cursors=
To work within a text document typically involves the [[ Current selection]], the [[ View cursor]] or a not visible [[ Text cursor]]. All of them provide access to [[ TextRange]] objects, which provide methods for changing the text.

The differences between them is summarised in the following table:

{| border="1"
|
| '''Current selection '''
| '''View cursor '''
| '''Text cursor '''
|-
| '''Typical command '''
|oCurSelection = thisComponent.getCurrentSelection
|oVC = thisComponent.getCurrentController.getViewCursor
|oCursor = oVC.getText.createTextCursorByRange(oVC)
|-
| '''Main service '''
|TextRanges
|TextViewCursor
|TextCursor
|-
| '''Object returned '''
|Array of selected text ranges
|The insertion point or a single text selection
|A single text selection
|-
| '''Number in frame '''
|One array
|One only
|As many as required
|-
| '''Movement '''
|(By view cursor)
|By Characters, Lines, and Pages
|By Characters, Words, Sentences, and Paragraphs
|-
| '''Cookbook page '''
|[[Current selection]]
|[[ View cursor]]
|[[ Text cursor]]
|-
|}

(I have not been able to work out how to select more than one block of text using code other than using the method FindAll. Although it is possible to record a current multiple selection, move the view cursor, and reselect the original multiple selection. See [[View cursor]]. If you know how to do this please edit this page!)

=Text Ranges=
[[ TextRange]]

Writer/API/Text cursor

2006-05-02T00:42:37Z

Iannz:

A text cursor can only move within the text range of the text object in which it was created. Thus a text cursor that is created for the main document's text range can not move inside a table.

=Creating a text cursor=
A common thing to do is to create a text cursor which has the same location as the view cursor, as follows:

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
</code>
If you want a cursor for the text in the main document:

<code>[oobas]
oCursor = thisComponent.getText.createTextCursor
'or
oText = thisComponent.getText
oCursor = oText.createTextCursorByRange(oText.getStart)
</code>

=Start and End of a text cursor=
A cursor has the methods <tt>getStart</tt>, and <tt>getEnd</tt>. Which is the start "end" and which is the end "end" is determined by the direction in which the selection was made.

However, the methods <tt>collapseToStart</tt> and <tt>collpaseToEnd</tt> are relative to the start and end of the document.

=Moving a cursor=
A cursor has a number of <tt>gotoXXX</tt> where XXX is some relative location. In each case there is always a boolean parameter for "extending the selection". When this parameter is set to <tt>true</tt> the selection is extended from the current selection to the new location.

There is no method for adding to the selection. While the view cursor can have more than one selection, text cursors only have one selection.

The <tt>gotoXXX</tt> methods return true if they were able to execute the movement, false otherwise.

<code>[oobas]
bExtend = false
oCursor.goLeft(5, bExtend) 'go left 5 characters
oCursor.goRight(10, bExtend) 'go right 10 characters
oCursor.gotoStart(bExtend) 'go to the start of the text range
oCursor.gotoEnd(bExtend) 'go to the end of the text range
oCursor.gotoRange(oVC, false)'go to the same range as the view cursor (error if oVC not in same text range

oCursor.gotoNextWord(bExtend)
oCursor.gotoPreviousWord(bExtend)
oCursor.gotoEndOfWord(bExtend)
oCursor.gotoStartOfWord(bExtend)

oCursor.gotoNextSentence(bExtend)
oCursor.gotoPreviousSentence(bExtend)
oCursor.gotoStartOfSentence(bExtend)
oCursor.gotoEndOfSentence(bExtend)

oCursor.gotoStartOfParagraph(bExtend)
oCursor.gotoEndOfParagraph(bExtend)
oCursor.gotoNextParagraph(bExtend)
oCursor.gotoPreviousParagraph(bExtend)
</code>

Writer/API/View cursor

2006-05-02T00:40:16Z

Iannz:

'''View Cursor in a Text document'''

=Accessing the view cursor=
A view cursor in text document is referenced as follows:

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
</code>
It is the only way to move within the page layout. For example to find the start of a line, the top of a page.

=Moving the view cursor=
<code>[oobas]
bExtend = false
oVC.goLeft(5, bExtend) 'go left 5 characters
oVC.goRight(10, bExtend) 'go right 10 characters
oVC.gotoStart(bExtend) 'go to the start of the text range
oVC.gotoEnd(bExtend) 'go to the end of the text range
oVC.gotoRange(oCursor, false) 'view cursor can go anywhere

oVC.goDown(2, bExtend)
oVC.goLeft(3, bExtend)
oVC.goUp(1, bExtend)
oVC.gotoEndOfLine(bExtend)
oVC.gotoStartOfLine(bExtend)

oVC.jumpToEndOfPage
oVC.jumpToFirstPage
oVC.jumpToLastPage
oVC.jumpToNextPage
oVC.jumpToPage(2, false)
oVC.jumpToPreviousPage
oVC.jumpToStartOfPage
</code>

=Using view cursor to find location on page=
The following routine returns the current insertion points location on a page in terms of lines and characters. The number of characters is meaningless if the insertion point is in a table.

<code>[oobas]
function fnPosn(oDoc)
set mCurSelection = oDoc.currentSelection ' Record current selection
'Locking controller prevents flicker. But under ALL circumstances must be unlocked
on local error goto finished:
oDoc.lockControllers
oVC = oDoc.getCurrentController.getViewCursor
oVC.collapseToEnd 'Move view Cursor
oVC.gotoStartofLine(true)
nX = len(oVC.string) 'How many characters from the start of the line
nY = 0
'How many lines from top of page
nPage = oVC.getPage
while oVC.goUp(1,false) and oVC.getPage = nPage
nY = nY + 1
wend
thisComponent.currentController.select(mCurSelection) 'Restore current selection
finished:
on error goto 0
oDoc.unlockControllers
fnPosn = "(" & nx & ", " & nY & ")"
end function
</code>
To call this code:

<code>[oobas]
msgbox fnPosn(thisComponent)
</code>

==Updating the status bar with the insertion points current location==
This code could be called whenever a key is pressed or the mouse clicked so that the status bar is updated with the current insertion point location. As follows:

<code>[oobas]
global Iannz_TSB_Controller, Iannz_TSB_MouseClickHandler, Iannz_TSB_KeyHandler

sub subSetupCustomStatusBar
Iannz_TSB_Controller = thisComponent.currentController
Iannz_TSB_MouseClickHandler = CreateUnoListener("MouseClickHandler_","com.sun.star.awt.XMouseClickHandler")
Iannz_TSB_Controller.addMouseClickHandler(Iannz_TSB_MouseClickHandler)
Iannz_TSB_KeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
Iannz_TSB_Controller.addKeyHandler(Iannz_TSB_KeyHandler)
end sub

sub subRemoveCustomStatusBar
if not isNull(Iannz_TSB_Controller) and not isEmpty(Iannz_TSB_Controller) then
oStatus = Iannz_TSB_Controller.Frame.createStatusIndicator
oStatus.end
Iannz_TSB_Controller.removeMouseClickHandler(Iannz_TSB_MouseClickHandler)
Iannz_TSB_Controller.removeKeyHandler(Iannz_TSB_KeyHandler)
end if
end sub

Sub MouseClickHandler_MousePressed(Event As Object)
Iannz_TSB_Controller.addMouseClickHandler(Iannz_TSB_MouseClickHandler)
end sub

sub MouseClickHandler_mouseReleased
subChangeStatusBar
Iannz_TSB_Controller.addMouseClickHandler(Iannz_TSB_MouseClickHandler)
end sub

sub MouseClickHandler_disposing
end sub

function KeyHandler_KeyPressed
KeyHandler_KeyPressed = false
end function

function KeyHandler_KeyReleased
subChangeStatusBar
KeyHandler_KeyReleased = false
end function

sub KeyHandler_disposing
end sub

sub subChangeStatusBar
oDoc = thisComponent
oVC = Iannz_TSB_Controller.viewCursor
oStatus = Iannz_TSB_Controller.Frame.createStatusIndicator
oStatus.end
if oVC.isCollapsed and isEmpty(oVC.getPropertyValue("Cell")) then
oStatus.start(fnPosn(thisComponent),100)
end if
end sub
</code>

Working with Text Documents

2006-05-02T00:37:45Z

Iannz:

This section is about working with the Writer component. It builds upon the material covered in [[Extensions_development_basic]] and the generic guides in the [[CookBook]].

=Cursors=
To work within a text document typically involves the [[ Current selection]], the [[ View cursor]] or a not visible [[ Text cursor]]. All of them provide access to [[ TextRange]] objects, which provide methods for changing the text.

The differences between them is summarised in the following table:

{| border="1"
|
| '''Current selection '''
| '''View cursor '''
| '''Text cursor '''
|-
| '''Typical command '''
|oCurSelection = thisComponent.getCurrentSelection
|oVC = thisComponent.getCurrentController.getViewCursor
|oCursor = oVC.getText.createTextCursorByRange(oVC)
|-
| '''Main service '''
|[[ TextRanges]]
|[[ TextViewCursor]]
|[[ TextCursor]]
|-
| '''Object returned '''
|Array of selected text ranges
|The insertion point or a single text selection
|A single text selection
|-
| '''Number in frame '''
|One array
|One only%%!%%
|As many as required
|-
| '''Movement '''
|(By view cursor)
|By Characters, Lines, and Pages
|By Characters, Words, Sentences, and Paragraphs
|-
| '''Cookbook page '''
|[[Current selection]]
|[[View Cursor]]
|[[Text Cursor]]
|-
|}

(I have not been able to work out how to select more than one block of text using code other than using the method FindAll. Although it is possible to record a current multiple selection, move the view cursor, and reselect the original multiple selection. See [[View Cursor]]. If you know how to do this please edit this page!)

=Text Ranges=
[[Working with text ranges]]

Working with styles

2006-05-02T00:29:48Z

Iannz:

=Display Style Names=
'''Display style names''' and '''style names''' are sometimes different. Thus to get a list of 'display' style names:

<code>[oobas]
function fnGetDisplayStyleNames(oDoc, sStyleFamily as string)
dim mApiNames, nStyles as integer, i as integer, oStyles as object

oStyles = oDoc.getStyleFamilies.getByName(sStyleFamily)
mApiNames = oStyles.getElementNames
nStyles = uBound(mApiNames)
dim mStyleNames(nStyles)
for i = 0 to nStyles
mStyleNames(i) = oStyles.getByIndex(i).getPropertyValue("DisplayName")
next
subShellSort(mStyleNames())
fnGetDisplayStyleNames = mStyleNames()
end function
</code>
<tt>subShellSort</tt> is defined in [[ sorting and searching]].

An example of calling this function:

<code>[oobas]
mStyleFamilyNames = thisComponent.getStyleFamilies.getElementNames
for i = 0 to uBound(mStyleFamilyNames)
msgbox join(fnGetDisplayStyleNames(thisComponent, mStyleFamilyNames(i)), chr(13)), 0, mStyleFamilyNames(i)
next
</code>

=Number formats=
Number formats have an Id number. Here is a function for getting that number:

<code>[oobas]
function fnGetNumberFormatId(oDoc, sNumberFormat)
sCharLocale = oDoc.getPropertyValue("CharLocale")
nFormatId = oDoc.getNumberFormats.queryKey(sNumberFormat, sCharLocale, false)
if nFormatId = -1 then 'Not yet defined
nFormatId = oDoc.getNumberFormats.addNew(sNumberFormat, sCharLocale)
end if
fnGetNumberFormatId = nFormatId
end function
</code>
An example for directly applying a number format to a range of cells in a spreadsheet:

<code>[oobas]
oCells = thisComponent.getSheets.getByIndex(0).getCellRangeByName("B2:B10")
nFourDP = fnGetNumberFormatId(thisComponent, "0.0000")
oCells.setPropertyValue("NumberFormat", nFourDp)
</code>

=Get Style=
The following function is for returning a style of a particular name, if the name doesn't already exist a style is created with that name.

<code>[oobas]
function fnGetStyle(oDoc, sStyleFamily, sInstance, sStyleName)
oStyles = thisComponent.getStyleFamilies.getByName(sStyleFamily)
if not oStyles.hasByName(sStyleName) then
oStyle = thisComponent.createInstance(sInstance)
oStyles.insertByName(sStyleName, oStyle)
else
oStyle = oStyles.getByName(sStyleName)
end if
fnGetStyle = oStyle
end function
</code>
(It would be good if the sInstance parameter could be removed but I haven't worked out how to do that. If you work it out please edit this page!)

An example of calling the above function, it creates a cell style called FourDP if it doesn't already exist, sets its number format, and applys the cell format to a range of cells:

<code>[oobas]
sStyle = "FourDP"
oStyle = fnGetStyle(thisComponent, "CellStyles", "com.sun.star.style.CellStyle", sStyle)
oStyle.setPropertyValue("NumberFormat", fnGetNumberFormatId(thisComponent, "0.0000")
oCells = thisComponent.getSheets.getByIndex(0).getCellRangeByName("B2:B10")
oCells.setPropertyValue("CellStyle", sStyle)
</code>

=Find Style=
To find an existing style that has the properties that you want:

<code>[oobas]
function fnFindStyle(oDoc, sStyleFamily, mProperties)
oStyleFamilies = oDoc.StyleFamilies
oStyles = oStyleFamilies.getByName(sStyleFamily)
nProperties = ubound(mProperties)
For i = 0 To oStyles.Count - 1
oStyle = oStyles(i)
bFound = true
for j = 0 to nProperties
if oStyle.getPropertyValue(mProperties(j).name) <> mProperties(j).value then
bFound = false
exit for
end if
next
if bFound then
fnFindStyle = oStyle
exit function
end if
next
end function
</code>
An example of calling this function:

<code>[oobas]
dim mProperties()
subAddProperty(mProperties(), "NumberFormat", fnGetNumberFormatId(thisComponent, "0.0000"))
oStyle = fnFindStyle(thisComponent, "CellStyles", mProperties())
if isNull(oStyle) then
sStyle = "FourDP"
oStyle = fnGetStyle(thisComponent, "CellStyles", "com.sun.star.style.CellStyle", sStyle)
oStyle.setPropertyValues(mProperties())
else
sStyle = oStyle.getName
end if
oCells = thisComponent.getSheets.getByIndex(0).getCellRangeByName("B2:B10")
oCells.setPropertyValue("CellStyle", sStyle)
</code>
This example calls <tt>subAddProperty</tt> which is defined in [[Working_with_properties#subAddProperty]].

Sorting and searching

2006-05-02T00:25:57Z

Iannz:

Neither OpenOffice.org Basic nor the API provide methods or functions for sorting arrays or searching within arrays.

It is quite common to sort almost sorted arrays, for example the list of style names belonging to a style family. Thus, I have found the shell sort to be the fastest for most uses in OpenOffice.org:

<code>[oobas]
sub subShellSort(mArray)

dim n as integer, h as integer, i as integer, j as integer, t as string, Ub as integer, LB as integer
Lb = lBound(mArray)
Ub = uBound(mArray)

' compute largest increment
n = Ub - Lb + 1
h = 1
if n > 14 then
do while h < n
h = 3 * h + 1
loop
h = h \ 3
h = h \ 3
end if
do while h > 0
' sort by insertion in increments of h
for i = Lb + h to Ub
t = mArray(i)
for j = i - h to Lb step -h
if strComp(mArray(j), t, 0) < 1 then exit for
mArray(j + h) = mArray(j)
next j
mArray(j + h) = t
next i
h = h \ 3
loop
end sub
</code>
Based on a routine available from [[http://www.oopweb.com/Algorithms/Documents/Sman/Volume/s_vss.txt here]].

Searching in a sorted list is compartively efficient with a binary search:

<code>[oobas]
function fnBinarySearch(a, v)
nLeft = 0
nRight = uBound(a)
nLen = len(v)
while nLeft <= nRight
nMid = int((nLeft + nRight)/2)
if left(a(nMid), nLen) = v then
fnBinarySearch = nMid
exit function
elseif v < a(nMid) then
nRight = nMid - 1
else
nLeft = nMid + 1
end if
wend
fnBinarySearch = -1
end function
</code>

Working with properties

2006-05-02T00:23:05Z

Iannz:

The following routines all deal with properties. They are revised routines from my RevealCodes macro, and the main routine which demonstrates calling some of the other routines displays the changes in "codes" for the current paragraph.

=fnNotIn=
The following routine compares two arrays or property beans, and returns an array of property beans for those items which are in array mProp1 but not in mProp2, or where the value is different.

<code>[oobas]
function fnNotIn(mProp1, mProp2)
'Returns an array of the properties in mProp1 not found in mProp2
dim mNotIn()
n1 = uBound(mProp1)
n2 = uBound(mProp2)
if n2 < 0 then
fnNotIn = mProp1
else
for i = 0 to n1
sName1 = mProp1(i).name
bNotFound = true
for j = 0 to n2
sName2 = mProp2(j).name
if sName1 = sName2 then
bNotFound = not fnEqualValues(mProp1(i).value, mProp2(j).value)
exit for
elseif sName2 > sName1 then
exit for
end if
next
if bNotFound then subAddThisProperty(mNotIn(), mProp1(i))
next
fnNotIn = mNotIn()
end if
end function
</code>

=fnEqualValues=
This routine is not strictly dealing with properties but is called by fnNotIn, so is included here. The function is recursive so will only work in OpenOffice.org 1.1.1 or greater. Compares two values of the same type and returns whether they are equal or not. Currently it doesn't work for structs or objects (if you know how to do this please edit this page!)

<code>[oobas]
function fnEqualValues(vValue1, vValue2) as boolean
'Returns true if the values are equal

if isArray(vValue) then
nUpperBound1 = uBound(vValue1)
nUpperBound2 = uBound(vValue2)
if nUpperBound1 <> nUpperBound2 then
fnEqualValues = false
elseif nUpperBound1 = -1 then
fnEqualValues = true
else
for i = 0 to nUpperBound1
if not fnEqualValues(vValue1, vValue2) then
fnEqualValues = false
exit for
end if
next
end if
elseif isUNOstruct(vValue) then
fnEqualValues = true 'Assume true as I don't know how to compare them
else
select case varType(vValue)
case 2-5,7, 8, 11 'numbers, date, string boolean
fnEqualValues = vValue1 = vValue2
case 9 'object ???
fnEqualValues = true 'Assume true as I don't know how to compare them
case else
fnEqualValues = true
end select
end if
end function
</code>

=subAddThisProperty=
This routine adds a property bean to the end of a one dimensional array.

<code>[oobas]
sub subAddThisProperty(mProperties, mProperty)
nNext = uBound(mProperties) + 1
redim preserve mProperties(nNext)
set mProperties(nNext) = mProperty
end sub
</code>

=fnDirectProperties=
Returns an array of property beans of directly applied properties to a text range (should work for other types of objects but has not been tested).

<code>[oobas]
function fnDirectProperties(oTextRange)
'Returns an array of property beans of directly applied properties
oProperties = oTextRange.getPropertySetInfo.getProperties
nProperties = uBound(oProperties)
dim mDirectProperties()
for i = 0 to nProperties
sName = oProperties(i).name
if oTextRange.getPropertyState(sName) <> com.sun.star.beans.PropertyState.DEFAULT_VALUE and _
((oProperties(i).attributes and com.sun.star.beans.PropertyAttribute.READONLY) = 0) then
nTypeClass = oProperties(i).type.typeClass
subAddProperty( mDirectProperties(),sName, oTextRange.getPropertyValue(sName))
end if
next
fnDirectProperties = mDirectProperties()
end function
</code>

=fnPropertyValues=
Returns an array of strings for the property names and their values. You could think of this as being a form of introspection.

<code>[oobas]
function fnPropertyValues(mProperties)
'returns an array of strings for the property names and their values
nProperties = Ubound(mProperties)
if nProperties < 0 then
fnPropertyValues = array("")
exit function
end if
dim mPropertyValues(nProperties)
for i = 0 to nProperties
mPropertyValues(i) = fnPropertyValue(mProperties(i))
next
fnPropertyValues = mPropertyValues()
end function
</code>

=fnPropertyValue=
Returns the concatentaion of a property name and its value as a string

<code>[oobas]
function fnPropertyValue(aProperty) as string
'Returns the concatentaion of a property name and its value as a string
if isNull(aProperty) or isEmpty(aProperty) then
fnPropertyValue = ""
msgbox "Oops!"
else
sName = aProperty.name
vValue = aProperty.Value
fnPropertyValue = sName & ": " & fnConvString(vValue)
end if
end function
</code>

=fnConvString=
Converts a variables value to a string. Currently if the variable is a struct or object it simply returns "Struct" or "Object". (If you know a better way please edit this page!)

<code>[oobas]
function fnConvString(vValue) as string
'Converts a variant to a string
if isArray(vValue) then
nUpperBound = uBound(vValue)
if nUpperBound = 0 then
fnConvString = ""
else
s = "{"
for i = 0 to nUpperBound
s = s & fnConvString(vValue(i)) & ","
next
nLen = len(s)
if nLen > 1 then
fnConvString = left(s, len(s) - 1) & "}"
end if
end if
elseif isUNOstruct(vValue) then
fnConvString = "Struct"
else
select case varType(vValue)
case 0, 2 to 5,7 'empty, numbers, date
fnConvString = cstr(vValue)
case 8 'string
fnConvString = vValue
case 9 'object ???
fnConvString = "Object"
case 11 'boolean
if vValue then
fnConvString = "True"
else
fnConvString = "False"
end if
case else
fnConvString = ""'vValue
msgbox varType(vValue)
end select
end if
end function
</code>

=subAddProperty=
This routine calls fnNewProperty to create new property bean, assign a name and optionally a value, and adds the new property bean to a one dimensional array.

<code>[oobas]
sub subAddProperty(mProperties, sName, optional vValue)
nNext = uBound(mProperties) + 1
redim preserve mProperties(nNext)
if isMissing(vValue) then
mProperties(nNext) = fnNewProperty(sName)
else
mProperties(nNext) = fnNewProperty(sName, vValue)
end if
end sub
</code>

=fnNewProperty=
Create new property bean, assign a name and optionally a value, returns the new property bean.

<code>[oobas]
function fnNewProperty(sName, optional vValue)
aProperty = createUnoStruct("com.sun.star.beans.PropertyValue")
aProperty.Name = sName
if not isMissing(vValue) then
aProperty.Value = vValue
end if
fnNewProperty = aProperty
end function
</code>

=Example - Displaying 'codes' of a paragraph=
This example demonstrates calling <tt>fnDirectProperties</tt>, <tt>fnNotIn</tt>, and <tt>fnPropertyValues</tt> defined above. It shows how the above codes could be used in a "reveal codes" type macro. The [[ join]] statement is just a quick and dirty way of creating a string out of an array of strings for displaying in the messagebox.

<code>[oobas]
sub main
oParagraph = fnGetCurrentParagraph
mParaProperties = fnDirectProperties(oParagraph)
msgbox join(fnPropertyValues(mParaProperties), chr(10)), 0 , "Paragraph properties"
oPortionEnum = oParagraph.createEnumeration
i = 0
while oPortionEnum.hasMoreElements
i = i + 1
oPortion = oPortionEnum.nextElement
mCurProperties = fnDirectProperties(oPortion)
if i > 1 then
mCloseProperties = fnNotIn(mPrevProperties, mCurProperties)
msgbox join(fnPropertyValues(mCloseProperties), chr(10)), 0 , "Portion " & i & " close properties"
mOpenProperties = fnNotIn(mCurProperties, mPrevProperties)
else
mOpenProperties = mCurProperties
end if
msgbox join(fnPropertyValues(mOpenProperties), chr(10)), 0 , "Portion " & i & " open properties"
set mPrevProperties = mCurProperties
wend
msgbox join(fnPropertyValues(mPrevProperties), chr(10)), 0 , "Portion " & i & " close properties"
end sub

function fnGetCurrentParagraph
'Returns the whole paragraph that the insertion point is in
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.text.createTextCursorByRange(oVC)
oCursor.gotoStartOfParagraph(false)
oCursor.gotoEndOfParagraph(true)
fnGetCurrentParagraph = oCursor.createEnumeration.nextElement
end function

</code>

Closing a document

2006-05-02T00:18:59Z

Iannz:

<code>[oobas]
thisComponent.close(true)
</code>
Please note that the parameter being passed is to do with what should happen if another process has vetoed closing the document or not and not whether the document is to be saved.

So to be sure that a document gets saved before closing use something like:

<code>[oobas]
sub subClose(oDoc)
if fnSave(oDoc) then
oDoc.close(true)
fnClose = true
else
if msgbox("Unable to save the file before closing." & chr(13) & _
"Close any way?", 4 + 32, "File not saved warning") = 6 then
oDoc.close(true)
end if
end if
end sub
</code>
fnSave is defined [[saving a document]].

Example of calling <tt>subclose</tt>:

<code>[oobas]
subClose(thisComponent)
</code>

{| border="1"
|'''Warning:'''
|Do not use <tt>thisComponent.dispose</tt> it could crash OpenOffice.org.
|}

Printing a document

2006-05-02T00:15:36Z

Iannz:

'''To print the current document without passing any arguments: '''

<code>[oobas]
thisComponent.print(array())
</code>
A more generic print routine:

<code>[oobas]
sub subPrint(oDoc, optional ncopies, optional bCollate, optional sPages, optional sFileName)
dim mPrintOptions()

if not isMissing(nCopies) then
subAddproperty(mPrintOptions(), "CopyCount", nCopies)
end if
if not isMissing(bCollate) then
subAddproperty(mPrintOptions(), "Collate", bCollate)
end if
if not isMissing(sPages) then
subAddproperty(mPrintOptions(), "Pages", sPages)
end if
if not isMissing(sFilename) then
subAddproperty(mPrintOptions(), "FileName", sFileName)
end if
oDoc.print(mPrintOptions())
end sub
</code>
This function calls subAddProperty which is defined in [[working with properties]].

Example of calling this function:

<code>[oobas]
subprint(ThisComponent, 1, ,"1", "PrintExample.txt")
</code>

Saving a document

2006-05-02T00:12:30Z

Iannz:

'''To save an existing document: '''

<code>[oobas]
thisComponent.store()
</code>
But, this maybe a bit too simplistic. So a more generic approach might be:

<code>[oobas]
function fnSave(oDoc)
if oDoc.hasLocation AND Not oDoc.isReadOnly Then
fnSave = true
on local error goto notSaved
oDoc.store()
on error goto 0
else
fnSave = fnDispatch("SaveAs")
end If
exit function

notSaved:
fnSave = false
end function
</code>

fnDispatch is defined in [[ The OpenOffice.org recorder and UNO dispatch calls]].

To "save as":

<code>[oobas]
sub subSaveAs(oDoc, sFile, optional sType)
sURL = convertToURL(sFile)
if isMissing(sType) then
oDoc.storeAsURL(sURL, array())
else
dim mFileType(0)
mFileType(0) = createUnoStruct("com.sun.star.beans.PropertyValue")
mFileType(0).Name = "FilterName"
mFileType(0).Value = sType
oDoc.storeAsURL(sURL, mFileType())
end if
end sub
</code>
To "export as" (leave the URL of the current document alone but save a copy of the file in the specified format):

<code>[oobas]
sub subExportAs(oDoc, sFile, optional sType)
sURL = convertToURL(sFile)
if isMissing(sType) then
oDoc.storeToURL(sURL, array())
else
dim mFileType(0)
mFileType(0) = createUnoStruct("com.sun.star.beans.PropertyValue")
mFileType(0).Name = "FilterName"
mFileType(0).Value = sType
oDoc.storeToURL(sURL, mFileType())
end if
end sub
</code>

Examples of calling these routines:

<code>[oobas]
subSaveAs(thisComponent, "C:\tmp\NewName.sxw") 'Windows example
subExportAs(thisComponent, "/home/ian/Example.txt", "Text") 'Linux example
</code>

=File Types=
The following routine, written by Danny Brewer (copied from [[http://www.oooforum.org/forum/viewtopic.phtml?t=3549 here]]) creates a new document and enters the current filters.

<code>[oobas]
Sub Main
oFF = createUnoService( "com.sun.star.document.FilterFactory" )
oFilterNames = oFF.getElementNames()

' Create a Writer doc and save the filter names to it.
oDoc = StarDesktop.loadComponentFromURL( "private:factory/swriter", "_blank", 0, Array() )
oText = oDoc.getText()
oCursor = oText.createTextCursor()
oCursor.gotoEnd( False )

' Print the filter names into a Writer document.
For i = LBound( oFilterNames ) To UBound( oFilterNames )
oText.insertString( oCursor, oFilterNames(i), False )
oText.insertControlCharacter( oCursor, com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False )
Next
End Sub
</code>

Saving a document

2006-05-02T00:11:01Z

Iannz:

'''To save an existing document: '''

<code>[oobas]
thisComponent.store()
</code>
But, this maybe a bit too simplistic. So a more generic approach might be:

<code>[oobas]
function fnSave(oDoc)
if oDoc.hasLocation AND Not oDoc.isReadOnly Then
fnSave = true
on local error goto notSaved
oDoc.store()
on error goto 0
else
fnSave = fnDispatch("SaveAs")
end If
exit function

notSaved:
fnSave = false
end function
</code>

fnDispatch is defined in [[ The OpenOffice.org recorder and UNO dispatch calls]].

To "save as":

<code>[oobas]
sub subSaveAs(oDoc, sFile, optional sType)
sURL = convertToURL(sFile)
if isMissing(sType) then
oDoc.storeAsURL(sURL, array())
else
dim mFileType(0)
mFileType(0) = createUnoStruct("com.sun.star.beans.PropertyValue")
mFileType(0).Name = "FilterName"
mFileType(0).Value = sType
oDoc.storeAsURL(sURL, mFileType())
end if
end sub
</code>
To "export as" (leave the URL of the current document alone but save a copy of the file in the specified format):

<code>[oobas]
sub subExportAs(oDoc, sFile, optional sType)
sURL = convertToURL(sFile)
if isMissing(sType) then
oDoc.storeToURL(sURL, array())
else
dim mFileType(0)
mFileType(0) = createUnoStruct("com.sun.star.beans.PropertyValue")
mFileType(0).Name = "FilterName"
mFileType(0).Value = sType
oDoc.storeToURL(sURL, mFileType())
end if
end sub
</code>

Examples of calling these routines:

<code>[oobas]
subSaveAs(thisComponent, "C:\tmp\NewName.sxw") 'Windows example
subExportAs(thisComponent, "/home/ian/Example.txt", "Text") 'Linux example
</code>
For more information on <tt>saveAsURL</tt> and <tt>saveToURL</tt> see [[ XStorable]] and for the parameters that can be passed to them see [[ MediaDescriptor]]. Use the above examples as templates for how to use these parameters in Basic.

Read on for the complete list of filters that can be passed to these functions.

=File Types=
The following routine, written by Danny Brewer (copied from [[http://www.oooforum.org/forum/viewtopic.phtml?t=3549 here]]) creates a new document and enters the current filters.

<code>[oobas]
Sub Main
oFF = createUnoService( "com.sun.star.document.FilterFactory" )
oFilterNames = oFF.getElementNames()

' Create a Writer doc and save the filter names to it.
oDoc = StarDesktop.loadComponentFromURL( "private:factory/swriter", "_blank", 0, Array() )
oText = oDoc.getText()
oCursor = oText.createTextCursor()
oCursor.gotoEnd( False )

' Print the filter names into a Writer document.
For i = LBound( oFilterNames ) To UBound( oFilterNames )
oText.insertString( oCursor, oFilterNames(i), False )
oText.insertControlCharacter( oCursor, com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False )
Next
End Sub
</code>

Opening a document

2006-05-02T00:03:29Z

Iannz:

'''The following function opens a file into a new window. '''

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>
A more complete function for opening a file:

<code>[oobas]
function fnOpenDoc(sFile, optional bAsTemplate, optional sPassword, optional bReadOnly, _
optional nMacroExecutionMode, optional nUpdateDocMode, optional sJumpMark, _
optional nViewId, optional bHidden, optional bStartPresentation,_
optional sFilterName, optional sFilterOptions, optional vFilterData, optional bRepairPackage)

dim mFileProperties()

if not isMissing(bAsTemplate) then
subAddproperty(mFileProperties(), "AsTemplate", bAsTemplate)
end if
if not isMissing(sPassword) then
subAddproperty(mFileProperties(), "Password", sPassword)
end if
if not isMissing(bReadOnly) then
subAddproperty(mFileProperties(), "ReadOnly", bReadOnly)
end if
if not isMissing(nMacroExecutionMode) then
subAddproperty(mFileProperties(), "MacroExecutionMode", nMacroExecutionMode)
end if
if not isMissing(nUpdateDocMode) then
subAddproperty(mFileProperties(), "UpdateDocMode", nUpdateDocMode)
end if
if not isMissing(sJumpMark) then
subAddproperty(mFileProperties(), "JumpMark", sJumpMark)
end if
if not isMissing(nViewId) then
subAddproperty(mFileProperties(), "ViewId", nViewId)
end if
if not isMissing(bHidden) then
subAddproperty(mFileProperties(), "Hidden", bHidden)
end if
if not isMissing(bStartPresentation) then
subAddproperty(mFileProperties(), "StartPresentation", bStartPresentation)
end if
if not isMissing(sFilterName) then
subAddproperty(mFileProperties(), "FilterName", sFilterName)
end if
if not isMissing(sFilterOptions) then
subAddproperty(mFileProperties(), "FilterOptions", sFilterOptions)
end if
if not isMissing(vFilterData) then
subAddproperty(mFileProperties(), "FilterData", vFilterData)
end if
if not isMissing(bRepairPackage) then
subAddproperty(mFileProperties(), "RepairPackage", bRepairPackage)
end if
sURL = ConvertToURL(sFile)
on local error resume next
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, mFileProperties())
end function
</code>
This function calls subAddProperty which is defined in [[working with properties]].

{| border="1"
| '''Parameter '''
| '''Explanation '''
|-
|bAsTemplate
|True = Create new document False = Open document (including templates) for editing
|-
|sPassword
|For opening password protected files
|-
|bReadOnly
|True = In the user interface the document will be presented as read only
|-
|nMacroExecutionMode
|com.sun.star.document.MacroExecMode.NEVER_EXECUTE com.sun.star.document.MacroExecMode.ALWAYS_EXECUTE com.sun.star.document.MacroExecMode.ALWAYS_EXECUTE_NO_WARN
|-
|nUpdateDocMode
|com.sun.star.document.UpdateDocMode.NO_UPDATE com.sun.star.document.UpdateDocMode.QUIET_UPDATE com.sun.star.document.UpdateDocMode.ACCORDING_TO_CONFIG com.sun.star.document.UpdateDocMode.FULL_UPDATE
|-
|sJumpMark
|For example the name of a bookmark in a text document
|-
|bHidden
|True = Document opened but not visible. Use with caution
|-
|bStartPresentation
|For Impress documents start the presentation
|-
|sFilterName
|See [[ saving a document]] for a list of filters
|-
|sFilterOptions
|Use this to supply additional info. to the filter
|-
|vFilterData
|Use this if a string for sFilterOptions is insufficient
|-
|bRepairPackage
|True = opens the document in repair mode, so as much information as possible will be retrieved
|-
|}

(Does anyone have a good reference for FilterOptions and FilterData?)

Creating a document

2006-05-01T23:59:15Z

Iannz:

The following function creates a new document of the specified type in a new window.

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>

Examples of calling this function:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>

Currently open documents

2006-05-01T23:57:25Z

Iannz:

'''The following function returns an array of the currently open documents. It calls fnWhichComponent which is available from [[Currently active document]].'''

<code>[oobas]
function fnCurrentDocuments(optional sType as string)
dim oEnum as object, oPosDoc as object, i as integer
dim oListboxDocs as object

oEnum = StarDesktop.getComponents.createEnumeration

'Count windows
i = -1
while oEnum.hasMoreElements
oPosDoc = oEnum.nextElement
' The check for interface XserviceInfo necessary as some windows, e.g. Help
' don't have the interface and need to be excluded anyway.
If HasUnoInterfaces(oPosDoc, "com.sun.star.lang.XServiceInfo") Then
if isMissing(sType) then
i = i + 1
elseif fnWhichComponent(oPosDoc) = Stype then
i = i + 1
end if
end if
wend

if i = -1 then
'no documents of specified type currently open
exit function
end if

dim mDocs(i)

i = -1
oEnum = StarDesktop.getComponents.createEnumeration
while oEnum.hasMoreElements
oPosDoc = oEnum.nextElement
If HasUnoInterfaces( oPosDoc, "com.sun.star.lang.XServiceInfo") Then
If isMissing(sType) then
i = i + 1
mDocs(i) = oPosDoc
elseif fnWhichComponent(oPosDoc) = Stype then
i = i + 1
mDocs(i) = oPosDoc
end if
end if
wend
fnCurrentDocuments = mDocs()
end function
</code>
An example of calling the above function. This function returns an array of the titles for the currently open documents.

<code>[oobas]
function fnCurrentDocTitles(optional sType as string)
if isMissing(sType) then
mDocs = fnCurrentDocuments()
else
mDocs = fnCurrentDocuments(SType)
end if

if isEmpty(mDocs) then
exit function
end if

nDocs = uBound(mDocs)

dim mTitles(nDocs)

for i = 0 to nDocs
mTitles(i) = mDocs(i).getCurrentController.getFrame.getPropertyValue("Title")
next
fnCurrentDocTitles = mTitles()
End function
</code>
An example of displaying the titles of the currently open documents:

<code>[oobas]
sText = "Text"
mCurTitles = fnCurrentDocTitles(sText)
if not isEmpty(mCurTitles) then
msgbox join(mCurTitles, chr(10)), 0, "Currently open " & sText & "documents."
else
msgbox "No Text documents currently open."
end if
</code>

Currently active document

2006-05-01T23:53:31Z

Iannz:

'''The currently active document can be accessed using thisComponent.'''

An almost equivalent to the BASIC command thisComponent is:

<code>[oobas]
StarDesktop.CurrentComponent
</code>
In OpenOffice.org basic it is generally preferable to use <tt>thisComponent</tt>.

By using <tt>StarDesktop.CurrentComponent</tt>, a macro in one document can be run on another document.

Another exception is when a routine is run by the OpenOffice.org event "Document Open". In this case use <tt>StarDesktop.CurrentComponent</tt> and a check on the document type. The reason for not using <tt>thisComponent</tt> is that when a library is opened the event fires and thus runs a second time on the currently active document.

To determine the type of document that is currently active you could use the following function:

<code>[oobas]
function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

An example of calling this function is:

<code>[oobas]
if fnWhichComponent(thisComponent) <> "Text" then
msgbox "Sorry - this only works for text documents", 16, "Error"
exit sub
end if
</code>

Working with documents

2006-05-01T23:48:03Z

Iannz:

[[Currently active document]]

[[Currently open documents]]

[[Creating a document]]

[[Opening a document]]

[[Saving a document]]

[[Printing a document]]

[[Closing a document]]

Working with documents

2006-05-01T23:47:20Z

Iannz:

'''Working with documents '''

[[Currently active document]]

[[Currently open documents]]

[[Creating a document]]

[[Opening a document]]

[[Saving a document]]

[[Printing a document]]

[[Closing a document]]

CookBook

2006-05-01T23:45:52Z

Iannz:

'''Cookbook '''

The material in this tutorial style cookbook builds upon the material covered in [[Extensions_development_basic|Starting in Basic]].

=General Guides=
[[Working with documents]]

[[Working with properties]]

[[Sorting and searching]]

[[Working with styles]]

=Component specific guides=
[[Working with Text Documents]]

[[Working with Spreadsheets]]

Extensions development basic

2006-05-01T23:39:15Z

Iannz:

'''Getting started tutorial'''

This page provides a getting started guide for writing macros in OpenOffice.org Basic. It assumes some prior programming knowledge. Please edit this page to make it more readable. I hope you will find it useful.

If you already know the basics then you may want the [[CookBook]] for wrappers and examples.

=Where do I write the code?=
OpenOffice.org Basic code is stored in modules within libraries. A library can be:

*Shared (for a network install - OOo Macros & Dialogs)
*Just for the current user (My Macros & Dialogs)
*Within a document or template, so that its code is only available when that document is open.Within a document or template, so that its code is only available when that document is open.
Libraries not stored in a document or template (that is libraries that are shared or for the current user) are referred to as '''OpenOffice.org libraries'''.

To determine the actual folders that contain the OpenOffice.org libraries see: '''Tools > Options… > OpenOffice.org > Paths > BASIC'''.

{| border="1"
|'''Note'''
|Do not copy or move libraries using operating system commands. Use the macro organizer or package manager instead.
|-
|}

Modules within libraries have a maximum size of 64kb. A library can contain up to 16,000 modules.

For more information see online help for: Modules and Libraries.

=Accessing the IDE=
To access the IDE for the first time:

OpenOffice.org 1.1.x: '''Tools > Macros > Macro… >'''

OpenOffice.org 1.9.x and above: '''Tools > Macros > Organize macros > OpenOffice.org Basic… >'''

To get started we will use Module1 in the Standard library which is stored for the current user only:

Type a name for the new macro: '''HelloWorld'''

In the macro from listbox select '''Standard'''

Click '''New'''

You should now see something like:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
The cursor will be positioned at the start of the <tt>Sub HelloWorld</tt> line.

{| border="1"
|'''Note'''
|Now that while the IDE is running it can be accessed from the OpenOffice.org Window menu, or the task panel provided by the operating system.
|-
|}

=Entering the code=
Select and delete:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Below the line "Sub HelloWorld" type <tt>msgbox "Hello World!"</tt>, so that the editor looks like:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|The IDE does not provide code completion or help with command syntax as you type, but to get help on a Basic command position the cursor in the command and press F1. OpenOffice.org Basic commands are not case sensitive. Thus msgbox, MSGBOX and Msgbox will all work. Strings are enclosed in double quotes.
|-
|}

=Running the code=
There are several ways of running the Basic code, these include:

Directly from the IDE. There is a run button on the macro bar (by default the third control on the second toolbar). This will run the first macro in the current module.

From the tools menu:

(Version 1.1.x) '''Tools > Macros > Macro…''';

(Version 1.9.x and above) '''Tools > Macro > Run Macro…'''

Assigning the macro to a [[ key press]].

Assigning the macro to a [[ menu entry]].

Assigning the macro to a toolbar button.

Creating a [[ control in a document]].

Assigning the macro to an event.

For now try running the "HelloWorld" subroutine by clicking the '''Run''' button. A small dialog titled "soffice" with the text "Hello World!" and an OK button should be displayed.

=Saving the code=
The code gets automatically saved whenever the container for the code gets saved. Thus, if the code is in an OpenOffice.org library (shared or users) then it gets automatically saved when OpenOffice.org exits. If the code is in a library which is part of a document it gets saved whenever the document is saved.

On the Standard toolbar (by default the top toolbar) in the IDE there is a save button. If the code is in a document or template then clicking this button saves the entire document or template. If the code is in an OpenOffice.org library then just the current library gets saved.

=Variables=
It is possible to force variable declaration with <tt>Option Explicit</tt> at the top of the module. For a discussion on whether to declare variables or not see: [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 this discussion]].

In that discussion the initial author of this wiki thought that variables should always be declared. Since then he has changed to not declaring them. In short it is generally a personal preference. In either case, it is the initial authors preference that variables be named according to the following convention, which is used in the examples in this Wiki:

The first letter of the variable name indicates the type of value that the variable is going to hold, as per the following table (based on a table in Tutorial.pdf by Sun)

{| border="1"
|'''''Letter'''''
|'''''Meaning'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE or FALSE)
|-
|e
|Enumeration. This variable can only have one of a limited set of values.
|-
|f
|Float (3.402823 x 1038 to 1.401298 x 10-45. A single variable can take up to four bytes) Double (1.79769313486232 x 10308 to 4.94065645841247 x 10-324. A double variable can take up to eight bytes) Currency (-922337203685477.5808 to +922337203685477.5807 and takes up to eight bytes of memory)
|-
|m
|Array (aka sequence aka matrix)
|-
|n
|Integer (-32768 to 32767.) or Long (-2147483648 and 2147483647).
|-
|o
|Object, service, or interface
|-
|s
|String (A string variable can store up to 65535 Unicode characters).
|-
|x
|Interface, to indicate that only operations of a particular interface of an object are used
|-
|v
|Variant, Any
|-
|}

Use long descriptive variable names making use of camel case

{| border="1"
|'''Note:'''
|User defined OpenOffice.org Basic variables are not case sensitive. But UNO-API constants are case sensitive.
|}

Convention exceptions to long descriptive names is for index variables where i, j, and k are commonly used, and for when a string is being built-up, where s is commonly used.

Edit sub HelloWorld so that it looks like the following and run it:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>
For more information on variables see the online help for "using variables".

=Understanding the OpenOffice.org API=
This section will start with an example. The remainder of this section aims to give information so that the example can be understood and expanded upon.

Try running the following code with different types of documents being active.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

==Subroutine naming convention==
In the above example the user defined function has a name that starts with the letters "fn". This is the initial authors convention so that people know that this is a user defined function. Similarly, the initial author uses the convention that user defined subroutines start with the letters "sub". When learning a language and an API it can be difficult to know what is built-in and what has been defined elsewhere. This document/wiki will use this convention for naming functions and subroutines.

==Introducing the OpenOffice.org API==
This section introduces the following terms:

* Interface
* Module
* Service
* Method
* Property

Understanding the difference between an interface and a service and what a module is, is not essential to being able to write extensions for OpenOffice.org, but it does help interpreting the documentation, and for introspection purposes. You may need to read this section at least twice.

An '''interface''' is a ''definition'' of a set of methods (and their arguments) that a service which implements that interface must have.

Interfaces are grouped together in '''modules''' for naming purposes. All interfaces (and services) start with the name "com.sun.star" then the name of the module then the name of the interface (or service).

For example most services provide the com.sun.star.beans.XPropertySet interface. This interface is stored in the module "beans" and provides access to the properties of a service. A '''property''' is a value where as a '''method''' is an action.

An OpenOffice.org object can have many services.

An OpenOffice.org object may have a service, which implements an interface, in which a method description says that another OpenOffice.org object is returned.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==X-Ray tool==
Using HasUnoInterfaces and supportsService gives information about an object at run time, but checking an object like this would be a nightmare for learning? Thankfully Bernard Marcelly has come to our rescue with the X-Ray tool. The X-Ray tool is available from: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Download the zip file, unzip the document, open the document in OpenOffice.org, follow the instructions for installation and set-up.

Part of the X-Ray tool set-up is to specify a local copy of the OpenOffice.org SDK. Download the OpenOffice.org SDK from and extract it.

In the above example, at the start of the code, there are two commented lines (comments start with an apostrophe):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Now that you have the X-Ray tool installed, uncomment these lines (remove the apostrophes) and rerun the macro. From version 5 of Xray the command simply becomes xray.

'''BasicLibraries''' is an OpenOffice.org Basic command that returns an object for accessing the OpenOffice.org libraries. The <tt>loadLibrary</tt> method ensures that the routines in that library are available for use.

<tt>xray.xray</tt> specifies the xray library and the xray subroutine within that library, thisComponent is the object that is being passed to xray for introspection.

To find the object that you want to work with often requires finding or creating it starting from either StarDesktop or thisComponent.

==Desktop, documents, and current selection==
StarDesktop and ThisComponent are OpenOffice.org Basic commands that refer to the application and currently active document respectively.

Unlike Microsoft Office, OpenOffice.org is one application with different components. When running some code it maybe useful to check which component is currently active. The above code demonstrates how that checking process can be done.

The Desktop that StarDesktop refers to is conceptual (historically it actually existed) and can be thought of as the OpenOffice.org application.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

Extensions development basic

2006-05-01T03:35:57Z

Iannz: /* Running the code */

'''Getting started tutorial'''

This page provides a getting started guide for writing macros in OpenOffice.org Basic. It assumes some prior programming knowledge. Please edit this page to make it more readable. I hope you will find it useful in getting started.

=Where do I write the code?=
OpenOffice.org Basic code is stored in modules within libraries. A library can be:

*Shared (for a network install - OOo Macros & Dialogs)
*Just for the current user (My Macros & Dialogs)
*Within a document or template, so that its code is only available when that document is open.Within a document or template, so that its code is only available when that document is open.
Libraries not stored in a document or template (that is libraries that are shared or for the current user) are referred to as '''OpenOffice.org libraries'''.

To determine the actual folders that contain the OpenOffice.org libraries see: '''Tools > Options… > OpenOffice.org > Paths > BASIC'''.

{| border="1"
|'''Note'''
|Do not copy or move libraries using operating system commands. Use the macro organizer or package manager instead.
|-
|}

Modules within libraries have a maximum size of 64kb. A library can contain up to 16,000 modules.

For more information see online help for: Modules and Libraries.

=Accessing the IDE=
To access the IDE for the first time:

OpenOffice.org 1.1.x: '''Tools > Macros > Macro… >'''

OpenOffice.org 1.9.x and above: '''Tools > Macros > Organize macros > OpenOffice.org Basic… >'''

To get started we will use Module1 in the Standard library which is stored for the current user only:

Type a name for the new macro: '''HelloWorld'''

In the macro from listbox select '''Standard'''

Click '''New'''

You should now see something like:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
The cursor will be positioned at the start of the <tt>Sub HelloWorld</tt> line.

{| border="1"
|'''Note'''
|Now that while the IDE is running it can be accessed from the OpenOffice.org Window menu, or the task panel provided by the operating system.
|-
|}

=Entering the code=
Select and delete:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Below the line "Sub HelloWorld" type <tt>msgbox "Hello World!"</tt>, so that the editor looks like:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|The IDE does not provide code completion or help with command syntax as you type, but to get help on a Basic command position the cursor in the command and press F1. OpenOffice.org Basic commands are not case sensitive. Thus msgbox, MSGBOX and Msgbox will all work. Strings are enclosed in double quotes.
|-
|}

=Running the code=
There are several ways of running the Basic code, these include:

Directly from the IDE. There is a run button on the macro bar (by default the third control on the second toolbar). This will run the first macro in the current module.

From the tools menu:

(Version 1.1.x) '''Tools > Macros > Macro…''';

(Version 1.9.x and above) '''Tools > Macro > Run Macro…'''

Assigning the macro to a [[ key press]].

Assigning the macro to a [[ menu entry]].

Assigning the macro to a toolbar button.

Creating a [[ control in a document]].

Assigning the macro to an event.

For now try running the "HelloWorld" subroutine by clicking the '''Run''' button. A small dialog titled "soffice" with the text "Hello World!" and an OK button should be displayed.

=Saving the code=
The code gets automatically saved whenever the container for the code gets saved. Thus, if the code is in an OpenOffice.org library (shared or users) then it gets automatically saved when OpenOffice.org exits. If the code is in a library which is part of a document it gets saved whenever the document is saved.

On the Standard toolbar (by default the top toolbar) in the IDE there is a save button. If the code is in a document or template then clicking this button saves the entire document or template. If the code is in an OpenOffice.org library then just the current library gets saved.

=Variables=
It is possible to force variable declaration with <tt>Option Explicit</tt> at the top of the module. For a discussion on whether to declare variables or not see: [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 this discussion]].

In that discussion the initial author of this wiki thought that variables should always be declared. Since then he has changed to not declaring them. In short it is generally a personal preference. In either case, it is the initial authors preference that variables be named according to the following convention, which is used in the examples in this Wiki:

The first letter of the variable name indicates the type of value that the variable is going to hold, as per the following table (based on a table in Tutorial.pdf by Sun)

{| border="1"
|'''''Letter'''''
|'''''Meaning'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE or FALSE)
|-
|e
|Enumeration. This variable can only have one of a limited set of values.
|-
|f
|Float (3.402823 x 1038 to 1.401298 x 10-45. A single variable can take up to four bytes) Double (1.79769313486232 x 10308 to 4.94065645841247 x 10-324. A double variable can take up to eight bytes) Currency (-922337203685477.5808 to +922337203685477.5807 and takes up to eight bytes of memory)
|-
|m
|Array (aka sequence aka matrix)
|-
|n
|Integer (-32768 to 32767.) or Long (-2147483648 and 2147483647).
|-
|o
|Object, service, or interface
|-
|s
|String (A string variable can store up to 65535 Unicode characters).
|-
|x
|Interface, to indicate that only operations of a particular interface of an object are used
|-
|v
|Variant, Any
|-
|}

Use long descriptive variable names making use of camel case

{| border="1"
|'''Note:'''
|User defined OpenOffice.org Basic variables are not case sensitive. But UNO-API constants are case sensitive.
|}

Convention exceptions to long descriptive names is for index variables where i, j, and k are commonly used, and for when a string is being built-up, where s is commonly used.

Edit sub HelloWorld so that it looks like the following and run it:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
'all your code should be like this for lonog time survival
msgbox "Hello World " & i
next i
end sub
</code>
For more information on variables see the online help for "using variables".

=Understanding the OpenOffice.org API=
This section will start with an example. The remainder of this section aims to give information so that the example can be understood and expanded upon.

Try running the following code with different types of documents being active.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

==Subroutine naming convention==
In the above example the user defined function has a name that starts with the letters "fn". This is the initial authors convention so that people know that this is a user defined function. Similarly, the initial author uses the convention that user defined subroutines start with the letters "sub". When learning a language and an API it can be difficult to know what is built-in and what has been defined elsewhere. This document/wiki will use this convention for naming functions and subroutines.

==Introducing the OpenOffice.org API==
This section introduces the following terms:

* Interface
* Module
* Service
* Method
* Property

Understanding the difference between an interface and a service and what a module is, is not essential to being able to write extensions for OpenOffice.org, but it does help interpreting the documentation, and for introspection purposes. You may need to read this section at least twice.

An '''interface''' is a ''definition'' of a set of methods (and their arguments) that a service which implements that interface must have.

Interfaces are grouped together in '''modules''' for naming purposes. All interfaces (and services) start with the name "com.sun.star" then the name of the module then the name of the interface (or service).

For example most services provide the com.sun.star.beans.XPropertySet interface. This interface is stored in the module "beans" and provides access to the properties of a service. A '''property''' is a value where as a '''method''' is an action.

An OpenOffice.org object can have many services.

An OpenOffice.org object may have a service, which implements an interface, in which a method description says that another OpenOffice.org object is returned.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==X-Ray tool==
Using HasUnoInterfaces and supportsService gives information about an object at run time, but checking an object like this would be a nightmare for learning? Thankfully Bernard Marcelly has come to our rescue with the X-Ray tool. The X-Ray tool is available from: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Download the zip file, unzip the document, open the document in OpenOffice.org, follow the instructions for installation and set-up.

Part of the X-Ray tool set-up is to specify a local copy of the OpenOffice.org SDK. Download the OpenOffice.org SDK from and extract it.

In the above example, at the start of the code, there are two commented lines (comments start with an apostrophe):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Now that you have the X-Ray tool installed, uncomment these lines (remove the apostrophes) and rerun the macro. From version 5 of Xray the command simply becomes xray.

'''BasicLibraries''' is an OpenOffice.org Basic command that returns an object for accessing the OpenOffice.org libraries. The <tt>loadLibrary</tt> method ensures that the routines in that library are available for use.

<tt>xray.xray</tt> specifies the xray library and the xray subroutine within that library, thisComponent is the object that is being passed to xray for introspection.

To find the object that you want to work with often requires finding or creating it starting from either StarDesktop or thisComponent.

==Desktop, documents, and current selection==
StarDesktop and ThisComponent are OpenOffice.org Basic commands that refer to the application and currently active document respectively.

Unlike Microsoft Office, OpenOffice.org is one application with different components. When running some code it maybe useful to check which component is currently active. The above code demonstrates how that checking process can be done.

The Desktop that StarDesktop refers to is conceptual (historically it actually existed) and can be thought of as the OpenOffice.org application.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

L'enregistreur de macro OpenOffice.org et les appels UNO (dispatch)

2006-04-04T06:22:39Z

Iannz:

'''The OpenOffice.org recorder and UNO dispatch calls'''

OpenOffice.org provides a recorder, to record a series of actions, in '''Writer and Calc only''', to produce some code. The recorder produces a series of UNO dispatch calls, which are not particularly useful for learning the OpenOffice.org API model. I personally find the code that the recorder produces to be a little hard to follow. It is generally considered preferable to use OpenOffice.org API calls but sometimes the only way or most convenient way is to use UNO dispatch calls.

For a list of dispatch calls see: http://www.openoffice.org/files/documents/25/2570/commandsReference.html

Below are three versions of the same macro:

*Recorded example
*Tidied UNO dispatch calls
*API Calls

The series of steps recorded were:

Type "Some text" ; Press '''Enter'''; Type "A new paragraph with a "; '''Format > Character… > Bold > OK'''; Type "bold"; '''Format > Character… > Regular> OK'''; Type " word in it".

{| border="1"
|'''Note:'''
|This would be best handled with autotext, but this simple example demonstrates the point.
|}

==Recorded example==
<code>[oobas]
sub Example
rem ----------------------------------------------------------------------
rem define variables
dim document as object
dim dispatcher as object
rem ----------------------------------------------------------------------
rem get access to the document
document = ThisComponent.CurrentController.Frame
dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")

rem ----------------------------------------------------------------------
dim args1(0) as new com.sun.star.beans.PropertyValue
args1(0).Name = "Text"
args1(0).Value = "Some text"

dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args1())

rem ----------------------------------------------------------------------
dispatcher.executeDispatch(document, ".uno:InsertPara", "", 0, Array())

rem ----------------------------------------------------------------------
dim args3(0) as new com.sun.star.beans.PropertyValue
args3(0).Name = "Text"
args3(0).Value = "A new paragraph with a "

dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args3())

rem ----------------------------------------------------------------------
dim args4(0) as new com.sun.star.beans.PropertyValue
args4(0).Name = "Bold"
args4(0).Value = true

dispatcher.executeDispatch(document, ".uno:Bold", "", 0, args4())

rem ----------------------------------------------------------------------
dim args5(0) as new com.sun.star.beans.PropertyValue
args5(0).Name = "Text"
args5(0).Value = "bold"

dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args5())

rem ----------------------------------------------------------------------
dim args6(0) as new com.sun.star.beans.PropertyValue
args6(0).Name = "Bold"
args6(0).Value = false

dispatcher.executeDispatch(document, ".uno:Bold", "", 0, args6())

rem ----------------------------------------------------------------------
dim args7(0) as new com.sun.star.beans.PropertyValue
args7(0).Name = "Text"
args7(0).Value = " word in it."

dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args7())

end sub
</code>

==Tidied UNO dispatch calls==
(This heading is linked to from [[ UNO Dispatch]], so if you change it change the link as well.)

Now the same example having been tidied using a function for calling the UNO dispatch calls (some UNO Dispatch calls return a value so using a function makes it more generically useful than a sub):

<code>[oobas]
sub Example
fnDispatch("InsertText", array("Text","Some text"))
fnDispatch("InsertPara")
fnDispatch("InsertText", array("Text","A new paragraph with a "))
fnDispatch("Bold", array("Bold",true))
fnDispatch("InsertText", array("Text","bold"))
fnDispatch("Bold", array("Bold",false))
fnDispatch("InsertText", array("Text"," word in it."))
end sub

function fnDispatch(sCommand as string, optional mArgs)
oFrame = ThisComponent.getCurrentController.getFrame
oDispatcher = createUnoService("com.sun.star.frame.DispatchHelper")
'on error resume next
if isMissing(mArgs) then
fnDispatch = oDispatcher.executeDispatch(oFrame, ".uno:" & sCommand, "", 0, array())
else
nArgs = uBound(mArgs) \ 2
dim Args(nArgs) as new com.sun.star.beans.PropertyValue
for i = 0 to nArgs
Args(i).name = mArgs(i * 2)
Args(i).value = mArgs(i * 2 + 1)
next
fnDispatch = oDispatcher.executeDispatch(oFrame, ".uno:" & sCommand, "", 0, Args())
end if
end function
</code>

==API calls==
Finally the same example using API calls:

<code>[oobas]
sub Example
oVC = thisComponent.getCurrentController.getViewCursor
oText = oVC.text
oText.insertString(oVC, "Some text", False)
oText.insertControlCharacter(oVC, com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False)
oText.insertString(oVC, "A new paragraph with a ", False)
oVC.setPropertyValue("CharWeight", com.sun.star.awt.FontWeight.BOLD)
oText.insertString(oVC, "bold", false)
oVC.setPropertyValue("CharWeight", com.sun.star.awt.FontWeight.NORMAL)
oText.insertString(oVC, " word in it.", false)
end sub
</code>

Current selection

2006-04-04T06:11:19Z

Iannz:

'''Current Selection in Text Documents'''

Also see [[ Getting started]].

Having made sure that text is selected, it is common to create a loop to do something to all of the currently selected text. But, remember that the first element of the array is either the current selection when there is only one selection, or the insertion point when there is more than one selection. Thus the following common code:

<code>[oobas]
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
if nCount = 1 then
oTextRange = oCurSelection.getByIndex(0)
'Do some action on oTextRange
else
for i = 1 to nCount - 1
oTextRange = oCurSelection.getByIndex(i)
'Do some action on oTextRange
next
end if
end if
</code>

URL Basics

2006-04-04T06:08:15Z

Iannz:

The following information is based on material found in: StarOffice™ 7 Office Suite A Sun™ ONE Software Offering Basic Programmer's Guide Page 74. See http://docs.sun.com/app/docs/doc/817-1826?q=StarOffice.

=File Names in URL Notation=
Since OpenOffice.org is a platform-independent application, it uses URL notation (which is independent of any operating system), as defined in the Internet Standard RFC 1738 for file names. Standard file names using this system begin with the prefix file:/// followed by the local path. If the file name contains sub-directories, then these are separated by a single forward slash., not with a backslash usually used under Windows. The following path references the test.sxw file in the doc directory on the C drive:.

<code>[oobas]
file:///C:/doc/test.sxw
</code>
To covert local file names into an URL, OpenOffice.org provides the ConvertToUrl function. To convert an URL into a local file name, OpenOffice.org provides the ConvertFromUrl function:

<code>[oobas]
MsgBox ConvertToUrl("C:\doc\test.sxw") ' supplies file:///C:/doc/test.sxw
MsgBox ConvertFromUrl("file:///C:/doc/test.sxw") ' supplies (under Windows) c:\doc\test.sxw
</code>
The example converts a local file name into a URL and displays it in a message box. It then converts a URL into a local file name and also displays this.

The Internet Standard RFC 1738, upon which this is based, permits use of the 0-9, a-z, and A-Z characters. All other characters are inserted as escape coding in the URLs. To do this, they are converted into their hexadecimal value in the ISO 8859-1 (ISO-Latin) set of characters and are preceded by a percent sign. A space in a local file name therefore, for example, becomes a %20 in the URL.

URL Basics

2006-04-04T06:07:09Z

Iannz:

The following information is based on material found in: StarOffice™ 7 Office Suite A Sun™ ONE Software Offering Basic Programmer's Guide Page 74. See http://docs.sun.com/app/docs/doc/817-1826?q=StarOffice.

=File Names in URL Notation=
Since OpenOffice.org is a platform-independent application, it uses URL notation (which is independent of any operating system), as defined in the Internet Standard RFC 1738 for file names. Standard file names using this system begin with the prefix file:/// followed by the local path. If the file name contains sub-directories, then these are separated by a single forward slash., not with a backslash usually used under Windows. The following path references the test.sxw file in the doc directory on the C drive:.

<code>[oobas]
file:///C:/doc/test.sxw
</code>
To covert local file names into an URL, OpenOffice.org provides the [[ ConvertToUrl]] function. To convert an URL into a local file name, OpenOffice.org provides the [[ ConvertFromUrl]] function:

<code>[oobas]
MsgBox ConvertToUrl("C:\doc\test.sxw") ' supplies file:///C:/doc/test.sxw
MsgBox ConvertFromUrl("file:///C:/doc/test.sxw") ' supplies (under Windows) c:\doc\test.sxw
</code>
The example converts a local file name into a URL and displays it in a message box. It then converts a URL into a local file name and also displays this.

The Internet Standard RFC 1738, upon which this is based, permits use of the 0-9, a-z, and A-Z characters. All other characters are inserted as escape coding in the URLs. To do this, they are converted into their hexadecimal value in the ISO 8859-1 (ISO-Latin) set of characters and are preceded by a percent sign. A space in a local file name therefore, for example, becomes a %20 in the URL.

Extensions development basic

2006-04-04T06:02:11Z

Iannz: /* Creating new documents */

'''Getting started tutorial'''

This page provides a getting started guide for writing macros in OpenOffice.org Basic. It assumes some prior programming knowledge. Please edit this page to make it more readable. I hope you will find it useful in getting started.

=Where do I write the code?=
OpenOffice.org Basic code is stored in modules within libraries. A library can be:

*Shared (for a network install - OOo Macros & Dialogs)
*Just for the current user (My Macros & Dialogs)
*Within a document or template, so that its code is only available when that document is open.Within a document or template, so that its code is only available when that document is open.
Libraries not stored in a document or template (that is libraries that are shared or for the current user) are referred to as '''OpenOffice.org libraries'''.

To determine the actual folders that contain the OpenOffice.org libraries see: '''Tools > Options… > OpenOffice.org > Paths > BASIC'''.

{| border="1"
|'''Note'''
|Do not copy or move libraries using operating system commands. Use the macro organizer or package manager instead.
|-
|}

Modules within libraries have a maximum size of 64kb. A library can contain up to 16,000 modules.

For more information see online help for: Modules and Libraries.

=Accessing the IDE=
To access the IDE for the first time:

OpenOffice.org 1.1.x: '''Tools > Macros > Macro… >'''

OpenOffice.org 1.9.x and above: '''Tools > Macros > Organize macros > OpenOffice.org Basic… >'''

To get started we will use Module1 in the Standard library which is stored for the current user only:

Type a name for the new macro: '''HelloWorld'''

In the macro from listbox select '''Standard'''

Click '''New'''

You should now see something like:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
The cursor will be positioned at the start of the <tt>Sub HelloWorld</tt> line.

{| border="1"
|'''Note'''
|Now that while the IDE is running it can be accessed from the OpenOffice.org Window menu, or the task panel provided by the operating system.
|-
|}

=Entering the code=
Select and delete:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Below the line "Sub HelloWorld" type <tt>msgbox "Hello World!"</tt>, so that the editor looks like:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|The IDE does not provide code completion or help with command syntax as you type, but to get help on a Basic command position the cursor in the command and press F1. OpenOffice.org Basic commands are not case sensitive. Thus msgbox, MSGBOX and Msgbox will all work. Strings are enclosed in double quotes.
|-
|}

=Running the code=
There are several ways of running the Basic code, these include:

Directly from the IDE. There is a run button on the macro bar (by default the third control on the second toolbar). This will run the first macro in the current module.

From the tools menu: (Version 1.1.x) '''Tools > Macros > Macro…'''; (Version 1.9.x and above) '''Tools > Macro > Run Macro…'''

Assigning the macro to a [[ key press]].

Assigning the macro to a [[ menu entry]].

Assigning the macro to a toolbar button.

Creating a [[ control in a document]].

Assigning the macro to an event.

For now try running the "HelloWorld" subroutine by clicking the '''Run''' button. A small dialog titled "soffice" with the text "Hello World!" and an OK button should be displayed.

=Saving the code=
The code gets automatically saved whenever the container for the code gets saved. Thus, if the code is in an OpenOffice.org library (shared or users) then it gets automatically saved when OpenOffice.org exits. If the code is in a library which is part of a document it gets saved whenever the document is saved.

On the Standard toolbar (by default the top toolbar) in the IDE there is a save button. If the code is in a document or template then clicking this button saves the entire document or template. If the code is in an OpenOffice.org library then just the current library gets saved.

=Variables=
It is possible to force variable declaration with <tt>Option Explicit</tt> at the top of the module. For a discussion on whether to declare variables or not see: [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 this discussion]].

In that discussion the initial author of this wiki thought that variables should always be declared. Since then he has changed to not declaring them. In short it is generally a personal preference. In either case, it is the initial authors preference that variables be named according to the following convention, which is used in the examples in this Wiki:

The first letter of the variable name indicates the type of value that the variable is going to hold, as per the following table (based on a table in Tutorial.pdf by Sun)

{| border="1"
|'''''Letter'''''
|'''''Meaning'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE or FALSE)
|-
|e
|Enumeration. This variable can only have one of a limited set of values.
|-
|f
|Float (3.402823 x 1038 to 1.401298 x 10-45. A single variable can take up to four bytes) Double (1.79769313486232 x 10308 to 4.94065645841247 x 10-324. A double variable can take up to eight bytes) Currency (-922337203685477.5808 to +922337203685477.5807 and takes up to eight bytes of memory)
|-
|m
|Array (aka sequence aka matrix)
|-
|n
|Integer (-32768 to 32767.) or Long (-2147483648 and 2147483647).
|-
|o
|Object, service, or interface
|-
|s
|String (A string variable can store up to 65535 Unicode characters).
|-
|x
|Interface, to indicate that only operations of a particular interface of an object are used
|-
|v
|Variant, Any
|-
|}

Use long descriptive variable names making use of camel case

{| border="1"
|'''Note:'''
|User defined OpenOffice.org Basic variables are not case sensitive. But UNO-API constants are case sensitive.
|}

Convention exceptions to long descriptive names is for index variables where i, j, and k are commonly used, and for when a string is being built-up, where s is commonly used.

Edit sub HelloWorld so that it looks like the following and run it:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
msgbox "Hello World " & i
next
end sub
</code>
For more information on variables see the online help for "using variables".

=Understanding the OpenOffice.org API=
This section will start with an example. The remainder of this section aims to give information so that the example can be understood and expanded upon.

Try running the following code with different types of documents being active.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

==Subroutine naming convention==
In the above example the user defined function has a name that starts with the letters "fn". This is the initial authors convention so that people know that this is a user defined function. Similarly, the initial author uses the convention that user defined subroutines start with the letters "sub". When learning a language and an API it can be difficult to know what is built-in and what has been defined elsewhere. This document/wiki will use this convention for naming functions and subroutines.

==Introducing the OpenOffice.org API==
This section introduces the following terms:

* Interface
* Module
* Service
* Method
* Property

Understanding the difference between an interface and a service and what a module is, is not essential to being able to write extensions for OpenOffice.org, but it does help interpreting the documentation, and for introspection purposes. You may need to read this section at least twice.

An '''interface''' is a ''definition'' of a set of methods (and their arguments) that a service which implements that interface must have.

Interfaces are grouped together in '''modules''' for naming purposes. All interfaces (and services) start with the name "com.sun.star" then the name of the module then the name of the interface (or service).

For example most services provide the com.sun.star.beans.XPropertySet interface. This interface is stored in the module "beans" and provides access to the properties of a service. A '''property''' is a value where as a '''method''' is an action.

An OpenOffice.org object can have many services.

An OpenOffice.org object may have a service, which implements an interface, in which a method description says that another OpenOffice.org object is returned.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==X-Ray tool==
Using HasUnoInterfaces and supportsService gives information about an object at run time, but checking an object like this would be a nightmare for learning? Thankfully Bernard Marcelly has come to our rescue with the X-Ray tool. The X-Ray tool is available from: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Download the zip file, unzip the document, open the document in OpenOffice.org, follow the instructions for installation and set-up.

Part of the X-Ray tool set-up is to specify a local copy of the OpenOffice.org SDK. Download the OpenOffice.org SDK from and extract it.

In the above example, at the start of the code, there are two commented lines (comments start with an apostrophe):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Now that you have the X-Ray tool installed, uncomment these lines (remove the apostrophes) and rerun the macro. From version 5 of Xray the command simply becomes xray.

'''BasicLibraries''' is an OpenOffice.org Basic command that returns an object for accessing the OpenOffice.org libraries. The <tt>loadLibrary</tt> method ensures that the routines in that library are available for use.

<tt>xray.xray</tt> specifies the xray library and the xray subroutine within that library, thisComponent is the object that is being passed to xray for introspection.

To find the object that you want to work with often requires finding or creating it starting from either StarDesktop or thisComponent.

==Desktop, documents, and current selection==
StarDesktop and ThisComponent are OpenOffice.org Basic commands that refer to the application and currently active document respectively.

Unlike Microsoft Office, OpenOffice.org is one application with different components. When running some code it maybe useful to check which component is currently active. The above code demonstrates how that checking process can be done.

The Desktop that StarDesktop refers to is conceptual (historically it actually existed) and can be thought of as the OpenOffice.org application.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See http://api.openoffice.org/docs/common/ref/com/sun/star/frame/XComponentLoader.html .

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

Extensions development basic

2006-04-04T05:58:44Z

Iannz: /* Variables */

'''Getting started tutorial'''

This page provides a getting started guide for writing macros in OpenOffice.org Basic. It assumes some prior programming knowledge. Please edit this page to make it more readable. I hope you will find it useful in getting started.

=Where do I write the code?=
OpenOffice.org Basic code is stored in modules within libraries. A library can be:

*Shared (for a network install - OOo Macros & Dialogs)
*Just for the current user (My Macros & Dialogs)
*Within a document or template, so that its code is only available when that document is open.Within a document or template, so that its code is only available when that document is open.
Libraries not stored in a document or template (that is libraries that are shared or for the current user) are referred to as '''OpenOffice.org libraries'''.

To determine the actual folders that contain the OpenOffice.org libraries see: '''Tools > Options… > OpenOffice.org > Paths > BASIC'''.

{| border="1"
|'''Note'''
|Do not copy or move libraries using operating system commands. Use the macro organizer or package manager instead.
|-
|}

Modules within libraries have a maximum size of 64kb. A library can contain up to 16,000 modules.

For more information see online help for: Modules and Libraries.

=Accessing the IDE=
To access the IDE for the first time:

OpenOffice.org 1.1.x: '''Tools > Macros > Macro… >'''

OpenOffice.org 1.9.x and above: '''Tools > Macros > Organize macros > OpenOffice.org Basic… >'''

To get started we will use Module1 in the Standard library which is stored for the current user only:

Type a name for the new macro: '''HelloWorld'''

In the macro from listbox select '''Standard'''

Click '''New'''

You should now see something like:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
The cursor will be positioned at the start of the <tt>Sub HelloWorld</tt> line.

{| border="1"
|'''Note'''
|Now that while the IDE is running it can be accessed from the OpenOffice.org Window menu, or the task panel provided by the operating system.
|-
|}

=Entering the code=
Select and delete:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Below the line "Sub HelloWorld" type <tt>msgbox "Hello World!"</tt>, so that the editor looks like:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|The IDE does not provide code completion or help with command syntax as you type, but to get help on a Basic command position the cursor in the command and press F1. OpenOffice.org Basic commands are not case sensitive. Thus msgbox, MSGBOX and Msgbox will all work. Strings are enclosed in double quotes.
|-
|}

=Running the code=
There are several ways of running the Basic code, these include:

Directly from the IDE. There is a run button on the macro bar (by default the third control on the second toolbar). This will run the first macro in the current module.

From the tools menu: (Version 1.1.x) '''Tools > Macros > Macro…'''; (Version 1.9.x and above) '''Tools > Macro > Run Macro…'''

Assigning the macro to a [[ key press]].

Assigning the macro to a [[ menu entry]].

Assigning the macro to a toolbar button.

Creating a [[ control in a document]].

Assigning the macro to an event.

For now try running the "HelloWorld" subroutine by clicking the '''Run''' button. A small dialog titled "soffice" with the text "Hello World!" and an OK button should be displayed.

=Saving the code=
The code gets automatically saved whenever the container for the code gets saved. Thus, if the code is in an OpenOffice.org library (shared or users) then it gets automatically saved when OpenOffice.org exits. If the code is in a library which is part of a document it gets saved whenever the document is saved.

On the Standard toolbar (by default the top toolbar) in the IDE there is a save button. If the code is in a document or template then clicking this button saves the entire document or template. If the code is in an OpenOffice.org library then just the current library gets saved.

=Variables=
It is possible to force variable declaration with <tt>Option Explicit</tt> at the top of the module. For a discussion on whether to declare variables or not see: [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 this discussion]].

In that discussion the initial author of this wiki thought that variables should always be declared. Since then he has changed to not declaring them. In short it is generally a personal preference. In either case, it is the initial authors preference that variables be named according to the following convention, which is used in the examples in this Wiki:

The first letter of the variable name indicates the type of value that the variable is going to hold, as per the following table (based on a table in Tutorial.pdf by Sun)

{| border="1"
|'''''Letter'''''
|'''''Meaning'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE or FALSE)
|-
|e
|Enumeration. This variable can only have one of a limited set of values.
|-
|f
|Float (3.402823 x 1038 to 1.401298 x 10-45. A single variable can take up to four bytes) Double (1.79769313486232 x 10308 to 4.94065645841247 x 10-324. A double variable can take up to eight bytes) Currency (-922337203685477.5808 to +922337203685477.5807 and takes up to eight bytes of memory)
|-
|m
|Array (aka sequence aka matrix)
|-
|n
|Integer (-32768 to 32767.) or Long (-2147483648 and 2147483647).
|-
|o
|Object, service, or interface
|-
|s
|String (A string variable can store up to 65535 Unicode characters).
|-
|x
|Interface, to indicate that only operations of a particular interface of an object are used
|-
|v
|Variant, Any
|-
|}

Use long descriptive variable names making use of camel case

{| border="1"
|'''Note:'''
|User defined OpenOffice.org Basic variables are not case sensitive. But UNO-API constants are case sensitive.
|}

Convention exceptions to long descriptive names is for index variables where i, j, and k are commonly used, and for when a string is being built-up, where s is commonly used.

Edit sub HelloWorld so that it looks like the following and run it:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
msgbox "Hello World " & i
next
end sub
</code>
For more information on variables see the online help for "using variables".

=Understanding the OpenOffice.org API=
This section will start with an example. The remainder of this section aims to give information so that the example can be understood and expanded upon.

Try running the following code with different types of documents being active.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

==Subroutine naming convention==
In the above example the user defined function has a name that starts with the letters "fn". This is the initial authors convention so that people know that this is a user defined function. Similarly, the initial author uses the convention that user defined subroutines start with the letters "sub". When learning a language and an API it can be difficult to know what is built-in and what has been defined elsewhere. This document/wiki will use this convention for naming functions and subroutines.

==Introducing the OpenOffice.org API==
This section introduces the following terms:

* Interface
* Module
* Service
* Method
* Property

Understanding the difference between an interface and a service and what a module is, is not essential to being able to write extensions for OpenOffice.org, but it does help interpreting the documentation, and for introspection purposes. You may need to read this section at least twice.

An '''interface''' is a ''definition'' of a set of methods (and their arguments) that a service which implements that interface must have.

Interfaces are grouped together in '''modules''' for naming purposes. All interfaces (and services) start with the name "com.sun.star" then the name of the module then the name of the interface (or service).

For example most services provide the com.sun.star.beans.XPropertySet interface. This interface is stored in the module "beans" and provides access to the properties of a service. A '''property''' is a value where as a '''method''' is an action.

An OpenOffice.org object can have many services.

An OpenOffice.org object may have a service, which implements an interface, in which a method description says that another OpenOffice.org object is returned.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==X-Ray tool==
Using HasUnoInterfaces and supportsService gives information about an object at run time, but checking an object like this would be a nightmare for learning? Thankfully Bernard Marcelly has come to our rescue with the X-Ray tool. The X-Ray tool is available from: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Download the zip file, unzip the document, open the document in OpenOffice.org, follow the instructions for installation and set-up.

Part of the X-Ray tool set-up is to specify a local copy of the OpenOffice.org SDK. Download the OpenOffice.org SDK from and extract it.

In the above example, at the start of the code, there are two commented lines (comments start with an apostrophe):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Now that you have the X-Ray tool installed, uncomment these lines (remove the apostrophes) and rerun the macro. From version 5 of Xray the command simply becomes xray.

'''BasicLibraries''' is an OpenOffice.org Basic command that returns an object for accessing the OpenOffice.org libraries. The <tt>loadLibrary</tt> method ensures that the routines in that library are available for use.

<tt>xray.xray</tt> specifies the xray library and the xray subroutine within that library, thisComponent is the object that is being passed to xray for introspection.

To find the object that you want to work with often requires finding or creating it starting from either StarDesktop or thisComponent.

==Desktop, documents, and current selection==
StarDesktop and ThisComponent are OpenOffice.org Basic commands that refer to the application and currently active document respectively.

Unlike Microsoft Office, OpenOffice.org is one application with different components. When running some code it maybe useful to check which component is currently active. The above code demonstrates how that checking process can be done.

The Desktop that StarDesktop refers to is conceptual (historically it actually existed) and can be thought of as the OpenOffice.org application.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See [[ loadComponentFromUrl]].

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

Menu entry

2006-04-04T05:55:55Z

Iannz:

'''Adding a menu entry'''

#Tools > Customize… > Menus
#Select desired menu from thr drop down
#Selecte the desired location in the listbox
#Click Add
#In the category list box: Navigate to the macro by clicking on the + signs next to libraries and click on the module.
#In the function list box: Click the desired function
#Click the Add button
#Click Close > OK

Key press

2006-04-04T05:51:11Z

Iannz:

'''Assigning a macro to a key press'''

#Tools > Customize… > Keyboard
#Select desired key press in the top list box
#Navigate to where tha macro is stored (scroll to the bottom of the Category list box, then click the plus signs to expand libraries and modules)
#In the function list box select the desired macro
#Click the Modify button (top right of dialog)
#Click OK

Extensions development basic

2006-04-04T05:48:04Z

Iannz: /* Entering the code */

'''Getting started tutorial'''

This page provides a getting started guide for writing macros in OpenOffice.org Basic. It assumes some prior programming knowledge. Please edit this page to make it more readable. I hope you will find it useful in getting started.

=Where do I write the code?=
OpenOffice.org Basic code is stored in modules within libraries. A library can be:

*Shared (for a network install - OOo Macros & Dialogs)
*Just for the current user (My Macros & Dialogs)
*Within a document or template, so that its code is only available when that document is open.Within a document or template, so that its code is only available when that document is open.
Libraries not stored in a document or template (that is libraries that are shared or for the current user) are referred to as '''OpenOffice.org libraries'''.

To determine the actual folders that contain the OpenOffice.org libraries see: '''Tools > Options… > OpenOffice.org > Paths > BASIC'''.

{| border="1"
|'''Note'''
|Do not copy or move libraries using operating system commands. Use the macro organizer or package manager instead.
|-
|}

Modules within libraries have a maximum size of 64kb. A library can contain up to 16,000 modules.

For more information see online help for: Modules and Libraries.

=Accessing the IDE=
To access the IDE for the first time:

OpenOffice.org 1.1.x: '''Tools > Macros > Macro… >'''

OpenOffice.org 1.9.x and above: '''Tools > Macros > Organize macros > OpenOffice.org Basic… >'''

To get started we will use Module1 in the Standard library which is stored for the current user only:

Type a name for the new macro: '''HelloWorld'''

In the macro from listbox select '''Standard'''

Click '''New'''

You should now see something like:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
The cursor will be positioned at the start of the <tt>Sub HelloWorld</tt> line.

{| border="1"
|'''Note'''
|Now that while the IDE is running it can be accessed from the OpenOffice.org Window menu, or the task panel provided by the operating system.
|-
|}

=Entering the code=
Select and delete:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Below the line "Sub HelloWorld" type <tt>msgbox "Hello World!"</tt>, so that the editor looks like:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|The IDE does not provide code completion or help with command syntax as you type, but to get help on a Basic command position the cursor in the command and press F1. OpenOffice.org Basic commands are not case sensitive. Thus msgbox, MSGBOX and Msgbox will all work. Strings are enclosed in double quotes.
|-
|}

=Running the code=
There are several ways of running the Basic code, these include:

Directly from the IDE. There is a run button on the macro bar (by default the third control on the second toolbar). This will run the first macro in the current module.

From the tools menu: (Version 1.1.x) '''Tools > Macros > Macro…'''; (Version 1.9.x and above) '''Tools > Macro > Run Macro…'''

Assigning the macro to a [[ key press]].

Assigning the macro to a [[ menu entry]].

Assigning the macro to a toolbar button.

Creating a [[ control in a document]].

Assigning the macro to an event.

For now try running the "HelloWorld" subroutine by clicking the '''Run''' button. A small dialog titled "soffice" with the text "Hello World!" and an OK button should be displayed.

=Saving the code=
The code gets automatically saved whenever the container for the code gets saved. Thus, if the code is in an OpenOffice.org library (shared or users) then it gets automatically saved when OpenOffice.org exits. If the code is in a library which is part of a document it gets saved whenever the document is saved.

On the Standard toolbar (by default the top toolbar) in the IDE there is a save button. If the code is in a document or template then clicking this button saves the entire document or template. If the code is in an OpenOffice.org library then just the current library gets saved.

=Variables=
It is possible to force variable declaration with <tt>Option Explicit</tt> at the top of the module. For a discussion on whether to declare variables or not see: [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 this discussion]].

In that discussion the initial author of this wiki thought that variables should always be declared. Since then he has changed to not declaring them. In short it is generally a personal preference. In either case, it is the initial authors preference that variables be named according to the following convention, which is used in the examples in this Wiki:

The first letter of the variable name indicates the type of value that the variable is going to hold, as per the following table (based on a table in Tutorial.pdf by Sun)

{| border="1"
|'''''Letter'''''
|'''''Meaning'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE or FALSE)
|-
|e
|Enumeration. This variable can only have one of a limited set of values.
|-
|f
|Float (3.402823 x 1038 to 1.401298 x 10-45. A single variable can take up to four bytes) Double (1.79769313486232 x 10308 to 4.94065645841247 x 10-324. A double variable can take up to eight bytes) Currency (-922337203685477.5808 to +922337203685477.5807 and takes up to eight bytes of memory)
|-
|m
|Array (aka sequence aka matrix)
|-
|n
|Integer (-32768 to 32767.) or Long (-2147483648 and 2147483647).
|-
|o
|Object, service, or interface
|-
|s
|String (A string variable can store up to 65535 Unicode characters).
|-
|x
|Interface, to indicate that only operations of a particular interface of an object are used
|-
|v
|Variant, Any
|-
|}

Use long descriptive variable names making use of camel case

{| border="1"
|'''Note:'''
|User defined OpenOffice.org Basic variables are not case sensitive. But UNO-API constants are case sensitive.
|-
|}

Convention exceptions to long descriptive names is for index variables where i, j, and k are commonly used, and for when a string is being built-up, where s is commonly used.

Edit sub HelloWorld so that it looks like the following and run it:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
msgbox "Hello World " & i
next
end sub
</code>
For more information on variables see: [[ using variables]].

=Understanding the OpenOffice.org API=
This section will start with an example. The remainder of this section aims to give information so that the example can be understood and expanded upon.

Try running the following code with different types of documents being active.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

==Subroutine naming convention==
In the above example the user defined function has a name that starts with the letters "fn". This is the initial authors convention so that people know that this is a user defined function. Similarly, the initial author uses the convention that user defined subroutines start with the letters "sub". When learning a language and an API it can be difficult to know what is built-in and what has been defined elsewhere. This document/wiki will use this convention for naming functions and subroutines.

==Introducing the OpenOffice.org API==
This section introduces the following terms:

* Interface
* Module
* Service
* Method
* Property

Understanding the difference between an interface and a service and what a module is, is not essential to being able to write extensions for OpenOffice.org, but it does help interpreting the documentation, and for introspection purposes. You may need to read this section at least twice.

An '''interface''' is a ''definition'' of a set of methods (and their arguments) that a service which implements that interface must have.

Interfaces are grouped together in '''modules''' for naming purposes. All interfaces (and services) start with the name "com.sun.star" then the name of the module then the name of the interface (or service).

For example most services provide the com.sun.star.beans.XPropertySet interface. This interface is stored in the module "beans" and provides access to the properties of a service. A '''property''' is a value where as a '''method''' is an action.

An OpenOffice.org object can have many services.

An OpenOffice.org object may have a service, which implements an interface, in which a method description says that another OpenOffice.org object is returned.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==X-Ray tool==
Using HasUnoInterfaces and supportsService gives information about an object at run time, but checking an object like this would be a nightmare for learning? Thankfully Bernard Marcelly has come to our rescue with the X-Ray tool. The X-Ray tool is available from: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Download the zip file, unzip the document, open the document in OpenOffice.org, follow the instructions for installation and set-up.

Part of the X-Ray tool set-up is to specify a local copy of the OpenOffice.org SDK. Download the OpenOffice.org SDK from and extract it.

In the above example, at the start of the code, there are two commented lines (comments start with an apostrophe):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Now that you have the X-Ray tool installed, uncomment these lines (remove the apostrophes) and rerun the macro. From version 5 of Xray the command simply becomes xray.

'''BasicLibraries''' is an OpenOffice.org Basic command that returns an object for accessing the OpenOffice.org libraries. The <tt>loadLibrary</tt> method ensures that the routines in that library are available for use.

<tt>xray.xray</tt> specifies the xray library and the xray subroutine within that library, thisComponent is the object that is being passed to xray for introspection.

To find the object that you want to work with often requires finding or creating it starting from either StarDesktop or thisComponent.

==Desktop, documents, and current selection==
StarDesktop and ThisComponent are OpenOffice.org Basic commands that refer to the application and currently active document respectively.

Unlike Microsoft Office, OpenOffice.org is one application with different components. When running some code it maybe useful to check which component is currently active. The above code demonstrates how that checking process can be done.

The Desktop that StarDesktop refers to is conceptual (historically it actually existed) and can be thought of as the OpenOffice.org application.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See [[ loadComponentFromUrl]].

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

Extensions development basic

2006-04-04T05:46:52Z

Iannz:

'''Getting started tutorial'''

This page provides a getting started guide for writing macros in OpenOffice.org Basic. It assumes some prior programming knowledge. Please edit this page to make it more readable. I hope you will find it useful in getting started.

=Where do I write the code?=
OpenOffice.org Basic code is stored in modules within libraries. A library can be:

*Shared (for a network install - OOo Macros & Dialogs)
*Just for the current user (My Macros & Dialogs)
*Within a document or template, so that its code is only available when that document is open.Within a document or template, so that its code is only available when that document is open.
Libraries not stored in a document or template (that is libraries that are shared or for the current user) are referred to as '''OpenOffice.org libraries'''.

To determine the actual folders that contain the OpenOffice.org libraries see: '''Tools > Options… > OpenOffice.org > Paths > BASIC'''.

{| border="1"
|'''Note'''
|Do not copy or move libraries using operating system commands. Use the macro organizer or package manager instead.
|-
|}

Modules within libraries have a maximum size of 64kb. A library can contain up to 16,000 modules.

For more information see online help for: Modules and Libraries.

=Accessing the IDE=
To access the IDE for the first time:

OpenOffice.org 1.1.x: '''Tools > Macros > Macro… >'''

OpenOffice.org 1.9.x and above: '''Tools > Macros > Organize macros > OpenOffice.org Basic… >'''

To get started we will use Module1 in the Standard library which is stored for the current user only:

Type a name for the new macro: '''HelloWorld'''

In the macro from listbox select '''Standard'''

Click '''New'''

You should now see something like:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
The cursor will be positioned at the start of the <tt>Sub HelloWorld</tt> line.

{| border="1"
|'''Note'''
|Now that while the IDE is running it can be accessed from the OpenOffice.org Window menu, or the task panel provided by the operating system.
|-
|}

=Entering the code=
Select and delete:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Below the line "Sub HelloWorld" type [[ msgbox]]<tt> "Hello World!"</tt>, so that the editor looks like:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|The IDE does not provide code completion or help with command syntax as you type, but to get help on a Basic command position the cursor in the command and press F1. OpenOffice.org Basic commands are not case sensitive. Thus msgbox, MSGBOX and Msgbox will all work. Strings are enclosed in double quotes.
|-
|}

=Running the code=
There are several ways of running the Basic code, these include:

Directly from the IDE. There is a run button on the macro bar (by default the third control on the second toolbar). This will run the first macro in the current module.

From the tools menu: (Version 1.1.x) '''Tools > Macros > Macro…'''; (Version 1.9.x and above) '''Tools > Macro > Run Macro…'''

Assigning the macro to a [[ key press]].

Assigning the macro to a [[ menu entry]].

Assigning the macro to a toolbar button.

Creating a [[ control in a document]].

Assigning the macro to an event.

For now try running the "HelloWorld" subroutine by clicking the '''Run''' button. A small dialog titled "soffice" with the text "Hello World!" and an OK button should be displayed.

=Saving the code=
The code gets automatically saved whenever the container for the code gets saved. Thus, if the code is in an OpenOffice.org library (shared or users) then it gets automatically saved when OpenOffice.org exits. If the code is in a library which is part of a document it gets saved whenever the document is saved.

On the Standard toolbar (by default the top toolbar) in the IDE there is a save button. If the code is in a document or template then clicking this button saves the entire document or template. If the code is in an OpenOffice.org library then just the current library gets saved.

=Variables=
It is possible to force variable declaration with <tt>Option Explicit</tt> at the top of the module. For a discussion on whether to declare variables or not see: [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 this discussion]].

In that discussion the initial author of this wiki thought that variables should always be declared. Since then he has changed to not declaring them. In short it is generally a personal preference. In either case, it is the initial authors preference that variables be named according to the following convention, which is used in the examples in this Wiki:

The first letter of the variable name indicates the type of value that the variable is going to hold, as per the following table (based on a table in Tutorial.pdf by Sun)

{| border="1"
|'''''Letter'''''
|'''''Meaning'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE or FALSE)
|-
|e
|Enumeration. This variable can only have one of a limited set of values.
|-
|f
|Float (3.402823 x 1038 to 1.401298 x 10-45. A single variable can take up to four bytes) Double (1.79769313486232 x 10308 to 4.94065645841247 x 10-324. A double variable can take up to eight bytes) Currency (-922337203685477.5808 to +922337203685477.5807 and takes up to eight bytes of memory)
|-
|m
|Array (aka sequence aka matrix)
|-
|n
|Integer (-32768 to 32767.) or Long (-2147483648 and 2147483647).
|-
|o
|Object, service, or interface
|-
|s
|String (A string variable can store up to 65535 Unicode characters).
|-
|x
|Interface, to indicate that only operations of a particular interface of an object are used
|-
|v
|Variant, Any
|-
|}

Use long descriptive variable names making use of camel case

{| border="1"
|'''Note:'''
|User defined OpenOffice.org Basic variables are not case sensitive. But UNO-API constants are case sensitive.
|-
|}

Convention exceptions to long descriptive names is for index variables where i, j, and k are commonly used, and for when a string is being built-up, where s is commonly used.

Edit sub HelloWorld so that it looks like the following and run it:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
msgbox "Hello World " & i
next
end sub
</code>
For more information on variables see: [[ using variables]].

=Understanding the OpenOffice.org API=
This section will start with an example. The remainder of this section aims to give information so that the example can be understood and expanded upon.

Try running the following code with different types of documents being active.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

==Subroutine naming convention==
In the above example the user defined function has a name that starts with the letters "fn". This is the initial authors convention so that people know that this is a user defined function. Similarly, the initial author uses the convention that user defined subroutines start with the letters "sub". When learning a language and an API it can be difficult to know what is built-in and what has been defined elsewhere. This document/wiki will use this convention for naming functions and subroutines.

==Introducing the OpenOffice.org API==
This section introduces the following terms:

* Interface
* Module
* Service
* Method
* Property

Understanding the difference between an interface and a service and what a module is, is not essential to being able to write extensions for OpenOffice.org, but it does help interpreting the documentation, and for introspection purposes. You may need to read this section at least twice.

An '''interface''' is a ''definition'' of a set of methods (and their arguments) that a service which implements that interface must have.

Interfaces are grouped together in '''modules''' for naming purposes. All interfaces (and services) start with the name "com.sun.star" then the name of the module then the name of the interface (or service).

For example most services provide the com.sun.star.beans.XPropertySet interface. This interface is stored in the module "beans" and provides access to the properties of a service. A '''property''' is a value where as a '''method''' is an action.

An OpenOffice.org object can have many services.

An OpenOffice.org object may have a service, which implements an interface, in which a method description says that another OpenOffice.org object is returned.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==X-Ray tool==
Using HasUnoInterfaces and supportsService gives information about an object at run time, but checking an object like this would be a nightmare for learning? Thankfully Bernard Marcelly has come to our rescue with the X-Ray tool. The X-Ray tool is available from: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Download the zip file, unzip the document, open the document in OpenOffice.org, follow the instructions for installation and set-up.

Part of the X-Ray tool set-up is to specify a local copy of the OpenOffice.org SDK. Download the OpenOffice.org SDK from and extract it.

In the above example, at the start of the code, there are two commented lines (comments start with an apostrophe):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Now that you have the X-Ray tool installed, uncomment these lines (remove the apostrophes) and rerun the macro. From version 5 of Xray the command simply becomes xray.

'''BasicLibraries''' is an OpenOffice.org Basic command that returns an object for accessing the OpenOffice.org libraries. The <tt>loadLibrary</tt> method ensures that the routines in that library are available for use.

<tt>xray.xray</tt> specifies the xray library and the xray subroutine within that library, thisComponent is the object that is being passed to xray for introspection.

To find the object that you want to work with often requires finding or creating it starting from either StarDesktop or thisComponent.

==Desktop, documents, and current selection==
StarDesktop and ThisComponent are OpenOffice.org Basic commands that refer to the application and currently active document respectively.

Unlike Microsoft Office, OpenOffice.org is one application with different components. When running some code it maybe useful to check which component is currently active. The above code demonstrates how that checking process can be done.

The Desktop that StarDesktop refers to is conceptual (historically it actually existed) and can be thought of as the OpenOffice.org application.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See [[ loadComponentFromUrl]].

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

Extensions development basic

2006-04-04T05:46:03Z

Iannz:

'''Getting started tutorial'''

This page provides agetting started guide for writing macros in OpnOffice.org Basic. It assumes some prior programming knowledge. Please edit this page to make it more readable. I hope you will find it useful in getting started.

=Where do I write the code?=
OpenOffice.org Basic code is stored in modules within libraries. A library can be:

*Shared (for a network install - OOo Macros & Dialogs)
*Just for the current user (My Macros & Dialogs)
*Within a document or template, so that its code is only available when that document is open.Within a document or template, so that its code is only available when that document is open.
Libraries not stored in a document or template (that is libraries that are shared or for the current user) are referred to as '''OpenOffice.org libraries'''.

To determine the actual folders that contain the OpenOffice.org libraries see: '''Tools > Options… > OpenOffice.org > Paths > BASIC'''.

{| border="1"
|'''Note'''
|Do not copy or move libraries using operating system commands. Use the macro organizer or package manager instead.
|-
|}

Modules within libraries have a maximum size of 64kb. A library can contain up to 16,000 modules.

For more information see online help for: Modules and Libraries.

=Accessing the IDE=
To access the IDE for the first time:

OpenOffice.org 1.1.x: '''Tools > Macros > Macro… >'''

OpenOffice.org 1.9.x and above: '''Tools > Macros > Organize macros > OpenOffice.org Basic… >'''

To get started we will use Module1 in the Standard library which is stored for the current user only:

Type a name for the new macro: '''HelloWorld'''

In the macro from listbox select '''Standard'''

Click '''New'''

You should now see something like:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
The cursor will be positioned at the start of the <tt>Sub HelloWorld</tt> line.

{| border="1"
|'''Note'''
|Now that while the IDE is running it can be accessed from the OpenOffice.org Window menu, or the task panel provided by the operating system.
|-
|}

=Entering the code=
Select and delete:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Below the line "Sub HelloWorld" type [[ msgbox]]<tt> "Hello World!"</tt>, so that the editor looks like:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|The IDE does not provide code completion or help with command syntax as you type, but to get help on a Basic command position the cursor in the command and press F1. OpenOffice.org Basic commands are not case sensitive. Thus msgbox, MSGBOX and Msgbox will all work. Strings are enclosed in double quotes.
|-
|}

=Running the code=
There are several ways of running the Basic code, these include:

Directly from the IDE. There is a run button on the macro bar (by default the third control on the second toolbar). This will run the first macro in the current module.

From the tools menu: (Version 1.1.x) '''Tools > Macros > Macro…'''; (Version 1.9.x and above) '''Tools > Macro > Run Macro…'''

Assigning the macro to a [[ key press]].

Assigning the macro to a [[ menu entry]].

Assigning the macro to a toolbar button.

Creating a [[ control in a document]].

Assigning the macro to an event.

For now try running the "HelloWorld" subroutine by clicking the '''Run''' button. A small dialog titled "soffice" with the text "Hello World!" and an OK button should be displayed.

=Saving the code=
The code gets automatically saved whenever the container for the code gets saved. Thus, if the code is in an OpenOffice.org library (shared or users) then it gets automatically saved when OpenOffice.org exits. If the code is in a library which is part of a document it gets saved whenever the document is saved.

On the Standard toolbar (by default the top toolbar) in the IDE there is a save button. If the code is in a document or template then clicking this button saves the entire document or template. If the code is in an OpenOffice.org library then just the current library gets saved.

=Variables=
It is possible to force variable declaration with <tt>Option Explicit</tt> at the top of the module. For a discussion on whether to declare variables or not see: [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 this discussion]].

In that discussion the initial author of this wiki thought that variables should always be declared. Since then he has changed to not declaring them. In short it is generally a personal preference. In either case, it is the initial authors preference that variables be named according to the following convention, which is used in the examples in this Wiki:

The first letter of the variable name indicates the type of value that the variable is going to hold, as per the following table (based on a table in Tutorial.pdf by Sun)

{| border="1"
|'''''Letter'''''
|'''''Meaning'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE or FALSE)
|-
|e
|Enumeration. This variable can only have one of a limited set of values.
|-
|f
|Float (3.402823 x 1038 to 1.401298 x 10-45. A single variable can take up to four bytes) Double (1.79769313486232 x 10308 to 4.94065645841247 x 10-324. A double variable can take up to eight bytes) Currency (-922337203685477.5808 to +922337203685477.5807 and takes up to eight bytes of memory)
|-
|m
|Array (aka sequence aka matrix)
|-
|n
|Integer (-32768 to 32767.) or Long (-2147483648 and 2147483647).
|-
|o
|Object, service, or interface
|-
|s
|String (A string variable can store up to 65535 Unicode characters).
|-
|x
|Interface, to indicate that only operations of a particular interface of an object are used
|-
|v
|Variant, Any
|-
|}

Use long descriptive variable names making use of camel case

{| border="1"
|'''Note:'''
|User defined OpenOffice.org Basic variables are not case sensitive. But UNO-API constants are case sensitive.
|-
|}

Convention exceptions to long descriptive names is for index variables where i, j, and k are commonly used, and for when a string is being built-up, where s is commonly used.

Edit sub HelloWorld so that it looks like the following and run it:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
msgbox "Hello World " & i
next
end sub
</code>
For more information on variables see: [[ using variables]].

=Understanding the OpenOffice.org API=
This section will start with an example. The remainder of this section aims to give information so that the example can be understood and expanded upon.

Try running the following code with different types of documents being active.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

==Subroutine naming convention==
In the above example the user defined function has a name that starts with the letters "fn". This is the initial authors convention so that people know that this is a user defined function. Similarly, the initial author uses the convention that user defined subroutines start with the letters "sub". When learning a language and an API it can be difficult to know what is built-in and what has been defined elsewhere. This document/wiki will use this convention for naming functions and subroutines.

==Introducing the OpenOffice.org API==
This section introduces the following terms:

* Interface
* Module
* Service
* Method
* Property

Understanding the difference between an interface and a service and what a module is, is not essential to being able to write extensions for OpenOffice.org, but it does help interpreting the documentation, and for introspection purposes. You may need to read this section at least twice.

An '''interface''' is a ''definition'' of a set of methods (and their arguments) that a service which implements that interface must have.

Interfaces are grouped together in '''modules''' for naming purposes. All interfaces (and services) start with the name "com.sun.star" then the name of the module then the name of the interface (or service).

For example most services provide the com.sun.star.beans.XPropertySet interface. This interface is stored in the module "beans" and provides access to the properties of a service. A '''property''' is a value where as a '''method''' is an action.

An OpenOffice.org object can have many services.

An OpenOffice.org object may have a service, which implements an interface, in which a method description says that another OpenOffice.org object is returned.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==X-Ray tool==
Using HasUnoInterfaces and supportsService gives information about an object at run time, but checking an object like this would be a nightmare for learning? Thankfully Bernard Marcelly has come to our rescue with the X-Ray tool. The X-Ray tool is available from: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Download the zip file, unzip the document, open the document in OpenOffice.org, follow the instructions for installation and set-up.

Part of the X-Ray tool set-up is to specify a local copy of the OpenOffice.org SDK. Download the OpenOffice.org SDK from and extract it.

In the above example, at the start of the code, there are two commented lines (comments start with an apostrophe):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Now that you have the X-Ray tool installed, uncomment these lines (remove the apostrophes) and rerun the macro. From version 5 of Xray the command simply becomes xray.

'''BasicLibraries''' is an OpenOffice.org Basic command that returns an object for accessing the OpenOffice.org libraries. The <tt>loadLibrary</tt> method ensures that the routines in that library are available for use.

<tt>xray.xray</tt> specifies the xray library and the xray subroutine within that library, thisComponent is the object that is being passed to xray for introspection.

To find the object that you want to work with often requires finding or creating it starting from either StarDesktop or thisComponent.

==Desktop, documents, and current selection==
StarDesktop and ThisComponent are OpenOffice.org Basic commands that refer to the application and currently active document respectively.

Unlike Microsoft Office, OpenOffice.org is one application with different components. When running some code it maybe useful to check which component is currently active. The above code demonstrates how that checking process can be done.

The Desktop that StarDesktop refers to is conceptual (historically it actually existed) and can be thought of as the OpenOffice.org application.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See [[ loadComponentFromUrl]].

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

Extensions development basic

2006-04-04T05:43:16Z

Iannz: /* Create new objects */

'''Getting started tutorial'''

Before we can access the OpenOffice.org Basic Integrated Development Environment (IDE), to write some code, a decision needs to be made about where the code is to be stored.

=Where do I write the code?=
OpenOffice.org Basic code is stored in modules within libraries. A library can be:

*Shared (for a network install - OOo Macros & Dialogs)
*Just for the current user (My Macros & Dialogs)
*Within a document or template, so that its code is only available when that document is open.Within a document or template, so that its code is only available when that document is open.
Libraries not stored in a document or template (that is libraries that are shared or for the current user) are referred to as '''OpenOffice.org libraries'''.

To determine the actual folders that contain the OpenOffice.org libraries see: '''Tools > Options… > OpenOffice.org > Paths > BASIC'''.

{| border="1"
|'''Note'''
|Do not copy or move libraries using operating system commands. Use the macro organizer or package manager instead.
|-
|}

Modules within libraries have a maximum size of 64kb. A library can contain up to 16,000 modules.

For more information see online help for: Modules and Libraries.

=Accessing the IDE=
To access the IDE for the first time:

OpenOffice.org 1.1.x: '''Tools > Macros > Macro… >'''

OpenOffice.org 1.9.x and above: '''Tools > Macros > Organize macros > OpenOffice.org Basic… >'''

To get started we will use Module1 in the Standard library which is stored for the current user only:

Type a name for the new macro: '''HelloWorld'''

In the macro from listbox select '''Standard'''

Click '''New'''

You should now see something like:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
The cursor will be positioned at the start of the <tt>Sub HelloWorld</tt> line.

{| border="1"
|'''Note'''
|Now that while the IDE is running it can be accessed from the OpenOffice.org Window menu, or the task panel provided by the operating system.
|-
|}

=Entering the code=
Select and delete:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Below the line "Sub HelloWorld" type [[ msgbox]]<tt> "Hello World!"</tt>, so that the editor looks like:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|The IDE does not provide code completion or help with command syntax as you type, but to get help on a Basic command position the cursor in the command and press F1. OpenOffice.org Basic commands are not case sensitive. Thus msgbox, MSGBOX and Msgbox will all work. Strings are enclosed in double quotes.
|-
|}

=Running the code=
There are several ways of running the Basic code, these include:

Directly from the IDE. There is a run button on the macro bar (by default the third control on the second toolbar). This will run the first macro in the current module.

From the tools menu: (Version 1.1.x) '''Tools > Macros > Macro…'''; (Version 1.9.x and above) '''Tools > Macro > Run Macro…'''

Assigning the macro to a [[ key press]].

Assigning the macro to a [[ menu entry]].

Assigning the macro to a toolbar button.

Creating a [[ control in a document]].

Assigning the macro to an event.

For now try running the "HelloWorld" subroutine by clicking the '''Run''' button. A small dialog titled "soffice" with the text "Hello World!" and an OK button should be displayed.

=Saving the code=
The code gets automatically saved whenever the container for the code gets saved. Thus, if the code is in an OpenOffice.org library (shared or users) then it gets automatically saved when OpenOffice.org exits. If the code is in a library which is part of a document it gets saved whenever the document is saved.

On the Standard toolbar (by default the top toolbar) in the IDE there is a save button. If the code is in a document or template then clicking this button saves the entire document or template. If the code is in an OpenOffice.org library then just the current library gets saved.

=Variables=
It is possible to force variable declaration with <tt>Option Explicit</tt> at the top of the module. For a discussion on whether to declare variables or not see: [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 this discussion]].

In that discussion the initial author of this wiki thought that variables should always be declared. Since then he has changed to not declaring them. In short it is generally a personal preference. In either case, it is the initial authors preference that variables be named according to the following convention, which is used in the examples in this Wiki:

The first letter of the variable name indicates the type of value that the variable is going to hold, as per the following table (based on a table in Tutorial.pdf by Sun)

{| border="1"
|'''''Letter'''''
|'''''Meaning'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE or FALSE)
|-
|e
|Enumeration. This variable can only have one of a limited set of values.
|-
|f
|Float (3.402823 x 1038 to 1.401298 x 10-45. A single variable can take up to four bytes) Double (1.79769313486232 x 10308 to 4.94065645841247 x 10-324. A double variable can take up to eight bytes) Currency (-922337203685477.5808 to +922337203685477.5807 and takes up to eight bytes of memory)
|-
|m
|Array (aka sequence aka matrix)
|-
|n
|Integer (-32768 to 32767.) or Long (-2147483648 and 2147483647).
|-
|o
|Object, service, or interface
|-
|s
|String (A string variable can store up to 65535 Unicode characters).
|-
|x
|Interface, to indicate that only operations of a particular interface of an object are used
|-
|v
|Variant, Any
|-
|}

Use long descriptive variable names making use of camel case

{| border="1"
|'''Note:'''
|User defined OpenOffice.org Basic variables are not case sensitive. But UNO-API constants are case sensitive.
|-
|}

Convention exceptions to long descriptive names is for index variables where i, j, and k are commonly used, and for when a string is being built-up, where s is commonly used.

Edit sub HelloWorld so that it looks like the following and run it:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
msgbox "Hello World " & i
next
end sub
</code>
For more information on variables see: [[ using variables]].

=Understanding the OpenOffice.org API=
This section will start with an example. The remainder of this section aims to give information so that the example can be understood and expanded upon.

Try running the following code with different types of documents being active.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

==Subroutine naming convention==
In the above example the user defined function has a name that starts with the letters "fn". This is the initial authors convention so that people know that this is a user defined function. Similarly, the initial author uses the convention that user defined subroutines start with the letters "sub". When learning a language and an API it can be difficult to know what is built-in and what has been defined elsewhere. This document/wiki will use this convention for naming functions and subroutines.

==Introducing the OpenOffice.org API==
This section introduces the following terms:

* Interface
* Module
* Service
* Method
* Property

Understanding the difference between an interface and a service and what a module is, is not essential to being able to write extensions for OpenOffice.org, but it does help interpreting the documentation, and for introspection purposes. You may need to read this section at least twice.

An '''interface''' is a ''definition'' of a set of methods (and their arguments) that a service which implements that interface must have.

Interfaces are grouped together in '''modules''' for naming purposes. All interfaces (and services) start with the name "com.sun.star" then the name of the module then the name of the interface (or service).

For example most services provide the com.sun.star.beans.XPropertySet interface. This interface is stored in the module "beans" and provides access to the properties of a service. A '''property''' is a value where as a '''method''' is an action.

An OpenOffice.org object can have many services.

An OpenOffice.org object may have a service, which implements an interface, in which a method description says that another OpenOffice.org object is returned.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==X-Ray tool==
Using HasUnoInterfaces and supportsService gives information about an object at run time, but checking an object like this would be a nightmare for learning? Thankfully Bernard Marcelly has come to our rescue with the X-Ray tool. The X-Ray tool is available from: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Download the zip file, unzip the document, open the document in OpenOffice.org, follow the instructions for installation and set-up.

Part of the X-Ray tool set-up is to specify a local copy of the OpenOffice.org SDK. Download the OpenOffice.org SDK from and extract it.

In the above example, at the start of the code, there are two commented lines (comments start with an apostrophe):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Now that you have the X-Ray tool installed, uncomment these lines (remove the apostrophes) and rerun the macro. From version 5 of Xray the command simply becomes xray.

'''BasicLibraries''' is an OpenOffice.org Basic command that returns an object for accessing the OpenOffice.org libraries. The <tt>loadLibrary</tt> method ensures that the routines in that library are available for use.

<tt>xray.xray</tt> specifies the xray library and the xray subroutine within that library, thisComponent is the object that is being passed to xray for introspection.

To find the object that you want to work with often requires finding or creating it starting from either StarDesktop or thisComponent.

==Desktop, documents, and current selection==
StarDesktop and ThisComponent are OpenOffice.org Basic commands that refer to the application and currently active document respectively.

Unlike Microsoft Office, OpenOffice.org is one application with different components. When running some code it maybe useful to check which component is currently active. The above code demonstrates how that checking process can be done.

The Desktop that StarDesktop refers to is conceptual (historically it actually existed) and can be thought of as the OpenOffice.org application.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See [[ loadComponentFromUrl]].

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>

Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>

This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command createUnoService. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
</code>

{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|}

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

Extensions development basic

2006-04-04T05:41:31Z

Iannz:

'''Getting started tutorial'''

Before we can access the OpenOffice.org Basic Integrated Development Environment (IDE), to write some code, a decision needs to be made about where the code is to be stored.

=Where do I write the code?=
OpenOffice.org Basic code is stored in modules within libraries. A library can be:

*Shared (for a network install - OOo Macros & Dialogs)
*Just for the current user (My Macros & Dialogs)
*Within a document or template, so that its code is only available when that document is open.Within a document or template, so that its code is only available when that document is open.
Libraries not stored in a document or template (that is libraries that are shared or for the current user) are referred to as '''OpenOffice.org libraries'''.

To determine the actual folders that contain the OpenOffice.org libraries see: '''Tools > Options… > OpenOffice.org > Paths > BASIC'''.

{| border="1"
|'''Note'''
|Do not copy or move libraries using operating system commands. Use the macro organizer or package manager instead.
|-
|}

Modules within libraries have a maximum size of 64kb. A library can contain up to 16,000 modules.

For more information see online help for: Modules and Libraries.

=Accessing the IDE=
To access the IDE for the first time:

OpenOffice.org 1.1.x: '''Tools > Macros > Macro… >'''

OpenOffice.org 1.9.x and above: '''Tools > Macros > Organize macros > OpenOffice.org Basic… >'''

To get started we will use Module1 in the Standard library which is stored for the current user only:

Type a name for the new macro: '''HelloWorld'''

In the macro from listbox select '''Standard'''

Click '''New'''

You should now see something like:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub

Sub HelloWorld

End Sub
</code>
The cursor will be positioned at the start of the <tt>Sub HelloWorld</tt> line.

{| border="1"
|'''Note'''
|Now that while the IDE is running it can be accessed from the OpenOffice.org Window menu, or the task panel provided by the operating system.
|-
|}

=Entering the code=
Select and delete:

<code>[oobas]
REM ***** BASIC *****

Sub Main

End Sub
</code>
Below the line "Sub HelloWorld" type [[ msgbox]]<tt> "Hello World!"</tt>, so that the editor looks like:

<code>[oobas]
Sub HelloWorld
msgbox "Hello World!"
End Sub
</code>
{| border="1"
|'''Notes:'''
|The IDE does not provide code completion or help with command syntax as you type, but to get help on a Basic command position the cursor in the command and press F1. OpenOffice.org Basic commands are not case sensitive. Thus msgbox, MSGBOX and Msgbox will all work. Strings are enclosed in double quotes.
|-
|}

=Running the code=
There are several ways of running the Basic code, these include:

Directly from the IDE. There is a run button on the macro bar (by default the third control on the second toolbar). This will run the first macro in the current module.

From the tools menu: (Version 1.1.x) '''Tools > Macros > Macro…'''; (Version 1.9.x and above) '''Tools > Macro > Run Macro…'''

Assigning the macro to a [[ key press]].

Assigning the macro to a [[ menu entry]].

Assigning the macro to a toolbar button.

Creating a [[ control in a document]].

Assigning the macro to an event.

For now try running the "HelloWorld" subroutine by clicking the '''Run''' button. A small dialog titled "soffice" with the text "Hello World!" and an OK button should be displayed.

=Saving the code=
The code gets automatically saved whenever the container for the code gets saved. Thus, if the code is in an OpenOffice.org library (shared or users) then it gets automatically saved when OpenOffice.org exits. If the code is in a library which is part of a document it gets saved whenever the document is saved.

On the Standard toolbar (by default the top toolbar) in the IDE there is a save button. If the code is in a document or template then clicking this button saves the entire document or template. If the code is in an OpenOffice.org library then just the current library gets saved.

=Variables=
It is possible to force variable declaration with <tt>Option Explicit</tt> at the top of the module. For a discussion on whether to declare variables or not see: [[http://www.oooforum.org/forum/viewtopic.phtml?t=5845 this discussion]].

In that discussion the initial author of this wiki thought that variables should always be declared. Since then he has changed to not declaring them. In short it is generally a personal preference. In either case, it is the initial authors preference that variables be named according to the following convention, which is used in the examples in this Wiki:

The first letter of the variable name indicates the type of value that the variable is going to hold, as per the following table (based on a table in Tutorial.pdf by Sun)

{| border="1"
|'''''Letter'''''
|'''''Meaning'''''
|-
|a
|Structure
|-
|b
|Boolean (TRUE or FALSE)
|-
|e
|Enumeration. This variable can only have one of a limited set of values.
|-
|f
|Float (3.402823 x 1038 to 1.401298 x 10-45. A single variable can take up to four bytes) Double (1.79769313486232 x 10308 to 4.94065645841247 x 10-324. A double variable can take up to eight bytes) Currency (-922337203685477.5808 to +922337203685477.5807 and takes up to eight bytes of memory)
|-
|m
|Array (aka sequence aka matrix)
|-
|n
|Integer (-32768 to 32767.) or Long (-2147483648 and 2147483647).
|-
|o
|Object, service, or interface
|-
|s
|String (A string variable can store up to 65535 Unicode characters).
|-
|x
|Interface, to indicate that only operations of a particular interface of an object are used
|-
|v
|Variant, Any
|-
|}

Use long descriptive variable names making use of camel case

{| border="1"
|'''Note:'''
|User defined OpenOffice.org Basic variables are not case sensitive. But UNO-API constants are case sensitive.
|-
|}

Convention exceptions to long descriptive names is for index variables where i, j, and k are commonly used, and for when a string is being built-up, where s is commonly used.

Edit sub HelloWorld so that it looks like the following and run it:

<code>[oobas]
sub HelloWorld
dim i as integer 'This line is optional
for i = 0 to 2
'These lines are indented for ease of reading only
msgbox "Hello World " & i
next
end sub
</code>
For more information on variables see: [[ using variables]].

=Understanding the OpenOffice.org API=
This section will start with an example. The remainder of this section aims to give information so that the example can be understood and expanded upon.

Try running the following code with different types of documents being active.

<code>[oobas]
sub main
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
msgbox fnWhichComponent(thisComponent)
end sub

function fnWhichComponent(oDoc) as string
if HasUnoInterfaces(oDoc, "com.sun.star.lang.XServiceInfo") then
if thisComponent.supportsService ("com.sun.star.text.GenericTextDocument") then
fnWhichComponent = "Text"
elseif thisComponent.supportsService("com.sun.star.sheet.SpreadsheetDocument") then
fnWhichComponent = "Spreadsheet"
elseif thisComponent.supportsService("com.sun.star.presentation.PresentationDocument") then
fnWhichComponent = "Presentation"
elseif thisComponent.supportsService("com.sun.star.drawing.GenericDrawingDocument") then
fnWhichComponent = "Drawing"
else
fnWhichComponent = "Oops current document something else"
end if
else
fnWhichComponent = "Not a document"
end if
End function
</code>

==Subroutine naming convention==
In the above example the user defined function has a name that starts with the letters "fn". This is the initial authors convention so that people know that this is a user defined function. Similarly, the initial author uses the convention that user defined subroutines start with the letters "sub". When learning a language and an API it can be difficult to know what is built-in and what has been defined elsewhere. This document/wiki will use this convention for naming functions and subroutines.

==Introducing the OpenOffice.org API==
This section introduces the following terms:

* Interface
* Module
* Service
* Method
* Property

Understanding the difference between an interface and a service and what a module is, is not essential to being able to write extensions for OpenOffice.org, but it does help interpreting the documentation, and for introspection purposes. You may need to read this section at least twice.

An '''interface''' is a ''definition'' of a set of methods (and their arguments) that a service which implements that interface must have.

Interfaces are grouped together in '''modules''' for naming purposes. All interfaces (and services) start with the name "com.sun.star" then the name of the module then the name of the interface (or service).

For example most services provide the com.sun.star.beans.XPropertySet interface. This interface is stored in the module "beans" and provides access to the properties of a service. A '''property''' is a value where as a '''method''' is an action.

An OpenOffice.org object can have many services.

An OpenOffice.org object may have a service, which implements an interface, in which a method description says that another OpenOffice.org object is returned.

==Introspection==
HasUnoInterfaces is an OpenOffice.org Basic function for introspection. See this [[http://www.oooforum.org/forum/viewtopic.phtml?t=7068 link]] for information on introspection in other languages.

HasUnoInterfaces returns true if all of the specified interfaces are available for the specified object.

Most OpenOffice.org objects provide the method supportsService because they have the interface com.sun.star.lang.XServiceInfo.

In the above example, the OpenOffice.org Basic command, '''HasUnoInterfaces''' checks that the current document has the interface com.sun.star.lang.XServiceInfo, because if it doesn't have that interface then it doesn't have the method supportsService, and a run time error would occur if such an object tried to access its nonexistent method.

'''SupportsService''' is a method which returns true if the specified service is available. The above examples checks for a service to determine the type of document that is currently active.

==X-Ray tool==
Using HasUnoInterfaces and supportsService gives information about an object at run time, but checking an object like this would be a nightmare for learning? Thankfully Bernard Marcelly has come to our rescue with the X-Ray tool. The X-Ray tool is available from: [[http://ooomacros.org/dev.php#101416 ooomacros]]. Download the zip file, unzip the document, open the document in OpenOffice.org, follow the instructions for installation and set-up.

Part of the X-Ray tool set-up is to specify a local copy of the OpenOffice.org SDK. Download the OpenOffice.org SDK from and extract it.

In the above example, at the start of the code, there are two commented lines (comments start with an apostrophe):

<code>[oobas]
'basicLibraries.loadLibrary("Xray")
'xray.xray thisComponent
</code>
Now that you have the X-Ray tool installed, uncomment these lines (remove the apostrophes) and rerun the macro. From version 5 of Xray the command simply becomes xray.

'''BasicLibraries''' is an OpenOffice.org Basic command that returns an object for accessing the OpenOffice.org libraries. The <tt>loadLibrary</tt> method ensures that the routines in that library are available for use.

<tt>xray.xray</tt> specifies the xray library and the xray subroutine within that library, thisComponent is the object that is being passed to xray for introspection.

To find the object that you want to work with often requires finding or creating it starting from either StarDesktop or thisComponent.

==Desktop, documents, and current selection==
StarDesktop and ThisComponent are OpenOffice.org Basic commands that refer to the application and currently active document respectively.

Unlike Microsoft Office, OpenOffice.org is one application with different components. When running some code it maybe useful to check which component is currently active. The above code demonstrates how that checking process can be done.

The Desktop that StarDesktop refers to is conceptual (historically it actually existed) and can be thought of as the OpenOffice.org application.

==Creating new documents==
To create a new text document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Array())
</code>
To create a new spreadsheet document:

<code>[oobas]
oDoc = StarDesktop.loadComponentFromURL("private:factory/scalc", "_blank", 0, Array())
</code>
An easier approach would be to write a simple function:

<code>[oobas]
function fnNewDoc(sDocType as string)
fnNewDoc = StarDesktop.loadComponentFromURL("private:factory/" & sDocType , "_blank", 0, Array())
end function
</code>
Then creating new documents can be achieved with:

<code>[oobas]
oDoc = fnNewDoc("swriter")
oDoc = fnNewDoc("scalc")
oDoc = fnNewDoc("simpress")
oDoc = fnNewDoc("sdraw")
oDoc = fnNewDoc("smath")
</code>
See [[ loadComponentFromUrl]].

==To open a document==
The following example shows how to open a file. For information on URLs in OpenOffice.org see [[ URL Basics]].

<code>[oobas]
sFile = "C:\Documents and Settings\danny\Desktop\MyCalc.sxc" ' Windows
sFile = "/home/danny/Desktop/MyCalc.sxc" ' Linux
sURL = ConvertToURL(sFile)
oDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
</code>
Again it may make sense to make this easier by writing a simple function:

<code>[oobas]
function fnOpenDoc(sFile)
sURL = ConvertToURL(sFile)
fnOpenDoc = StarDesktop.loadComponentFromURL(sURL, "_blank", 0, Array())
end function
</code>
Examples of calling the function:

<code>[oobas]
oDoc = fnOpenDoc("C:\Documents and Settings\danny\Desktop\MyCalc.sxc") ' Windows
oDoc = fnOpenDoc("/home/danny/Desktop/MyCalc.sxc") ' Linux
</code>

==Current Selection==
It is common to want to run some code that effects the current selection. <tt>ThisComponent</tt> has the method <tt>getCurrentSelection</tt>. Since many different types of objects could possibly be selected it is common to check that the currently selected object has the service that contains the method that we want to apply to the object.

Edit the main subroutine to the following and rerun it on a text document with different selections. (To select more than one block of text hold down the control key).

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
'xray.xray oCurSelection
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
msgbox "There are " & oCurSelection.getCount() & _
" selections in the current text document."
end if
end if
end sub
</code>
With nothing selected the number of selections is one - the insertion point, with one block of text selected the count is still one, but with two blocks of text the count is three - the insertion point and the two blocks of selected text.

Exercise 1: Modify the above code so that it works on selected cell ranges in a spreadsheet.

Question1: For two blocks of cells selected, what would be the count for the number of selections?

==Properties==
Uncomment <tt>'xray.xray oCurSelection</tt> so that xray runs, to see that the object that <tt>oCurSelection</tt> points to has a "property" called <tt>Count</tt> with a description of "pseudo-prop, read only". It is possible in OpenOffice.org Basic to write <tt>oCurSelection.count</tt>, but as this is not possible in all other languages accessing the OpenOffice.org API, this Wiki will try to always use the method approach. (I say try because I have not been in the habit of doing this and sometimes I may forget).

This next example demonstrates changing a property value for the current selections.

<code>[oobas]
sub main
basicLibraries.loadLibrary("Xray")
if fnWhichComponent(thisComponent) = "Text" then
oCurSelection = thisComponent.getCurrentSelection()
if oCurSelection.supportsService("com.sun.star.text.TextRanges") then
nCount = oCurSelection.Count
'xray.xray oCurSelection.getByIndex(0)
'Warning: The insertion point will have the same action applied twice
'in this case it doesn't matter, but in others it might.
for i = 0 to nCount - 1
oCurSelection.getByIndex(i).setPropertyValue("CharStyleName", "Strong Emphasis")
next
end if
end if
end sub
</code>
In OpenOffice.org Basic it is possible to shorten the assignment line to:

<code>[oobas]
oCurSelection(i).CharStyleName = "Strong Emphasis"
</code>
This wiki will try to use the full methods for both indexing and assigning properties. The rationale is that this makes converting the code to other languages easier and also helps the learner to understand what is happening (again I have not been in the habit of doing this so some examples may slip past me).

Exercise 2: Rewrite the above code so that the warning can be removed.

See [[ Current selection]].

=Iterative Access to Subordinate Objects (Enumeration access)=
Sometimes to access the desired object an enumeration is required. For example paragraphs, within a document or within a selection.

When a Writer document is active and some text is selected, both <tt>thisDocument.getText()</tt> and <tt>thisComponent.getCurrentSelection().getByIndex(i)</tt> have the service: com.sun.star.text.TextRange which has the interface: com.sun.star.container.XContentEnumerationAccess, it is possible to create an enumeration of the paragraphs for the current document or for a particular selection.

<code>[oobas]
' Create enumeration object
oTextElementEnum = thisComponent.getText().createEnumeration()
'or thisComponent.getCurrentSelection().getByIndex(i).createEnumeration()

' loop over all text elements
while oTextElementEnum.hasMoreElements()
oTextElement = oTextElementEnum.nextElement
if oTextElement.supportsService("com.sun.star.text.TextTable") then
MsgBox "The current block contains a table."
end if
if oTextElement.supportsService("com.sun.star.text.Paragraph") then
MsgBox "The current block contains a paragraph."
end if
wend
</code>
Exercise 3: Extend the above example to display in a message box all text portions that are bold.

=Named access=
Some objects provide named access to a particular type of subordinate object, some others indexed access, and some both named and indexed access.

For example if the current document in OpenOffice.org is a spreadsheet then to access a particular sheet can be done by index access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByIndex(0)
</code>
or named access:

<code>[oobas]
oSheet = thisComponent.getSheets.getByName("Sheet1")
</code>
To check if an object with a particular name already exists use <tt>hasByName</tt>, for example:

<code>[oobas]
if thisComponent.getSheets.hasByName("Sheet1") then
</code>
To loop through all the available object names can be done like:

<code>[oobas]
mNames = thisComponent.getSheets.getElementnames
for i = lbound(mNames) to ubound(mNames)
msgbox mNames(i)
next
</code>

Some named subordinate objects also provide the interface: com.sun.star.container.XNameContainer. This interface defines that such objects should have the following methods: <tt>insertByName</tt>, <tt>replaceByname</tt> and <tt>removeByName</tt>.

E.g.

<code>[oobas]
thisComponent.getSheets.insertByName("NewSheet")
</code>

=Create new objects=
Some objects have services which implement interfaces to provide specific methods for creating a particular type of object.

For example if the current document is a Writer document then <tt>thisComponent.getText</tt> is an object that provides the service com.sun.star.text.Text which implements the interface com.sun.star.text.XSimpleText which defines the methods <tt>createTextCursor</tt> and <tt>createTextCursorByRange</tt>. Both of these methods create a text cursor for accessing the text of the document. These cursors are quite independent of the view cursor . The view cursor is visible on the screen and is manipulated by the user (and can be manipulated by program control), where as a text cursor is not visible on the screen and is solely used by program control. The following code snippet demonstrates creating a new text cursor, such that it starts at the same location as the viewCursor and is then moved independent of the view cursor.

<code>[oobas]
oVC = thisComponent.getCurrentController.getViewCursor
oCursor = oVC.getText.createTextCursorByRange(oVC)
oCursor.gotoStartOfSentence(false)
oCursor.gotoEndOfSentence(true)
msgbox oCursor.getString
</code>
Some objects are context dependent and get created using the method <tt>createInstance</tt> which is defined in the interface com.sun.star.lang.XMultiServiceFactory. For example to add a rectangle to the first page of a drawing document:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
dim aSize as new com.sun.star.awt.Size

aPoint.x = 1000
aPoint.y = 1000

aSize.Width = 10000
aSize.Height = 10000

oRectangleShape = thisComponent.createInstance("com.sun.star.drawing.RectangleShape")
oRectangleShape.Size = aSize
oRectangleShape.Position = aPoint

thisComponent.getDrawPages.getByIndex(0).add(oRectangleShape)
</code>
This example also uses UNO structs see below for more information on UNO stucts.

Some objects are context independent to create these objects use the OpenOffice.org Basic command [[ createUnoService]]. For example to create the equivalent to StarDesktop:

<code>[oobas]
oDesktop = createUnoService("com.sun.star.frame.Desktop")
</code>

The process that I use to determine how to access or create an object is as follows:

Does the object already exist if so I should be able to access it from something like <tt>thisComponent</tt>.

Will the new object belong to another object, if so does the owner have a specific method for creating the object, if so use it.

The new object will belong to another object, but that object doesn't provide a specific method for creating it, but does provide <tt>createInstance</tt>. If the object doesn't provide <tt>createInstance</tt> are you sure you are using the correct object, or is it context independent.

I have found working out how to create an object to be quite difficult with existing documentation so I hope that this document/wiki will eventually make this clear.

==UNO structs==
UNO structures can be declared using the OpenOffice.org Basic command <tt>dim</tt>:

<code>[oobas]
dim aPoint as new com.sun.star.awt.Point
</code>
Or by using the OpenOffice.org Basic command <tt>createUnoStruct</tt>:

<code>[oobas]
aPoint = createUnoStruct("com.sun.star.awt.Point")
{| border="1"
|'''Note:'''
|When declaring UNO structs case is important. Note that everything upto the name of the struct is lowercase, and that the name of the struct is in TitleCase.
|-
|}
</code>

==Creating Listeners and Handlers==
Through the user interface it is possible to assign macros to some events:

OpenOffice.org versions 1.1.x: '''Tools > Configure… > Events'''.

OpenOffice.org versions 1.9.x and above: '''Tools > Customize… > Events'''.

It is also possible to assign macros to a wider range of events using the OpenOffice.org Basic command CreateUnoListener. This same command is used for creating both listeners and handlers. A listener checks for an event and always allows other listeners to respond to the event as well. A handler listens for an event, and can optionally consume the event so that other listeners don't get to act on it.

The following example creates a keyHandler:

<code>[oobas]
global IannzExampleKeyHandler

sub SetupKeyHandler
oController = thisComponent.currentController
IannzExampleKeyHandler = CreateUnoListener("KeyHandler_","com.sun.star.awt.XKeyHandler")
oController.addKeyHandler(IannzExampleKeyHandler) ' Register the listener
end sub

sub RemoveKeyHandler
thisComponent.currentController.removeKeyHandler(IannzExampleKeyHandler)
end sub

sub KeyHandler_disposing
end sub

function KeyHandler_keyReleased(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyReleased = False
end function

function KeyHandler_keyPressed(oKeyEvent as new com.sun.star.awt.KeyHandler) as boolean
KeyHandler_keyPressed = false 'Let other listeners handle the event
if oKeyEvent.modifiers = com.sun.star.awt.KeyModifier.MOD2 then 'Control key was pressed
if oKeyEvent.keyCode = com.sun.star.awt.Key.Q then
msgbox "Alt + Q was pressed"
KeyHandler_keyPressed = true 'Don't let other listeners process this event
end if
end if
end function
</code>
A variable declared as global keeps its value even after the macro exits. In this case we want to be able to use this variable later to remove the handler. As variables declared globally could be used in other libraries to try and avoid conflict I start all my global variables with Iannz my registered name for the OpenOffice.org web site.

<tt>sub SetupKeyHandler</tt> sets up the handler. The first parameter to CreateUnoListener is the staring name for the methods that will be called when that type of event occurs in this example .<tt>"KeyHandler_"</tt>.

The second parameter is the name of the interface for the listener or handler, "com.sun.star.awt.XKeyHandler". The name is case sensitive, everything up to and including the module name is always lowercase, the name of the interface always starts with "X" and the remainder is in TitleCase.

Use the SDK to find out what methods the interface must supply. You must supply routines for all of these methods even if you don't intend to use them. You also need to supply a disposing method. The names of these routines start with the string given in the first parameter to CreateUnoListener , in this example <tt>"KeyHandler_"</tt>.

Thus in the example there is <tt>KeyHandler_disposing</tt> and <tt>KeyHandler_keyReleased</tt> which don't actually do anything but are required, and <tt>KeyHandler_keyPressed</tt> which actually does the job.

<tt>sub RemoveKeyHandler</tt> demonstrates how to remove the handler.

=OpenOffice.org constants=
The above example uses OpenOffice.org constants.

E.g. com.sun.star.awt.KeyModifier.MOD2

OpenOffice.org constants are case sensitive. Everything up to and including the module name is always lowercase. The constant group is in TitleCase. The actual constant name is always UPPERCASE.

Programmers not using OpenOffice.org Basic may not have access to these constants.

=Using the recorder=
See [[ The OpenOffice.org recorder and UNO dispatch calls]] section for a discussion on recording UNO Dispatch commands versus writing API calls.

Extensions development

2006-04-04T04:29:08Z

Iannz: /* Starting in a language */

{{Extensions}}
Developing extensions is an efficient way to bring value to OpenOffice.org without diving into core sources. Obviously all developers willing to [[Main_Page|develop at OpenOffice.org sources level]] are welcomed.

OpenOffice.org enables third party tools creation through UNO bridges, allowing using many languages.

The principle is to create UNO packages that can be listed in the OpenOffice.org [[Extensions_repository|Extensions repository]] and installed by end-users easily.

This section wants to give newcomers as well as experienced developers some hints to develop Extensions in their desired languages and provide them with tools and frameworks that ease and homogenize the development.

Finally, popular Extensions may be integrated into OpenOffice.org so it is important to follow common policies from beginning to ease this merging.

==== Starting in a language ====
Addons can be written in various languages. Each section is here to give starting informations that let you create your addons. Each section is dedicated to a language. It deals with specific points concerning the Extensions aspect. Resources regarding the OpenOffice.org API can be found on the [http://api.openoffice.org API project] and UNO bridges languages issues on the [http://udk.openoffice.org UDK project]

The translations of these pages are welcomed and [[Extensions#Translating_these_pages|guidelines are available]].

* [[Extensions_development_python|Starting in Python]]
* [[Extensions_development_basic|Starting in Basic]]
* [[Extensions_development_java|Starting in Java]]
* Starting in C++
* Non programmatic Extensions
* Extensions packaging

==== Tools & Frameworks ====

* [[Extensions_development_translation|Translation framework]]
* Extension Packager
* Predefined wizards
* Introspection Tools : discover the API

[[Category:Extensions]]

User:Iannz

2005-11-17T21:10:14Z

Iannz:

Test

MediaWiki Configuration

2005-11-16T21:46:35Z

Iannz: /* CodeSyntaxHighlight MediaWiki Extension */

This pages have been automatically generated by twiki2mediawiki. Please
review all of them, as there will be broken markup and broken links.

Please review your page and move the link from the "Converted Pages" to "Reviewed Pages". To move your page to a new name you have to login. If you would like to see a page removed add a link to the [[Twiki2mediawiki_TODO_list#remove.28d.29|remove(d)]] section.

== Reviewed Pages ==

=== ok ===

* [[OOo Ergonomics]] (from [[Main_OOoAnnoyances]])
* [[OpenDocument]]
* [[OpenOffice]]
* [[Main_IRCCommunication]]
* [[Main_OOoJava]]
* [[OOoRelease201]]
* [[ProductRelease]]
* [[Main_OOoRelease200]]
* [[Writing_warning-free_code]] (from [[Main_WarningFree]])

SVG* got re-worked by Haui
* [[Main_SVGGroupOpacity]]
* [[Main_SVGEllipticArcs]]
* [[Main_SVGImportFilter]]
* [[Main_SVGSupportedFeatures]]
* [[Main_SVGUnsupportedFeatures]]
* [[Main_SVGFilterSourceCode]]
* [[Main_SVGUserExperiences]]
* [[Main_SVGPathSemantics]]
* [[Main_SVGHEAD]]
* [[Main_SVGImportTodo]]
* [[Main_SVGCoordinateSystems]]

=== remove(d) ===

Please add a link to pages you would like to see removed here.

* [[_default_WebLeftBar]]
* [[_default_WebRss]]
* [[Main_CaioTiago]]
* [[Main_OOo]]
* [[Main_EikeRathke]]
* [[Main_IanNz]]
* [[Main_JacquelineMcNally]]
* [[Main_LondonOffice]]
* [[Main_OfficeLocations]]
* [[Main_SanJoseOffice]]
* [[Main_StefanTaxhet]]
* [[Main_TokyoOffice]]
* [[Main_MichaelMeeks]]
* [[Sandbox_MyPlayGround]]
* [[Sandbox_StefanTaxhetSandbox]]
* [[Sandbox_WebLeftBar]]
* [[Sandbox_WebRss]]
* [[Main_WebRss]]
* [[Main_TestTest]]
* [[Main_StefanTaxhetAdmin]]
* [[Sandbox_SurveyServicesOpenOfficeOrg]]
* [[Main_TOCStyleInclude]]
* [[Main_CodeStyleInclude]]
* [[Main_DianeMackay]]
* [[Main_StephanBergmann]]

These pages are of dubious usefulness, completeness & relevance and should prolly be removed:
* [[WebOOoBanners]]
* [[OOoES]]

== Converted Pages - pending re-work ==

It's good if you rename these pages as they are re-worked to remove the 'Main_' suffix - use the 'move' tab to do that.

* [[DomainDeveloper]]
* [[Main_SurveyServicesOpenOfficeOrg]]
* [[Main_MacOSXBuildInstructions]]
* [[Main_ReleaseMilestone]]
* [[Main_ReleaseCodeline]]
* [[Main_TargetMilestone]]

== Personal Pages ==

It's probable that we don't want / require personal pages in the wiki. Hence this lot can be axed in a week or two if no-one screams, many of them contain broken Twiki junk.
To help us with this process, it'd be great if you could remove the content from your page & move your name into the relevant 'remove(d)' section above to join the other alumnii there.

* [[Main_AlanKatzman]]
* [[Main_AlexandroColorado]]
* [[Main_AlexBrooks]]
* [[Main_AndreSchnabel]]
* [[Main_AndrewBrown]]
* [[Main_BadBoy]]
* [[Main_BerndSeidler]]
* [[Main_BernhardHaumacher]]
* [[Main_CharlesSchulz]]
* [[Main_ChrisReid]]
* [[Main_ChristophNeumann]]
* [[Main_CorNouws]]
* [[Main_CraigAdams]]
* [[Main_CristianDriga]]
* [[Main_CyrilJacquenot]]
* [[Main_CyrilRIP]]
* [[Main_DavidFraser]]
* [[Main_DeepankarDatta]]
* [[Main_DonaldGillies]]
* [[Main_DrewCrosland]]
* [[Main_EricBachard]]
* [[Main_EricHoch]]
* [[Main_ErnestoWalker]]
* [[Main_FlorianHeckl]]
* [[Main_FrankSchoenheit]]
* [[Main_FriedrichStrohmaier]]
* [[Main_GorkemCetin]]
* [[Main_GrSingleton]]
* [[Main_HelenePetit]]
* [[Main_JacquesRoux]]
* [[Main_JimWatson]]
* [[Main_JiriReznicek]]
* [[Main_JohannesSwoboda]]
* [[Main_JoostAndrae]]
* [[Main_JuergenSchmidt]]
* [[Main_KazunariHirano]]
* [[Main_KoheiYoshida]]
* [[Main_LaptopPerKidLetter]]
* [[Main_LouisSuarez]]
* [[Main_LuisCabreraSauco]]
* [[Main_MaartenBrouwers]]
* [[Main_MarcMaki]]
* [[Main_MarkoMoeller]]
* [[Main_MarkusHibbetts]]
* [[Main_MartinTaylor]]
* [[Main_MikeStockman]]
* [[Main_OpenTiss]]
* [[Main_PaoloMantovani]]
* [[Main_PatrickBall]]
* [[Main_PaulWujek]]
* [[Main_PavelJanik]]
* [[Main_PeteBedingfield]]
* [[Main_PeterEberlein]]
* [[Main_PeterThoeny]]
* [[Main_RalfSchellenberger]]
* [[Main_ReneAuberger]]
* [[Main_RobertRees]]
* [[Main_RolfMeyer]]
* [[Main_ScottCarr]]
* [[Main_SeoCoolhuoquoz]]
* [[Main_SettanttaOo]]
* [[Main_StephanBergmann]]
* [[Main_SuperBiskit]]
* [[Main_SvanteSchubert]]
* [[Main_Syndication]]
* [[Main_TheTschaena]]
* [[Main_VincentPatrick]]
* [[Sandbox_AndrewBrownSandbox]]
* [[Sandbox_BernhardHaumacherSandbox]]
* [[Sandbox_CristianDrigaSandbox]]
* [[Sandbox_ScottCarrSandbox]]

== Managing Rights ==

* sysop via db 
http://meta.wikimedia.org/wiki/Setting_user_rights_in_MediaWiki#Granting_rights_to_users

* [http://meta.wikimedia.org/wiki/User_rights User Rights]

It seems neccessary to require users to login to edit. 
This avoids defacement and makes authors feel more responsible for
the content.

Special Pages to take care of:
* Special:Userrights
* OOoWiki:Administrators

== Help Content (done) ==

Help:Contents with links to 
http://meta.wikimedia.org/wiki/MediaWiki_FAQ 
http://meta.wikimedia.org/wiki/MediaWiki_User%27s_Guide

Help:Editing with links to 
http://meta.wikimedia.org/wiki/Help:Editing 
http://meta.wikimedia.org/wiki/Help:Contents#For_editors

== Copyrights (done) ==

[[Project:Copyrights]]

== Navigation Box (done) ==

See http://meta.wikimedia.org/wiki/MediaWiki_FAQ#In_version_1.5
 
[[MediaWiki:Sidebar]]

== InterWiki Links ==

http://meta.wikimedia.org/wiki/Help:Guide_for_system_administrators_for_setting_up_interwiki_linking#add_your_own_custom

[[User:Haui]] configured issue InterWiki links for TWiki. That would be handy here too.

== Custom Namespaces ==

http://meta.wikimedia.org/wiki/Help:Custom_namespaces

== Cleanup Test Installations ==

mediawiki2, mediawiki, backups of httpd.conf, ... can be purged.

We might want to keep one playground though.

== CodeSyntaxHighlight MediaWiki Extension ==
Code Syntax highlighting using GeShi
http://qbnz.com/highlighter/
Has been added as per
http://mercury.it.swin.edu.au/swinbrain/index.php/CodeSyntaxHighlight_MediaWiki_Extension
 

Haven't updated help page yet.

The default color codes for Geishi could be improved.

I have changed the colors for oobas, but am not sure what colors to assign for C. I haven't managed to mimick the BASIC IDE as I don't understand why keywords like "for" are blue but "msgbox" is green.

For those that have access to the server the files are in:
ooodata/www/mwiki/extensions/CodeSyntaxHighlight/geshi
and look like (initial comments removed):
<code>[php]
$language_data = array (
'LANG_NAME' => 'C',
'COMMENT_SINGLE' => array(1 => '//', 2 => '#'),
'COMMENT_MULTI' => array('/*' => '*/'),
'CASE_KEYWORDS' => GESHI_CAPS_NO_CHANGE,
'QUOTEMARKS' => array("'", '"'),
'ESCAPE_CHAR' => '\\',
'KEYWORDS' => array(
1 => array(
'if', 'return', 'while', 'case', 'continue', 'default',
'do', 'else', 'for', 'switch', 'goto'
),
2 => array(
'null', 'false', 'break', 'true', 'function', 'enum', 'extern', 'inline'
),
3 => array(
'printf', 'cout'
),
4 => array(
'auto', 'char', 'const', 'double', 'float', 'int', 'long',
'register', 'short', 'signed', 'sizeof', 'static', 'string', 'struct',
'typedef', 'union', 'unsigned', 'void', 'volatile', 'wchar_t'
),
),
'SYMBOLS' => array(
'(', ')', '{', '}', '[', ']', '=', '+', '-', '*', '/', '!', '%', '^', '&', ':'
),
'CASE_SENSITIVE' => array(
GESHI_COMMENTS => true,
1 => false,
2 => false,
3 => false,
4 => false,
),
'STYLES' => array(
'KEYWORDS' => array(
1 => 'color: #b1b100;',
2 => 'color: #000000; font-weight: bold;',
3 => 'color: #000066;',
4 => 'color: #993333;'
),
'COMMENTS' => array(
1 => 'color: #808080; font-style: italic;',
2 => 'color: #339933;',
'MULTI' => 'color: #808080; font-style: italic;'
),
'ESCAPE_CHAR' => array(
0 => 'color: #000099; font-weight: bold;'
),
'BRACKETS' => array(
0 => 'color: #66cc66;'
),
'STRINGS' => array(
0 => 'color: #ff0000;'
),
'NUMBERS' => array(
0 => 'color: #cc66cc;'
),
'METHODS' => array(
1 => 'color: #202020;',
2 => 'color: #202020;'
),
'SYMBOLS' => array(
0 => 'color: #66cc66;'
),
'REGEXPS' => array(
),
'SCRIPT' => array(
)
),
'URLS' => array(
1 => '',
2 => '',
3 => 'http://www.opengroup.org/onlinepubs/009695399/functions/{FNAME}.html',
4 => ''
),
'OOLANG' => true,
'OBJECT_SPLITTERS' => array(
1 => '.',
2 => '::'
),
'REGEXPS' => array(
),
'STRICT_MODE_APPLIES' => GESHI_NEVER,
'SCRIPT_DELIMITERS' => array(
),
'HIGHLIGHT_STRICT_BLOCK' => array(
)
);
</code>

I found this link useful for working out color codes:
http://www.htmlgoodies.com/tutorials/colors/article.php/3478961

[[User:Iannz]]

HSQLDB:Tips and Tricks

2005-11-16T21:29:23Z

Iannz: /* How to know the version of the embedded HSQLDB? */

= How to connect to a "normal" (not embedded) HSQL database? =
TODO

= How to migrate data between embedded and non-embedded HSQLDB? =
TODO

= How to know the version of the embedded HSQLDB? =
You can determine the version of the embedded HSQLDB engine with the following Basic macro
<code>[oobas]
Option Explicit

Sub hsqlVersion
Dim databaseURLOrRegisteredName As String
databaseURLOrRegisteredName = "hsqldb"
' adjust this string to your needs. It needs to be the name of a registered database,
' or a complete URL

Dim databaseContext As Object
databaseContext = createUnoService( "com.sun.star.sdb.DatabaseContext" )

Dim databaseDocument As Object
databaseDocument = databaseContext.getByName( databaseURLOrRegisteredName )

Dim connection As Object
connection = databaseDocument.getConnection( "", "" )

MsgBox "product version: " & connection.getMetaData().getDatabaseProductVersion()

connection.close
End Sub
</code>
Note that this will give you a version number such as "1.8.0", but ''not'' "1.8.0.1". To my best knowledge, this last digit in the HSQLDB version cannot be obtained by any means at runtime.

MediaWiki Configuration

2005-11-16T01:20:17Z

Iannz: