Converting SCAPI projects to version 4 of the SDK

This page describes updating a plugin from a pre-4.00 version of SCAPI. If you are starting afresh, go to this page instead.

Getting started, creating a new project for SCAPI v4.00+ (incl version 18.20 and beyond)

This guide has been updated to the 2019.00 version of Trimble Access. This is SCAPI version 19.00 released in May 2019, built using Visual Studio 2019 and in a 64-bit configuration. 

• 1. Install software if not already done:

     • Install Visual Studio 2015 2017. The 64-bit version is preferable, but the 32-bit one also works.  Trimble Access is still a 32-bit now a 64-bit app so plugins must also be built as 32-bit 64-bit.

     • Install the latest Trimble Access (Version 4.00 19.00 or above) using Trimble Installation Manager (download). 

     • Make sure you tick the Survey Core API item; if it doesn't appear then there is probably a problem with your license and you should contact Trimble.

  2. Start a new project:

     • Create a new SCAPI project in a new solution using the Visual Studio 2015 2017 New project wizard.

     • (File -> New -> Project, Templates -> Other languages -> Visual C++ -> Trimble Access SDK v19.00 -> Trimble Access Plugin Application).

     • Take care choosing the project name - preferably use the previous plugin (DLL) name or something very similar. This becomes the DLL and application name and is difficult to change later.

     • Familiarise yourself with the new property sheet (scapi.props) and adjust the values as required, either in a text or xml editor or (preferably) in the Visual Studio Properties Manager window.

• • Important: Replace the generated GUID in the property sheet with the GUID from the old version. All Trimble Access services will then recognise this as the same application as before.

• 1. At this point it should be possible to do a test build of the plugin with its default Hello World form:

     • A release build will produce two installer (.exe) files in the project directory.

     • You should be able to install the plugin by running the emulator installer exe, start up Trimble Access 2018.00 (or higher) and get the Hello World form to appear.

  2. Add the old project's source files to the version 4 project:

     • See below for notes about moving image resources.

     • See below for notes about moving and updating source code.

Images and other resources

The resource DLLs are no longer used; images and other files are now resources in the plugin DLL. The largest images, generally those from the 1024x600 DLL, can simply be copied across and used in the new solution.

The new UI will resize images on the fly to the size required. Note that icons, buttons, etc should preferably be about 256 x 256 pixel png files with transparent backgrounds. Smaller images (say 96 x 96) will work on many devices, but quality may suffer on large screens. There is no requirement for sets of images (up, down, selected, disabled, etc) for buttons, just a single PNG image with a transparent background.

The API still using the same Windows-style IDB_imagename (resource.h/resource.rc) system, so names and source code should not need to be changed.

• • Copy Resources.h from the old "master" resources project, typically the 1024x600 or the largest available, to replace the resources.h that was generated.

    • You might need to add IDB_Application back in.

  • The new .rc2 file that was created by the project wizard should already be correct. DO NOT EDIT THE VERSION NUMBER FIELDS, they are macros which are substituted at build time from the properties sheet scapi.props.

  • The old 1024x600 project's resource (.rc) file must be merged by hand into the new TargetName.rc in a text editor. 

  • By default Visual Studio will open a resource editor for a .rc2 file. Don't use this; instead open the .rc files using As code or Text editor or View code, depending on how you open the file.

  • Move only the resource definitions, and put them just after the IDB_Application image definition that's in the default .rc file.

  • Note that the plugin dll version and other properties are in a separate .rc2 file (which should not need to be edited).

  • In all other respects the .rc file is the same.

  • The paths to image files in TargetName.rc should still be correct if you keep whatever folder structure was used for the images in the old resources project. 

• We recommend that images are placed in a subdirectory of the project if there are more than a few.

  • Copy the largest (usually 1024x600) images from the old resources project into the folder chosen for images. 

  • A TargetName.png file is required in the project directory for displaying an image on the button in the Trimble Access application chooser. On the customer's device, this file is installed beside the DLL. A default file will have been created in the project directory by the project wizard, and this must be replaced by an appropriate image.

  • Also, an icon (.ico) file is required for the installer, called TargetName.ico with a 96 x 96 icon, or larger. Likewise, this icon should be replaced by something less generic.

Source code

Copy the old source files into the new project directory, and add them to the project as existing files.  There are some things to note:

• • Only the initialisation and UI classes have changed. Everything else is the same - surveying, instruments, coordinate systems, database, etc.

  • The old module containing the tsc_AppMainWindow subclass (usually MainWindow.h/.cpp) will need to be rewritten to use the new MainWindow module, which is now derived from tsc_AppMainMenu.

  • The tsc_Application module (Application.h/.cpp) can just be copied across, with one small change to create a tsc_AppMainMenu subclass rather than a tsc_AppMainWindow subclass.

  • Most other source files can simply be copied across and should build without change, though a number of deprecated warnings are likely.

  • Some form layout methods have changed and may require changes in your code. The new form system is better at automatic layouts, which unfortunately makes it harder to control for custom layouts.

  • There are some changes to the tsc_JobMap. In particular, the tsc_Image used to draw on the map will need to be resized if the window size changes.

Installer

Unless additional files need installing, the installer (.nsi files) will be close to the final requirement.  Most information is now passed in from the property sheet so editing the .nsi files is often unnecessary.

Operation of the NSIS script is otherwise much the same as before.

If you have special requirements for plugin installation, then the changes made to the old NSIS scripts will need to be moved to the new scripts.