LGUI2:Data Bindings

From Lavish Software Wiki
Revision as of 22:58, 15 October 2019 by Lax (talk | contribs)
(diff) ←Older revision | view current revision (diff) | Newer revision→ (diff)
Jump to navigation Jump to search

LavishGUI 2 Data Bindings provide a way to bind certain LavishGUI 2 values, such as the text in a text box, to LavishScript values.

Defining a Data Binding

A Data Binding is defined either by a JSON object enclosed by {}, or by a string.

As a JSON Object

Data Binding properties
pullFormat A LavishScript Data Sequence that retrieves the desired value, e.g. ${MyObject.MyValue}
pullReplaceNull A string to replace a "NULL" pulled value
pushFormat An Array of 2 strings that, with the value in-between, form a command to update the desired value, e.g. [ "MyObject.MyValue:Set[\"", "\"]" ] may form MyObject.MyValue:Set["new value"]
pushNullFormat A string with the command to update the desired value, if it would otherwise update to NULL
autoPull A boolean specifying whether Pull should be done automatically on demand. Default is true
autoPush A boolean specifying whether Push should be done automatically on demand. Default is true
pullOnce A boolean specifying whether Pull should only be done automatically once (e.g. to initialize the value), and then disable autoPull
pullHook An Event Hook, minus the "eventHandler". When the hooked event fires, the Data Binding will Pull.
bufferSize An integer specifying the maximum length for the string returned by LavishScript. Default is 4096

As a String

For simple cases, Data Bindings can be defined as a single string. The string must be a LavishScript object path (Data Sequence without the containing ${}), from which the Data Binding can automatically build the most common Pull and Push settings from. The object is assumed to have a Set method, and the Data Binding will have no special handling for NULL.

For example, given the string MyObject.MyValue, the following will be used:

"pullFormat": "${MyObject.MyValue}"
"pushFormat": [ "MyObject.MyValue:Set[\"", "\"]" ]

Relative Data Bindings

Sometimes, a Data Binding may depend on the object (usually an Element) that owns it. In this case, the lgui2 LGUI2 object provides a DataBindingContext member to refer to the object itself. For example:

"pullFormat":"${LGUI2.DataBindingContext.Metadata.Get[someValue]}"

Examples

A textblock with pull-only Data Binding

NULL is replaced with an empty string by "pullReplaceNull"
{
  "type":"textblock",
  "textBinding":{
    "pullFormat":"${MyObject.MyValue}",
    "pullReplaceNull":""
  }
}

A textbox with two-way Data Binding

NULL is replaced with an empty string for both push and pull
{
  "type":"textbox",
  "textBinding":{
    "pullFormat":"${MyObject.MyValue}",
    "pullReplaceNull":"",
    "pushFormat":[ 
       "MyObject.MyValue:Set[\"", 
        "\"]" 
     ],
    "pushNullFormat":"MyObject.MyValue:Set[\"\"]"
  }
}

LavishGUI 2 Topics