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.

One variation allows a plugin to be License-free. Such a plugin is created in the usual way, but with a special license name that can be obtained from your Trimble representative. No license is required to install and run the plugin, and if such a plugin is uploaded to the plugin store, any customer with a normal TA license will be able to install and use it. The plugin will also be able to be manually installed on any device (that is, by any method other than installing with TIM).

To use the tsc_Application 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.  To use your tsc_Application subclass, an instance of it must be allocated on the heap using new, and passed into 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 the tsc_AppMainMenu subclass that you have defined to create your main menu items. The pointer must have been heap-allocated with new, and should not be deleted, 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 (typically, this occurs automatically when the project is created from the MSVC project template) and must 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 GetProductGuid is 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 it is not possible for this function to be called 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. The returned string should be identical (or at least very similar) to the value in the .timxml file to avoid user 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;
Provide the product EULA in the returned string, or a document path.  If the returned string is empty (""),no EULA is shown. Otherwise it will be displayed to the user, who must acknowledge that it has been read.  If the user fails to acknowledge reading the EULA, the plugin will be unloaded and cannot be used, until Trimble Access is restarted and the EULA is accepted.

The string returned may be in either of two formats:

• Plain text: Lines are delimited by any valid newline characters. No formatting other than line breaks is supported, and the text is displayed as supplied. UTF-8 encoding is used by Scapi, and valid Unicode characters may be included. This is the only method supported before TA 2024.10.

• HTML: Starting with version 2024.10, an html file may be displayed by supplying one or more file paths without line breaks which identifies this as a file path, and not EULA txt.

  •  The full HTML-5 standard is supported. The file encoding used should be UTF-8.

  • Trimble Access path macros are permitted in the path, and if it is not absolute then it is relative to the Resources directory which, by default, is the same as the directory containing the .dll or .so file.

  • Multiple paths may be supplied, separated by semi-colons. The additional paths can be used as a fall-back to display the EULA in other languages if the preceding files do not exist.

  • When supplying a file path, a useful macro is $(IsoLanguage) which allows multi-language Eulas to be supported and to display the currently selected language. 

Example:

tsc_String Application::GetProductEula() const

{

    tsc_String text = tsc_File::ReadAllText("$(PluginResDir)/MyPlugin_Eula.txt"); 

    if (text.IsEmpty())

    {

        text = tsc_SurveyCore::Translate(X_ErrorEulaNotAvailable);

    }

    return text;

}

-- or --

tsc_String Application::GetProductEula() const

{

return tsc_String{"EulaText_$(IsoLanguage).html;EulaText_en.html"};

}

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).  The icon should be square and sized between 96 x 96 and 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.

Note that the following methods have largely been made obsolete by recent UI changes in Trimble Access.

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. This function has very little effect now, since TA no longer runs with no job opened.

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 may 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.