# jprefs.tcl

## Introduction

The jprefs.tcl library is distributed as part of the jstools package. It consists of procedures to support application configuration files (written in Tcl) and user preference files (as Tcl code, but see Changes Since Version 3.6/3.0 below).

This document describes jprefs.tcl version 4.0/4.0.

## Usage

### Accessing the Library

In order to use the jprefs.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.

### Preferences and Preference Files

These procedures manage user preferences through the X and Tk defaults mechanism. They use Xstyle defaults files, but manage them internally, without requiring the user to edit them directly. They link X defaults and global arrays that an application can consult to see the current state of user preferences. By default, they use the global array `J_PREFS` and the file ~/.tk/defaults, both of which are intended to store crossapplication defaults.

### Global Preferences

The `j:read_global_prefs` procedure reads the standard jstools crossapplication preferences, most of which are used by the jstools libraries. You should make sure you read the user's global preferences, either by calling `j:read_global_prefs` or, better yet, by calling `j:jstools_init` (in jinit.tcl), early in your code; otherwise your application won't work consistently with other applications using the libraries, and some library procedures might not work at all. You should also give your users access to the jstools Global Preferences panel, which you can bring up with the `j:global_pref_panel` procedure in jprefpanel.tcl.

## Credits and Copyright

### Author

Jay Sekora

`js@calumet.org`

`http://shore.net/~js/`

### Copyright

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

## Overview

### Procedures

`j:source_config` - read user configuration from a file

`j:read_prefs` - read X defaults for preferences from file, set array

`j:read_global_prefs` - read common jstools preferences from ~/.tk/defaults

`j:read_standard_prefs` - alias for `j:read_global_prefs` (deprecated)

`j:write_prefs` - write X defaults for preferences to file from array

### See Also

jprefpanel.tcl

jbindentry.tcl

jbindtext.tcl

jinit.tcl

jldb.tcl

## j:source_config

### Usage

`j:source_config` [`-directory` directory]`` filename

### Argument

filename is the name of the file to source

### Option

`-directory` directory`` (default ~/.tk)

### Description

This procedure is used for reading configuration files. It sources the file filename, normally in the user's .tk directory but in directory if specified. The file is sourced in the context of the calling procedure, so any variables set by the sourced file will be visible to the procedure calling `j:source_config` (and if they're global in the calling procedure, they'll be global to `j:source_config` as well).

## j:read_prefs

### Usage

`j:read_prefs` [options]`` defaults

### Options

`-array` array`` (default `J_PREFS`) - array to read defaults into

`-directory` dir`` (default ~/.tk) - directory file is in

`-file` file`` (default defaults) - defaults file to read

`-prefix` prefix`` (default `{}`) - prefix to keys in array

### Argument

defaults - list of `{`option`` default`}` sublists

### Example

`j:read_prefs -array BROWSERPREFS -file jbrowser-defaults {

{fancy 0}

{lbwidth 20}

{lbheight 20}

{lbfont default}

}

`[...]`

if $BROWSERPREFS(fancy) {

` [...]`}

`

`set mode READONLY`

j:read_prefs -array TESTPREFS -file test-${mode}-defaults \

-prefix $mode {

{always_ask 1}

{keep_backups 1}

}

[...]``

if $TESTPREFS($mode,always_ask) { [...]`}`

### Description

This procedure reads an Xstyle defaults file, and extracts each specified option from it into the array array. If a particular option doesn't occur in the defaults file (or the defaults file doesn't exist at all), the corresponding default is used instead. The file name will be defaults.tcl unless file is specified, and it will be searched for in ~/.tk unless directory is specified.

If file is specified, it will have a .tcl suffix tacked onto it to produce the actual file name.

As a special case, if an option is `tk_strictMotif`, then the `tk_strictMotif` global variable will be set as well as the `tk_strictMotif` element in array.

If prefix is specified and nonnull, it (plus a comma) is prepended to each preference name, so that for instance you can specify ``-prefix friend`' and access preferences (and array indices) like ``friend,name`', ``friend,age`', etc. (This mechanism is used by `jedit` for modespecific preferences, with prefix being the name of the mode.)

## j:read_global_prefs

### Usage

`j:read_global_prefs`

### Description

This procedure reads a standard set of defaults from the file ~/.tk/defaults, and sets the corresponding elements of the `J_PREFS` global array (and the `tk_strictMotif` global variable). It's a shorthand for using `j:read_prefs` with a particular fixed set of defaults.

Currently, the standard defaults handled (and the hardwired values used if they don't occur in ~/.tk/defaults) are:

`language` (default `en`) - ISO code for language to display text in

`autoposition` (default `0`) - whether to centre popup panels

`bindings` (default `basic`) - keyboard bindings (`emacs`, `edt`, `vi`, or `basic`)

`typeover` (default `1`) - whether typing replaces the selection

`confirm` (default `1`) - whether to confirm before certain actions

`printer` (default `lp`) - name of preferred printer

`scrollbarside` (default `right`) - which side of windows scrollbars are on

`visiblebell` (default `1`) - whether to flash the window to simulate a bell

`audiblebell` (default `1`) - whether to ring the display's bell

`j_fs_fast` (default `0`) - if `1`, don't `stat`(2) files in file selector list

`tk_strictMotif` (default `0`) - if `1`, don't hilight active widgets

Many of these are used by other procedures in the jstools libraries (or by Tk itself), but some of them have to be handled by your application. In particular, `bindings` has to be processed by your application. There are procedures in the jbindtext.tcl and jbindentry.tcl libraries to make it easy to set up bindings. The simplest way to read users' global preferences and set up keyboard bindings appropriately, though, is to call `j:jstools_init` early in your code; that procedure calls `j:read_global_prefs`, and then sets up bindings appropriately.

In version 3.6/2.0 of jstools, this procedure was called `j:read_standard_prefs`, and that name is still supported for backwardscompatibility. (Don't rely on it staying, though.)

## j:write_prefs

### Usage

`j:write_prefs` [options]

### Options

`-array array` (default `J_PREFS`) - array to read current values from

`-directory dir` (default ~/.tk) - directory defaults file is in

`-file file` (default `defaults`) - defaults file to write

`-prefix` prefix`` (default `{}`) - prefix to keys in array

### Examples

`j:write_prefs -array BROWSERPREFS -file jbrowser-defaults

`

`j:write_prefs -array TESTPREFS \`

-file test-${mode}-defaults -prefix $mode

### Description

This procedure is used to save user preferences. By default, it writes all elements of array array which do not have a comma in their names into a preference file. The file name will be defaults.tcl unless file is specified, and it will be put in ~/.tk unless directory is specified. The directory is created if necessary (and possible).

If file is specified, it will have a .tcl suffix tacked onto it to produce the actual file name.

If prefix is specified and nonnull, then it writes all elements of array whose names start with prefix followed by a comma. For instance you can specify ``-prefix friend`' and write preferences (and array indices) like ``friend,name`', ``friend,age`', etc. (This mechanism is used by `jedit` for modespecific preferences, with prefix being the name of the mode.)

## Bugs and Misfeatures

* The `-prefix` option to `j:read_prefs` and `j:write_prefs` seems like a kludge to me. I put it in because I didn't want to have to have separate procedures in `jedit` just to read and write modespecific preferences.

## Future Directions

* `j:source_config` should take a path of directories to search for the file in, to make things like sitewide defaults easier. Perhaps the same is true of `j:read_prefs` and `j:write_prefs`.

``