# FolderBrowserDialog

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.

{% hint style="info" %}
For a full list of properties, methods and events see the [API documentation.](http://docs.wisej.com/api)
{% endhint %}

## 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](https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-16f10ee38bcaae40e488e5b03d087439d080da37%2Fimage.png?alt=media)

{% hint style="warning" %}
Directories must have the appropriate read permissions to be discoverable by the Wisej.NET application.
{% endhint %}

{% hint style="success" %}
The [FolderBrowserDialog.SelectedPath](https://docs.wisej.com/api/wisej.web/common-dialogs/wisej.web.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()](https://docs.wisej.com/api/wisej.web/common-dialogs/wisej.web.folderbrowserdialog#mappath-folderpath).
{% endhint %}

### 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](https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-41eec084de77cf2f0e1d660f3ba738f5d4ef4cac%2Fimage.png?alt=media)

## 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:

{% tabs %}
{% tab title="C#" %}

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

{% endtab %}
{% endtabs %}

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](https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-bbbd739ab3d19e319517eeb68cef8d5d97330b6d%2Fimage.png?alt=media)

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](https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-611c817e1b1aa3c007ece8adb73bf3861d11b833%2Fimage.png?alt=media)

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

![Dialog showing FolderBrowserDialogUI selection](https://553579532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MF1D11gPs_az3xaKusw%2Fuploads%2Fgit-blob-fb175687bb28dc2623276b690d6c8b93cef55d05%2Fimage.png?alt=media)

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

{% hint style="info" %}
The custom constructor has one argument, a `FolderBrowserDialog` instance that contains the configuration required to build the dialog.
{% endhint %}