
~~Title: Canvas Controls~~

<html><font color=#990000 size="+2"><b>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, from //Shared Variables// or
from local persistence in the browser if controls are marked as //Persistent//.
\\
\\
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 any control elements or their values are bound to //Result Object//, they will be populated.  This life-cycle sequence 
means that controls may be set up with default values, marked as persistent and also be initialized by query.  Conversley, components that are not 
''Autoload'' enabled can have default values set in varipus ways and then have the values over-written when the component is reloaded.
\\
\\
Controls that are bound to //Result Objects// will be marked with a <color #00a2e8>{{fa>database?fw}}</color> symbol in the Editor to indicate that 
tha query result is used to populate control values.  Result values may change if a component is reloaded directly or as a result of ''Live Control''
option being enabled.  This is called //autofetch// and may be configuredin the Data Source tab.
\\
\\

==== 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>

\\

=== Text ===

zz

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

To bind data you bind

There are types of data and //masks// that can be used to present //Date//, //Numeric// or other formatted data for input.  Includes a //Date Picker// control.

\\
\\
=== Image (Icon) ===

The image or ''Icon'' control allows users to conditionaly set images registered as ''Resources'' in the //Component//.
Images may be uploaded from a desktop directtly into the //Component// or imported dynamically from a URL.  It is 
resommended for performance that images are loaded into the //Component// as reosurces. They are dynamically converted
to SVG based binary strings and compressed by the <color #00a2e8>RTAI Framework</color>.  Combining images with trigger-based behavior can
enable informative animation within the user interface.  Images can be bound to ''icon'' elements anywhere they are 
supported, and may be easily changed in response to user interactions as well. For example, setting certain images on
//Hover// mode in //Style// can provide an interactive experience for users.
\\

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

To bind data you bind

//** Control Specific API **//

Images may be handled programatically in trigger scripts.

  * Note that the ''image:////'' URL is interal to the framework and is only relevant for purpose of identifying and decoding //SVG// style images defined as //resources//. 

<sxh DSQL; gutter: true;>
  image = 'image://' + component.getIcon('ico_watch_sm');
</sxh>  

\\
\\
=== Combo Box ===

zz

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

To bind data you bind
\\

=== Choice ===

A //Choice// control provides a pick list of values that users can select.  The values are stored as an array of //choice options// that are either simple options or complex, detailed objects.  This can be usefulf for adding inforaion to choice elements.  Choice elements can be added through configuration, programmatically or by data binding, allowing users to load context sensitive choice items.

  *  ''control.addChoice('<text>')''  Adds a choice element to the pick list.

  *  ''control.selectChoice('<text>')'' Adds an element to selected items, but doesn't add it to the pick list.  

  *  ''control.deselectChoice('<text>')'' Removes an element from selected items, and returns it to the pick list.  

  *  ''control.removeChoice('<text>')'' Removes a choice element from the pick list.  

Examples:

<sxh DSQL; gutter: true;>
  var ch = component.getControl('ch');
  ch.addChoice('Option A');
  ch.render();
</sxh>
  
<sxh DSQL; gutter: true;>
  // Select a choice
  var ch = component.getControl('ch');  
  ch.selectChoice('Option A'); 
  // Deselect a choice
  var ch = component.getControl('ch');
  ch.deselectChoice('Option B');
</sxh>

\\

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

Choice supports data bindging to 

<code>
  [+]- controls[..]
       |
      [-]- choices			myChoices
           | 
          [-]- options[..]
               |
               +-- simple option	Option 1
               +-- simple option	Option 2		

</code>

  
\\

=== 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
\\

=== Switch ===

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
\\

=== Layout Container ===

zz

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

To bind data you bind
\\

=== Frame ===

zz

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

To bind data you bin

\\
\\

=== Split Panel Frame ===

zz

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

To bind data you bin

\\
\\
=== Color Picker ===

zz

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

To bind data you bind
\\

=== Progress Bar ===

zz

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

To bind data you bind
\\

=== Range Slider ===

zz

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

To bind data you bind
\\

=== Callout ===

zz

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

To bind data you bind
\\

=== Context Menu ===

A //Context Menu// can be added to any //Canvas Control// allowing for actions and logic to be added to the context of a control.  The main canvas itself can also have a context menu added to it.  Like other application UI controls, a menu will open based on a right-click action at the pointer's position.  And can be configured with classic menu //look-and-feel// utems such as icons, menu separators and so forth.

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

Menu items can be boudn to //Data Source// results, allowing for enu content to be controlled by back-end applications. There are some notable use cases for this approach, especally in situations where conditional icons or menu text must be rendered.  However inmost cases, static menu controls will work just fine.

{{:wiki:rtai:context_menu_basic.png|}}

Menu actions can be configured to either //raise events// or trigger based on specific actions.  In most cases, //Context Menu// triggers are defined in response to ''click'' actions. Triggres will fire only in the context of component-local actions.  If a //Context Menu// item click needs to affect other components in an application, users should //raise event// that can then be seen by [[rtai_events| Application Event Consumers]].

Here is an example of a trigger definition on a context menu item:

{{:wiki:rtai:ctx-menu-triggers_1.png?500|}}

\\

=== 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 Specific API**// 
\\
\\
The grid API has several layers.  It contains an overall ''grid'' level interface for working with //control data//
as an abstraction.  And a //direct// API for working with underlying grd data elements as standard //Array// objects.  This 
allows users granular control over data content and the ability to use any thrd party libary to query, sort of merge
grid contents.  For example, using the popular //Lodash// library already included in the //framerowk//.

See [[data_grid_api | Data Grid API]] for an extensive list of supported APIs.

\\
\\
=== Drop Box ===

zz

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

To bind data you bind
\\

=== 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.  Multiple controls and their values can be set using a //Shared Variable//. This may be useful when setting common Look & Feel, Font Size, color or position.  And may also be used to share  values between components, or canvas elements in the <color #00a2e8>Real-Time AI</color> environment using the API. If variables are set directly using  event trigger logic, users will need to call ''component.refresh()'' to synchronize the state of a component's control valules 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

