Common Dialog Classes

Windows Forms includes a host of common dialog classes, enabling a consistent and easy-to-operate user interface. The common dialog classes inherit the System.Windows.Forms.CommonDialog class. CommonDialog implements many of the methods that the common dialogs use, which contributes to the consistency and ease of use among all the common dialogs.

This section covers the common dialogs and provides tips on how to use them effectively. To create each of the listings in this section, I dragged a Button control to the form and added relevant code to its Click event. All of the dialogs can be dragged from the Tool Palette and dropped onto the design surface. They reside toward the bottom of the form designer (see Figure 7.1), as do other nonvisual components.

Figure 7.1. A common dialog in the form designer.

SHOP TALK
INSTALLING NEW COMPONENTS

While writing this chapter, I noticed that the FolderBrowserDialog was not yet a member of the Dialogs section of the Tool Palette. This is a new dialog added to the .NET Framework v1.1, so it hadn't been included yet. Here are the steps I took to load the FolderBrowserDialog into the Tool Palette. This procedure can be used for any other control you would like to have in the Tool Palette.

To fix this, I opened the Component menu and selected Installed .NET Components. The first tab is for Installed .NET Components, so I clicked into the ListView control and typed F-O, which brought me straight to the FolderBrowserDialog component. After checking the box and clicking the OK button, I went to the Tool Palette to find it. It wasn't in the Dialogs section, so I started looking in the other sections. The problem is that there were so many components that looking for the one I needed got tedious using the scrollbar. That's why the <Search Tools> box is there. It is just a text box that brings up the components named for what is typed. So I typed an F and the FolderBrowserDialog appeared right away in the Windows Forms section. I quickly dragged it down to the Dialog section and was set to move on.

ColorDialog

The ColorDialog offers a common way to obtain a Color object for applications. Listing 7.6 shows how to use it.

Listing 7.6 The ColorDialog Class (ColorDlg.cs)

 private void btnColor_Click(object sender, System.EventArgs e) {   colorDialog1.ShowDialog();   MessageBox.Show(colorDialog1.Color.ToString()); } 

As shown in Listing 7.6, the only requirement for displaying a ColorDialog is to execute its ShowDialog method. It uses the Color property to extract which color the user selected. ColorDialog has some properties that control how it is displayed (see Table 7.3). Each property is available for setting in the Object Inspector.

Table 7.3. ColorDialog Class Properties

PROPERTY	DESCRIPTION
AllowFullOpen	Setting this property to false prevents opening the custom colors panel.
AnyColor	Setting this property to true displays all available colors.
Color	Used to get the color that the user selected.
FullOpen	By default, the ColorDialog appears with a grid of predefined colors to select. A button labeled "Define Custom Colors >>" expands the dialog to the right to expose a custom color editing panel. When AllowFullOpen is true, this panel is automatically opened as soon as ColorDialog appears.
ShowHelp	Setting this property to true displays the Help button.
SolidColorOn	Only solid colors can be selected when this property is set to true.

FolderBrowserDialog

The FolderBrowserDialog is used for selecting a directory and optionally creating new directories. It can be set to begin display at various places in a system. Listing 7.7 shows how to use the FolderBrowserDialog.

Listing 7.7 The FolderBrowserDialog Class (FolderDlg.cs)

 private void btnFolder_Click(object sender, System.EventArgs e) {   folderBrowserDialog1.ShowDialog();   MessageBox.Show(folderBrowserDialog1.SelectedPath); } 

The routine in Listing 7.7 displays the FolderBrowserDialog with the ShowDialog method. The SelectedPath property returns the path that the user selected. If no path was selected, the path for the RootFolder property will be returned. The FolderBrowserDialog exposes properties that can be altered in the Object Inspector (see Table 7.4).

Table 7.4. FolderBrowserDialog Class Properties

NAME	DESCRIPTION
Description	Displays a customized message above the folders.
RootFolder	Specifies the folder where the directory tree will begin. This is a member of the Environment.SpecialFolder enum.
SelectedPath	Contains the path the user selected.
ShowNewFolderButton	Determines whether the New Folder button appears. Setting this property to false will hide the New Folder button.

FontDialog

The FontDialog displays common fonts, the same way that a word processor or any text editing application does. Listing 7.8 shows how to use this component.

Listing 7.8 The FontDialog Class (FontDlg.cs)

 private void btnFont_Click(object sender, System.EventArgs e) {   fontDialog1.ShowDialog();   MessageBox.Show(fontDialog1.Font.ToString()); } 

Listing 7.8 shows how to start a FontDialog. After a font has been selected, a Font object can be obtained from the Font property. Table 7.5 describes the FontDialog properties that can be set or read from. These properties can be set in the Object Inspector.

Table 7.5. FontDialog Class Properties

PROPERTY	DESCRIPTION
AllowScriptChange	Allows changing the character set of the font.
AllowSimulations	Allows GDI+ font simulations.
AllowVectorFonts	Allows selection of vector fonts.
AllowVerticalFonts	Allows selection of vertical fonts.
Color	Returns the color selected by the user.
FixedPitchOnly	Allows selection of fixed pitch fonts.
Font	Returns the System.Drawing.Font object selected by the user.
FontMustExist	Sets whether to return an error when a selected font doesn't exist.
MaxSize	Maximum font size that can be selected.
MinSize	Minimum font size that can be selected.
ScriptsOnly	Whether script fonts and not fixed fonts can be selected.
ShowApply	Controls display of the Apply button.
ShowColor	Determines whether the user should be given a color choice.
ShowEffects	Controls whether to show special effects, like underline and strikeout.
ShowHelp	Controls display of the Help button.

OpenFileDialog

An OpenFileDialog lets a user navigate to and open files. Listing 7.9 shows how to use the OpenFileDialog.

Listing 7.9 The OpenFileDialog Class (OpenFileDlg.cs)

 private void btnOpen_Click(object sender, System.EventArgs e) {   openFileDialog1.ShowDialog();   MessageBox.Show(openFileDialog1.FileName); } 

The code in Listing 7.9 uses the FileName property to extract the name of a single selected file from the OpenFileDialog. If the MultiSelect property of the OpenFileDialog is set to true, multiple files can be obtained by reading the FileNames property, which is an array of strings with the name of each file the user selected. Table 7.6 shows the properties of the OpenFileDialog that can be set in the Object Inspector.

Table 7.6. OpenFileDialog Class Properties

PROPERTY	DESCRIPTION
AddExtension	Can add extension automatically to filename.
CheckFileExists	Checks whether a selected file exists.
CheckPathExists	Checks whether the path of a selected file exists.
DefaultExt	Default file extension.
DereferenceLinks	Determines whether shortcut links are dereferenced.
FileName	Name of single file selected.
Filter	Sets the type of files to filter. Specified as "bmp files (*.bmp)|*.bmp|All files (*.*)|*.*" for bitmap files (replace extension as needed).
FilterIndex	Index of selected file filter.
InitialDirectory	Directory to begin displaying files.
MultiSelect	Determines whether multiple files can be selected.
ReadOnlyChecked	Sets the read-only check box.
RestoreDirectory	Determines whether current directory will be restored.
ShowHelp	Controls display of the Help button.
ShowReadOnly	Controls display of the read-only check box.
Title	Title bar display text.
ValidateNames	Determines whether selected filenames should be checked for invalid characters.

SaveFileDialog

The SaveFileDialog enables users to save a file. Listing 7.10 shows how to use this dialog.

Listing 7.10 The SaveFileDialog Class (SaveFileDlg.cs)

 private void btnSave_Click(object sender, System.EventArgs e) {   saveFileDialog1.ShowDialog();   MessageBox.Show(saveFileDialog1.FileName); } 

Listing 7.10 shows how to implement a SaveFileDialog. It retrieves the name that the file was saved as by reading the FileName property. Table 7.7 shows the SaveFileDialog properties that can be set in the Object Inspector.

Table 7.7. SaveFileDialog Class Properties

PROPERTY	DESCRIPTION
AddExtension	Can add extension automatically to filename.
CheckFileExists	Checks whether a selected file exists.
CheckPathExists	Checks whether the path of a selected file exists.
CreatePrompt	Determines whether user should be notified before a file is created.
DefaultExt	Default file extension.
DereferenceLinks	Determines whether shortcut links are dereferenced.
FileName	Name of file selected.
Filter	Sets the type of files to filter. Specified as "bmp files (*.bmp)|*.bmp|All files (*.*)|*.*", for bitmap files (replace extension as needed).
FilterIndex	Index of selected file filter.
OverwritePrompt	Determines whether user should be notified before overwriting an existing file.
InitialDirectory	Directory to begin displaying files.
RestoreDirectory	Determines whether current directory will be restored.
ShowHelp	Controls display of the Help button.
Title	Title bar display text.
ValidateNames	Determines whether selected filenames should be checked for invalid characters.

PageSetupDialog

The PageSetupDialog has options for configuring page layout and printer settings. Listing 7.11 shows how to use it.

Listing 7.11 The PageSetupDialog Class (PageSetupDlg.cs)

 private void btnPageSetup_Click(object sender, System.EventArgs e) {   pageSetupDialog1.Document = new PrintDocument();   pageSetupDialog1.ShowDialog();   string settings =     pageSetupDialog1.PageSettings.ToString() +     "\n\n" +     pageSetupDialog1.PrinterSettings.ToString();   MessageBox.Show(settings); } 

In Listing 7.11, the Document property of the PageSetupDialog is set to a default instance of the PrintDocument class. This is the preferred method of initializing the PageSetupDialog. Whatever PrintDocument object you pass to the Document property can be customized as needed. Table 7.8 shows which properties of the Object Inspector can be set to customize the PageSetupDialog. Remember to add a using declaration for System.Drawing.Printing, the namespace for PrintDocument, to the top of the file. Otherwise, you'll need to fully qualify the type as System.Drawing.Printing.PrintDocument.

Table 7.8. PageSetupDialog Class Properties

PROPERTY	DESCRIPTION
AllowMargins	Determines whether user can edit margins.
AllowOrientation	Determines whether user can select between portrait and landscape layout.
AllowPaper	Determines whether user can change paper size.
AllowPrinter	Controls display of the Printer button.
Document	PrintDocument object used to set or return printer settings.
MinMargins	Minimum margins that user can set.
ShowHelp	Controls display of the Help button.
ShowNetwork	Controls display of the Network button.

PrintPreviewDialog

The PrintPreviewDialog enables a user to view a preview of a page as it would look if printed. Listing 7.12 shows how to use the PrintPreviewDialog.

Listing 7.12 The PrintPreviewDialog Class (PrintPreviewDlg.cs)

 private void btnPrint_Click(object sender, System.EventArgs e) {   PrintDocument myPrintDoc = new PrintDocument();   myPrintDoc.PrintPage += new PrintPageEventHandler(PagePrinter);   printPreviewDialog1.Document = myPrintDoc;   printPreviewDialog1.ShowDialog(); } private void PagePrinter(object sender, PrintPageEventArgs ev) {   int x = ev.MarginBounds.Width/2;   int y = ev.MarginBounds.Height/2;   ev.Graphics.DrawString(     "Welcome to C#Builder Kick Start",     Font, Brushes.Black,     x, y, new StringFormat());   ev.HasMorePages = false; } 

The PrintPreviewDialog in Listing 7.12 is set with a PrintDocument object and then displayed, similar to the PageSetupDialog. The difference this time is that the PrintDocument object was actually initialized with more than default values. If you set the PrintPage event of the PrintDocument object with a delegate that references the PagePrinter method as its parameter, the code has full control over what is displayed in the PrintPreviewDialog.

Everything used in the PagePrinter routine uses some property of the PrintPageEventArgs parameter. Because the routine centers a message on the screen, it obtains the Height and Width properties of the MarginBounds property of the PrintPageEventArgs. Dividing the Height and Width properties of the MarginBounds by two gets the center point on the screen. In the DrawString method, we specify the string, the inherited form's Font property, the Black brush from the Brushes enum, the x and y coordinates of where to write the string, and a default StringFormat object. As long as there are pages in a document to print, HasMorePages would be set to true. However, this routine just wants to render a single page, so it sets HasMorePages to false. Besides the Document property, shown in Listing 7.12, the PrintPreviewDialog has a UseAntiAlias property, which helps to smooth font output on some printers.

PrintDialog

The PrintDialog enables a user to print a document. Listing 7.13 shows how to use the PrintDialog.

Listing 7.13 The PrintDialog Class (PrintDlg.cs)

 private void btnPrint_Click(object sender, System.EventArgs e) {    printDialog1.Document = new PrintDocument();    printDialog1.ShowDialog(); } 

To make the PrintDialog work, you must set its Document property with a new PrintDocument object, as shown in Listing 7.13. See Listing 7.12 for how to add an event handler to the PrintDocument that controls page printing.