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