tsc_UITask

Overview

The tsc_UITask class represents one task, or unit of work, that a user can invoke from a menu or by other means, and that a programmer can launch.  Approximately 270 UI tasks are predefined in Survey Core, including Starting a survey, measuring a point, running a Station Setup, displaying a calculator, opening a job, staking out a point, displaying a map, COGO computations, keying in a road, and so forth.

Also see: About UITasks

Important: UITasks should not be launched as a convenience for the programmer; they are similar in concept to a Process within the Windows O/S.  One does not launch a separate Windows application simply to run some code in parallel (that is, on another thread), and likewise UItasks must not be used for this purpose, unless the task is a new workflow.  In addition, a UITask is not always run on a separate thread, so this is not a reliable means to start a new thread.  Instead, use tsc_MonitorThread and tsc_Thread.

For more detail about how tasks relate to jobs and instruments, see the section About UITasks, jobs, and instrument switching

Within a plugin, new UITasks are defined and registered with Survey Core by subclassing from tsc_UITask and implementing the required functionality, and registering the subclass with tsc_Application.

All UITasks, including every tsc_UITask, is identified by a run code - an x_Code which is a predefined integer value.  To start a task, one only needs to specify the run code and the correct UITask will be launched.  Each x_Code can be registered to one UITask only, and only one instance of a specific UITask may be running at a time.

Each UI task must specify the requirements for the environment in which it will run.  It may require a job database to be open, it may need a total station to be connected, or it may require that a Station setup has been completed.  These requirements are defined within the tsc_UITask subclass so that SC can set up the environment before the task is run, or conversely not show (or disable) a menu item until the correct environment is present.

Because a UITask's requirements have to be known to Survey Core any time a menu containing the task is displayed, Survey Core must be able to instantiate a tsc_UITask at will.  The plugin programmer must therefore supply a function callback which will construct their tsc_UITask subclass and return the address.  This construction may happen quite often, so it is suggested that as little as possible work is done in the constructor.  If the user chooses the menu item (or it is launched programatically) then the Run() function in the class is called, and that is where all the work is done.

UITasks may be launched programmatically with the Launch function in the tsc_SurveyCore class.

Member functions

tsc_UITask  (int scTaskId);
The constructor should called via a new() from the callback function specified in the RegisterUITask (see tsc_SurveyCore class).  The task ID passed to the callback must be passed onwards to the base class constructor as scTaskId.  The constructor should be light-weight, as the UITask may be constructed frequently.

virtual ~tsc_UITask ();
The destructor may be called quite often and in most cases there's no need to implement it.  Clean-up for the task is best done just prior to returning from the Run() function.

virtual void Run ();
Override this function to implement your task.  This function is called when a user selects the task's menu item, or when it is launched programatically.  The task is normally (but not always) run on a new thread.  Until the Run function exits, the task remains in a runnable state and is able to be switched-to by the user, and it can respond to events.  Because the UITask finishes when the Run function exits, the UITask is typically kept running by displaying a form using ShowDialog() which doesn't exit until the form is closed.

The Run function (and anything it calls) should avoid long operating system waits, such as the Windows' API call Sleep() or any of the wait functions, as these will cause the UI to lock up until the wait finishes.  The Survey Core event system contains functions for most situations where a wait is required, and these must be used in preference to O/S calls.

x_Code RunCode () const;
This function returns the task's run code.

bool CanBeShutDown () const;
Test if all open forms in this UI task can be closed.
A form is considered "able to be closed" if there is no unsaved input and the plugin has not called IsCloseable(false) on the form.  If all forms currently open in the UItask are in a closeable state, then this function returns true.  Survey Core uses this value to determine if an "abandon changes" warning needs to be issued before shutting down a UI task.

bool IsFront () const;
The following function returns true if the top form of this UI task is executing at the front of Survey Core.

bool IsRunning () const;
Returns true if this UITask is currently executing, regardless of whether it's on top or hidden under other UItasks.

tsc_SurveyStyle TaskStyle () const;
Returns the style selected by user for this task (this could be an empty style).

tsc_Instrument& TaskInstrument () const;
Obtains a reference to the instrument that was assigned to this task at the time the task was started.  This is the instrument that the task is expected to be working with.  In order for an instrument to be assigned, the UItask's RequiredSurveyState() method must return something other than tsc_SurveyStateNone and you should return true for SupportsGnss and/or SupportsTs.

tsc_Instrument CurrentInstrument () const;
Obtains a reference to the instrument that is currently connected.  Total stations have precedence over GNSS instruments when both are currently in use.  Can be useful for determining your UITask menu item status.  Note that this instrument may be in use by another task and may change at any time; it therefore must not be used for measurements or any other function that could change its state.  Instead, use TaskInstrument().

tsc_Instrument SetTaskInstrument (tsc_InstrumentType type);
Sets the instrument currently assigned to the (running) task.  The call will be ignored if the supplied instrument does not match the task criteria.  The TaskInstrument is returned. If the task is the topmost task then the display instrument will be changed as well.

Environment

The following survey states may be requested by a UITask.  The requested state will be automatically set up before the UITask's Run method is called.   This may involve the user having to select a style, level the instrument, etc.  If the user cancels out of any essential part of this, the task will not be run.

enum tsc_SurveyState
{
tsc_SurveyStateNone,
Means that no instrument interaction is performed by the UITask.
TaskInstrument will return a null Instrument.

tsc_SurveyStateConnected,
Means that a connection to an instrument of the type specified by the SupportsXxx methods will be established..

tsc_SurveyStateStyleSelected,
Means that a style while be selected for the task but an instrument connection will not be enforced.
TaskInstrument could be a null instrument or an instrument not suited for the selected style.

tsc_SurveyStateStyleConnected,
Means that a connection to an instrument and a style will be established before the task is run (e.g. for a station setup).

tsc_SurveyStateSurveyActive
Means that a connected instrument, style and a current (or starting) survey will be established before the task is run.

};

Overridable methods

The following functions allow plugin programmers to configure the environment in which their UI task is to run.  They are called as required by Survey Core, and therefore should be overridden in the subclass. Generally it is sufficient to return a constant value, although it is possible to compute a value (for instance, EnableOnMenu might be dependent on some external condition).  Override any function which requires a value different from the default shown below for the function.

virtual tsc_Image& Icon()
Return an image that is shown for this task. In particular, this image is used on the favorites form, so it is usual to use the same icon as that used for the same item in the main menu. If this method is not overridden, the application icon is used which is not ideal if more than one UiTask will be registered.
It is good for this function to cache the tsc_Image and not reload or redraw it every time, since it may be called quite often and the image is always the same.

virtual bool RequiresJob () const { return false; }
Does a job have to be open before running this task?  If set to true and no job is open, the user is prompted before the task is run. This should return true if the UiTask references the current job or database in any way.

virtual bool RequiredSurveyState () const { return tsc_SurveyStateNone; }
Is a style required (in other words, must a survey be running) before this task is launched?  If this function returns anything other than tsc_StyleStateNone, Survey Core will set up the required conditions (see the tsc_SurveyState enum) before the task is run.  This may include a list of styles; the types of styles presented to the user depends on the values that SuppportsGNSS and SupportsTS return, and if they both return true, integrated surveying styles are also included.

virtual bool SupportsGnss () const { return false; }
Return true if this task supports the use a GNSS receiver.  Also see RequiredSurveyState.

virtual bool SupportsTs () const { return false; }
Return true if this task requires a conventional instrument.  Also see RequiredSurveyState.

virtual bool ShowOnMenu () const { return true; }
Should this item be currently displayed on General Survey menus or tsc_WizardMenu forms?

virtual bool EnableOnMenu () const { return true; }
Should this item be currently enabled on General Survey menus or tsc_WizardMenu forms.  Returning false greys out the item.

virtual bool TickOnMenu () const { return false; }
Should this item be currently ticked on General Survey menus.

virtual bool SeparateMenu () const { return false;}
When true, displays a separator line before this item on a General Survey menu.

virtual bool  AllowSwitchTo () const { return true; }
Should this task be shown on the "Switch To" menu?  If false, the task will never appear on the switch-to menu, but the user may still return to this task if the task in front is closed, or Ctrl+Tab is pressed.

virtual tsc_String SwitchToText () const { return ""; }
Optionally override to change the text for this task when it is displayed on the "Switch To" form.  By default, the translation of the task's run code is displayed - which in most cases is adequate.

virtual bool  RequiresThread  () const { return true; }
Override this function and return false to have this task run on the main thread.  At the time of writing, returning false should be avoided for any task which performs UI, since modeless forms are not yet possible with Survey Core.  A task which performs some action but has no UI and performs no waits, may return false for improved performance.

virtual bool AllowInstrumentSwitch () const;
Override to select whether the user can change the task instrument on-the-fly by clicking the status message bar or via SetTaskInstrument.  By default this is true.

virtual tsc_String PreselectStyle () const;
Override to have the named style used always.  This override has priority over PreselectStyles.

virtual tsc_StringList PreselectStyles(const tsc_StringList& preFiltered) const;
Override to filter the styles available for user selection, this call will be supplied with a list of suitable styles already filtered to met the task criteria (which may be empty!).  If overridden you can then return a modified set to reflect your style preferences.

virtual bool TaskRequestsStationSetupStatus() const { return false; }
Override to request that this task is considered as a station setup routine in menus, specifically within tsc_SurveyMenuUITask menus.