tsc_UiTree

This class is used to create a Tree-like structure that can be used for displaying information in UI elements such as tsc_TreeListControl and the Job Review window.

Other relevant classes

• tsc_Font

• tsc_Color

• tsc_Image

• tsc_TreeListControl

Terminology and trees

A tree, as defined by tsc_UiTree, consists of one or more top-level rows, each of which may be alone or contain one or more sub-trees.  A sub-tree may itself contain zero or more sub-trees, at an ever increasing depth.  Rows are numbered and can be addressed directly; sub-trees are not. This tree concept is very similar to nested bullet points, like this:

• This is top-level row number 0.  It is a lone row with no subtrees, and has a depth of zero.

• This is top-level row number 1.  It contains subtrees (see below), and also has a depth of zero.

  • This is a subtree of row 1.  It has a depth of 1.

  • This is also a subtree of row 1 with a depth of 1.  It contains a subtree.

    • This is a second-level subtree in row 1.  It has a depth of 2.

• This is top-level row number 2.  Note how sub-trees are not counted in the row numbering.

Because we've used the term row to designate only top-level rows, the subtree items are called lines. Internally the tsc_UiTree makes extensive use of line numbers when drawing items and processing events, however line numbers will be rarely (if ever) seen in the interface.  Every line, including the top-level rows, is represented in the plugin as a tsc_UiTreeItem.  They are referred to as items throughout this documentation.

The tsc_UiTree class as described later in this page is a container for items (tsc_UiTreeItem).  It contains methods for adding and retrieving top-level row items.  It does not provide direct access to items in subtrees; one must obtain these by navigating down from the top-level tsc_UiTreeItem objects.

The tree idea moves to a family tree concept when the relationship between items is considered.  Items in the same sub-tree and at the same depth are known as siblings.  All top-level row items are siblings of each other.   An item which is one deeper is a child, and all immediate children are siblings of one another.  The item at one depth less is, of course, the parent. There exist methods in tsc_UiTreeItem which allow navigation up and down between siblings, and in and out from parents to children and vice versa. The parent of a top-level row item is the tsc_UiTree, but for simplicity's sake a non-existing item is returned.

Public constructors for tsc_UiTree

tsc_UiTree()
Constructs a new tree.   Rows, items, and subtrees may then be added to create a complete structure to be displayed.  Only one tsc_UiTree object may be present in the structure.

tsc_UiTree (const tsc_UiTree& from)
Copy constructor makes a reference to the same tree. 

Public methods

tsc_UiTree& operator= (const tsc_UiTree& from)
Makes a reference to the 'from' tree. 

int RowCount () const
The count of top-level rows currently in the tree. 

tsc_UiTreeItem FirstRow () const
Returns the first row in the tree. 

tsc_UiTreeItem GetRow (int rowNumber) const
Returns the top-level item displayed in a given row number. 

tsc_UiTreeItem AddRow ()
Adds a new top-level row. The row may start a subtree. 

Relationship to the displayed result

The image below shows the various elements of a tsc_UiTree as it appears in a tsc_TreeListControl.  In this case, it is a Point Manager window which uses the same control. Blue text has been manually added.

Note that the 3rd and 4th lines (Northing and Easting) have values that extend beyond their columns; to allow this the individual cells have been given an increased width. These cells also have left-aligned text.

Also note that the three top-level rows (P001, P002-A, and TRIMBLEATJ) have a small icon.  This can be achieved by adding an image to the cell and specifying TextFloat(true) to prevent the text overwriting the image.