tsc_ControlListBase

Overview

This class is the base for lists of controls/fields (tsc_Control and subclasses) that are present on a tsc_Form.

When Show or ShowDialog is first called on a form, or an application's main window is created, the window is created and all the controls that are present in the controls list will be drawn.

Softkey controls in the list are processed separately and added to the softkey area at the bottom of the window.

It is preferable to populate and/or modify the list before the window is shown since this is a much cheaper operation.  It is also possible to modify the list after the window has been shown, but this may cause a partial or full rebuild of the form using the modified control list, with possibly a slight flicker on the screen.  Multiple consecutive changes to the list will be incorporated into a single rebuild.

When the list is destroyed (typically as a result of destroying the parent form) all items in the list will be removed and deleted. Any control or field that is not in the list will have to be programmatically deleted by the caller.

Public methods

Returns true if the control is present in the list (by pointer compare).

bool Contains (tsc_Control* control);
Returns true if the control is present in the list (by x_Code compare).  X_NULL always returns false.

bool ContainsIdentifier (x_Code identifier);
Removes a control from the list.  The memory for the control must be deallocated by the caller.  No error occurs if the control is not present.

[Previous to version 4.00, it was incorrectly stated that the memory was automatically deleted].

void Remove (tsc_Control* control);
To remove all controls from the list.  This will not delete any items so this must be done by the caller, or the DeleteAll function may be used to remove and delete the items.

void RemoveAll ();
Removes all controls from the list without deleting them.  Do not call this function on an open window.  

void DeleteAll ();
Removes all items from the list and deletes their memory. DeleteAll is called automatically during window destruction, and this will deallocate the memory for all controls in the list.

int Count();
Returns the count of controls present in the list.

Protected methods

Subclasses (see below for a list) expose overrides of the Add method as appropriate for the window type on which they are used.

tsc_Control* Add (class tsc_Control* control);
Adds a control to the end of the list.  The control must have been allocated on the heap using new.  Destruction of the list will deallocate the memory for all controls present in the list at the time of destruction.  See the individual subclasses for their treatment of the Add method.

All controls in the list must have unique identifiers; if a control is added with an identifying x-code the same as another control in the list, an exception will occur.  See tsc_ControlList for ways around this problem.  If an identical control is added twice (same pointer) then no action occurs.

Note that the control pointer is returned unchanged to allow this sort of construct:

tsc_Control* mysk = Controls.Add (new tsc_SoftkeyControl (X_Measure));

Subclasses

• tsc_FormControlList

• tsc_MainMenuControlList (Deprecated)