Class FolderBrowser
The FolderBrowser component provides a convenient and easy to use object oriented wrapper for the Win32 Shell folder browser API.
Inheritance
Implements
Namespace: Syncfusion.Windows.Forms
Assembly: Syncfusion.Shared.Base.dll
Syntax
public class FolderBrowser : Component, ICustomTypeDescriptorRemarks
The FolderBrowser class completely abstracts the various complex Shell API functions, structures and callback routines required for invoking the folder selection dialog and allows you to work with a more .NET-centric programming model consisting of aptly named properties, methods and events. Most convenient of all, you no longer need to allocate PIDLs as specifying the location of the rootfolder; browsing is now a simple task of setting the FolderBrowser.StartLocation property from one of the values provided in the FolderBrowserFolder enumeration. Using the FolderBrowser class to browse the Shell folders is simple and to the .NET developer a completely familiar issue of instantiating the FolderBrowser component, setting the appropriate properties and events on it and invoking the ShowDialog() method. For more detailed information on the Shell APIs refer to the Platform SDK documentation on the SHBrowseForFolder method.
Examples
The following code creates an instance of the FolderBrowser component, sets the folder dialog start location and styles and invokes the FolderBrowser.ShowDialog() method:
private void ShowFolderBrowserDialog()
{
// Create the FolderBrowser component:
this.folderBrowser1 = new Syncfusion.Windows.Forms.FolderBrowser();
// Initialize the FolderBrowser component:
this.folderBrowser1.Description = "Syncfusion FolderBrowser";
this.folderBrowser1.StartLocation = Syncfusion.Windows.Forms.FolderBrowserFolder.Desktop;
this.folderBrowser1.Style =
( Syncfusion.Windows.Forms.FolderBrowserStyles.RestrictToFilesystem |
Syncfusion.Windows.Forms.FolderBrowserStyles.BrowseForComputer );
// Provide a handler for the FolderBrowserCallback validation event:
this.folderBrowser1.FolderBrowserCallback += new Syncfusion.Windows.Forms.FolderBrowserCallbackEventHandler(this.folderBrowser1_BrowseCallback);
// Display the folderbrowser dialog:
if (this.folderBrowser1.ShowDialog() == DialogResult.OK)
this.selectedFolder = this.folderBrowser1.DirectoryPath;
} // Event handler for the FolderBrowser.FolderBrowserCallback validation event.
// This handler is functionally equivalent of the Win32 BrowseCallbackProc callback function:
private void folderBrowser1_BrowseCallback(object sender, Syncfusion.Windows.Forms.FolderBrowserCallbackEventArgs e)
{
this.label1.Text = String.Format("Event: {0}, Path: {1}", e.FolderBrowserMessage, e.Path);
if (e.FolderBrowserMessage == FolderBrowserMessage.ValidateFailed)
{
e.Dismiss = e.Path != "NONE";
}
}Constructors
FolderBrowser()
Overloaded. Creates a new instance of the FolderBrowser component.
Declaration
public FolderBrowser()FolderBrowser(IContainer)
Creates a new instance of the FolderBrowser and initializes it with the container.
Declaration
public FolderBrowser(IContainer container)Parameters
| Type | Name | Description |
|---|---|---|
| System.ComponentModel.IContainer | container | An object implementing IContainer that will host this instance of the FolderBrowser component. |
Properties
CustomStartLocation
Gets or sets custom start location for showing dialog.
Declaration
public string CustomStartLocation { get; set; }Property Value
| Type |
|---|
| System.String |
Description
Gets or sets the text displayed above the tree control in the folder browser dialog.
Declaration
public string Description { get; set; }Property Value
| Type | Description |
|---|---|
| System.String | A String value. |
DirectoryPath
Retrieves the location of the selected folder.
Declaration
public string DirectoryPath { get; }Property Value
| Type | Description |
|---|---|
| System.String | A String value. |
SelectLocation
Gets or sets selected location for showing dialog.
Declaration
public string SelectLocation { get; set; }Property Value
| Type |
|---|
| System.String |
StartLocation
Gets or sets the start location for the folder browser dialog.
Declaration
public FolderBrowserFolder StartLocation { get; set; }Property Value
| Type | Description |
|---|---|
| FolderBrowserFolder | A FolderBrowserFolder value. |
Remarks
The StartLocation property is the functional equivalent of the Win32 PIDLs.
Style
Gets or sets the options for the folder browser dialog.
Declaration
public FolderBrowserStyles Style { get; set; }Property Value
| Type | Description |
|---|---|
| FolderBrowserStyles | A FolderBrowserStyles value. |
Methods
OnFolderBrowserCallback(FolderBrowserCallbackEventArgs)
Raises the FolderBrowserCallback event.
Declaration
protected virtual void OnFolderBrowserCallback(FolderBrowserCallbackEventArgs arg)Parameters
| Type | Name | Description |
|---|---|---|
| FolderBrowserCallbackEventArgs | arg | A FolderBrowserCallbackEventArgs value that contains the event data. |
ShowDialog()
Overloaded. Displays the folder browser dialog with a default owner.
Declaration
public DialogResult ShowDialog()Returns
| Type | Description |
|---|---|
| System.Windows.Forms.DialogResult | DialogResult.OK if the user clicks OK in the folder dialog; DialogResult.Cancel otherwise. |
ShowDialog(IWin32Window)
Displays the folder browser dialog with the specified owner.
Declaration
public DialogResult ShowDialog(IWin32Window owner)Parameters
| Type | Name | Description |
|---|---|---|
| System.Windows.Forms.IWin32Window | owner | A top-level window that will serve as the owner for the dialog. |
Returns
| Type | Description |
|---|---|
| System.Windows.Forms.DialogResult | DialogResult.OK if the user clicks OK in the folder dialog; DialogResult.Cancel otherwise. |
ValidateProc(IntPtr, Int32, IntPtr, IntPtr)
Validates the procedure.
Declaration
public bool ValidateProc(IntPtr hwnd, int uMsg, IntPtr lParam, IntPtr lpData)Parameters
| Type | Name | Description |
|---|---|---|
| System.IntPtr | hwnd | |
| System.Int32 | uMsg | |
| System.IntPtr | lParam | |
| System.IntPtr | lpData |
Returns
| Type |
|---|
| System.Boolean |
Events
FolderBrowserCallback
Occurs when an event within the folder browser dialog triggers a call to the validation callback.
Declaration
public event FolderBrowserCallbackEventHandler FolderBrowserCallbackEvent Type
| Type |
|---|
| FolderBrowserCallbackEventHandler |