3. Defining a File Open Dialog
Sometimes it's hard to
know precisely how to modify a common file dialog to make it easier to
use. Microsoft has tried for years and still isn't happy. Because you
know your users, you have a better chance of creating the perfect dialog
box — one that precisely matches the needs of your users. The new CommonOpenFileDialog class makes it easier to make the modifications your users need in a File Open dialog box. Listing 8-1 shows some of the changes you can make and how to implement them.
Example 1. Defining a File Open dialog box
private void btnOpen_Click(object sender, EventArgs e)
{
// Define the dialog box.
CommonOpenFileDialog dlgOpen = new CommonOpenFileDialog("File Open");
// Configure the File Open dialog box.
// The user must select just one file.
dlgOpen.Multiselect = false;
// Treat .LNK files as their targets.
dlgOpen.NavigateToShortcut = true;
// Select a default starting location.
dlgOpen.InitialDirectory = @"C:\Test";
// Disallow read-only files.
dlgOpen.EnsureReadOnly = false;
// Add some alternative places to find data.
ShellContainer Place = KnownFolders.DocumentsLibrary as ShellContainer;
dlgOpen.AddPlace(Place, FileDialogAddPlaceLocation.Top);
dlgOpen.AddPlace(@"C:\Test", FileDialogAddPlaceLocation.Top);
// Add selection filters.
dlgOpen.Filters.Add(new CommonFileDialogFilter("Text File", ".txt"));
dlgOpen.Filters.Add(new CommonFileDialogFilter("HTML File", ".htm,.html"));
dlgOpen.Filters.Add(new CommonFileDialogFilter("Document File", ".doc"));
// Create a test button.
CommonFileDialogButton btnHelp =
new CommonFileDialogButton("btnHelp", "&File Selection Help");
// Add an event handler for chkTest.
btnHelp.Click += new EventHandler(btnHelp_Click);
// Add a special control.
dlgOpen.Controls.Add(btnHelp);
// Show the dialog box.
CommonFileDialogResult Result = dlgOpen.ShowDialog(this.Handle);
// Check the selection results.
if (Result == CommonFileDialogResult.OK)
// Display the selected file.
MessageBox.Show("The user selected: " + dlgOpen.FileName);
else
// The user clicked Cancel.
MessageBox.Show("User clicked Cancel");
}
|
The code begins by creating the File Open dialog box, dlgOpen, using the CommonOpenFileDialog class. If you really don't want to make any changes, you can call dlgOpen.ShowDialog()
to obtain one or more file selections from the user at this point.
However, you'll generally need to perform several kinds of tasks to
optimize the File Open dialog box:
Configure the existing features.
Provide one or more custom locations to find files.
Add one or more filters to define the kinds of files the user can open.
Add one or more specialty controls.
The example doesn't begin to
cover all the configuration options at your disposal, but it does show
the options that you'll commonly change. For one thing, you'll want to
set the File Open dialog box to specifically allow or disallow multiple
file selections. When you want the user to open one file at a time, make
sure you set Multiselect to false. Many organizations use .LNK
(link) files to make it easier for users to find files without knowing
where those files are located. If this is the case in your organization,
you'll want to set NavigateToShortcut to true to ensure that the user opens the file pointed to by the link, rather than the .LNK
file itself. It's also important to set an initial directory so the
user always begins the search in a specific location. Finally, you'll
want to decide whether the user should open read-only files. Nothing's
more frustrating than to open a read-only file and later find that you
can't save the changes you made. When you set EnsureReadOnly to false and the user selects a read-only file, the user sees the dialog box shown in Figure 8-1 automatically — no extra coding required on your part.
Even with a default directory and lots of help through .LNK files, users are apt not to find what they need. Fortunately, you can add other places the user can look for files. The AddPlace() method provides two techniques to accomplish the task, as shown in Listing 8-1.
The first technique works with known locations, such as the user's
Documents folder. The second technique works with non-standard
locations, such as C:\Test. The user
sees these added locations on the left side of the File Open dialog box
along with the other standard locations, as shown in Figure 2.
Every File Open dialog box
should define standard filters the user can use to locate precisely the
file type needed, even if one of the filters must be *.* to allow for
all files. The code uses dlgOpen.Filters.Add() to add new filters to the list. Each filter entry is a CommonFileDialogFilter
object, whose constructor requires two arguments: a common name for the
file such as Text File and one or more file extensions. Notice that you
separate multiple file extensions using commas:
dlgOpen.Filters.Add(new CommonFileDialogFilter("HTML File", ".htm,.html"));
which displays both .HTM and .HTML files for the user when the user selects the HTML File filter option.
The CommonFileDialogButton() constructor requires the name of the control as the first argument because the application will send this information as the sender
variable to the control's event handlers. After you create the
variable, you can add event handlers to it. The example adds the event
handlers as part of the form's constructor, as shown in Listing 2.
As with any other event handler, you can press Tab after you type +=,
and the IDE will automatically add the proper event handler constructor
for you. Press Tab a second time and the code automatically creates an
event handler for you, like the one shown in Listing 2.
Example 2. Creating the btnHelp event handler
void btnHelp_Click(object sender, EventArgs e)
{
// Display a helpful message.
MessageBox.Show(
"Select the file type you want: text, HTML, or document." +
" Then select a file from the resulting list.");
}
|
The event handler is simple in
this case. All it does is display a help message. However, you can
create event handlers of any required complexity. After you create the
control, you add it to the File Open dialog box by calling dlgOpen.Controls.Add() with the name of the control as the argument.
The btnOpen_Click() event handler shown in Listing 1 displays the File Open dialog box next by calling dlgOpen.ShowDialog(). Notice the inclusion of this.Handle
as an argument to tie the File Open dialog box to the application. If
you don't provide this argument, the user could try to perform all kinds
of other tasks and simply leave the File Open dialog box in limbo. When
the user closes the dialog box by selecting either Open or Cancel, Result contains a CommonFileDialogResult enumeration value of either OK or Cancel.
You can test for this value as shown in the example and do something.
In this case, the example simply shows the name of the file that the
user selected or displays a message stating that the user clicked
Cancel. Figure 3 shows the File Open dialog box with all the additions made by the example.
