commonlib.DataBinding

binding npl data table (members) to other IDE controls or ParaUIObject. it is a two way binding.

Title	binding npl data table (members) to other IDE controls or ParaUIObject. it is a two way binding.
Author(s)	LiXizhi
Date	2008/2/1
File	script/ide/DataBinding.lua

Description

Data binding provides a way for developers to create a read/write link between the controls and the data in their application (their data model).

Sample Code

NPL.load("(gl)script/ide/DataBinding.lua");
local bindingContext = commonlib.BindingContext:new();
@param dataSource: it can be a table (1) or a binding function (2): 
bindingContext:AddBinding(dataSource, dataMember, ControlName,ControlType, ControlPropertyName, DataSourceUpdateMode, NullValue);
commonlib.Binding.ControlTypes = {
   ParaUI_editbox = 1, -- bindable fields:"text"
   ParaUI_text = 2,-- bindable fields:"text"
   ParaUI_button = 3,-- bindable fields:"text"
   ParaUI_container = 4,-- bindable fields:"text"
   ParaUI_listbox = 5,-- bindable fields:"text"
   IDE_checkbox = 6,-- bindable fields:"text", "value"
   IDE_radiobox = 7,-- bindable fields:"text", "value", "SelectedIndex"
   IDE_dropdownlistbox = 8,-- bindable fields:"text", "value", TODO: "SelectedIndex"
   IDE_treeview = 9,-- bindable fields: "text", TODO: "value", "SelectedIndex"
   IDE_sliderbar = 10,-- bindable fields: "value"
   IDE_canvas3d = 11,-- bindable fields: "model", "image" are readonly 
   IDE_coloreditor = 12,-- bindable fields: "text" as rgb "255 255 255"
   IDE_editbox = 13,-- bindable fields: "text"  multiline editbox
   IDE_numeric = 14,-- bindable fields: "value"  numeric updown control
   MCML_node = 20,-- bindable fields: SetUIValue and GetUIValue
}
-- e.g. 
   local bindingContext = commonlib.BindingContext:new();
   bindingContext:AddBinding(package, "text", "AssetManager.NewAsset#editboxPackageName", commonlib.Binding.ControlTypes.ParaUI_editbox, "text")
   bindingContext:AddBinding(package, "Category", "AssetManager.comboBoxCategory", commonlib.Binding.ControlTypes.IDE_dropdownlistbox, "text", commonlib.Binding.DataSourceUpdateMode.ReadOnly)
   bindingContext:AddBinding(package, "bDisplayInMainBar", "AssetManager.checkBoxShowInMainbar", commonlib.Binding.ControlTypes.IDE_checkbox, "value", commonlib.Binding.DataSourceUpdateMode.Manual, true)
   bindingContext:AddBinding(treeNode.asset, "filename", "AssetManager.treeViewAssetAttributes", commonlib.Binding.ControlTypes.IDE_treeview, "RootNode#filename<Text>")
   bindingContext:AddBinding(package, "RadioIndex", "radioButton1", commonlib.Binding.ControlTypes.IDE_radiobox, "SelectedIndex")
   bindingContext:AddBinding(package, "Volume", "settings.trackBarVolume", commonlib.Binding.ControlTypes.IDE_sliderbar, "value")         
   bindingContext:AddBinding(function (dataMember, bIsWriting, value)
         -- one needs to ensure that the ParaObject is a valid object. 
         -- usually we bind normal 3d object by getting it dynamically from the scene using ObjEditor.GetObjectByParams(param)
         local att = ParaScene.GetAttributeObject();
         if(not bIsWriting) then
            -- reading from data source
            return att:GetField(dataMember, value or "");
         else
            -- writing to data source
            att:SetField(dataMember, value);
         end
      end, 
      "ClassName", "textBox1", commonlib.Binding.ControlTypes.ParaUI_editbox, "text")
   bindingContext:AddBinding(values, "filePath", "page root name", commonlib.Binding.ControlTypes.MCML_node, "filePath")
   
   
-- call following to pull/push data
bindingContext:UpdateDataToControls()
bindingContext:UpdateControlsToData()

Member Functions

BindingContext:new

create a new binding context

syntax

function BindingContext:new(o)

parameters

o

BindingContext:AddBindingObject

Call this function to add a new binding to the binding context.

• param dataSource :
• param dataMember :
• param binding : commonlib.Binding object, specifying which control to bind to. When constructing a Binding instance, you must specify three items: (1) The name of the control property to bind to. (2) The data source. (3) The navigation path that resolves to a list or property in the data source. A period-delimited navigation path is required when the data source is set to an object that contains multiple DataTable objects

syntax

function BindingContext:AddBindingObject(dataSource, dataMember, binding)

parameters

dataSource
dataMember

| binding | commonlib.Binding object, specifying which control to bind to. When constructing a Binding instance, you must specify three items: (1) The name of the control property to bind to. (2) The data source. (3) The navigation path that resolves to a list or property in the data source. A period-delimited navigation path is required when the data source is set to an object that contains multiple DataTable objects |

BindingContext.ParaSceneBindingFunc

sample binding function (data source) for binding with attribute object field of any ParaObject.

syntax

function BindingContext.ParaSceneBindingFunc(dataMember, bIsWriting, value)

parameters

dataMember
bIsWriting
value

BindingContext:AddBinding

[[ same as AddBindingObject except that multiple calls with the same input will not update the old binding.

• param dataSource : it can be a table (1) or a binding function (2): (1) npl table to which this binding manager is associated. (2) a function (dataMember, bIsWriting, value) end, where
• param dataMember : the self.dataMember is passed to the function.
• param bIsWriting : if true, the function should write the value parameter to the data source. otherwise, it should read and return the value of the data member in the datasource.
• param value : when bIsWriting is true, it denotes the value to be written to the data source. otherwise, it means the default value returned.
• return __ : if bIsWriting is nil, it returns the value of the datamember in the datasource.
• see __ : ParaSceneBindingFunc() for an example.
• param dataMember : string value. it can be something like "level2.level3" to bind to a deep member.
• param ControlName : string: the control name. It may contain # to concartinate parent name with child name.
• param ControlType : type of commonlib.Binding.ControlTypes.
• param ControlPropertyName : if nil, it will bind to the control, and let the control decide how to display data. If it is a IDE control, the binding object will be assigned to the IDE control's databinding field. databinding field in IDE controls, such as TreeNode, will allow the control to dynamically read and write data from data source.
• param DataSourceUpdateMode : type of commonlib.Binding.ControlTypes.
• param NullValue : default value.
• return __ : the Binding object created is returned.

]]

syntax

function BindingContext:AddBinding(dataSource, dataMember, ControlName, ControlType, ControlPropertyName, DataSourceUpdateMode, NullValue)

parameters

| dataSource | it can be a table (1) or a binding function (2): (1) npl table to which this binding manager is associated. (2) a function (dataMember, bIsWriting, value) end, where |

dataMember	string value. it can be something like "level2.level3" to bind to a deep member.
ControlName
ControlType	type of commonlib.Binding.ControlTypes.
ControlPropertyName
DataSourceUpdateMode	type of commonlib.Binding.ControlTypes.
NullValue

| return | the Binding object created is returned. ]] | | return | the Binding object created is returned. ]] |

BindingContext:UpdateDataToControls

Pulls data from the data-bound control into the data source, returning no information.

syntax

function BindingContext:UpdateDataToControls()

BindingContext:UpdateControlsToData

Pushes data from the data source into the data-bound control, returning no information

syntax

function BindingContext:UpdateControlsToData()

BindingContext:Contains

Gets a value indicating whether the BindingContext contains the BindingManager associated with the specified data source (and data member).

• param dataSource : the data source object to search for. Currently only lua table is supported.

TODO

may support db, xml, file in future

• param dataMember : [optional] if nil, it will only search for existance of dataSource. If it is a string, both the dataSource and dataMember is searched. A data member is string name of a sub field or table in the dataSource.
• return __ : true if the BindingManager is found

syntax

function BindingContext:Contains(dataSource, dataMember)

parameters

| dataSource | the data source object to search for. Currently only lua table is supported.

TODO

may support db, xml, file in future |

dataMember
return	true if the BindingManager is found

BindingContext:GetItem

Gets a BindingManager that is associated with the specified data source and data member.

• param dataSource : the data source object to search for. Currently only lua table is supported.

TODO

may support db, xml, file in future

• param dataMember : [optional] if nil, it will only search for existance of dataSource. If it is a string, both the dataSource and dataMember is searched. A data member is string name of a sub field or table in the dataSource.
• return __ : BindingManager is returned otherwise nil.

syntax

function BindingContext:GetItem (dataSource, dataMember)

parameters

| dataSource | the data source object to search for. Currently only lua table is supported.

TODO

may support db, xml, file in future |

dataMember
return	BindingManager is returned otherwise nil.

BindingContext:Add

Adds the BindingManager associated with a specific data source to the collection. it will always create add new one, so it is better to check using Contains() before adding

syntax

function BindingContext:Add(BindingManager)

parameters

BindingManager

BindingContext:Clear

Clears the collection of any BindingManager objects

syntax

function BindingContext:Clear()

BindingContext:Remove

Delete any BindingManager(s) associated with the specified data source.

syntax

function BindingContext:Remove(dataSource)

parameters

dataSource

BindingManager:new

----------------------------------------------------------
 BindingManager: Manages all Binding objects that are bound to the same data source and data member. 
----------------------------------------------------------

local BindingManager = {
   --[[ it can be a table (1) or a function (2): 
      (1) npl table to which this binding manager is associated. 
      (2) a function (dataMember, bIsWriting, value) end, where
   * _param_ __dataMember__ : the self.dataMember is passed to the function. 
   * _param_ __bIsWriting__ : if true, the function should write the value parameter to the data source. otherwise, it should read and return the value of the data member in the datasource. 
   * _param_ __value__ : only used when bIsWriting is true, which denotes the value to be written to the data source. 
   * _return_ ____ : if bIsWriting is nil, it returns the value of the datamember in the datasource. 
   ]]
   dataSource = nil,
   -- a member name (string) in the dataSource to which all binding objects of this manager is associated. 
   -- it can also be a function (dataSource, bIsWriting, value) end
   dataMember = nil,
   -- if the data member in the dataSource is an array, this is the current position (1-based index) in the array. 
   -- this parameter has no effect if the dataMember is a property field, rather than an array. 
   Position = 1,
   -- the collection of all Binding objects 
   Bindings = {},
}

;

commonlib.BindingManager = BindingManager;

create a new BindingManager

syntax

function BindingManager:new(o)

parameters

o

BindingManager:GetCurrentValue

get the current object at current position. The dataMember itself is returned if it is not an array table.

syntax

function BindingManager:GetCurrentValue()

BindingManager:SetCurrentValue

set the current object at current position. The dataMember itself is returned if it is not an array table.

syntax

function BindingManager:SetCurrentValue(value)

parameters

value

BindingManager:Add

Adds a binding to the bindings collection. it will always create add new one, so it is better to check using Contains() before adding

syntax

function BindingManager:Add(binding)

parameters

binding

BindingManager:Contains

whether the manager contains a given binding

syntax

function BindingManager:Contains(ControlName, ControlType, ControlPropertyName)

parameters

ControlName
ControlType
ControlPropertyName

BindingManager:GetBinding

return a binding

syntax

function BindingManager:GetBinding(ControlName, ControlType, ControlPropertyName)

parameters

ControlName
ControlType
ControlPropertyName

BindingManager:PullData

Pulls data from the data-bound control into the data source, returning no information.

syntax

function BindingManager:PullData()

BindingManager:PushData

Pushes data from the data source into the data-bound control, returning no information

syntax

function BindingManager:PushData()

BindingManager:AddNew

-- for array type dataMember

syntax

function BindingManager:AddNew()

Binding:new

--------------------------------------------------
 Binding: Represents the simple binding between the property value of an NPL table(or the property of the current object in an array) and the property value of an IDE control or ParaUIObject. 
 e.g. you can bind the text property of an EditBox control to the FirstName property of a Customer table.
--------------------------------------------------
local Binding = {
   -- string: Set/Get the IDE control name (it may also be the control itself) or ParaUIObject name(it may be childname#childname) that the binding belongs to.
   ControlName = nil,
   -- type of control in commonlib.Binding.ControlTypes 
   ControlType = nil,
   -- string: Gets or sets the name of the control's data-bound property. 
   ControlPropertyName = nil, 
   -- how data source is updated. type of commonlib.Binding.DataSourceUpdateMode. It defaults to Manual update. 
   UpdateMode = nil,
   -- values provided to the control if the dataMember is nil. 
   NullValue = nil,
   -- the parent BindingManager object
   BindingManager = nil, 
};
commonlib.Binding = Binding;

 supported control types
commonlib.Binding.ControlTypes = {
   ParaUI_editbox = 1, -- bindable fields:"text"
   ParaUI_text = 2,-- bindable fields:"text"
   ParaUI_button = 3,-- bindable fields:"text"
   ParaUI_container = 4,-- bindable fields:"text"
   ParaUI_listbox = 5,-- bindable fields:"text"
   IDE_checkbox = 6,-- bindable fields:"text", "value"
   IDE_radiobox = 7,-- bindable fields:"text", "value", "SelectedIndex"
   IDE_dropdownlistbox = 8,-- bindable fields:"text", TODO: "SelectedIndex"
   -- bindable fields(TreeNode or treenode property): "RootNode#SubNode", "RootNode#SubNode<propertyName>", TODO: "value", "SelectedNodePath"
   -- Note: Please note that the root node name must begins with "Root"
   -- bind a table(dataMember needs to be a table) to a treenode like this "RootNode#SubNode", it uses partial copy when updating. i.e. it only updates fields inside the data member with the treenode. 
   -- bind a property dataMember to a treenode propery like this "RootNode#SubNode<propertyName>"
   -- Note: the treeview is not immediately updated when update controls on binding context, one needs to manually call update. 
   IDE_treeview = 9,
   IDE_sliderbar = 10, -- bindable fields:"value"
   IDE_canvas3d = 11,-- bindable fields: "model", "image"
   IDE_coloreditor = 12,-- bindable fields: "text" as rgb "255 255 255"
   IDE_editbox = 13,-- bindable fields: "text"  multiline editbox
   IDE_numeric = 14,-- bindable fields: "value"  numeric updown control
   
   MCML_node = 20,-- bindable fields: SetUIValue  and GetUIValue
}

 Specifies when a data source is updated when changes occur in the bound control. 
commonlib.Binding.DataSourceUpdateMode  = {
   -- [default]: Data source is manually updated by calling the push/pull data or update functions on binding or binding context level.
   Manual = nil,
   -- Data source is never updated and values entered into the control are not parsed, validated or re-formatted.  
   ReadOnly = 1,
   -- Data source is updated whenever the value of the control property changes.
   OnPropertyChanged = 2,
   -- Data source is updated when the control property is validated,  After validation, the value in the control property will also be re-formatted.
   OnValidation = 3,
}

create a new BindingManager

syntax

function Binding:new(o)

parameters

o

Binding:ToString

convert to string. mostly for logging debugging info.

syntax

function Binding:ToString()

Binding:GetValue

get the current value

syntax

function Binding:GetValue()

Binding:ReadValue

Sets the control property to the value read from the data source.

syntax

function Binding:ReadValue()

Binding:WriteValue

Reads the current value from the control property and writes it to the data source.

syntax

function Binding:WriteValue()