About UITasks, jobs, and instrument switching

Most UITasks provide some kind of workflow, and a majority of these require a job to be open and some sort of surveying instrument, normally a GNSS receiver or a Total Station to be set up.  Tasks which support Integrated Surveying (IS) will require one GNSS and one conventional instrument.

Survey Core, and therefore the API, handles the setup of jobs and instruments as part of its architecture and developers are strongly encouraged to follow the automatic workflows.

In brief, a UITask is a class which supports interaction between the app and a user, and carries with it a number of properties which describe the surveying environment required by the task, such as the type(s) of instrument it expects to use.  Many UITasks may run at once, using the same or different instruments, and the user may switch freely between the tasks and instruments - although with some restrictions.

Standard General Survey surveying workflow

First, the user must get one or more instruments connected and configured.  Before any kind of surveying can be done General Survey requires a "survey" to be running. For a Total Station this means the instrument must be levelled, and a station setup has to be performed, or a previous setup continued (the Use last functionality).  For GNSS the receiver needs to be configured to receive corrections or to log positions for post-processing, and configured correctly for the survey.  All of these configurations are controlled by the Survey Style which is chosen by the user (or chosen automatically if only one style is suitable).

Once this setting-up has occurred, a "survey" is running and the user can start other tasks such as Measure Topo or Stakeout. A user may be running several such tasks at once, possibly using different instruments.  At present Survey Core supports one GNSS receiver and one Total Station, separately or both at the same time.  Because different tasks may be using different instruments (eg, GNSS continuous topo at the same time as measuring control points with a total station), each task is assigned an instrument when it is started and the instrument remains associated with the task until it exits.  Tasks which support Integrated Surveying will have both instruments associated with them. An instrument may be associated with multiple tasks at a time.

The user typically works with one instrument at a time; the currently selected instrument is shown in the status bar and related messages are displayed in the message bar.  (S)He also may switch instruments manually.  When the user switches to a task that was started with a different instrument to the current, SC will automatically switch to the correct instrument for the task.

The instrument associated with a task is chosen in one of four ways:

• 1. If no survey was running when it is started, a list of styles allows an instrument type to be chosen (the style contains the instrument type).

  2. If a survey was already in progress, the currently selected instrument is used.

  3. If a task only supports one type of instrument, it will always switch to that type if it's available.

  4. The task itself has requested an instrument switch.  If successful the new instrument becomes associated with the task.

Using the API

The management of tasks, survey styles, and instruments, is a relatively complex business, so this management has been built into the UITask system to make setup easier for the programmer.  The UITask system is used throughout Survey Core itself to handle instrument connections and survey setup.  This means the system must be well understood to get the most from it, and to avoid "fighting" against it.

The API allows the programmer to control how his task is seen by Survey Core, by overriding the following functions in a subclass derived from tsc_UITask .  This means the correct environment (instrument, style, configuration, etc) will be correctly set up before the UITask's Run function is called.

virtual bool RequiresJob  () const;
virtual bool SupportsGnss () const;
virtual bool SupportsTs   () const;
virtual tsc_SurveyState RequiredSurveyState () const;

Returning true from RequiresJob ensures that a job is open before the task is run, and that it cannot be closed while the task is still running.  If no job is open when the task is launched, the Job Open dialog is presented to the user, and if this dialog is cancelled the task is not run.

If RequiredSurveyState reports that an instrument connection, style selection or survey start is required, then that action is performed before running the task.  Other states may be requested - see the tsc_UITask class for details.

Survey states other than tsc_SurveyStateNone and tsc_SurveyStateConnected require the user to choose a survey style before the task runs.  The items that are displayed on the style menu are determined by the SupportsGnss and SupportsTs return values.  If both of these return true then integrated styles are also included.  Tasks which are started with a style are also locked to the instrument(s) and they will be shut down if the survey is ended.