tsc_SurveyCore

Overview

This class provides access to core functionality such as registering the plugin, registering new tasks, controlling menus, launching of user tasks, access to language translations, and other methods that don't fit anywhere else.

There is only one static instance of this class, and all functions are static.

Registering a plugin as an application

Note: If a plugin project is created using the Visual Studio Trimble project wizard, the application registration code described below is created automatically. This section is more of a guide to how it works and how to modify it.

Registering the plugin as an application is mandatory and the plugin must supply its own main menu at this time. Registration as an application has the following effects:

• • The application may be licensed and/or sold through the Trimble online store.

  • The application can be launched by Trimble Access with a selection on the Application Picker form, or at startup.

  • The plugin's main menu becomes available to the user.

bool RegisterApplication (tsc_Application* application);
Call RegisterApplication during initialisation to register the application. The plugin's licence GUID, which was supplied during plugin registration, is used to locate the application's license in the licensing system, and users who have a license for the plugin will get the opportunity to install it.  

The application parameter must be a heap-allocated instance of your application's subclass of tsc_Application.  The instance will be automatically freed during shutdown (or immediately if registration fails).

Note that as of v2.30 a licensing failure is not regarded as a registration failure.

For example:

extern void tsc_InitializePlugin ()

{

    if (tsc_SurveyCore::RegisterApplication (new MyApplication))

    {

        // Other initialization code here.

    }

} 

A plugin application can also be launched directly by a command line containing the plugin's licence GUID such as:

survey.exe app=FDDF92D1-0BE1-4890-809E-9A45E12D8E90

See the section Plugin registration and initialisation for details about the GUID.

Shutting down the plugin

When the Survey Core application is being shut down, each plugin is given the opportunity to clean up as part of the process.  If required, the plugin may export a shutdown function for this purpose.  Note that most Survey Core services have been shut down by the time this handler is called; it should be regarded as a last-chance opportunity to clean up before exiting.  Use form OnClose handlers wherever possible to deal with cleaning up.  This method must be defined or a linker error will occur; define an empty function if no finalization is required.

extern void tsc_FinalizePlugin ()
{
// finalization code here.
}

Translations and x_Codes

The Survey Core language translation system uses tokens to identify translatable strings.  Every string that requires translation is held in a database in a number of different languages, and is addressed by its token name.  Internally, we equate token names with an enum (that is, an integer) identifier known as an x_Code.  Any of the several thousand predefined Survey Core strings which have already been translated into many languages may be used, and an additional custom translation database should also be supplied with the plugin.

x_Codes are used for a number of purposes in addition to obtaining translated strings.  For instance they make convenient identifiers - a button uses an x_Code to display the translated text string as required on the button, but also reports the same x_Code in an event when the button is pressed.

To obtain the string translated to the current language for a given x_Code, the Translate function is used:

static tsc_String  Translate  (x_Code token) const;
A plugin should supply its own database of x_Codes by specifying a tdb file to be used.

static x_Code AddXCode (const char* string);
To programatically add an x-code/string pair, use the AddXCode function.  A new x_Code is assigned to the string and returned.  If an identical string has already been added, the same code is returned again.  This string is not translated; the text that was supplied is the text that will be returned by translate regardless of language settings.  The x_Code only lasts until Survey Core is shut down, and the same call may return a different value of x-code next time SC is run.  While there are situations where AddXCode's use is necessary, try to avoid use of this method, as the number of unique strings allowed in calls to AddXCode is strictly limited; to include custom strings, use a Survey Core translation database (TDB) file instead.

User interface tasks (tsc_UITask)

UITask is a key Survey Core class which encapsulates the idea of one task that the user may perform, such as starting a survey, keying in a point, displaying the map, checking the current satellites, and so forth.  Survey Core has about 270 predefined UItasks that may be run from a menu or started programatically.  A UITask is identified by a special x_Code, known as a runCode.  RunCodes are generally the same as the text which appears on the menu item for the task, though they may be different if required.  Any x_Code can be a runCode, provided it is used to identify one task only.

In the plugin environment, the SC UITask is represented by the tsc_UITask class.

static bool Launch (x_Code runCode);
To launch a UI task programatically, use this function.   If a task of the same runCode is already running, it will be brought to the front.  The runCode may be either a standard Survey Core run code or the run code of a UITask defined in the plugin.  It blocks until the new task has started running, and returns true on success or false on failure (uncommon).

static bool TerminateAndRelaunch (x_Code runCode);
To replace a UI task programatically, use this function.   If a task of the same runCode is already running, the running task is terminated and a new task created.  Avoid using this method wherever possible, it will terminate the running task with little or no warning to the user, and valuable work could be lost if used inappropriately.    It blocks until the task is running again and returns whether the launch was successful.

static bool RegisterUITask (x_Code runCode, tsc_CreateUITaskInstance* createFunction);
Use this function to register a new tsc_UITask.
A very common requirement for a plugin is to implement its own UI tasks. To do this, the tsc_UITask class is subclassed and the task is implemented in the Run function.  For details, see the tsc_UITask section.  When a task subclass has been implemented, it must be registered with Survey Core so it may be run when requested. 
Once the UITask is registered, it may then be added to a menu for the user to run, or launched programatically.

The createFunction parameter is a function that returns a new instance of the desired tsc_UITask subclass.  The function has the following signature:

typedef class tsc_UITaskNative* tsc_CreateUITaskInstance (int scTaskId);

Notes regarding UiTask creation

1. The createFunction may be called often from Survey Core - every time a menu with the task item on it is displayed - so do not put any significant work in the constructor of your tsc_UITask subclass, or there will be a delay before the menu pops up.

2. The RegisterUITask call will fail and return false if another UITask already exists for this RunCode.

3. tsc_UITaskNative is the base class for tsc_UITask, so your subclass pointer can be returned from the createFunction method without casting.

Custom Favorites and Switch-to Items

static bool AddUITaskToFavoritesMenu     (x_Code runCode);
static bool RemoveUITaskFromFavoritesMenu(x_Code runCode);
static bool AddUITaskToSwitchToMenu      (x_Code runCode);
static bool RemoveUITaskFromSwitchToMenu (x_Code runCode);

Once an application and UITasks have been registered, UITasks may also be added to the Switch to and Favorites lists for the application.

A return value of false indicates that either the application or the task was not registered - or in the case of remove that the list does not contain the item.  An item may be added more than once but only one copy will be kept.  

Note that the Switch to page is dynamic and automatically shows all currently running UI tasks and it will not generally be necessary to add specific items to it.  

The Favorites menu is persistent; the user manually adds and removes items to customise this menu and it can be annoying to have it changed by the application.  Changes should preferably be restricted to adding new items the first time the plugin is run.

Time

static double LinearTime();
Gets a constantly increasing tick count.
A clock such as the Windows ticker which increments once per millisecond is limited to 22 days before it overflows when implemented as a 32-bit integer as in the .NET compact framework.  It is a convention within Survey Core to instead use a double representing seconds.  A double is independent of clock resolution and never overflows (at least, not in the lifetime of this universe).   This function returns the time in seconds and fractions of a second generally since the last boot-up or TA startup, and is guaranteed to always increase at the same rate if the current date or time is changed. It may stop incrementing while the device is suspended.  The resolution is typically around 1 millisecond, but this depends to some extent upon the OS and the device.

The following methods provide the current date and time of day as a number of seconds since some distant past date.  The resolution is dependent on the OS and hardware platform. The returned value is suitable for use in date and time fields on forms and in other API structures that store the date and/or time as a double, and is compatible with tsc_DateTime.  See tsc_DateTime for more details on the double time value.

static double UTCTime();
Gets the current UTC date and time.

static double LocalTime();
Gets the current date and time adjusted to the local time zone, according to the zone set in the device's operating system.

Logging

Messages may be written to the Survey Core log using these functions.  Each call adds one line, prepended by the time and thread number.  If a value is provided, it is converted to a string and output following the message.  The log file is called "sc.log" and can be found in the Trimble Data\System files directory.

static void Log    (const char* message);
static void Log    (const char* message, const char* string);
static void Log    (const char* message, int value);
static void Log    (const char* message, unsigned int value);
static void Log    (const char* message, long value);
static void Log    (const char* message, unsigned long value);
static void Log    (const char* message, double value);
static void LogHex (const char* message, const void* data, int length);

Status message area

The message area is shown on all screens and may be used to display informational messages for a short period of time.  Display time is measured in cycles of 400mSec; a message is displayed for the given number of cycles and it may be interleaved with other messages which are also displaying at the time.  If the value string is supplied, it is appended to the translated message text.

static void StatusMessage (x_Code message, int cyclesOf400ms = 1);
static void StatusMessage (x_Code message, const char* value, int cyclesOf400ms = 1);

Some SurveyCore X_Codes also trigger sounds events when given to the status line by StatusMessage.  The x_Codes that trigger sound events are listed below and may not be available in some languages. The list is under constant revision and may be outdated.

 Voiced status messages

Some SurveyCore X_Codes also trigger sounds events when given to the status line by StatusMessage.  The x_Codes that trigger sound events are listed below and are only available in some languages.

Threads

Also see: tsc_MonitorThread,  tsc_Thread,  tsc_QuickTask.

void Sleep (double seconds);
The current thread can be slept for a given period of time with this function.  During the sleep the message queue continues to be processed and UI remains responsive.  Avoid using the Windows API Sleep function, which will lock up the thread's UI and message processing until it completes.

bool DoEvents();
When performing large amounts of processing the UI can become unresponsive and (for example) a cancel button used to abort the processing won't respond when pressed.  To avoid this problem, call DoEvents() periodically during the processing.  This should be done either after a certain number of operations, or after some length of time (e.g. every 0.25 seconds works well).  DoEvents will immediately process any queued messages and then return.  It returns true unless a Survey Core shutdown is in progress.  If false is returned, any long-running processing should be exited if possible.

Hardware determination

static tsc_String SerialNumber();
Retrieves the serial number of the device your are currently running on.  This serial number will match the number that Trimble Access Installation Manager uses.  Note that the format can be very different across platforms.

static tsc_Hardware Hardware();
Returns the hardware platform.
Survey Core can run on an increasingly large number of different Trimble and third-party hardware platforms.  This function indicates which platform the current instance is running on.  Note that this is a runtime check; there are no compile-time macros apart from PLATFORM_WINDOWS and PLATFORM_ANDROID.

The tsc_Hardware enumeration is defined as follows (and may be regularly updated while this documentation falls behind). Old discontinued platforms remain in the list mostly out of nostalgia.

enum tsc_Hardware
{
    Hw_Undefined        = 0,
    Hw_Desktop          = 10,  // Otherwise known as the "Emulator", SC running on a PC.
    Hw_Tablet           = 20,  // Trimble Tablet.
    Hw_Tablet2          = 21,  // Trimble Tablet 2.
    Hw_Tablet3rdParty   = 22,  // Non-Trimble tablet or laptop
    Hw_TabletT10        = 23,  // Trimble T10 tablet
    Hw_Recon            = 30,  // Trimble Recon - NOTE: Plugins are not supported.
    Hw_TCU              = 40,  // TCU 1 (Original, detachable, WinCE 5.0) Not Supported.
    Hw_TCU2             = 41,  // TCU 2 (With ROHS and WinCE 5.0) Not supported.
    Hw_TCU3             = 42,  // TCU 3 (Model 3 like S3, WinCE 6.0)
    Hw_TSC2             = 50,  // Trimble TSC2 brick.
    Hw_TSC3             = 51,  // Trimble TSC3 brick.
    Hw_TSC7             = 52,  // Trimble TSC7 brick/tablet
    Hw_T7               = 53,  // Trimble T7 tablet
    Hw_M3_3             = 60,  // Trimble M3 model 3 attached CU. Not supported.
    Hw_S3CU             = 61,  // Non-robotic Trimble S3 permanently attached CU.
    Hw_C5               = 62,  // Trimble C5 perm attached CU. Not supported.
    Hw_GeoXR            = 70,  // GeoXR device (portrait form factor).
    Hw_Slate            = 80,  // Slate CE device (portrait form factor).
    Hw_TDC600           = 100, // Trimble Android controller.
    Hw_TCU5             = 110, // Trimble Android control unit.
    Hw_TSC5             = 120  // Trimble Android controller.
};

Operating System determination

The host operating system can be determined by this function and corresponding enum:

static tsc_OS OperatingSystem ();

enum tsc_OS
{
    Os_Undefined = 0,
    Os_WinCE     = 10,
    Os_Desktop   = 20,
    Os_Android   = 30
};

There are a number of compile-time macros that can be used to determine the operating system.  Of course these are dependent on your project properties in MSVC but the following two are defined by default:

#define PLATFORM_WINDOWS 1
#define PLATFORM_ANDROID 1
One of these will be defined as 1, the other as 0. The meaning is "any form of Windows", or "any form of Android". 

_WIN32
_WIN64  
One or the other of these is defined within Trimble Access, but they are not necessarily defined in plugin projects. The surest way is to open the plugin's project properties for the various build configurations and examine the C++ preprocessor defines. Custom defines can be added if required.

Screen type

Orientation

static tsc_DisplayOrientation DisplayOrientation();
This method returns the display orientation.  On some hardware models this is fixed by the model and is not a dynamic property. For others including Android it can change if the device is rotated.

enum tsc_DisplayOrientation
{
    Disp_Undefined = 0,
    Disp_Landscape = 1, // Landscape, display is wider than high.
    Disp_Portrait  = 2, // Portrait, display is higher than wide.
};

Pixel size of windows

The size, in pixels, of one of the standard-sized windows for the current hardware and OS can be obtained by this function.

The returned tsc_Size contains two public properties, Width and Height.  Note that this is not reliable for detecting landscape and portrait displays as the SurveyCore window layout changes - please use DisplayOrientation for this purpose.

static tsc_Size WindowSize (tsc_WindowSizeMode sizing);

Plugin Location

static tsc_String DllPath ();
The full path to the currently running plugin DLL.
This function is deprecated. See tsc_Path for alternatives.