Each IDLTask is defined by a set of parameters. Each has constraints on data type, values, etc. The IDLParameterUintArray is used when an IDLTask has a parameter defined as type of UINTARRAY.
Syntax
Result = IDLParameterUintArray( [, Properties=value])
Properties
Properties can be set as keywords to the function during creation, or retrieved using the "." notation after creation. The NAME property is required on initialization. The VALUE property is the only property that can be updated after creation.
CHOICE_LIST, DEFAULT, DESCRIPTION, DIMENSIONS, DIRECTION, DISPLAY_NAME, INCLUSIVE_MAX, INCLUSIVE_MIN, MAX, MIN, NAME, REQUIRED, TEST_EXACT, TEST_OVERFLOW, TYPE, VALUE
Methods
Dehydrate
Hydrate
Validate
Return Value
Returns a reference to a newly-created object.
Properties
CHOICE_LIST
An array that lists the possible values for the parameter. The default is !NULL. The values of CHOICE_LIST can be an array of scalars or an array of arrays that conform to the parameter’s TYPE and DIMENSIONS properties. Validation of the CHOICE_LIST is done by validating each element in the array or validating the slice along the last dimension. In the task template this is defined with the "choice_list" key.
The following are examples of two options available in defining a CHOICE_LIST for a parameter with TYPE=’BYTE’ and DIMENSIONS=[3].
The first example has the CHOICE_LIST property set to the following:
CHOICE_LIST = [[255,0,0], [0,255,0], [0,0,255]]
The above allows the user of the parameter to set VALUE to the following:
param.Value = [255,0,0]
or
param.Value = [0,255,0]
or
param.Value = [0,0,255]
The second example has the CHOICE_LIST property set to the following:
CHOICE_LIST = [0,255]
The above allows the user of the parameter to set VALUE to any combination that contains 0 and 255. That provides 8 options: [0,0,0], [0,0,255], [0,255,255], [255,255,255], [255,255,0], [255,0,0], [0,255,0], [255,0,255].
param.Value = [0,0,0]
or
param.Value = [255,0,255]
etc...
DEFAULT
The default value of the parameter. The default is !NULL. The values of this property must adhere to the TYPE property. In the task template this is defined with the "default" key.
DIMENSIONS
The dimensions of the array which is required on initialization. The dimensions can be specified with array of integers or a scalar string. If the number of elements in any dimension does not matter, then use a string value of an asterisk ('*') for that dimension. In the task template this is defined with the "dimensions" key and is required.
- Example of a three-element array declaration: [3]
- Example of a 1D array with any number of elements: '[*]'
- Example of a 2D array with any number of columns or rows: '[*, *]'
- Example of a 2D array with a specific number of elements: [3, 256]
- Example of a 2D array with any number of columns and 3 rows: '[*, 3]'
DESCRIPTION
A string describing the purpose of the parameter with respect to the task. In the task template this is defined with the "description" key.
DIRECTION
A string describing if the parameter acts as "INPUT" or "OUTPUT". In the task template this is defined with the "direction" key. The default is "INPUT".
DISPLAY_NAME
A string for the display name of the parameter that could be used to build a user interface. It can contain spaces and special characters. In the task template this is defined with the "display_name" key. If not set, the value will default to the NAME property's value.
INCLUSIVE_MAX
A boolean value that indicates whether a parameter can equal MAX or not. The default is 1, which allows the value to equal MAX. In the task template this is defined with the "inclusive_max" key.
INCLUSIVE_MIN
A boolean value that indicates whether a parameter can equal MIN or not. The default is 1, which allows the value to equal MIN. In the task template this is defined with the "inclusive_min" key.
MAX
The maximum allowed value of the parameter. In the task template this is defined with the "max" key.
MIN
The minimum allowed value of the parameter. In the task template this is defined with the "min" key.
NAME
The name of the parameter which is required on initialization. The parameter’s value can be set and retrieved from the IDLTask using "." dot notation using this name. The name can also be used in the IDLTask::Parameter method to retrieve the parameter object. NAME must be a valid IDL variable name. In the task template this is defined with the "name" key. Use DISPLAY_NAME for a better user interface label.
REQUIRED
A boolean value that indicates whether the parameter is required or not. The default is 0, which allows the parameter to be optional. In the task template this is defined with the "required" key.
TEST_EXACT
A boolean value that indicates whether floating point values that are not exact integers are accepted or not. The default is 0, which allows truncation of floating point value to the parameter's type. In the task template this is defined with the "test_exact" key.
TEST_OVERFLOW
A boolean value that indicates whether out of range values will generate an error or wrap around the integer range. The default is 1, for out of range values to generate an error. In the task template this is defined with the "test_overflow" key.
TYPE
In the task template when "type" key is defined as UINTARRAY, the IDLParameterUIntArray is created and populated with the key/value pairs defined in the template. The TYPE property returned is UINTARRAY.
VALUE
The current value of the parameter. The parameter's VALUE can be set at any time through IDLTask using "." dot notation using the NAME of the parameter, or directly on the parameter object.
IDLParameterUintArray::Dehydrate
The Dehydrate function method transforms the current parameter instance into a Hash containing keys to describe each of its properties. Any property that must conform to the TYPE property will be itself dehydrated by the IDLDehydrate function to ensure they are reduced to primitive form. The return value can be passed into the Hydrate function to clone the parameter instance, or it can be serialized for storage or transmission.
Syntax
Result = IDLParameterUintArray.Dehydrate([ERROR=error])
Return Value
A Hash comprised of IDL primitive values that describes this parameter and all its properties.
Keywords
ERROR
Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').
When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.
IDLParameterUintArray::Hydrate
The Hydrate static function method takes in a Hash of IDL primitive values and builds a new instance of this parameter class using all the dehydrated properties. It expects all property values to be properly dehydrated. This allows you to dehydrate a parameter and store the primitives, then restore it in a later IDL session.
Syntax
Result = IDLParameterUintArray.Hydrate( dehydratedForm [, ERROR=error])
Return Value
The result is a reference to a new instance of this parameter class.
Arguments
dehydratedForm
The Hash of IDL primitive values describing all of this parameter's properties in dehydrated form, to be transformed into a new instance of this parameter class.
Keywords
ERROR
Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').
When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.
IDLParameterUintArray::Validate
This Validate function method returns a Boolean value that indicates whether the Value passed to it is valid for the parameter. If the Value is invalid, then 0 is returned and the ERROR keyword will be populated with information on why the Value is invalid. This method allows the user to test the Value before setting the parameter’s Value and generating an error that must be handled by the user routine.
Syntax
Result = IDLParameterUintArray.Validate( value [, ERROR=error])
Return Value
The result is a Boolean value indicating if the Value is valid for the parameter.
Arguments
Value
The value to test for validity. On successful return this argument will be typecast to the parameter's TYPE.
Keywords
ERROR
Set this keyword to a named variable that will contain any error message issued during execution. If no error occurs, the ERROR variable will be set to an empty string ('').
When this keyword is not set and an error occurs, the function returns to the caller and execution halts. In this case, the error message is contained within !ERROR_STATE and can be caught using IDL's CATCH routine.
Version History