::tycho::Object
-
Source File -
Contents:
public methods
- public variables
- protected variables
- protected common
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.
add
name value args
Remaining arguments are a list of option-value pairs, where the options can be any of:
-attributes
: An arbitrary list of attributes that can be attached
to the parameter. These are a flat list of name-value pairs, as in
{minimum 0 maximum 10}. The attribute
method provides a more
convenient interface.
-build
: A script that is executed to build
the parameter value if it is "UNKNOWN."
-convert
: A script that is executed to convert a preference
value into one understood by subscribers.
-default
: A default value of the parameter, which may be used by
some editors to "reset" the parameter.
The default
method provides a more convenient interface.
-description
: An informative description of the parameter.
The description
method provides a more convenient interface.
-edit
: A function (FIXME: What format?) that is used to edit
the parameter value.
-state
: Can be either "normal" or "disabled." If disabled, the
parameter cannot be altered.
-type
: The "type" of the parameter, from the following list:
string
: Can be any arbitrary value. This is the default, and
is assumed if no -type
variable is given.
data
: This is a nested parameters structure. There are a number
of options that are relevant only to this type -- see below.
number
: Constrained to be a number.
integer
: Constrained to be an integer.
boolean
: A boolean value.
choice
: A small set of (arbitrary) possible values. These
are intended for display by radiobuttons.
set
: A larger set of (arbitrary) possible values. These
are intended for display by an option menu.
custom
: Same as string, except that they are intended to
be displayed by some custom-made widget.
font
: A font value, specified as a list {family size
style}. The second and third elements can be omitted -- see FontManager
for details.
unknown
: This is used internally to indicate that the type
needs to be resolved later.
-updatecommand
: A script that is executed when the parameter
is updated.
-validate
: A function that is applied to a new parameter
value when it is set. If the function returns 0, then the parameter
is not set; if it returns 1, then the parameter is set and
-updatecommand
is executed.
-values
: A list representing the set of legal values of
the parameters. Valid for choice and set types.
The following options are relevant only to the data type:
-class
: The class of object which will be created to hold the
data. Defaults to Parameters.
-name
: The name of the object which will be created to
hold the data. If not supplied, one will be automatically
generated.
-file
: A file which will be read to initialize the new
object with data. If the file does not exist, then the data
contained in the object when it is destroyed will be written to
that file. If this option is not specified, then no data will be
saved.
assign
name value
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
current
name
description
args
-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
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
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:
depends
links if there
are any.
UNKNOWN
.
If the type is "data", then the returned value is successively:
-class
option
which is then initialized by -file
as long as it exists
-class
option
which is then initialized by -build
.
UNKNOWN
.
inherit
name args
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
describe
method.
names
{pattern {}}
parmcget
name option
parmconfigure
name {option {}} args
list
method.
traverse
start link init function combine
Example:
p traverse fred -depends UNKNOWN {p current %0} { if { [string match %0 UNKNOWN] } {return %1} else {return %0} }.
write
{filename {}}
-file
option, or to this one if not.
unsafeassign
name value
This method performs no error or range-checking.
checktype
name
-description
-file
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
-inherits
-children
-symname
_inherits
_attributes
_build
_class
_default
_depends
_description
_edit
_file
_name
_override
_state
_type
_updatecommand
_validate
_values
current
_children
_symname
_convert
parameteroptions
-attributes -build -default -description -edit -state \
-type -updatecommand -validate -values \
-class -name -file -override -depends -inherits -children \
-symname -convert