CommonDialog Control

The CommonDialog control provides a standard set of dialog boxes for operations such as opening and saving files, and selecting colors and fonts. The control also has the ability to display help by running the Windows Help engine.

Syntax

CommonDialog

Library Name

CEComDlg

DLL Name

MSCEComDlg.dll

The CommonDialog properties, methods, and events listed in the following table are supported:

Remarks

You use the CommonDialog control in your application by adding it to a form and setting its properties. The dialog displayed by the control is determined by the methods of the control. At run time, a dialog box is displayed or the help engine is executed, when the appropriate method is invoked; at design time, the CommonDialog control is displayed as an icon on a form. This icon cannot be sized.

The CommonDialog control can display the following commonly used dialog boxes:

• Open
• Save As
• Font
• Color

    To use the common dialog control

1. If you haven't done so already, add the CommonDialog control to the toolbox. For information on adding a control, see Installing Controls Using the Windows CE Control Manager.
2. On the toolbox, click the CommonDialog control and draw it on a form.

   When you draw a CommonDialog control on a form, it automatically resizes itself. The CommonDialog control is invisible at run time

3. At run time, use the appropriate method, as listed in the following table, to display the desired dialog.

Note In Windows CE, common dialog boxes are not movable; they are always centered vertically and horizontally on the screen. Common dialog boxes in Windows CE always have the Help button displayed.

The Color Dialog Box

The Color common dialog box enables the user to select a color from a palette or to create and select a custom color. At run time, when the user chooses a color and closes the dialog box, you use the Color property to get the selected color.

    To display the Color dialog box

1. Set the Flags property for the CommonDialog control to the Visual Basic constant cdlCCRGBInit.
2. Use the ShowColor method to display the dialog box

Use the Color property to get the RGB value of the color the user selects.

The Open and Save As Dialog Boxes

The Open common dialog box provides users with a way to select a file to open.

The Save As common dialog box is identical to the Open dialog box in appearance, except for the dialog's caption, and file names appearing dimmed out. At run time, when the user chooses a file and closes the dialog box, the FileName property is used to get the selected file name.

    To display the Open or Save As dialog box

1. Specify the list of file filters that are displayed in the Files of type list box by setting the Filter property.
2. Use the ShowOpen method to display the dialog box.

After the user chooses a file, use the FileName property to get the name of the selected file.

With all the common dialog boxes, when the CancelError property is True, an error is generated when the user clicks the dialog box's Cancel button. You detect that the Cancel button was pressed by trapping the error when the dialog box is displayed.

The Font Dialog Box

The Font dialog box enables the user to select a font by its size, color, and style.

    To display the Font dialog box

1. Set the Flags property to one of the following constant values:
   • CdlCFScreenFonts (screen Fonts)
   • CdlCFPrinterFonts (printer Fonts)
   • CdlCFBoth (both screen and printer fonts)

   Note You must set the Flags property to one of these values before displaying the Font dialog box. Otherwise, the following error occurs:

No Font Exists

2. Use the ShowFont method to display the Font dialog box.

Displaying a Help File

The ShowHelp method of the common dialog control allows you to display a Help file.

    To display a Help file using the ShowHelp method

1. Set the HelpCommand and HelpFile properties.
2. Use the ShowHelp method to display the specified Help file.