Control Property References
 

Description

Control Property References, also knows as Substitution Syntax, are used to determine what is displayed in controls. When setting the data for a control, click in the Data Source property field. An ellipsis button is displayed . Clicking this will display the Data Builder Wizard, which assists in building data queries.

To display the Window Properties

• ${.property}
  displays the property of the current window.

• ${/WINDOWNAME.propertyname}
  displays the property of the named window.

• ${windowelement}
  displays the Data element of the current window.

• ${windowcontext}
  displays the Context element of the current window.

Example:

${.caption} displays the caption of the current window.

${/MYBIDS.caption} displays the caption of MYBIDS window.

To reference a property on a control in the current window

• ${CONTROLNAME.property}
  displays the property of CONTROLNAME

• ${CONTROLNAME.selectedelement}
  displays the selected element of CONTROLNAME

Example:

${TEXT1.value} will return what is in a control named TEXT1 (you would normally use this in another control to get the value in the nominated control).

To reference a control on a different window

${/WINDOWNAME/CONTROLNAME.property}

displays the property of CONTROLNAME on WINDOWNAME.

Example:

${/MYBIDS/BIDLIST.isselected}='Y' returns TRUE if there is a selected element in BIDLIST on MYBIDS window.

To reference a subcomponent (for example: a column in a list)

${/WINDOWNAME/CONTROLNAME/COLUMNNAME.property}

displays the property of CONTROLNAME on WINDOWNAME.

Example:

${/MYBIDS/BIDLIST/PRODCOL.caption} displays the caption of PRODCOL in BIDLIST on MYBIDS window.

Recursive Substitution

It is possible to do recursive substitution, for example:

${/${/app.activewindow}.caption}

displays the caption of the currently active window.

Special Cases/Reserved Words

There are a few special cases that should not be used to name controls:

• ${windowelement}
  displays the data element for the window. Defaults to the window's context if no Data attribute explicitly stated.

• ${windowcontext}
  displays the data element used to open the window

• ${rowelement}
  displays the data element associated with the row being evaluated in a list. Valid for:
  A column's Data Source,
  A column's List Data Field property (to generate an embedded combo box).
  CAPTION attribute for a treeview/ITEM (refers to element being evaluated).

• ${PARENTCONTROL}
  references the control that was used to open a window (either explicitly stated or by default from a BUTTONCLICK event). To enable passing back a value to that control.

• ${app} should not be used to name a window, to avoid conflicts with application property notation.

Dynamic String Syntax

It is possible to dynamically create strings, using combinations of fixed text, ${} notation, and XPath notation. To embed XPath within a string, use the eval() function:

Control: Button

Trigger: Click

Action: Message

Parameters:

Text: Qty: ${QTYTEXT.value}

or

Text Qty: eval(/FOR_SALE/ITEM/@QTY)

or

Text: Qty: eval(${LIST}/@QTY)

Example: how to set a label to show an attribute from an element

The eval() function invokes a query directly to the underlying local data and will always return a string. The XPath statement should always be defined to return an XML attribute (or include a function that returns a single value). The following statement sets a label to show the QTY attribute from a SALE_ITEM element.

Control: Button

Trigger: Click

Action: Set Property

Parameters:

Control: LABEL

Property: VALUE

Value: eval(/FOR_SALE/SALE_ITEM[@SALE_ID='ID01']/@QTY)

If the underlying data was:

<FOR_SALE>

     <SALE_ITEM SALE_ID='ID01' QTY='20' />

The label would show 20.

Without the eval() function, the label would show:

FOR_SALE/SALE_ITEM[@SALE_ID='ID01']/@QTY

eval() can be combined with ${ } substitution syntax, as in:

Control: Button

Trigger: Click

Action: Set Property

Parameters:

Control: LABEL

Property: VALUE

Value: eval(/FOR_SALE/SALE_ITEM[@SALE_ID='${TEXT.value}']/@QTY)

If the user had typed ID01 into the control named TEXT, then the label would again show 20.

Nesting eval() functions is supported, so the following would be valid:

eval(eval(/mystuff/@useelement) [@SALE_ID='${TEXT.value}']/@QTY)"

where the data had an element:

<mystuff useelement="/FOR_SALE/SALE_ITEM" />

Predicate Value

A predicate value is an expression that can be used as one value in a predicate clause. These can also be used to define a complex Data Field. The following are all valid:

Control: Text Field

Parameters:

Data: ${LIST}

Data Field: concat('Qty: ', @QTY)

Control: Text Field

Parameters:

Data: ${LIST}

Data Field: @QTY mult @PRICE

Control: Text Field

Parameters:

Data Field: sum(/FOR_SALE/SALE_ITEM/@QTY)

Condition: (@QTY mult @PRICE) > 100

For the most part, these will use the functions available in the Altio XPath engine.

Available Properties:

See the following pages for details of what properties are supported by objects at run time:

Run time Properties for Applications

Run time Properties for the Designer

Run time Properties for Windows

Run time Properties for Controls

• Run time Properties for Button Controls

• Run time Properties for List Controls

• Run time Properties for Menu Control Items

• Run time Properties for Select Controls

• Run time Properties for Treeview Controls

See also:

Using Data Builder Wizard, Designer Property References