tsc_IMeasureFormMonitor

This interface is used to handle the events on a tsc_MeasureForm that the plugin has started, or a measure form that is currently in use.

Use this interface by passing an instance into the tsc_MeasureForm::Start method or by returning a new instance from a tsc_MeasureFormHandlerFactory  (note that some factory supplied monitors will be discarded).

When the measure form is used the relevant events are triggered as a result.  The events will stop occuring once the form has been dismissed.

For more information on how to use event monitors see the page Event handling.

Some of these events allow you to access and change data in the measurement process, always test what result this has on the database and the host measure form behaviour.  Be aware that there are many types of measure form and you may wish to restrict which events you handle.

Events can happen in any order as some measurement forms can handle multiple measurements, or the user can switch applications forcing a different monitor to supplanted the existing one.  It is best to not assume that you will have all the events called in the order you expect.  Handle each event so that you are resilient to this type of event interruption.

For example:

• • The user started your measurement but switched away to General Survey and you lost control of the measurement (supplanted).

  • While there the user captured the measurement and your monitor did not get the OnPostMeasurement event that was necessary for your workflow.

  • The user then switched back to your application and one of your monitors was reinstated.

  • The user attempted to Store the measurement.

  • In OnPreStore your code can choose to allow the standard measurement through without your workflow or perhaps deny the store with a dialog letting the user know that another measurement is required.

In general these are rare but should be considered to construct robust code.

Event handlers

virtual void OnMfMeasured ();
A measurement has completed but has not been stored yet.

virtual void OnMfStored ();
A point has been stored to the database.

virtual void OnMfCompleted ();
The measure form has closed after a successful observation.

virtual void OnMfAborted ();
The measure form has closed without storing an observation.

virtual void OnRequestorDestroyed ();
The tsc_MeasureForm object that started the monitor has been destroyed.  No more events will be received.

virtual void OnMfSupplanted ();
Another UITask has taken control of the measure form. This is caused by the user selecting a point measurement through some other UI, such as the map.  No more events will be received.

virtual void OnCreated ();
The tsc_MeasureForm object that the monitor started with has been destroyed. WRONG!!

virtual void OnPointNameSelected (tsc_String& newName);
The point name has been changed by either the form creation, a point being stored or by the user changing it.  You can edit the name but be aware that some point fields have requirements about whether the point exists or not, care required.

virtual void OnCodeFieldChanged (tsc_EntityFeatures& features);
The code field value has been changed and as a result the attribute data will have been edited.  You can remove, append or prepopulate any custom features and attributes here.

Be aware that custom attributes that are unknown to the current job's feature library cannot be edited by the default UI and you may need to override this or apply custom attributes on the OnPreStore event.

virtual tsc_AttribEditResult OnAttributeSoftkey (const tsc_Observation* observation, tsc_EntityFeatures& features);
The user is requesting to edit the attributes, return a value to indicate whether you have handled this and if you have, whether the operation was successful and the attributes are ready to be stored.  If the operation is not handled the SC default entry UI will be used.  Be aware that the features will not neccessarily be populated from the code field and that this may happen at point store.

virtual bool OnPreMeasure (tsc_Observation* observation);
Return true to allow the measurement to start.  The observation will hold any details gathered so far. !! Todo What happens on false return??

virtual bool OnMeasureCancelled (tsc_Observation* observation);
The measurement was cancelled.

virtual bool OnPostMeasure (tsc_Observation* observation);
Return true to accept the measurement result.  The observation will hold any details gathered so far.

virtual bool OnPreStore (tsc_Observation* observation);
Return true to allow the measurement to be stored in the database.  The observation parameter holds the measurement details to be stored. If false is returned and the setting
tsc_MeasureForm::ExitFormOnPreStoreCancel is set to true, the measure form will exit immediately; if false, the user may continue measuring another point.

virtual tsc_AttribEditResult OnPreStoreAttribute (const tsc_Observation* observation, tsc_EntityFeatures& features);
We have stored the points and now it is time to make sure the attributes can be stored.  This is a validation where you are expected to ensure that all attribute data is ready to be stored and you can show UI to achieve this if default values cannot be determined.  If this is not handled then SurveyCore will show perform this task.  Note that if your event handler handles this and returns a AttribHandledAborted then the measure point will be deleted if it has already been stored (you may wish to warn the user of this with a dialog, X_DiscardAttribsPointCodeChanges, X_DiscardAttribsDeleteStoredPoint & X_DiscardAttribsDontStorePoint may be useful).  Note that this may be called more than once.

virtual void OnPostStore (const tsc_Point& point);
Called after the point is stored in the database.

virtual bool ServiceEventsOnMeasureFormThread();
Not an event as such, but called by SurveyCore to determine what thread you wish to have your events serviced by.

Standard Monitor practice is to have the events serviced by the thread that calls Start.  This is appropriate as it will be the correct thread to deal with the data and objects that the caller has nearby.  If that thread is hosting an active UITask then it can also perform UI as part of that task.

In the case of this monitor it is the tsc_MeasureForm that will call Start making it like a typical monitor.  If you are customising the measure form with UI or a lengthy operation (which suggests UI to inform the user of the current state) then you really want to be running on the measure form thread so that your UI is a part of that UITask.  In this case override this function to return true, the default return is false. tsc_MeasureFormHandlerFactory generated monitors will always be started on the measure form thread.