tsc_IReviewMonitor

This interface is used to handle the events on a job review form that the user has initiated or the plugin has launched.

Use this interface by implementing a subclass that returns a new instance from a tsc_ReviewHandlerFactory. Currently many review forms have no events so some monitors will be asked to do very little.

When the review 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 database via the review process, always test what result this has on the database and the host form behaviour.  Be aware that there are many types of review 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 review form but switched away to General Survey and you lost control of the form (supplanted).

  • While there the user manipulated the review data and your monitor did not get the 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 complete the form.

  • In a store event your code can choose to allow the standard request through without your workflow or perhaps deny the store with a dialog letting the user know that the edit must be aborted and restarted.

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

Event handlers

The review form handler has been initialised.

virtual void OnCreated ();
The review form has closed without any changes made.

virtual void OnClosedUnchanged ();
The review form has closed and the user has accepted the edits made.

virtual void OnClosedEdited ();
The review form has closed, abandoning any edits.

virtual void OnAborted ();
Another application has taken control of the review form. No more events will be received.

virtual void OnSupplanted ();
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 OnPreStoreAttribute event.

virtual void OnCodeFieldChanged (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 when the edits are stored.

virtual tsc_AttribEditResult OnAttributeSoftkey (const tsc_Entity& entity, tsc_EntityFeatures& features);
The user has committed to the store. Return false to abort the store.

virtual bool OnPreStore (const class tsc_Entity& entity);
We are accepting the edits and saving the data, 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 perform this task.  Note that if your event handler handles this and returns a AttribHandledAborted then the save will be aborted.

virtual tsc_AttribEditResult OnPreStoreAttribute (const tsc_Entity& entity, tsc_EntityFeatures& features);
We have completed storing now.

virtual void OnPostStore (const tsc_Entity& entity);