tsc_TsVideoForm

When a compatible instrument is attached, the user's application is active, and the Video form is running in that application then your application's attached tsc_TsVideoForm will be called to extend the Video form's behaviour.

There is only one active tsc_TsVideoForm allowed per application with the tsc_TsVideoForm only affecting the display within its own application.

To use this class it must be subclassed and event handler functions overidden as appropriate.  The best place to instantiate the tsc_TsVideoForm subclass is in the plugin's tsc_AppMainWindow subclass as your attached subclass may be called upon to work on behalf of the Video form at any time.

Processing Video events

Video events are raised by Survey Core calling an event handler in the tsc_TsVideoForm subclass.  Because these events will prevent the video from performing any further processing while the are being handled by the plugin, it is important for event handlers to process the event quickly and return.  Performing any action which may cause a wait or UI (such as a form) will prevent the video from continuing and it may become unresponsive (in particular if you are debugging you may lose the instrument connection).

If it is necessary to perform lengthy operations or interact with the user, then a UITask or a thread should be launched to deal with this.

Most event handlers allow the default action to be overwritten.  In general, if the default action has been prevented, then some kind of indication should be given to the user to show that the action has been processed.

Unlike tsc_Forms these event overrides should respond (where appropriate) with true when the video form can continue processing as it would normally.  Return false to indicate that the plugin has handled this event.

The total station video task runs within its own thread environment, and event handlers will be called on the video thread.  This means that an event handler can not interact with a form or other UI objects in any other UiTask.  Other objects (such as tsc_Image) are generally thread-safe, since Survey Core will serialize access to them.  Take care with objects shared between the tsc_TsVideoForm event handlers and other event handlers in the plugin, since a thread switch could occur at any point.  Vulnerable objects should be protected using a tsc_Lock, but be careful to avoid locked sections of code that span any kind of wait or long-running operation.

Public Methods

tsc_TsVideoForm();
Constructs the object.  The constructor does very little; the class only becomes active after AttachToVideo() is called.

void AttachToVideo ();
Attaches this instance to the current Survey Core TS video form. Subsequently, any time the user interacts with the video form within this plugin's application the event handlers in this class instance will be called. The class is only active while the plugin is the current application.  If the user switches to another application such as General Survey or another plugin, that application becomes the controller for the video until such time as the user switches back.  During the time that another application is current, no events will be raised.

If another instance of tsc_TsVideoForm within the same plugin subsequently calls AttachToVideo, then the previous caller is detached.  There is no interaction between different plugins; only the current application interacts with the video form at a given time, even when multiple plugins are active and attached to the form.

void DetachFromVideo ();
Detaches this plugin from the video.  This method will apply to any subclass instance of tsc_TsVideoForm that called AttachToVideo() within the plugin, but does not affect other applications or plugins.  If no instance is attached to the video form, this call does nothing.

virtual void OnVideoOpened();
Called when the video window is started.  If you attach to an already open video form this event will not occur.

virtual void OnVideoClosed();
Called when the video is closed. Note this is not called when detaching from the video form or when the video form loses focus.

virtual void RequestVideoClose();
Request that the Video UITask be shut down.

bool VideoIsOnTop();
Call to see if the video window is at the front as the active UI Task.

void InvalidateTitle();
Ask the video form to regenerate the window title.

virtual tsc_String OnDrawVideoTitle(const tsc_String& suggestedTitle);
Override the video title with text of your own - it is suggested that you keep the Video text as a prefix as this is how the Video UI is named in other parts of SurveyCore (e.g. switch to).

void InvalidateEnterSoftkeyText();
Ask the video to regenerate the enter softkey text.

virtual x_Code OnEnterSoftkeyText (x_Code suggestedEnterKeyText);
This event handler is called to determine the video form's Enter softkey x_Code.  Either return the suggested x_Code or an x_Code of your own choice.

Note that the x_Code will likely change the behaviour of the video form's default response to the enter key,  you may wish to override OnEnterSoftkey as well..

bool OnEnterSoftkey (x_Code enterKeyText);
This event handler is called when the video form's Enter softkey has been pressed by the user.  Respond to the press by one of the following:

• • Return true to allow the video form to continue and process the button press as normal.

  • Launch a UiTask to handle the button press, and return false.  The Uitask may perform UI.

  • Perform some other processing that does not involve long waits or UI.

The enterKeyText parameter contains the x-code of the text that was shown on the Enter key when it was pressed, and therefore indicates what action the user might be expecting from the enter key.