2.

Getting Started
In OpenOffice.org (OOo), macros and dialogs are stored in documents and libraries. The included integrated
development environment (IDE) is used to create and debug macros and dialogs. This chapter introduces the
basic concepts of starting the IDE and creating macros by showing the steps to produce a simple macro,
which displays the text “Hello World” on the screen.
A macro is a saved sequence of commands or keystrokes stored for later use. An example of a simple macro
is one that “types” your address. Macros support commands that allow a variety of advanced functions, such
as making decisions (for example, if the balance is less than zero, color it red; if not, color it black), looping
(while the balance is greater than zero, subtract 10), and even interacting with a person (asking the user for a
number). Some of these commands are based on the BASIC programming language. (BASIC is an acronym
for Beginner’s All-purpose Symbolic Instruction Code.) It is common to assign a macro to a keystroke or
toolbar icon so that it can be quickly started.
A dialog – or dialog box – is a type of window used to have a “dialog” with a user. The dialog may present
information to the user, or obtain input from the user. You can create your own dialogs and store them in a
module with your macros.
The OpenOffice.org macro language is very flexible, allowing automation of both simple and complex tasks.
Although writing macros and learning about the inner workings of OpenOffice.org can be a lot of fun, it is
not always the best approach. Macros are especially useful when you have to do a task the same way over
and over again, or when you want to press a single button to do something that normally takes several steps.
Once in a while, you might write a macro to do something you can’t otherwise do in OpenOffice.org, but in
that case you should investigate thoroughly to be sure OOo cannot do it. For instance, a common request on
some of the OpenOffice.org mailing lists is for a macro that removes empty paragraphs. This functionality is
provided with AutoFormat (select Tools > AutoCorrect Options > Options tab and check Remove blank
paragraphs). It is also possible to use regular expressions to search for and replace empty space. There is a
time and a purpose for macros, and a time for other solutions. This chapter will prepare you for the times
when a macro is the solution of choice.

2.1. Macro storage

In OpenOffice.org, routines that are logically related are stored in a module. For example, a module might
contain routines for finding common mistakes that require editing. Logically related modules are stored in a
library, and libraries are stored in library containers. The OpenOffice.org application can act as a library
container, as can any OOo document. Simply stated, the OpenOffice.org application and every
OpenOffice.org document can contain libraries, modules, and macros.
Container A library container contains zero or more libraries.
Library A library contains zero or more modules and dialogs.
Module A module contains zero or more subroutines or functions.

2.1.1. Library container

An OOo document is a library container, as is the application itself. If a specific document requires a macro,
it is useful to store that macro in the document. The advantage is that the macro stays with the document.
This is also an easy way to send macros to others.
If several documents use the same macros, however, then every document will have a copy, and, if you
change the macro, then you must change it in every document that contains the macro. Macros contained in

14
a document are visible only to that document. It is not easy, therefore, to call a macro in a document from
outside of that document.

TIP Do not (except in rare exceptions) store macros that will be called from outside a document in a document;
because macros contained in a document are visible only to that document.

The application library container has two primary components, macros distributed with OOo, and macros
that you create. The OOo macro dialog shows your macros in a container named “My Macros”, and those
distributed as “OpenOffice.org Macros” (see Figure 1). OpenOffice.org Macros are stored in a directory with
the application, and My Macros are stored in your user directories.
Use Tools > Macros > Organize Macros > OpenOffice.org Basic to open the OOo Basic Macros dialog
(see Figure 1). The library containers are the highest level objects shown in the “Macro from” area.

Figure 1. Use the OOo Macros dialog to create new macros and organize libraries.

2.1.2. Libraries
A library container contains one or more libraries, and a library contains one or more modules and dialogs.
Double-click on a library container in Figure 1 to see the contained libraries. Double-click on a library to
load the library and see the contained modules and dialogs.
The OOo Macros dialog uses a different icon to distinguish loaded libraries; in Figure 2, Standard and
XrayDyn are loaded, the other libraries are not.

TIP The icons and colors that you see on your computer may be different than those shown in the screen shots.
Different versions of OOo may use different icons and colors. and more than one icon set is supported. Use
Tools > Options > OpenOffice.org > View to change the icon size and style.

15
 Figure 2. Loaded libraries are shown differently.

2.1.3. Modules and dialogs

A module is typically used to group similar functionality at a lower level than a library. The macros are
stored in the modules. To create a new module, select a library and click New.

2.1.4. Key points

Things to consider:
• You can import libraries from one library container to another.
• Import a module by importing the library that contains the module. It is not possible to simply import
a single module using the GUI.
• Use descriptive names for libraries, modules, and macros. Descriptive names reduce the likelihood
of a name collision, which hampers library import.
• The Standard library is special; it is automatically loaded so the contained macros are always
available.
• The Standard library is automatically created by OOo and cannot be imported.
• Macros contained in a library are not available until after the library is loaded.
• The Macro organizer dialog allows you to create new modules, but not new libraries.
The key points listed above have certain consequences; for example, I rarely store macros in the Standard
library because I cannot import the library to another location. My usual usage for the standard library is for
macros called from buttons in a document. The macros in the standard library then load the actual work
macros in other libraries, and call them.

2.2. Creating new modules and libraries

The New button on the Macros dialog always creates a new subroutine in the selected library (see Figure 1
and Figure 2). A new module is created if the library does not yet contain a module.

16
From the Macros dialog, click the Organizer button to open the OOo Macro Organizer dialog (see Figure 3).
The Modules and Dialogs tabs are almost identical. Use the Modules or Dialogs tab to create, delete, and
rename modules or dialogs.

Figure 3. Modules tab of the OOo Macro Organizer dialog.

Use the Libraries tab (see Figure 4) to create, delete, rename, import, and export libraries.

Figure 4. Libraries tab of the OOo Macro Organizer dialog.

The first step is to select the desired library container from the Location drop-down. To rename a library,
double click on the library and then edit the name in place.

17
 TIP I find renaming modules and libraries in the Macro Organizer dialogs to be frustrating. For renaming
libraries, double or triple click on the library name then wait a few seconds. Try again. Try one more time.
Click on another library. Double or triple click on the library name; you get the idea.
The easiest method to change a module name is to right click on the module name in the tabs at the bottom
of the IDE and choose rename (see Figure 11).

2.3. Macro language

The OpenOffice.org macro language is based on the BASIC programming language. The standard macro
language is officially titled StarBasic, but, it is also referred to as OOo Basic, or Basic. Many different
programming languages can be used to automate OOo. OOo provides easy support for macros written in
Basic, JavaScript, Python, and BeanShell. In this document, my primary concern is Basic.

2.4. Create a module in a document

Each OOo document is a library container able to contain macros and dialogs. When a document contains
the macros that it uses, possession of the document implies possession of the macros. This is a convenient
distribution and storage method. Send the document to another person or location, and the macros are still
available and usable.
1) To add a macro to any OOo document, the document must be open for editing. Start by opening a
new text document, which will be named “Untitled 1” — assuming that no other untitled document
is currently open.
2) Use Tools > Macros > Organize Macros > OpenOffice.org Basic to open the OOo Basic Macros
dialog (see Figure 1).
3) Click the Organizer button to open the OOo Macro Organizer dialog, then click on the Libraries tab
(see Figure 4).
4) Select “Untitled 1” from the location drop-down.

Figure 5. Libraries tab of the OOo Macro Organizer dialog.

5) Click New to open the New Library dialog.

18
 Figure 6. New library dialog.
6) The default name is Library1, which is not very descriptive. Choose a descriptive name and click
OK. The new library is shown in the list. For this example, I named the library “HelloWorld”.

Figure 7. The new library is shown in the list.

7) In the Modules tab, select the HelloWorld library. OOo created the module named “Module1” when
the library was created.

Tip Although Module1 is created when the library is created, a bug in OOo 3.2 may prevent the module from
displaying without closing and re-opening the dialog.

19
 Figure 8. The new library is shown in the list.
8) Click New to open the New Module dialog. The default name is Module2, because Module1 already
exists.

Figure 9. New module dialog.

9) Use a descriptive name and click OK. Module1 is finally displayed (bug in 3.2.0), as is the newly
created module.

20
 Figure 10. The new module is shown in the list.
10) Select HelloModule and click Edit.
11) At this point, I saved the document and named it “DelMeDoc” because I intended to delete the
document when I was finished with the example. Select a name that works well for you. If you
reopen the dialog shown in Figure 10, the document name will be shown rather than “Untitled 1”.
At this point, the Integrated Debugging Environment (IDE) is opened to edit the macro.

2.5. Integrated Debugging Environment

Use the Basic Integrated Debugging Environment (IDE) to create and run macros (see Figure 11). The IDE
places significant functionality in a little space. The toolbar icons are described in Table 1. The top left
corner just above the editing window contains a drop-down list that
shows the current library. The portion in the square brackets identifies the library container, and the portion
following identifies the library. This provides a quick method to choose a library.

21
 Figure 11. Basic Integrated Debugging Environment.
Rest your mouse cursor on a toolbar icon for a few seconds to read the text that appears; this provides a hint
at what that icon does.
Table 1. Toolbar icons in the Basic IDE.
Icon Key Description
Ctrl+N Create a new OOo document.

Ctrl+O Open an existing OOo document.

Ctrl+S Save the current library. If the library is in a document, then the document is saved.

Ctrl+P Print the macro to the printer.

Ctrl+V Paste the clipboard.

Ctrl+Z Undo the last operation.

Ctrl+Y Redo the last operation that was undone.

Open the Object catalog (see Figure 12). Select the macro and double-click on the macro.

Open the OOo Macros dialog (see Figure 2). Select a macro and click edit or run. This is a short-
cut for Tools > Macros > Organize Macros > OpenOffice.org Basic.
Select a module. This opens the OOo Macro Organizer dialog with the Modules tab selected (see
Figure 3). Select a module and click Edit.

22
 Icon Key Description
Open the OOo help, which contains numerous useful examples for Basic.

Click the Compile icon to check the macro for syntax errors. No message is displayed unless an
error is found. The Compile icon compiles only the current module.
F5 Run the first macro in the current module. While stopped (from a breakpoint, or single stepping,

this continues the execution). To run a specific macro, use to open the OOo Basic Macros
dialog, select the desired macro, and click Run.
Shift+F5 Stop the currently running macro.

Shift+F8 Step over the current statement. When a macro stops at a breakpoint, this executes the current
statement. Can also be used to start a macro running in single step mode.
F8 Step into. This is the same as Step over except if the current statement calls another macro, it
single steps into that macro so that you can watch that macro execute.
Step out runs the macro to the end of the current subroutine or function.

Shift+F9
Toggles a breakpoint on / off at the current cursor position in the IDE. An icon ( ) is displayed to
the left of the line to show that a breakpoint is set for that line. You can also double-click in the
breakpoint area to toggle a breakpoint on / off.
Open the manage breakpoints dialog (see Figure 17), which allows you to selectively turn
breakpoints on or off, and also, to prevent a breakpoint from triggering until it has been reached a
certain number of times.
F7 Select a variable and click the Watch icon to add the variable to the watch window. You can also
enter the variable name into the Watch input line and press enter.
Find parentheses.

Insert Basic source. Open a dialog to select a previously saved basic file and insert it.

Save the current module as a text file on disk. OOo stores modules on disk in a special encoded
format. Files saved using this method are standard text files. This is an excellent way to create a
backup of a macro or to create a text file that can be easily sent to another person. This is different
from the Disk icon, which is used to save the entire library or document that contains the module.
Import a dialog from another module.

Module names are listed along the bottom of the IDE. Module navigation buttons are to the left of
the module names. The buttons display the first, previous, next, and last module in the current library. Right
click on a module name to:
• Insert a new module or dialog.
• Delete a module or dialog.
• Rename a module; this is the easiest way that I know to rename a module or dialog.
• Hide a module or dialog.
• Open the OOo Basic Organization dialog.

Use to open the Objects catalog (see Figure 12), select a macro and double-click on the macro to edit
that macro.

23
 Figure 12. Objects catalog.

2.6. Enter the macro

Change the text in the IDE to read as shown in Listing 1. Click the run icon.
Listing 1. Hello World macro
REM ***** BASIC *****
Option Explicit

Sub Main
Print "Hello World"
End Sub

Table 2. Line by line description of Listing 1.

Line Description
REM ***** BASIC ***** Basic comment, this line is ignored. A comment may also begin with a single quote
character.
Option Explicit Tells the basic interpreter that it is an error to use a variable that is not explicitly
defined. Misspelled variables are likely to be caught as an error at compile time.
Sub Main Indicates that this is the beginning of the definition of a subroutine named Main.
Print "Hello World" The Print command.
End Sub End the Main subroutine.

The macro in Listing 1 is text that a human can read. The computer must translate macro text into something
that the computer can use. The process of converting the human readable macro into something that the
computer can read is called compiling. In other words, a macro is written as lines of text that are compiled to
prepare a runnable program.

24
2.7. Run a macro
The Run icon always runs the first macro in the current module. As a result, a different approach is required
if more than one macro is in a module. The following options can be used:
• Place the macro first in the module, and click the Run icon. 
• Use the first macro to call the desired macro. I like this method during development. I keep a main 
macro as the first thing that does nothing. During development, I change the main macro to call the 
macro of interest. For general use, I let the main macro at the top call the most frequently run macro.
• Use the Macro dialog (see Figure 2) to run any routine in the module.
• Add a button to your a document or toolbar that calls the macro. 
• Assign the macro to a keystroke. Use Tools > Customize to open the Customize dialog. Select the 
Keyboard tab. Macro libraries are at the bottom of the Category list. This is also available with Tools
> Macros > Organize Macros > OpenOffice.org Basic, select the macro, and click the Assign 
button to launch the Customize dialog. Various tabs in this dialog allow you to assign the macro to 
execute as a menu item, from a toolbar icon, or a system event.
To use the Macro dialog to run any subroutine in a module, follow these steps:
1. Select Tools > Macros > Organize Macros > OpenOffice.org Basic to open the Macro dialog (see
Figure 2).
2. Find the document that contains the module in the “Macro from” list.
3. Double­click a library to toggle the display of the contained modules. 
4. Select the module to display the contained subroutines and functions in the “Existing macros in: 
<selected module name>” list.
5. Select the desired subroutine or function to run — for example, HelloWorld.
6. Click the Run button to run the subroutine or function.

2.8. Macro security

Depending on how OOo is configured, you may not be able to run macros in a document. When I open a
document containing a macro, the warning in Figure 13 is displayed. If you do not expect a macro or do not
trust the source, then choose to disable macros. Remember, I am able to write a macro that destroys your
computer.

25
 Figure 13. The opened document contains a macro.
Use Tools > Options > OpenOffice.org > Security to open the Security tab of the Options dialog.

Figure 14. Options dialog, security tab.

Click the Macro Security button to open the Macro Security dialog. Choose a level that fits your comfort
level. Medium security uses the confirmation dialog in Figure 13, which is relatively quick and unobtrusive.

26
 Figure 15. Macro Security dialog, Security Level tab.
You can set trusted locations and certificates that allow documents to load without confirmation based on
either where they are stored, or the certificate used to sign a document.

Figure 16. Macro Security dialog, Trusted Sources tab.

27
2.9. Using breakpoints
If you set a breakpoint in the code, the macro stops running at that point. You can then inspect variables,
continue running the macro, or single-step the macro. If a macro fails and you don’t know why, single-
stepping (running one statement at a time) allows you to watch a macro in action. When the macro fails,
you’ll know how it got there. If a large number of statements run before the problem occurs, it may not be
feasible to run one statement at a time, so you can set a breakpoint at or near the line that causes the
problem. The program stops running at that point, and you can single-step the macro and watch the behavior.
The breakpoint On/Off icon sets a breakpoint at the statement containing the cursor. A red stop sign marks
the line in the breakpoint column. Double-click in the breakpoint column to toggle a breakpoint at that
statement. Right-click a breakpoint in the Break-point column to activate or deactivate it.

Use the Manage Breakpoints icon to load the Manage Breakpoints dialog. All of the active breakpoints
in the current module are listed by line number. To add a breakpoint, enter a line number in the entry field
and click New. To delete a breakpoint, select a breakpoint in the list and click the Delete button. Clear the
Active check box to disable the highlighted breakpoint without deleting it. The Pass Count input box
indicates the number of times a breakpoint must be reached before it is considered active. If the pass count is
four (4), then the fourth time that the statement containing the breakpoint is to be run, it will stop rather than
run. This is extremely useful when a portion of the macro does not fail until it has been called multiple
times.

Figure 17. Manage Breakpoints dialog.

There are two things that cause a breakpoint to be ignored: a pass count that is not zero, and explicitly
marking the breakpoint as “not active” in the Manage breakpoints dialog. Every breakpoint has a pass count
that is decremented toward zero when it is reached. If the result of decrementing is zero, the breakpoint
becomes active and stays active because the pass count stays at zero thereafter. The pass count is not
restored to its original value when the macro is finished or restarted.

2.10. How libraries are stored

Macro libraries are stored as XML files that are easily editable using any text editor. In other words, it is
easy for you to poke around and damage your files. This is advanced material that you may want to ignore. If
you do not understand XML and why the file contains &gt; rather than >, perhaps you should not edit the
files. Although manually editing your external libraries is generally considered foolish, I have had at least
one instance where this was required, because OOo was unable to load a module that contained a syntax
error.

28
Each library is stored in a single directory, and each module and dialog is contained in a single file. The
global libraries that are included with OpenOffice.org are stored in a shared basic directory under the
directory in which OOo is installed. Examples:
C:\Program Files\OpenOffice3.2\share\basic 'A Windows installation
/opt/openoffice.org/basis3.2/share/basic 'A Linux installation

OpenOffice.org stores user-specific data in a directory under the user’s home directory. The location is
operating system specific. Use Tools > Options > OpenOffice.org > Paths to view where other
configuration data is stored. Here are some examples where my basic macros are stored:
C:\Documents and Settings\andy\Application Data\OpenOffice.org\3\user\basic 'Windows XP
C:\Users\pitonyaka\AppData\Roaming\OpenOffice.org\3\user\basic 'Windows 7
/home/andy/OpenOffice.org/3/user/basic 'Linux

User macros are stored in OpenOffice.org\3\user\basic. Each library is stored in its own directory off the
basic directory. The user directory contains two files and one directory for each library (see Table 3).
Table 3. Files and some directories in my user/basic directory.
Entry Description
dialog.xlc XML file that references every dialog file known to this user in OpenOffice.org.
script.xlc XML file that references every library file known to this user in OpenOffice.org.
Standard Directory containing the Standard library.
Pitonyak Directory containing a the library named Pitonyak.
PitonyakDialogs Directory containing the library named PitonyakDialogs.

The files dialog.xlc and script.xlc contain a reference to all of the dialogs and libraries known to OOo. If
these two files are overwritten, OOo will not know about your personal libraries even if they exist. You can,
however, either manually edit the files, or, even easier, use the OOo Macro Organizer dialog to import the
libraries (because you can import a library based on the directory).
The directory containing a library contains a single file for each module and dialog in the library. The
directory also contains the files dialog.xlb and script.xlb, which references the modules.

2.11. How documents are stored

The standard OOo formats use a standard ZIP file to store all of the components. Any program that can view
and extract ZIP files can be used to inspect an OOo document — however, some programs will require you
to change the file extension to end with ZIP.
After unzipping an OOo document, you will find files that contain the primary content, styles, and settings.
The extracted document also contains three directories. The META-INF directory references all of the other
files, embedded pictures, code libraries, and dialogs. The Dialogs directory contains all of the embedded
dialogs, and the Basic directory contains all of the embedded libraries.
The point to all this is that in an emergency, you can manually inspect a document’s XML and potentially fix
problems.

29
2.12. Conclusion
Macros and dialogs are stored in modules, modules are stored in libraries, and libraries are stored in library
containers. The application is a library container, as is every document. The IDE is used to create and debug
macros and dialogs.
You have just completed one of the most difficult steps in writing macros for OpenOffice.org: writing your
first macro! You are now ready to explore, try other macro examples, and create a few of your own.

30