tsc_UiTreeItem

The class represents one line item in a tsc_UiTree.

A line may be a top-level row, or any line within a subtree of a top-level row.  All items are organised in a tree-like structure, with a tsc_UiTree object being the root.  A tsc_UiTreeItem cannot exist outside of a tsc_UiTree, and once an item is added to a tree it remains there until explicitly removed or the whole tree is destroyed.  

A subtree is created simply by adding child items to a tsc_UiTreeItem.  Any item with one or more children will be displayed with an expand icon [+] to the left of the text, which can be clicked to expand that level of the subtree.  All subtrees are initially collapsed.

When a subtree is displayed, it is indented from its parent.  The size of the indent is equal to the pixel height of a row.  Indenting moves all of the cells in the line towards the right.  The PushColumns option allows this to be changed for any line, so that only the left edge of the leftmost cell is moved to the right.

The tsc_UiTreeItems that represent nodes in the tree may be stored by the plugin (perhaps so they can be subsequently updated), or they may be discarded; either way the item will remain in the tree.  Any tsc_UiTreeItem may be retrieved again by navigating through the tree.

tsc_UiTreeItem objects may have a Tag. The tag is a pointer to a tsc_Object, which allows any object - provided it has been subclassed from tsc_Object - to be stored with the item. This is useful for connecting an item back to its source data.

The items at the top level are always displayed in the control. These items are known as rows within the control.  The top level items may be indexed directly by row number by calling tsc_UiTree::GetRow(rowNumber).

Note: This control is optimised to handle a large number of rows at the top level rather than within subtrees.  Placing extreme numbers of items within a subtree may degrade performance.  The meaning of 'extreme' is somewhat dependent on the hardware platform in use. A hundred sub-tree items or less should perform well on all current platforms. On the other hand, tens of thousands of rows should perform without a problem.

Public Methods

tsc_UiTreeItem ()
Constructs an empty item. Such an item is not useful except for assigning to.

tsc_UiTreeItem (const tsc_UiTreeItem &)
Copy constructor makes a reference to the same item.

tsc_UiTreeItem & operator= (const tsc_UiTreeItem &from)
Makes a reference to the 'from' item.

bool operator== (const tsc_UiTreeItem& equalTo) const;
Equality of two tsc_UiTreeItem objects returns true only if the two items refer to the same line in the control.  That is, if they are the same item.

bool operator!= (const tsc_UiTreeItem& notEqualTo) const;
Inequality returns the opposite of == (see above).

bool  Exists () const
True if this item 'exists'. Navigation functions that fail will return an 'empty' item which will return false from Exists() .  This allows use of a statement such as:

if (item.NextSibling().Exists()) ...

int Depth () const
Returns the depth within the whole tree where this item exists.  Rows at the top level will return zero, and this increases by one for each nested subtree.

tsc_UiTree Root () const
Returns the tree root object that this item belongs to.

tsc_UiTreeItem Parent () const
Returns this item's parent, or NULL if the item is at the top level - in which case the parent of the item is the tree object.

tsc_UiTreeItem NextSibling () const
Returns the next sibling item, which is the next item at the same level. If the item is the last at the same depth within the subtree then NextSibling will return an item whose Exists() is false.

tsc_UiTreeItem PrevSibling () const
Returns the previous sibling item, which is the previous item at the same level.  If the item is the first then NextSibling will return an item whose  Exists()  is false.

bool HasChild () const
This item has at least one child (subtree) node.

tsc_UiTreeItem Child () const
Returns the first child item, which is the first line in the item's  subtree.

tsc_UiTreeItem Add ()
Adds a new item (sibling) after the last at this item's level.

tsc_UiTreeItem InsertAfter ()
Inserts a new sibling (same-level item) before this one.

tsc_UiTreeItem InsertBefore ()
Inserts a new sibling (same-level item) after this one.

tsc_UiTreeItem AddChild ()
Adds a new child after the last child of the item.

void Remove ()
Removes this item and, recursively, any children it may own.

void Texts (const char* col0, ...  , const char* coln )
Sets the text of up to five columns at once.  Overloads of the function exist for any number of columns up to five.  This is simply a shortcut for item.GetCell(n).Text()
If the cells do not exist, they are created first.

virtual  tsc_UiCell GetCell (int columnNumber)
Returns an instance of the attributes for the cell at the given column in the item's line.
If no cell exists at that position, a new cell is created with default attributes.
The leftmost cell is number zero. This is the only way to create or access a cell. For example:

item.AddChild().GetCell(0).Text ("New cell text");

void Font ( tsc_Font  font)
Sets the Font for this line.  If not specified, then the font for the item's parent is used, or for a top-level row the control's default font is used.  All cells in a line will use the same font. The font size does not affect the line spacing.

tsc_Font Font ()
Get the line's Font.

void PushColumns (bool push)
When a subtree is displayed, its leftmost column is indented from its parent.  This means that the leftmost column will become narrower.  Setting this property by calling  PushColumns(true) means all cells will be indented and the leftmost cell will remain the same width, and cells will no longer line up with the control's columns.

bool PushColumns ()
Returns the current PushColumns setting for the item.

void IndentMore (int indents)
Adds further indents to the line.

int IndentMore ()
Returns the additional indent of this item.

void Tag (tsc_Object* tag, bool autoDelete)
Stores a user-defined pointer with the item. The pointer may be NULL or any tsc_Object subclass, and may be used to connect a tree item back to its data source.

The autoDelete parameter controls disposal of the object.  If true , then the object is deleted when the item is destroyed or an existing Tag is replaced; if false the caller must delete the object.

tsc_Object* Tag ()
Gets the tag pointer from the item.

virtual  tsc_String ToString () const
Returns a formatted representation of this item only. Each indent is represented by one leading space character, and the text content of each cell is output separated from neighbouring cells by a tab character.

tsc_String ToString (int maxDepth=-1) const
Returns a formatted representation of this item and its children recursively.  The maxDepth parameter controls how deeply the subtree recursion goes - zero means just the item, 1 means the item plus the immediate subtree, and so on.  -1 outputs all items in the subtree.

The returned string contains the items separated by newlines (\r\n) and each line has a leading space for each indent and tab characters between the text of the cells.