TBrowseFolder Component

Written by Todd Fast
Copyright © 1996-97 by Pencilneck Software. All rights reserved.
Version 1.0, lego 9-25-96
Version 2.0, lego 5-7-97
Version 2.1, lego 5-12-97
Version 2.2, lego 6-19-97

Description

Native Delphi component that encapsulates the SHBrowseForFolder interface, which allows Win32 users to select a directory using the standard shell dialog. In addition, TBrowseFolder allows the developer to add a custom button to the dialog. This feature allows you to extend the features of the shell and is found exclusively in this component.

Author

Todd Fast
Please reach me at one of the following addresses if you have any questions, comments, or contributions.

tfast@eden.com
pencilneck@hotmail.com
http://www.eden.com/~tfast/pencilneck.html

Contributors

Distribution

This component is freeware. As such, Pencilneck Software gives no warranty to its accuracy, fitness for any particular use, effects of use, or reliability. This component may not be distributed as a part of another component package without Pencilneck Software's written consent. It may be freely distributed, although it must be distributed with all original files in their original format intact. If you use this component in your software, please include an acknowledgment that portions are copyrighted by Pencilneck Software. Please contact the author, Todd Fast, at one of the above addresses with questions, comments, bug-reports or any updates you make to the component.

Installation Notes

Version 2.2 of this component comes ready to install into Delphi 3.0. If you have Delphi 3.0, you don't have to do anything special to install the component. If you're running Delphi 20, however, you need to make a small change to the BrowseFolder.pas file before installing the component.

Installation in Delphi 2.0

Open the file BrowseFolder.pas in Delphi or another text editor. After the file header, there is a line that looks like the following:

{$DEFINE DELPHI3}

Change this line to the following:

{ $DEFINE DELPHI3} // Add a space before the dollar ($) sign

This change will allow your component to compile properly in Delphi 2.0.

Version Changes

Warning! Version 2.x of this component is not backward compatible with version 1.x. I've incorporated changes into this version that I've wanted to change for some time. Unfortunately, these changes will break any code that uses any but the most basic features of the component. Essentially, code using the property CallbackParam or handling any of the component's events will need to be modified. Fortunately, the changes to the component are simple to incorporate into existing code, and ultimately offer a wealth of additional features.

Version 2.2

Additions

• Users can now choose between a push button and a check box as the custom button type. This feature has added two properties to the component: CustomButtonType and CustomButtonChecked.

Removals

Changes

Version 2.1

Additions

• The SelectedDirectory property is no longer read-only

Removals

• CallbackParam is no longer available for use by developers, and has been used internally to cache a pointer to the current instance of the component. Thanks to Alin Flaider for the original idea and supporting code.

Changes

Version 2.0

Additions

• The component now allows developers to add a custom button to the browse dialog and process its click events. The developer also has control of the button's caption and width.
• The addition of the custom button has spawned several new properties: CustomButtonCaption, CustomButtonEnabled, CustomButtonVisible, CustomButtonWidth, SyncCustomButton.
• The addition of the custom button has spawned a new event called OnCustomButtonClick.
• This HTML component documentation.
• Property editor for the component that allows you to not only invoke the dialog at design time, but choose the Directory property using this dialog.

Removals

• CallbackParam is no longer available for use by developers, and has been used internally to cache a pointer to the current instance of the component. Thanks to Alin Flaider for the original idea and supporting code.

Changes

• The component now selects the folder named in the Directory property when it appears.
• The component no longer uses kludgy global pointers to event handlers. This fact doesn't change the use of the program for the vast majority of users and is generally an improvment in the implementation only. This fact also means that the EBrowseDialogAlreadyShowing exception is no longer necessary and has been removed.
• The component's event declarations have changed completely. This means that any code handling the events from version 1.x must be changed. These changes have made the information from the component much easier to obtain from within the handlers, and represent a significant improvement in the component.
• The Folder property has been renamed to RootFolder.
• A new folder item has been added to RootFolder called foDesktopExpanded. This item is the same as foDesktop, but opens the dialog with the "My Computer" node expanded. Thanks to Ahto Tanner for code suporting this feature.
• The ShowFullPath property has been renamed to ShowPathInStatusArea.
• If the user selects the dialog's Cancel button, the Directory property remains unaffected. This was not the case with some of the contributions I received.

BrowseFolder Documentation

Index

Properties

• CustomButtonCaption
• CustomButtonChecked
• CustomButtonEnabled
• CustomButtonHandle
• CustomButtonType
• CustomButtonVisible
• CustomButtonWidth
• DialogHandle
• Directory
• DisplayName
• Flags
• ImageIndex
• ParentHandle
• RootFolder
• SelectedDirectory
• ShowPathInStatusArea
• SyncCustomButton
• Title

Events

• OnInitialized
• OnSelectionChanged
• OnCustomButtonClick

Methods

• Create
• Execute
• SetStatusText
• SetSelectionPIDL
• SetSelectionPath
• EnableOK

Additional Procedures

• GetIDListFromPath
• CompressString
• BreakApart

Properties

property CustomButtonCaption: String read FCustomButtonCaption write SetCustomButtonCaption;

property CustomButtonChecked: boolean read FCustomButtonChecked write FCustomButtonChecked default FALSE;

property CustomButtonEnabled: Boolean read FCustomButtonEnabled write SetCustomButtonEnabled default TRUE;

property CustomButtonHandle: HWnd read FCustomButtonHandle write FCustomButtonHandle;

property CustomButtonType: TCustomButtonType read FCustomButtonType write FCustomButtonType default btPushButton;

property CustomButtonVisible: Boolean read FCustomButtonVisible write FCustomButtonVisible default FALSE;

property CustomButtonWidth: Integer read FCustomButtonWidth write SetCustomButtonWidth default 75;

property DialogHandle: HWnd read FDialogHandle write FDialogHandle;

property Directory: String read FDirectory write FDirectory;

property DisplayName: String read FDisplayName;

property Flags: TBrowseInfoFlagSet read FFlags write FFlags;

property ImageIndex: Integer read FImageIndex;

property ParentHandle: HWnd read FParentHandle write FParentHandle;

property RootFolder: TSHFolders read FRootFolder write FRootFolder default foDesktopExpanded;

property SelectedDirectory: String read FSelectedDirectory;

property ShowPathInStatusArea: Boolean read FShowPathInStatusArea write FShowPathInStatusArea;

property SyncCustomButton: Boolean read FSyncCustomButton write FSyncCustomButton;

property Title: String read FTitle write FTitle;

Events

property OnInitialized: TBrowserInitializedEvent read FOnInitialized write FOnInitialized;
TBrowserInitializedEvent=procedure(Sender: TBrowseFolder; DialogHandle: HWND) of object;

property OnSelectionChanged: TSelectionChangedEvent read FOnSelectionChanged write FOnSelectionChanged;
TSelectionChangedEvent=procedure(Sender: TBrowseFolder; DialogHandle: HWND; const ItemIDList: PItemIDList; 
	const Directory: String) of object;

property OnCustomButtonClick: TCustomButtonClickEvent read FOnCustomButtonClick write FOnCustomButtonClick;
TCustomButtonClickEvent=procedure(Sender: TBrowseFolder; DialogHandle: HWND) of object;

Methods

constructor Create(AOwner: TComponent);

procedure EnableOK(const Hwnd: HWND; const Value: Boolean);

function Execute: Boolean;

procedure SetSelectionPath(const Hwnd: HWND; const Path: String);

procedure SetSelectionPIDL(const Hwnd: HWND; const ItemIDList: PItemIDList);

procedure SetStatusText(const Hwnd: HWND; const StatusText: String);

Additional Procedures

function BreakApart(const theString, Separator: String; var Tokens: TStringList): Integer;

function CompressString(const Path, Separator, Replacement: String; MaxLength: Integer): String;

procedure GetIDListFromPath(Path: String; var ItemIDList: PItemIDList);

Remarks

This component wraps a few of the Win32 shell functions to display the Windows standard folder browse dialog. I originally hacked this component together over the course of a couple of evenings based on Microsoft's sketchy documentation and some of their C header files, and with some contributions and some free time, have since improved it to be the most flexible component of its type available.

Hints

• The SetStatusText, SetSelectionPIDL, SetSelectionPath, and EnableOK methods ecapsulate the messages you can send to the browse dialog while it is active (see the Microsoft docs on SHBrowseFolder for more information.) Use these functions from within the TBrowseFolder event handlers to make changes to the browse dialog instead of using SendMessage (although that would be perfectly acceptable, and this file defines all the constants you would need.)
• Use the SHGetFileInfo function to retrieve extended information about the selected folder. You can also use the ImageIndex and DisplayName properties of the component for additional information.
• For more information, lookup SHBrowseForFolder, BROWSEINFO, and BrowseCallbackProc in the Win32 online help.
• Beware! The Microsoft documentation on these functions shipped with Delphi is not entirely accurate. In most cases, they've reversed the location of certain parameters sent to the callback function or of messages you can send to the browse dialog. Compare my implementation below with the documentation for more information.