Creating a .NET "In-process" GisLink Application

Creating a .NET GisLink Add-In Project

Note: This topic details how to create a GISLink application, an example of how to create a basic simple .NET "In-process" GisLink application see .NET "in-process" GisLink Example.

  • This topic references Microsoft Visual Studio 2012.

    • Start Microsoft Visual Studio and select File > New Project…

    Although an "in-process" Add-In is created as a Class Library Application it is simpler to start the new project as a Windows Forms Application and alter the application type in order to retain references for System.Windows.Forms.

    The Application Type property can be set on the Application page of the Visual Studio Project Designer.

    With a project selected in Solution Explorer, on the Project menu, click Properties, click the Application tab.

    For a Visual Basic project, in the Application Type list, click the desired type. For a C# project, in the Output Type list, click the desired type.

    The application architecture and frameworks can be set on the Compile and Debug pages of the Visual Studio Project Designer.

    The application architecture (x86 / x64) must match the SIS installation.

    SIS requires the .NET Framework 4 which should be chosen as target framework for all configurations.

    The Cadcorp.SIS.GisLink.Library.dll must be used as reference for GisLink Add-in applications.

    References can either be added in the Visual Studio Solution Explorer or on the References page of the Visual Studio Project Designer.

    Cadcorp.SIS.GisLink.Library.dll can be found by browsing the SIS installation directory.

    Adding a GisLink Application Class

    Classes can be added to a project in the Visual Studio Solution Explorer.

    In order to ease programming access to the SIS API methods and constants it is recommended to import the GisLink library and constants.

    The class itself must be “decorated” with a GisLinkProgram attribute. This is the name of the Add-in which is shown in the SIS Add-In Manager.

    The GisLinkProgram class constructor is executed once when SIS is loading, which means all Ribbon Group and Context Menu config items must be defined in the constructor. Anything you want running all the time in SIS, such as (some) triggers or a WCF inter-process server should also be initiated here.

    Note: SIS API commands can also be accessed from SisClickArgs object passed to any registered SisClickHandler. The product level (Manager, Editor, Modeller) you use can be decided here based on which object you choose to instantiate from the SisClickArgs.

    Example code for a full GisLink application:

    Imports Cadcorp.SIS.GisLink.Library

Imports Cadcorp.SIS.GisLink.Library.Constants

<GisLinkProgram("Cadcorp V8 VB.NET GisLink Sample")> _
Public Class Loader
    
    Public Shared _App as SisApplication
    
    Public Sub New(ByVal SisApplication As SisApplication)
        _App = SisApp
        
        ' Local Menu For AComLine
        Dim mMainMenu As SisMenuItem = New SisMenuItem("AComLine", New SisClickHandler(AddressOf DoAComLine))

        mMainMenu.Text = "AComLine"
        mMainMenu.Help = "Calls The AComLine Command"
        mMainMenu.Class = ""
        mMainMenu.Filter = ""
        'mMainMenu.Image = ""
        mMainMenu.Locus = ""
        mMainMenu.MinSelection = 0
        mMainMenu.MaxSelection = -1
        mMainMenu.MinStatus = 2
        mMainMenu.Enabled = True

        _App.ContextMenu.MenuItems.Add(mMainMenu)
        
    End Sub
    
    Private Sub DoAComLine(ByVal sender as Object, ByVal e as SisClickArgs)
    
        ' Choose licence level.
        Sis = e.MapManager
        
        ' SIS API calls are now possible.
        Sis.SwitchCommand("AComLine")
        
        ' Ensure control is returned from the GisLink to the Desktop app.
        Sis.Dispose()
        Sis = Nothing
        
    End Sub
End Class

    Adding commands to the SIS Applications tab

    SIS uses a ribbon interface as a means of accessing commands. GisLink Add-In buttons can be created in the ribbon, in a new group on the Applications tab.

    The following controls can be defined in the GisLink Add-in application constructor:

    SisRibbonGroup – A ribbon group is a container for ribbon controls.

    SisRibbonButton – A SisClickHandler in the constructor of the SisRibbonButton object has the address of a Sub procedure which is called when the button is clicked on the SIS ribbon interface.

    The following example shows a simple ribbon control definition:

    Dim AddInRibbonGroup As SisRibbonGroup = APP.RibbonGroup

    AddInRibbonGroup.Text ="My Add-In"

    Dim myCommandButton As SisRibbonButton = NewSisRibbonButton("My Command",New SisClickHandler(AddressOf MyCommand))

    myCommandButton.Help = "Simple descriptive text here"

    myCommandButton.Description = "Detailed description of the use of this command, appears as ToolTip help"

    myCommandButton.LargeImage = True

    myCommandButton.Icon = Nothing

    AddInRibbonGroup.Controls.Add(myCommandButton)

    SisRibbonCheckBox – A checkbox control within the button group.

    SisRibbonLabel – A simple text label within the button group.

    SisRibbonLaunchButton – Each ribbon group can have one launch button, suggested use would be to allow the user to access a dialog with advanced features or settings for the Add-In.

    SisRibbonSeperator – Allows you to control the layout of other controls within a ribbon group.

    Adding commands to the SIS Map Window Context Menu

    Menu items can be added to the SIS Map Window context menu.

    SisMenuItem – A menu item can be directly added to the SIS Map Window context menu or to an existing SisMenuItem. Adding menu items to existing menu items will nest the control as a sub-menu. A SisClickHandler in the constructor of a SisMenuItem has the address of a Sub procedure which is called when the button is clicked on the SIS ribbon interface.

    The following example creates a menu with a nested menu item in the Map Window context menu:

    Dim MyContextMenu AsSisMenuItem = New SisMenuItem("MyContextMenu")

    Dim MySisMenuItem AsSisMenuItem = New SisMenuItem("MyMenuItem", New SisClickHandler(AddressOf MyContextMenuSub))

    MyContextMenu.MenuItems.Add(MySisMenuItem)

    APP.ContextMenu.MenuItems.Add(MyContextMenu)

    Adding Sub procedures to a GisLink Add-In class

    GisLink methods are run inside a Sub procedure which is called from the address of the SisClickHandler (SisRibbonButton or SisMenuItem).

    It is recommended to use Private access for a Sub procedure which is called from the SisClickHandler in the same class.

    The SisClickHandler delegate Sub for GisLink Sub procedures requires parameter declarations for the sender (as Object) and e (as SisClickArgs).

    The functionality level must be set for the public shared SIS property from the SisClickArgs class.

    Private Sub MyCommand(ByVal sender AsObject, ByVal e AsSisClickArgs)

        SIS = e.MapEditor

       Try

            SIS.DoCommand("AComOverlays")

       Catch ex AsException

       EndTry

        SIS.Dispose()

        SIS = Nothing

    End Sub

    Note: It is recommended to put all procedural code in Try…Catch block in order to prevent the SIS process from stalling when a Sub procedure fails.

    Filter

    Named filters are created and assigned to Ribbon control objects in the constructor event of the GisLink Add-In application. The SIS object must be disposed after the creation of a named filter. Otherwise control is not given back to the SIS desktop and the application will hang after start-up. The named filter will be stored in the current NOL. If a named filter is assigned to a SIS Ribbon button, the button will only be available when the selected items pass through the filter. Feature, ClassTree, Layer, and Property type filter can be assigned to the filter property of a SisRibbonButton or SisMenuItem.

    The following example shows the creation of a named class filter for the Area class. The SisRibbonButton will only be enabled when an area item is selected.

    Public Sub New(ByVal SISApplication As SisApplication)

    APP = SISApplication

    SIS.CreateClassTreeFilter("fArea","-Item +Area")

    SIS.Dispose()

    Dim AddInRibbonGroup As SisRibbonGroup = APP.RibbonGroup

    AddInRibbonGroup.Text = "My Add-In"

    Dim myCommandButton As SisRibbonButton = New SisRibbonButton("My Command", New SisClickHandler(AddressOf MyCommand))

    myCommandButton.Help = "Simple descriptive text here"

    myCommandButton.Description = "Detailed description of the use of this command, appears as ToolTip help"

    myCommandButton.LargeImage = True

    myCommandButton.Icon = Nothing

    myCommandButton.Filter ="fArea"

    AddInRibbonGroup.Controls.Add(myCommandButton)

    End Sub

    Top of Page

    Send comments on this topic.

    Click to return to www.cadcorp.com

    © Copyright 2000-2017 Computer Aided Development Corporation Limited (Cadcorp).