Using the GISDK Extension Engine In-Process API

 

Maptitude has a .NET Extension API. With this API you can write an assembly with any .NET language that can be loaded by Maptitude and that can make calls to our macro functions or compiled macro language code. Your extension runs in the same process as Maptitude, and has access to the hosting GISDK environment via the IGisdkEngine interface.

 

The steps for building such an extension in C# are as follows:

 

1. In Visual Studio, create a C# class library project. Make sure it is based on at least the .NET 4 Framework.
2. Add a reference to GisdkAPI.dll , which you can find in the program folder for Maptitude.
3. Create a class that implements the GisdkAPI.IGisdkExtension interface. Specifically, the entry point to your code will be your implementation of the Load() method of this interface. When this method runs, it will be passed a reference to an IGisdkEngine object, which is what you can use to call into Maptitude. 
4. The best way to do this is to assign this object to a variable of type 'dynamic'. You can then use this variable to call macro functions directly. For example:

class MyExtension : GisdkAPI.IGisdkExtension

{

    public void Load(IGisdkEngine engine)

    {

        dynamic app = engine;

        MessageBox.Show("The current layer is " + app.GetLayer());

    }

}

 

5. You can also use this object to call macros and create GISDK objects:

app.Macro("G30 create set", setName);

myDKObject = app.CreateObject("MyDKClass");

 

6. The properties of GISDK types as well as GISDK objects (including their methods) can be referenced using the standard dot notation:

var scope = app.GetMapScope(myMap);

double area = scope.Width * scope.Height;

 

var myDKObject = app.CreateObject("MyDKClass");

myDKObject.DoSomething();

 

7. The GisdkAPI assembly contains a utility class for helping with GISDK options arrays:

var options = new GisdkAPI.OptionsArray();

options["Map"] = mapName;

options["Layer"] = layerName;

 

var themeOptions = new GisdkAPI.OptionsArray(app.GetThemeOptions(themeName));

var themeValues = themeOptions["Values"]

 

8. Your entry class will also need to implement a getter for the Title property. which is required by the IGisdkExtension interface.
9. Once you have completed and built your class library project, you need to place the assembly (.dll file) into one of the following locations:

• c:\ProgramData\Caliper\Extensions\ (available for all users, all products)
• c:\ProgramData\Caliper\<productname>\Extensions\ (available for all users, current product)
• c:\Users\<username>\Documents\Caliper\Extensions\ (available for current user, all products)
• c:\Users\<username>\Documents\Caliper\<productname>\Extensions\ (available for current users, current product)

A menu item to run the extension will then appear under the Add-Ins sub-menu of the Tools menu.

Types Defined in GisdkAPI.dll

 

Interface IGisdkExtension

You must create a class that implements this interface, which defines the entry point to the extension:

 

void Load(GisdkAPI.IGisdkEngine app)

    this method is called in order to load the extension

string Title { get; }

   return the title of the extension to be displayed in the Add-ins menu in the getter for this property

 

Interface IGisdkEngine

When the extension is loaded a dynamic object which implements this interface will be passed to the IGisdkExtension.Load() method. Use this object to call GISDK functions and macros:

 

object Function(string functionName, params object[] args)

    call a macro function

 

Note that you can also call the function as a method directly on the object itself. For example, instead of:

 

engine.Function("SetLayer", "Streets")

 

you can simply write:

 

engine.SetLayer("Streets")

 

object Macro(string macroName, params object[] args)

    call a GISDK macro that is compiled into a UI database

 

IGisdkType CreateObject(string className, params object[] args)

    create an instance of a GISDK class

 

IGisdkEngine WithAlternateInterface(string dbPathName)

   returns another instance of IGisdkEngine which you can use to call GISDK macros and create objects of GISDK classes that are compiled into the specified UI database.

 

System.Windows.Forms.IWin32Window GetMainWindow()

   returns the window handle of the main application frame window; can be used as the owner window for displaying Windows Forms as modal dialog boxes

 

Interface IGisdkType

Instances of custom GISDK types are returned via calls on the IGisdkEngine interface as dynamic objects implementing this marker interface. Properties of these values are retrieved dynamically.

 

Class OptionsArray

This is a utility class for handling arrays as GISDK options arrays. You can pass an instance of this type to any macro function which expects an options array:

 

OptionsArray()

    create an empty OptionsArray

 

OptionsArray(dynamic optionsArray) 

    create an OptionsArray from an options array returned by a GISDK function

 

object[] ToArray()

    returns an regular array of arrays representing the options

 

bool ContainsKey(string key)

    returns whether the OptionsArray contains the specified option

 

void AddMultiElementOption(string key, params object[] values)

    add an option with several values

 

object this[string key] { set; get; }

    get and set options via a string indexer

 

Class GisdkRuntimeException (inherits from System.Exception)

If there is a macro error encountered when calling a function or macro then an exception of type GisdkRuntimeException will be thrown:

 

int Status { get; }

    returns the macro error type number

 

For an example of a project which partially implements the Map Library dialog in C#, go to http://www.caliper.com/ovusware.htm, click the Maptitude link under Free Software Add-Ins, and choose Batch Maps (DotNET).

Using WithAlternateInterface to Run Macros Defined in Your Module

With the .NET Extension API you can run macros defined in your module. Let's say your other module has the macro named "Another Macro Name" and it is compiled to the file path/to/another_module.dbd:

 

Macro "Another Macro Name" (arg1,arg2)

endMacro

 

You can set the alternate interface to your module with:

 

var other_module = dk.WithAlternateInterface("path/to/another_module.dbd")

 

then use your macro:

 

result = other_module.Macro("Another Macro Name",arg1,arg2)

 

In this way you can refer to many different modules.