<* PRAGMA LL *>

There are two user-actions, selecting and activating.

\begin{itemize}

\item The user may {\it select} items, either by single-clicking on an item to select just that one, or by single-clicking and dragging to select a range. Shift-clicking adds to the selection. A change in selection is reported to the client by invoking the selectItems method. The client can read the current selection by calling GetFile or GetFiles.

\item The user may {\it activate} an item, either by double-clicking on it, or by typing its name in the helper followed by Return.

Activation of a {\it file} is reported to the client by invoking the activateFile method, whose default is a no-op.

Activation of a {\it directory} is reported by invoking the activateDir method, whose default behavior is to call Set to display the activated directory.

The client can distinguish between a double-click and Return by looking at the AnyEvent.T passed to the activation method. A double-click will be reported as an AnyEvent.Mouse, and Return will be reported as an AnyEvent.Key.

\end{itemize}

Directories are indicated in the display by showing some text (e.g., ``(dir)'') after the name, but that is not part of the pathname returned by getValue, GetFile, GetFiles, or the value passed to activateDir.

A background thread calls Refresh(v) for every open filebrowser v, once per second, to see whether it needs to be updated (although a distributed filesystem may cause a substantial delay before the change is noticed).

FileBrowserVBT is internally synchronized.

INTERFACE FileBrowserVBT;

IMPORT AnchorSplit, AnyEvent, Font, ListVBT, PaintOp,
       Pathname, Shadow, TextList, TypeinVBT, VBT;

TYPE
  T <: Public;
  Public =
    ListVBT.T OBJECT
    METHODS
      <* LL.sup <= VBT.mu *>
      init (font                      := Font.BuiltIn;
            colors: PaintOp.ColorQuad := NIL           ): T;
      <* LL.sup = VBT.mu *>
      selectItems  (event: AnyEvent.T);
      activateFile (filename: Pathname.T; event: AnyEvent.T);
      activateDir  (dirname : Pathname.T; event: AnyEvent.T);
      error        (err: E);
    END;

The implementation calls v.selectItems(event) when the user changes the selection using the mouse.

When the user double-clicks on a file in the browser, the implementation calls v.activateFile(filename, event), where filename in the absolute pathname corresponding to the first selected item. If the user types Return in the helper, the implementation calls v.activateFile(filename, event), where filename is either the pathname in the helper, if that was absolute, or absolute pathname corresponding to

      Pathname.Join (GetDir(v), 'helper text', NIL)

The implementation calls v.activateDir(dir) when a directory is activated. The normal action is simply to set v to view that directory, relative to GetDir(v). If an error occurs during the activation, the error method is invoked.

The implementation calls v.error(...) when an error occurs during user action in v, and the Error exception cannot be raised (e.g., because it happened in a separate thread). Some examples of errors are as follows: the user has typed a nonexistent directory in the path; the current directory has become inaccessible; the user has no permission to read the directory. The default method is a no-op. By overriding this method, the client can provide better information to the user.

The error method is passed an E object containing information about the error that occurred. Here is its definition:

EXCEPTION Error (E);
TYPE
  E = OBJECT
        v   : T;
        text: TEXT       := "";
        path: Pathname.T := ""
      END;

The argument to the Error exception includes the FileBrowserVBT itself, along with a descriptive message and the pathname in question when the error occurred.

TYPE Selector <: ListVBT.MultiSelector;

The FileBrowser's helper (see page \pageref{FBHelper}) is a TypeinVBT. Once the user types in the helper, any selected items in the browser are unselected. If the user types Return in the browser, that will activate the name in the Helper.

If an error occurs during the activation, the error method of the filebrowser to which the helper is attached will be invoked.

TYPE Helper <: TypeinVBT.T;

PROCEDURE SetHelper (v: T; helper: Helper) RAISES {Error};
<* LL.sup = VBT.mu *>

Sets the helper for v to be helper, and fills it with GetDir(v).

The directory menu shows the name of each of the parent directories, going back to the root directory.

TYPE
  DirMenu <: PublicDirMenu;
  PublicDirMenu =
    AnchorSplit.T OBJECT
    METHODS
      <* LL.sup <= VBT.mu *>
      init (font             := Font.BuiltIn;
            shadow: Shadow.T := NIL;
            n     : CARDINAL := 0             ): DirMenu;
      <* LL.sup = VBT.mu *>
      setFont (font: Font.T);
    END;

PROCEDURE SetDirMenu (v: T; dm: DirMenu);
<* LL.sup = VBT.mu *>

Sets the directory-menu of v to be dm and fill it with the current directory.

A file browser can be ``read-only'':

PROCEDURE SetReadOnly (v: T; readOnly: BOOLEAN);
<* LL.sup = VBT.mu *>

Change the ``read-only'' mode of v to be readOnly.

      v.activateFile(filename)
   

By default all files in the directory are displayed, but the following procedure can be used to filter which files are shown:

PROCEDURE SetSuffixes (v: T; suffixes: TEXT);
<* LL.sup = VBT.mu *>

Specify which suffixes are to be displayed.

\subsubsection{Setting the displayed directory}

PROCEDURE Set (v       : T;
               pathname: Pathname.T;
               time    : VBT.TimeStamp := 0) RAISES {Error};
<* LL.sup = VBT.mu *>

Set the display state of v.

If pathname refers to a non-existent or inaccessible directory, Error will be raised. The exception will also be raised if pathname refers to a non-existent file and v is read-only.

If time is not zero and there is a helper, then the helper will take the keyboard focus and will display its new contents in replace-mode, ready for the user to type something in its place.

PROCEDURE Unselect (v: T);
<* LL.sup = VBT.mu *>

Put v into the no-selection state, without changing the current directory. Equivalent to v.selectNone().

PROCEDURE Refresh (v: T) RAISES {Error};
<* LL.sup = VBT.mu *>

Update the display without changing the directory.

\subsubsection{Retrieving selections from the browser}

PROCEDURE GetFiles (v: T): TextList.T RAISES {Error};
<* LL.sup = VBT.mu *>

Return the current selections of v, or NIL if there are no selections. The list includes ``full'' pathnames; they satisfy Pathname.Absolute, but they may contain symbolic links. Use FS.GetAbsolutePathname to get a pathname with no symbolic links.

PROCEDURE GetFile (v: T): Pathname.T RAISES {Error};
<* LL.sup = VBT.mu *>

Return the first selection, or the empty string if there are no selections.

PROCEDURE GetDir (v: T): Pathname.T;
<* LL.sup = VBT.mu *>

Return the current displayed directory of v. Returns an empty string if v is in the ``empty'' state.

END FileBrowserVBT.