Directory View

Preliminary documentation.

For Directory v1.0 beta.

Intro

Directory View is a file/directory viewer/manipulator. It creates a View (window) which is used to display a selected directory.

The application is a plugin based architecture.

Plugins are required to do anything beyond browsing and basic drag and drop.

It is designed for individuals who know something about the filing system, privileges and how the system works. It is not designed for amateurs.

It does not protect the user from themselves in the same way as the Finder does.

You can inflict a lot of damage to the filing system with this application. (Usual access rights will prevent the system from being hosed).

Currently, Directory View will never execute as root.

It allows you to view a directory in six ways :

• Info display : information about the directory itself

• Text display : display contents in a line-by-line text format

• Star display : not yet implemented

• Tree display : an icon based, hierarchical display

• Column display : similar to Finder column display

• Object display : shows ALL* objects in the directory in an icon or list view

• Selected display : lists objects which are in one or more of the four selection states

* the View does not collect every single item in a directory. It only goes 3 levels deep and no more. You can "instruct it" to go deeper.

It has multiple select modes (as opposed to one as in the Finder and everywhere else).

The Plugin Manager has been implemented and plugins are supported.

This beta release will come with one plugin which has three simple functions : a basic Zip Tool, a "Is a Directory" Filter and a partially completed copy Command.

It is not another Finder.

The View

The View window is divided into 3 sections: a Tool bar, Tab view (display modes) and a Info Strip (grey strip along the bottom of the window).

Each Tab pane is explained below.

The Info Strip is used to display simple information about a filing system object or the current display. Object -Icon display, for example, shows the path of the object under the mouse.

Status Strips

Each View has eight Status Strips that hang around the edge of the main display pane.

They are normally invisible (the beta release will display them as floating windows) and are only visible when the View is the front-most window.

The strips are available for use by the plugins to display basic information such as a Progress Bar or a simple text message like "20 of 40 items deleted". The strips are thin are hopefully not too distracting.

The strips do not respond to mouse-clicks (unless the current plugin owner changes that).

The sample Zip Tool uses one of the strips when zipping.

Tool Bar

By default, the Tool bar has four tools : Print, Easy Filter, Show Page & Get Objects.

Print

This will not function for all display types.

It will function for Info, Text (left box), Tree & Objects - Icon display.

The File menu has a Print submenu with the various displays listed.

Clicking the Print icon or Print from the File Menu will print the current display.

Show Page

This is a toggle to show the page boundaries of the current Page Setup.

Easy Filter

The previous filter will be moved to it's own plugin.

This button will be used to show the selected default Filter (see below). It currently does nothing.

Get Objects

Gathers all filing system objects up to 5 levels below the root object. (Future releases will allow depth selection.)

Depending on the item count of the sub-directories, this can take a while to gather.

A small, transparent "Gathering Objects" chasing arrows window will display in the top-right corner of the window.

When the gathering is complete, it will disappear.

The Refresh commands of the various display types will still function. They will take a "snapshot" of what the View currently has and display it.

Commands

Commands are implemented via Plugins (see below).

Commands are functions that are View specific and generally operate on objects selected with one or more of the select modes.

Info Display

Displays filing system information about the directory.

Text Display

Displays the contents of the directory in two boxes.

The left box lists the directory contents, one object per line, in the following format:

--file A

-+dir A

----file B

----file C

--file D

The right box is used to display what is in the left box in a user defined format string (similar to printf).

The default format string is ':PTH:\n'. (See below for format types.)

The outputted text is editable.

Formatting

The format string is simply a string of characters with file object metadata placeholders and escape characters.

The escape characters are as follows:

\n new line

\t tab

\\ backslash

\: colon character

A metadata placeholder consists of 2 ':' colons with 3 or more characters in-between.

The :PTH: metadata placeholder is an example.

Below is a full list of metadata codes. Codes with (_xy) indicate optional formatting codes. The undescore is necessary and if there are 2 or more marker letters, all markers have to be indicated.

NME object name without suffix

NMS object name with suffix

PTH full path of object

TYP object type

CDT(_xy) creation date. Where xy are optional formatters:

x: Date form. L (long); S (short); A (abbreviated); R (relative), - skip

y: Time form: N (not displayed), L (long), S(short), A(abbreviated), - skip

MDT(_xy) modification date

ADT(_xy) last access date

BDT(_xy) backup date

LSZ(_x) logical size. x is one of B(bytes), K(KB), M(MB), G(GB) & T(TB). Bytes is the 

default.

PSZ(_x) physical size

DLS(_x) data fork logical size

DPS(_x) data fork physical size

RLS(_x) resource fork logical size

RPS(_x) resource fork physical size

DIR(_x) Director item count. x is count of specific item type: F(file), D(dir),

S(symbolic link), A(alias)

PRM(_x) permission flags. x is display format of permission values: O or o (octal)

B (binary, Capital B for b0 first, lowercase b for b15 first)

X or x (hexadecimal)

D or d (decimal)

L (letters - RWXRWXRWXS. lowercase 'l' for lowercase)

OWN(_x) owner ID. x is one of I (numeric ID), N (name) or B (both)

GRP(_x) group ID.

Star Display

The Star display is to be a 2D or 3D "solar system" display of a directory's contents.

It is not yet implemented and won't be implemented in v1.0.

Tree Display

A tree-like display of the directory's contents.

The two sliders are used for horizontal and vertical spacing of the grid.

If either of the values are below a certain threshold, the icons and text will be replaced with small circles.

The Lock checkbox is used to keep the two sliders in sync. The result is that the icons will always be square.

Column Display

Standard hierarchical column display similar to the Finder.

Currently, only one object can be selected at any one time.

There is also a semi-transparent floating window. It is used to display info about the currently select item.

The slider is used to change the transparency.

If the cursor moves into any part of the window except for the title bar or slider, the window will "teleport" to the "far side" of the window. Holding the option key will prevent the teleporting.

Object Display

Object display can show all objects of the root directory in one big layout of icons or lines. There is no hierarchical navigation.

The number actually shown depends on what the View has "stored" (the count).

Object display consists of two sub-display views : icon and list.

Icon

The left slider is the icon size. The right slider is the icon spacing as a multiple of the icon size.

The progress bar under the icon pane is used to indicate the progress of calculating the icon positions (and other internal data creation). For thousands of icons, this can take a while.

The grey strip at the bottom of the window will display the object's filing system path and other information depending on the current sorting method.

List

Selected Display

This shows what objects have been selected with the four different select modes.

Objects can be removed or "transferred" to a different selection group.

The above selected objects in the selected lists below.

Select Modes

There are 4 different select modes, each operating independently of one another.

They operate essentially the same as the standard single select mode in the Finder.

The different modes are used by the plugin tools & commands.

Simple example : file copy to multiple destinations. Files are selected using Source select mode & target directories Destination select mode.

Currently, each View is unaware of another View's selections. They are independent.

Plugins may query any View's selection group and act upon it.

Also, there is no global selection group. 

Plugin Manager

The Plugin Manager (PM), well, manages plugins.

There are two steps required to use plugins.

The first is the plugin configuration file. This is a simple text file with details on where the plugin is stored, who the developer is and other plugin specific information that the developer has added.

This file must be stored in '~/Library/Application Support/DirTree/'.

The file must have the '.dtcfg' extension. It can be edited and read by any text editor.

The second is the placement of the plugin itself. The plugin itself can, theoretically, be stored anywhere. Even remotely.

For the initial release, the plugin must reside "locally". (AFP and Samba mounts are respected).

The default location is '~/Library/Application Support/DirTree/DTPlugs', though it can be stored anywhere.

The configuration file will contain a path or partial path of where it is supposed to go followed by the full name of the plugin. Partial paths are relative to '~/Library/Application Support/DirTree/'.

The developer should have given instructions of where too put it. You can edit the configuration file yourself and change it's location. If you do, it is important you do not change the last component of the path. This is the name of the plugin.

Example from configuration file that came with DirTree:

Plugin_Path:DTPlugs/DTBundlePlugin.bundle

Plugin is stored in '~/Library/Application Support/DirTree/DTPlugs' and is named 'DTBundlePlugin.bundle'.

Changes:

Plugin_Path:~/Documents/DTPlugs/DTBundlePlugin.bundle

Plugin is stored in '~/Documents/DTPlugs/' and is named 'DTBundlePlugin.bundle'.

Plugin_Path:/Users/tridiak/Documents/DTPlugs/DTBundlePlugin.bundle

Plugin is stored in '~/Documents/DTPlugs/' and is named 'DTBundlePlugin.bundle'.

Plugin_Path:DTBundlePlugin.bundle

Plugin is stored in '~/Library/Application Support/DirTree/' and is named 'DTBundlePlugin.bundle'.

Plugin Management Window

This is the PM window:

The left-hand list is a list of plugins collected from configuration files.

The right-hand list is a list of functions a seleted plugin has.

The 'rejection reason' strip is why a plugin cannot be used. It can vary, but possibilities are OS version, DirTree version, bad configuration file & the plugin is not where the configuration file says it is.

This shown example is the plugin that will be shipped with DirTree.

The bottom box gives details about the plugin and the developer. Details concerning the functions themselves are dealt with in their own dialogs.

The Description button toggles between a short description and a long description.

The Developer button gives details about the developer.

Plugins belong in one of five states:

• Unavailable

• Available

• Inactive

• Activated

• In Use

Unavailable usually means the plugin cannot be used for some reason. Why varies. The PM may drop a plugin down to this state if the plugin misbehaves or if it abruptly becomes unavailable.

Available means the Plugin is available. The plugin has NOT beed loaded or initialised yet. The user can initialise it as shown below.

The user can turn the plugin off by changing it's state to Available. (The PM can also do it itself when certain circumstances arise).

Inactive means that some or all of it's functions can be used. No function is is actually available until they are assigned.

Commands are added to or removed from Views.

Tools are added to or removed from the Tool menu.

Filters are added to a Filter list maintained by the PM. They are used by Views, some contextual menu functions and plugins.

If any of the listed functions are assigned, the plugin's state changes to activated. This is an indicator for the user.

It is possible to drop the state from Activated to Availabe, usually at anytime. Specific plugins may block for various reason.

If no function is assigned, the plugins state will drop to Inactive.

The final state, "In Use", indicates that the plugin is actively executing one or more of it's functions. Only the PM can raise or drop from this state. The user can't do it directly.

The user can do it indirectly by closing the View actively executing a function or cancelling the execution of the function if the plugin allows such as possibility.

The plugin may the block the state drop if cancelling the execution is difficult or dangerous.

Sample Plugin

The sample plugin has four functions:

• Zip  : a Tool that zips (without any options) the front-most View.

• Simple Filter : a filter that returns true if an object is a directory.

• Copy : unfinished Copy/Move command. Objects under select mode 0 (primary) are copied or moved to directories under select mode 1. For now it just lists objects under either select modes.

• Twiddle : used for debugging purposes. All it does is raise the plugin state to "In Use". It will display Chasing Arrows in one of the Status Strips.

Filter Window

A list of Filters that have been "assigned".

The left hand box is the filter list.

The right hand box is a description box for a selected filter.

If a plugin has preferences for a filter, the 'Prefs' button will bring it up.

The Primary filter is the one that is used by default (such as the Tree & Icon contextual menus options : Select By Filter). It is marked with 2 asterisks.

Tool Window

Similar to Filter window.

They 'key' column is the menu key for the tool.

It is editable and you can select almost any key.

It is important to note that the key combination is always Cmd-Shift-<key>. This cannot be changed. It is used to guarantee no conflicts with any DirTree menu key combinations.

Command Window

There may not be a Command window. Commands are View specific and I will (probably) implement a sheet displaying information about the current Commands in a View.

Feeback Note : I would like to know if people prefer the Tool/Command/Filter options be kept in separate windows or moved into the main Preference window under one (or three) of the tabs. I am open to other ideas on this.