tsc_Control and field types

Controls and fields

tsc_Control is the base class for all fields and controls that can exist on a form.  A typical auto-layout form is shown on the right with several edit controls, and with the Semi-major axis field context menu displayed. Note also the two drop-down list fields (Type and Coordinates), and that the form is longer than the screen.  A large number of the fields available are variations (subclasses) of the edit control.  In its basic form it is a tsc_StringField.


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

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 will have 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 does reserve 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 text where applicable.

Warning tooltips

For the purpose of displaying warnings and error messages, a tooltip containing a message may be displayed adjacent to any field or control.  The tooltip remains visible for the duration specified, with a default of 3.5 seconds.  The user may continue to interact with the form while the message is displayed. Focus is set to the control when DisplayWarningTip is called.    

    void DisplayWarningTip (const char* message, double duration = 3.5);
    void DisplayWarningTip (x_Code message, double duration = 3.5);

For example:

point1Field->DisplayWarningTip ("This point should be a Backsight");
or
point1Field->DisplayWarningTip (PX_PointShouldBeBacksight);

The control must exist for the warning to be displayed.  Since the controls typically are not instantiated in the constructor or OnLoad functions, DisplayWarningTip is generally used in Event Handlers such as OnFieldCompleted.

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.