tsc_Application

This class is used if the plugin wishes to appear as a Trimble Access Segmented Application.  This means that it can be launched from the Trimble Access menu system as though it were an autonomous application.  Being an application also allows the plugin to be licensed through the Trimble Access licensing system and purchased in Trimble's online store, provided certain conditions are met.

Currently, this is the only supported type of Scapi application.

To use this class, make a subclass of it and implement the pure virtual functions.  Each function's return value allows control over some aspect of the application's operation, as detailed below.  An instance of the subclass must be allocated on the heap using new, and passed into a call to RegisterApplication in the tsc_SurveyCore class.  SurveyCore will take ownership of the application memory, and will delete the memory when appropriate.

On Windows, the application may then be launched (handy for debugging and testing) with the command -
survey.exe app=<guid>
where <guid> is the value that was specified on the application's custom property page in Visual Studio.  This GUID is supplied to the plugin loader through the application's .timxml file which is in the same directory as the plugin library (.dll or .so).  Under normal circumstances with a Trimble Access customer running the application, the Core program will be started and the user will then select the application from the application chooser screen.

The only time the two GUIDs may be different is when more than one application is hosted within one plugin.  All GUIDs must be valid and licensed, except when the plugin is being run on a computer or other device which has a valid SDK (developer) license.

Member functions

These function overrides determine how the application behaves.  The values to be returned will typically be constant.

The tsc_Application class must supply a Main Menu to be displayed when the application starts. Override and implement this function to supply such a class.  The instance must be allocated on the heap. See tsc_AppMainMenu for details.  Be aware that this instance is retained and used for multiple SCAPI application starts and stops within the lifespan of the host process.

virtual class tsc_AppMainWindow* MakeMainMenu () const = 0;
The tsc_Application class must supply a Main Window to be displayed when the host application starts. Override and implement this function to supply such a class.  The instance must be allocated on the heap. See tsc_AppMainWindow for details.  Be aware that this instance is retained and could be used for multiple SCAPI application starts and stops within the lifespan of the host process.

virtual class tsc_AppMainWindow* MakeMainWindow () const {return NULL;}
Deprecated at version 4.00. Override MakeMainMenu instead.

virtual class tsc_AppMainMenu* MakeMainMenu () const;
Override this method with a function that returns a pointer to a tsc_AppMainMenu subclass. The pointer must have been heap-allocated with new. viz:

     virtual tsc_AppMainMenu* MakeMainMenu() const

     {

         return new MyMainMenu();

     }

virtual tsc_String GetProductGuid () const;
GetProductGuid only needs to be overridden when a single plugin is hosting multiple applications. In this case, make and register a tsc_Application for each app, and return a hyphenated GUID representing the license and identification of the application - this should be grouped by hyphens in the usual Microsoft manner.  This guid must also be known to the both the licensing system and specified correctly in the installer configuration files.  The GUID should be generated once (eg, from the MSVC tools menu) and remain unchanged. The GUID's main purpose is for licensing the plugin for purchase by end users, and the only reason to change it would be if new licensing conditions applied.  If not overridden, the product GUID is obtained from the application.timxml file when the plugin is loaded.

virtual tsc_String GetProductName () const = 0;
Return a full product name from this function.  It appears in a variety of places, primarily at the top of the splash screen but also in licensing error messages, some file export formats, etc. Because this function is not available during builds, installation, and startup, the ProductName element in the .timxml file is used instead, which is generally a single word written in one language. It should be identical (or at least very similar) to the value in the .timxml file to avoid confusion.

virtual tsc_String GetProductDescription () const = 0;
Return a brief description of the product about 5-20 words long, preferably translated. Appears on the Splash screen.

virtual tsc_String GetProductSupportString () const = 0;
Return a support contact (e.g. phone number, company name or website). Appears on the Splash screen.

virtual tsc_String GetProductEula () const = 0;
Return a product EULA.  If the returned string is not empty (""), it will be shown to the user, who must acknowledge that it's been read.  If the user fails to acknowledge reading the EULA, the plugin will be unloaded and cannot be used.

virtual int GetProductIcon () const; Deprecated: use GetProductImage instead.
virtual tsc_Image GetProductImage() const;
Override this function to provide an image for display in places such as the splash screen.

The image should be a PNG file or resource (at least 8-bit depth, with transparency).  Suggested icon size is at least 96 x 96, and not bigger than 256 x 256.

virtual bool ShowSplashScreen () const = 0;
Return true to indicate that a splash screen (based on your product data such as Product name, description, etc) should be displayed when starting your application.

Trimble supplies the image used to generate the splash screen background. It is about 1280 x 800 pixels, and will be resized to fit the actual window.

virtual bool IsAutoConnectRequired () const = 0;
Trimble Access automatically attempts to locate and connect to any instrument it can find, whether connected by radio, bluetooth, wifi, serial port, USB port, or any other way an instrument can connect.  If the plugin uses an instrument in any way, return true from this function.  Return false only if the plugin is instrument-independent, such as a plugin that only exports files.  Returning false means that Survey Core will not try to autoconnect to instruments while this application runs.

virtual bool IsOpenJobRequired () const = 0;
If the plugin makes use of the current job in any way, return true from this function.  This means that upon launch Survey Core will open any last-used job for the user, and also save the current job's name at shutdown.

virtual bool HasInstrumentInteraction () const = 0;
Trimble Access watches the "Trimble" key on the keyboard of some devices - in particular the mobile devices such as the TSC7.  A short press returns focus to the launcher, and a long press will display either the Trimble Functions dialog for Total Station control, or the GNSS Functions dialog for GNSS receiver control, depending on the connected instrument type.  This member function controls whether the Trimble key will cause this to occur or not; return true if a long press should display the functions dialog.

virtual bool OnCloseConfirm () const = 0;
When Survey Core is shut down, either by program request or by the user hitting the X button, a warning dialog may be displayed.  This function should return false to prevent this dialog from being displayed at all (the application just closes), or it may return true which allows the dialog to be shown.  The name of the application will be displayed as part of the dialog message.