Class ::tycho::Preferences


Inherits: ::tycho::Parameters - Related constructs - Source File - Contents: public methods - protected variables
A Preferences object maintains a set of preferences, and is used to build a complex set of user and system preference settings. It does not have any user interface components -- that is the job of another widget. Preferences inherit from the Parameters widget, and can thus be organized hierarchically. In addition, a user-interface widget for viewing and editing preferences can be generated automatically -- see the "PreferenceEdit" widget.

Preferences extends Parameters with a "subscribe-and-publish" model to update widgets that require the value of a preference. The recommended method of keeping a widget up to date is by have it call the subscribe method, which causes a specified option of the widget to be updated whenever the value of the preference changes. There are two other methods of accessing preference values: a client can simply read it (there is no automatic update with this method), and an arbitrary script can be executed whenever a preference changes.

FIXME: Use "Default" instead of null string.

The preference class has one very deliberate restriction: the value of a preference cannot be the null string. Setting a preference to a null string means "Use the default value." If the preference set has a parent, the preference value will be whatever the parent thinks it is; if not, and the preference value for each widget that is subscribed via a configuration option will be that widget's default value of the option. If there is no parent, then widgets that are subscribed by command are... um... in trouble. FIXME. This is useful for two things: first, you don't have to specify the value of preferences: just set them to {} and let Tk choose sensible defaults. Second, it allows a lot of flexibility in allowing preferences to be selectively overridden by the user.


Public constructs

Public Methods

commandsubscribe key args
Subscribe to a preference for update with a command. The first argument is a key that is needed only for unsubscribing later. The second argument is a script that will be applied with three arguments when a preference is updated: the key, the preference name, and the updated value. The third argument is a list of preferences to which to subscribe.

Note the command is not called when subscribing.

commandunsubscribe key name
Unsubscribe a command from one or more preferences. If there are no arguments, then the command is unsubscribed from all preferences with a matching key. If there are arguments given, unsubscribe only from the given preferences.
exclude widget args
Exclude one or more options of a widget from the subscription mechanism. The argument list is assumed to be a flat list of option-value pairs, just as passed to a widget. Once excluded, requests to subscribe an option on the given widget will be ignored; if the option has already been subscribed, then it is unsubscribed and the value set back to the excluded value.
subscribe widget args
Subscribe to a preference using widget options. The first argument is the widget that is subscribing. Following arguments are option-preference pairs -- that is, the name of the widget option followed by the name of the preference with which it will be updated. At the time of subscription, there is no check that the requested parameters are valid, in order to keep subscriptions costs to a minimum.

If the widget is already subscribed to a given parameter, then change the option with which it is subscribed.

Before returning, this method updates all the subscribed options with the current values (unless the value is UNKNOWN, in which case nothing happens).

unsubscribe widget args
Unsubscribe a widget from one or more preferences. If there are no arguments, then the widget is unsubscribed from all preferences: this should be called in the widget's destructor. In addition, all exclusions will be deleted.

If there are arguments given, unsubscribe only from the given preferences and don't change the exclusions.

unsafeassign name value
Set a preference to a new value, updating all subscribers. Generate an error if the preference doesn't exist in this set.

This method performs no error or range-checking.

update name value
Update subscribers to a given parameter. The update is propagated down the preference tree.

Protected constructs

Protected Variables

commandsubscribers
Each preference has zero or more commands to execute when updated.
subscribers
Each preference has zero or more subscribers.
exclusions
Some options may be excluded from potential subscribers.

Index of classes



Author: John Reekie
Version: @(#)Preferences.itcl 1.18 12/05/96
Copyright: (c) 1995-1996 The Regents of the University of California.