Using the FileDialog Objects

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Paul Cornell
Microsoft Corporation

April 2001

Applies to:
   Microsoft® Office XP

Summary: Describes how to manipulate file dialog boxes by using the FileDialog object model in the Microsoft Office 10.0 Object Library. (5 printed pages)

Contents

Introduction File Dialog Box User Interface Elements Exploring the FileDialog Object Model Example: Concatenating Selected Files Conclusion

Introduction

File dialog boxes in Microsoft® Office give users and applications the ability to manipulate files and folders. Although the Open and Save As file dialog boxes existed in Microsoft Office 2000, developers didn't have much programmatic access to them. Prior to Office XP, in order to program and distribute solutions that rely on file dialog boxes, developers had to incorporate the Common Dialog ActiveX® control available in separate products such as Microsoft Visual Basic® or Microsoft Visual FoxPro®, or use the Microsoft Windows® application programming interface (API).

In Office XP, however, the Open and Save As file dialog boxes are available directly within the Office 10.0 object library, as well as two additional file dialog boxes (File Picker and Folder Picker) for selecting files or a folder. These new file dialog boxes allow developers to get lists of files or a folder path from users without having to build a custom user interface. The new FileDialog object model in Office XP also allows programmatic access to file dialog box user interface items such as:

• Setting the title text for the file dialog box
• Setting the "action button" text (such as Open, Save, and so on)
• Setting the allowable file types (such as *.doc, *.xls, and so on).
• Setting the initial file or folder selection
• Setting the initial view (Large Icons view, Thumbnails view, and so on)
• Allowing single or multiple file selections

To better understand how to programmatically access file dialog boxes, let's explore the various user interface elements of the file dialog boxes and how these elements correspond to the FileDialog object model.

File Dialog Box User Interface Elements

To better understand how file dialog boxes can be manipulated, Figure 1 provides a graphical representation of the user interface elements of a file dialog box, and Table 2 provides a description of some of these elements along with their corresponding FileDialog object members.

Figure 1. File dialog box user interface elements

Table 2. File dialog box element descriptions and FileDialog object members

Now let's explore the FileDialog object model for accessing file dialog boxes.

Exploring the FileDialog Object Model

To understand the object model for accessing file dialog boxes, Figure 2 provides a graphical representation of the collections and objects in the FileDialog object model, and Table 3 describes the purpose of each of these items in the object model.

Figure 2. The FileDialog object model

Table 3. Description of objects/collections in the FileDialog object model

Now that you know the graphical elements of a file dialog box and how they relate to the FileDialog object model, let's look at an example of how to use file dialog boxes programmatically.

Example: Concatenating Selected Files

In the example, which is available for download, I demonstrate how to program the File Picker and Save As file dialog boxes to concatenate multiple Microsoft Word files into one Word file.

The custom BuildFileDialogBox function in this example allows you to customize file dialog box user interface elements, such as the title, the initial path or file name, the initial view, and the caption for the action button, by using just one line of code. This is preferable to iterating through long lists of hard-coded property settings every time you want to customize a file dialog box. For instance, for a file dialog box with the object name of dlgFileDialogBox, the following code changes the title to "Select Files," the initial path to drive C, the initial view to Thumbnail view, the action button's caption to "Get Files," and allows multiple files to be selected, all in one line of code.

Call BuildFileDialogBox(dlgFileDialogBox:=dlgFileDialogBox, _
    strCaption:="Select Files", _
    strInitialFile:="C:\", _
    msoDialogView:=MsoFileDialogViewThumbnail, _
    strButtonCaption:="Get Files", _
    blnMultipleFiles:=True)

An array of one or more custom description/file extension strings can be used to replace the default file filter settings when a file dialog box is created. Since I want to allow the user to select only Word documents in this example, I need to limit the selections in the Files of type box to display only the string "Word Documents (*.doc)". Because storing these custom strings in a spreadsheet or database is too complex for this type of solution, I pass a parameter array consisting of these custom strings to the custom BuildFilters function. This function clears any existing file filters from the file dialog box, and inserts the array of custom strings as a list of file filters in the file dialog box by using the Add method of the FileDialogFilters collection. However, if you wanted to add just a single file filter, you could use the following code:

Application.FileDialog(FileDialogType:=msoFileDialogOpen).Filters.Add _
    Description:="Word Documents (*.doc)", _
    Extensions:="*.doc"

After you display a file dialog box, you always want to check whether the user selected the "action" button (such as Open or Save), and if not, terminate any further activity for that file dialog box. The Show method returns a value of –1 if the action button is selected, and the Show method returns a value of 0 if the Cancel button is selected. So, to exit a subroutine if the Cancel button is selected, your code would look something like this:

If dlgSaveAsDialogBox.Show = 0 Then
    Exit Sub
Else
    ' Code if "action" button was clicked...
End If

The heart of the solution is in the custom ConcatenateWordFiles function. After a new Word document is created (by using a FileDialogSelectedItems collection that contains the files selected in the File Picker file dialog box), the code iterates through each of the selected Word documents. This is a convenient way to access each of the files the user has selected. The code uses the FileDialogSelectedItems collection to copy each file's contents to the Clipboard and append the contents from the Clipboard into the new Word document.

Finally, control is passed back to the FileConcatenator subroutine, where the Execute method is used in conjunction with the Save As dialog box to save the new Word document with the file name and path supplied by the user.

Conclusion

The FileDialog object model provides a convenient way to manipulate the Open, Save As, File Picker, and Folder Picker file dialog boxes without needing the Common Dialog ActiveX control or the Windows API. By using the FileDialogSelectedItems collection, you can capture lists of selected files or a folder path for further processing in custom applications. Additionally, many of the file dialog box elements (such as captions, views, starting paths, file extensions, and so on) that were not previously accessible through Office VBA code can now be customized programmatically.