tsc_Control and field types

A Field and a control have different behaviours, as follows:

• • A field is a collection of controls, such as the tsc_StringField which contains an edit control, a context menu button, and a prompt being a description of what the field represents.

  • Some field types (eg, those with an edit control) have a small button to the right which displays a context menu.

  • A field is self-sizing and is intended to cooperate with the form's automatic flow layout system.

  • Fields generally only raise one event, OnFieldCompleted, when the user exits the field.  At this point the Value property is available; controls do not have the Value property.

  • Fields pay attention to current unit settings where applicable, and convert to the internal SI units automatically.  Furthermore, the user may enter the units into a field (eg 3.21m may be entered even when the current units are set to feet).

  • Controls usually need to be explicitly sized and consist of just a single control.

  • Controls raise a variety of different events, such as OnClick and OnSelectionChange, but not OnFieldCompleted.

  • Some larger controls may disobey the rules for automatic form layout, typically because of their size.

The available controls and fields can be found in the sub-pages to this page.

Controls and fields are generally used as they are, but occasionally they are further subclassed by the plugin developer to extend their existing functionality.  Either way, a control must be allocated on the heap with the 'new' operator.  If a control is added to a form, and the form is subsequently closed and deallocated (using delete), the form's destructor will also delete the control.  Any control not added to the form at the time it is closed needs to be explicitly deleted by the plugin code.

Fields and controls generally have a implicit maximum capacity of about 1000 characters.

Fields and unit settings

Most Survey Core fields respond to the application-wide units and display settings available in the Job Properties, and use this information to provide properly formatted and parsed text including precision, units and in some cases automatic range checking.  Typically these settings are not customisable on a field by field basis, and this provides consistency across the entire application.

Common tsc_Control functions

The following methods, common to all controls and fields, are included in the tsc_Control class.  These methods apply to all fields and controls, except where noted.

Read only

A field can be marked as read-only which displays the field without allowing editing, but note that some fields change appearance - for instance checkboxes become static text saying "Yes" or "No", and drop-down lists display just the selected item in a static control.

    bool IsReadOnly () const;
    void SetReadOnly (bool readOnly);

Position

A row and column position can be given for the top left corner of a control for when using a custom grid layout on a form.

    void SetCustomLayoutPosition (tsc_ColRow& position);

A control or field may be placed on subsequent pages of a form by adding a tsc_PageBreakControl before adding the control.  A row number beyond the end of the page will cause the control to overflow to the next page, however it may overlap other fields on that page.

Further positioning options are available; see tsc Form - Custom layout box model

Sizing

A width and height for the control can be specified when using a custom grid layout on the form.  By default the dimensions are given as a percentage of the window client area size; using the third parameter allows the size to instead be interpreted as a percentage of the cell size, or of the grid size (the area inside the margins).  A dimension may be given as tsc_Control::NoLayoutPosition, which applies a standard or automatic sizing to that dimension.

Note: Using zero for the width or height is not supported, and some controls will not display correctly when a very small width or a non-standard height is given.

    void SetCustomDimensions (int width, int height, tsc_DimensionType dimType = tsc_DimPercentOfWindow);

    enum tsc_DimensionType
    {
        tsc_DimPercentOfWindow = 0,
        tsc_DimPercentOfGrid,
        tsc_DimPercentOfCell
    };

Note that when using  tsc_DimPercentOfCell in conjunction with a fine form grid (eg, 50 x 50), it is possible to specify a width or height greater than 100. For instance, a value of 250 would be 2.5 cells wide, which will work just fine.

Margins

void SetCustomMargins (int left, int top, tsc_DimensionType dimType = tsc_DimPercentOfCell);
A control is placed by default at the top left of its grid cell.   Any individual control or field may be moved relative to the top-left of its cell by some percentage of the cell, grid, or window size, similar to the above for setting dimensions.  The left and top values may be positive or negative and of any magnitude; a control may be moved outside of its cell.  Specify zero for no effect.  You should not use tsc_Control::NoLayoutPosition for margins.

More detailed information can be found at tsc Form - Custom layout box model.

Note that margins are effective on tsc_GroupBoxStartControl and tsc_GroupBoxEndControl; they simply serve to move the top-left and bottom-right corners of the group box, respectively.

Visibility

You can set or query the Visible status of a control; controls that are not visible continue to take up space in the layout, but nothing is displayed in the space.  To remove a control from the layout altogether, remove it from the form's control list.

    bool IsVisible  () const;
    void SetVisible (bool visible);  

Presence

You can set or query the Present status of a control; controls that are not present take up no space in the layout (unlike not-visible which is invisible but still reserves space on the form).

    bool IsPresent  () const;
    void SetPresent (bool visible);  

Colours

Custom colors may be set for fields and controls.  Note that some controls may ignore color settings - currently colors are supported by tsc_LabelControl and all tsc_Field derived classes except tsc_CheckboxField and tsc_RadioField.  Controls or fields that appear read-only (e.g. read only fields or all tsc_LabelControls) use only the foreground color because they indicate the read-only state by displaying text on the form background.  For tsc_ButtonControl they set the "normal" colours - when the button is enabled, not depressed, and doesn't have focus; see the additional colour setting methods on tsc_ButtonControl for the other button states.  Setting a colour to tsc_Color::Empty behaves the same as clearing it.

    void SetForegroundColor(const tsc_Color& color);
    void SetBackgroundColor(const tsc_Color& color);
    void ClearForegroundColor();
    void ClearBackgroundColor();

Prompts

Most controls will take an x-coded prompt value which can also be used as an identifier for the field.  The prompt must map to a translatable string that lets the user know what the field is for.  It is typically displayed as a label preceding or associated with the control that displays the value.  In general, fields follow this pattern of displaying the prompt, whereas controls do not.  For example buttons and radio-buttons use the x_Code as a unique identifier for button click event handlers, but use other means to set the text.  Each x_Code identifier must be unique across all controls on a form, including softkeys.

x_Code GetIdentifier ();
Retrieves the control's identifier.

void SetIdentifier (x_Code newText);
Changes the control's identifier and prompt text where applicable.

Text size and weight

tsc_Control* SetPromptTextSize (tsc_TextSize size);
Sets the size of the prompt text.

tsc_Control* SetTextSize (tsc_TextSize size);
Sets the size of the text used in the control.

tsc_Control* SetTextWeight (tsc_TextWeight weight);
Sets the weight of the text used in the control.

Events

virtual bool OnFieldParse(const char* fieldText, tsc_String& error);
Optionally override this to perform the parsing of text in edit control-based fields.  If you return true the standard SurveyCore parsing will not occur.

Populate the error string to present a (translated) tooltip error and force the user focus back to the field to correct or abandon the edit.

Note that if you override this there will be no SuveyCore processing of the text - you need to parse it and set the value on the control if the (your!) parse was successful.  If you return false then SurveyCore parsing will continue (in fact the tsc_Form event gets the next chance to override the parsing).

virtual enum tsc_ContextFieldMenuButtonBehaviour OnIsContextMenuButtonPresent();
Optionally override to control whether the context field menu button appears (only effective for fields that are based on edit fields).

virtual void OnContextMenuRequested(tsc_FieldContextMenu& menuItems);
Optionally override to append or edit the context field menu options. Only called for field types with the ability to display a context menu.

virtual bool OnContextMenuSelected (x_Code& selected, tsc_String& fieldText, int& cursorPos);
Optionally override to handle the selected field context menu selection made by the user. This handler is only called for field types that are able to display context menus.

Return true to indicate that the field edit should be completed with no further menu handling or return false to allow editing to continue or for the standard (or base class) event handlers to persue further action.

In either case you can modify the fieldText or cursorPos to suit your requirements, a field edit operation will be started if neccessary.

If you change the fieldText consider updating the cursor position to suit the location that further input should be placed (i.e. often at the end).

List of control types

         ButtonControl,              ///< A button containing text.

    ImageButtonControl,         ///< A button showing an image.

    MenuItemControl,            ///< A button for tsc_WizardMenu forms.

    UITaskMenuItemControl,      ///< A standard UITask button for tsc_WizardMenu.

    SubMenuItemControl,         ///< A sub menu button for tsc_WizardMenu.

    SoftkeyControl,             ///< A softkey control for any form.

    LabelControl,               ///< A simple one-line text label.

    ImageControl,               ///< A control containing a single image.

    ListControl,                ///< A list box, being a list of items with columns.

    StringField,                ///< A string edit field with prompt.

    FloatField,                 ///< A unitless floating-point number field with prompt.

    AzimuthField,               ///< An azimuth (angle) field with prompt

    AngleField,                 ///< An angle field with prompt.

    HorzDistanceField,          ///< A horizontal distance field with prompt.

    VertDistanceField,          ///< A vertical distance field with prompt.

    SlopeDistanceField,         ///< A distance field with prompt.

    DurationField,              ///< A duration field with prompt.

    DateField,                  ///< A date field with prompt.

    TimeField,                  ///< A time field with prompt.

    TimestampField,             ///< A timestamp field with prompt.

    IntegerField,               ///< An integer field with prompt.

    CheckboxField,              ///< A checkbox field with prompt.

    GradeField,                 ///< A grade field with prompt.

    StationOffsetField,         ///< A stationing and offset field with prompt.

    FilenameField,              ///< A filename field with prompt.

    RadioField,                 ///< A radio button field with prompt.

    DropDownStringListField,    ///< A drop-down list box field with prompt, populated by strings.

    DropDownXCodeListField,     ///< A drop-down list box field with prompt, populated by x-codes.

    DropDownEnumListField,      ///< A drop-down list box field with prompt, representing an enum.

    GroupBoxStartControl,       ///< For starting a Group box.

    GroupBoxEndControl,         ///< For ending a Groupbox.

    LineBreakControl,           ///< Control used to force the next control on to a new line.

    EnterSoftkeyControl,        ///< A softkey control occupying the Enter (right) position.

    EscSoftkeyControl,          ///< A softkey control occupying the Escape (left) position.  

    SeparatorMenuItemControl,   ///< An empty item to be used as a separator on a wizard menu.

    FeatureCodeField,           ///< A string field for entering database feature codes.

    PointField,                 ///< Field used to enter a new point name or to select an existing point.

    PasswordField,              ///< String field used to enter passwords.

    AreaField,                  ///< A field for displaying or retrieving an area value.

    LatitudeField,              ///< A field for high precision latitude locations.

    LongitudeField,             ///< A field for high precision longitude locations.

    MultiLineEditField,         ///< A text field capable of handling multiline text.

    TreeListControl,            ///< A list control where each row may contain expandable nested subtrees.

    CustomMenuItemControl,      ///< A custom button for tsc_WizardMenu.

    HorzCoordinateField,        ///< A coordinate horizontal value.

    VertCoordinateField,        ///< A coordinate vertical value.

    DropDownPortListField,      ///< A drop-down list box field, containing a list of serial ports.

    PrismConstantField,         ///< A field for entering Prism constant values in mm.

    InstrumentHeightField,      ///< Instrument height field

    TargetHeightField,          ///< Target height field

    StationingField             ///< Stationing (distance) field.