GridView < Main

CommonCtrl.GridView

GridView is a container showing 2 dimensional array of data in matrix display form.

Title	GridView is a container showing 2 dimensional array of data in matrix display form.
Author(s)	WangTian
Date	2007/11/19
File	script/ide/GridView.lua

Description

Sample Code

NPL.load("(gl)script/ide/GridView.lua");
local ctl = CommonCtrl.GridView:new{

-- more comments for gridview


   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
   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");

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();

Member Functions

GridCell:new

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

------------------------------------------------------------
Grid Cell
------------------------------------------------------------

Represents a cell of a GridView.
local GridCell = {
---- Gets the parent tree node of the current tree node.
--parent = nil,
-- Gets the ancister grid view that the grid cell is assigned to.
GridView = nil,
-- Gets or sets the name of the grid cell.
name = nil,
-- Gets or sets the text displayed in the label of the grid cell.
text = nil,
-- column index of this cell in the gridview, from 1
column = nil,
-- row index of this cell in the gridview, from 1
row = nil,

-- Appearances : Added by LiXizhi 2008.4.19
font = nil,
font_color = 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 grid cell is in the selected state.
--Selected = nil,
---- if true, node is invisible.
--Invisible = nil,
---- Gets or sets the URL to navigate to when the cell is clicked.
--NavigateUrl = nil,
---- Gets or sets a non-displayed value used to store any additional data about the cell, such as data used for handling postback events.
--Value = nil,
---- Gets or sets the object that contains data about the grid cell.
--Tag = nil,
---- Gets or sets the text that appears when the mouse pointer hovers over a grid cell.
--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,
------ Width of this grid cell, if this is nil, GridView.DefaultCellWidth will be used
----CellWidth = nil,
------ Height of this grid cell, if this is nil, GridView.DefaultCellHeight will be used
----CellHeight = nil,
---- string to be executed or a function of format function FuncName(gridCell) end
--onclick = nil,

--------------------------------
-- internal parameters, do not use externally
--------------------------------
-- logical position of the node relative to the grid view container.
logicalX = 0,
logicalY = 0,

---- logical position for the right bottom corner of this cell
--logicalRight = 0,
--logicalBottom = 0,
---- internal column index of this cell. such that ...
--indexColumn = 0,
---- internal row index of this cell. such that ...
--indexRow = 0,
---- render column index
--columnindex = 0,
---- render row index
--rowindex = 0,
}

GridCell = GridCell;

constructor

syntax

function GridCell:new (o)

parameters

o

GridCell:GetCellCoord

TODO: implement this funciton in the grid view

after the content of a grid cell is changed, one may need to call this function at the GridView

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

function GridCell:Update(x, y) -- ---- TODO: move this function to GridView? --self.LogicalX = x; --self.LogicalY = y; --if(not self.Invisible) then ----log(self:GetNodePath()..", "..y.."\n") --x,y = x, y + self:GetHeight(); -- --if(self.Expanded) then --local nSize = table.getn(self.Nodes); --local i, node; --for i=1, nSize do --node = self.Nodes[i]; --if(node ~=nil) then --x,y = node:Update(x, y); --end --end --end --end --self.LogicalBottom = y; --return x,y; end

get a string containing the cell coordinate as long as the GridView does not change, the cell coordinate uniquely identifies a GridCell.

return __ : row, column

syntax

function GridCell:GetCellCoord()

parameters

return	row, column

GridCell:GetSiblingCellUp

get the sibling Up/Down/Left/Right cell

syntax

function GridCell:GetSiblingCellUp()

GridView:new

------------------------------------------------------------
 GridView
------------------------------------------------------------

 GridView is a container showing 2 dimensional array of data in matrix display form.
local GridView = {
   -- the top level control name
   name = "GridView1",
   -- normal window size
   alignment = "_lt",
   left = 0,
   top = 0,
   width = 300,
   height = 300, 
   --buttonwidth = 20, -- the drop down button width
   --dropdownheight = 150, -- the drop down list box height.
   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,
   ---- automatically display horizontal scroll bar when content is large
   --AutoHorizontalScrollBar = true,
   ---- Vertical ScrollBar Width
   --VerticalScrollBarWidth = 15,
   ---- Horizontal ScrollBar Width
   --HorizontalScrollBarWidth = 15,
   ---- how many pixels to scroll each time
   --VerticalScrollBarStep = 3,
   ---- how many pixels to scroll each time
   --HorizontalScrollBarStep = 3,
   ---- how many pixels to scroll when user hit the empty space of the scroll bar.
   ----      this is usually same as DefaultCellHeight
   --VerticalScrollBarPageSize = 48,
   ---- how many pixels to scroll when user hit the empty space of the scroll bar.
   ----      this is usually same as DefaultCellWidth
   --HorizontalScrollBarPageSize = 48,
   ---- The root tree node. containing all tree node data
   --RootNode = nil, 
   
   
   -- row data containing all the gridcells organized in rows
   -- table indexed by rows
   -- each row table contains a subtable indexed by columns, each entry is a grid cell
   -- both index from 1
   cells = {};
   
   -- number of columns in the gridview
   columns = nil,
   -- number of rows in the gridview
   rows = nil,
   
   
   -- cell width and cell height
   -- NOTE: Current version only supports the same width and height gridcell defined in the GridView
   cellWidth = 36,
   cellHeight = 36,
   
   -- different with the tree view
   defaultCellWidth = 24,
   defaultCellHeight = 24,
   
   -- Gets or sets a function by which the individual GridCell control is drawn. The function should be of the format:
   -- function DrawCellEventHandler(parent,gridcell) end, where parent is the parent container in side which contents should be drawn.
   --      And gridcell is the GridCell object to be drawn
   -- if DrawCellHandler is nil, the default GridView.DrawNormalCellHandler function will be used.
   DrawCellHandler = nil,
   -- 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. 
   fastrender = nil,
   
   ----------------------------------
   ---- internal parameters, do not use externally
   ----------------------------------
   
   -- number of columns in the gridview client area
   clientColumns = nil,
   -- number of rows in the gridview client area
   clientRows = nil,
   
   -- row ID of the left top cell in the gridview client area
   clientLeftTopCellRow = nil,
   -- column ID of the left top cell in the gridview client area
   clientLeftTopCellColumn = nil,
   
   -- this is automatically set according to whether a scroll bar is available.
   clientWidth = 10;
   clientHeight = 10;
   
   
   ---- 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 GridView.DrawNormalNodeHandler function will be used. 
   --DrawNodeHandler = nil,
   ---- Cache size: The number of TreeNode controls to be cached. [N/A]
   --CacheSize = 30,
   ---- a function of format function FuncName(treeNode) end or nil
   --onclick = nil,
   ----------------------------------
   ---- internal parameters, do not use externally
   ----------------------------------
   ---- top left cell and bottom right cell mainly for the horizontal and vertical scroll bar available
   --TopLeftCell = nil,
   --BottomRightCell = nil,
   ---- 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 = {},
}

GridView = GridView;

constructor

syntax

function GridView:new (o)

parameters

o

GridView:Show

param bShow : boolean to show or hide. if nil, it will toggle current setting.

syntax

function GridView:Show(bShow)

parameters

bShow	boolean to show or hide. if nil, it will toggle current setting.

GridView:Update

this function should be called whenever the layout of the grid view changed. internally, it will recalculate all cell logical positions. TODO: @param ShowCell: nil or a gridCell. It will automaticly scroll for the best show of the cell element.

syntax

function GridView:Update()

GridView:RefreshUI

refresh the UI

syntax

function GridView:RefreshUI()

GridView.DefaultCellDrag

test callback on cell drag and drop

syntax

function GridView.DefaultCellDrag(fromgridview, draggridcell, fromRow, fromColumn, toRow, toColumn)

parameters

fromgridview
draggridcell
fromRow
fromColumn
toRow
toColumn

GridView:AppendCell

append the GridCell object into the grid view

param cell : GridCell object
param mode : where to place the newly added cell when cell on target position already exists according to Numpad, if the cell inserted at 5, and 5 already has a cell, then try to insert cell according to the sequence:

"Up"
8 1 4 7

"Down"
2 9 6 3

"Left"
4 9 8 7

"Right"
6 1 2 3 if the sequence hit the topleft or rightbottom corner of a gridview, drop cell.

syntax

function GridView:AppendCell(cell, mode)

parameters

cell	GridCell object
mode

GridView:InsertCell

insert the GridCell object into the grid view

param cell : GridCell object
param mode : where to place the newly added cell when cell on target position already exists according to Numpad, if the cell inserted at 5, and 5 already has a cell, then try to insert cell according to the sequence:

"Up"
8 1 4 7

"Down"
2 9 6 3

"Left"
4 9 8 7

"Right"
6 1 2 3 if the sequence hit the topleft or rightbottom corner of a gridview, drop cell.
param bAppend : whether to append the cell into the target position

syntax

function GridView:InsertCell(cell, mode, bAppend)

parameters

cell	GridCell object
mode
bAppend	whether to append the cell into the target position

GridView:PrintMe

DEBUG PURPOSE: print the cell data into a file

syntax

function GridView:PrintMe(filename)

parameters

filename

GridView:GetCellByRowAndColumn

get a GridCell object from the grid view by row and column index

param row : GridCell row index
param column : GridCell column index

syntax

function GridView:GetCellByRowAndColumn(row, column)

parameters

row	GridCell row index
column

GridView:RemoveCellByRowAndColumn

remove a GridCell object from the grid view by row and column index

param row : GridCell row index
param column : GridCell column index

syntax

function GridView:RemoveCellByRowAndColumn(row, column)

parameters

row	GridCell row index
column

GridView:GetCellByName

get the first occurance of gridcell object whose name is name

syntax

function GridView:GetCellByName(name)

parameters

name

GridView:RemoveCellByName

remove all occurance of grid cell whose name is name

syntax

function GridView:RemoveCellByName(name)

parameters

name

GridView:GetCellByText

get the first occurance of gridcell object whose text is text

syntax

function GridView:GetCellByText(text)

parameters

text

GridView:GetCellByPoint

TODO: implement this funciton in the grid view

-- get the best matched cell that contains the logical point x, y

syntax

function GridView:GetCellByPoint(x, y)

parameters

x
y

GridView:GetCellByIndex

get the gridcell object according to the index NOTE: index is defined according to the sequence: 1 2 3 4 5 6 7 8 9 10 11 12 13 14

1. 16 ... NOTE: also the index sequence is calculated by rows and columns of the grid view object, NOT the logical client area width and height

syntax

function GridView:GetCellByIndex(index)

parameters

index

GridView:IndexToRowAndColumn

index and row+column transform NOTE: index is defined according to the sequence: 1 2 3 4 5 6 7 8 9 10 11 12 13 14

1. 16 ... NOTE: also the index sequence is calculated by rows and columns of the grid view object, NOT the logical client area width and height

syntax

function GridView:IndexToRowAndColumn(index)

parameters

index

GridView:GetCellByCursor

-- get the best matched cell that on the current cursor position if position is beyond the gridview client area, return nil

syntax

function GridView:GetCellByCursor()

GridView:GetCellCount

Get cell count

syntax

function GridView:GetCellCount()

GridView:ClearAllCells

clear all gridcells

syntax

function GridView:ClearAllCells()

GridView:UpdateLogicalPosition

update the logical positions of grid cells

syntax

function GridView:UpdateLogicalPosition(row, column)

parameters

row
column

Topic revision: r1 - 2008-02-29 - LiXizhi