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
Name	Type	Value	Scope	Description
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

This page created by RB-ADoc by Park Bench Software