GCFolderBrowser

Simple interface component for browsing a folder hierarchy. Download Now (60K Xcode project)

Sometimes an application wants to allow the user a quick way to navigate through the folder hierarchy on disk without going to the full use of NSOpenPanel, which is always modal in some way. GCFolderBrowser is one solution - an easy-to-use controller that uses an NSOutlineView to show any part of the file structure you choose. It is particularly suited to those situations where you might want to design an interface for browsing for certain kinds of files and need a quick way to navigate the folder structure.

GCFolderBrowserController is the main class presented here. It manages an NSOutlineView, and internally represents elements of the file structure using GCFolderInfo objects. These objects permit the folder hierarchy on disk to be presented by the interface as lazily as possible - only those folders that the user actually opens within the outline view are ever scanned for their contents. In this demo application, a custom text cell is used in the outline view to display a small folder icon adjacent to the folder's name. All of the acrtual look and feel of the interface is set up entirely within Interface Builder. This code does not force any particular look on your interface. The demo uses the now-standard "source list" style for the outline view.

The controller informs other code of the user's selection choice using a simple informal protocol which consists of one method sent to the controller's delegate. In the demo app, the Application Delegate is used as this object for convenience. Note that all delegates and data sources are wired up in IB.

Using the Folder Browser

The simplest way to use the folder browser is to instantiate a GCFolderBrowserController within an appropriate nib, set up the interface components and simply wire them up. The only code that you have to write is to respond to the selection choice in the controller's delegate. The delegate method looks like this:

- (void) folderBrowser:(GCFolderBrowserController*) browser didSelectFolder:(GCFolderInfo*) folderInfo;

The information about the selected folder is passed as a GCFolderInfo object, which encapsulates information about the folder, such as its path, name and icon. This is also the object used internally by the controller, and is defined in its header file.

The browser will display folders from some given root folder downwards. By default the root folder is set to the current user's home folder, but you can change it to anything you like using -setRootFolder: The demo allows a new root to be set.

The folder browser can be used to navigate into file packages too, if you wish. By default it is set not to do so. To enable this, use -setIncludesFilePackages:YES.

To preselect any folder in the browser, you can use -selectPath: passing any valid path. If the path does exist somewhere in the folder hierarchy displayed, the folders will be opened as necessary and the final destination highlighted.