tsc_DropDownEnumListField

This field type is designed for presenting enumeration types to the user in the form of a drop-down list.

Often, some data type is described internally by an enumeration, such as a list of colors, where some selection is to be made by the user. Such a list can be presented using a tsc_DropDownXCodeListField, however this requires the list to contain exactly the same items as the enumeration in the correct order, such that the selected index value exactly matches the enumeration values.

The tsc_DropDownEnumListField allows an enumeration to be mapped to an array of strings, and then any subset of the items in the enumeration may be used to populate the drop-down list, in any sequence. Do not allow the drop down list to be displayed with empty arrays or with listItems that are not present in the fullEnumeration array.

For a drop-down list populated with simple strings, use tsc_DropDownStringListField instead.

For a drop-down list of translated strings which does not represent an enumeration, use tsc_DropDownXCodeListField instead.

Control sizing

Drop-down lists may contain any reasonable number of items.

The control in its closed-up state occupies a single line on a form and if no string within the list is too long, then two may fit side by side. The width of the control is determined by the longest string within it.

Horizontally, the list is sized to the longest string item, up to the width of the form. When using a custom layout, the SetCustomDimensions() method on the control may be used to set the list to a fixed width.

When the list is opened by the user, it may occupy as much vertical space as is available on the form. If the list contains more items than will fit, a vertical scroll bar is added.

The image to the right shows a variety of drop-down lists as displayed by the drop-down form in the HowTo sample (see the Samples subdirectory in the SDK distribution).

Public methods

Events

An OnFieldCompleted event is generated when the user selects another item. Override this method to receive a notification of a change to the selected item in a drop-down list.

virtual bool tsc_Form::OnFieldCompleted (tsc_Control& control);

This event is raised when the user changes the selected item. The event doesn't occur until the user has committed the change by pressing Enter while focus is within the drop-down list, or clicks away from the control. Selection changes performed programmatically do not raise this event.

Example

Also see the HowTo code sample in the SDK samples directory.

This example presupposes that a translation database (XML file) has been populated with translations for the five colours used in the example, and that they are called PX_Pink, PX_White, PX_Red, PX_Blue, and PX_Black.

// A enumeration of all colours possible in our small example world. enum Colours { Pink, White, Red, Blue, Black }; // A list of x-codes to match the enumeration, providing translated strings for the colour names. tsc_XCodeList allColours = tsc_XCodeList (PX_Pink, PX_White, PX_Red, PX_Blue, PX_Black); // A field to present the user with the choice of red, white, or blue, initially set to white. tsc_DropDownEnumListField *cfield = new tsc_DropDownEnumListField (X_Color, tsc_XCodeList (PX_Red, PX_White, PX_Blue), allColours, White); // adding the field to the form this->Controls.Add(cfield); // other form details omitted ... // Handling a selection change. virtual bool OnFieldCompleted (tsc_Control& control) { if (control.GetIdentifier() == X_Color) { Colours selColour = (Colours) cfield->SelectedEnum(); ... tsc_MessageBox::Show (PX_Selected, tsc_String::Format("Colour #%d (%s)", (int)selColour, cfield->SelectedXCode())); } }

Page updated

Report abuse