Task Template for IDL 8.7
This topic describes the fields (also called keys) in a task template for use with IDL 8.7.
Task Keys
This table describes the keys that provide an overview of the task. Refer to IDLTask for additional details.
|
Key |
Required |
Description |
|
name
|
Yes, if storing the task definition to disk
|
A string with the name of the task. This name is used when calling the IDLTask function to create an instance of the task. The name of the task file must match the value of this key and must be a valid IDL variable name.
|
|
base_class
|
Yes |
A string with the name of the class to use; the most common is IDLTaskFromProcedure.
|
|
schema
|
Yes |
A string containing the schema of the task definition. The schema is: idltask_1.1 . IDL will support this schema in future releases if a new schema is introduced.
|
|
routine
|
Yes, when used with IDLTaskFromProcedure
|
The routine that is called when Task.Execute is invoked.
|
|
display_name
|
No |
A string with the name of the task for display purposes. Spaces and special characters are allowed.
|
|
description
|
No |
A string with a description of the task.
|
|
revision
|
No |
A string with the semantic revision number of the task. Semantic versioning provides a quick way to extract information about a new task release using a convention of X.Y.Z, where:
- X represents the major version. An incremented value indicates that task additions and updates are not backward-compatible.
- Y represents the minor version. An incremented value indicates that task additions and updates are backward-compatible.
- Z represents the patch number. An incremented value indicates bug fixes that do not affect the task.
The revision key is for development purposes only. The revision number does not affect which task file is loaded. Whichever task file is found first will be used. If revision is not set, it will default to a value of 1.0.0.
|
|
parameters
|
No |
A LIST of HASHs of key/value pairs, described in the Parameter Keys table below.
|
Parameter Keys
This table describes the keys that belong to the parameters group in a task definition; these are repeated for each parameter. Depending on the parameter type, there can be additional keys. Refer to the IDLParameter* topics to find out specific information about a given parameter. The mapping of the parameter properties to the task definition is 1:1, if the parameter property name is TEST_EXACT then the task definition key is test_exact.
|
Key |
Required |
Description |
name
|
Yes |
The name of the parameter as it appears to the end user. This key must be a valid IDL variable name.
|
type
|
Yes |
A scalar string indicating the parameter type to use on creating an instance of the task.
Basic scalar data type string values are:
BYTE, INT, UINT, LONG, ULONG, LONG64,ULONG64, FLOAT, DOUBLE, COMPLEX, DCOMPLEX, STRING, BOOLEAN, LIST, HASH, DICTIONARY, ORDEREDHASH
Basic array data types must include the dimensions key and type string values are:
BYTEARRAY, INTARRAY, UINTARRAY, LONGARRAY, ULONGARRAY, LONG64ARRAY,ULONG64ARRAY, FLOATARRAY, DOUBLEARRAY, COMPLEXARRAY, DCOMPLEXARRAY, STRINGARRAY, BOOLEANARRAY
The type key value can be set to a class name to indicate that the user must provide an object of the given class name.
|
dimensions
|
No for scalar, Yes for array
|
A scalar string specifying the required dimensions for a parameter, if type specified is an *ARRAY type.
If the number of elements in any dimension does not matter, then use an asterisk ('*') for that dimension.
- 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]"
|
keyword
|
No |
The internal keyword that the parameter should map to when invoking the routine. If it is the same as the name key, then you do not need to create this key. |
display_name
|
No |
A string with the name of the parameter for display purposes. Spaces and special characters are allowed.
|
description
|
No |
A string with a description of the parameter. |
direction
|
No |
Specify if the parameter is input or output. If this key is not set, then direction defaults to input.
|
required
|
No |
A boolean value that indicates whether the parameter is required or not. The default is false, which allows the parameter to be optional.
|
default
|
No |
The default value of the parameter if the end user does not provide a value.
|
hidden
|
No |
A boolean value that indicates whether the parameter is visible to the user or not. The default is false, which means the user can see it and set its value. Set this key to true to prevent the user from seeing the parameter or changing its value. You must also set the default key to the desired value.
|
additional keys
|
No |
Depending on the parameter there may be additional keys available to define. For example for a type set to STRING, there is fold_case and choice_list. You could use the QueryProperty static method on the given parameter class to discover the available keys:
IDL>print, IDLParameterString.QueryProperty()
|
Revision History
This section summarizes the updates to task templates, compared to the previous release:
- The revision key was introduced in 8.7.
See Also
Task Schema History, Custom IDL Tasks