tsc_MeasureForm

This API allows a certain amount of control over the standard Survey Core point measurement UI. 

This class should be used in preference to using tsc_SurveyCore::Launch to start a measurement. It uses the same forms and workflow but provides greater control over the process.

Prerequisites to running a tsc_MeasureForm

If a tsc_MeasureForm is started by a plugin when there is no current survey, the user will see a menu of styles which will include both TS and GNSS.

If the use chooses a GNSS style, a GNSS survey is started using the normal Survey Core workflow to set up the receiver and establish a GNSS corrections stream.  When complete, the measure form is displayed.  Note that the measure form will often appear before the receiver has gained initialization; it is up to the user to wait until accurate fixed positions are available before beginning to measure points.

If the user has choosen a conventional style (ie, using a total station) a list of types of Station Setup that can be done will be displayed.  The user is then led through a workflow for the chosen method and after the station setup is complete, the measure form will be displayed.

Often, this workflow will not be useful for new types of station setup provided by the plugin, and for this reason the Plugin's workflow should be implemented in a UITask, with appropriate implementations of the SupportsTs, SupportsGnss, and RequiredSurveyState methods.  When the UITask is launched (preferably by the user), a survey style, instrument connection, etc, will be established so that when the tsc_MeasureForm is run, everything is correctly set up for it, and the built-in Survey Core station setup workflow will be avoided.

Measurement types

The type of point stored in the database is controlled by this enumeration.

enum tsc_MeasureType

{

    tsc_MtTopo,            // A "normal" topo measurement.

    tsc_MtCalibration,      // A GNSS calibration point.

    tsc_MtCheckshot,       // A check measurement

    tsc_MtBacksight,       // A backsight measurement

    tsc_MtCheckBacksight,  // A backsight check measurement.

    tsc_MtConstruction     // A point used to construct a cogo calculation.

};

tsc_MeasureForm class

This class stores up the options and starts a measurement or series of measurements.

Measurement options

Set these properties according to how the measurement form is required to behave, before calling Start().  The defaults value are false for booleans and empty for strings.

tsc_MeasureType  Type;

Sets the type of the point to be stored in the database.  The default is tsc_MtTopo.

bool AutoPointName;

Set this to true to automatically increment the point name to an unused one before each measurement.

bool AutoMeasure;

Setting this to true automatically starts measuring without asking the user to press the Measure button.  If this option is set true, the AutoExitForm property should also be set to true, otherwise the user has no oportunity to move the instrument between measurements.

bool AutoExitForm;

If this property is set true the measure form will exit and redisplay the calling task after the measurement is done.  If false, the form remains displayed (and allows more measurements) until the user presses Esc.

bool AllowIncompleteStation;

Normally, the measurement UI will not allow Total Station measurements to be taken until a station setup has been completed.  Set this true if measurements are to be performed during station setup.

bool CheckForDuplicates; (Defaults to true)

Normally SurveyCore will check to see if the measured point already exists (by name) and will prompt the user to determine the duplicate point behaviour.  This is on by default but may be disabled.

bool AllowCsvBacksightCopyToJob;

Used for measuring backsight points only. A backsight measurement requires a defining coordinate, and this must remain present in the current job database. It is possible to use a point from a linked CSV file, however if the file is detached then the entire station will become unusable. If a CSV point is chosen with this option set true, then the coordinates will be copied into the current job making the backsight and the station independent of the linked file.

void PointName (const char* name);

Supply a name for the point, or leave it empty to auto-generate a point name according to the user's current configuration.  If AutoPointName has been set true, this point name may be incremented until a unique name is found; otherwise the name is used unchanged, and if the point already exists in the database then an additional measurement for the point is stored after the point tolerance system has processed the coordinate.

void PointCode (const char* code);

Supply a value for the code field on the measure form.  If left empty then the last-used coding is used.

void Features (const tsc_EntityFeatures& features);

Features for the point.  Only features referenced by the point code will be used.

Constructor

tsc_MeasureForm (tsc_MeasureType type);

Constructs the instance and supplies a measurement type.  The type is always required but may be changed before the measurement is started.

Starting a measurement

void Start ();

void Start (tsc_IMeasureFormMonitor* monitor);

These methods launch the measurement form if necessary, bring it to the front, and allow the user to control the measurement, in line with the options previously set.  The overload with the monitor parameter allows progress on the measure form to be tracked.

bool StartAndWait ();

bool StartAndWait (tsc_IMeasureFormMonitor* monitor);

These methods launch the measurement form if necessary, bring it to the front, and allow the user to control the measurement, in line with the options previously set.  The overload with the monitor parameter allows progress on the measure form to be tracked.

This version will also wait for the completion of the measure form workflow, returns true if at least a single point was stored.

Monitoring progress

There are two ways to monitor the progress of the measurement. The first is a simple method that returns the current state, and the second uses a tsc_Monitor subclass to invoke event handlers on changes of state.

The following enumeration defines the different states of the measurement form.

enum tsc_MeasureProgress

{

    tsc_MpNotStarted,     // Form has not been displayed yet.

    tsc_MpInProgress,     // Form is displayed, now waiting for measure, store, or other UI.

    tsc_MpDone,           // Store completed, form has exited.

    tsc_MpAborted,        // User aborted the measuring process, form has exited.

    tsc_MpAbandoned,      // Requestor abandoned the measuring process, form may still be running - no further events.

    tsc_MpSupplanted      // Some other UITask took control of the measure form that was being monitored - no further events.

};

tsc_MeasureProgress  Progress () const;

This method returns the current state of the measurement.

Starting a survey and style selection

If a measurement is started when no current survey exists, the user is prompted to select a survey style via a Survey Core form, and a survey is automatically started, which may involve an entire workflow such as station setup.  When the survey has been started, the measurement form is displayed according to the tsc_MeasureForm options. 

Monitoring tsc_MeasureForm events with tsc_IMeasureFormMonitor

Subclass tsc_IMeasureFormMonitor to receive progress events from the measurement form.  Override the methods for the events that are to be monitored; the events for methods not overridden will be discarded.  Your monitor will receive events until either the launched measure form or the tsc_MeasureForm instance are closed or destroyed respectively.  Where you want to listen to events for an extended time be sure that your tsc_MeasureForm instance is not destroyed prematurely.

See tsc_IMeasureFormMonitor for events that can be overriden.