OpenOffice.org is an invaluable asset on a computer in any home or office; it's Writer component can be used to write any documents (such as a letter to the bank manager, or even an article for Suite101); and the Calc component can be used to produce spreadsheets for everything from daily household cash management to to multi-million dollar business proposals (and hence using Writer to put together a letter to the bank manager). Unfortunately, it doesn't take long for these spreadsheets to become very complicated, often much too complicated for new users; fortunately a spreadsheet designer can make life much easier by introducing custom dialog boxes.

Creating a Custom Dialog Box

There are three stages to creating a custom dialog box:

• design the dialog using OpenOffice's IDE (Integrated Design Environment)
• write the code that provides functionality to the dialog
• associate code to any objects such as buttons

So, the first job to do is to create the dialog box itself (using the OpenOffice Basic IDE); and to do this click on:

• Tools
• Macros
• Organize Dialogs
• New

As always in when you're creating a new dialog (or a new Baic module) the IDE will suggest a name (for example Dialog1 or Module1); it's always best to change the name to something more memorable – such as dlgRoomVolume; and once that's done then a new, blank dialog box will have been created. The next step is to:

• use the IDE's toolbox to add elements (such as text boxes and buttons) to the dialog
• use each elements property dialog to give the element appropriate names and to change any displayed text (such as the labels on buttons)

Once the visual side of the dialog is correct then the functionality needs to be considered.

Writing Code for the Custom Dialog Box

The new dialog box may look professional, but it doesn't actually do anything yet; and so, to make it useful, two things must be done:

• code must be written that will make the dialog available to a user
• code must be written for all of the actions in the dialog

At this stage the developer needs to turn to a code window of the IDE - either by clicking on one of the tabs at the bottom of the screen (for an existing macro) or by creating a new macro (as shown in Using Macros to Automate OpenOffice.org Calc).

Obviously, the first task is to write a macro (or macros) that will call the dialog:

Option Explicit

Dim dlgRoomVolume as Object

Sub Main

show_dlgRoomVolume

End Sub

Sub show_dlgRoomVolume

Dim libStandard

Dim libDialog

libStandard = DialogLibraries.getByName("Standard")

libDialog = libStandard.getByName("dlgRoomVolume")

dlgRoomVolume = CreateUnoDialog(libDialog)

dlgRoomVolume.execute

End Sub

This code:

• loads all of the necessary libraries
• creates the dialog box
• shows the dialog box to the user

And it's worth noting that it is normally considered bad practice to use global variables whilst programming - in this case it is essential - the dialog box object must be available to all of the macros.

As it stands the user will be able to see the dialog; they'll even be able to type into any text or numeric boxes, but nothing else will happen; therefore, the next job to do is to write the code that will add actions to the dialog:

Sub set_contents

Dim targetCell

targetCell = thisComponent.Sheets(0).getCellRangeByName("B1")

targetCell.Value = dlgRoomVolume.getControl("ipRL").Value

End Sub

The purpose of the macro is to take the contents of numeric boxes in the dialog and to do something with them - in this case to write data to a spreadsheet. However, the dialog still won't 'do' anything - for that to happen the macro needs to be assigned to an action.

Assigning Basic Code to Dialog Events

The custom dialog now consists of two elements:

• the Graphical User Interface, or GUI (which doesn't do anything)
• the macros (which the user can't access)

The macros, therefore, need to be assigned to the actions of the dialog; and this is done by doing the following:

• view the dialog in design mode
• click on one of the elements (such as a button)
• view its properties (right mouse click on it)
• click on the 'Event's tab
• choose the event (e.g. Mouse button clicked) and then click on the 'Assign action' button (it has three dots on it)
• select the macro to be assigned to the action

If the macro to show the dialog is now run then the macro will be executed when the button is clicked

Conclusion

This short tutorial has shown how to extend the functionality of OpenOffice by adding custom built dialog boxes. It has shown that the three steps are:

• create a new dialog using the OpenOffice Basic IDE
• write macros to be run by the dialog (again in the OpenOffice Basic IDE)
• assign the macros to the dialog box elements (such as buttons)

By using this simple technique a developer can quickly build a highly complex, but simple to use, application.