## DSF Filesystem Browser Example

### Goals

This example demonstrates an implementation of a viewer model with a layout node that has itself as a child. Such layout nodes are needed to represents elements which themselves have a natural tree structures. This example uses filesystem folders as the tree-structured data, which is retrieved directly from the java.io.File class. This example also demonstrates a viewer model implementation which does not retrieve data using DSF services and associated data model interfaces.

### Design

Model Adapter Hookup
A flexible-hierarchy tree viewer {@link org.eclipse.debug.internal.ui.viewers.model.provisional.TreeModelViewer} is created within a model dialog. Corresponding {@link FileBrowserModelAdapter} and {@link FileBrowserVMProvider} classes are instanciated, and the root element object created by FileBrowserVMProvider is set as input to the tree viewer. From there FileBrowserModelAdapter is returned as the {@link IElementContentProvier} and {@link IModelProxyFactory} for all elements in the tree.

Layout Nodes
There are three layout nodes:

- {@link FileBrowserVMProvider.VMRootLayoutNode} is just a root node, which generates the input element for the viewer.
- {@link FilesystemRootsLayoutNode} retrieves the roots of the filesystem hierarchy ("C:\", "D:\", etc on Windows).
- {@link FileLayoutNode} is a child of FilesystemRootsLayoutNode and it recursively retrieves all folders and files under the given parent file element. This layout node does not allow any children nodes to be added to it, and it returns only itself as a child node (through a call to IVMLayoutNode.getChildLayoutNodes).

Both FilesystemRootsLayoutNode and FileLayoutNode create elements of the same type: {@link FileVMContext}. Additionally, when populating elements in the tree, the FileLayoutNode requires that a FileVMContext element be the parent element in order to be able to retrieve its children.

Event Handling/Generating Model Deltas
The view model responds to events generated by a text box in the dialog, where the user can type in a filesystem path. If the entered path resolves to a file on the filesystem, the view model generates a delta to select and reveal the given file in the tree. The two file layout nodes handle generating the delta in different ways:

- FilesystemRootsLayoutNode is a standard layout node.

1. In the event handler implementation {@link org.eclipse.cdt.dsf.ui.viewermodel.IVMLayoutNode#buildDelta}, the user specified file-path is compared to the list of file-system roots.
2. If the user file-path contains one of the filesystem roots, a new delta node is added for that root and the child layout node is called to continue the delta processing.
3. If the user file-path points to one of the filesystem roots, the IModelDelta.SELECT and IModelDelta.EXPAND flags are also added to the delta so that the root will be selected in the viewer.

- FileLayoutNode is the special case, because it is a recusrive node. This node does not call any child nodes to process the delta, instead it calculates the delta for all file elements in user file-path, starting at the parent element.

1. First the parent FileVMContext element is retrieved from the delta.
2. Then the user file-path is broken down into {@link java.io.File} objects representing each segment in the path, starting at the parent file element retrieved in step 1.
3. Then a delta node is added for each segment of the calculated path.
4. IModelDelta.SELECT and IModelDelta.EXPAND flags are added to the last delta.

### How to use

1. Make sure that the DSF examples menu is visible in the perspective

- Go to Windows -> Customize Perspective...
- Select Commands tab
- Check the "DSF Examples" in the "Available command groups" table.

2. Open the dialog by selecting DSF Examples->Open File Browser Dialog menu item.
3. Expand the items in the tree to see filesystem contents.
4. Select elements in the tree, to fill in text box with selected file's path.
5. Type in a file path in text box and have the tree expand to the specified element.