CommonCtrl.TreeView

Displays hierarchical data, such as a table of contents, in a tree structure. It can handle tons of data

Title	Displays hierarchical data, such as a table of contents, in a tree structure. It can handle tons of data
Author(s)	LiXizhi
Date	2007/9/19
File	script/ide/TreeView.lua

Description

Sample Code

NPL.load("(gl)script/ide/TreeView.lua");
local ctl = CommonCtrl.TreeView:new{
   name = "TreeView1",
   alignment = "_lt",
   left=0, top=0,
   width = 200,
   height = 200,
   parent = nil,
   -- function DrawNodeEventHandler(parent,treeNode) end, where parent is the parent container in side which contents should be drawn. And treeNode is the TreeNode object to be drawn
   -- the function return nil or the new height if current node height is not suitable, it will cause the node to be redrawn.
   -- predefined handlers: 
   --  CommonCtrl.TreeView.DrawPropertyNodeHandler  if one uses data binding controls. 
   --  CommonCtrl.TreeView.DrawSingleSelectionNodeHandler  if one wants to high light the current selection. 
   DrawNodeHandler = nil,
};
local node = ctl.RootNode;
node:AddChild("Node1");
node:AddChild(CommonCtrl.TreeNode:new({Text = "Node2", Name = "sample"}));
node = node:AddChild("Node3");
node = node:AddChild("Node3_1");
node = node:AddChild("Node3_1_1");
ctl.RootNode:AddChild("Node4");
ctl.RootNode:AddChild("Node5");

-- automatically bind to an attribute object or NPL table: use DrawPropertyNodeHandler handler. 
-- node:BindParaAttributeObject(nil, ParaScene.GetAttributeObject(), true)
-- node:BindNPLTable(bindingContext, o, bReadOnly, fieldNames, fieldTextReplaceables)

ctl:Show();
-- One needs to call Update() if made any modifications to the TreeView after the Show() method, such as adding or removing new nodes, or changing text of a given node. 
-- ctl:Update();
-- node:SortChildren(CommonCtrl.TreeNode.GenerateGreaterCFByField("Text")); -- sort children by field

Member Functions

TreeNode:new

 common control library
NPL.load("(gl)script/ide/common_control.lua");

------------------------------------------------------------

-- Tree Node

------------------------------------------------------------

 Represents a node of a TreeView. 
local TreeNode = {
   -- Gets the parent tree node of the current tree node. 
   parent = nil, 
   -- Gets the parent tree view that the tree node is assigned to. 
   TreeView = nil,
   -- Gets the zero-based depth of the tree node in the TreeView control 
   Level = 0,  
   -- Gets the array of TreeNode objects assigned to the current tree node.
   Nodes = nil,
   -- Gets a value indicating whether the tree node is in the expanded state. 
   Expanded = true,
   -- Gets a value indicating whether the tree node is in the selected state. 
   Selected = nil, 
   -- if true, node is invisible.
   Invisible = nil,
   -- Gets or sets the name of the tree node. 
   Name = nil,
   -- Gets or sets the text displayed in the label of the tree node. 
   Text = nil,
   -- Gets or sets the text color
   TextColor = nil,
   -- Gets or sets the URL to navigate to when the node is clicked. 
   NavigateUrl = nil, 
   -- Gets or sets a non-displayed value used to store any additional data about the node, such as data used for handling postback events. 
   Value  = nil,
   -- some predefined type, it only takes effect if one chooses to use the default draw node handler provided by this class
   -- nil, "Title", "separator"
   Type = nil,
   -- Gets or sets the object that contains data about the tree node. 
   Tag = nil,
   -- Gets or sets the text that appears when the mouse pointer hovers over a TreeNode. 
   ToolTipText = nil,
   -- icon texture file
   Icon = nil,
   -- Gets or sets the key for the image associated with this tree node when the node is in an unselected state. 
   -- this can be a index which index into TreeView.ImageList[ImageKey] or it can be a string of image file path or URL.
   ImageKey = nil,
   -- Gets or sets the key of the image displayed in the tree node when it is in a selected state.
   -- this can be a index which index into TreeView.ImageList[ImageKey] or it can be a string of image file path or URL.
   SelectedImageKey = nil,  
   -- Height of this tree node, if this is nil, TreeView.DefaultNodeHeight will be used
   NodeHeight = nil,
   -- string to be executed or a function of format function FuncName(treeNode) end
   onclick = nil,
   --------------------------------
   -- internal parameters, do not use externally
   --------------------------------
   -- logical position of the node relative to the tree view container. 
   LogicalX = 0,
   LogicalY = 0,
   -- logical position for the right bottom corner of this node and all its children
   LogicalRight = 0,
   LogicalBottom = 0,
   -- internal index of this node. such that self.parent[self.index] is self. 
   index = 0,
   -- render line index
   lineindex = 0,
   
}

TreeNode? = TreeNode? ;

constructor

syntax

function TreeNode:new (o)

parameters

o

TreeNode:GetChildCount

Get child count

syntax

function TreeNode:GetChildCount()

TreeNode:ClearAllChildren

Clear all child nodes

syntax

function TreeNode:ClearAllChildren()

TreeNode:Resize

resize of the number of first level childs. This function only delete child, but never add child if current child count is smaller than nCount.

syntax

function TreeNode:Resize(nCount)

parameters

nCount

TreeNode:SwapChildNodes

swap two child objects at the given index. this is used when sorting child nodes.

syntax

function TreeNode:SwapChildNodes(index1, index2)

parameters

index1
index2

TreeNode.CompareNodeByText

a default compare function. this is equavalaent to GenerateCFByField? ("Text")

syntax

function TreeNode.CompareNodeByText(node1, node2)

parameters

node1
node2

TreeNode.GenerateLessCFByField

generate a less compare function according to a node field name.

• param fieldName : the name of the field, such as "Text", "Name", etc

syntax

function TreeNode.GenerateLessCFByField(fieldName)

parameters

fieldName	the name of the field, such as "Text", "Name", etc

TreeNode.GenerateGreaterCFByField

generate a greater compare function according to a node field name.

• param fieldName : the name of the field, such as "Text", "Name", etc

syntax

function TreeNode.GenerateGreaterCFByField(fieldName)

parameters

fieldName	the name of the field, such as "Text", "Name", etc

TreeNode:SortChildren

sorting the children according to a compare function. Internally it uses table.sort(). compareFunc: if nil, it will compare by Node.Text. One can also build a compare function by calling GenerateLessCFByField? (fieldName) or GenerateGreaterCFByField? (fieldName)

syntax

function TreeNode:SortChildren(compareFunc)

parameters

compareFunc

TreeNode:AddChild

Add a new child node, the child node is returned

• param o : it can be a tree node object such as using TreeNode? :new() or just a string.
• param index : nil or index at which to insert the object. if nil, it will inserted to the last element. if 1, it will inserted to the first element.

syntax

function TreeNode:AddChild(o, index)

parameters

o	it can be a tree node object such as using TreeNode? :new() or just a string.
index

TreeNode:RemoveChildByName

remove all occurance of first level child node whose name is name

syntax

function TreeNode:RemoveChildByName(name)

parameters

name

TreeNode:Detach

detach this node from its parent node.

syntax

function TreeNode:Detach()

TreeNode:GetChildByName

get the first occurance of first level child node whose name is name

syntax

function TreeNode:GetChildByName(name)

parameters

name

TreeNode:GetChildByNamePath

get the first occurance of the child node whose name is name. It will recursively search child nodes. Note: we do not guarantee that all child nodes have a unique name

• param __ : a string containing the node name path, separated by #, such as "RootNode#ChildNode#SubNode". usually a value returned by the node:GetNodeNamePath().

syntax

function TreeNode:GetChildByNamePath(name)

parameters

name

TreeNode:GetChildByText

get the first occurance of first level child node whose text is text

syntax

function TreeNode:GetChildByText(Text)

parameters

Text

TreeNode:NewSubControlName

create a new sub control name: reuse control names as much as possible while ensuring that all visible control names are unique.

syntax

function TreeNode:NewSubControlName()

TreeNode:DeleteAllSubControls

delete all sub controls, whose name is created by NewSubControlName? .

syntax

function TreeNode:DeleteAllSubControls()

TreeNode:Expand

Expands the current tree node.

syntax

function TreeNode:Expand()

TreeNode:ExpandAll

Expands the current node and all its child nodes.

syntax

function TreeNode:ExpandAll()

TreeNode:Collapse

Collapses the current tree node.

syntax

function TreeNode:Collapse()

TreeNode:CollapseAll

Collapses the current node and all its child nodes.

syntax

function TreeNode:CollapseAll()

TreeNode:Update

after the content of a tree node is changed, one may need to call this function at the root node

• param x :,y: logical position
• return __ : logical position for the sibling node

syntax

function TreeNode:Update(x, y)

parameters

x	,y: logical position
y

TreeNode:GetNodePath

get a string containing the node path. such as "0/1/1/3" as long as the TreeNode? does not change, the node path uniquely identifies a TreeNode? .

syntax

function TreeNode:GetNodePath()

TreeNode:GetNodeNamePath

get a string containing the node name path, separated by #, such as "RootNode#ChildNode#SubNode" Note: we do not guarantee that all child nodes have a unique name

syntax

function TreeNode:GetNodeNamePath()

TreeNode:GetNodeByPoint

get the best matched node that contains the logical point x,y. This function is usually called on the root node. it calls recursively.

• param x :,y: logical position
• return __ : logical position for the sibling node

syntax

function TreeNode:GetNodeByPoint(x, y)

parameters

x	,y: logical position
y

TreeNode:GetNextNode

get the next node in render order. it can be first child node or the sibling node or the sibling of its parent node or nil for last node.

• param skipchildren : true to skip child nodes. otherwise nil.

syntax

function TreeNode:GetNextNode(skipchildren)

parameters

skipchildren	true to skip child nodes. otherwise nil.

TreeNode:GetNextNode2

same as GetNextNode? (), except that it will not skip expanded node.

syntax

function TreeNode:GetNextNode2(skipchildren)

parameters

skipchildren

TreeNode:GetIndentation

get indentation. If the parent height is 0 the current node will not indent from parent.

syntax

function TreeNode:GetIndentation()

TreeView:new

------------------------------------------------------------

-- TreeView

------------------------------------------------------------

 Displays hierarchical data, such as a table of contents, in a tree structure.
local TreeView = {
   -- the top level control name
   name = "TreeView1",
   -- normal window size
   alignment = "_lt",
   left = 0,
   top = 0,
   width = 300,
   height = 26, 
   parent = nil,
   -- appearance
   container_bg = nil, -- the background of container
   main_bg = "", -- the background of container without scrollbar, default to full transparent
   -- automatically display vertical scroll bar when content is large
   AutoVerticalScrollBar = true,
   -- true to disable mouse wheel to scroll content. call EnableMouseWheel to alter setting at runtime. 
   disablemousewheel = nil,
   -- if true, vertical scroll bar is created but is invisible
   HideVerticalScrollBar = nil,
   -- Vertical ScrollBar Width
   VerticalScrollBarWidth = 15,
   -- how many pixels to scroll each time
   VerticalScrollBarStep = 3,
   -- how many pixels to scroll when user hit the empty space of the scroll bar. this is usually same as DefaultNodeHeight
   VerticalScrollBarPageSize = 24,
   -- The root tree node. containing all tree node data
   RootNode = nil, 
   -- Default height of Tree Node
   DefaultNodeHeight = 24,
   -- default icon size
   DefaultIconSize = 16,
   -- whether to show icon on the left of each line. 
   ShowIcon = true,
   -- default indentation
   DefaultIndentation = 5,
   -- Gets or sets a function by which the individual TreeNode control is drawn. The function should be of the format:
   -- function DrawNodeEventHandler(parent,treeNode) end, where parent is the parent container in side which contents should be drawn. And treeNode is the TreeNode object to be drawn
   -- if DrawNode is nil, the default TreeView.DrawNormalNodeHandler function will be used. 
   DrawNodeHandler = nil,
   -- Cache size: The number of TreeNode controls to be cached. [N/A]
   CacheSize = 30,
   -- Force no clipping or always using fast render. Unless you know that the unit scroll step is interger times of all TreeNode height. You can disable clipping at your own risk. 
   -- Software clipping is always used to clip all invisible TreeNodes. However, this option allows you to specify whether to use clipping for partially visible TreeNode. 
   NoClipping = nil,
   -- a function of format function FuncName(treeNode) end or nil
   onclick = nil,
   -- function (self) end called, when click the parent container. parent container can only be clicked when there is not enough line taking the full treeview space. 
   onmouseup_parent = nil,
   -- only used in property view: the percentage of width used to display the name text. 
   PropertyNameWidthPercentage = 0.4,
   --------------------------------
   -- internal parameters, do not use externally
   --------------------------------
   -- the client area X, Y position in pixels relative to the logical tree view container. 
   ClientX = 0,
   ClientY = 0,
   -- this is automatically set according to whether a scroll bar is available.
   ClientWidth = 10,
   ClientHeight = 10,
   -- a mapping from node path to existing line control container index, the total number of mapping here does not exceed CacheSize
   NodeUIContainers = {},
}

TreeView? = TreeView;

constructor

syntax

function TreeView:new (o)

parameters

o

TreeView:Show

• param bShow : boolean to show or hide. if nil, it will toggle current setting.
• param bDoNotUpdate : Most the time, this is nil. If true, it will not update the treeview; this usually happens when people wants to perform some sort and then call Update manually.
• return __ : true if control is updated.

syntax

function TreeView:Show(bShow, bDoNotUpdate)

parameters

bShow	boolean to show or hide. if nil, it will toggle current setting.
bDoNotUpdate
return	true if control is updated.

TreeView:Update

this function should be called whenever the layout of the tree view changed. internally, it will recalculate all node logical positions.

• param bShowLastElement : true to show the last element, otherwise ShowNode? or show position is not changed.
• param ShowNode : nil or a treeNode. It will scroll for the best show of the node element. This is usually used when expanding a tree node.
• param DisableRecursive : internally used: disable recursive call of this function.

syntax

function TreeView:Update(bShowLastElement, ShowNode, DisableRecursive)

parameters

bShowLastElement	true to show the last element, otherwise ShowNode? or show position is not changed.
ShowNode
DisableRecursive	internally used: disable recursive call of this function.

TreeView:RefreshUI

this function is called whenever the user scrolls the TreeView.

syntax

function TreeView:RefreshUI(DisableRecursive)

parameters

DisableRecursive

TreeView:ScrollToEnd

Scroll to show the last element. One need to call RefreshUI? for this to take effect on UI.

syntax

function TreeView:ScrollToEnd()

TreeView:GetNodeByPath

get a string containing the node path. such as "0/1/1/3" as long as the TreeNode? does not change, the node path uniquely identifies a TreeNode? .

syntax

function TreeView:GetNodeByPath(path)

parameters

path

TreeView:ShowRootNode

public: whether to draw the root node. Default to false

syntax

function TreeView:ShowRootNode(bShow)

parameters

bShow

TreeView:EnableMouseWheel

whether to allow mouse wheel to scroll the content of treeview. default to true.

syntax

function TreeView:EnableMouseWheel(bEnable)

parameters

bEnable

TreeView.OnTreeViewMouseWheel

private: called whenever the mouse wheel is detected in each TreeNode? container

syntax

function TreeView.OnTreeViewMouseWheel(sCtrlName)

parameters

sCtrlName

TreeView.OnVScrollBarChanged

private: called whenever the vScroll bar is changed

syntax

function TreeView.OnVScrollBarChanged(sCtrlName)

parameters

sCtrlName

TreeView.OnToggleNode

private function: called by default TreeNode? UI

syntax

function TreeView.OnToggleNode(sCtrlName, nodePath)

parameters

sCtrlName
nodePath

TreeView.OnClickNode

private function: called by default TreeNode? UI

syntax

function TreeView.OnClickNode(sCtrlName, nodePath)

parameters

sCtrlName
nodePath

TreeView.OnSelectNode

private function: same as OnClickNode? except that it remembers a single selection.

syntax

function TreeView.OnSelectNode(sCtrlName, nodePath)

parameters

sCtrlName
nodePath

TreeNode:SelectMe

select this tree node, but it does not invoke the onclick method on the node.

• param bUpdateUI : if true, the entire treeview is updated.

syntax

function TreeNode:SelectMe(bUpdateUI)

parameters

bUpdateUI	if true, the entire treeview is updated.

TreeView.DrawSingleSelectionNodeHandler

single selection node renderer: it only differs from DrawNormalNodeHandler? that the currently selected leaf node is high lighted.

syntax

function TreeView.DrawSingleSelectionNodeHandler(_parent,treeNode)

parameters

parent
treeNode

TreeNode:BindNPLTable

[[ generate all sub nodes according to a given ParaAttributeObject? . Each propery field in the attribute object are binded to a sub tree node of the current node. In order to render the treeNode properly, one needs to use the DrawPropertyNodeHandler? handler in the treeview. note: there is no need to call bindingContext:UpdateDataToControls() after calling this.

• param bindingContext : the binding context with which the bindings are associated. if nil, a new binding context will be created.
• param o : the NPL table
• param bReadOnly : true if the binding is readonly. Please note if some property is read only, it will be readonly even if this value is nil.
• param fieldNames : if nil, all known propery fields in the attributes objects are binded.

otherwise

it is an array of attribute names that will be binded. such as {"ClassName", "ClassID",}. They will appear in the given order.

• param fieldTextReplaceables : it a table mapping field names to field text. If this is nil or the mapping is not found, the field name will be used as the tree node text. such as {["ClassName"] = "Name of the class", ["ClassID"] = "unique identifier"}

]]

syntax

function TreeNode:BindNPLTable(bindingContext, o, bReadOnly, fieldNames, fieldTextReplaceables)

parameters

bindingContext	the binding context with which the bindings are associated. if nil, a new binding context will be created.
o
bReadOnly	true if the binding is readonly. Please note if some property is read only, it will be readonly even if this value is nil.
fieldNames

| fieldTextReplaceables | it a table mapping field names to field text. If this is nil or the mapping is not found, the field name will be used as the tree node text. such as {["ClassName"] = "Name of the class", ["ClassID"] = "unique identifier"} ]] |

TreeNode:BindParaAttributeObject

[[ generate all sub nodes according to a given ParaAttributeObject? . Each propery field in the attribute object are binded to a sub tree node of the current node. In order to render the treeNode properly, one needs to use the DrawPropertyNodeHandler? handler in the treeview. note: there is no need to call bindingContext:UpdateDataToControls() after calling this.

• param bindingContext : the binding context with which the bindings are associated. if nil, a new binding context will be created.
• param att : the ParaAttributeObject? itself or a function () end that returns the att object.
• param bReadOnly : true if the binding is readonly. Please note if some property is read only, it will be readonly even if this value is nil.
• param fieldNames : if nil, all known propery fields in the attributes objects are binded.

otherwise

it is an array of attribute names that will be binded. such as {"ClassName", "ClassID",}. They will appear in the given order.

• param fieldTextReplaceables : it a table mapping field names to field text. If this is nil or the mapping is not found, the field name will be used as the tree node text. such as {["ClassName"] = "Name of the class", ["ClassID"] = "unique identifier"}

]]

syntax

function TreeNode:BindParaAttributeObject(bindingContext, att, bReadOnly, fieldNames,fieldTextReplaceables)

parameters

bindingContext	the binding context with which the bindings are associated. if nil, a new binding context will be created.
att
bReadOnly	true if the binding is readonly. Please note if some property is read only, it will be readonly even if this value is nil.
fieldNames

| fieldTextReplaceables | it a table mapping field names to field text. If this is nil or the mapping is not found, the field name will be used as the tree node text. such as {["ClassName"] = "Name of the class", ["ClassID"] = "unique identifier"} ]] |

TreeView.OnPropertyValueChanged_String

only used by property node handler. whenever a string typed property changes, it will update the treeNode.propertyValue field with the new value.

syntax

function TreeView.OnPropertyValueChanged_String(sCtrlName,nodePath, ctrlname)

parameters

sCtrlName
nodePath
ctrlname

TreeView.DrawPropertyNodeHandler

[[ draw property node: each node may be a readonly or editable text, boolean, int, float, color, radiobox, dropdownlistbox, etc field. ]]

syntax

function TreeView.DrawPropertyNodeHandler(_parent,treeNode)

parameters

parent
treeNode

TreeView.RenderCategoryNode

render a category node that can expand child nodes.

syntax

function TreeView.RenderCategoryNode(_parent,treeNode, left, top, width, height)

parameters

parent
treeNode
left
top
width
height

TreeView.RenderTextNode

render a category node that can expand child nodes.

syntax

function TreeView.RenderTextNode(_parent,treeNode, left, top, width, height)

parameters

parent
treeNode
left
top
width
height

TreeView.GetCtl

Helper function: return treeView, treeNode.

syntax

function TreeView.GetCtl(sCtrlName,nodePath)

parameters

sCtrlName
nodePath