pbsw-code.net : pbsw-ListBox

pbsw-ListBox

A ListBox subclass (and support classes) that handle a hierarchical list, with associated tree-based structure.

The tree-node class (pbsw_LBNode) can be subclassed to allow the nodes to hold whatever data you want.

The features include live drag-reordering of items.

Note: the current design allows for only single column listboxes without a column heading, and does not support dragging items out of the list.

Requires: REALbasic 5.5




Class: pbsw_ListBox Superclass: Listbox Interfaces: None
This is the main class - a ListBox subclass.

Many methods are available for inserting items directly into the structure,
including positions relative to the visually selected item or the the last item inserted.

There is a special method: Rebuild() that is needed if you manipulate the tree nodes directly.

If you use the ListBox methods to add and remove nodes to the list, and to add nodes as children
of other nodes, you do not need to call Rebuild(). Using the ListBox methods and avoiding Rebuild()
as much as possible will give you the best performance, especially in large lists.


Methods
AddChildToLastAdded(theNode as pbsw_LBNode) [Public]
Adds theNode as a child of the last item added
(will only work if the last added node is a container)
AddChildToLastAdded(theName as string, isContainer as boolean = false) [Public]
Creates a new node named "theName" and adds it to the last added node
If isContainer is true, the new node will be a container node.
(will only work if the last added node is a container)
AddChildToNode(chosenNode as pbsw_LBNode, theNode as pbsw_LBNode) [Public]
Adds theNode as a child node of chosenNode
(will only work if chosenNode is a container)
AddChildToNode(chosenNode as pbsw_LBNode, theName as string, isContainer as boolean = false) [Public]
Creates a new node named "theName" and adds it as a child of chosenNode
If isContainer is true, the new node will be a container node.
(will only work if chosenNode is a container)
AddChildToSelection(theNode as pbsw_LBNode) [Public]
Adds theNode as a child of the selected node
(will only work if the selected node is a container)
AddChildToSelection(theName as string, isContainer as boolean = false) [Public]
Creates a new node named "theName" and adds it to the selected node
If isContainer is true, the new node will be a container node.
(will only work if the selected node is a container)
AddSampleData() [Public]
Adds a set of sample (demonstration) data to the list
Append(theNode as pbsw_LBNode) [Public]
Appends theNode to the end of the list
Append(theName as string, isContainer as boolean = false) [Public]
Creates a new node named "theName" and appends it to the end of the list
If isContainer is true, the new node will be a container node.
CollapseAll() [Public]
Collapses all rows in the list
ExpandAll() [Public]
Expands all rows in the list
GetDragReorderOption() as boolean [Public]
Returns true if the list supports drag reordering of items
GetLastAddedNode() as pbsw_LBNode [Public]
Returns the last node added to the list
GetNodeAtRow(theRow as integer) as pbsw_LBNode [Public]
Returns the node currently at row number "theRow"
(only top level rows, and rows inside expanded rows are counted in row number)
(row 0 is the first visible row)
(if you modify any nodes directly, you need to call Rebuild() to update the listbox)
GetNodeRow(theNode as pbsw_LBNode) as integer [Public]
Returns the row number of theNode
(only top level rows, and rows inside expanded rows are counted in row number)
(row 0 is the first visible row)
GetRoot() as pbsw_LBNode [Public]
returns the node that is the root of the tree structure represented by the listbox
(if you modify any nodes directly, you need to call Rebuild() to update the listbox)
GetSelectedNode() as pbsw_LBNode [Public]
Returns the currently selected node
(if you modify any nodes directly, you need to call Rebuild() to update the listbox)
Insert(row as integer, theNode as pbsw_LBNode, theDepth as integer = 0) [Public]
Inserts theNode into the list above row numbered "row".
(only top level rows, and rows inside expanded rows are counted in row number)
(row 0 is the first visible row)
(the use of theDepth is not quite worked out completely yet)
Insert(row as integer, theName as string, theDepth as integer = 0, isContainer as boolean = false) [Public]
Creates a new node named "theName" and inserts it above row numbered "row"
If isContainer is true, the new node will be a container node.
(only top level rows, and rows inside expanded rows are counted in row number)
(row 0 is the first visible row)
(the use of theDepth is not quite worked out completely yet)
InsertAfter(chosenNode as pbsw_LBNode, theNode as pbsw_LBNode) [Public]
Inserts theNode after chosenNode
InsertAfter(chosenNode as pbsw_LBNode, theName as string, isContainer as boolean = false) [Public]
Creates a new node named "theName" and inserts it after chosenNode
If isContainer is true, the new node will be a container node.
InsertAfterLastAdded(theNode as pbsw_LBNode) [Public]
Inserts theNode after the last added node
InsertAfterLastAdded(theName as string, isContainer as boolean = false) [Public]
Creates a new node named "theName" and inserts it after the last added node
If isContainer is true, the new node will be a container node.
InsertAfterSelection(theNode as pbsw_LBNode) [Public]
Inserts theNode after the selected node
InsertAfterSelection(theName as string, isContainer as boolean = false) [Public]
Creates a new node named "theName" and inserts it after the selected node
If isContainer is true, the new node will be a container node.
InsertBefore(chosenNode as pbsw_LBNode, theNode as pbsw_LBNode) [Public]
Inserts theNode before chosenNode
InsertBefore(chosenNode as pbsw_LBNode, theName as string, isContainer as boolean = false) [Public]
Creates a new node named "theName" and inserts it before chosenNode
If isContainer is true, the new node will be a container node.
InsertBeforeLastAdded(theNode as pbsw_LBNode) [Public]
Inserts theNode before the last added node
InsertBeforeLastAdded(theName as string, isContainer as boolean = false) [Public]
Creates a new node named "theName" and inserts it before the last added node
If isContainer is true, the new node will be a container node.
InsertBeforeSelection(theNode as pbsw_LBNode) [Public]
Inserts theNode before the selected node
InsertBeforeSelection(theName as string, isContainer as boolean = false) [Public]
Creates a new node named "theName" and inserts it before the selected node
If isContainer is true, the new node will be a container node.
ParentOf(theNode as pbsw_LBNode) as pbsw_LBNode [Public]
Returns the parent node of theNode
(if you modify any nodes directly, you need to call Rebuild() to update the listbox)
Rebuild(doRefresh as boolean = true) [Public]
Rebuilds the ListBox from the tree structure (starting at the root node)
If doRefresh is true, the ListBox will be refreshed
(if you modify any nodes directly, you need to call Rebuild() to update the listbox)
RemoveAllNodes() [Public]
Removes all the nodes/rows
RemoveLastAddedNode() [Public]
Removes the last added node
RemoveSelected() [Public]
Removes the selected node from the list
SelectNode(theNode as pbsw_LBNode) [Public]
Select theNode (highlight it visually in the list)
SetDragReorderOption(doDragReorder as boolean) [Public]
If doDragReorder is true, the drag reordering feature is turned on, otherwise it is turned off.
(You can also set the EnableDragReorder property in the IDE for your list)
(This function is a means to change that option at runtime)
SetRoot(theNode as pbsw_LBNode) [Public]
Sets theNode as the root (starting) node for the tree structure of the list, and rebuilds the list
(if you modify any nodes directly, you need to call Rebuild() to update the listbox)

New Events
DebugMsg(theText as string)
This event is used for noting debugging information - it will most likely go away before version 1.0
ErrMsg(theError as integer)
This event is fired when certain (non-fatal) errors occur.
(See pbsw_ListBox_Errors module for error numbers.


Class: pbsw_LBNode Superclass: None Interfaces: None
This class is the basis for the tree structure holding the list data.

The structure is made up of "nodes", starting with a root node.

Nodes can be designated as containers, which means that they hold other nodes (children).

pbsw_LBNode can be subclassed to hold whatever other data you may need.


Methods
AppendChild(theNode as pbsw_LBNode) [Public]
Adds theNode to the list of children
(this only works if this node is a container)
Constructor(theName as string, isContainer as boolean = false) [Public]
theName is the name of the node
if isContainer is true, the node will be a container node
ContainsNode(theNode as pbsw_LBNode) as boolean [Public]
Returns true if theNode is a child of this node
CountChildren() as integer [Public]
Returns the number of children
GetChild(index as integer) as pbsw_LBNode [Public]
Returns the child at position "index"
(the first child is position 1)
GetName() as string [Public]
Returns the name of the node
GetNextChild(theNode as pbsw_LBNode) as pbsw_LBNode [Public]
Returns the child node after theNode
InsertChildAfter(existingNode as pbsw_LBNode, insertedNode as pbsw_LBNode) [Public]
Inserts insertedNode after existingNode
(this only works if this node is a container)
InsertChildBefore(existingNode as pbsw_LBNode, insertedNode as pbsw_LBNode) [Public]
Inserts insertedNode before existingNode
(this only works if this node is a container)
InsertFirstChild(theNode as pbsw_LBNode) [Public]
Inserts theNode as the first child node
(this only works if this node is a container)
IsContainer() as boolean [Public]
Returns true if this node is a container node
IsExpanded() as boolean [Public]
Returns true if this node is expanded (visually)
ParentOf(theNode as pbsw_LBNode) as pbsw_LBNode [Public]
Returns the parent node of theNode if it can be found in the tree below this node
RemoveNode(index as integer) [Public]
Removes the node at position "index"
RemoveNode(theNode as pbsw_LBNode) [Public]
Removes theNode if it can be found in the tree structure below this node
SetContainer(canContain as boolean) [Public]
If canContain is true, then this node becomes a container, otherwise, it stops being a container, and all children are removed
SetExpanded(isExpanded as boolean) [Public]
Sets the expanded state of this node to isExpanded


Class: pbsw_LBNodeArray Superclass: None Interfaces: None
This class is for storing and manipulating a list of nodes.
It is currently not used in any way by pbsw_ListBox.

Note: this is a 1 based array (the first node is number 1)


Methods
Append(theNode as pbsw_LBNode) [Public]
Add theNode to the end of the array
Clear() [Public]
Remove all nodes from the array
Contains(theNode as pbsw_LBNode) as boolean [Public]
Returns true if the array contains theNode
ContainsParentOf(theNode as pbsw_LBNode) as boolean [Public]
Returns true if the array contains the parent node of theNode
Count() as integer [Public]
Returns the number of nodes in the array
Insert(index as integer, theNode as pbsw_LBNode) [Public]
Inserts theNode into the position "index" of the array
(position 1 is the first node in the array)
Item(index as integer) as pbsw_LBNode [Public]
Returns the node at position "index" in the array
(position 1 is the first node in the array)
Pop() as pbsw_LBNode [Public]
Returns the last added node, and removes it from the array
Remove(index as integer) [Public]
Removes the node at position "index" in the array
(position 1 is the first node in the array)
Remove(theNode as pbsw_LBNode) [Public]
Removes theNode from the array
SetExpandedAll(isExpanded as boolean) [Public]
Sets the expanded state of all nodes in the array to isExpanded


Class: pbsw_LBDragTimer Superclass: Timer Interfaces: None
This class is used to handle certain conditions while drag-reordering rows, and to indicate when the drag ends.
You should not deal with it directly.




Module: pbsw_ListBox_Errors
These are error numbers for the pbsw_ListBox's ErrMsg event.
You may handle them in any way you see fit in your instances.


Constants
NameTypeValueScopeDescription
CannotAddToNonContainer Integer -2 Public An attempt was made to add a child to a non-container node
DuplicateNode Integer -1 Public An attempt was made to add a node that is already in the tree


pbsw-code.net : pbsw-ListBox