# The jstools File Selector Panel

## Introduction

The jstools package provides a File Selector Panel, shared by several applications, which lets you select a file (or directory) name. It's typically used to specify file names to load data from or save data into. Some applications may use it for other purposes, such as to specify the directory to move a file into, or to choose a file to delete. Also, in some applications it may provide an option menu that lets you choose a file format.

The File Selector Panel is implemented by the jfs.tcl library; if you're a Tk programmer, you can use it in your own applications.

This document describes the File Selector Panel provided by version 4.0/4.0b of the jstools libraries.

## Usage

The File Selector Panel contains a scrollable file list on the left showing the files and directories in the current directory, some buttons on the right which let you choose what to do, and a field at the bottom of the panel - typically labelled `File:' - that lets you type a file or directory name. At the top, below a prompt, is a label which shows you the pathname of the current directory (the directory whose contents are displayed in the file list). There's also a checkbox which lets you control whether directories are distinguished in the file list.

### Buttons

Several buttons may be displayed along the righthand edge of the panel. Which buttons appear depends on how the filename you choose is going to be used, so different applications will provide different sets of buttons. (OK, Cancel, and Home are the most commonly available buttons.) The possible buttons are as follows:

#### OK

The OK button tells the application to use the current filename (which appears in the `File:' field at the bottom of the panel) if it is a file, or moves into it if it's a directory. Thus, the typical way to choose an existing file is to click on it in the file list and then click OK. (You can specify a new file name by typing it in the `File:' field and clicking OK.)

#### Cancel

The Cancel button tells the application that you don't want to perform the action for which the File Selector panel was brought up - e.g., you don't want to load a new file, or save the file you're working on.

Incidentally, you can always cancel by typing Control-c or Meta-period, even if the Cancel button isn't displayed (although if it's not, the application probably isn't prepared to cancel the operation).

#### Go Into

The Go Into button moves into the currentlyselected filename (assuming it's a directory). This is useful in some cases when the OK button isn't available.

#### Home

The Home button moves to your home directory.

#### Root

The Root button moves to the toplevel directory, ``/`'.

#### Here

The Here button tells the application to use the current directory (whose name appears near the top of the panel and whose contents are displayed in the file list).

The bottommost button is the default button, and appears with a sunken border around it. Pressing Return in the `File:' field, or doubleclicking in the file list, has the same effect as clicking on the default button (unless the currentlyselected filename is a directory). Usually, OK is the default button.

### The File List

The file list in the left part of the panel displays the contents of the current directory. At the top is the entry ``..`', which represents the parent directory. Beneath that are listed all the files (including subdirectories) in the current directory. Files whose name begins with a period appear after files whose name doesn't; other than that, files are sorted by ASCII collating order

Normally, directories in the file list have a trailing slash (`/`) appended so you can distinguish them from plain files. This can be slow in large directories (or in directories in certain kinds of filesystems), so you can turn it off by selecting the `Fast' checkbox in the upper right or the `Fast file selector' checkbox on the Global Preferences panel. (This option is saved the next time you save your global preferences.) Turning this option on means that you won't be able to distinguish directories from other kinds of files visually in the file selector, so you won't know in advance what doubleclicking on an entry in the list will do; for that reason, I recommend you leave it off if your machine is fast enough.

Clicking on a file or directory name in the file list selects it and copies it into the `File:' field at the bottom of the panel. Doubleclicking will then change directory into the selected file if it is a directory, or perform the action of the default button (typically OK) otherwise.

### The Filename Entry

At the bottom of the File Selector panel is an entry field labelled `File:' for typing a filename into. Whenever you (single)click on a file or directory name in the list, it will be entered into this field for you, but you can also type filenames here. (If you're creating a new file, of course, you'll need to type it's name; otherwise you can do everything with the mouse.)

## File Types

If the application lets you choose among several file types, an option menu will appear above the filename entry field. This will display the current file type, and if you click on it with mouse button 1, a menu will pop up that lets you choose among the available file types. Which types are available depends on the application.

``