tsc_ListControl

This control allows the display of and selection from a list of strings.

A list box control which shows a list of strings, one row per string, any one of which may be selected. It also supports column view which can be specified by calling AddColumn; individual row strings specify column separation with tab characters.

The initial state of the control has no columns, and behaves as though there is one column across the entire width. Columns may be added by calling AddColumn() once per column. Break each row's text into columns by inserting tab characters (\t) into the row strings.

Sizing issues

Because of its size, which is typically much larger than most types of field, a tsc_ListControl may not cooperate well with other controls and fields on a form.  In many situations the list control can be simply added to a form as the only field and it will expand to the full size of the form.

When placed with other controls on an auto-layout form, the list control will occupy the remainder of the form and all controls must therefore precede it.  To alter this behaviour use a custom layout and specify a size for the list control.  Also on auto-layout forms, it is not possible to add fields after the list control because they will be displayed on the second page, and the resulting page up/down button will overlap the bottom right corner of the list control.

For any situation where the list control does not behave as required, use a custom layout for the form and size the list appropriately.

Public methods

Columns

Columns may be created by calling an AddColumn method.  If title text is supplied then column headings will be drawn, and the columns will be resizable by dragging the divider between column heading buttons. There is a maximum of ten columns allowed.

Column widths may be specified as a percentage of the total available width, or given as zero.  When zero-width columns exist, the list control will compute the width remaining after assigning all non-zero-width columns, and split it evenly amongst the zero-width columns such that all columns fit exactly into the width of the control.  This is only done once, when the control is first created.

The total of the column widths may exceed 100 percent; if this occurs a horizontal scrollbar will be added to allow the user to see all columns.  A minimum column size of about 10 pixels exists; any column less than the minimum (including zero-width columns which are computed to be less than the minimum) will be given the minimum width.

Events

The list control raises events a little differently than most other fields and controls.

bool OnClick (tsc_Control& control);

The OnClick event is raised when the user clicks an item in the list, or presses the space key while an item is selected.  Tap-and-hold on an item does not raise OnClick, it simply selects the item.  This event is generated from the space or enter key, or a mouse-up message, and will follow an OnSelectionChange event.

bool OnSelectionChange (tsc_Control& control);

This event is raised when the current selection is changed to another item in the list, regardless of what caused the change (user action, program control, etc).  This event is generated by an arrow key or the mouse-down message, and will therefore precede the OnClick event.

bool OnFieldCompleted (tsc_Control& control);

This event is never raised, since tsc_ListControl is a control, not a field.