Class ::tycho::Parameters


Inherits: ::tycho::Object - Source File - Contents: public methods - public variables - protected variables - protected common
A Parameters object maintains a set of parameters. Parameters are essentially just name-value mappings, but with additional information attached to make it easier to manage complex sets of such parameters. Parameters can be hierarchical (a set of parameters can "override" another set of parameters), which turns out to be a surprisingly useful thing to do. They're used for managing user preferences (via the Preferences subclass) and for parameters of stars and targets in the Ptolemy interface.

Part of the information contained in a Parameters set is used to automatically construct a user interface for viewing and editing the parameter set (see ParameterEdit).

FIXME: Change the following paragraph: allow empty string and use the string "Default" to indicate that the default should be used.

The parameter class has one very deliberate restriction: the value of a parameter cannot be the null string. Setting a parameter to a null string means "Use the default value." If the parameter set has a parent, the parameter value will be whatever the parent thinks it is; if not, and the parameter 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 parameters: just set them to {} and let Tk choose sensible defaults. Second, it allows a lot of flexibility in allowing parameters to be selectively overridden by the user.


Public constructs

Public Methods

add name value args
Add a parameter to the parameter set. The first argument is the name by which the parameter will be referred to from now on. If the parameter already exists, an error is generated.

Remaining arguments are a list of option-value pairs, where the options can be any of:

The following options are relevant only to the data type:

.
assign name value
Set a parameter to a new value. Generate an error if the parameter doesn't exist in this set. (Note that inherited parameters are not updated.)

This method checks the value assigned to the parameter against its type and range. If the new value is not legal, the value is not updated and this method returns false, if it's OK, then the update command is executed and this method returns true. If the parameter is disabled, then the parameter is not changed and this method returns false.

converted name
Get the current value of a parameter after processing it with it's conversion function (if any). This is normally used for converting font specifications into system-dependent font descriptions, and so on.
current name
Get the current value of a parameter, without looking at the default or up the hierarchy. If the parameter does not exist, an error is generated.
description args
Get or set the description option of a parameter. With just one argument this method returns the description of that parameter; otherwise, the argument list is take as an alternating parameter-description list, and the -description option of each parameter is set to the corresponding description.

This method is provided as a cleaner interface to the description than parmcget and parmconfigure.

describe
Return a string that "describes" this object. The string can be passed to the load method of an empty object to exactly regenerate this object. If the string is passed to a non-empty object, then the result is (currently) unpredictable.

This method and its counterpart, load, are designed so that loading an object from a description string is much faster than creating it in the first place.

get name
Get the current value of a parameter, looking for inherited values if necessary. If the parameter does not exist, an error is generated.

This routine does some "behind-the-scenes" stuff to get data if it is not already in this object. If this object doesn't have the requested entry, then the "depends" links in the parent dataset are followed to find it. If the object does have an entry, then the behaviour depends on the type of the data: if it is simple data (that is, not another object), then the returned value is successively:

  1. The current value as long as it isn't "UNKNOWN"
  2. The default option if there is one.
  3. The value returned by the build script if there is one.
  4. The value returned by following depends links if there are any.
  5. UNKNOWN.

If the type is "data", then the returned value is successively:

  1. The current value as long as it isn't "UNKNOWN"
  2. The default option if there is one.
  3. A new object of the class given by the -class option which is then initialized by -file as long as it exists
  4. A new object of the class given by the -class option which is then initialized by -build.
  5. UNKNOWN.
.
inherit name args
Create a new parameter that inherits from an ancestor parameter set. Flags an error if this parameter set already contains that parameter or if there is no such inherited parameter. If the value argument is supplied, then the new parameter is set to that value, otherwise it is set to UNKNOWN so that it defaults from the inherited parameter.

Note: In order to avoid unnecessarily creating the inherited objects, this method does not access any of the data in those objects, but sets the type to "unknown" to indicate that the type must be resolved later. For the same reason, there is no check here that the parameter actually exists in a super class: rather, the error will become known when this parameter is accessed and a superclass containing it is not found.

load description
Load this parameter object with data. The passed description string must be one generated by the describe method.
names {pattern {}}
Get the parameters defined in this set. Note that this does not include inherited parameters. If the pattern argument is given, return only parameters that match it (glob-style).
parmcget name option
Get the value of a parameter configuration option. If the parameter is not defined in this set, look for an inherited one.
parmconfigure name {option {}} args
Get or set the value of one or more parameter configuration options. This works only on parameters that are defined in this parameter set -- to get their names, use the list method.
traverse start link init function combine
Traverse the specified link, applying a function at each node and returning the results.

Example:

p traverse fred -depends UNKNOWN {p current %0} { if { [string match %0 UNKNOWN] } {return %1} else {return %0} }.

write {filename {}}
Write all data in a preferences set to a file. Each contained data object is written to its own file if it has a -file option, or to this one if not.
unsafeassign name value
Set a parameter to a new value, and call the update script Generate an error if the parameter doesn't exist in this set. (Note that inherited parameters are not updated: the only way to change a parameter is to have access to its parameter set.)

This method performs no error or range-checking.

checktype name
Make sure that the type of the object is not "unknown.".

Public Variables

-description
A brief but informative description of the purpose of these parameters.
-file
A file that describes the parameters. This is a short-cut for creating a Parameters object, reading the contents of the file, and using load on it.

FIXME: We shouldn't be able to change this, since it is also reflected in the object that created this one...

-parent
The parent of this dataset.
-inherits
If inherits links are set up, add corresponding child links.
-children
FIXME: Get rid of this.
-symname

Protected constructs

Protected Variables

_inherits
FIXME: Get rid of this.
_attributes
Parameters can have arbitrary attributes.
_build
A script to build a parameter value.
_class
Nested data may have a class given.
_default
Some parameters have a default value.
_depends
A parameter may depend on another.
_description
Some parameters have an informative description.
_edit
A function to edit a parameter value.
_file
A file to load to build a parameter value.
_name
Nested data may have a name given.
_override
A parameter may be overridden by another -- this is the inverse of the depends option. FIXME: Need a better name.
_state
Each parameter has a state: normal or disabled.
_type
Each parameter has a type.
_updatecommand
A script to execute when the parameter is updated.
_validate
A function to validate a newly set parameter value.
_values
Some parameters have an allowable set of values.
current
Each parameter has a current value.
_children
_symname
_convert

Protected Common

parameteroptions -attributes -build -default -description -edit -state \ -type -updatecommand -validate -values \ -class -name -file -override -depends -inherits -children \ -symname -convert
The names of the parameter options.

Index of classes



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