My First Dialog | OpenOffice.org Macros Explained

To create a dialog in the IDE, you must first create an empty dialog. You can use one of two methods to add an empty dialog to a library. The first method is to use the Macro Organizer dialog (Tools Macros Macro). Click the Organizer button to open the Macro Organizer dialog, and then click the New Dialog button. The advantage of using the Macro Organizer is that you can immediately provide a meaningful name for the dialog.

You can also create dialogs and modules directly in the Basic IDE by right-clicking the Module tab. I started by creating and editing the Basic module "Hello". The tabs shown at the bottom of the Basic IDE identify the opened modules and dialogs. Place the cursor in the tab named Hello and click the right mouse button. Then select Insert BASIC Dialog (see Figure 1 ).

Figure 1: Right-click the module tab and select Insert BASIC Dialog.

A new dialog is created with the name Dialog1. Right-click the Dialog1 tab and choose Rename to change the name of the dialog from Dialog1 to HelloDlg. An empty dialog appears in the middle of the IDE page. This dialog, which is currently empty, is the one that will be displayed when you are finished. To select the dialog, click in its lower right corner. After you've selected the dialog, you can use the mouse to change its size or location. If you had selected the dialog by clicking anywhere in it, the more common activity of selecting controls contained in the dialog would be more difficult.

Tip	When something is selected, green boxes appear around the selected item. The green boxes are called handles.

Click the Controls Dialog icon in the toolbar to open the Controls toolbar (see Figure 2 ). The Controls toolbar is non-modal, so you can leave it open and still manipulate the dialog. Click the lower right Test Mode button to open a copy of the dialog in test mode. This allows you to see how the dialog looks. To close the dialog after opening it in test mode, click the Close icon in the upper right corner of the dialog.

Figure 2: Click the Controls button in the toolbar to open the design tools window.

Tip	The Controls toolbar is sometimes referred to as the "design tools window."

Most of the icons in the Controls toolbar are used to add controls to your dialog. If you click any of the control icons in the Controls toolbar, the cursor changes from an arrow-shaped selection cursor to a cross-shaped cursor. You can click the Select icon to change the cursor back to the selection shape rather than insert a new control.

The Properties Dialog

Much of what a dialog or control does is controlled by properties, which you can set at both run time and design time. To set properties at design time, first select the object. After the object is selected, either right-click the object and select Properties, or click the Properties button in the Controls dialog (see Figure 3 ).

Figure 3: Set the properties for the dialog.

The Name property (see Figure 3) sets the name used to retrieve the control from the dialog. For a dialog, there is no reason to change the name, because the dialog is not retrieved in the same way that a control is retrieved. The Title property exists for dialogs (and only for dialogs), and it sets the value of the dialog's title-I set the title for my example dialog to "Hello World." Although the Properties dialog supports setting the position and size, this is usually done using the mouse.

Tip	The properties shown in the Properties dialog change based on the selected object. Even the dialog's title changes based on the selected object. The current title is "Properties: Dialog" because properties for a dialog are displayed.

Use the following steps to set up the dialog in this example.

Open the Controls toolbar by clicking the Controls icon in the toolbar.
Select the dialog by clicking the lower right corner of the dialog (see Figure 2).
Click the Properties icon on the Controls toolbar to open the Properties dialog (see Figure 3).
Set the dialog's name to HelloDlg-I like to name things.
Set the dialog's title to "Hello World." When the cursor leaves the Title property field, the title is displayed in the dialog's title bar.
Make certain that the Properties dialog is not covering the Hello World dialog.
Click the Button icon in the Controls toolbar to add a button to the Hello World dialog. When the cursor moves over the dialog, it changes from the selection arrow to a cross. Position the cursor where you want the button, and then click the mouse button and drag to define the appropriate size.
When the button is created, it defaults to the name CommandButton1. Use the Properties dialog to change the button's name to OKButton and the button's label to "OK".
Use the Properties dialog to change the button type to OK so that the button will automatically close the dialog. If you don't do this, the button will do nothing unless a handler is registered for the button-event handlers are set from the Events tab in the Properties dialog.
In the "Help text" field, enter the text "Click Here" so that some help text is displayed when the cursor rests over the button.

Tip	OpenOffice.org includes numerous excellent examples of dialog and control manipulation in the module named ModuleControls contained in the Tools library.

Starting a Dialog From a Macro

Dialogs can be stored in the document or in a global library (see Chapter 16, "Library Management"). Regardless of where the dialog is stored, it must be loaded before it can be used. Remember that you can access the dialog libraries stored in the current document by using DialogLibraries, and the libraries stored in the application by using GlobalScope.DialogLibraries. Use the following sequence of steps to load, create, and execute a dialog:

Use the loadLibrary() method to load the library containing the dialog. Although you can skip this step if the library is already loaded, it is probably not prudent to assume this.
Use the getByName() method to retrieve the library from DialogLibraries.
Use the method getByName() to retrieve the dialog from the retrieved library.
Create the dialog using CreateUnoDialog().
Execute the dialog.

Listing 2 loads and executes a dialog stored in the current document.

Listing 2: RunHelloDlg is in the Hello module in this chapter's source code files as SC17.sxw.

 Dim oHelloDlg     'The run-time dialog that is created Sub RunHelloDlg   Dim oLib        'Library that contains the dialog   Dim oLibDlg     'Dialog as stored in the library   REM First, load the library.   REM If the dialog is stored in an application-level library rather than   REM in the document, then GlobalScope.DialogLibraries must be used.   DialogLibraries.loadLibrary("OOMECH17")   REM Obtain the entire library now that it has been loaded.   oLib = DialogLibraries.getByName("OOMECH17")   REM Obtain the dialog as stored in the library.   REM I usually think of this as the definition of the dialog.   oLibDlg = oLib.getByName("HelloDlg")   REM Create a dialog that can be used.   oHelloDlg = CreateUnoDialog(oLibDlg)   REM Now start the dialog.   REM The execute() method is really a function that returns 1 if OK   REM is used to close the dialog and 0 if Cancel is used to close the   REM dialog. Clicking the Close button in the upper right corner   REM of the dialog is considered the same as clicking Cancel.   oHelloDlg.execute() End Sub

Tip	The variable that contains the dialog is declared outside of the subroutine that creates the dialog so that the dialog can be accessed in event handlers, which are implemented as subroutines.

Assign an Event Handler

Controls and dialogs can call external event handlers. You can assign individual subroutines as event handlers by using the Events tab of the Properties dialog (see Figure 4 ). A quick look at the title shows that the events in Figure 4 are for a command button. The supported events can change based on the selected object.

Figure 4: Events for a command button.

You can use an event handler to close the Hello World dialog. Use the Properties dialog to change the Button type from OK to default; the dialog will no longer close on its own. You might want to do this, for example, if you want to validate input before closing a dialog. Now, write the event handler that will close the dialog (see Listing 3 ).

Listing 3: ExitHelloDlg is in the Hello module in this chapter's source code files as SC17.sxw.

 Sub ExitHelloDlg   oHelloDlg.endExecute() End Sub

To assign the "When initiating" event to call the ExitHelloDlg macro, open the Properties dialog for the button and click the Events tab. Click the three dots to the right of the desired event (see Figure 4) to open the Assign Macro dialog (see Figure 5 ). You can assign the event handler to any event by selecting the event in the Event list in the upper left corner. The three dots that are used to open the Assign Macro dialog determine which event is initially selected, but you may assign any event from the Assign Macro dialog. You can assign event handlers to multiple events before closing the Assign Macro dialog.

Figure 5: Assign macros to event handlers.

Use the lower left box in the Assign Macro dialog to select the library that contains the event handler. All of the subroutines contained in the selected library are shown in the "Existing macros in:" box. After selecting an appropriate macro, click the Assign button. After you have assigned event handlers, click the OK button to close the Assign Macro dialog.

Warning

To assign an event handler, you must click the Assign button and not the OK button. The only purpose for the OK button is to close the Assign Macro dialog. It is a common and frustrating mistake to select an event handler for an event, and then click OK rather than Assign.