tsc_IScAppMonitor

This interface is used to handle miscellaneous Survey Core global events.  Any class may subclass from this interface, in addition to any other monitor interfaces and any regular base class.

See the Event handling page for more information on global events and event handling using the Monitor classes.

Class methods

void Start();
Call this method (use the tsc_IScAppMonitor::Start() syntax) to start global events flowing into the monitor's event handlers.  The thread that calls this method will be the same thread on which the event handlers are called.  It is not an error to call Start more than once.

void Stop();
This method stops event handlers from being called.  Use the tsc_IScAppMonitor::Stop() syntax.  The effect will be immediate.  It is not an error to call Stop more than once, and destruction of the monitor will also call Stop automatically.

Event handlers

Any of the following event handlers may be implemented.  Note that most of these handlers do not supply information about the event.  This is a performance consideration; the event sender does not know what the handler wishes to do and therefore does not waste time setting up interfaces that may never be used.  Rather, the event handler should "pull" the information it needs, when it needs it.

virtual void OnActiveThreadChanged()
The topmost form or window has changed to a form or window owned by a different thread from the previous window.  The tsc_UITask::IsFront method is useful to determine if one's own thread is currently displaying the topmost window.

virtual void OnOneSecondTick()
This event is fired every second.

virtual void OnAboutToSuspend()
The user has pressed the power-on/off button briefly, and the controller is about to suspend.  Process this event quickly, before the suspend occurs.

virtual void OnResumedFromSuspend()
The user has pressed the power button again, and operation has resumed.

virtual void OnLowBattery()
The battery level is becoming dangerously low.  The amount of time left until automatic suspension is somewhat indeterminate.

virtual void OnJobChanged()
The current job has been opened or closed.  Changes to data within the job do not raise this event (see tsc_IDatabaseMonitor).

virtual void OnStakeoutListChanged()
The stakeout list, as stored in the database, has changed.

virtual void OnLinkedFilesChanged()
A file has been linked or unlinked from the current job.

virtual void OnStationOffsetReferenceEntityChanged()
A station/offset is a coordinate which is defined by a distance along (i.e. the stationing), and a perpendicular distance offset from, a reference entity such as a line, arc, or road alignment. When the reference entity is changed in some way, the station/offset's position may also change.  This event signifies such an occurrence.

virtual void OnFilesystemNearlyFull()
The file system is close to full, perhaps only a few tens of KB remain.  This event is generally raised only once but multiples are posible. Survey Core will also alert the user; there is no need for the plugin to display anything.

virtual void OnFilesystemFull()
A write to a file (any file) has failed because the filesystem is full.  Survey Core will also alert the user; there is no need for the plugin to display anything.

virtual void OnInternetConnected()
A working connection to the internet has been established.  This includes global DNS service and general connectivity.

virtual void OnInternetDisconnected()
The connection to the internet has been lost.

virtual void OnDialupConnected()
A dial-up connection has been established.  This typically means a connection to a modem (such as a cellphone) but not necessarily a full internet connection.  OnInternetConnected should occur soon after this event.

virtual void OnDialupDisconnected()
The dial-up connection has been lost.

virtual void OnUserLoginChanged()
A user has logged in or out.

virtual void OnSensorStateChanged()
There has been a state change with a sensor.  This means a survey or station setup has been started, completed, or ended, or the currently selected instrument (total station, GNSS receiver) has been switched to another instrument.  Use your UITask instrument to determine if the change might affect you.

virtual void OnMapSelectionChanged()
The user has selected or deselected one or more items on the map.

virtual void OnActiveMapUpdated()
The active map selection has changed.

virtual void OnBackgroundMapSelectionChanged()
A background map file has been selected or deselected on the current job.

Monitored events example

This example uses the tsc_IScAppMonitor interface which (among other things) has an OnJobChanged event, which fires when the user opens, creates, or closes the current job in Survey Core.  Our example displays an entirely useless dialog that says what just happened.

Everything else, including code to make the form itself actually work, has been omitted for clarity.  Note that the call to Start has been qualified by the interface name; this is necessary when there are two or more monitor interfaces with the same Start and Stop method names, and this syntax should be used always.

class myForm : public tsc_Form, tsc_IScAppMonitor 

{

     myForm ()

     {

         tsc_IScAppMonitor::Start();

     }

     void OnJobChanged()

     {

         tsc_Job job = tsc_Job::CurrentJob();

         if (job.IsOpen())

         {

             tsc_MessageBox::Show (job.Name(), "Job has just been opened.");

         }

         else

         {

             tsc_MessageBox::Show ("NoJob", "Job has just been closed.");

         }

     }

};