Updating from SDK 0.1.1 to 1.0.6

The newest TanvasTouch SDK offers many improvements for developers, while requiring just a few changes to existing applications. This document is for partners who have been using any version of the TanvasTouch SDK prior to version 1.0, and will explain changes to the TanvasTouch Engine, and required changes necessary for existing applications.

New features in the TanvasTouch Engine Dashboard

The TanvasTouch Engine dashboard has a few new features.

In the top-right corner is the Mode indication, which shows whether the engine is running in Production or Development mode. Development mode should be used during active development of any application, and Production mode should be used on production devices. Do not run the Engine in development mode within a production environment as it may interfere with the main applications.
The TanvasTouch engine runs, by default, in Production mode; pass the -mode:development command-line argument to have it run in Development.

Updating the TanvasTouch libraries

The old TanvasTouch libraries must be removed from the solution:

  1. Expand References in the Solution Explorer, right-click on tanvas-lib-cs and select Remove.
  2. Expand Lib in the Solution Explorer, for both tanvas-lib-cs.dll and tanvas-lib-core.dll right click and select Delete. Visual Studio will present a warning that the files will be permanently deleted, click OK.
  3. In the project root in the Solution Explorer, right click on tanvas-lib-core.dll, and select Delete. Visual Studio will present a warning that the files will be permanently deleted, click OK.

Now add the new libraries to the solution:

  1. Copy the C# API library files Tanvas.TanvasTouch.dll and tanvastouch.dll from the API/C# folder of the TanvasTouch SDK into the (now empty) Lib folder of the Visual Studio project:
    !!! The default install location of the TanvasTouch SDK is C:\Program Files\TanvasTouch SDK\API.
  2. With Show All Files selected in the Solution Explorer, right click on both Tanvas.TanvasTouch.dll and tanvastouch.dll, and select Include In Project
  3. Right click on the project in the Solution Explorer, and select Add… and then Reference…, select Browse and then navigate to the Lib folder of the project, and select Tanvas.TanvasTouch.dll. It might be necessary to select All Files first.
  4. Right click on the project in the Solution Explorer, and select Add… and then Existing Item..., navigate to the Lib folder of the project, and select tanvastouch.dll. It might be necessary to select All Files first.
  5. In the Solution Explorer, right-click on tanvastouch.dll in the root of the project, and under Properties change Copy to Output Directory to Copy if newer.

!!! At this point verify that the application builds (it won’t yet run, but it should build).

Updating the application code

!!!! This section uses names of methods in the C# API, but the guidance is applicable in all programming environments.

The major addition to this version of the API, is that the application must now initialize the TanvasTouch library before calling any other functions. This serves to establish a connection between the application and the TanvasTouch Engine, and starts the licensing process.

Boolean TanvasTouch.API.Initialize(string app_id, string license_key);
  • Accepts:
    • app_id: This string is an application-ID that is unique for your application and organization. Reverse Domain-Name Notation should be used for the format of this ID. For example, the application-id for the TanvasTouch Viewer is co.tanvas.tools.viewer
    • license_key: This string is the license key for the application. Contact [email protected] to for free application license keys.
  • Returns:
    • true – Success
    • false – Error. Typically this means that the TanvasTouch Engine is not running, or that it’s an incompatible version.

TanvasTouch.API.Initialize() returns instantly, however no TanvasTouch resources (TView, TSprite, etc) can be created until the TanvasTouch Engine has verified the application-id and license key.

There are two options available for waiting for licensing to complete, select the method which best suits the design of the application:

  1. TanvasTouch.Service.LicenseStatus WaitForLicensing(): blocks and will not return until the license has been either approved or denied. This is a blocking call and should therefore only be called from a secondary thread.
  2. TanvasTouch.Service.LicenseStatus GetLicenseStatus(): returns the current and immediate license status. This is non-blocking and can therefore be called periodically from the main thread.

The above functions return a TanvasTouch.Service.LicenseStatus:

  • unknown: current licensing status is unknown. This typically indicates that Initialize() wasn’t called, the TanvasTouch Engine isn’t running, or some other error.
  • in_progress: the TanvasTouch Engine is in the process of verifying the license.
  • approved: the license key has been approved.
  • denied: the license key was not approved.

!! No TanvasTouch resources can be created unless the license state is approved.

!!! While the TanvasTouch Engine is running in Development mode, the app_id and license_key passed to Initialize() may be empty strings; however WaitForLicensing() or GetLicenseStatus() must still be called. The TanvasTouch Engine must never be run in Development mode while in a production environment.

In addition to the licensing features, this new API provides a method for getting a user-friendly error message (and error-code) should any other function fail:

ErrorCode GetLastError(): returns an ErrorCode object which has both a Value property and a Message property.

More Information

For more information about Application Licensing, see Application Licenses.

For full API reference, see API Reference.

For questions or problems updating any application to the TanvasTouch SDK 1.0.6, please contact Tanvas Support: [email protected]