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