Conditional action syntax
A conditional action includes an action, a condition, and a value. Event handlers of the type Conditional Action and certain component attributes use the syntax described here. We recommend that you use the Edit Set of Conditional Actions dialog box from the appropriate field in the properties dialog box to guide you through the creation of conditional actions. This topic explains the syntax of the expressions created through that process.
A subset of the WinStudio API is available for developers to script conditional actions in WinStudio. You might want to use the conditional action dialog box rather than scripting for these reasons:
- You might see a small performance gain because there is no initial compile as with scripts.
- Using the dialog boxes to build the expression is easier and less error-prone than writing code.
- For component enabled, required, and hidden expressions, you do not need to create event handlers at various points to ensure that your logic executes when certain values change.
Syntax
A conditional action procedure has three parts:
ACTION ( ActionType: component1 | property1 | variable1 [ ;component2 | property2 | variable2 ; . . .] ,
Boolean expression,
True | False | component | property | variable | literal | event_name [ , ] )
ActionType: component1 | property1 | variable1 [ ;component2 | property2 | variable2 ; . . .] ,
This parameter specifies an action type (Enabled, Required, Modified, Toggle, Focus, Set, SetModified [Set and Modify property], Modified, New [applies to caches only], GenEvent [applies to forms and repaint on component]. The action type is followed by a colon (:) and a component, property, or a variable name or a list of components, properties, or variable names in any order. Names must be separated by a semicolons (;). The parameter ends with a comma.
Boolean expression,
This parameter is an expression that evaluates to a Boolean value. The expression is a regular expression that can be used in an If statement with few exceptions. Precedence for OR and AND is the same and can be changed using parenthesis. The parameter ends with a comma.
True | False | component | property | variable | literal | event_name [ , ]
This parameter contains a value or a list of values separated by semicolons. For Enabled or Required, valid values are True or False; there is only one value for the entire list of components. For Set and SetModified, valid values include properties, components, variables, or literal values. An empty string is designated by "". The parameter ends with a comma if additional three-part parameters follow it.
ACTION takes up to 300 parameters in this three-part form.
Keywords are preceded by a #.
Valid Actions
Set, SetModified (take three parameters) = {property | component | variable [; property | component | variable], condition, property | component | variable | constant [; property | component | variable | constant | expression]}
Enabled = Toggle:#C(Name.Enabled)
Required = Toggle:#C(Name.Required)
Modified = Toggle:#{C|P|R|CA}(Name.Modified)
Toggle (takes three parameters) = {component | property | row | cache [; component | property | row | cache], condition, True | False}
GenEvent, GenEventRet (take three parameters) = {event_on [; event_on], condition, form_event_name | component_event_name [; form_event_name | component_event_name]}
Focus = {#C(Name) | #C(variable), condition, [#C(Name) | #C(variable)]} - If a condition is false the focus will use optional component if supplied.
ReturnValue = {, condition, constant (0 - success, otherwise failure)} - Sets the return value out of the conditional action script.
Stop = {, condition, } - If the condition evaluates to true script stops execution.
Validate = {, condition, message} - If the condition evaluates for false, message is displayed.
component = {#C(variable), #C(Name) | #C(Name.Enabled) | #C(Name.Visible) | #C(Name.Required) | #C(Name.Modified)}
property = {#P(variable), #P(Name) | #P(Name.Modified) | #P(cache_name.Name) | #P(cache_name.Name.Modified)}
variable = {#V(Name) | #GV(Name)
row = {#R(variable), #R(cache_name.Modified) | #R(cache_name.New) | #R(cache_name.Deleted) | #R(cache_name.Invalid)}
cache = {#CA(cache_name.Modified) | #CA(cache_name.NewModified) | #CA(cache_name.Deleted) | #CA(cache_name.Save) | #CA(cache_name.Refresh) | #CA(cache_name.New) | #CA(cache_name.Copy) | #CA(cache_name.Delete) | #CA(cache_name.Navigate) | #CA(cache_name.Filter) | #CA(cache_name.Notes)}
event_on = {form_event | component_event}
form_event = {#F(variable) | #F(ThisForm) | #F(FormName)}
form_event_name - {constant - name of the event to generate on the form}
component_event = {#C(variable) | #C(Name)}
component_event_name = {Repaint (force repaint of a component) | Validate (run all validations attached to a component)}
message = {#S(Name) [; #S(Name)]}
condition = {ELSE | condition_expression} - Empty condition retains the same value as previous condition.
condition_expression = {[FOREACH:cache_name(]compare_expression condition_operator compare_expression[)]}
compare_expression = {expression comparison_operator expression}
condition_operator = { | &}
comparison_operator = {= <> != > < >= <= : !:}
expression = {[(]single_expression [ + - / * single_expression[)]]
single_expression = {function | property | component | variable | row}
function = {SUM | MAX | MIN | AVG | CInt | CDbl | CDate | Ceiling | Floor | CStr | InStr | $DATE}
SUM = {SUM(expression [? compare_expression]) - Sum all the values in the cache, if condition expression is supplied only rows that the condition evaluates to true will be summed.
MAX = {MAX(expression [? compare_expression]) - Get the maximum value for the expression out of all rows in the cache, if condition expression is supplied only rows that the condition evaluates to true will be considered.
MIN = {MIN(expression [? compare_expression]) - Get the minimum value for the expression out of all rows in the cache, if condition expression is supplied only rows that the condition evaluates to true will be considered.
AVG = {AVG(expression [? compare_expression]) - Get the average value for the expression out of all rows in the cache, if condition expression is supplied only rows that the condition evaluates to true will be considered.
CInt = {CInt(expression)}
CDbl = {CDbl(expression)}
CDate = {CDate(expression)}
Ceiling = {Ceiling(expression)}
Floor = {Floor(expression)}
CStr = {CStr(expression)}
InStr = {InStr(expression1;expression2)} - Returns (-1) if expression2 was not found in expression1, otherwise the first starting position of the expression2 in expression1.
$DATE - constant evaluates to current date.
= - Equal to
!=, <> - Not equal to
>, < - Greater than, less than
>=, <= Greater than or equal, less than or equal
: - (in list) - List is delimited by parentheses () and separated by semi-colons (;). For example: (1;2;3;4) or ("a";"b";"c")
!: - (not in list) - List is delimited by parentheses () and separated by semi-colons (;). For example: (1;2;3;4) or ("a";"b";"c")
expression =
cache_name = {primary_cache | grid_name}
primary_cache = {PrimaryCache} - Constant, assumes a primary cache attached to a form.
grid_name = {name of the grid component on the form} - Extracts a cache out of the grid component on a form.
#V(Name) - Returns or sets the value of a variable.
#GV(Name) - Returns or sets the value of a global variable. (Often required by conditional actions; if #V does not work, try this instead.)
#C(Name) - Gets or sets the current value in a component.
#C(Name.Enabled) - Gets or sets the enabled property on a component.
#C(Name.Visible) - Gets or sets the visible property on a component.
#C(Name.Required) - Gets or sets the required property on a component.
#C(Name.Modified) - Gets or sets the modified property on a component.
#PModified(Name) = #P(Name.Modified)
#P(Name), #P(cache_name.Name) - Gets or sets the current value in a property attached to a current row in a collection.
#P(Name.Modified), #P(cache_name.Name.Modified) - Gets or sets the modified property on a property attached to a current row in a collection.
#S(Name) - Returns the value of the string.
#RModified(cache_name) = #R(cache_name.Modified)
#RNew(cache_name) = #R(cache_name.New)
#RDeleted(cache_name) = #R(cache_name.Deleted)
#REntries(cache_name) = #R(cache_name.Entries)
#RAutoInsert(cache_name) = #R(cache_name.AutoInsert)
#RNewUnmodified(cache_name) = #R(cache_name.NewUnmodified)
#R(cache_name.Modified) - Gets or sets current row in a collection modified.
#R(cache_name.New) - Gets or sets current row in a collection new.
#R(cache_name.Deleted) - Gets or sets current row in a collection deleted.
#R(cache_name.Invalid) - Gets or sets current row in a collection invalid (error state).
#R(cache_name.Entries) - Returns number of entries in the cache including auto-inserted row.
#R(cache_name.AutoInsert) - Returns true or false based on the auto-inserted property for a row.
#R(cache_name.NewUnmodified) - Returns true or false based on the combination of new and modified properties for a row
#CA(cache_name.Modified) - Marks or unmarks all rows as modified in a cache.
#CA(cache_name.NewModified) - Marks or unmarks all rows as new in a cache.
#CA(cache_name.Deleted) - Marks or unmarks all rows as deleted in a cache.
#CA(cache_name.Save) - Turns off or on the save capability on a cache.
#CA(cache_name.Refresh) - Turns off or on the refresh capability on a cache.
#CA(cache_name.New) - Turns off or on the new capability on a cache (also gets rid of the auto-inserted row).
#CA(cache_name.Copy) - Turns off or on the copy capability on a cache.
#CA(cache_name.Delete) - Turns off or on the delete capability on a cache.
#CA(cache_name.Navigate) - Turns off or on the navigate capability on a cache.
#CA(cache_name.Filter) - Turns off or on the filter capability on a cache.
#CA(cache_name.Notes) - Turns off or on the notes capability on a cache
Examples
This call enables the components ExchangeRateEdit and ExchangeRateGridCol if the property CurrencyCode is not equal to the property DefaultCurrencyCode and the property InvoiceStatusType is not in 2, 3, 4, and 5. Otherwise, ExchangeRateEdit and ExchangeRateGridCol are disabled.
ACTION (Enabled:#C(ExchangeRateEdit);#C(ExchangeRateGridCol), #P(CurrencyCode) <> #P(DefaultCurrencyCode) & #P(InvoiceStatusType) !: (2;3;4;5), True)
This is equivalent to:
ACTION (Enabled:ExchangeRateEdit;ExchangeRateGridCol, #P(CurrencyCode) <> #P(DefaultCurrencyCode) & #P(InvoiceStatusType) !: (2;3;4;5), True)
This call disables the ExchangeRateEdit component when the property CurrencyCode is equal to an empty string and sets the Required property on the same component to False. Otherwise, ExchangeRateEdit is enabled and required.
ACTION (Enabled:#C(ExchangeRateEdit), #P(CurrencyCode) = "", False, Required:#C(ExchangeRateEdit), #P(CurrencyCode) = "", False)
This call sets and marks as modified the ExchangeRate and BeginDate properties only if the property CurrencyCode is equal to the property DefaultCurrencyCode. ExchangeRate is set to the integer sum of 1 and the value of the variable Test; and BeginDate is set to a value in the InvoiceDate property.
ACTION (SetModified:#P(ExchangeRate);#P(BeginDate), #P(CurrencyCode) = #P(DefaultCurrencyCode), CInt(1+#V(Test));#P(InvoiceDate))
This call sets as not modified the current row in the PrimaryCache and marks as unmodified the property BeginDate in the primary cache only if the property CurrencyCode is equal to the property DefaultCurrencyCode.
ACTION (Modified:#R(PrimaryCache);#P(BeginDate), #P(CurrencyCode) = #P(DefaultCurrencyCode), False;False)
ACTION (GenEvent:#F(ThisForm);#F(APDefaults), #P(CurrencyCode) = #P(DefaultCurrencyCode), StdObjectRefresh; StdObjectSave)
This call disables the Save operation on the form PrimaryCache when StatusType is equal to 10. Valid values are: Save, Refresh, New, Copy, Delete, Navigate, Filter, and Notes.
ACTION (Enabled:#CA(PrimaryCache.Save), #P(StatusType) = 10, False)
This call sets the current object to New on the PrimaryCache to False when StatusType is equal to 10. Valid values are: New, Deleted, Invalid, and Modified.
ACTION (Toggle:#R(PrimaryCache.New), #P(StatusType) = 10, False)
This call always forces a repaint of the FormsGrid component.
ACTION (GenEvent:#C(FormsGrid), 1 = 1, Repaint)
This call sets the focus to the component Test1 if the property Test equals 1. Otherwise, it sets the focus to Test2.
ACTION (Focus:#C(Test1), #P(Test) = 1, #C(Test2))