(Print this page)

A Folder Browser dialog (in Windows Forms)
Published date: Tuesday, April 1, 2003
On: Moer and Éric Moreau's web site

We often need to have users use a "folder browser" dialog in our applications. You surely already have used the Win32 ShBrowseForFolder function when building VB6 applications? Guess what, Microsoft Visual Studio .Net team forgot this feature when they built VS.Net 2002! 

There are at least two ways for handling this dialog right now. One is managed while the other is unmanaged. Unmanaged code runs outside the .Net Framework. I will show you the managed way and I will give you links for the unmanaged code.

Create a new project.

Create a new Visual Basic .Net project using the Windows Application template. 

Since this project inherits an existing class, we need to add a reference. Select "Add Reference..." from the Project menu. From the "Add Reference" dialog, choose "System.design.dll" (in the .Net tab) and click the Select button and then the OK button.

Create a wrapper class.

We will create a class that wraps the functionality of the folder browser. This wrapper will ease the re-use of this feature. About 5 lines will be required to use the feature. 

Select "Add Class..." from the Project menu. Be sure that the Class template is selected and change the name to MyFolderBrowser.vb. Finally, click the Open button. 

Before the "Public Class MyFolderBrowser", we need to import the Design namespace using this line: 

Imports System.Windows.Forms.Design
The following code is going into the class (between the Public Class ... and the End Class lines). As I have said earlier, we inherit an existing class. So we need to add this line: 
Inherits FolderNameEditor
We also need to recreate two enumerations that change the behavior of the dialog box: 
Public Enum enuFolderBrowserFolder
    Desktop = FolderBrowserFolder.Desktop
    Favorites = FolderBrowserFolder.Favorites
    MyComputer = FolderBrowserFolder.MyComputer
    MyDocuments = FolderBrowserFolder.MyDocuments
    MyPictures = FolderBrowserFolder.MyPictures
    NetAndDialUpConnections = _
        FolderBrowserFolder.NetAndDialUpConnections
    NetworkNeighborhood = _
        FolderBrowserFolder.NetworkNeighborhood
    Printers = FolderBrowserFolder.Printers
    Recent = FolderBrowserFolder.Recent
    SendTo = FolderBrowserFolder.SendTo
    StartMenu = FolderBrowserFolder.StartMenu
    Templates = FolderBrowserFolder.Templates
End Enum

'The FolderBrowserStyles collection is a member of FolderNameEditor
Public Enum enuFolderBrowserStyles
    BrowseForComputer = FolderBrowserStyles.BrowseForComputer
    BrowseForEverything = FolderBrowserStyles.BrowseForEverything
    BrowseForPrinter = FolderBrowserStyles.BrowseForPrinter
    RestrictToDomain = FolderBrowserStyles.RestrictToDomain
    RestrictToFilesystem = FolderBrowserStyles.RestrictToFilesystem
    RestrictToSubfolders = FolderBrowserStyles.RestrictToSubfolders
    ShowTextBox = FolderBrowserStyles.ShowTextBox
End Enum
Now we can create two public class members from the enumeration (and we also give a default value): 
Public StartLocation As enuFolderBrowserFolder = _
    enuFolderBrowserFolder.BrowseForComputer
Public Style As enuFolderBrowserStyles = _
    enuFolderBrowserStyles.ShowTextBox
Let's now add some private members to the class (and one of them is of the FolderBrowser type that comes from the FolderNameEditor namespace): 
Private mstrDescription As String = _
    "Please select a directory below:"
Private mstrPath As String = String.Empty
Private mobjFB As New FolderBrowser()
Now add two public properties to our class. The Description property can be used to change the message that will appear in dialog (near the top). 
Public Property Description() As String
    Get
        Return mstrDescription
    End Get
    Set(ByVal Value As String)
        mstrDescription = Value
    End Set
End Property
The read-only Path property will be used to retrieve the selected folder. 
Public ReadOnly Property Path() As String
    Get
        Return mstrPath
    End Get
End Property
The last thing we need in this class is a method that will actually display the dialog and return a dialog result and set the path property: 
Public Function ShowBrowser() As System.Windows.Forms.DialogResult
   With mobjFB
       .Description = mstrDescription
       .StartLocation = CType(Me.StartLocation, _
                           FolderNameEditor.FolderBrowserFolder)
       .Style = CType(Me.Style, _
                       FolderNameEditor.FolderBrowserStyles)
       Dim dlgResult As DialogResult = .ShowDialog
       If dlgResult = DialogResult.OK Then
           mstrPath = .DirectoryPath
       Else
           mstrPath = String.Empty
       End If
       Return dlgResult
   End With
End Function

Test the class.

When we started the wrapper class, I told you that the use of the class should take about 5 lines of code. It is now the time to count them! 

Add a button to the form that is already created in your project. Double-click on it to create the Click handler procedure. In the handler, copy these lines: 

Dim objFB As New MyFolderBrowser()
If objFB.ShowBrowser = DialogResult.OK Then
    MessageBox.Show(objFB.Path)
End If
With four lines of code, you have a working folder browser! 

You can run the project now and you should see the dialog to the right appear after you have clicked the button. 

Figure 1: Your Folder Browser dialog

If you select one folder and click the OK button, the selected path will be displayed into a message box (because this is what we are doing with the Path property). 

Do you remember that we have added properties to our class? 

Before calling the ShowBrowser method, we could have used them like this:

objFB.Description = "Type your own description"
objFB.StartLocation = _
MyFolderBrowser.enuFolderBrowserFolder.Desktop
objFB.Style = _
MyFolderBrowser.enuFolderBrowserStyles.ShowTextBox
This will change the description in the resulting dialog, the startup location (set to the Desktop instead of MyComputer) and also a textbox will appear just over the buttons.

What if I really want to use unmanaged code?.

You can still use the ShBrowseForFolder Win32 API call if you are ready to use unmanaged code. Why would you want to use unmanaged code? One reason could be because you may set the starting folder! 

If you really want to use the ShBrowseForFolder Win32 API call, you can read the Browsing for a folder article. This article also shows you how to use Win32 APIs. 

There is also another example from GotDotNet.

What about C#?

For those of you doing C#, you can have a look at HOW TO: Implement a Managed Component that Wraps the Browse For Folder Common Dialog Box by Using Visual C# .NET.

Conclusion.

The next version of Visual Studio .Net (named VS.Net 2003) is due later this month. This newer version is using the .Net Framework 1.1. The new framework will expose a folder browser feature into the System.Windows.Forms.FolderBrowserDialog class.

I hope you appreciated the topic and see you next month.


(Print this page)