Class FolderBrowser

The FolderBrowser component provides a convenient and easy to use object oriented wrapper for the Win32 Shell folder browser API.

Inheritance
System.Object
FolderBrowser
Implements
System.ComponentModel.ICustomTypeDescriptor
Namespace: Syncfusion.Windows.Forms
Assembly: Syncfusion.Shared.Base.dll
Syntax
public class FolderBrowser : Component, ICustomTypeDescriptor
Remarks

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 Description
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 Description
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 Description
System.Boolean

Events

FolderBrowserCallback

Occurs when an event within the folder browser dialog triggers a call to the validation callback.

Declaration
public event FolderBrowserCallbackEventHandler FolderBrowserCallback
Event Type
Type Description
FolderBrowserCallbackEventHandler
Remarks

FolderBrowserCallbackEventHandler

Implements

System.ComponentModel.ICustomTypeDescriptor

Extension Methods