Table of Contents
Codebot Shell Controls Manual
Introduction
The codebot shell controls is an easy to use set of shell classes, components, and controls for Embarcadero Delphi versions 7 and 2009. The programming tools in this package allow you to programatic access object in the shell namespace.
The shell namespace is represented in Windows by Windows Explorer (explorer.exe). These shell namespace exist include virtual folders like the control panel and network places, files and folders, and attached devices such as printers and scanners. Shell objects can be invoked to show property pages, execute commands and other programs. More information about shell objects is available in more depth in this article on the codebot website.
A video walkthrough of the contents of this package is available here.
Package Installation
Extract the contents of the shell controls zip to your hard disk. Keep the directory structure intact and move the extracted contents to a development source code directory of your choice. Open Delphi, close all opened projects, then open the cobebot shell controls runtime package. The runtime package names for various Delphi versions are as follows:
d12botshellrun.dpkThe runtime package for Delphi 2009
d7botshellrun.dpkThe runtime package for Delphi 7
As you open the runtime package you may receive version import messages asking to some files. This is normal, click yes or okay to any prompts. Once the package is open, select "Build" from your package project menu. The build should succeed. After you have built the runtime package close all projects.
Next, open the codebot shell controls design time package. The design time package names are as follows:
d12botshelldsgn.dpkThe design time package for Delphi 2009
d7botshelldsgn.dpkThe design time package for Delphi 7
Again, click through any prompts to recreate any files. Once the project is open, select "Install" from your package project menu. This will build and install the runtime packages. You should see a dialog with a message informing you that the Codebot Shell controls were installed correctly. Close the design time package. You should now have a "Codebot Shell" tab with the following controls: TShellBubbles, TShellEdit, TShallPathEditBar, TShellTree, TShellView, TSmallShellImages, TLargeShellImages, TShellBinding.
Quick Start
Open Delphi and create a new VCL from project. Select the Codebot Controls tab from the component pallet and drop the following components on your form: TShellPathEditBar, TShellTree, TShellView, and TShellBinding. Double click TShellBinding, select all the controls, and press OK. Press F9 to run the project. You've just built a functional version of Windows Explorer.
Component Overview
TShellBubbles is a visual control which mimics the left most pane of an open dialogs on Windows XP. Like all Codebot Shell Controls, shell bubbles uses the Windows theming engine. In addition, again like all other shell controls, it relies on the shell system images. This means that the shell bubbles and all the other shell controls will visually "fit in" on your user's computer, without regard to the version of Windows the are running.
The purpose of the shell bubbles control is to give the user quick access to frequent or important folders. As a programmer, you can add and reorder bubble items using special folder paths, or your own paths added programatically. You can set shell bubbles to use large or small icons, and you choose to turn off or on text labels. You can also control if the labels appear below or to the side of the folder's icon.
The purpose of the shell bubbles control is to give the user quick access to frequent or important folders. As a programmer, you can add and reorder bubble items using special folder paths, or your own paths added programatically. You can set shell bubbles to use large or small icons, and you choose to turn off or on text labels. You can also control if the labels appear below or to the side of the folder's icon.
Key Properties
ItemsA collection of TShellBubbleItem objects
ItemIndexThe index of current TShellBubbleItem
NavigateRootWhen used with binding clicking causes a the selection or the root to update
StyleControls if small or large icons are used
TextLabelsTurns off or on text labels
Key Events
OnClickA TShellBubbleItem was clicked. Check ItemIndex to determine which one
TShellEdit is a drop down edit control which allows the user to select a folder. The use can type or edit path names, or choose a folder from a drop down shell tree. You can set whether the user can type full paths, or paths relative to the current folder. You can also enable path completion, where a separate path combo is presented as the user types with a choice of folders and files that best match the user's input. TShellEdit and the related TShellPathEditBar are somewhat mutually exclusive controls. The shell edit acts like the explorer address bar from windows xp, while the shell path edit bar resembles Vista's newer bread crumb navigation bar.
Key Properties
HotTrackNotify you when the mouse moves over a new node in the drop down tree
OptionsOptions include use auto suggest, and use short relative paths
RootThe root shell node of the shell edit control
SelectedNodeThe current shell node which is displayed in the edit portion of the control
SpecialFolderSets a new root using a TSpecialFolder enumeration
StatusTextControls the text in the status area of the drop down
Key Events
OnNodeHoverA shell node was hovered over while HotTrack is enabled
OnSelectNotification that a new shell node was selected
TShellPathEditBar is a Vista style bread crumb path bar control. As the path edit bar is a VCL implementation, it will work on Windows 2000 or later. TShellPathEditBar and TShellEdit are somewhat mutually exclusive. You may use either or both. One favors the XP explorer approach, while the other favors Vista. The control offers auto suggestion, drop down paths, and a horizontal shell node list separated by arrow bullet glyphs.
Unlike the Vista bread crumb bar, you can choose to show icons at every node. You can also choose to always draw node buttons. Clicking an empty area allows you to edit the path as text. When no empty area is available, you can double click the control, or press space or enter, to invoke edit mode.
Key Properties
EditingToggles between node arrows input and text input
RootThe root shell node of the shell edit control
SelectedNodeThe current shell node which is displayed as the last node in the path
ShowFilesShow non-folder nodes in the drop down lists
ShowSuggestShow the auto suggest list when editing
SpecialFolderSets a new root using a TSpecialFolder enumeration
Key Methods
ParseConvert text into a shell node and set that as the SelectedNode
Key Events
OnChangeOccurs when a the selected node changes
OnDefaultActionAllows you to intercept the execution of a non-folder node
TShellTree is a tree view control, but with TShellTreeNode item in place of the traditional TTreeNode items. Since the items in the tree are populated from the system shell, you cannot add or alter items without adding to or altering the information tied to the computer through the shell. The tree control is essentially the left side tree window in explorer. It will update in real time when your computer's shell objects change.
The shell tree control is a very useful control serving many purposes. You can use it to create your own browse for folder dialog, or you can root to a private folder to show the structure of application data such as project and resource files and folders on disk. To set the root to or selected node to any arbitrary location, you can use code similar to the following:
procedure SetTreeRoot(Tree: TShellTree; const FolderName: string);
var
  Node: TShellNode;
begin
  Node := TShellNode.CreateFromFolder(FolderName);
  Tree.Root := Node;
  Node.Free;
end;
Key Properties
AllowContextMenuAllows the default system context menu to appear when the tree receives a right click event
RootThe root shell node of the shell edit control
SelectedNodeThe current shell node which is displayed as the last node in the path
ShowSuggestShow the auto suggest list when editing
SpecialFolderSets a new root using a TSpecialFolder enumeration
Key Events
OnChangeOccurs when a the selected node changes
OnCollapseOccurs when a node is collapsed
OnExpandOccurs when a node expands
Key Related Functions
FindTreeNodeSearch for a node even if it has yet to have been created in the tree
TShellView is a control that hosts a real instance of explore's content window. Because of this, the actual functionality of the shell view control varies between Windows versions, which is a good thing. For example, Vista users can view very large thumbnails images in the shell view control. They can also filter items using the header panels. Everything you can do with the explorer.exe content pane, you do with the shell view controls
Some useful features are detecting changes to the selected item, filtering or including items using the OnIncludeItem event, processing the default action to invoke custom code when an item is double clicked. You may also remove the context menu using the AllowContextMenu.
Here is a simple idea for using a shell view control in your programs is to create a log file viewer. On one of your forms place a shell edit control which will be used by your users to check your applications logs files. You can point the shell view to your logging directory and filter the files based on log names for you application. You may also choose to have the log items sorted with the most recent first. You can then invoke you own custom log viewer when the user double clicks an log item, or if you log in test format, just allow the default action and notepad be launched opening your log file with no extra code. This approach make it very quick and easy to implement a log viewing feature into your own applications as the file system and the shell control handles most of the work for you.
Key Properties
AllowContextMenuAllows the default system context menu to appear when the tree receives a right click event
DefaultKeysTranslates keystrokes to default actions, such as F2 to rename an item and backspace to go up one level
ParentRootThe top most shell node level of shell view. This property defaults to nil
RootThe root shell node of the shell edit control
SelectedNodeThe current shell node which is displayed as the last node in the path
SpecialFolderSets a new root using a TSpecialFolder enumeration
ViewModeToggles the view mode between details, list, icons, thumbnails, and tiles
Key Methods
ExecuteVerbInvoke a command from the folder's default context menu
ExploreNavigate to a new folder folder given a path
GetItemsReturns a list of items in the current view using selection and path parameters
RefreshReloads the current view. Useful when you alter how you want to filter items using OnIncludeItem
Key Events
OnDefaultActionAllows you to intercept the execution of any item in the view
OnChangeOccurs when a the you navigate to a new root
OnIncludeItemAllows you to check each shell node as it populates the view. You can filter items in this event
OnSelectionChangedFires when the selection changes. You may use GetItems to detect the current selection
TLargeShellImages and TSmallShellImages are image list components which both refer to the system image list. Their handles are shared, so adding multiple instances of either component to multiple forms does not increase your applications memory usage. The large image list holds the normal icon scheme dependent on the users configuration. Typically these are 32x32 pixel images, but the size can be larger based on user settings. The small image list holds small icons, almost always 16x16 pixel icons. You can use these image lists with any control that has an image list property.
TShellBinding is a component which can be used to synchronize changes between shell controls. Though not totally necessary, it alleviates the programming tasks of connecting changes in one control to another.
To use the shell binding component, just place shell controls on a form, then place a shell binding component on the same form. Double click the shell binging component to invoke the binding editor. Select the shell controls want want to synchronize, and click OK. When a shell edit, tree, and view controls are bound together, selecting a node shell tree in the shell tree updates the root in the shell view, and the selected node and text in the shell edit. Alternately, opening a folder in the shell view updates the selected node in the shell tree and shell edit controls.
The shell binding component removes the need to write this code:
procedure TForm1.ShellBubblesClick(Sender: TObject);
var
  Node: TShellNode;
begin
  Node := ShellBubbles.Items[ShellBubbles.ItemIndex].Node;
  ShellTree.SelectedNode := Node;
  ShellEdit.SelectedNode := Node;
  ShellView.Root := Node;
end;
Notable Classes
The Codebot Shell Controls package contains a notable TShellNode class defined in the Shltools unit. It is helpful to understand what this class is and how it functions when using the shell controls units. In general TShellNode is a class which represents a namespace item.
Typically, when working within the shell namespace you need to be very careful when working with pointers to system allocated binary data known as item id lists. Working with item id lists can be difficult, as you are generally required to take ownership of the memory as soon you touch it, and then dispose of it later using the system task allocator. This can all be very complex, but the TShellNode class takes care this and other tasks for you.
The TShellNode class has multiple constructors based on the way you want to work. Here is a summary of the constructors.
Constructors
CreateCreate a node using a parent and a relative list. Either parameter can be nil. If both are nil the node refers to the system shell root which is the desktop. If parent is nil, then the new node is relative to the desktop.
CreateFromListCreate a node using an absolute list. If the list is nil the new node refers to the desktop.
CreateFromObjectReturns a new shell node given an IShellFolder object
CreateFromPathCreates a new node given a string path
Constructor Related
CloneClones a new node using the specified class type. If class type is nil, the clone is of the same class type as the original instance.
Note, if you choose use a contructtor with an item id list, the shell node then owns the list. You should not attempt to free the list or share it with another newly created shell node. Freeing a parent node, frees all child nodes and their item id lists.
Key Properties
AbsoluteListThe node's absolute item id list
RelativeListThe node's relative item id list
IsEqualDetermines if two nodes reference the same shell namespace object
ItemsIndexed property of child shell node object
CountThe number of child node in items. Accessing this property for the first time causes the node to enumerate and create children
HasChildrenDetects if child nodes exist without creating them
ShellFolderA reference to the current item's IShellFolder object. If this property is nil the node refers to a non-folder object.
NameThe name of the shell namespace object as it appear in explorer
PathThe file path of the shell namespace object if it resides on disk
Key Methods
ClearDestroys all references and children and unitializes the Count property
ExecuteExecute a verb from the node's shell context menu
GetAttributesRetrieve a the attribute flags of the node