User Interface overview

UI tasks

When the user starts some operation, such as Compute Inverse or Stake out, Survey Core creates and launches a UiTask to represent the operation, and the plugin may then create any number of forms within the framework of that UiTask.

Within one UiTask, all forms are modal.  The most recently shown form must be closed before the user can interact with the previous form.  Once the last form is closed, the UiTask terminates, and the user is returned to the previously displayed UiTask or to the main window.

The user may start multiple UI Tasks and make use of the main menu to switch between them at (almost) any time.  When a UiTask is brought to the front, the form most recently shown (ie, the topmost) within that UiTask is displayed.

Forms

Nearly all User Interface interaction with the user is carried out on forms, implemented by making a subclass of tsc_Form. 

Controls and fields

A number of controls are available for displaying on a form.  These include static text, a single-line edit control, a list view control, drop-down lists, buttons with text and/or graphics, and images.  Many controls perform extra functions and are instead called fields.  Fields often combine multiple controls and perform functions such as formatting and parsing of the value, context-sensitive utility menus, verification of input values, etc.  Field types include edit controls for values such as Azimuth, Horizontal distance, filenames, etc.

Laying out controls on a form

By default, controls and fields are placed on a form using a type of automatic flow layout.  Depending on the size of the control and the size and aspect ratio of the screen, controls are laid out in a grid starting at the top left and proceeding to the right and towards the bottom.  Controls passing beyond the bottom of the screen will not be visible but can be scrolled or swiped into view.

SCAPI allows the plugin to define its own grid and position the controls anywhere within the grid.  This method allows much greater control over the layout, but suffers from some dependence on the screen size and aspect ratio of the many different devices supported by Trimble Access.

Graphical forms

A form may contain images by using the tsc_ImageControl, and in the extreme case, the form may contain a single image control covering almost the entire window.  The plugin may then draw anything on the image and also handle mouse (stylus) events to provide fully graphic interaction. The TrimBlocks sample plugin in the SDK illustrates how this may be done.

Events

All events are handled by the form, including those generated by controls and fields.  Event handlers are written by overriding the tsc_Form's event handler method in the subclass. All event handler function names begin with On. Only the handlers for wanted events need to be overridden; events for any handler not overridden will simply be ignored.  Generally, all UI and event handling within a UiTask is performed on a single thread.  Any operation to be performed on a form from a different thread must be passed through a tsc_Event and tsc_EventDelegate pair so that the correct thread is used to interact with the form.

Forms normally sit in a wait state, waiting for events to be raised.  This can only occur while the form's thread is in the appropriate message-handling wait within Survey Core.  If a form event handler performs a long computation or calls any function (such as a Windows API) that blocks the thread with a wait, event dispatching will be prevented and the UI will become unresponsive.  For this reason, long computations or functions requiring waits should either be performed on a separate thread, or steps taken to make the computation interruptible by form events.