When a variable is defined as a Choice or Checkbox, the expression is evaluated when the user changes the selection. For a Table, the expression is not evaluated when individual cells are edited, but it is evaluated when the final edit is made (e.g., when the green checkbox is pressed or Edit table window is closed).
The expression can contain side-effects. For example, within the expression, you can assign to a global variable using the := operator. Such side-effects are not permitted in variable definitions. The result of the evaluation is not saved and is never used. Hence, the whole purpose of the expression is to enact some sort of side-effect.
The expression syntax is the same as the syntax for a Definition attribute.
The OnChange expression is always evaluated in mid-mode.
When you change the Definition of a variable using the Assignment Operator, :=, the OnChange expression for that variable evaluates, unless it is already running. The fact that it doesn't run a second time if already running enables some interesting capabilities.
An OnChange attribute can change its own Definition. As an example, suppose that a variable
X has the following as its OnChange expression:
X := "" & (Definition of X)
When a user enters a value, it is always converted to text. When the value is first changed, OnChange runs. It in turn alters the value again, but OnChange is not launched a second time because it is already running.
Two or more input variables can change each other via their OnChange attributes to keep them mutually consistent. For example, suppose you have two inputs variables,
Local_Time, and you have a variable named
Time_Offset that relates the two. You set
OnChange GMT_Time : Local_Time := GMT_Time + Time_Offset
OnChange Local_Time : GMT_Time := Local_Time - Time_Offset
Now a user enters a time into the
Local_time immediately adjusts. Or he enters a time into the
Local_time input -- GMT_Time immediately adjusts. In the first case,
OnChange of GMT_Time evaluates, which changes the definition of
Local_time, which in turn triggers
OnChange of Local_Time. Local_time actually changes the definition of
GMT_Time again, but to the same value it already has, but
OnClick of GMT_Time does not run again because it is already active; hence, the loop terminates.
Inputs and Outputs
If the OnChange attribute of
X uses the value of
Y will show up on the list of Inputs for
X in the Object Window, and
X will be in the list of Outputs for
Z is assigned to in the OnChange attribute of
Z will appear as an Output of
X will appear as an Input of
Z. However, on the diagram, arrows are not show to depict these dependencies.
The OnChange attribute was introduced in Analytica 4.6. It replaces the Script attribute when used for Choice and Checkbox controls prior to Analytica 4.6. You can use OnChange for any variable, including text inputs, where Script was only available for user input variables using Checkbox or Choice functions. OnChange expects an expression using the standard Analytica syntax, where the Script attribute expects Typescript, which meant you had to learn a slightly different syntax to use it. The Script attribute still works in 4.6 so that legacy models still work. If a variable contains both OnChange and Script, it evaluates OnChange before Script.