---++!! !commonlib.DataBinding %TOC{title="Contents:"}% %STARTINCLUDE% ---++ 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). %T% __Sample Code__ <verbatim> 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() </verbatim> ---+++ Member Functions ---++++ !BindingContext:new create a new binding context __syntax__ <verbatim>function BindingContext:new(o)</verbatim> __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__ <verbatim>function BindingContext:AddBindingObject(dataSource, dataMember, binding)</verbatim> __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__ <verbatim>function BindingContext.ParaSceneBindingFunc(dataMember, bIsWriting, value)</verbatim> __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_ ____ : BindingContext.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__ <verbatim>function BindingContext:AddBinding(dataSource, dataMember, ControlName, ControlType, ControlPropertyName, DataSourceUpdateMode, NullValue)</verbatim> __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__ <verbatim>function BindingContext:UpdateDataToControls()</verbatim> ---++++ !BindingContext:UpdateControlsToData Pushes data from the data source into the data-bound control, returning no information __syntax__ <verbatim>function BindingContext:UpdateControlsToData()</verbatim> ---++++ !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__ <verbatim>function BindingContext:Contains(dataSource, dataMember)</verbatim> __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__ <verbatim>function BindingContext:GetItem (dataSource, dataMember)</verbatim> __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__ <verbatim>function BindingContext:Add(BindingManager)</verbatim> __parameters__ | *BindingManager* | | ---++++ !BindingContext:Clear Clears the collection of any BindingManager objects __syntax__ <verbatim>function BindingContext:Clear()</verbatim> ---++++ !BindingContext:Remove Delete any BindingManager(s) associated with the specified data source. __syntax__ <verbatim>function BindingContext:Remove(dataSource)</verbatim> __parameters__ | *dataSource* | | ---++++ !BindingManager:new <verbatim>---------------------------------------------------------- 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 = {}, }</verbatim>; commonlib.BindingManager = BindingManager; create a new BindingManager __syntax__ <verbatim>function BindingManager:new(o)</verbatim> __parameters__ | *o* | | ---++++ !BindingManager:GetCurrentValue get the current object at current position. The dataMember itself is returned if it is not an array table. __syntax__ <verbatim>function BindingManager:GetCurrentValue()</verbatim> ---++++ !BindingManager:SetCurrentValue set the current object at current position. The dataMember itself is returned if it is not an array table. __syntax__ <verbatim>function BindingManager:SetCurrentValue(value)</verbatim> __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__ <verbatim>function BindingManager:Add(binding)</verbatim> __parameters__ | *binding* | | ---++++ !BindingManager:Contains whether the manager contains a given binding __syntax__ <verbatim>function BindingManager:Contains(ControlName, ControlType, ControlPropertyName)</verbatim> __parameters__ | *ControlName* | | | *ControlType* | | | *ControlPropertyName* | | ---++++ !BindingManager:GetBinding return a binding __syntax__ <verbatim>function BindingManager:GetBinding(ControlName, ControlType, ControlPropertyName)</verbatim> __parameters__ | *ControlName* | | | *ControlType* | | | *ControlPropertyName* | | ---++++ !BindingManager:PullData Pulls data from the data-bound control into the data source, returning no information. __syntax__ <verbatim>function BindingManager:PullData()</verbatim> ---++++ !BindingManager:PushData Pushes data from the data source into the data-bound control, returning no information __syntax__ <verbatim>function BindingManager:PushData()</verbatim> ---++++ !BindingManager:AddNew -- for array type dataMember __syntax__ <verbatim>function BindingManager:AddNew()</verbatim> ---++++ !Binding:new <verbatim>-------------------------------------------------- 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, }</verbatim> create a new BindingManager __syntax__ <verbatim>function Binding:new(o)</verbatim> __parameters__ | *o* | | ---++++ !Binding:ToString convert to string. mostly for logging debugging info. __syntax__ <verbatim>function Binding:ToString()</verbatim> ---++++ !Binding:GetValue get the current value __syntax__ <verbatim>function Binding:GetValue()</verbatim> ---++++ !Binding:ReadValue Sets the control property to the value read from the data source. __syntax__ <verbatim>function Binding:ReadValue()</verbatim> ---++++ !Binding:WriteValue Reads the current value from the control property and writes it to the data source. __syntax__ <verbatim>function Binding:WriteValue()</verbatim> %STOPINCLUDE%
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r1
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
Topic revision: r1 - 2008-02-29
-
LiXizhi
Home
Site map
CCWeb web
HaqiTeen web
Main web
ParaEngine web
TWiki web
Main Web
Users
Groups
Index
Search
Changes
Notifications
RSS Feed
Statistics
导航页WebTopMenu
Preferences
开发指南
Getting Started
ParacraftSDK
NPL
MCML
NPL Reference Manual
美术Mod
Account
Log In
English
简体中文
簡體中文
E
dit
A
ttach
Copyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki?
Send feedback