OpenOffice.org Macros Explained

An integrated development environment (IDE) is a set of programming tools used to facilitate the creation of software. OpenOffice.org includes a very capable IDE with tools that run, edit, and find errors in your macros. It is worth the time to become familiar with its features. Figure 13 shows the IDE with captions added for many of the icons and display areas. The central display area where macro code is listed is the editor window. Many of the features, such as Stop, Breakpoint, Single Step, and the Watch pane serve as a simple yet effective debugger for macro code.

Figure 13: The IDE included with OpenOffice.org is very capable.

This section provides a quick overview of the standard functions of the IDE. Do not be surprised if you don't fully understand how to use them all at this point. You will become very familiar with these functions as you work through the examples. The first set of functions are used for debugging, and the ones described near the end of this section support the organization and management of objects in your macro programs, libraries, and documents. Following are the icon descriptions.

• The Compile icon compiles and performs a syntax check of only the current module. The Compile icon is useful if you don't want to run the macro but you want to verify that it's syntactically correct. No message is displayed unless an error is found (see Figure 10). When an error is found, a dialog appears, indicating the error. An arrow in the Breakpoint column marks the line with the error, and the portion of the code that caused the error is highlighted. Click the OK button to close the error dialog.

  Note	The process of compiling translates OOo macros into machine language, which the computer can understand and run.

• The Run icon compiles all of the modules in the current library and then runs the first subroutine or function in the current module. This is different from the Compile icon, which compiles only the current module.

• The Stop icon stops a running macro. When you click this icon, you can't resume the macro; you must start it again, from the beginning. The Stop icon is enabled only while a macro is running. When enabled, the Stop icon resembles a traffic stop sign.

• The Procedure Step icon runs the current statement. If the macro is not yet running, the first routine in the module is started and marked as the current statement. The current statement has an arrow in the Breakpoint column, and the cursor is moved to that line. If, however, the macro is already running, the current statement runs and the next runnable statement is marked as current. The Procedure Step icon treats calls to other routines as a single statement and does not step into them. Notice that the icon has an arrow that curves around the curly brackets that represent a subroutine or function call.

• The Single Step icon runs the current statement. The behavior is the same as the Procedure Step icon except that subroutines and functions are not treated as a single statement. Each statement in the called routine is considered a statement. Subroutines and functions are stepped into, marking the called subroutine or function definition as the current statement. Notice that the icon contains an arrow that points into the curly brackets that represent a subroutine or function call.

• The Step Back icon runs the macro to the end of the current routine and then steps out of it. The effect is the same as repeatedly clicking the Procedure Step icon until the last statement in the current routine (End Sub or End Function) is current, and then clicking Procedure Step one more time to step out of the routine. The statement following the call to the current routine becomes the current statement. If you accidentally click Single Step rather than Procedure Step, click the Step Back icon once. Notice that the icon contains an arrow that leaves the curly brackets that represent a subroutine or function call.

• The Breakpoint icon sets a breakpoint at the statement containing the cursor. A red stop sign marks the line in the Breakpoint column. Double-click the Breakpoint column to toggle a breakpoint at that statement. Right-click a breakpoint in the Breakpoint column to activate or deactivate it.

• The Manage Breakpoints icon loads the Manage Breakpoints dialog (see Figure 14 ).

• The Add Watch icon assumes that the current word (the word that contains the icon) is a variable and adds this variable name to the Watch pane.

• The Object Catalog icon opens the Objects window (see Figure 15 ), where you can browse all of the currently available library containers. Use this window to see which libraries, modules, and subroutines are available. Double-click a subroutine to load it into the IDE. The functionality is similar to the Navigator in an OOo Writer document. You must save a file before its modules are available in the Object Catalog.

  Tip	Leave the Objects window open and use it as a navigator to quickly jump between modules, libraries, or even subroutines in the same module.

• The Macros icon loads the Macro dialog. Selecting Tools Macros Macro also loads the Macro dialog.

• The Modules icon loads the Macro Organizer dialog. This icon has the same effect as clicking the Organizer button in the Macro dialog (see Figure 2 and Figure 3).

• Select or place the cursor directly to the left of a parenthesis, and then click the Find Parentheses icon to find the matching parentheses. When the IDE matches parentheses, it selects the matching parentheses and everything that they enclose.

• To open the Controls window, click the Controls icon while editing a dialog. (For more information about controls, see Chapter 17, "Dialogs and Controls.")

• To create a dialog for editing, click the Modules icon to load the Macro Organizer dialog. Click the New Dialog button to create a new dialog. See Chapter 17, "Dialogs and Controls," for more about using and creating dialogs in macros.

• The last two icons, Insert Source Text and Save Source As, are used to insert text stored in an external source file into the current module, and to save the current module to an external text file. 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.

Figure 14: Manually edit and configure breakpoints.

Figure 15: You can browse the available libraries and modules in the Objects window.

Using Breakpoints

If you set a breakpoint in the code, the macro will stop 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 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 Breakpoint column to activate or deactivate it.

The Manage Breakpoints icon loads the Manage Breakpoints dialog (see Figure 14). All of the active breakpoints in the current IDE dialog appear in the lower list. To add a breakpoint, enter a line number in the entry field at the top and then 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.

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.

It is easy to monitor the value of variables from the IDE while a routine is running. Place the cursor next to or in any word in the Edit window and click the Add Watch icon to add the word to the Watch pane. The Watch pane displays the value of variables that are currently in scope. The text "<Out of Scope>" is displayed for variables that are not available. Another way to add variables to the Watch pane is to type the name into the Watch window and press Enter. To delete a name from the Watch pane, select it in the Watch pane or type the name into the Watch window and click the Remove Watch icon. Click a name in the Watch pane to place its name in the Watch window.