PMGuide - File Dialog Controls

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Presentation Manager Programming Guide and Reference

How to Use this Book Device Functions Direct Manipulation Functions Dynamic Data Formatting Functions Hooks and Procedures Profile Functions Spooler Functions Window Functions Message Processing Data Types Errors Atom Tables Button Controls Clipboards Combination Box Container Controls Control Windows Cursors Dialog Windows Direct Manipulation Drawing in Windows Dynamic Data Exchange Entry-Field Controls File Dialog Controls Font Dialog Controls Frame Windows Hooks Initialization Files Keyboard Accelerators List-Box Controls Menus Messages and Message Queues Multiple-Line Entry Field Controls Mouse and Keyboard Input Mouse Pointers and Icons Notebook Controls Painting and Drawing Presentation Parameters Resource Files Scroll-Bar Controls Slider Controls Spin Button Controls Static Controls Title-Bar Controls Value Set Controls Windows Window Classes Window Procedures Window Timers Appendices Notices Glossary

File dialog controls provide basic functions that enable users to do the following:

• Display and select from a list of drives, directories, and files
• Enter a file name directly
• Filter the file names before they are displayed
• Display active network connections
• Specify .TYPE EA extended attributes
• Interact with a single-selection or multiple-selection file dialog
• Interact with a modal or modeless file dialog

These basic functions can be extended to meet the requirements of PM applications.

About File Dialog Controls

The file dialog control enables you to implement Open or SaveAs dialogs.

Customizing the File Dialog

You can customize the File Dialog control by using the standard controls and adding any of your own design. Specify a standard control by including the control name, ID, and style in the dialog.

Using File Dialog Controls

This section describes how to create:

• A file dialog
• An Open dialog
• A SaveAs dialog

Creating a File Dialog

To present a file dialog to users, your application must do the following:

1. Allocate storage for a FILEDLG data structure and set all fields to NULL.
2. Initialize the fields in the FILEDLG data structure.

The application must do the following:

1. Set the cbSize field to the size of the data structure.
2. Set the fl field to indicate the type of dialog. You must set the FDS_OPEN_DIALOG or FDS_SAVEAS_DIALOG flags.

The application can set the following:

1. An application-specific title. Pass the pointer to a null-terminated string in the pszTitle field.
2. An application-specific text for the OK push button. Pass the pointer to a null-terminated string in the pszOKButton field.
3. A custom dialog procedure to provide application-specific function. Pass the pointer to a window procedure in the pfnDlgProc field.
4. Set other FDS_* flags in the fl field to customize the dialog style.
5. Pass the initial position of the dialog in the x and y fields.
6. Initialize the FILEDLG data structure with any values that users should see when they invoke the dialog for the first time. For example, you can:
7. Pass the name of the first drive from which file information will be displayed in the pszIDrive field.
8. If you want to limit user selections, pass a list of drives from which the user can choose in the papszIDriveList field. Otherwise, the system defaults to showing all available drives.
9. Pass the name of an extended-attribute filter to be used to filter file information in the pszIType field.
10. Pass a list of extended attributes in the papszITypeList field. By selecting from this list, users can filter file information.
11. Pass the name of the initial file to be used by the dialog in the szFullFile field. This can be a file name or a string filter, such as *.dat, to filter the initial file information. This field can be fully qualified to select the initial drive and directory.
12. Invoke the file dialog. Call WinFileDlg and pass the dialog's owner window handle and a pointer to the initialized FILEDLG data structure.
13. Verify the return value from WinFileDlg. If it is successful, the application can create the file dialog (either Open or SaveAs) by using the file name or file names returned from the dialog.

Creating an Open Dialog

When the Open dialog is invoked, the fields in the dialog box are updated with the fields passed in the FILEDLG data structure. The values passed in the szFullFile field of the data structure are displayed in the File Name field, the Directory list box, and the Drive field. The value passed in the pszIType field is displayed in the Type field.

Creating a SaveAs Dialog

The SaveAs dialog is identical to the Open dialog with these exceptions:

• By default, the file names in the file list box are grayed and cannot be selected, although the list box can be scrolled.
• When the user clicks on the OK push button or presses the Enter key, the file name in the File Name field is passed to the application, and the application saves, rather than opens, the file.
• The titles of the file name, filter, and dialog are SaveAs rather than Open.

Graphical User Interface Support for File Dialog Controls

This section provides information about the file dialog user interface.

Name Field

The File Name field is a single-line entry (SLE) field used to display the name of a file that was selected from the file list box or entered directly by the user. As the user types, the file or files matching the user entry are scrolled into view in the file list box. The first file name that most closely matches the file name typed by the user is placed at the top of the list box. When the user types a character that causes a mismatch, the file at the top of the list is displayed. When the user presses the Enter key, the dialog returns the selected file name to the application. The application then initiates the default action of opening the file. When a file name is not valid, such as when the file does not exist, the application displays an error message. The File Name field displays the currently selected file name or the current string filter. When a filter is specified in the szFullFile field of the FILEDLG data structure, the string filter is displayed without the path information. The string filter remains in the field until a file is selected or the user types over the data in the field. When a file name is not specified, the File Name field is blank.

File List Box

The File list box is a single- or multiple-selection list box that is scrollable both horizontally and vertically. It contains all the files that meet the filter criteria, sorted by name. When the file dialog is a single-selection dialog, the selected file name is placed in the File Name field. When the file dialog is a multiple-selection dialog, the topmost selected file name is placed in the File Name field. When the user double-clicks on a file name, the dialog exits and returns the selected file or files to the application for opening.

Directory List Box

The Directory list box is a single-selection list box that is scrollable both horizontally and vertically. The Directory list box displays the path in the szFullFile field of the FILEDLG data structure as a list of each parent subdirectory. Any subdirectories of the selected directory also are displayed. Each directory level is indented to show the path, and the current working directory level is indicated by an arrow. The top entry is always the root directory, with the drive specification preceding it. When the szFullFile field is NULL, the current path of the current drive is displayed. The user selects a new subdirectory by double-clicking on the subdirectory name. This action updates the Directory list box.

Drive Field

The Drive field contains a drop-down list of the logical drives. This field cannot be edited by the user. The Drive field displays the value passed in the papszIDriveList field of the FILEDLG data structure. If the application does not specify a drive list, all drives currently available on the system are displayed. When the drop-down list is displayed, the current drive is highlighted. When the user selects a drive, the display is refreshed. When either the user-specified drive or the default drive has a volume label, the volume label is displayed also. Users can access networked files by associating logical disks with remote servers, or they can enter the name and ID of the server in the File Name field. When the server name entered is not found in the Drive drop-down list, it is added to the list and displayed in the Drive field.

Type Field

The Type field contains a drop-down list of extended-attribute filters. The Type field displays the value passed in the pszIType field of the FILEDLG data structure. The current setting is highlighted when the drop-down list is displayed. When a type filter is not specified by the application, <All Files> is displayed and no extended-attribute type filtering is used with the initial display. All files affected by the string filter and the extended-attribute type filter criteria are displayed, based on how the filters are to be used. The default is that all file names meeting the intersection of the two filters are shown. When users change the value in the Type field, the File list box is updated to display a list of files that meet the new type filter criteria. Files that meet both the string filter and extended-attribute type filter are displayed.

Standard Push Button and Default Action

The OK push button initiates the default action. When a subdirectory is selected, the File Name field is empty. When the user clicks on the OK push button or presses the Enter key, the subdirectory is opened and the displayed values in the File list box and the Directory list box are refreshed. When a file name is selected, selection of subdirectories is canceled and the File Name field is updated with the name of the selected file. When the user clicks on the OK push button or presses the Enter key, the file displayed in the File Name field is returned to the application for opening.

Subclassing the Default File Dialog Procedure

The name of the dialog procedure is assigned to the pfnDlgProc field of the FILEDLG data structure.