
~~Title: RTAI Canvas Controls~~

<html><font color=#990000 size="+2"><b>Visual Canvas Controls</b></font></html>

The <color #00a2e8>Real-Time AI</color> environment provides visual controls for working with data, that can be placed on a component
canvas or added to the IO Control Tab.  Control types placed on the tab are the same as those available on component canvas and may
pass values via Shared Variabe binding or direct API calls on components that support them.  Control values may also be bound to Query
and Function parameters for //input// as well as Result Object elements for //output//.
\\
Controls may be added using //IO// or //Canvas// tabs, respectivley.  The //IO Control// tab must first be enabled using Control Settings 
of the component.

{{:doc:io_canvas_control.png?nolink&600}}
\\ 

==== Control Life-Cycle Overview ====

Controls are created when a component is initalized.  Their default values are then determined from static settings or from //Shared Variables//.
The last step in control value initalization occurs when a parent Component's ''Autoload'' option is enabled.  In this case, the //Data Source//
will execute it's query and if an //Result Object// elements are bound to control values, they will be populated.
\\
\\
Controls that are bound to //Result Objects// will have the <color #00a2e8>{{fa>database?fw}}</color> symbol set in the Editor to indicate that 
the result is used to pupulate initial control values.  Not that result values may change if a component is reloaded directly or as a result of''Live Control''
optionbeing enabled.  This is sometmes called //autofetch//.
\\
\\
Controls are not drag-able, but they may be //enabled// or //disabled// and their size and location may be altered as a consequence of trigger logic or 
other events.  Controls can support any of the following capabilities:

=== Shared Variable Links ===  
{{fa>link?24}}

This allows a control's value to be linked to a //Shared Variable// and its value to be initalized from the variable.  Consequently this allows one or more
controls and parameters to be set using a shared value.  This may be useful when setting common Look & Feel, Font Size, color or position.  But may also
be used to pass values between components and Dashboard Canvas elements in the <color #00a2e8>Real-Time AI</color> environment.  If triggers are not used,
users will need to call ''component.refresh()'' to update component values with //Shared Variable// content after it changes.
\\

=== Parameters ===  
{{fa>cogs?24}}

Parameter bindings are used to associate control values with //Data Source// query parameters. No secial processing or update logic is required once the
association is declared.  When a component is re-loaded as a consequence of trigger logic or as a result of ''Live Control'' option being enabled, the parameter 
value is automatically used by the query.
\\

=== Event Triggers === 
{{fa>lightbulb-o?24}}

Event Triggers are executed when a control value is changed and //after focus transfers to another element//.  Trigger logic can perform any variety of tasks
including raising of custom events, changing values in other controls or affecting changes in component element or canvas controls.  Triggers may reload
components and thereby execute queries directly as a consequence of user interaction.  See [[component_control_api | Component Control API]] section for a
detailed set of methods that may be used to drive logic execution and component life cycle.
\\

=== Events === 
{{mdi>alpha-e-circle-outline?24}}

Events are raised when a control value is changed and //after focus transfers to another element//. This method of asyncronous communication is useful in cases
where you want to signal state change or pass information to //Application Listeners//.  It is typically used in RTAI applications (dashboard canvas), as a
way to let other components react to events raised by a specific control.  For example, changing a category such as //State// or //Country// in one component
can raise an event with the name of the category.  Other components in an application can consume this event, set their //Shared Variables// to the new
category and automatically ''component.refresh()''.  In this example several components act together to change the context of what is being seen, for instance
changing state from //New York// to //Florida// and re-loading the graphs and visal elements of a component accordingly.
\\
\\
<callout type="tip" icon="true" title="Event Scope">RTAI Events are local to the application.  They do not curently support raising events in the Event Fabric.  \\ However, it is possible to use standard Javascript Client that is part of the internal //Data Source// to raise events on the back-end.</callout>
\\


=== Reload Actions ===
{{fa>refresh?24}}

Other





==== Available Controls in Release 3.8 ====

Components are self contained visual elements such as Charts, Forms or Applications that allow yout to interact with the Data Fabric back-end.
They 

=== Button ===  

{{:doc:btn_control.png?nolink&50}}

Creates a canvas button capable of enabled, disabled state that may be clicked to trigger an action an event or query. It may be 
bound to Shared Variables or Data Source as display values. Buttons support image or text as internal labels and may also support 
tool-style behavior via emphasis visibility options.

<popover html="true" placement="middle" trigger="click focus" title="**Supported Bindings**" content="The control supports **Parameter** binding as //__string__// 
or //__JSON__// representation of any data type."> <btn type="link"><color #00a2e8>Data Binding {{fa>database?fw}}</color></btn></popover>

<btn type="primary" size="sm">{{fa>cogs?16}} Parameters</btn> 
<btn type="success" size="sm">{{fa>lightbulb-o?16}} Event Triggers</btn> 
<btn type="info" size="sm">{{fa>refresh?16}} Reload Actions</btn>

\\

=== Label ===

{{:doc:lb_control.png?nolink&50}}

Creates a canvas label with enabled or disabled, non-editable content. Label values may be changed as a consequence of trigger or function processing.  The 
canvas component should be refreshed to effect change. For example ''component.refresh()''  It may be bound to Shared Variables or Data Source as display values.

<popover html="true" placement="middle" trigger="click focus" title="**Supported Bindings**" content="The control does not support data binding as its 
value cannot be changed by direct user actions."> <btn type="link"><color #00a2e8>Data Binding {{fa>database?fw}}</color></btn></popover>

\\

=== Image (Icon) ===

zz

<color #00a2e8>//__Data Binding__// {{fa>database?fw}}</color>

To bind data you bind
\\

=== Drop Down List Box ===

zz

<color #00a2e8>//__Data Binding__// {{fa>database?fw}}</color>

To bind data you bind
\\

=== Choice ===

zz

<color #00a2e8>//__Data Binding__// {{fa>database?fw}}</color>

To bind data you bind
\\

=== Radio Button ===

zz

<color #00a2e8>//__Data Binding__// {{fa>database?fw}}</color>

To bind data you bind
\\

=== Check Box ===

zz

<color #00a2e8>//__Data Binding__// {{fa>database?fw}}</color>

To bind data you bind
\\

=== HTML Frame ===

zz

<color #00a2e8>//__Data Binding__// {{fa>database?fw}}</color>

To bind data you bind
\\

=== Canvas Panel ===

zz

<color #00a2e8>//__Data Binding__// {{fa>database?fw}}</color>

To bind data you bind
\\

=== Data Grid ===


{{:doc:grid-tile.png?nolink&50|}}
\\
Creates an interactive data grid (table) control capable of row and column displa. Allows an control be defined as a column element and
provides fine-grained access to column and row events. When binding column values from the grid to Parameters, all values are treated as
scalar. Values will be collected into a JSON array and assigned to a datasource parameter.

<popover html="true" placement="middle" trigger="click focus" title="**Supported Bindings**" content="The control supports binding of columns as 
//__JSON Array__// representation of any data type. Each column fully supports bi-directional data binding based on which ever type of control the 
column is defined as. Statis elements and Formatter rules may also be specified."> <btn type="link"><color #00a2e8>Data Binding {{fa>database?fw}}</color></btn></popover>

<btn type="primary" size="sm" icon="fa fa-cogs"> [[canvas_controls#parameters | Parameters]]</btn> 
<btn type="success" size="sm" icon="fa fa-lightbulb-o"> [[canvas_controls#event_triggers |Event Triggers]]</btn> 
<btn type="info" size="sm" icon="fa fa-refresh"> [[canvas_controls#reload_actions |Reload Actions]]</btn>

\\

//**Control API**// 
\\
\\
When the grid API is used, it alters the visible, cached content of the Grid.  This is what is displayed on the canvas by default,
unless a ''gridControl.resetData()'' method is called.  This resets content and performs a cache merge.  Therefore if the initial grid
values are populated from the back-end system, and the API is used to manipulate them, the user will only see the chaned, //cached// 
versionn and not the actual results from the //data fech// operation.  In this example //gridContol// is the name of the grid control.


''addRow(row)'' - append row object to the end.
  * returns boolean true/false to indicate if row was added(true) or ignored(false) in case it's duplicate and grid option 'uniqueIdConstraint'=true;

''insertRow(row, index = 0)'' - insert row on index (index 0 by default so to the beginning)
  * returns boolean true/false to indicate if row was added(true) or ignored(false) in case it's duplicate and grid option 'uniqueIdConstraint'=true;

''removeRow(id)'' - remove row by id

''removeRowAt(index = 0)'' - remove row at index

''removeRows(column, value)'' - remove all rows where chosen column has specified value.
  * If "column" is string - first column with given header will be used.
  * If "column" is number - it will be used as zero-based column index, so column=0 means first column in the grid.

''getRow(id)'' - find row by id

''findRow(column, value)'' - find first row, where chosen column has specified value.
  * If "column" is string - first column with given header will be used.
  * If "column" is number - it will be used as zero-based column index, so column=0 means first column in the grid.
  * Returns row object or 'undefined' if not found.

''findRows(column, value)'' - find all rows, where chosen column has specified value.
  * If "column" is string - first column with given header will be used.
  * If "column" is number - it will be used as zero-based column index, so column=0 means first column in the grid.
  * Returns array, empty if nothing found.


''clearRows()'' - remove all rows

''resetData()'' - resets and merges visible grid contents, re-enabling data fetch from back-end

''data'' - API property to access data array.
  * Returns detached copy, so modifying array will not affect grid untill assigned back to property explicitly.

For example:

''myGrid.data.shift(); /* no effect, first item removed from the copy.*/''
\\
\\
''var data = myGrid.data; /* save copy to var */
\\
data.shift(); /* mutate copy */
\\
myGrid.data = data; /* Here we overwrite grid data explicitly. */''

Note, row objects inside data are still same as in the grid:

''myGrid.data[0].cells[0]="Hello"; /* this affects the grid data directly */''
