tsc_TreeListControl

A TreeList control shows a tree-like arrangement of rows with expandable sub-trees.  In its initial state, the control has no columns, and behaves as though there is a single column across the entire width. Up to ten columns may be added to the control. Columns may have header buttons with draggable dividers so the user can customize the column widths.

The information to be displayed is supplied as a tsc_UiTree containing any number of tsc_UiTreeItem objects. Changing objects within the tree will update the control automatically.  See the tsc_UiTree documentation for more detailed information about constructing a tree for display by the tsc_TreeListControl.

Public Members for tsc_TreeListControl

tsc_TreeListControl (x_Code identifier, tsc_UiTree& tree, int initialSelection);

Constructs a tree list control, given a control identifier which may also serve as a prompt, a tsc_UiTree instance containing the data to be displayed, and the row number of the initially selected item.

void AddColumn (int widthPercent, const char* title = NULL);

Adds the first column, or a column to the right of the previously added column.  The width is given as a percentage of the entire width of the control, or as zero to automatically size the column.  After all non-zero widths have been allocated, the remaining width is shared equally amongst the zero-width columns.

If a title is supplied, it is drawn in the column button, or if NULL is supplied for all buttons then no buttons are shown. Columns should be added before the control is created.

void AddColumn (int widthPercent, x_Code title);

Adds the first column, or a column to the right of the previously added column.  The width is given as a percentage of the entire width of the control, or as zero to automatically size the column.  After all non-zero widths have been allocated, the remaining width is shared equally amongst the zero-width columns.

If a title is supplied, it is translated and drawn in the column button, or if X_NULL is supplied for all buttons then no buttons are shown. Columns should be added before the control is created.

void Font (tsc_Font& font);

Sets the default font for header buttons and text in rows. Any individual row may override the font.

void ShowPrompt ();

Call this method to display a field prompt above the control.  The text is obtained from the control identifier given in the constructor.

int RowCount () const;

Returns the number of top-level rows currently in the list.  The count does not include any lines contained in subtrees, whether expanded or not.

int SelectedIndex () const;

The row currently selected by the user.  This is the index of the top-level row, starting at zero.  If the row contains a subtree, then the selection may be any line within the subtree.

void SelectedIndex (int newValue);

Selects the specified top-level row.  This method will not select a line within a subtree.

void SelectedItem (tsc_UiTreeItem item);

Selects the row that contains the supplied item.

tsc_UiTreeItem SelectedItem ();

Get the item for the row currently selected by the user.

tsc_UiTreeEventArgs GetEventArgs();

Gets the event details for event being currently handled. This information is only valid when called from event handlers such as OnClick, OnSelectionChanged, and OnFieldCompleted. It gives full details of the event at the time it was raised.

tsc_String GetLayout ();

Returns a character representation of the control's column widths, which may have been adjusted by the user. This is useful for persisting column widths between instances, but is only useful if the control contains visible column headers for the user to adjust.

A good time to call this function is when the control is about to be destroyed (in OnFormClosing() for example) and save the returned string for later use by SetLayout().

The tsc_AppSettings class contains methods for persisting data such as this.

void SetLayout (const char* layout);

Sets the layout of the columns as it was when GetLayout() was used to obtain the layout string. This method should be called after the columns have been added, before the control is created. This could be either during form construction or in the tsc_Form::OnLoad() event handler.

It can be called at other times but this may surprise the user.

Column widths from the layout string are applied once when the control is created, and so will override widths set for columns previously added. Note that cell widths which are

explicitly set in tsc_UiCell objects are not affected by SetLayout. If an empty or invalid string is supplied, column widths remain unchanged.

The width of all columns are contained in the string as absolute pixel values, so any auto-sized (zero width) colums will become fixed.  This is of no consequence unless the overall size of the control has been changed.