Gregor.WinShell

Sunday, May 04, 2003

Gregor.WinShell namespace

Windows Shell Namespace Access

The main class here is CShellItem, which represents an item in the Windows Shell, such as a file, folder, printer, and so on. You can navigate to an item by file system path (both absolute and relative), by special folder ID (such as MyComputer), or by an item ID list pointer obtained elsewhere. A CShellItem object knows its file system path (if applicable, otherwise is a string representation of folder's class id), its display name (file name, mostly), its type name, its parent and children, and its associated icons. The ShellExec method let's you open (or explore etc.) the item directly in the shell.

Shortcuts

The class CShortcutBase provides the implementation for CShellLink, CInternetShortcut, and CFolderShortcut. All are variations of shortcuts supported by the Windows Shell using the Shell's IShellLink and IPersistFile interfaces; this .NET wrapper calls straight into the COM implementation.

Folder Browsing

The CFolderBrowser class wraps the SHBrowseForFolder function, and allows rooting any folder (file system or otherwise), and initially selecting any folder (file system or otherwise). It works with CShellItem objects.

Explorer-Style File Operations

The SHFileOperation function is wrapped up by subclasses of CFileOperationBase. This allows safe, shell-like file operations (deleting, renaming, moving, copying) in the same way as they are executed by the Windows Shell.

Icons

The CSystemImageList class shovels icons from the Windows system image list into a regular System.Windows.Forms.ImageList when given a file name (or even extenstion) or a CShellItem object (extracting the associated shell icon).

Finding Files

The CFileFinder class searches for files. Plain and simple, it supports multiple wildcard expressions (separated by semicolons), subdirectory recursion, as well as scanning file contents for a given piece of text, with the option of disregarding case or checking word boundaries.

Shell Auto-Completion

The CAutoCompleter class adds IE-style auto-completion to any text box (or combo box etc.), something that was first introduced with IE5. Applications provide an object that supports supports the IAutoCompleteProvider interface for custom sources of auto-complete tokens. By implementing the Shell's IACList interface internally, the CAutoCompleter class enables auto-complete sources to support the more performant approach of enumerating names in a hierarchical namespace level-by-level.

Support Modules

The ShellSupport module is intended as a kitchen sink for interesting shell APIs. For now, it adds default auto-complete behaviour to text or combo boxes (as a quick alternative to using the CAutoCompleter class mentioned above), and pops up the "Add To Favorites" and "Organize Favorites" dialog boxes.

The ShellFileInfo module is useful for extracting associated icons, with having to create a CShellItem instance and using CSystemImageList.

Implementation Notes

Gregor.WinShell also tackles interesting COM interop problems, like referencing managed objects from unmanaged ones - see CAutoCompleter and related types.

In order to call back managed code, unmanaged class CAutoCompleteSource, which implements COM's IEnumString and IACList interfaces, references a managed object implementing the IAutoCompleter interface. This reference is contained in a GCHandle, which takes into account the GC's moving arround of managed objects. The GCHandle is, however, encapulated in a templated struct called "gcroot" (offered by VC++7), which allows type-safe operations (supplementing the managed type whose instances are held by the GCHandle).