Visual Studio project property sheet

Above, * indicates a property which you should configure, ‡ properties are often correct but should checked, and unmarked properties should be left as they are.

General

A plugin property sheet is a single place where all of the plugin configuration is done.  Custom Property sheets are a feature of Microsoft Visual Studio 2015 and later, which is the IDE Trimble recommends for building SCAPI plugins. A functional property sheet is made when a project is created by the Scapi New Project wizard, however it must be customised for the application.

Property sheet file details

The same property sheet is used for all configurations (Win32, Win64, Debug and Release, Tablet, Emulator, and Android).  The properties file, which is in XML format, is called Scapi.props in the plugin project directory.

Editing properties

You must set these properties before doing the first build of a plugin project.

To edit the property sheet, you should use the Visual Studio built-in form (but if you simply open the file in MSVC, you'll just get the XML source).  The XML may be edited directly, but the project will need to be reloaded after any edit.

To edit the properties in Visual Studio (and avoid the project reload) go to the menu: View ➼ Other windows ➼ Property manager. This window will display a list of projects and configurations.  Choose any configuration under the project to be edited and double-click the Scapi item (all configurations point to the same file). This will display a full set of project properties.  On the left in the tree, choose Common Properties ➼ User Macros.  This will show a set of named plugin properties which can be edited.

Notes

Visual Studio does not save the property sheet in the "usual" way.  Instead, to save it right-click the Scapi entry in the Property manager and choose Save. If the property sheet is in a MSVC-controlled source control system like TFS or Git it will be checked out at this time. Also, if the sheet XML is updated outside of MSVC, the property form doesn't reflect the changes; only reloading the solution seems to fix this. This behaviour may change as a result of Microsoft updates.

Properties defined here may be substituted into any part of the MSVC build process by using a $(propertyname) macro.  You may also add your own properties, preferably in your own property sheets.

The properties

The properties are as follows. The values that we use at Trimble for our Land Seismic app are provided as examples. All property values must be set.

• • Avoid using the double-quote (") character. Many of these values are substituted into strings with double-quotes around them already, and escape sequences are inconsistent.

  • In the following, * indicates a property which must be changed to reflect your plugin, and

  • ‡ indicates a property that is often correct but should checked at least once when making a new project.

  • Properties without * or ‡ are pre-set should be left unchanged.

CompanyName *

Provide a short name, that is valid as a file name, for the company that is developing and/or marketing this plugin. For example, Trimble uses the string "Trimble" in this field. It is primarily used for file paths and windows registry path names.

CompanyFullName *

Give the full name of the company for use in plain text. Most special characters are allowable. For example, Trimble uses Trimble Inc. in this field.

ProductName *

The name of this plugin. This should be a short but descriptive name for the application used to identify it in messages and in the installer. Initially set to the project name. For the Trimble Land Seismic application, this field is Trimble Land Seismic.

ProductIdentifier ‡

An identifier-safe name for the plugin. The default name is based on the project name and is usually good. This property is used to name many plugin-related files, directories, and windows registry keys is derived from the project name with unsafe characters replaced by underscores. This name is defined in the plugin project's Properties page ➼ Configuration properties ➼ General, where there is a Target name property which is set equal to the project name by the project template. Altering this name is not recommended since many files, folders, and other things, are expected to have the same name.

ProductWebSite *

Supply the url of a web page describing your product. This url is used in places such the "More info" link in various places. For example, the value used for Trimble's Land Seismic app is www.trimble.com/survey/trimble-access-is-landseismic.aspx

TokenName ‡

Supply the PX_ token name of the application name as it appears in the translation database (.tdb) file, for display in the UI. By default this is set to PX_ProductFullName. Language translations for this token name should be provided in the .tdb file, to be used in the UI as appropriate.  The translations (including English) should be kept short enough to look acceptable on the Trimble Access Application chooser form. If no translation of the name is required, the text may be specified here directly with no PX_ on the front (and no quotes). If the TokenName value starts with PX_ but is not a valid language token in the translations database, then the ProductName is used instead. For example, the Trimble Power Line application could use the text Power Line, or PX_ProductFullName, where the translated string might be "Power Lines" or its equivalent in the currently selected language.

PluginGUID ‡

The GUID of the plugin. If the tsc_Application::GetProductGuid() method is implemented in tsc_Application, the returned value must match this property. The GUID is randomly generated when the project is created by the Visual Studio project template, and should not be changed once it has been assigned. A typical GUID, which should be lower-case, looks like this:
3e858abd-88b5-49e4-99b7-301ade78642d  ↞ But don't use this one.

If you are creating both Android and Windows variants of your plugin, use the same GUID for both. That is, copy/paste the GUID from one project to the other.This allows the same user subscription (license) to be used for both.

IconFile ‡

The path to an installed image file relative to the .timxml file's installed location, and is usually installed into the same directory along with the plugin dll. The icon is displayed in the application chooser and in other places . The image file type may be one of the following, in order of preference:

• SVG, the preferred format since it is easily resizeable without loss of quality.

• PNG, which support transparency but may lose quality when resized.  The size should be 120 x 120 or more.

• JPG, the least preferred, since transparency, quality, and resizing are all poor.

Example: LandSeismic.png

Also, an icon (.ico) file is required for the plugin installer (Windows only). This file is called TargetName.ico and a default file is supplied by the project wizard. You should update this to a less generic icon by replacing the file.

LicenseName *

Give the exact name of the Subscription in the Trimble licensing system for this application. Typically this is the same as the application name (ProductName), but possibly includes a license version number. Please check information sent to you at the time you applied to Trimble to create this application.  For plugins which will never be released (eg, made for evaluation or testing), this field is irrelevant and may be left empty. 

PluginMajorVersion *

The first component of the plugin DLL's version number, which usually starts at 0 or 1 and is only updated for major revisions.  All version components must be integers.

PluginMinorVersion *

The second component of the DLL's version number. Start at 00 and increment by at least one for each released version, using two digits to make it plainer that 2.10 is greater than 2.01, and avoiding the ambiguous 2.1

PluginBuildVersion *

The third component of the version number. Could be updated every build, but as a minimum, this must be incremented any time the application installer is uploaded to the Trimble server to distinguish this from earlier versions. 

The fourth component of the version number is always zero. The version number of the generated DLL can be viewed in Windows Explorer by right-clicking the DLL, choosing Properties, and then the Details tab. In Trimble Access, the About box shows the version number of all loaded plugins.

PluginVersion

Do not change.  This is the composite version number constructed from the above values, such as 3.12.45 

ScapiVersion ‡

Specify the version of the SCAPI SDK to be used to build this plugin.  Any installed version of the SDK may be specified here. Because this version also determines the oldest version of Trimble Access that the plugin may be used with, the only reason to build a plugin using an SDK version that is not the latest, is to provide binary compatibility to users of older versions of Trimble Access. This backward compatibility is not possible between versions before 19.00, and later versions. Multiple versions may exist concurrently on the Scapi downloads server, to suit the various versions of Trimble Access currently in use.

To install another version of the SDK, run Trimble Installation Manager and choose the required version from the drop-down list at the top (you may need to wait until TIM has updated itself). Multiple SDK versions may be installed on a single computer. Then update this value in this property sheet to the newly installed version number, and also update the MinimumSdkVersion, below. Also check the release notes for the new version in case changes to your plugin are required.

All this applies to Windows and Android equally. Both platforms are supported in the one SDK installation.

MinimumSdkVersion

The lowest version of Trimble Access that this plugin may be used with. Customers will not be offered this plugin installation if they are installing an earlier version of TA.  Normally this is the same as the SCAPI SDK version the plugin is built with (see ScapiVersion, above) but a later version may be specified if necessary.  Never specify an earlier version than ScapiVersion; this will very likely cause incompatibility errors for users of the plugin.

ScapiSdkDir

The directory in which the SCAPI SDK is installed. By default this property contains the standard path, derived from the specified ScapiVersion (see above) and should not need changing. If the SDK has been installed in some non-standard location, then this property will need to be adjusted. If a different SDK version is to be used, adjust the ScapiVersion property and not this one.

A typical path might be: $(ProgramW6432)\Trimble\Trimble Survey Core API v20.20\

Trimble Access developers should change this property to point to their local working directory:  ...\access\SC\Scapi\

PluginTestDir

This is the directory in which Trimble Access looks in for additional plugins which are under development.

When the plugin is built, an MSVC build event copies the plugin files into this directory for testing and debugging. By default this property contains the usual path under your user AppData folder, derived from the specified ScapiVersion property (see above) and should not be changed. 

Note: If your installer (controlled by the .nsi files) installs other necessary files along with the plugin, then you should edit the Post-build event property of your plugin project and add a copy command for these files to also be copied to the plugin test directory, which will allow your plugin to access the files.

The usual setting is: %AppData%\Trimble\Trimble Survey Core API V$(ScapiVersion) Plugins\$(CompanyName)\

TimXmlProperties

Do not change. A powershell script is used to generate the installer (.timxml) file for the plugin, and this property defines part of the command line that is passed to the script.

SeeThisUrlForMoreInfo

https://sites.google.com/trimble.com/scapi-plugin-developers-guide/plugin-property-sheet

This is purely to allow you, the developer, to find more information (i.e. this page). It is not necessary for the project.