tsc_Form - Custom layout box model

Please note that, since version 21.00 of Trimble Access, forms are scrollable and no longer paged. This means that forms can be of arbitrary length and so the height and bottom margin parameters are mostly irrelevant. The height of a form is still 100% and represents the viewable portion at the top for any form that is longer than the height. Some other aspects of control positioning may have changed since pre-21.00 days.

Dimensions

All dimensions used for custom layout are expressed in percentages, which means the form will work on any window size and screen resolution, within reason.

The image above shows a form with a 2x2 grid containing single large button in position (0,1).  This example can be seen in the HowToSample plugin in the samples directory of the SCAPI installation.  The parts shown in blue, red, and yellow have been manually added for explanation; the rest is as the form would appear. 

The button control shown in the image allows internal layout using alignment and padding, however most other controls do not provide this functionality.

A sample code snippet to produce this form is given at the bottom of this page.

Form layout

A custom layout form is laid out like a table, which we call a Grid, with some number of columns and rows.  Each box in the grid is called a cell, rather like an HTML table. The grid has an outer margin between it and the inside of the form window.  The blue lines in the example form show where the cell borders lie, and the thinner blue lines are the cell boundaries.

The tsc_Form methods SetCustomGridDimensions and SetCustomMarginsPercent are used to configure the grid.

Multi-page forms

Prior to Trimble Access version 4.00, forms could have multiple pages. Since 4.00, the grid simply continues down and off the bottom of the window, for as many rows as are required by the form. The user may scroll the form using up and down swipes.  To place controls and fields beyond the bottom, simply use higher row numbers. The tsc_PageBreakControl now performs no function.

When controls are being added whose position is unspecified (that is, SetCustomLayoutPosition has not been called) the control is placed into the grid cell following the highest one previously used, working left-to-right then downwards from the top.

Control and field positioning

Controls and fields are positioned relative to the top-left corner of a cell.  By default, the top-left of the control or field is aligned to the top-left of the cell, however it may be offset from this position by specifying a left and top margin.  Margin values may be negative, which offsets the control towards the left and upwards.  These are set using the SetCustomMargins method of tsc_Control.

For a field, the top left is generally the upper left corner of the prompt text, and the control is positioned below the prompt.  For controls (which have no prompt), it is the upper left corner of the control itself.  Some controls such as the button (as used in the example image above) also have internal layout control properties for further positioning the content within the control's borders.

Control and field sizing

The size of a field or control may be specified using the SetCustomDimensions method of tsc_Control.  The size of a control may also be constrained by the size of the form.  If no size is specified, Survey Core will attempt to provide a standard size field or control, which will  be suitable for most "normal" uses.  In some cases, for instance a button with an image or an image control, the control will be sized to fit the image.  The default size for a button control will be the size of the image plus the padding, or if there is no image then the button will be made the standard Survey Core height and the width to fit the text.

Internal layout for some controls

Internal control layout is governed by two mechanisms; padding and alignment.  The padding lies inside the border of the control and provides an empty space between the control's border and the content.  The rectangle enclosed by the padding (the yellow rectangle in the example at the top of this page) is called the content rectangle. If the content text or image exceeds the extent of the content rectangle, the padding areas may be overwritten.  Clipping only occurs at the border of the control.

Padding values are specified as percentages of the control size.  For this purpose, the control size is the size of the outside of the control, and includes the border, padding, and content (eg, the "Internet Explorer" width in the diagram below).

Within the content rectangle, content may be aligned horizontally (left, centre, right) and vertically (top, middle, bottom).  There are separate properties for text and images so that, for instance, an image can be aligned to the left and the text to the right.  If they overlap, the text is drawn on top of the image.

The left, right, top, and bottom alignments place the content hard against the relevant side of the content rectangle.  The middle and center alignments place the centre of the content in the center of the content rectangle.

Default values

If any layout property is not set, the form system defaults that setting as though the following had been applied:

SetCustomGridDimensions (2, 5);

SetCustomMarginsPercent (0, 0, 0, 0);

SetCustomLayoutPosition (...); // The next available cell. SetCustomMargins (0, 0);

SetPadding (8, 8, 8, 8);   // Or similar for resolution. SetCustomDimensions (...); // An appropriate size.

TextAlign (tsc_AlignMiddleCenter);

ImageAlign (tsc_AlignMiddleLeft); 

Sample code to match the example form

The following code will produce a form similar to the image shown on this page.

BoxForm::BoxForm () {      // Set up the form         this->Text ("SCAPI Layout box model");     this->SetLayoutMode (Layout_Custom);     this->SetCustomGridDimensions (2, 2);     this->SetCustomMarginsPercent (12, 16, 4, 16);      // Load the "tick" image for the button. In the USA this is called a check mark.     checkMark = tsc_Image::FromResource (IDB_BigLittleTick);      // Create the button and set up the layout.     buttonControl = new tsc_ButtonControl(X_LayoutMethod, "Yes", checkMark);     buttonControl->SetCustomLayoutPosition (tsc_ColRow(0, 1));     buttonControl->SetCustomMargins (8, 28, tsc_DimPercentOfCell);     buttonControl->SetPadding (18, 2, 7, 26);     buttonControl->SetCustomDimensions (128, 40, tsc_DimPercentOfCell);     buttonControl->TextAlign (tsc_AlignTopCenter);     buttonControl->ImageAlign (tsc_AlignMiddleLeft);     this->Controls.Add (buttonControl); }