mrparameter__define.pro


Name:
mrparameter
Methods:
Constructor
mrparameter::init           : constructor, 2nd part

Public variables (get)
mrparameter::name           : returns the name of this parameter
mrparameter::type           : returns its type, 'int', 'real' or 'string'
mrparameter::limits         : return lower/upper limits and step size
mrparameter::validValues    : return them (as array)
mrparameter::size           : returns the the number of elements

Public variables (set)
mrparameter::set            : set the parameter value(s)
mrparameter::get            : return the parameter value(s)
mrparameter::setLimits      : set lower/upper limits and step size
mrparameter::setValidValues : for discrete or text parameters
mrparameter::setSize        : sets the number of elements
mrparameter::check          : check validity of current value(s)

Private methods
mrparameter::dump           : dump object to screen (for debugging)
mrparameter__writedtd       : static method, writes part of DTD
mrparameter::write          : write object content to file in XML format
mrparameter__define         : constructor, 1st part
mrparameter::cleanup        : the destructor
Description:
An object to hold a numerical or character parameter with 1 or
more elements identified via a name.
mrparameter is meant to be used with mrparameterset__define.pro.html#mrparameterset>mrparameterset which acts
as a container for a group of parameters belonging together.

Name:
mrparameter::init
Syntax:
obj = obj_new('mrparameter', name, type, size)
Arguments:
name
The name of this parameter. Parameter names within a parameterset
serve as a key, and thus have to be unique.
type
String denoting the type of the parameter. One of 'int', 'real' or
'string', default is 'real'.
size
The number of values stored in this parameter. May be changed
dynamically explicitly (via the setSize method) or implicitly by
adding a large value set. Default size is '1'.
Description:
Create a new mrparameter object with name 'name'.
Once a parameter object is created, it cannot change name nor type.

Name:
mrparameter::cleanup
Description:
The destructor

Name:
mrparameter::set
Syntax:
obj->set, value, position=pos, /delete
Arguments:
value
Single value or value array of the correct type
position
An integer denoting the position at which to set (or start, if
'value' is an array) the variables.
delete
Delete currently set values, before possibly setting new ones.
The method may be used with only the /delete keyword set, to
clear all values. This will of course not change the size of the
parameter.
Description:
Sets mrparameter value or values. If the parameter holds more than
a single value, the value array or a subarray can be set at once,
starting at position 'position'.
If there's more values than would fit in the current parameter set,
the size is automatically enlarged to fit the extra values.
There's no type checking - the method will crash if string values are
assigned to a parameter of numeral type.

Name:
mrparameter::get
Syntax:
result = obj->get( position=pos )
Arguments:
position
Element position whose value to return
Description:
Return the element at position 'position'.
If pos is not specified, all values (i.e. a single value or an array)
will be returned.
If position points at an invalid position, a 'message' is thrown.

Name:
mrparameter::name
Syntax:
result = obj->name()
Description:
Return the parameter's name

Name:
mrparameter::size
Syntax:
result = obj->size()
Description:
Return the number of elements of the parameter

Name:
mrparameter::setSize
Syntax:
obj->setSize, size
Arguments:
size
Integer, denoting the number of elements of the parameter.
Description:
Sets the number of elements for the parameter. This might enlarge
or shrink the current parameter - accordingly parameter values might
get lost. When enlarging, the extra parameters are set to 0, 0. or ''
respectively.

Name:
mrparameter::type
Syntax:
result = obj->type()
Description:
Return parameter type as string, i.e. one of 'int', 'real' or 'string'

Name:
mrparameter::setLimits
Syntax:
obj->setLimits, low=low, up=up, step=step, error=err
Arguments:
low
Integer or real (depending on the type) specifying the lower limit
up
Integer or real specifying the upper limit
step
Integer or real specifying the step size (meant for UIs)
error
Setting new limits might render currently set values out of bounds.
If the error keyword is set, the method will call mrparameter::check
and set the assigned variable to '1', in case the check failed.
See also mrparameter::check
Description:
Set the mentioned values - parameter objects of type 'string' don't
support this method and return immediately.

Name:
mrparameter::limits
Syntax:
obj->limits, low=low, up=up, step=step, error=err
Arguments:
low
If specified, the assigned variable is set to the lower limit
up
If specified, the assigned variable is set to the upper limit
step
If specified, the assigned variable is set to the step size
error
If set, the assigned variable upon return holds a bitmap of undefined,
but requested values
Description:
Return limits and step size.
Request for undefined limit values (i.e. values were not set via
setLimits before) are ignored. The corresponding bit in 'err' is
set to '1' where bit1 = low, bit2 = up, bit3 = step.
Parameter objects of type 'string' do not support this method and
return immediately. Error is set to '-1' in that case.

Name:
mrparameter::setValidValues
Syntax:
obj->setValidValues, values, /delete, error=err
Arguments:
values
Single value or array of values of the correct type.
[Values] might be omitted - e.g. when deleting currently set
valid values a la obj->setValidValues, /delete
delete
If set to '1', the current list of valid values will be deleted
before adding the new ones. Default is to append to the list.
Using only delete without setting any values may be used to
clear the list of valid values.
error
Setting a valid value list may render currently set parameter values
invalid. If the error keyword is set, the method will call
mrparameter::check and set the assigned variable to '1', if the check
failed.
Description:
Define or append to a list of valid values the parameter may have.
Values are character or numerical constants depending on the parameter
type. There's no check for uniqueness (yet).

Name:
mrparameter::validValues
Syntax:
result = obj->getValidValues( count=count )
Arguments:
count
If set, contains the number of valid elements in result upon return.
Description:
Returns a pointer to an array of valid values or ptr_new() if none set

Name:
mrparameter::check
Syntax:
result = obj->check()
Description:
Returns '1', (=TRUE) if check passed, else '0'.
If a list of validValues is available the method will check against
this list, otherwise it will check for upper and lower limits.

Name:
mrparameter::dump
Syntax:
obj->dump
Description:
dump the contents of this parameter object - meant for debugging only

Name:
mrparameter__writedtd
Syntax:
obj->write, unit
Arguments:
unit
Logical unit to write to. This is a 'static' method.
Description:
Write the part of the DTD that builds a single parameter

Name:
mrparameter::write
Syntax:
obj->write, unit, /valuesonly
Arguments:
unit
Logical unit to write to
valuesonly
If set, write only values, but no limits and valid value lists.
Default is to write all.
Description:
Dump the content of a parameter object to file.

Name:
mrparameter__define
Description:
Private Procedure (constructor)

Last modified: Mon Nov 29 13:30:07 2004