 Illustration 12.1: Macro dialog |
[ Previous document | Content Table | Next document ]
OpenOffice.org provides functionality to create and manage Basic macros and dialogs. The following sections examine the usage of the OpenOffice.org Basic programming environment.
Section 12.1 OpenOffice.org Basic and Dialogs - First Steps with OpenOffice.org Basic guides you through the necessary steps to write OpenOffice.org Basic UNO Programs.
Section 12.2 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE provides a reference to the functionality of the OpenOffice.org Integrated Development Environment (IDE). It describes:
The dialogs to manage Basic and dialog libraries.
The functionality of the Basic IDE window: the Basic macro editor and debugger, and the Dialog editor.
The assignment of macros to events
Section 12.3 OpenOffice.org Basic and Dialogs - Features of OpenOffice.org Basic describes the Basic programming language integrated in OpenOffice.org, including
Provides an overview about the general language features built into OpenOffice.org Basic.
Extends the UNO language binding chapter 3.4.3 Professional UNO - UNO Language Bindings - OpenOffice.org Basic by information on how to access the application specific UNO API.
Points out threading and rescheduling characteristics of OpenOffice.org Basic that differ from other languages, such as, from Java, which can be important under certain circumstances.
Section 12.4 OpenOffice.org Basic and Dialogs - Advanced Library Organization describes how the Basic library system stores and manages Basic macros and dialogs in OpenOffice.org, and how the user can access libraries and library elements using the appropriate interfaces.
Section 12.5 OpenOffice.org Basic and Dialogs - Programming Dialogs and Dialog Controls describes the toolkit controls used to create dialogs in the dialog editor. In this section the different types of controls and their specific properties are explained in detail.
Section 12.6 OpenOffice.org Basic and Dialogs - Creating Dialogs at Runtime describes how UNO dialogs can be created at runtime without using the dialog editor. This is useful to show dialogs from UNO components. As this is an advanced way to create dialogs, this section goes deeply into the Toolkit interfaces and extends the section 12.5 OpenOffice.org Basic and Dialogs - Programming Dialogs and Dialog Controls.
Section 12.7 OpenOffice.org Basic and Dialogs - Library File Structure discusses the various files used by the Basic IDE.
Section 12.8 OpenOffice.org Basic and Dialogs - Library Deployment discusses the automatic deployment of Basic libraries into a local or a shared OpenOffice.org installation.
This section provides a tutorial to enable developers to use the Basic IDE. It describes the necessary steps to write and debug a program in the Basic IDE, and to design a Basic dialog. A comprehensive reference of all tools and options can be found at 12.2 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE.
Create a new Writer document and save the document, for example, FirstStepsBasic.odt.
Click Tools – Macros – Organize Macros – OpenOffice.org Basic.
The OpenOffice.org Basic Macros dialog appears. The Macro from list shows macro containers where Basic source code (macros) can come from. There is always a My Macros and a OpenOffice.org Macros container for Basic libraries. Additionally each loaded document can contain Basic libraries.
|
Illustration 12.1: Macro dialog |
The illustration above shows that the document FirstStepsBasic.odt is the only document loaded. Therefore, the My Macros, OpenOffice.org Macros and FirstStepsBasic.odt containers are displayed in the illustration above. Both containers, My Macros and FirstStepsBasic.odt, contain a library named Standard. The OpenOffice.org Macros container contains the libraries that come with a default OpenOffice.org installation – most of them are AutoPilots. The Standard libraries of the application and for all open documents are always loaded. They appear enabled in the dialog. Other libraries have to be loaded before they can be used.
The libraries contain modules with the actual Basic source code. Our next step will create a new module for source code in the Standard library of our FirstStepsBasic.odt document.
Scroll to the document node FirstStepsBasic.odt in the Macro from list.
Select the Standard entry below the document node and click New.
OpenOffice.org shows a small dialog that suggests to create a new module named Module1.
Click OK to confirm.
The Basic source editor window (Illustration 12.2) appears containing a Sub (subroutine) Main.
 Illustration 12.2: Basic source editor window |
The status bar of the Basic editor window shows that the Sub Main is part of FirstStepsBasic.Standard.Module1. If you click Tools – Macros – OpenOffice.org Basic in the Basic editor, you will see that OpenOffice.org created a module Module1 below the Standard library in FirstStepsBasic.odt.
 Illustration 12.3 |
When a module is selected, the Macro name list box on the left shows the Subs and Functions in that module. In this case, Sub Main. If you click Edit while a Sub or Function is selected, the Basic editor opens and scrolls to the selected Sub or Function.
Enter the following source code in the Basic editor window. The example asks the user for the location of a graphics file and inserts it at the current cursor position of our document. Later, the example will be extended by a small insert graphics autopilot. (BasicAndDialogs/FirstStepsBasic.odt)
Sub Main
' ask the user for a graphics file
sGraphicUrl = InputBox("Please enter the URL of a graphic file", _
"Import Graphics", _
"file:///"
if sGraphicURL = "" then ' User clicked Cancel
exit sub
endif
' access the document model
oDoc = ThisComponent
' get the Text service of the document
oText = oDoc.getText()
' create an instance of a graphic object using the document service factory
oGraphicObject = oDoc.createInstance("com.sun.star.text.GraphicObject")
' set the URL of the graphic
oGraphicObject.GraphicURL = sGraphicURL
' get the current cursor position in the GUI and create a text cursor from it
oViewCursor = oDoc.getCurrentController().getViewCursor()
oCursor = oText.createTextCursorByRange(oViewCursor.getStart())
' insert the graphical object at the cursor position
oText.insertTextContent(oCursor.getStart(), oGraphicObject, false)
End Sub
If help is required on Basic keywords, press F1 while the text cursor is on a keyword. The OpenOffice.org online help contains descriptions of the Basic language as supported by OpenOffice.org.
Starting with the line oDoc = ThisComponent, where the document model is accessed, we use the UNO integration of OpenOffice.org Basic. ThisComponent is a shortcut to access a document model from the Basic code contained in it. Earlier, you created Module1 in FirstStepsBasic.odt, that is, your Basic code is embedded in the document FirstStepsBasic.odt, not in a global library below the My Macros container. The property ThisComponent therefore contains the document model of FirstStepsBasic.odt.
 |
Outside document libraries use ThisComponent or StarDesktop.CurrentComponent to retrieve the current document. If access to an open document is required, even if it is not the current document, you have to iterate over the components in StarDesktop.Components, checking their URL property with code similar to the following: oComps = StarDesktop.Components oCompsEnum = oComps.createEnumeration()
while oCompsEnum.hasMoreElements() oComp = oCompsEnum.nextElement() ' not all desktop components are necessarily models with a URL if HasUnoInterfaces(oComp, "com.sun.star.frame.XModel") then print oComp.getURL() endif wend |
 |
To debug the program, put the cursor into the line oDoc = ThisComponent and click the Breakpoint icon in the macro bar. |
 |
The Run icon launches the first Sub in the current module. Execution stops with the first breakpoint. |
 |
Now step through the program by clicking the Single Step icon. |
 |
Click the Macros icon if you need to run a Sub other than the first Sub in the module.. In the OpenOffice.org Basic Macros dialog, navigate to the appropriate module, select the Sub to run and press the Run button. |
To observe the values of Basic variables during debugging, enter a variable name in the Watch field of the Basic editor and press the Enter key to add the watch, or point at a variable name with the mouse cursor without clicking it. In the example below, we can observe the variables sGraphicUrl and oGraphicObject:
 Illustration 12.4 |
Since OpenOffice.org 2.0 it is also possible to inspect the values of UNO objects in the Basic debugger during runtime.
A Sub can be called from customized icons, menu entries, upon keyboard shortcuts and on certain application or document events. The entry point for all these settings is the Customize dialog accessible through the Assign button in the Macro dialog or the Tools – Customize command.
To assign the Sub Main to a toolbar icon, select Tools – Customize and click the Toolbars tab The Toolbars tab looks like this:
 Illustration 12.5 |
Click the Add button in the Toolbars tab. In the Add Commands dialog that pops up, scroll down the Category list until you see the OpenOffice.org Macros node.Expand it and the FirstStepsBasic.odt node. Navigate to the Module FirstStepsBasic.Standard.Module1 and select it. When Module1 is selected, the Commands list shows an entry "Main" for the Sub Main in Module1.Clicking Add will add it to a toolbar.
You can now click the new toolbar item to launch the example macros.
The section 12.2.3 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE - Assigning Macros To GUI Events describes other options to make your Sub accessible from the user interface.
To create a dialog in the Basic IDE, right-click the Module1 tab at the bottom of the Basic source editor and select Insert – Basic Dialog. The IDE creates a new page named Dialog1:
 Illustration 12.6 |
 |
To add controls to the dialog, we require the dialog design tools. Click the Controls icon to pop up the design tools window. The title bar of the tools window can be used to drag the window away from the toolbar to keep it open permanently. |
Our dialog shall offer a more convenient way to select a file than the simple input box of our first example. Furthermore, the user shall be able to control how the picture is anchored in the text after inserting it. For this, we will create a wizard dialog with two steps.
 |
In the design tools window, select File Selection and define the size of the Browse control by dragging a rectangle in the dialog using the left-mouse button. |
 |
The Properties icon displays the Properties Dialog that is used to edit controls and hook up event handling code to events occurring at dialog controls. |
 |
Next, add << Back and Next >> Buttons to move between the dialog steps, and a Finish and Cancel button. Select the Button icon and define the button size using the left-mouse button. Buttons are labeled with a default text, such as CommandButton1. If the Properties Dialog is not open, double click the newly inserted button controls to display it. Enter new labels in the Label field as suggested, and name the dialog step buttons Back and Next. Set the property Enabled for the << Back button to false. |
 |
Use the Label tool to create a label "Select Graphics File:" in the same manner. |
Now the dialog looks similar to the illustration below:
 Illustration 12.7 |
 |
Test the dialog using the Activate Test Mode icon from the design tool window. After you have finished the test, click the Close button of the test dialog window. |
To edit the dialog, such as setting the title and changing the size, select it by clicking the outer border of the dialog. Green handles appear around the dialog. The green handles can be used to alter the dialog size.The Properties Dialog is used to define a dialog title and other dialog properties.
Now we will write code to open the dialog and add functionality to the buttons. To show a dialog, create a dialog object using createUnoDialog() and call its execute() method. A dialog can be closed while it is shown by calling endExecute().
|
|
It is possible to configure the Finish button and the Cancel button to close the dialog by setting the button property PushButtonType to OK and Cancel respectively. The method execute() returns 0 for Cancel and 1 for OK. |
To add functionality to GUI elements, develop Subs to handle GUI events, then hook them to the GUI elements. To add functionality to the buttons of our dialog, click the Module1 tab in the lower part of the Basic IDE and enter the following Subs above the previous Sub Main to open, close and process the dialog. Note that a Private variable oDialog is defined outside of the Subs. After loading the dialog, this variable is visible from all Subs and Functions of Module1. (BasicAndDialogs/FirstStepsBasic.odt)
Private oDialog as Variant ' private, module-wide variable
Sub RunGraphicsWizard
oDialog = createUnoDialog(DialogLibraries.Standard.Dialog1)
oDialog.execute
End Sub
Sub CancelGraphicsDialog
oDialog.endExecute()
End Sub
Sub FinishGraphicsDialog
Dim sFile as String, sGraphicURL as String
oDialog.endExecute()
sFile = oDialog.Model.FileControl1.Text
' the FileControl contains a system path, we have to transform it to a file URL
' We use the built-in Basic runtime function ConvertToURL for this purpose
sGraphicURL = ConvertToURL(sFile)
' insert the graphics
' access the document model
oDoc = ThisComponent
' get the Text service of the document
oText = oDoc.getText()
' create an instance of a graphic object using the document service factory
oGraphicObject = oDoc.createInstance("com.sun.star.text.GraphicObject")
' set the URL of the graphic
oGraphicObject.GraphicURL = sGraphicURL
' get the current cursor position in the GUI and create a text cursor from it
oViewCursor = oDoc.getCurrentController().getViewCursor()
oCursor = oText.createTextCursorByRange(oViewCursor.getStart())
' insert the graphical object at the cursor position
oText.insertTextContent(oCursor.getStart(), oGraphicObject, false)
End Sub
Sub Main
...
End Sub
Select the Cancel button in our dialog in the dialog editor, and click the Events tab of the Properties Dialog, then click the ellipsis button on the right-hand side of the Event When Initiating. As shown in the next illustration the Assign Action dialog appears.
 Illustration 12.8Assign Action dialog |
In the Assign Action dialog press the Macro ... button to open the Macro Selector dialog shown in the illustration below. Navigate to FirstStepsBasic.Standard.Module1, select the Sub CancelGraphicsDialog and press the OK button to link this sub to the wizard dialog's Cancel button.
 Illustration 12.9 |
The next illustration shows how the new assignment is shown in the Assign Action dialog.
 Illustration 12.10 |
Pressing the OK button in the Assign Action dialog finishes the assignment process.
 |
In the Assign Action dialog there's also a Component ... button. This button is only needed in the context of dialogs used by UNO components, see 4.11 Writing UNO Components - Accessing Dialogs. In the Basic context this button is not relevant. |
Using the same method, hook the Finish button to FinishGraphicsDialog.
|
|
If the Run icon is selected now, the dialog is displayed, and the Finish and Cancel buttons are functional. |
The final step is to create a small AutoPilot with two pages. The OpenOffice.org Dialogs have a simple concept for AutoPilot pages. Each dialog and each control in a dialog has a property Page (Step) to control the pages of a dialog. Normally, dialogs are on page 0, but they can be set to a different page, for example, to page 1. All controls having 1 in their Page property are visible as long as the dialog is on page 1. All controls having 2 in their page property are only displayed on page 2 and so forth. If the dialog is on Page 0, all controls are visible at once. If a control has its Page property set to 0, it is visible on all dialog pages.
This feature is used to create a second page in our dialog. Hold down the Control key, and click the label and file control in the dialog to select them. In the Properties Dialog, fill in 1 for the Page property and press Enter to apply the change. Next, select the dialog by clicking the outer rim of the dialog in the dialog editor, enter 2 for the Page property and press the Enter key. The label and file control disappear, because we are on page 2 now. Only the buttons are visible since they are on page 0.
On page 2, add a label "Anchor" and two option buttons "at Paragraph" and "as Character". Name the option buttons AtParagraph and AsCharacter, and toggle the State property of the AtParagraph button, so that it is selected by default. The new controls automatically receive 2 in their Page property. When page 2 is finished, set the dialog to page 1 again, because we want it to be on page 1 on startup.
 Illustration 12.11 |
The Subs below handle the << Back and Next >> buttons, and the Sub FinishGraphicsDialog has been extended to anchor the new graphics selected by the user. Note that the property that is called Page (Step) in the GUI, is called Step in the API. (BasicAndDialogs/FirstStepsBasic.odt)
Sub BackGraphicsDialog
oDialog.Model.Step = 1
oDialog.Model.Back.Enabled = false
oDialog.Model.Next.Enabled = true
End Sub
Sub NextGraphicsDialog
oDialog.Model.Step = 2
oDialog.Model.Back.Enabled = true
oDialog.Model.Next.Enabled = false
End Sub
Sub FinishGraphicsDialog
Dim sGraphicURL as String, iAnchor as Long
oDialog.endExecute()
sFile = oDialog.Model.FileControl1.Text
' State = Selected corresponds to 1 in the API
if oDialog.Model.AsCharacter.State = 1 then
iAnchor = com.sun.star.text.TextContentAnchorType.AS_CHARACTER
elseif oDialog.Model.AtParagraph.State = 1 then
iAnchor = com.sun.star.text.TextContentAnchorType.AT_PARAGRAPH
endif
' the File Selection control returns a system path, we have to transform it to a File URL
' We use a small helper function MakeFileURL for this purpose (see below)
sGraphicURL = MakeFileURL(sFile)
' access the document model
oDoc = ThisComponent
' get the Text service of the document
oText = oDoc.getText()
' create an instance of a graphic object using the document service factory
oGraphicObject = oDoc.createInstance("com.sun.star.text.GraphicObject")
' set the URL of the graphic
oGraphicObject.GraphicURL = sGraphicURL
oGraphicObject.AnchorType = iAnchor
' get the current cursor position in the GUI and create a text cursor from it
oViewCursor = oDoc.getCurrentController().getViewCursor()
oCursor = oText.createTextCursorByRange(oViewCursor.getStart())
' insert the graphical object at the beginning of the text
oText.insertTextContent(oCursor.getStart(), oGraphicObject, false)
End Sub
This section discusses all features of the Integrated Development Environment (IDE) for OpenOffice.org Basic. It shows how to manage Basic and dialog libraries, discusses the tools of the Basic IDE used to create Basic macros and dialogs, and it treats the various possibilities to assign Basic macros to events.
The main entry point to the library management UI is the Tools – Macros – Organize Macros – OpenOffice.org Basic menu item. This item activates the OpenOffice.org Basic Macros dialog where the user can manage all operations related to Basic and dialog libraries.
The following picture shows an example macro dialog. From here you can run, create, edit and delete macros, assign macros to UI events, and administer Basic libraries and modules.
 Illustration 12.12 |
The tree titled with Macro from shows the complete library hierarchy that is available the moment the dialog is opened. See 12.4 OpenOffice.org Basic and Dialogs - Advanced Library Organization for details about the library organization in OpenOffice.org..
Unlike the library organization API, this dialog does not distinguish between Basic and dialog libraries. Usually the libraries displayed in the tree are both Basic and dialog libraries.
|
|
Although it is possible to create Basic-only or dialog-only libraries using the API this is not the normal case, because the graphical user interface (see 12.2.1 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE - Managing Basic and Dialog Libraries - Macro Organizer Dialog below) only allows the creation of Basic and dialog libraries simultaneously. Nevertheless, the dialog can also deal with Basic-only or dialog-only libraries, but they are not marked in any way. |
The tree titled Macro from represents a structure consisting of three levels:
Library container -> library -> library element
The top-level nodes represent the application Basic and dialog library container (nodes My Macros and OpenOffice.org Macros). Foreach opened document, the document's Basic and dialog library container (see 12.4 OpenOffice.org Basic and Dialogs - Advanced Library Organization). In the example two documents are open, a text document called Description.odt and a spreadsheet document named Calculation.ods.
In the second level, each node represents a library. Initially all libraries, except the default libraries named Standard, are not loaded and grayed out. To load a library, the user double-clicks the library. In the example above, the My Macros root element contains the Standard library, already loaded by default.
The third level in the tree is visible in loaded libraries. Each node represents a library element that can be modules or dialogs. In the OpenOffice.org Basic Macros dialog, only Basic modules are displayed as library elements, whereas dialogs are not shown. By double-clicking a library the user can expand and condense a library to show or hide its modules. In the example, the My Macros/Standard library is displayed expanded. It contains two modules, Module1 and Module2. The document Description.odt contains a Standard library with one Basic module Module1. Calculation.ods contains a Standard library without Basic modules. All libraries, respectively their dialog library part, may also contain dialogs that cannot be seen in this view.
If a library is password-protected and a user double-clicks it to load it, a dialog is displayed requesting a password. The library is only loaded and expanded if the user enters the correct password. If a password-protected library is loaded using the API, for example, through a call to BasicLibraries.loadLibrary("Library1"), it is displayed as loaded, not grayed out, but it remains condensed until the correct password is entered (see 12.4 OpenOffice.org Basic and Dialogs - Advanced Library Organization).
The middle column contains information about the macros, that is, the Subs and Functions, in the libraries. In the list box at the bottom, all Subs and Functions belonging to the module selected in the tree are listed. In the edit field titled Macro name, the Sub or Function currently selected in the list box is displayed. If there is no module selected in the tree, the edit field and list are empty. You can type in a desired name in the edit field.
On the right-hand side of the OpenOffice.org Basic Macros dialog, there are several buttons. The following list describes the buttons:
Run
Executes the Sub or Function currently displayed in the Macro name edit field. The OpenOffice.org Basic Macros dialog is closed, before the macro is executed.
Close
Closes the OpenOffice.org Basic Macros dialog without any further action.
Assign
Opens the Customize dialog that can also be opened using Tools - Customize. This dialog can be used to assign Basic macros to events. For details see 12.2.3 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE - Assigning Macros To GUI Events below.
Edit
Loads the module selected in the tree into the Basic macro editor. The cursor is placed on the first line of the Sub or Function displayed in the Macro name edit field. See chapter 12.2.2 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE - Basic IDE Window below for details about the Basic macro editor. This button is disabled if there is no module selected in the tree or no existing Sub or Function displayed in the Macro name edit field.
Delete
This button is only available if an existing Sub or Function is displayed in the Macro name edit field. The Delete button removes the Sub or Function displayed in the Macro name edit field from the module selected in the module selected in the tree.
New
This button is only available if no existing Sub or Function is displayed in the Macro name edit field. The New button inserts a new Sub into the module selected in the tree. The new Sub is named according to the text in the Macro name edit field. If Macro name is empty, the Sub is automatically named Macro1, Macro2, and so forth.
Organizer
This button opens the OpenOffice.org Basic Macro Organizer dialog box that is explained in the next section.
Help
Starts the OpenOffice.org help system with the Macros topic.
This dialog is opened by clicking the Button Organizer in the OpenOffice.org Basic Macros dialog. The dialog contains the tab pages Modules, Dialogs and Libraries. While the OpenOffice.org Basic Macros dialog refers to Subs and Functions inside Basic modules, such as run Subs, delete Subs, and insert new Subs, this dialog accesses the library system on module (tab page Modules) , dialog (tab page Dialogs) and library (tab page Libraries) level.
Illustration 12.13 shows the OpenOffice.org Basic Macro Organizer dialog with the Modules tab page activated. The list titled Module is similar to the Macro from list in the Macro dialog, but it contains the complete library hierarchy for the OpenOffice.org application libraries and the document libraries. The libraries are loaded, and condensed or expaned by double-clicking the library. The illustration shows the application library Standard containing two modules, Module1 and Module2.
 Illustration 12.13 |
|
|
The illustration above shows that two documents are loaded. The illustration shows a library Standard in document Description.odt containing a module named Module1, and another library Standard in document Calculation.ods containing no Basic module.
The following list describes the buttons on the right side of the dialog:
Edit
Loads the module selected in the tree into the Basic macro editor. If a module is not selected, this button is disabled.
Close
Closes the OpenOffice.org Basic Macro organizer dialog without any further action.
New Module
Opens a dialog that allows the user to type in the desired name for a new module. The name edit field initially contains a name like Module<Number>, Such as Module1 and Module2. depending on the modules already existing. Clicking the OK button add the new module as a new item in the Module list. The New Module button is disabled if the selected library has read-only status.
Delete
Deletes the selected module. This button is disabled if no module is selected, or if the selected module belongs to a library with read-only status.
Illustration 12.14 shows the OpenOffice.org Basic Macro Organizer dialog with the Dialogs tab page activated. The illustration shows the application library Standard containing two dialogs, Dialog1 and Dialog2.
 Illustration 12.14 |
The illustration shows a library Standard in document Calculation.ods containing a dialog named Dialog1, and another library Standard in document Description.odt containing no dialog.
The following list describes the buttons on the right side of the dialog:
Edit
Loads the dialog selected in the tree into the Dialog editor. The section 12.2.2 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE - Basic IDE Window - Dialog Editor below describes the Dialog Editor in more detail. If a dialog is not selected, this button is disabled.
Close
Closes the OpenOffice.org Basic Macro organizer dialog without any further action.
New Dialog
Opens a dialog that allows the user to enter the desired name for a new dialog. The name edit field initially contains the name Dialog<Number>, such as Dialog1 and Dialog2, depending on the dialogs already existing. Clicking the OK button creates the dialog in the Dialog list. This button is disabled if the selection contains a library with read-only status.
Delete
Deletes the selected dialog. This button is disabled if no dialog is selected, or if the selected dialog belongs to a library with read-only status.
The following illustrations show the OpenOffice.org Basic Macro Organizer dialog with the Libraries tab page activated. In this dialog, the application and document libraries are listed separately. The Library list only contains the libraries of the library container currently selected in the Location list box. The second illustration is dropped down showing the My Macros & Dialogs and OpenOffice.org Macros & Dialogs entries and the two open documents.
 Illustration 12.15 |
 Illustration 12.16 |
The libraries are displayed in the following manner:
Regular libraries are displayed in black.
Libraries with read-only status are grayed out.
Library links are followed by an URL indicating the location where the library is stored. In the example above, all libraries except for Standard and Library1 are library links and all library links have read-only status.
Password protected libraries are indicated with a key symbol before the name. In the example, only Library1 is password protected.
Clicking a library twice (notdouble-click) allows the user to rename it.
The following list describes the buttons on the right side of the dialog:
Edit
Loads the first module of the library selected in the Library list box into the Basic macro editor (see 12.2.2 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE - Basic IDE Window - Basic Source Editor and Debugger below). If the library only contains dialogs, the first dialog of the corresponding dialog library is displayed in the Dialog editor (see 12.2.2 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE - Basic IDE Window - Dialog Editor below). If the Basic/Dialog editor window does not exist, it is opened.
Close
Closes the OpenOffice.org Basic Macro Organizer dialog without any further action.
Password
Opens the Change Password dialog displayed in the next illustration for the library currently selected in the Library list box.
This dialog is used to change the password if the library is already password protected. Enter the old password first, then the new password twice.
If the library is not password protected, the Old password edit field is disabled. The new password is entered twice in the New password section. Clicking OK activates the password protection if both passwords match.
 Illustration 12.17 |
New
Opens a dialog allowing the user to enter the name for a new library. The name edit field initially contains the name Library<Number>, such as Library1 and Library2, depending on the libraries already existing. Clicking the OK button creates the library and adds it to the Library list. A new library is always created as a Basic and dialog library.
Import
This button is used to import additional libraries into the library container that is selected in the Location list box. The button opens a file dialog where the user selects the location where the libraryis imported from. The following types of files can be selected:
Library container index files (script.xlc or dialog.xlc)
Library index files (script.xlb or dialog.xlb)
OpenOffice.org documents (e.g. *.odt, *.ods,*.sxw, *.sxc, *.sdw, *.sdc)
Star Office 5.x and previous Basic library files (*.sbl)
After selecting a file, an Import library dialog is displayed. The next illustration shows the dialog after selecting a library index file script.xlb. The dialog displays all libraries that are found in the chosen file. In this example, only the library Euro appears, because the file script.xlb only represented this library.
 Illustration 12.18 |
The checkboxes in the Options section, when selected, indicates if a library is inserted as a read-only link and if existing libraries with the same name are replaced by the new library.
The next illustration shows the dialog after selecting the writer document LibraryImportExample. This document contains the four libraries Standard, Library1, Library2 and Library3. The illustration shows that the libraries Library1 and Library2 are selected for import. The Insert as reference (read-only) option is disabled, because the libraries inside documents cannot be referenced as a link. As well, StarOffice 5.x Basic libaray files can not be linked.
 Illustration 12.19 |
Clicking the OK button imports the selected libraries into the library container that was previously selected in the Location list box, including the Basic and dialog libraries.
Export
This button is used to export a library. The Standard library cannot be exported. Clicking the button displays the Export Basic library dialog.
 Illustration 12.20 |
This dialog allows to chose between two export formats. Choosing Export as package and clicking OK opens the Export library as package file dialog allowing to save the library in the UNO package bundle format that can be easily imported from other OpenOffice.org installations using the Package Manager available in the Tools menu. So this format should be used for deploying Basic libraries.
 Illustration 12.21 |
Choosing Export as BASIC library in the Export Basic library dialog opens the Export as BASIC library dialog allowing to choose a location where the library will be stored as folder named like the library. This format can be accessed with the Import functionality described above.
 Illustration 12.22 |
The exported libraries always contain both Basic Modules and Dialogs.Delete
Deletes the item selected in the Library list box. If the item represents a library link, only the link is removed, not the library itself. The Delete button appears disabled whenever a Standard library is selected, because Standard libraries cannot be deleted.
The OpenOffice.org IDE is mainly represented by the Basic IDE window. The IDE window has two different modes:
The Basic editor mode displays and modifies Basic source code modules to control the debugging process and display the debugger output
The dialog editor mode displays and modifies dialogs.
Basic source code and dialogs are never displayed at the same time. The IDE window is in Basic editor or debugger, or in dialog editor mode. The following illustration shows the Basic IDE window in the Basic editor mode displaying Module2 of the application Standard library.
 Illustration 12.23 |
The IDE window control elements common to the Basic editor and dialog editor mode are described below. The mode specific control elements are described in the corresponding subchapters 12.2.2 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE - Basic IDE Window - Basic Source Editor and Debugger and 12.2.2 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE - Basic IDE Window - Dialog Editor:
Clicking the Printer button in the main toolbar prints the displayed Basic module or dialog directly without displaying a printer dialog.
The Save button in the main toolbar behaves in two different ways depending on the library currently displayed in the IDE window.
If the library belongs to the application library container, the Save button saves all modified application libraries.
If the library belongs to a document, the Save button saves the document.
On the left-hand side of the toolbar, a Library list box shows the currently displayed library. The user can also modify the displayed library. In the example above, the Standard library of the application Basic ([My Macros & Dialogs].Standard) is displayed. The list box contains all the application and document libraries that are currently accessible. The user can select one to display it in the IDE window.
The tabs at the bottom of the IDE window indicate all the modules and dialogs of the active library. Clicking one of these tabs activates the corresponding module or dialog. If necessary, the IDE window switches from Basic editor to dialog editor mode or conversely. Right-clicking a tab opens a context menu:
Insert opens a sub menu to insert a new module or dialog.
Delete deletes the active module or dialog after confirmation by the user.
Rename changes the name of the active module or dialog.
Hide makes the active module or dialog invisible. It no longer appears as a tab flag, thus it cannot be activated. To activate, access it directly using the OpenOffice.org Basic Macros or OpenOffice.org Basic Macro Organizer dialog and clicking the Edit button.
Modules opens the OpenOffice.org Basic Macro Organizer dialog.
The status bar displays the following information:
The first cell on the left displays the fully qualified name of the active module or dialog in the notation LibraryContainer.LibraryName.<ModuleName | DialogName>.
The second cell displays an asterisk "*" indicating that at least one of the libraries of the active library container has been modified and requires saving.
The third cell displays the current position of the cursor in the Basic editor window.
The fourth cell displays "INSRT" if the Basic editor is in insertion mode and "OVER" if the Basic editor is in overwrite mode. The modes are toggled with the Insert key.
The Basic editor and debugger of the IDE window is shown when the user edits a Sub or Function from the Tools-Macros-Organize Macros-OpenOffice.org Basic dialog (see Illustration 12.24: Basic Editor and Debugger). In this mode, the window contains the actual editor main window, debugger Watch window to display variable values and the debugger Calls window to display the Basic call stack. The Watch and Calls windows are only used when a Basic program is running and halted by the debugger.
The editor supports common editor features. Since the editor is only used for the OpenOffice.org Basic programming language, it supports a Basic syntax specific highlighting and F1 help for Basic keywords.
 Illustration 12.24: Basic Editor and Debugger |
The following list explains the functionality of the macro toolbar buttons.
 |
Compile: Compiles the active module and displays an error message, if necessary. This button is disabled if a Basic program is running. Always compile libraries before distributing them. |
|
|
Run: Executes the active module, starting with the first Sub in the module, before all modified modules of the active library are compiled. Clicking this button can also result in compiler errors before the program is started. This button resumes the execution if the program is halted by the debugger. |
 |
Stop: Stops the Basic program execution. This button is disabled if a program is not running. |
 |
Procedure Step: Executes one Basic statement without stepping into Subs or Functions called in the statement. The execution is halted after the statement has been executed. If the Basic program not is running the execution is started and halted at the first statement of the first Sub in the current module. |
|
|
Single Step: Executes one Basic statement. If the statement contains another Sub, execution is halted at the first statement of the called Sub. If no Subs or Functions are called in the statement, this button has the same functionality as the Step over button (key command F8). |
 |
Step back: Steps out of the current executed Sub or Function and halts at the next statement of the caller Sub or Function. If the currently executed Sub or Function was not called by another Sub or Function or if the Basic program is not running, this button has the same effect as the Run button. |
|
|
Breakpoint: Toggles a breakpoint at the current cursor line in the Basic editor. If a breakpoint can not be set at this line a beep warns the user and the action is ignored (key command F9). A breakpoint is displayed as a red dot in the left column of the editor window. |
 |
Add watch: Adds the identifier currently touched by the cursor in the Basic editor to the watch window (key command F7). |
 |
Object Catalog: Opens the Objects dialog. This dialog displays the complete library hierarchy including dialogs, modules and the Subs inside the modules. |
|
|
Macros: Opens the OpenOffice.org Basic Macros Dialog. |
 |
Modules: Opens the OpenOffice.org Basic Macro Organizer dialog |
 |
Find Parentheses: If the cursor in the Basic editor is placed before a parenthesis, the matching parenthesis is searched. If a matching parenthesis is found, the code between the two parentheses is selected, otherwise the user is warned by a beep. |
|
|
Controls: Opens the dialog editing tools in the dialog editor. In Basic editor mode this button is disabled. |
 |
Insert Source File: Displays a file open dialog and inserts the selected text file (*.bas is the standard extension) at the current cursor position into the active module. |
 |
Save Source As: Displays a file Save As dialog to save the active module as a text file (*.bas is the standard extension). |
Illustration 12.24: Basic Editor and Debugger shows how the IDE window looks while a Basic program is executed in debugging mode.
The Stop button is enabled.
A breakpoint is set in line 11.
The execution is halted in line 12. The current position is marked by a yellow arrow.
The Watch window contains the entries Value and Hello, and displays the current values of these variables. Values of variables can also be evaluated by touching a corresponding identifier in the source code with the cursor.
The Calls window shows the stack. The currently executed Sub doIt is displayed at the top and the Sub Main at the second position.
This section provides an overview of the Dialog editor functionality. The controls that are used to design a dialog are not explained. See 12.5 OpenOffice.org Basic and Dialogs - Programming Dialogs and Dialog Controls for details on programming these controls. The dialog editor is activated by creating a new dialog, clicking a dialog tab at the bottom of the IDE window, or selecting a dialog in the OpenOffice.org Basic Macro Organizer dialog and clicking the Edit button.
Initially, a new dialog consists of an empty dialog frame. The next illustration shows Dialog2 of the application Standard library in this state.
 Illustration 12.25 |
In the dialog editor mode, the Controls button is enabled and the illustration shows the result by clicking this button. A small toolbar with dialog specific tools is displayed. The buttons in this toolbar represent the types of controls that can be inserted into the dialog. The user clicks the desired button, then draws a frame with the mouse at the position to insert the corresponding control type.
The following three buttons in the dialog tools window do not represent controls:
 |
The Select button at the lower right of the dialog tools window switches the mouse cursor to selection mode. In this mode, controls are selected by clicking the control with the cursor. If the Shift key is held down simultaneously, the selection is extended by each control the user clicks. Controls can also be selected by drawing a rubberband frame with the mouse. All controls that are completely inside the frame will be selected. To select the dialog frame the user clicks its border or includes it in a selection frame completely. |
|
|
The Activate Test Mode button switches on the test mode for dialogs. In this mode, the dialog is displayed as if it was a Basic script (see 12.5 OpenOffice.org Basic and Dialogs - Programming Dialogs and Dialog Controls). However, the macros assigned to the controls do not work in this mode. They are thereto help the user design the look and feel of the dialog. |
|
|
The Properties button at the lower left of the dialog tools window opens and closes the Properties dialog. This dialog is used to edit all properties of the selected control(s). The next illustration shows the Properties dialog for a selected button control. |
 |
The Manage Language button (available since OpenOffice.org 2.2) opens the Manage User Interface Languages dialog allowing to manage the localization of dialogs. All details concerning Dialog localization are described in 12.2.4 OpenOffice.org Basic and Dialogs - OpenOffice.org Basic IDE - Dialog Localization. |
 Illustration 12.26 |
The illustration above shows that the dialog tool window can be pulled from the main toolbar by dragging the window at its caption bar after opening it.
The Properties dialog has two tabs. The General tab, visible in Illustration 12.26, contains a list of properties. Their values are represented by a control. For most properties this is a list box, such as color and enum types, or an edit field, such as numeric or text properties. For more complex properties, such as fonts or colors, an additional ellipsis button opens another type of dialog, for example, to select a font. When the user changes a property value in an edit field this value is not applied to the control until the edit field has lost the focus. This is forced with the tab key. Alternatively, the user can commit a change by pressing the Enter key.
The Events tab page displays the macros assigned to the events supported by the selected control:
 Illustration 12.27 |
In the example above, a macro is assigned to the Key pressed event: When this event occurs, the displayed Sub doNothing in Module2 of the application Basic library Standard is called. The events that are available depend on the type of control selected.
To change the event assignment the user has to click one of the ellipsis buttons to open the Assign Action dialog displayed in Illustration 12.28: Assign Action Dialog.
 Illustration 12.28: Assign Action Dialog |
The list box titled Event displays the same information as the Events tab of the Properties dialog. The Assign Action dialog is always the same, that is only the selected event in its Event list changes according to the ellipsis button the user selected on the Events tab of the Properties dialog.
To assign a macro to an event, the user needs to click on the Macro ... button. This opens the Macro Selector dialog which allows the user to select a macro from the library hierarchy. Clicking OK in the Macro Selector assigns the selected macro to the event. If another macro is already assigned to an event, this macro is replaced. If no Sub is selected, the OK button is disabled.
If the dialog is stored in a document, the library hierarchy displayed in the Macro Selector dialog contains the application library containers and the library container of the document. If the dialog belongs to an application dialog library, document macros are not displayed since they cannot be assigned to the controls of application dialogs. This is because it cannot be guaranteed that the document will be loaded when the application dialog event is fired.
The Remove button is enabled if an event with an assigned macro is selected. Clicking this button removes the macro from the event, therefore the event will have no macro binding.
The list box below the Remove button is used to select different macro languages. Currently, only OpenOffice.org Basic is available.
The OK button closes the Assign Action dialog, and applies all event assignments and removals to the control. The changes are reflected on the Events tab of the Properties dialog.
The Cancel button also closes the Assign Action, but all assignment and removal operations are discarded.
As previously explained, it is also possible to select several controls simultaneously. The next picture shows the situation if the user selects both CommandButton1 and CheckBox1.For the Properties dialog such a multi selection has some important effects.
 Illustration 12.29: Properties dialog for multi selection |
Here the caption of the Properties contains the string Multiselection to point out the special situation. The two important differences compared to the single selection situation are:
The displayed properties are an intersection of the properties of all the selected controls, that is, the property is only displayed if all the selected controls support that property. A property value is only displayed if the value is the same for all selected controls. All selected controls are effected when a value is changed by the user. Values that are not the same for all controls can be set with the effect that the specified value applies to all controls in the selection.
A multi-selection Properties dialog does not have an Events tab. Events can only be specified for single controls.
The functionality to assign macros to control events in the dialog editor was discussed earlier. There is also a general functionality to assign macros or other actions to events. This functionality can be accessed through the Customize dialog that is opened using Tools – Customize or by clicking the Assign button in the Macro dialog. In this section, only the assignment of macros is discussed. For more information about this dialog, refer to the OpenOffice.org documentation.
The next illustration shows the Menu tab of the Customize dialog
 Illustration 12.30: Configuration dialog for Menu |
The illustration above shows how a macro is assigned to a new menu item. The Menu and Menu Content list boxes can be used to navigate the OpenOffice.org menu hierarchy. Clicking the Add... button opens the Add Commands dialog. The Category list box in the Add Commands dialog contains entries for built-in OpenOffice.org functions, and a OpenOffice.org Macros entry that represents the hierarchy of OpenOffice.org macros. When an entry is selected in the Categories list box, any commands or macros it contains are displayed in the Commands list box on the right.
Clicking the Add button in the Add Commands dialog adds the selected command or macro to a menu.
The other buttons in the Menus tab of the Customize dialog are as follows:
The New button creates a new top level menu
The Menu button has commands for moving, renaming and deleting top level menus
The Modify button has commands for adding submenus and separators, and renaming and deleting menu items.
The arrow buttons change the position of a menu item.
The Reset button restores the default menu configuration.
The next illustration shows the Events tab of the Customize dialog:
 Illustration 12.31: Configuration dialog for Events |
On this tab, macros can be assigned to general events in OpenOffice.org. The events are listed in the list box titled Event. The Assign button opens the Macro Selector from which the user can select macros to assign to events. The Remove button removes the assigned macro from the selected event.
In the Keyboard tab macros are accessed in Category and Function list boxes, then assigned to a shortcut key that can be specified in the Shortcut keys list box. There are also Load, Save and Reset buttons for loading, storing and resetting keyboard configurations.
The Keyboard tab contains a OpenOffice.org and a Document radio button which controls the scope for which keyboard assignments are made.
Beginning with OpenOffice.org 2.2 it's possible to localize dialogs created in the Dialog Editor. The localization always refers to complete Dialog Libraries, not to single dialogs. A Dialog Library's default state is “Not localized”. In this state dialogs behave and are stored in the same way as before the localization feature was available.
The entry point for localizing a Dialog Library is the Manage User Interface Languages dialog that can be openend by clicking the Manage Language button in the dialog tool window (placed at the right in the second line in Illustration 12.32). The next illustrations shows the dialog editor with an opened Manage User Interface Languages dialog.
 Illustration 12.32: Dialog Editor with Manage User Interface Languages dialog |
Initially no language is defined, so the Present Languages list has no entry. The dialog captions shows that the localization refers to the complete library Standard. To enable localization for this library the Add... button has to be used. It opens another dialog allowing to chose the first language to be supported (see next illustration). The currently active UI language is preselected.
|
< |