tsc_IMeasureFormMonitor

This interface is used to handle the events on a tsc_MeasureForm that the plugin has started or a measure from that is part of SurveyCore within your application.

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 forms and you may wish to restrict which events you handle.

Events can happen in any order as some measurement form have multiple measurements or the user can switch applications forcing monitor supplanting.  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

A measurement has completed but has not been stored yet.

virtual void OnMfMeasured ();

A point has been stored to the database.

virtual void OnMfStored ();

The measure form has closed after a successful observation.

virtual void OnMfCompleted ();

The measure form has closed without storing an observation.

virtual void OnMfAborted ();

The tsc_MeasureForm object that started the monitor has been destroyed.  No more events will be received.

virtual void OnRequestorDestroyed ();

Introduced in version 1.60

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 OnMfSupplanted ();

Introduced in version 1.60

The tsc_MeasureForm object that the monitor started with has been destroyed.

virtual void OnCreated ();

Introduced in version 2.60 as a Beta interface extension, accepted in 2.70.

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 OnPointNameSelected (tsc_String& newName);

Introduced in version 2.60 as a Beta interface extension, accepted in 2.70.

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 void OnCodeFieldChanged (tsc_EntityFeatures& features);

Introduced in version 2.60 as a Beta interface extension, accepted in 2.70.

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 tsc_AttribEditResult OnAttributeSoftkey (const tsc_Observation* observation, tsc_EntityFeatures& features);

Introduced in version 2.60 as a Beta interface extension, accepted in 2.70.

Return true to allow the measurement to start.  The observation will hold any details gathered so far.

virtual bool OnPreMeasure (tsc_Observation* observation);

Introduced in version 2.60 as a Beta interface extension, accepted in 2.70.

The measurement was cancelled.

virtual bool OnMeasureCancelled (tsc_Observation* observation);

Introduced in version 2.60 as a Beta interface extension, accepted in 2.70.

Return true to accept the measurement result.  The observation will hold any details gathered so far.

virtual bool OnPostMeasure (tsc_Observation* observation);

Introduced in version 2.60 as a Beta interface extension, accepted in 2.70.

Return true to allow the measurement to be stored in the database.  The observation will hold the measurement details to be stored.

virtual bool OnPreStore (tsc_Observation* observation);

Introduced in version 2.60 as a Beta interface extension, accepted in 2.70.

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 tsc_AttribEditResult OnPreStoreAttribute (const tsc_Observation* observation, tsc_EntityFeatures& features);

Introduced in version 2.60 as a Beta interface extension, accepted in 2.70.

Called after the point is stored in the database.

virtual void OnPostStore (const tsc_Point& point);

Introduced in version 2.60 as a Beta interface extension, accepted in 2.70.

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.

virtual bool ServiceEventsOnMeasureFormThread();

Introduced in version 2.70.