# jfs.tcl

## Introduction

The jfs.tcl library is distributed as part of the jstools package. It creates a generalpurpose modal fileselection panel that allows the user to select a file (or directory) and returns its full pathname.

This document describes jfs.tcl version 2001.02.10.

## Usage

### Accessing the Library

In order to use the jfs.tcl library, it (and any other libraries it depends on) must be in your Tcl `auto_path`, described in `tclvars`(n). Information about how to arrange that, and other conventions common to the jstools libraries, is in the Usage section of The jstools Libraries.

## Credits and Copyright

### Author

Jay Sekora
`js@aq.org`
`http://www.aq.org/~js/`

### Copyright

The library is copyright © 1992-2001 by Jay Sekora, but may be freely redistributed under the conditions at the top of the file.

## Overview

### Procedures

`::jstools::fs` - file selection panel

## ::jstools::fs

### Usage

`::jstools::fs` [options]

### Options

`-buttons` buttonlist`` (default `{ok cancel mkdir home}`)
`-prompt` prompt`` (default `Choose a file`)
`-directory` dir`` (default `.`)
`-cancelvalue` cancelvalue`` (default `{}`)
`-fileprompt` fileprompt`` (default `File:`)
`-title` title`` (default `File Selector`)
`-types` typelist`` (default `{}`)
`-typevariable` typevar`` (default `{}`)
`-typeprompt` typeprompt`` (default `File type:`)
`-filehistory` filehistory`` (default `fs_files`)

### Examples

`set filename [::jstools::fs -prompt "Save as:"]
set dirname [::jstools::fs -buttons {here cancel home root} \
-prompt "Change directory to..."]`
`
set outfile [::jstools::fs -prompt "Save as:" \
-types {sc oleo "Tab-separated values" "HTML table"} \
-typevariable format -typeprompt "Spreadsheet format:"]
set settings [::jstools::fs -prompt "Save settings to:" \
-dir $env(HOME)/settings \
-filehistory settings`

### Note

In previous versions of the library, the arguments to `-prompt`, `-fileprompt`, `-title`, and `-typeprompt` were automatically localised. In this version they are not.

### Description

This procedure creates a fileselection box with a configurable set of buttons, a label containing prompt at the top, a listbox showing the files in the current directory, and an entry labelled fileprompt at the bottom that lets the user type in a file name. The user can select an existing file either with the mouse or from the keyboard, and the entry supports filename completion with the Tab key. (A new file name, of course, has to be typed in.) The windowmanager name of the panel will be title.

The file selection panel has a number of predefined buttons, and you can choose which ones appear using the `-buttons` option. The first button in buttonlist will be the default button, and pressing Return in the entry widget or doubleclicking in the listbox will do the same thing as clicking on this button (unless the current file name is a directory, in which case it will switch to that directory). If the `-buttons` option is not specified, the `ok`, `cancel`, `mkdir`, and `home` buttons will be displayed (and `ok` will be the default button).

The available buttons and their functions are:

- `ok` - Return the current filename if it is a file; `cd` to it if it's a directory. This is the typical way to select a filename
- `gointo` - `cd` to the current filename, if it's a directory. This is useful when`here` is the default button.
- `home` - `cd` to the user's home directory.
- `root` - `cd` to the root directory.
- `here` - Return the name of the current working directory. This can be used, for instance, to choose where to move a file to.
- `mkdir` - Ask for the name of a directory to create, create it, and `cd` into it. Useful when the user is saving a file and wants to create a new subdirectory to save it in.
- `cancel` - Return cancelvalue.

Unless filehistory is the null string, filehistory will be used as the name of a history list (see jhistory.tcl) associated with the filename entry widget at the bottom of the panel. Two buttons with arrows will be displayed next to the entry field. Clicking the uparrow button or pressing the up arrow on the keyboard will go up (back) in the history list. Clicking the downarrow button or pressing the down arrow on the keyboard will go down (forwards) in the history list. The currentlydisplayed value will be added to the history list whenever a noncancelvalue value is returned (e.g. when the user clicks the OK button). This makes it easy for the user to access frequentlyused files.

If `-types` and `-typevariable` are specified, an option button, labelled typeprompt, will be displayed that lets the user choose among the file types in typelist. The `::jstools::fs` procedure will set the variable typevar in the caller's scope to the element of typelist that the user selected. This is intended to let the user select a file format for saving, although it could conceivably be put to other uses.

Unless the global variable `J_PREFS(j_fs_fast)` is true, directory names in the listbox will have a trailing slash (`/`). The user can set this with a small checkbox at the upperright of the fileselection panel (as well as from the Global Preferences panel created by j:global_pref_panel, in jprefpanel.tcl).

Keyboard shortcuts for the Cancel button are set up using `::jstools::cancel_button` in jtkutils.tcl, even if it doesn't appear in buttonlist. This means that the user can always cancel (returning cancelvalue) by typing (e.g.) Control-c, even if you didn't include `cancel` in buttonlist.

Note that while `::jstools::fs` may change the working directory while it's active (i.e., when the user goes into a directory, `::jstools::fs` `cd`s into that directory to display its contents), it restores the original working directory before it returns. Since `::jstools::fs` is modal, this means that you don't have to worry about your application changing directory unless you explicitly do a `cd` yourself. (This behaviour is different from that of previous versions.)

## Bugs and Limitations

- The value given by `[pwd]` isn't always the most appropriate way to refer to a directory, for instance if the automounter is being used.
- It's nonorthogonal that `::jstools::fs` returns the filename as the procedure's return value, but returns the file type in a variable as a sideeffect. I can't think of a better way to do it, though, since I want the common case (not specifying a list of file types) to be as terse and intuitive as possible.

## Future Directions

- More buttons should be available for `::jstools::fs` - one that springs to mind is a `preview' button. Also, there should be a way for the calling procedure to add arbitrary buttons to the `::jstools::fs` panel.

`
`