Programming with .NET FAQ's
|
 |
Question:
How do I develop GISLink applications using .NET?
Answer: The
Cadcorp SIS Map Manager, Cadcorp SIS Map Editor, and Cadcorp SIS Map
Modeller desktop applications can be customised using GisLink to perform
particular tasks, to automate some of the built-in functions of the
system, or to extend the applications’ capabilities in specific
ways.
GisLink is a set of methods that make use of the Windows messaging
system to allow external programs to communicate with Cadcorp SIS
applications.
You can write GisLink customisations using any Windows programming
language that supports COM or .NET components. This article introduces
GisLink programming in the Microsoft Visual Basic.NET environment.
You should refer to the Cadcorp SIS Programming Reference Guide for
full details on GisLink customisation using other programming languages.
A full list of API methods is given in the Programming Reference Guide,
with practical examples of their use.
Getting started
The GisLink module file
The GisLink methods and constants available to programmers are contained
in a file which must be generated from within one of the Cadcorp SIS
desktop products, Cadcorp SIS Map Manager, Cadcorp SIS Map Editor
, and Cadcorp SIS Map Modeller.
To generate the GisLink file:
- Run the Cadcorp SIS application (Cadcorp SIS
Map Manager, Cadcorp SIS Map Editor or Cadcorp SIS Map Modeller)
and choose Program Window from the Tools menu.
- Choose the Generate Programming File
command from the system menu (top left of the in the
Program Window.
- Choose the GisLink option and the appropriate
Visual Basic or .NET version from the drop-down list.
- Fill in the Filename field, using the Browse
button to navigate to the folder where you intend storing the
file. Programmers typically name this file GisLink. If the
.NET option is chosen the file will be given a .vb
extension, while VB6.0 users will see a
.bas extension is given.
- Click OK to generate the file.
You should now add the generated GisLink file to
your new development project:
Select Project>Add Existing Item
and browse to the newly created GisLink.vb file. The .NET environment
automatically takes a copy of the file and adds it to your project
folder.
Cadcorp SIS Map Manager, Cadcorp SIS Map Editor
and Cadcorp SIS Map Modeller offer different levels of functionality,
and therefore different GisLink methods. This means the GisLink files
created by each of the applications will be different. Your programs
will stop with errors if you try to call a Cadcorp SIS Map Editor
or Cadcorp SIS Map Modeller method from a GisLink customisation running
with Cadcorp SIS Map Manager, or a Cadcorp SIS Map Modeller method
when running with Cadcorp SIS Map Editor or Cadcorp SIS Map Manager.
The Startup Form
The 'startup object' of your application must be a form, and it is
the Load event of the startup form which establishes a connection
to the Cadcorp SIS desktop application. This form is used to define
and establish the links between your application and Cadcorp SIS,
and it is suggested that you make this form invisible:
Select Project>Properties… and display
the General tab. Set the Startup Object to the name of your form
in the drop-down list. Click OK.
In the initialization of the form set the Opacity
of the form to 0:
Public Sub New()
MyBase.New()
'This call is required by the Windows Form Designer.
InitializeComponent()
'Add any initialization after the InitializeComponent() call
Me.Opacity = 0
End Sub
Establishing a connection
Your program and Cadcorp SIS communicate using
the Windows handle
of this startup form. Because every form, dialog, and control in Windows
has a unique handle, you are able to run several GisLink customisations
simultaneously, each having its own channel of communication with
Cadcorp SIS.
The connection between the program and the currently running Cadcorp
SIS application is established in the Load event of the startup form
using the SetupLink method:
Private Sub fclsStartup_Load(ByVal sender As
System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
If GisSetupLink(Me.Handle) = 0 Then
MsgBox("Error connecting to SIS application", MsgBoxStyle.Exclamation,
"GisLink")
End
End If
End Sub
The GisSetupLink method broadcasts the startup
form’s handle to the Windows Messaging system. If Cadcorp SIS
is running, it will pick up this message and a link between your program
and Cadcorp SIS is established. The handle to the Cadcorp SIS session
is returned, and you may wish to store this as a global variable for
use elsewhere in your program.
The ListCaps button
When a connection is successfully established,
the Cadcorp SIS application will look for a CommandButton on the startup
form with the Text property set to "ListCaps" (an abbreviation
of ListCapabilities). The name of the button is unimportant, but Text
property must be ListCaps. If Cadcorp SIS detects this button it will
invoke its Click event, running any code you write in this event.
It is in the Click event of this button that you should add the commands,
and perform any other setup specific to your customisation. You may
also choose to remove some commands from the Cadcorp SIS application
user interface.
Cadcorp SIS commands
Whenever a menu option is selected in Cadcorp SIS Map Manager, Cadcorp
SIS Map Editor, and Cadcorp SIS Map Modeller, a command is invoked.
Each of these commands has a name, which users are normally unaware
of. The Program Window which you used to generate the GisLink file
displays these commands when they are selected, enabling programmers
to find the command name and use it within a custom application. All
system command names begin with the letters ACom.
Adding custom commands
Adding commands to the Cadcorp SIS menu bar
GisLink customisations can add custom commands to both the main application
menu and the local (right mouse button) pop-up menu. Custom commands
are added by calling the AddCommand method. Each custom command to
be used by the GisLink customisation must be added in the Click event
of the button captioned ListCaps. Each custom command must have a
corresponding command button on the start-up form, whose Text property
exactly matches the menu$ argument given in the AddCommand method.
The following code registers the custom command Out by 10, which will
appear on the Zoom sub-menu of the Map menu of the Cadcorp SIS application.
Private Sub cmdListCaps_Click(ByVal sender As
System.Object, ByVal e As System.EventArgs) Handles cmdListCaps.Click
GisAddCommand("&Map|&Zoom|Out by 10", "Zoom
Out by a factor of 10", "Item", 0, -1, "",
"")
GisRelease()
End Sub
Notice that Map is prefixed with an ampersand (&),
which indicates that the following letter is to be underscored and
used as the keyboard shortcut. If you want to add commands to the
existing Cadcorp SIS menus, the text used in the GisAddCommand method
must exactly match the text which appears on the Cadcorp SIS menu:
GisAddCommand("&Construct|Geometry &2D|Hexagon",
"Creates a regular hexagon", "Item", 0, -1,
"", "")
Notice that the GisRelease method is called as
the last statement of the procedure. Think of GisRelease as being
the ‘full stop’ (period) at the end of the conversation
with Cadcorp SIS.
For more information about the GisAddCommand method refer to the Cadcorp
SIS Programming Reference Guide.
When the user selects Map>Zoom>Out by 10 from the Cadcorp SIS
menu, GisLink will look for a button with the Text property &Map|&Zoom|Out
by 10 on your startup form. If it finds such a button, it
will invoke its Click event, and perform the code you have written
there, for example:
Private Sub cmdZoomOut_Click(ByVal sender As
System.Object, ByVal e As System.EventArgs) Handles cmdZoomOut.Click
GisZoomView(10)
GisRelease()
End Sub
Adding commands to the Cadcorp SIS pop-up
menu
Commands added to the Cadcorp SIS main menu must
always contain the pipe (|) symbol to define the hierarchy of the
drop-down menu. Commands without this symbol will appear on the local
pop-up menu. If you want to create a hierarchy of commands on the
local pop-up menu, use the hash (#) symbol rather than a pipe (|).
Private Sub cmdListCaps_Click(ByVal sender As
System.Object, ByVal e As System.EventArgs) Handles cmdListCaps.Click
GisAddCommand("Redraw", "Redraw the map",
"Item", 0, -1, "", "")
GisAddCommand("Zoom#In", "Zoom in by 2", "Item",
0, -1, "", "")
GisAddCommand("Zoom#Out", "Zoom out by 2",
"Item", 0, -1, "", "")
GisRelease()
End Sub
When the user selects Zoom>In
from the Cadcorp SIS pop-up menu, GisLink will look for a button with
the Text property Zoom#In on your startup form, and
invoke the click event:
Private Sub cmdPopupZoomIn_Click(ByVal sender
As System.Object, ByVal e As System.EventArgs) Handles cmdPopupZoomIn.Click
GisZoomView(0.5)
GisRelease()
End Sub
You must call the GisRelease method at the end
of the ListCaps_Click, to return control back to the Cadcorp SIS application
user.
Removing system commands
Your customisation can remove system commands,
to simplify the Cadcorp SIS interface presented to the user. System
commands are typically removed (and re-added if necessary) in the
Load event of the startup form, using the AllowCommands method:
' Remove all system commands.
GisAllowCommands(SIS_COM_NONE, "")
' Remove the zoom in and zoom out commands.
GisAllowCommands(SIS_COM_REMOVE, "AComZoomIn2 AComZoomOut")
' Put the zoom in and zoom out commands back.
GisAllowCommands(SIS_COM_ADD, "AComZoomIn2 AComZoomOut")
' Allow all commands available for the current SIS application.
GisAllowCommands(SIS_COM_ALL, "")
Running system commands
Although the GisLink API contains many functions
to perform operations in Cadcorp SIS applications, it is sometimes
easier to invoke one of the system commands than to write code to
produce the same result. Almost all of the commands available to the
user can also be invoked through program code, although some are obviously
more useful than others.
System commands fall into two categories:
- one-shot commands, which perform an action without
user mouse or positional input, such as Map>Redraw)
- callback commands, which require user mouse or
positional input, such as Construct>Geometry 2D>Line)
One-shot commands are run using the CallCommand
method. Callback commands are started using the SwitchCommand method.
For example, the following code starts by calling a one-shot command,
Redraw, then starts drawing a line.
' Redraw the view by command.
GisCallCommand ("AComRedraw")
' Start drawing a line.
GisSwitchCommand ("AComLine")
' Release control back to the user.
GisRelease()
The one-shot redraw command will be started
and completed in the duration of the CallCommand method. However,
the callback command exists beyond the duration of the SwitchCommand
method, in this case until the user presses Enter or Ctrl-Enter
to complete the line, or Escape to quit the command. The progress
of callback commands is monitored using triggers. Refer
to the Cadcorp SIS Programming Reference Guide for full details
on using triggers.
GisLink debugging
ProgramView
The Program Window monitors all GisLink method calls, triggers and
errors, and outputs information about GisLink customisations connected
to the Cadcorp SIS application. Options on the system menu of the
Program Window allow you to switch on and off the method calls,
triggers, and error output. The Program Window has an Always on
Top option that forces it on top of other windows all the time.
When debugging a GisLink customisation, you sometimes need to regain
the control from the customisation, particularly when the customisation
code has failed to call Release. The Stop Waiting option on the
Program Window system menu will immediately return control to the
Cadcorp SIS application. In addition pressing Ctrl-Break will return
control to the Cadcorp SIS application.
API errors
Any errors generated by an API method are output in the Program
Window, and can also be checked in your program. The system variable
_ExecError& contains the error code from the last API method
called. The GisLink file contains a list of the errors that can
occur when using GisLink. To query the last error status, use the
following code:
Dim lError As Integer
lError = GisGetInt(SIS_OT_SYSTEM, 0, "_ExecError&")
'You can query the error directly in the Visual Basic Immediate
window by typing:
Print GisGetInt(SIS_OT_SYSTEM, 0, "_ExecError&")
Refer to the Gislink.vb file and the Cadcorp SIS
Programming Reference Guide for a list of error codes and their meaning.
|
|
|
|
|
Technical
FAQ's |
 |
Not what you are looking for, check out frequently
asked questions (FAQ) about:
More information?
Guide
to Transparency in Cadcorp SIS
Cadcorp
SIS Control Development Modules (CDM) - Questions & Answers
Cadcorp
Positional Accuracy Manager
|
