FolderBrowserDialog

Allows the user to select a folder from one of the Roots.

This class provides a way to prompt the user to browse, create, and eventually select a folder. Use this class when you only want to allow the user to select folders, not files. Browsing of the folders is done through a tree control. Only folders from the file system can be selected; virtual folders cannot.

Typically, after creating a new FolderBrowserDialog, you set the RootFolder to the location from which to start browsing. Optionally, you can set the SelectedPath to an absolute path of a subfolder of RootFolder that will initially be selected. You can also optionally set the Description property to provide additional instructions to the user. Finally, call the ShowDialog method to display the dialog box to the user. When the dialog box is closed and the dialog box result from ShowDialog is DialogResult.OK, the SelectedPath will be a string containing the path to the selected folder.

You can use the ShowNewFolderButton property to control if the user is able to create new folders with the New Folder button.

FolderBrowserDialog is a modal dialog box; therefore, when shown, it blocks the rest of the application until the user has chosen a folder. When a dialog box is displayed modally, no input (keyboard or mouse click) can occur except to objects on the dialog box. The program must hide or close the dialog box (usually in response to some user action) before input to the calling program can occur.

For a full list of properties, methods and events see the API documentation.

Features

Multiple Roots

The FolderBrowserDialog component allows for setting multiple directory roots to navigate and select a file.

FolderBrowserDialog showing multiple root directories for navigation

Directories must have the appropriate read permissions to be discoverable by the Wisej.NET application.

The FolderBrowserDialog.SelectedPath property returns the path selected by the user, which is the virtual path relative to the root. To retrieve the physical path on the server use FileBrowserDialog.MapPath().

Help

The FolderBrowserDialog component has an optional "?" (Help) tool that allows you to process and display information to help users navigate the control.

FolderBrowserDialog showing help button and navigation interface

How To

Customize the Appearance

The FolderBrowserDialog component can be customized by applying appearances to each individual control within the dialog. This includes the tree view, buttons, and bottom panel.

To customize these controls, create a new class that inherits from FolderBrowserDialogUI, add the custom FolderBrowserDialog constructor, and modify the controls within it:

C#

public partial class CustomFolderBrowserDialogUI : FolderBrowserDialogUI
{
  public CustomFolderBrowserDialogUI(FolderBrowserDialog folderDialog) : base(folderDialog)
  {
    this.HeaderBackColor = Color.CadetBlue;
    this.buttonOpen.BackColor = Color.CadetBlue;
  }
}

After applying the FolderBrowserDialog's DialogTemplate property to the new class, the resulting popup will look like this:

Customized FolderBrowserDialog with cadet blue theme applied

For instructions on how to use a custom template to offer advanced customization of the FolderBrowserDialog, see below.

Advanced

Using a Custom Template

The FolderBrowserDialog is fully customizable through the DialogTemplate property. This property, when set, will provide a custom interface for allowing users to select a directory from one of the given Roots.

To build a new custom template, create a new Inherited Window in the project.

Dialog showing the Inherited Window creation option

After clicking Add, you'll be shown a list of inheritable windows. Select FolderBrowserDialogUI and click OK.

Dialog showing FolderBrowserDialogUI selection

Using a custom template requires implementing a custom constructor for processing dialog initialization.

The custom constructor has one argument, a FolderBrowserDialog instance that contains the configuration required to build the dialog.