jprefs.tcl

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).

This document describes jprefs.tcl version 4.1/4.2.

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 by saving and reading automatically generated files of Tcl code. (Earlier versions of this library used X­style defaults files.) These files are managed internally; the user need not edit them directly. Users' preferences are stored in global arrays that an application can consult to see the current state of user preferences. By default, these procedures use the global array J_PREFS and the file ~/.tk/defaults.tcl, both of which are intended to store cross­application defaults.

Global Preferences


The j:read_global_prefs procedure reads the standard jstools cross­application 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.

(Many of the other jstools libraries make use of the preferences read by j:read_global_prefs, so users may see their effects even if you don't specifically check for them.)

Credits and Copyright

Author

Jay Sekora
js@aq.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 {pref 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 a preferences file, and extracts each specified pref from it into the array array. If a particular pref doesn't occur in the preferences 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.

(The format of file is a set of Tcl variable assignments, but you should not count on being able to put arbitrary Tcl code in the file, since it's rewritten whenever a user saves hir preferences.)

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

As a special case, if a pref 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 non­null, 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 mode­specific 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.tcl, 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.tcl) 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 backwards­compatibility. (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 non­null, 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 mode­specific preferences, with prefix being the name of the mode.)

j:pref:module

Usage

j:pref:module module options

Argument

module - the name of the module to create

Options

-label label (default Preferences) - localisable name for module
-panel panel (default main) - name of panel to display this module in
-array array (default J_PREFS) - array to store module's preferences in

Example

See j:prefe:create_pref for an example

Description

This procedure creates and registers a new preferences module module. It must be called before any actual preferences are registered with j:pref:create_pref. Preferences in module will be stored in elements of the array array.

If you use the jprefpanel.tcl library to create your interface, the user­interface components that allow the user to set preferences in module will appear on the panel named panel, which should be a legal Tk toplevel name. You should provide a (localisable) human­readable name for the module as label, which will be used as a title for the preferences in module.

j:pref:create_pref

Usage

j:pref:create_pref [pref module options]

Arguments

pref - the name of the global variable that stores this preference
module - the module to which this preference belongs

Options

-prompt prompt (default {}) - localisable label for this preference
-type type (default string) - kind of preference
-link link (default {}) - unimplemented
-text text (default {}) - unimplemented
-values values - permissible values for one­of­many preferences
-default default (default {}) - initial factory setting for this preference

Examples

j:pref:module printing \
-label Printing \
-panel .printing_prefs \
-array PRINT

j:pref:create_pref size printing \
-prompt {Font size:} -default 12
j:pref:create_pref font printing \
-type radio -prompt {Font:} -default
/Courier \
-values {
{/Courier Courier}
{/Times-Roman Times}
{/Helvetica Helvetica}
}
j:pref:create_pref landscape printing \
-type boolean -prompt {Landscape:} -default 0
j:pref:create_pref_panel .printing_prefs

Description

This procedure registers a new preference pref within module. The given module must already have been registered by a call to j:pref:module. The preference will be stored in the global array specified for module when the module was created; for instance, in the extended example above, with the name of the preference as the key; for instance, in the extended example above, the value of the font preference is stored in the global variable PRINT(font).

The prompt option is a human­readable label to be associated with the preference. The kind of preference is specified by type, which can currently be one of string, boolean, or radio.

If prompt is string (or unspecified), the value of the preference can be any arbitrary string. If it is boolean, the value can be true or false. If it is radio, the value can be one of a set of values provided by values.

The values option is an arbitrarily­long list of two­element sublists. The first element in each sublist is the value of the variable (i.e., a machine­readable setting for the preference); the second element is a label corresponding to it (i.e., a human­readable setting for the preference).

The default option provides a default value for the preference; if the variable corresponding to the preference does not already exist, it will be created and set to default.

Bugs and Misfeatures

Future Directions