Changes required for version 20.10

Upgrading to v20.10 and beyond

Version 20.10 of Trimble Access supports the Android platform for Scapi plugins. This has necessitated some changes to the SDK and in order to keep development similar for both Windows and Android we have made a few changes to the Windows Scapi SDK. Plugins built using the Trimble Access v19.xx or 20.xx SDK for Windows are binary-compatible with version 20.10, provided there is no use of the Windows GDI+ API.

There are two primary areas of change for Windows development:

• • Android cannot use the Windows graphics methods (GDI+), so all graphics are now handled by the Qt framework. All GDI+ code must be replaced or removed. tsc_Image has new methods to help with this.

  • All resources are now distributed as separate files, rather than as binary blobs in a resource or the plugin DLL. Resources are referred to as Assets in Android installations.

  • Most plugins built with v19.xx and v20.01 SDK will continue to work. (v20.00 has a stability issue, please don't use it).

And some other things to note:

• The development environment has changed to use Microsoft Visual Studio 2022.

  • A number of new methods have been added to the tsc_Image class which allow paths to be created, stroked, and filled, and with the existing methods for drawing text and images upon other images, most basic graphics requirements should be covered.

By making these changes for Windows, a plugin will become very close to the state required to run on Android. 

Version 19.xx and 20.01 compatibility on Windows

To allow plugins built with an older SDK (19.xx and 20.01) to continue working:

• • We have added a warning dialog if a plugin attempts to obtain an HDC from a tsc_Image. Plugins doing this may crash since a call to GetHDC() will now always return a null value.

  • All resource files in the plugin or resource DLL will be extracted to a temporary folder in the user's AppData area so they can be accessed by the new resource system.

  • The version 19.xx/20.01 SDK can still be used to develop plugins, provided GetHDC() is never called.

  • To use the new graphics methods in tsc_Image, it will be necessary to upgrade your plugin to version 20.10 (or later).

Upgrading existing Windows plugins v20.10

The required changes to source code are essentially the same as those for Android; plugins should mostly work in both environments without #if's, except for plugins making use of the Windows API. There are also a few changes required in the build.

1. The path macro $(PluginDllDir) is obsolete. If used, it will return the directory containing the timxml file, not the dll directory, though the two are often the same.

   1. The path macro $(PluginResDir) is the replacement and also returns the timxml directory. This is the root location of the resource files (and of the Android Assets).

   2. Remove the resource file lines from the .rc file. Keep the .rc and .rc2 files because they are still needed to supply the plugin's version number. 

   3. Windows plugins may still use .rc file resources, but must use the Windows API to access them. We suggest converting them to discrete files as described.

   4. Add the files from the .rc file into the tsc_InitializePlugin() function (call RegisterAssets as in the example below). Paths must match the installation, relative to the .timxml file's directory.

   5. Change the installer build to include all resource files individually into the installation, and install them in the same directory as the .timxml file, or a directory inside it.

   6. In the Windows MSVC project C++ preprocessor properties, add the macro PLATFORM_WINDOWS=1 to both release and debug configurations.

   7. Drawing of graphics must be changed to use the new tsc_Image methods.

   8. If the new and existing graphics functions supplied in tsc_Image are insufficient then Qt must be installed and QPainter used to draw on images. For development using Qt, see Using QImage & QPainter, in the Android section.

Example of tsc_InitializePlugin function

Example of code to be added to existing tsc_InitializePlugin function (use the same code for both Windows and Android):

extern void tsc_InitializePlugin ()

{

    tsc_SurveyCore::RegisterApplication (...);

    tsc_SurveyCore::RegisterUITask (...);

    ...

    tsc_SurveyCore::RegisterAssets (

    {

        {IDB_FolderIcon, "FolderPic.png"},

        {IDB_Pencil, "Pencil.png"},

        {IDF_TemplateXml, "CustomDataTemplate.xml"}

    });

}