Image resources

May 28th 2020, version 20.10 : Rewritten to document the new simplified way of dealing with resources for both Windows and Android platforms, and using a third-party graphics library.

Overview

Most plugins will require images for displaying on buttons and other UI elements.  Images for this purpose may be obtained from a resource included in the installation as a PNG or JPG file. Although there is support for JPG, it is incomplete, transparency is not supported, and Trimble strongly recommends that PNG format is used throughout. In some places an SVG file may be used. These are preferable because they resize without any quality loss.

Images should be drawn with a transparent background to allow underlying UI elements to show through, and for buttons in particular to allow the button's state to display correctly.

Multiple platforms

In previous versions, multiple images of various sizes and resolutions were required to support the different sized screens that Trimble Access could run on.

Since then, display resolutions have improved and on-the-fly resizing has become practical, so along with the use of third-party libraries as our UI framework it is possible to supply a single high(ish) resolution image for use in all situations.

Adding resources to a project

The resource header, resource.h, continues to be used since it is already present in existing plugins. This header is maintained by hand and contains a name and number for each image resource. In Windows-only plugins, other resources may also be present as before.

The Windows resource.rc and .rc2 files may also remain in Windows builds but are not included in Android projects. 

The image resources used in Scapi are not included in the .rc file. For both Android and Windows, resource image filenames are instead registered at startup by the plugin's initialisation function.

The process below is for images. For other file types, simply add the file to the project, the installation scripts, and post-built events. At run time, the file path can be constructed using the appropriate macros in the tsc_Path class.

To add an image resource, do the following steps:

• • Invent an integer value and a name and add them to the resource.h file. Typically the integer value will be the previously highest used plus one. The value itself is immaterial but must be between 1 and 65534.

  • You can use the name to access the image in controls, fields, or to load into a tsc_Image.

  • Add the image file to the root or a sub-directory in the plugin project.

  • Add an item to the tsc_SurveyCore::RegisterAssets method that is called during startup, typically found in the <pluginName>.cpp file generated by the project template. This item associates the resource ID with the file path.

  • In the project properties post-build event, add a line to copy the image to the AppData folder where it will be used for testing. The project should already have images being copied in the correct manner, so just copy and modify one of these.

  • (Windows) Add a line to the <pluginName>.nsi file to install the file on the user's device. Again, copy and modify an existing line.

  • (Android) The image file will need to be present in the zip installation file. The existing zip command may be doing this already by means of a wildcard.

Assuming you used the Visual Studio project template (or copied some other existing plugin project that did), there should be enough of a framework that you can simply copy and/or modify what is already there.

Image types and resolutions

We recommend .png files for most purposes. Avoid jpeg images; these are optimised for photographs and while they may compress better, the rendering of sharp lines and shapes is often compromised by artifacts of the lossy compression.

Scapi supports alpha-channel transparency for most images, and backgrounds of images should be transparent wherever possible.

Size and resolution are a compromise. Depending on the platform, too-small images can be fuzzy or jaggy, too-big images will be slower and take more memory. As a rough guide, an image that looks good enough in the Trimble Access emulator on a 1920x1080 (or thereabouts) monitor, will be good for any platform. The size could be reduced if you are targeting small or low resolution devices only.

It is also possible to select different size images for different platforms by having separate calls to tsc_SurveyCore::RegisterAssets during plugin initialization although at Trimble we haven't found a need to do this.

Using a Windows resource dll

Not generally recommended; see this page.