IDashApplication

IDashApplication automation interface.

Instances supporting this interface may be created using the Application coclass.

These examples create an instance and display its window. The application must be installed and its COM server registered on Windows. The C# example uses dynamic COM binding and does not require an imported interop assembly.

The JavaScript examples run with Windows Script Host, not in a browser. Save the chosen JavaScript example as automate.js and place this batch file in the same directory. The batch file works from any current directory and returns the script’s exit code to its caller.

@echo off
cscript.exe //nologo "%~dp0automate.js"
exit /b %errorlevel%
​
// Save as automate.js and run with the batch file above.
var obj = new ActiveXObject("GemsDashDesign.Application");
obj.Visible = true;
WScript.Echo(obj.Version);
using System;
using System.Runtime.InteropServices;

var applicationType = Type.GetTypeFromProgID("GemsDashDesign.Application", throwOnError: true)!;
dynamic app = Activator.CreateInstance(applicationType)!;
try
{
    app.Visible = true;
    Console.WriteLine(app.Version);
}
finally
{
    Marshal.FinalReleaseComObject(app);
}
$ErrorActionPreference = 'Stop'
$app = New-Object -ComObject 'GemsDashDesign.Application'
try {
    $app.Visible = $true
    $app.Version
} finally {
    [void][System.Runtime.InteropServices.Marshal]::FinalReleaseComObject($app)
}
Dim obj
Set obj = CreateObject("GemsDashDesign.Application")
obj.Visible = True
WScript.Echo obj.Version
// Direct COM interface.
::CoInitialize(NULL);
IDashApplication* iface = 0;
HRESULT hr = ::CoCreateInstance(
    CLSID_Application, 
    NULL, 
    CLSCTX_LOCAL_SERVER,
    IID_IDashApplication,
    (LPVOID*)&iface);

if (iface) {
    iface->put_Visible(TRUE);
    iface->Release();
}
::CoUninitialize();
// IDispatch interface.
::CoInitialize(NULL);
HRESULT    hr;
CLSID      clsid;        // CLSID of ActiveX object.
LPUNKNOWN  punk  = NULL; // IUnknown of ActiveX object.
LPDISPATCH pdisp = NULL; // IDispatch of ActiveX object.

// Retrieve CLSID for GemsDashDesign.Application from the registry.
// This is {4CF7EE02-7183-4DF2-B0D9-751AEE62FC25} which could be 
// used directly for better performance.
hr = CLSIDFromProgID(L"GemsDashDesign.Application", &clsid);
if (FAILED(hr)) {
    return hr;
}  
// Create an instance of the ActiveX object.
hr = CoCreateInstance(clsid, NULL, CLSCTX_SERVER, 
                      IID_IUnknown, (void **)&punk);
if (FAILED(hr)) {
    if (punk) punk->Release();
    return hr;
}    
hr = punk->QueryInterface(IID_IDispatch, (void **)&pdisp);
if (FAILED(hr)) {
    punk->Release();
    if (pdisp) pdisp->Release();
    return hr;
}
punk->Release();
// << Use the dispatch interface..
pdisp->Release();    
::CoUninitialize();

Contents

Properties

Property Description
Version Get application version.
ModulePath Get application EXE path.
Visible Displays/hides the Application UI.
FullScreen Makes the window fullscreen (or not).
LastErrorString Provides an error string describing the last method failure that occurred, if possible.
Setup Not yet implemented.
Tabs Not yet implemented.
SelectedDevice Gets the currently selected device (if any).
CurrentTabID Get / Set the current top-level tab ID.
CurrentSubTabID Get / Set the current sub-level tab ID.
SimulatorRunning
SimulatorProcessId Running simulator host PID for native debugger attachment, or zero when stopped.

Public Methods

Function Description
CreateOptionsMap Create an instance of IDashOptionsMap that can be used to modify the behaviour of various functions that accept options.
InvokeAction Invokes an action with the specified ID.
OpenSetup Opens the setup specified by ‘path’.
SaveSetup Saves the current setup by its current file name.
SaveSetupAs Saves the current setup by a new file name.
NewSetup Creates a new setup.
CreateDeviceList Gets a list of the devices that are attached to the system.
GenerateHelpInfo Generate Help Information as JSON.
EnumerateWindows Enumerate Windows in the application.
TakeScreenShot Take a screenshot of a window or the whole application.
CloseWindow Close a window (if possible).
FocusWindow Focus & raise a window (if possible).
SetProperties Set mutiple properties on a window / view.
GetProperties Get all properties from a window / view.
SetProperty Set a single property on a window / view.
GetProperty Get a single property from a window / view.
Click Simulate a mouse click.
SetSimulationChannel Set a simulator channel value.
ImportCanDbc Import CAN DBC file.
Keyboard Simulate a keyboard.
ListCANPorts Obtains an interface for listing CAN adaptors connected to the PC.
BindSimuatorCANPort Connect a physical CAN port to the simulator.
EmbedCdxModel Embed a CDX Model package into the currently open setup (if editable + supported).
ConfigureSimulator Configure the next simulator launch without starting it.
SupportsCdxModelImageDescriptor Query implemented CDX Model image descriptor versions without loading a package.

Properties

Version

Get application version.

BSTR Version

ModulePath

Get application EXE path.

BSTR ModulePath

Visible

Displays/hides the Application UI.

BOOL Visible

The UI will be hidden initially when creating an instance of GemsDashDesign.

FullScreen

Makes the window fullscreen (or not).

BOOL FullScreen

Setting this value to TRUE causes the application window to take up the full screen without title bars etc.

When entering fullscreen mode via the COM Automation Interface, the popup ’toaster’ window giving users a way of exiting fullscreen mode is not displayed.

LastErrorString

Provides an error string describing the last method failure that occurred, if possible.

BSTR LastErrorString

Wehre appropriate, this string is also included in Error exception description strings as a result of IDispatch calls (e.g. when accessed via late binding as with JavaScript).

Setup

Not yet implemented.

IDispatch Setup

In future this will return an interface to the setup object which Offers more setup specific functionality than the Application interface.

Tabs

Not yet implemented.

IDispatch Tabs

In future this will return an interface that gives access/control of the list of tabs, tab groups, views within tabs etc.

SelectedDevice

Gets the currently selected device (if any).

IDashDevice SelectedDevice

May return a NULL device.

CurrentTabID

Get / Set the current top-level tab ID.

BSTR CurrentTabID

CurrentSubTabID

Get / Set the current sub-level tab ID.

BSTR CurrentSubTabID

Some tabs have sub-tabs. This property allows you to get/set the current sub-tab where possible.

SimulatorRunning

BOOL SimulatorRunning

@breif Control the simulator running state.

SimulatorProcessId

Running simulator host PID for native debugger attachment, or zero when stopped.

ULONG SimulatorProcessId

Public Methods

Method: CreateOptionsMap

Create an instance of IDashOptionsMap that can be used to modify the behaviour of various functions that accept options.

HRESULT CreateOptionsMap([out, retval] IDashOptionsMap **options)

It is also possoble to use JavaScript objects for options instead of an options map.

See Also: IDashOptionsMap

Method: InvokeAction

Invokes an action with the specified ID.

HRESULT InvokeAction([in] BSTR action_id, [in, optional] VARIANT options)

If ‘deferred’ is specified and set to ’true’ then the function will defer the action invocation via the event loop and return immediately. In cases where the action would display a modal dialog or message box, using a deferred invocation avoids the caller from blocking. Deferred calls retain the application and snapshot their options until execution finishes.

Method: OpenSetup

Opens the setup specified by ‘path’.

HRESULT OpenSetup([in] BSTR path, [in, optional] VARIANT options)

The user may be prompted to save any modified setup files. See IDashOptionsMap::SaveModifiedDiscard and IDashOptionsMap::SaveModifiedPrompt

Method: SaveSetup

Saves the current setup by its current file name.

HRESULT SaveSetup([in] VARIANT options)

If the setup does not have a file name then the behaviour of this function will depend upon the ‘options’ parameter and may not be saved as a result.

See IDashOptionsMap::SaveModifiedDiscard and IDashOptionsMap::SaveModifiedPrompt

Method: SaveSetupAs

Saves the current setup by a new file name.

HRESULT SaveSetupAs([in] BSTR path, [in] VARIANT options)

If the setup does not have a file name then the behaviour of this function will depend upon the ‘options’ parameter and may not be saved as a result.

See IDashOptionsMap::OverwriteAllow and IDashOptionsMap::OverwriteSilent

If options contains saveCopy = true, writes a copy without changing the open setup’s file name or modified state.

Method: NewSetup

Creates a new setup.

HRESULT NewSetup([in] VARIANT options)

If the setup has been modified then the behaviour of this function will depend upon the ‘options’ parameter and may fail as a result.

Method: CreateDeviceList

Gets a list of the devices that are attached to the system.

HRESULT CreateDeviceList([out, retval] IDashDeviceList **retval)

This will implicitly re-scan the system for the attached devices.

Method: GenerateHelpInfo

Generate Help Information as JSON.

HRESULT GenerateHelpInfo([in, optional] VARIANT options, [out, retval] BSTR *result)

Returns

The information as a JSON string. If outputFile is specified in options then the returned string will be blank.

If the ‘options’ parameter has a property ‘outputFile’ then the JSON will be written to that file instead of returned as a string.

Method: EnumerateWindows

Enumerate Windows in the application.

HRESULT EnumerateWindows([in, optional] VARIANT options, [out, retval] BSTR *result)

Returns

The information as a JSON string.

Method: TakeScreenShot

Take a screenshot of a window or the whole application.

HRESULT TakeScreenShot([in, optional] VARIANT options, [out, retval] VARIANT *result)

Returns

The information as a JSON string.

If the ‘options’ parameter has a property ‘outputFile’ then the screenshot will be output to that path instead of returned.

options can identify the window through one of the following keys:

  • id
  • name
  • label
  • menu: screenshot the active context menu, if any.

If one of these items are not specified then a screenshot of the main window will be taken.

Other options:

  • clipboard: place the screenshot on the Windows clipboard
  • focus: true/false (default true)) - focus the window first.
  • print: Use WM_PRINT to capture the window. This may not work well for all windows (not 100% WYSIWYG), but does mean that occluded window areas are captured.
  • outputFile: Path to save the screenshot to.
  • cursor: Include the mouse cursor in the screenshot (default: false).
  • expand: Expand the screenshot rectangle by the specified number of ‘device’ pixels (depends on Windows display scaling option). expand option does not work with the ‘print’ option.

Method: CloseWindow

Close a window (if possible).

HRESULT CloseWindow([in] VARIANT options, [out, retval] VARIANT *result)

Returns

TRUE if OK, false otherwise. This is a variant for posssilbe future changes.

options: id: Window ID for the window to close. name: ’name’ of window to close. label: ’label’ of window to close. code: result code (e.g. if the window is modal - see e.g. wxID_OK).

Method: FocusWindow

Focus & raise a window (if possible).

HRESULT FocusWindow([in] VARIANT options)

Method: SetProperties

Set mutiple properties on a window / view.

HRESULT SetProperties([in] VARIANT options, [in] VARIANT props)

Method: GetProperties

Get all properties from a window / view.

HRESULT GetProperties([in] VARIANT options, [out, retval] VARIANT *result)

Returns

a JSON string detailing the properties.

Method: SetProperty

Set a single property on a window / view.

HRESULT SetProperty([in] VARIANT options, [in] BSTR name, [in] VARIANT value)

Special Properties:

“selection”: string: json style array [[row,col],…n]. ‘col’ is optional. e.g. “[[5,2],[5,3]]” If a number is specified, the whole row is selected. “text”: For text editors, sets the text.

“expand_sidebar”: Expand the sidebar. “lock_sidebar”: Lock the sidebar.

Method: GetProperty

Get a single property from a window / view.

HRESULT GetProperty([in] VARIANT options, [in] BSTR name, [out, retval] VARIANT *result)

Returns

The property value.

Method: Click

Simulate a mouse click.

HRESULT Click([in] VARIANT options)

Method: SetSimulationChannel

Set a simulator channel value.

HRESULT SetSimulationChannel([in] BSTR channel, [in] VARIANT value)

Method: ImportCanDbc

Import CAN DBC file.

HRESULT ImportCanDbc([in] BSTR path, [in] VARIANT options)

Method: Keyboard

Simulate a keyboard.

HRESULT Keyboard([in] VARIANT options)

Method: ListCANPorts

Obtains an interface for listing CAN adaptors connected to the PC.

HRESULT ListCANPorts([out, retval] IDashCANPorts **retval)

Method: BindSimuatorCANPort

Connect a physical CAN port to the simulator.

HRESULT BindSimuatorCANPort([in] int index, [in] BSTR port_identifier, [in] VARIANT options)

Note: The CAN port will use the bitrate defined in the display setup.

Method: EmbedCdxModel

Embed a CDX Model package into the currently open setup (if editable + supported).

HRESULT EmbedCdxModel([in] BSTR path)

Replaces the current model identity, embedded firmware and Model IPC signal definitions. Takes into account the package’s ‘protected’ setting. The source path is retained for file-change notifications and reloading.

Does not program the display, show ant dialogs, change tabs, or save the setup. Call SaveSetup or SaveSetupAs afterwards to persist the embedded model.

Returns E_INVALIDARG for an empty filename, or a failing HRESULT if no editable CD6 setup is open or package validation/installation fails. For more errors information, see LastErrorString.

​
// Save as automate.js and run with the Windows Script Host batch file
// shown in the application interface examples.
var app = new ActiveXObject("GemsDashDesign.Application");
var options = app.CreateOptionsMap();
options.discardModifiedFiles = true;
options.promptSaveModified = false;
options.allowFileOverwrite = true;
app.OpenSetup("C:\\Setups\\input.cd6.gdd", options);
app.EmbedCdxModel("C:\\Models\\engine.cdxmodel");
app.SaveSetupAs("C:\\Setups\\output.cd6.gdd", options);
using System;
using System.Runtime.InteropServices;

var applicationType = Type.GetTypeFromProgID("GemsDashDesign.Application", throwOnError: true)!;
dynamic app = Activator.CreateInstance(applicationType)!;
try
{
    dynamic options = app.CreateOptionsMap();
    try
    {
        options.discardModifiedFiles = true;
        options.promptSaveModified = false;
        options.allowFileOverwrite = true;
        app.OpenSetup(@"C:\Setups\input.cd6.gdd", options);
        app.EmbedCdxModel(@"C:\Models\engine.cdxmodel");
        app.SaveSetupAs(@"C:\Setups\output.cd6.gdd", options);
    }
    finally
    {
        Marshal.FinalReleaseComObject(options);
    }
}
finally
{
    Marshal.FinalReleaseComObject(app);
}
$ErrorActionPreference = 'Stop'
$app = New-Object -ComObject 'GemsDashDesign.Application'
try {
    $options = $app.CreateOptionsMap()
    try {
        $options.discardModifiedFiles = $true
        $options.promptSaveModified = $false
        $options.allowFileOverwrite = $true
        $app.OpenSetup('C:\Setups\input.cd6.gdd', $options)
        $app.EmbedCdxModel('C:\Models\engine.cdxmodel')
        $app.SaveSetupAs('C:\Setups\output.cd6.gdd', $options)
    } finally {
        [void][System.Runtime.InteropServices.Marshal]::FinalReleaseComObject($options)
    }
} finally {
    [void][System.Runtime.InteropServices.Marshal]::FinalReleaseComObject($app)
}

Method: ConfigureSimulator

Configure the next simulator launch without starting it.

HRESULT ConfigureSimulator([in] VARIANT options)

debugger attach.

Stop the simulator before configuring.

Empty model paths are auto-populated from environment variables CDX_MODEL_DLL

  • CDX_MODEL_IMAGE.

Returns E_INVALIDARG for bad options; E_FAIL for unsupported displays, invalid files, or if the simulator is already running. For more errors information, see LastErrorString.

Start with SimulatorRunning = true, then use SimulatorProcessId to attach Visual Studio or VS Code’s native debugger to SimHost, which loads both DLLs.

Method: SupportsCdxModelImageDescriptor

Query implemented CDX Model image descriptor versions without loading a package.

HRESULT SupportsCdxModelImageDescriptor([in] LONG descriptorVersion, [out, retval] VARIANT_BOOL *supported)

Read-only: requires no open setup, files or connected device, and does not import, save, program or change UI state. S_OK for known and unknown versions; E_POINTER if supported is null. A true result does not bypass validation: schema 2 requires descriptor 1/3, schema 3 requires descriptor 2/4 and valid calibration metadata; all package integrity and identity checks still apply.

Older servers may not implement this appended method. Late-bound clients must handle a missing member as unknown capability, not infer support from the application version. Native clients require an updated server.