Field Context

Context: HL Kit … Kit Reference  … Multiple Sources

Jump to: Target References

The "field" context represents any field within any pick or thing. If within a thing, all aspects of the field are read-only.

Context Transitions

From within a "field" context, you can utilize the following set of valid context transitions:

state	Transitions to the state context. Example: this.state
pick	Transitions to the pick context corresponding to the pick that contains the current field. Example: this.pick
chosen	Transitions to either the pick context corresponding to the user-selected pick stored within the field or the thing context corresponding to the user-selected thing stored within the field, depending on the nature of the field. The transition is only valid for use on fields that store menu selections made by the user. Example: this.chosen

Target References

There are a variety of ways to access and manipulate the contents of fields. The complete list of target references for fields is presented in the table below.

NOTE! When a field is accessed from within a thing or a visual script, all operations are restricted to read-only behavior. Any attempts to modify a field from within a thing context or via a visual script will fail.

value	(Left, Right, Number) Accesses the contents of the field as a numeric value. If the field is text and the contents retrieved, the contents are automatically converted to a suitable value. Example: result = this.field[myfield].value Example: this.field[myfield].value = 42
text	(Left, Right, String) Accesses the contents of the field as a string. If the field is numeric can the contents retrieved, the contents are automatically converted to a suitable string. Example: result = this.field[myfield].text Example: this.field[myfield].text = "hello"
isempty	(Right, Number) Returns non-zero if the field contains the empty string and zero if it contains text of any length. If used on a numeric field or with an array or matrix, an error is reported. Testing of array and matrix elements must be done via the "compare" intrinsic. Example: result = this.field[myfield].isempty
ischanged	(Right, Number) Returns non-zero if the field contents have been changed in any way from its original starting state. This can detect a field that has been changed by the user or via a script. Example: result = this.field[myfield].ischanged
reset	(Right, Number) The contents of the field are reset to the initial default value for the thing. A value of zero is always returned. Example: perform this.field[myfield].reset
ischosen	(Right, Number) Returns non-zero if the field contains a pick or a thing that was selected via a menu. If the field is associated with a menu and no selection has yet been made, zero is returned. Example: result = this.field[myfield].ischosen
delta	(Left, Right, Number) Accesses the delta component of a user field for manipulation separately from the user-specified value. The field must be explicitly configured to support delta processing. Example: result = this.field[myfield].delta Example: this.field[myfield].delta = 2
arrayvalue[row]	(Left, Right, Number) Accesses the contents of a specific element of the array-based field as a numeric value. The index of the element is given by row, where the index is a zero-based value that must be less than the number of rows in the array. If the field is text and the contents retrieved, the contents are automatically converted to a suitable value. Example: result = this.field[myfield].arrayvalue[3] Example: this.field[myfield].arrayvalue[3] = 42
arraytext[row]	(Left, Right, Number) Accesses the contents of a specific element of the array-based field as a string. The index of the element is given by row, where the index is a zero-based value that must be less than the number of rows in the array. If the field is numeric can the contents retrieved, the contents are automatically converted to a suitable string. Example: result = this.field[myfield].arraytext[3] Example: this.field[myfield].arraytext[3] = "hello"
matrixvalue[row,col]	(Left, Right, Number) Accesses the contents of a specific element of the matrix-based field as a numeric value. The index of the element is given by row and col, where the indices are zero-based values that must be less than the number of rows and columns in the matrix, respectively. If the field is text and the contents retrieved, the contents are automatically converted to a suitable value. Example: result = this.field[myfield].matrixvalue[3,4] Example: this.field[myfield].matrixvalue[3,4] = 42
matrixtext[row,col]	(Left, Right, String) Accesses the contents of a specific element of the matrix-based field as a string. The index of the element is given by row and col, where the indices are zero-based values that must be less than the number of rows and columns in the matrix, respectively. If the field is numeric and the contents retrieved, the contents are automatically converted to a suitable string. Example: result = this.field[myfield].matrixvalue[3,4] Example: this.field[myfield].matrixvalue[3,4] = 42
arraydump	(Right, String) Generates and returns a text string that contains the values of all elements in the array, with the results appropriately formatted for easy viewing. This mechanism is ideal for use within "debug" statements to help isolate scripting problems with arrays. Only usable with array-based fields. Example: result = this.field[myfield].arraydump NOTE! The generated output is capped to the limits of the debug output mechanism, so using this mechanism with large arrays and/or text-based fields may result in the output being truncated.
matrixdump	(Right, String) Generates and returns a text string that contains the values of all elements in the matrix, with the results appropriately formatted for easy viewing. This mechanism is ideal for use within "debug" statements to help isolate scripting problems with matrices. Only usable with matrix-based fields. Example: result = this.field[myfield].matrixdump NOTE! The generated output is capped to the limits of the debug output mechanism, so using this mechanism with large matrices and/or text-based fields may result in the output being truncated.
datetime[fmt,sep]	(Right, String) Returns the contents of the field formatted for output as a date or time, where sep is the separator string to use between values. The fmt parameter dictates the formatting to be used and must be one of the following values: realdate – Formatted as if it's a real-world date. realtime – Formatted as if it's a real-world time. gamedate – Formatted as if it's a game-world date. gametime – Formatted as if it's a game-world time. Example: result = this.field[myfield].datetime[gamedate,"/"] NOTE! This target reference is only supported on fields within picks - not things.
modify[oper,val,str]	(Right, Number) Applies a modification to the field with accompanying notes for tracking a history of changes. The modification nature is given by the oper parameter, which which specifies the operation to be performed. The val parameter is an arithmetic expression the provides the modification value to be applied. The str parameter is a text annotation that is recorded along with the modification. If str is the empty string, the notes are the name of the initial pick context that is applying the change (or "?????" if the initial context is not a pick). The oper parameter must be one of the following: '+' - The value is added to the field. '-' - The value is subtracted from the field. '*' - The value is multiplied into the field. '/' - The value is divided into the field. '=' - The new value is assigned to the field and all previous adjustments to the field are ignored. This operator is only valid with "stack" or "changes" history tracking. '#' - The value is added to the field, but no sign is displayed for the field within the history report. This allows the identification of basic values included into the field calculation that are distinct from bonuses (which include the '+'). '$' - The value is completely ignored and only the text entry is added for the modification. This allows a history entry to be recorded that has no value but that needs to be included in the report. The field must be explicitly configured to support history tracking. Always returns a value of zero. Example: perform this.field[myfield].modify[+,1,"first"]
history[spl,start]	(Right, String) Generates and returns a text string that contains the change history for the field. The spl parameter is a string that is inserted between entries in the change history, splicing them together for appropriate output. The start parameter is the starting value used for the field within the report. Both the spl and start parameters are optional, although the spl is required in order to specify the start parameter. If omitted, the spl parameter defaults to a comma and a space (", "), while the start parameter defaults to zero. The history report contents depend on the history behavior assigned to the field, as given below: best – Only the notes text for each history entry is reported stack – The notes text for each entry is reported and the adjustment details are included in parentheses with the notes (e.g. "notes (+2)") changes - Same as 'stack' Example: result = this.field[myfield].history Example: result = this.field[myfield].history["&"] Example: result = this.field[myfield].history[", ",42]