Version 4.00 breaking changes

API Changes

Quick link: Converting a SCAPI project to the version 4 or higher SDK.

Note: Trimble Access and Survey Core have become almost synonymous, so from TA 2018.20 the version of Survey Core will match the last 4 digits of TA. So, version 2018.20 of TA will contain version 18.20 of Survey Core (Survey.exe).  Because the version number continues to increase, there is nothing special that needs to be done to deal with this.

Further note: From version 19.00 (May 2019) we are building a 64-bit application. This has not had a great effect upon development, except of course, plugins must also be built in an x64 configuration. Visual Studio 2017 should be used for these builds.

Survey Core is now using QT for its GUI framework, providing an enhanced user experience. Many visual aspects of the UI have changed, however the underlying principles remain much the same. These changes have caused a number of flow-on effects for plugins to deal with. In summary:

• • The main window is a more conventional window than previously, with the usual minimize, maximize, and close buttons.

  • On many platforms the window can be resized (ie, by dragging an edge or corner),  and in the case of mobile devices such as tablets, rotated.

  • Gesture support is improved and gestures such as pinch and swipe are better supported. In consequence, forms no longer have pages and instead can be continuously scrolled.

  • Automatically laid-out forms will probably work better than before, however any use of custom layouts will most likely require some changes.  More details below.

  • The main menu page has been redesigned; the large buttons are gone, replaced by a tree of slide-out menus.  

  • The concept of Projects has been strengthened in the UI, resulting in significant changes in the way jobs are handled, incorporating the redesign of the main window.

• 1. The idea of pages as part of the tsc_Form has been deprecated, since forms may now be scrolled up and down with a gesture.  Consequently, the tsc_PageBreakControl class will have no effect if added to a form.  Because the form page effectively has no bottom, the meaning of rows per page becomes unclear: 

     • From version 4.00, the specified number of rows is divided into the height of the standard form less the top and bottom margins to calculate the vertical field spacing, which is then used for the entire form. This means pages that look good during development and testing will often continue to look good on most devices and screen sizes.

• • A form's bottom margin does not actually appear anywhere on screen.

  • The layout grid may have controls and fields added for any number of rows. When controls extend past the bottom, the form becomes scrollable.

    • A "standard form" is one that is the same size, in pixels, as the desktop (or laptop) emulator.  This allows developers to size things correctly using their development environment, and expect this to work on most other platforms.  Some special attention may need to be paid to small portrait devices.

    • The sizing has changed; all forms are now full-width but may cover the status line at the top, and the softkeys at the bottom. Forms may be "tiled" side-by-side with the map or a video display.

1. The tsc_AppMainWindow class is deprecated, and also changed to support the new main menu style, though it still functions in much the same way as before.  A replacement class, tsc_AppMainMenu, is specifically tailored for the new UI and allows submenus to be created instead of the second level button menus used in the old UI.

2. The tsc_ImageField is now strictly correct in the z-order of controls on a form. This means that adding an image field to an automatically laid-out form after other controls may prevent some controls from being clicked, because the image - if it is large - will cover the controls, although this may not be apparent because the controls will still be be visible if the supplied image is largely transparent. In general, images should be added to the form before other controls. The image will be positioned according to the layout but its size will not affect positioning of later controls.

3. When opening a Job, a progress bar is now automatically displayed. This means that a job being opened from within a tsc_Thread or tsc_MonitorThread may crash because the progress bar constitutes UI which is not permitted outside of a tsc_UITask.  In this unlikely scenario, the thread must be converted to a tsc_UITask and started running on a new thread by using tsc_Survey_Core::Launch().

4. The Map has become the default window, displayed instead of the old "big button" window. This requires the map to be functional even when no job exists. Some plugins may have previously assumed that a job was open when the map requests a paint. From version 4.00, any plugin which uses the tsc_JobMap to draw on the map should have statements to guard against accessing the job if none is open. 

5. The option to use "geometric" movement when tabbing between fields on a form is no longer supported. The tab order of fields is always the same as their position in the Controls member of the form, and the arrow keys can no longer be used to navigate between fields.

6. The tsc_ButtonControl has a number of minor changes to the way it is laid out. In particular, the floating text feature is gone but a similar effect can be obtained using the text alignment options with a new margin parameter.

   1. The tsc_ListControl and tsc_TreeListControl fields behave slightly differently: when the list is empty or no current selection has been set, the SelectedIndex property of the control will be -1.  Attempting to manipulate item -1 will result in an assert and the application will close.  It is allowable to set the current selection to -1, which means no item is currently selected.

   2. The tsc_TreeListControl no longer supports the editing of cells.  To allow the user to enter a new value, a separate field must be supplied.

   3. The tsc_Rs232Stream class has been changed to accommodate any COM port by replacing the port name enumeration with a string.

   4. All images and colors now have an alpha channel. In some places, older image formats may exist, but these will be converted to ARGB automatically. Note that colors with a zero alpha value will be fully transparent and not display at all, where they would have previously; such colours and images should be replaced to include the correct alpha channel values.

Build and deployment changes

The build process has been greatly simplified. Some of this is due to support for Windows CE being dropped, so there are now only two build configurations - Windows 32-bit Release and Debug. The release build creates two installers - one for the emulator for development and demonstrations on desktop and laptop computers, and one called tablet for all customer installs whatever the actual device (using Windows 7 and 10 only).

We have also made good use of the Custom Property sheets which are available in Visual Studio 2015.  The entire build configuration is now done in one place, the plugin property sheet.

• 1. Trimble recommends that conversion to version 4 should be accomplished by using the v4 SCAPI Project Wizard to create a new SCAPI application, and copying the existing VS 2008 files across. Changes will be required, though most are minor.  The changes are summarised below, and the steps required to convert a pre-version 4.00 project are detailed here.

  2. From version 4.00, each plugin DLL is accompanied by an XML file which describes and names the application. This information is drawn from the SCAPI property sheet in the project. The file is in the same directory and has the same name as the DLL, but with .timxml as the file extension. This file is created automatically when the plugin is built, from information in the plugin property sheet.

  3. [This is a future plan...] The .timxml file is supplied along with the installer when submitting the plugin to Trimble for inclusion in the Store.  Information that previously needed to be filled in on the online submission form is now mostly obtained from the .timxml file.

  4. The installation build steps are different:

     • Windows CE is no longer supported and the old .inf files used for building these installs are no longer required.

     • There are still two installation configurations, one called Tablet which is for all customer installs, and one called Emulator which is used for testing and demonstration purposes. The only difference between the two installers is that the Emulator version installs with the Emulator version of Trimble Access such that multiple versions may co-exist on the same computer. The Tablet installer supports just a single version on a computer.

     • The new .timxml file also contains all the information previously placed in the Windows registry by the installer.  The registry data used for this is no longer required.

  5. All resource DLLs are removed.  The resources from the largest (1024x600) are moved into the plugin DLL itself.  Resource images are resized on the fly by the new UI and multiple sizes are no longer required.

Other non-breaking changes

• 1. Many cosmetic changes have occurred because of the UI upgrade.  Most fields and controls should behave as before, however some differences may have crept in and thorough testing should be carried out before releasing a plugin for this version of Trimble Access.

  2. Additional field and control layout options are available, and group boxes are now containers within which different layout rules may be applied.

1. A boolean field may now appear as either a checkbox (as before) or a sliding switch.

2. A new field is available, tsc_DropDownPortListField, which automatically populates itself with strings used to identify COM ports (both real and virtual).

3. The new UI now has the status bar at the top of the window rather than at the right-hand side of the window, so if an expanded form that doesn't show the status bar is to be displayed the form SetSizing method called in the constructor needs to have its parameter set to Size_High or Size_Full rather than Size_Wide.

4. ...