Total Access Components Tour: Common Dialogs

If you have ever worked with Windows applications, you are familiar with the standard dialogs that appear when you open or save a file, or select a printer or font. These dialogs are implemented by Windows and are available to developers through the Windows Application Programming Interface (API). Unfortunately, using the API can be difficult for many programmers because of the complicated interface issues associated with the API.

The Common Dialogs control eliminates most of these difficulties by encapsulating the API calls into an easy to use control.

The Common Dialogs control makes it easy to use the Windows Dialogs for:

• Selecting a file to open (the Open dialog)

• Selecting a name to save a file as (the Save dialog)

• Selecting a color (the Select Color dialog)

• Printer settings (the Printer dialog)

• Selecting a font (the Font dialog)

In addition, the Common Dialogs control allows you to work with Windows Help files.

Using the Common Dialogs

There are four basic steps involved in using the Common Dialogs custom control:

1. Determine which part of the custom control you want to use. Since this custom control contains a lot of functionality grouped into dialogs, you must identify which dialog you want to use as well as the properties, methods and events that apply to that dialog.
   

2. Prepare the dialog by setting the properties that define how the dialog works.
   

3. Call the dialog you want by using the appropriate Show method. For example, to call the File Open dialog, you would call the ShowOpen method.
   

4. Gather information about the information that was entered into the dialog. You do this by checking the properties of the custom control.

Step 1 – Determine Which Part of the Custom Control To Use

If you are planning on using the Common Dialogs custom control, you no doubt have a specific function in mind. For example, you may want to prompt the user of your application for the path and name of a file to open. In this case, you want to use the Open File dialog.

Step 2 – Prepare the Dialog

Before calling the dialog, you define the characteristics of the dialog by setting the custom control’s properties. You can do this through the custom control’s property page, or by setting the properties programmatically with VBA code. If the values for the properties are not going to change based on conditions your application’s user is defining, you can set the property values in the property sheet—these values are saved with the form. However, if the property settings may change based on conditions and values that you cannot pre-define, you should set properties in your VBA code.

In Step 1, you determined which dialog you are going to use. Now you must identify the properties that apply to that specific dialog. 

Step 3 – Call the Dialog

Each of the dialogs contained in the Common Dialogs control has an associated Show method. This method causes the control to display the dialog. For example, to display the Open File dialog, call the ShowOpen method.

Step 4 – Gather Return Information

As soon as your VBA code calls the dialog, the code is suspended. When you close the dialog using the [OK] or [Cancel] button, your code then continues to execute. The one exception to this is the ShowHelp method—it performs the requested Help action, and immediately returns control to your VBA code.

Once the dialog has closed, you can gather information about what was done in the dialog. For example, if the Open File dialog was displayed, you probably want to retrieve the value of the path and file selected. To do this, read the values of the properties related to the dialog you are using.

Detecting the [Cancel] Button

Each of the common dialogs has both [OK] and [Cancel] buttons. Your code may need to detect if the [Cancel] button was pressed. To do this, set the CancelError property of the custom control to True. When this property is set to True, pressing the [Cancel] button in the dialog triggers a VBA error. You can trap for this error in your code and use the error to determine whether or not the [Cancel] button was pressed.

Common Dialog Properties

Common Dialog Events