A rather tedious, but quite common, task in nearly every application is to prompt the user for file names, font names and sizes, or colors to be used by the application. Designing your own dialog boxes for these Purposes would be a hassle, not to mention that your applications wouldn’t have the same look and feel of all Windows applications. In fact, all Windows applications use some standard dialog boxes for common operations, such as selecting a font or opening a file.These dialog boxes are built into the operating system and any application can use them.
If you ever want to display a File Open or Font dialog box, don’t design it-it already exists. To use it, just place the Common Dialogs control on your Form and call the appropriate method. For instance, the ShowOpen method invokes the File Open dialog box; the ShowColor method invokes the Color dialog box.
Using the Common Dialogs Control
The Common Dialogs control is a peculiar one. It provides it:; services to the application, but it doesn’t need to be displayed on the Parol at run time (similar to the TImer control). The Common Dialogs control provides the following built-in Windows dialog’ boxes:
• Open The File Open common dialog box lets user section file to open.
• Save As The File Save common dialog box lets users select or specify a filename in which the current document will be saved.
• Color The Color dialog box lets users select colors or specify cUstom colors.
• Font The Font common dialog box lets users select a typeface and style to be applied to the current text selection.
• Print The Print common dialog box lets users select and set up a printer.
• Help The Help common dialog box displays Help topics.
You’ll see many examples of the Common Dialogs control in the following chapters. This section explores the basic properties and methods of the control, especially the Flags property, which modifies the default behavior of each common dialog box.
To call upon the services of the Common Dialogs control, you must first place an instance of the control on the Form. After the control is placed on the Form, you can’t adjust its size because the Common Dialogs control remains hidden at .runtime; You can, however, set several properties to adjust the appearance of any of the dialog boxes it displays, such as the initial font in the Font dialog box or a default file name in the Open or Save As dialog boxes.
To display a common dialog box from ‘within your code, you must assign the proper value to the control’s Action property, The Action property acts as ? method: after you assign a value to it, the corresponding common dialog box is displayed. An alternate (and preferred) way of invoking the same dialog boxes is to use the ‘~ore descriptive methods instead Of numeric values, The methods of the control and their equivalent Action property values are listed in Table.
After you assign a value to the Action property or call the equivalent method, the corresponding dialog box appears ~~ and execution of the program is suspended until the dialog box is closed, Using the Open and the’Save dialog boxes, for example, the user can traverse the entire structure of his or her hard disk and locate the desired filename. Where the user clicks the Open or Save button, the program control is returned to the application, which can read the name of the file selected by the user (FileName property) and use it to open the file or to store the current document there.
Here is the sequence of statements used to invoke the File Open dialog box and retrieve the selected filename:
CommonDialogl.ShowOpen
fileName = CommonDialogl.FileName
The variable fileName is the full path name of the file selected by the user. You can also set the FileName property to a filename that’s displayed when the common dialog box is first opened. This allows the user to click the Open button to open the preselected file or choose another file.
Similarly, you can invoke the Color dialog box and read the value of the selected color with the following statements:
The dialog box sets the FileName and Color properties, and your application simply reads them.
The Common Properties
Each common dialog box has a number of properties that you can adjust in appearance and/ or function. Most of the properties are optional, and they should be set before you open the dialog box. Some of the properties common to nearly all the common dialog boxes are discussed next. Afterwards, we’ll look at the properties that are unique to each common dialog box.
Cancel Error
Each dialog box has a Cancel button, which should signal to your application the user’s intention to cancel the current operation. The Cancel action can be reported to your application by means ‘of an error. To specify whether an error is generated. when the user clicks the Cancel button, set the CancelError property to True. If you don’t want to handle this situation through an error handler, set the CancelError property to False and. examine the value returned by the Common Dialogs control (such as the FileName or Color property). If the user has canceled the operation, this. alue will be an empty string.
If you set the CancelError property to True, you must also provide an error handler that will detect this condition and act accordingly. All common dialog boxes return the same error, which is error number 32755 (constant cdlCancel). Your error handler must examine the error number, and if it’s 32755, cancel the operation. You can open the Open common dialog box and detect whether the
user has canceled the operation with the following code.
DialogTitle
The second common property is the DialogTitle property, which returns or sets the string displayed in the title bar of the dialog box. The default title on the dialog box’s title bar is the name of the dialog box (e.g., Open; Save, Color).
Flags
A third property of all the common dialog boxes is Flags, which you use to adjust the function of each common dialog box. The values of this property will vary depending on the specific common dialog.box being opened. These values are discussed in the following sections devoted to each type of dialog box.
Min and Max
These properties apply to the Print and Font common dialog boxes. In the Print dialog box, they determine the minimum and maximum allowable values for the print range that the user can specify. In the Font common dialog box, the properties determine the minimum and maximum size displayed in the Size list (the range of font sizes from which the user will be allowed to select).
VB6 at Work: The CD Box Project
The Flags property. of the. Common Dialogs control may take on a large number of values, and remembering them is out of the question, When programming the Common Dialogs control, you should have a reference at hand.
In this chapter’S folder on the CD, you’ll find the CD~x application. You can use it to experiment with the various settings of the common dialog boxes; see what each property does and determine which flag combinations you might need for a specific application. Or you can create an executable, run it (outside the VISual Basic IDE) to get the settings of a control right, and then use the constants in’ your code.
The CD Box application is based on a Tab control with one tab per common dialog box. The tab for the Color ‘common dialog box, shown. contains a list of all the flags you can set in the Color common dialog box as well as the value of the Color property. Each tab will be explained as we examine each common dialog box-in the following sections.
The Color Common Dialog Box
The Color common dialog box, shown, is one of the simplest dialog boxes. It has a single property, Color, which returns the color selected by the user or sets the initially selected color when the user opens the dialog box.
Before opening the Color dialog box with the ShowColor method, you can set a ‘number of flags through its Flags property, whose values are shown in Table. To combine multiple flags, add their values or use the OR operator.
The Color tab of the CD Box application lets you set (or reset) the various flags and the value of the color that’s initially selected in the Color dialog box. You can specify this value in decimal or hexadecimal format (the latter is more common). The Show Dialog Box button displays the Color common dialog box. When you select a color and then exit the Color dialog box, the Picture Box control at the bottom is filled with the selected color. In addition, the color’s value is displayed in decimal and hexadecimal format in the two Textbox controls under the Color Value heading.
The Font Common Dialog Box
The Font common dialog box, shown, lets the user review and select a font and its size and style. To open the Font dialog box, set the Action property to 4 or invoke the ShowFont method of the Common Dialogs control.
After the user selects a font, its size and style, and possibly some special effects . (color or the underline attribute), and clicks the OK button, the Common Dialogs control returns the attributes of the selected font through the following properties:
• . Color Returns the font’s selected color; to allow the user to set this property, you must first set the Flags property to cdlCFEffects.
• FontBold It’s True if the bold attribute is set
• FontItalic It’s True if the italic attribute is set
• FontStrikethru It’s True,if the strike through attribute is set; to allow the user to set this property, you must first set the Flags property to cdlCFEffects.
• FontUnderline It’s True if the underline attribute is set; to allow the user to this property, you must first set the Flags property to cdlCFEffects
• FontName Returns the selected font’s name
• FontSize Returns the selected font’s size.
When the Font common dialog box is closed, the values of the corresponding checkboxes on the tab are updated to match the settings specified by the user in the dialog box. You can also set the value of any of the previous properties to specify the initial settings of the Font dialog box before clicking the Show Dialog Box button.
You may have noticed that some properties require the cdlCFEffects flag to be set. This flag displays a few additional settings that are considered special effects, such as strike through, underline, and the color of the font.
Using the Flags Property with the Font Dialog Box
The CD Box Form shown in Figure 8.6 provides checkboxes for every type of flag you can set with the Font common dialog box. The Flags property of the Font common dialog box can take on any of the values shown in Table.
When the Font common dialog box is first opened, the font name, size, and attributes of the font selected the last time the same dialog box was opened are displayed .
If you want these fields to be empty when the user opens this dialog box, set the Flags property to the following value:
CommonDialogl.Flags – cdlCFNoFaceSel OR cdlCFNosizeSel OR _
cdlCFNoStyleSel
This line displays the Font dialog box without an initial font, size, or style selection.
The FileOpen and FileSave Common Dialog Boxes
FileOpen and FileSave are the two most widely used common dialog boxes. Nearly every application prompts the user for a filename. Windows 95 . provides two highly customizable common dialog boxes for this purpose. The ‘two dialog boxes are nearly identical and most of their properties all common, so let’s look at the properties of both.
When a File common dialog box is opened, it rarely displays all the files in any given folder. Usually the ‘number of files displayed is limited to the ones that the application recognizes so that users can easily spot the file they want. The Filter property determines which files appear in the File Open or File Save dialog box.
It’s also standard for the Windows 95 interface not to display the extensions of files (although Windows distinguishes files using invisible extensions.which is why I’ve turned on the option to display rile extensions for . The Save. As Type ComboBox contains the various file types recognized by the application. The various file types can be described ill plain English with long descriptive names and without their extensions,
The extension of the default fife type for the application is’described by the DefaultExt property, and the list of the file types displayed in the Save As Type box is described by the Filter property. Both the DefaultExt and the Filter properties are available in the control’s Properties window at design time. At rum you must set them manually from within your code.
• DefaultExt Sets the default extension of the dialog box. Use this property to specify a default filename extension. such as TXT or DOC, so that when a file with no extension is saved, the extension specified by this property is automatically appended to the filename.
• Filter The Filter property is used 0 specify the type(s) of files displayed in the dialog box’s file list box. ‘Io display text files only, set the Filter property to “Text file ,txt”. The pipe symbol separates the description of the files (what the user sees) from the actual extension (how the operating system distinguishes the various file types).
Don’t include spaces before or after pipe symbol because these spaces will be displayed with the description and Filter values. In the FileOpen diaIog box of an image processing application, you’ll probably provide options for each image file type, as well as an option for all images:
The FileOpen dialog box has four options which determine what appears in the ( ‘Save As) Type box.
.• Filter lndex When you specify more than one filter for a dialog box, the filter specified first in the Filter property becomes the default. If you want to use a ” Filter value other than the first one, use the Filterlndex property to determine which filter will be displayed as the default when the Open or Save dialog box is opened. The index of the first filter is 1 and there’s no reason to ever set this property to 1. If you want to use the Filter property value of~previous example and set the Filter index property to 2, the Open dialog box will display GIF files by default.
• File Title This property returns the name of the file to be opened or saved. The FileTitle property doesn’t include the path name, If you set this.,property before opening ‘the dialog box, the specified filename will appear in the File Name field.
• InitDir This property sets the initial directory (folder) in which files are displayed the first time the Open and Save dialog boxes are opened. Use this property to display the files of the application’s folder or to specify folder in which the application will store its files by default. If you don’t specify an initial folder, it will default to the last folder where the dialog box opened or saved a file. It’s also customary to set the initial folder to the application’s path, with the following statement:
CommonDialog1.InitDir = App.Path
• MaxFileSize This property returns or sets the maximum size of the filename opened using the Common Dialogs control. Its default value is 256, which is plenty for any reasonable filename. Normally you won’t use this property unless you allow the user to select multiple files in that case, you must allocate enough memory to store the names of the selected files. See the descriptions of the flags of this common dialog box to find out how you can allow multiple file selection in the Open and Save common dialog boxes.
To specify that the user must select an existing file only (in other words, the user won’t be allowed to a nonexistent filename in the File Name field), set the Flags to cdlCFNFileMustExist, with the following statement:
Which value sets certain bits in the Flags property; when multiple flags are combined with the OR operator, all corresponding bits are set. To test for a Flag value, you must use AND with the flag’s corresponding value or constant. To find out the status of the read-only checkbox, use a structure such as the following:
Multiple File Selection
The first Flag constant allows for the selection of multiple files on the dialog box. This option isn’t very common, but it can come in handy in situations when you want to process a number of files enmasse. You can let the user select many files and then process them one at a time Or, you ‘may wish to prompt the user to select multiple files to be moved or copied.
To allow the user to select multiple files on the File Open common dialog control, specify the cdlOFNAllowMultiselect flag as follows:
This flag allows the user to select multiple files with the mouse by holding down the Shift or Ctrl key.
The names of the selected files are reported by the property FileName, but unlike single file selections, you can’t use this property to open the files directly. The File- Name property contains the path names of all selected files and in order to use them, you mus.t first extract each one. Extracting the filenames from the FileName property is straightforward string manipulation code, but there’s a small glitch you have to deal with ..
With the simple (Windows 3.11) File Open common dialog box, the filenames are separated by a space. All you have to do is to scan the property value for spaces and extract the names of the selected files. If you specify the cdlOFNExplorer flag, which:opens a windows 98/NT Explorer-style dialog box, the filenames are delimited by the null character (Chr(O» because long paths and filenames may contain spaces too (this excludes the use of the space as a delimiter, of course). So, the code for extracting the names of the selected files from the FileName property is different, depending on the type of File Open common dialog box.
VB6 at Work: The MFiles Project
In this chapter’s folder on the CD, you’ll find the MFiles project, which demonstrates the use of the cdlOFNAllowMultiselect fl••g of the Open common dialog box. The application’s Form is shown. Besides the controls xoee on .the Form at runtime, there is also an instance of the Common Dialogs control that’s invisible at runtime. The Command button at the bottom of the Form opens a File Open dialog box, ‘where you can select multiple files. After closing the dialog box by clicking the OK or Open button (depending on the version of the dialog box you open), the application displays the names of the selected files in the ListBox control. Notice that only the names of the files are displayed. The path, which is common [or all files, is displayed on a Label control near the top of the Form.
The code behind the Select Multiple Files button is shown next.
The code isn’t complicated, but it’s quite lengthy compared to the code that retrieves and uses a single filename. Before opening the dialog box, the code Sets the control’s MaxFileSize property to a large value to make sure the FileName property will hold all the selected files (you may want to increase this value, depending on the nature of the application). After the user selects the files and , closes the dialog box, the code extracts the name of the path; it’s the first segment of the FileName property up to the first instance of the space delimiter. The path is displayed on a Label control and applies to all selected files. The cdlOFNA/low- Multiselect flag allows the selection of multiple files in the same folder, but you can’t select multiple files in more than one folder. Each time you switch to another folder, the current selection is cleared.
Then, the program scans the FileName property searching for spaces. Each time ‘a space is found, it extracts another filename by isolating the characters to the left of the delimiter and removes it from the FileName string. The last filename isn’t delimited by the space character. After all other filenames have been extracted, the FileNames string contains the name of the last selected file.
Notice how the code.uses the FileTitle property: if the FileTitle property isn’t empty, then the user has selected a single file, whose name is displayed on the ListBox control, and the program exits,
VB6 at Work: The MFiles95 Project
The MFiles95 project, shown, opens an Explorer-style dialog box that .displays long filenames, some of which may contain spaces. The code of the Select Multiple Files button is identical to the listing in Code 8.2, but uses the delimiter Chr(O) instead of the space character, You can open the project in the Visual Basic editor and examine its code.
The Print Common Dialog Box
The Print common dialog box enables users to select a printer, set certain properties of the printout (number of copies, pages to be printed, and so on), and set up a specific printer.
4’0 open the Print dialog box. set the Action property of the Common Dialogs. control to 5 or invoke the ShowPrinter method of the Common Dialogs control. After the user selects a printer and clicks OK, the Common Dialogs control returns the printer’s device context and the attributes of the desired printout to the calling program through the following properties:
• Copies Specifies the number of copies to print
• FromPage Specifies the pa~e on which to start printing
. .
• ToPage Specifies the page on which to stop printing
• hDC Specifies the device context for the selected printer. TheRichTextbox control’s Print net hod, for example, requires an hDC argument to tell it where to send its printout.
When the Print common dialog box is closed, the application reads the values of these properties to determine the settings specified by the user.
You can also set the value of any of the previous properties before calling the Show Printer method so that initial settings will appear when the dialog box is first opened. The Flags property of the Pr common dialog box enables you to specify these initial things. These values are shown in Table.
To experiment with the various settings of the Print common dialog box. you can use the Print tab of the CD Box application, shown.
The Help Common Dialog Box
The Help common dialog box is as simple to use as the other ones, but you must first prepare your Help files. I won’t discuss how to build Help files in this book; you can purchase many specialized tools for this task. If you don’t have your own Help files, you can use ones that come with an application like Visual Basic. Visual Basic’s Help file is called VB6. You don’t have to specify an extension or a path; WinHelp knows where the Help files are located.
The,basic properties of the Help common dialog box are the following:
• HelpFile Specifies the filename of a Windows Help file that will be used to display online Help. This file must be supplied by your application, but for the purposes of learning the Help common dialog box, you can use any Help files already on your hard drive.
• HelpCommand Sets or returns the type of Help requested. The values of this property are listed in Table 8.6. The constants listed in the table look like flags, but they are actually parameters for the HelpCommand property. You can combine multiple commands by using the OR operator or by adding them together.
• HelpContextID Sets or returns a context number for an object. This ID is a number that tells WinHelp where in the Help file it will find the pages describing the specific topic. If you’ve created a Windows Help file for your application, Visual Basic searches the Help file for the topic identified by the current context ID when a user opens the Help common dialog box (by pressing the F1 key, for instance).
• HelpKey Sets on returns the keyword that identifies the requested Help topic. To use this property, you must also set the HelpCommand property to cdIHelpKey.
You can use the CD Box application to experiment with some of the Windows Help files. They are all located in the Help folder under the Windows folder, and you need to specify only their name in the Help File box. If you set the cdl- Helplndex flag, the Index tab of the Help file is opened automatically. Or you can check the cdlHelpKey flag and supply. a key such as “text” in the Help Key box. The Help dialog box opens the specified Help file, locates the topic, and takes you there.
