ArcGIS Engine Developer Guide--Ch. 6

164 Pages·2004·3.3 MB·English

6
Developer
scenarios
Throughout this book, you have been introduced to
several programming concepts, patterns, and APIs. This chapter is intended to
apply these concepts by walking you through some application development
scenarios. Each of the scenarios builds and deploys an application using the tools
and APIs available in ArcGIS Engine. Each scenario is available complete as an
ArcGIS developer sample included in the ArcGIS Engine developer kit.
The developer scenarios included are:
• building applications with ActiveX (cid:127) building applications with visual JavaBeans (cid:127)
building applications with Windows Controls (cid:127) building applications with C++ and
Motif widgets (cid:127) building a command-line Java application (cid:127) building a command-
line C++ application
Ch06_DevScenarios.pmd 307 10/18/2004, 12:20 PM
BUILDING APPLICATIONS WITH ACTIVEX
This walkthrough is for developers who want to build and deploy an application
Rather than walk through this scenario, you can using ActiveX. It describes the process of building and deploying an application
get the completed application from the samples using the ArcGIS controls.
installation location. The sample is installed as
part of the ArcGIS developer samples. You can find this sample in:
The ArcGIS developer samples are not included <install_location>\DeveloperKit\Samples\Developer_Guide_Scenarios\
in the typical installation of the ArcGIS Engine ArcGIS_Engine\Building_an_ArcGIS_Control_Application\Map_Viewer
developer kit. If you do not have them installed,
rerun the Developer Kit Install wizard, click PROJECT DESCRIPTION
Custom or Modify, and click the samples feature The goal of this scenario is to demonstrate and familiarize you with the steps
under Software developer kit.
required to develop and deploy a GIS application using the standard ArcGIS
controls within a COM API. This scenario uses the MapControl,
PageLayoutControl, TOCControl, and ToolbarControl as ActiveX Controls
within the Microsoft Visual Basic 6.0 development environment. C++, Java, and
.NET programmers should refer to the following scenarios available later in this
chapter: ‘Building a command-line C++ application’, ‘Building applications with
visual JavaBeans’, ‘Building a command-line Java application’, and ‘Building
applications with Windows Controls’.
This scenario demonstrates the steps required to create a GIS application for
viewing preauthored ESRI map documents, or MXDs. The scenario covers the
following techniques:
• Loading and embedding the ArcGIS controls in Microsoft Visual Basic 6.0
• Loading preauthored map documents into the MapControl and
PageLayoutControl
• Setting ToolbarControl and TOCControl buddy controls
• Handling form resize
• Adding Control commands and tools to the ToolbarControl
• Creating popup menus
• Managing label editing in the TOCControl
• Drawing shapes on the MapControl
• Creating a custom tool to work with the MapControl, PageLayoutControl,
and ToolbarControl
• Customizing the ToolbarControl
• Deploying the application onto a Windows operating system
CONCEPTS
ActiveX is another term for a Microsoft Compo- This scenario is implemented using the Microsoft Visual Basic 6.0 development
nent Object Model object. All of ArcObjects is environment and uses the ArcGIS controls as ActiveX components. ActiveX
based on COM, and the ArcGIS controls are
refers to a set of technologies that enables software components written in
COM objects.
different languages to work together in a networked environment. Each ActiveX
ArcGIS control has events, properties, and methods that can be accessed once the
control is embedded within an ActiveX container such as a Visual Basic form.
The objects and functionality within each control can be combined with other
ESRI ArcObjects and custom controls to create customized end user applications.
308 • ArcGIS Engine Developer Guide
Ch06_DevScenarios.pmd 308 10/18/2004, 12:20 PM
BUILDING APPLICATIONS WITH ACTIVEX
The scenario could have been written in any other COM development environ-
ment that fully supports ActiveX, including Microsoft Visual C++, Borland
Delphi, Sybase PowerBuilder, and Microsoft Visual Basic for Applications. Visual
Basic, while not providing all the functionality of a development environment
such as Visual C++, was chosen because it appeals to a wider audience. Which-
ever development environment you use, your future success with the ArcGIS
controls depends on your skill in both the programming environment and
ArcObjects.
The MapControl, PageLayoutControl, TOCControl, and ToolbarControl are used
in this scenario to provide the user interface of the application. The ArcGIS
controls are used in conjunction with other ArcObjects and control commands by
the developer to create a GIS viewing application.
DESIGN
The scenario has been designed to highlight how the ArcGIS controls interact
with each other and to expose a part of each ArcGIS control’s object model to
the developer.
Each ActiveX ArcGIS control has a set of property pages that can be accessed
once the control is embedded within an ActiveX container. These property pages
provide shortcuts to a selection of a control’s properties and methods and allow a
developer to build an application without writing any code. This scenario does
not use the property pages, but rather builds up the application programmatically.
For further information about the property pages, refer to ArcGIS Developer
Help.
REQUIREMENTS
To successfully follow this scenario you need the following (the requirements for
deployment are covered later in the ‘Deployment’ section):
• An installation of the ArcGIS Engine developer kit with an authorization file
enabling it for development use.
• An installation of the Microsoft Visual Basic 6.0 development environment
and an appropriate license.
• Familiarity with Microsoft Windows operating systems and a working knowl-
edge of Microsoft Visual Basic 6.0. While the scenario provides some informa-
tion about how to use the ArcGIS controls in Microsoft Visual Basic 6.0, it is
not a substitute for training in the development environment.
• While no experience with other ESRI software is required, previous experi-
ence with ArcObjects and a basic understanding of ArcGIS applications, such
The ArcGIS developer samples are not included as ArcMap and ArcCatalog, are advantageous.
in the typical installation of the ArcGIS Engine
developer kit. If you do not have them installed, • Access to the sample data and code that comes with this scenario. This is
rerun the Developer Kit Install wizard, click located at:
Custom or Modify, and click the samples feature
<install_location>\DeveloperKit\Samples\Developer_Guide_Scenarios\
under Software Developer Kit.
ArcGIS_Engine\Building_an_ArcGIS_Control_Application\Map_Viewer
Chapter 6 (cid:127) Developer scenarios (cid:127) 309
Ch06_DevScenarios.pmd 309 10/18/2004, 12:20 PM
BUILDING APPLICATIONS WITH ACTIVEX
The controls and libraries used in this scenario are as follows:
• MapControl • TOCControl
• PageLayoutControl • ToolbarControl
• Carto Object Library • System Object Library
• Display Object Library • SystemUI Object Library
• Geometry Object Library
In Visual Basic, these control and library names are prefixed with ‘esri’.
IMPLEMENTATION
The implementation below provides you with all the code you will need to
successfully complete the scenario. It does not provide step-by-step instructions
to develop applications in Visual Basic 6.0, as it assumes that you have a working
knowledge of the development environment already.
Loading the ArcGIS controls
Before you start to program your application, the ArcGIS controls and the other
ArcGIS Engine library references that the application will use should be loaded
into the development environment.
1. Start Visual Basic and create a new Standard EXE project from the New
project dialog box.
2. Click the Project menu and click Components.
3. In the Components dialog box, check ESRI MapControl, ESRI
PageLayoutControl, ESRI TOCControl, and ESRI ToolbarControl. Click OK.
The ESRI Automatic References Visual Basic Add-
In can be used to quickly select and reference
the ArcGIS controls and other ArcGIS Engine
libraries that you frequently use in Visual
Basic 6.0. To load the add-in click Add-In
Manager from the Add-Ins menu, click ESRI
Automatic References, and check the load
behavior check boxes. To then display the Add-In,
click ESRI Automatic References from the Add-Ins
menu.
ESRIMapControl

ESRIPageLayoutControl
ESRITOCControl
ESRIToolbarControl
The controls will now appear in the Visual Basic toolbox.
310 (cid:127) ArcGIS Engine Developer Guide
Ch06_DevScenarios.pmd 310 10/18/2004, 12:20 PM
BUILDING APPLICATIONS WITH ACTIVEX
4. Click the Project menu again and click References.
5. In the References dialog box, check ESRI Carto Object Library, ESRI Display
Object Library, ESRI Geometry Object Library, ESRI System Object Library,
and ESRI SystemUI Object Library. Click OK.

Embedding the ArcGIS controls in a container
Before you can access each control’s properties, methods, and events, each control
needs embedding within an ActiveX container. Once the controls are embedded
within the form, they will shape the application’s user interface.
1. Open the Visual Basic Form.
2. Double-click the MapControl button in the Visual Basic toolbox to add a
MapControl to a form.
3. Repeat to add the PageLayoutControl, TOCControl, and ToolbarControl.
4. Resize and reposition each control on the form as shown.

Chapter 6 (cid:127) Developer scenarios (cid:127) 311
Ch06_DevScenarios.pmd 311 10/18/2004, 12:20 PM
BUILDING APPLICATIONS WITH ACTIVEX
Loading map documents into the PageLayoutControl and
MapControl
Individual data layers or preauthored ESRI map documents can be loaded into
the MapControl and PageLayoutControl. You can either load the sample map
document provided or you can load your own map document. Later you will add
a dialog box to browse to a map document.
1. Double-click the form to display the code window.
2. Click the Form_Load event and enter the following code. (If you are using
your own map document, substitute the filename.)
Private Sub Form_Load()
' Check and load a preauthored map document into the PageLayoutControl
using relative paths.
Dim sFileName As String
sFileName = "..\..\..\..\..\..\Data\ArcGIS_Engine_Developer_Guide\Gulf
of St. Lawrence.mxd"
If PageLayoutControl1.CheckMxFile(sFileName) Then
PageLayoutControl1.LoadMxFile sFileName
End If
End Sub
3. Click the PageLayoutControl_ OnPageLayoutReplaced event and enter the
following code to load the same map document into the MapControl. The
OnPageLayoutReplaced event will be triggered whenever a document is
loaded into the PageLayoutControl.
Private Sub PageLayoutControl1_OnPageLayoutReplaced(ByVal newPageLayout
As Variant)
' Load the same preauthored map document into the MapControl.
MapControl1.LoadMxFile PageLayoutControl1.DocumentFilename
' Set the extent of the MapControl to the full extent of the data.
MapControl1.Extent = MapControl1.FullExtent
End Sub
Setting the TOCControl and ToolbarControl buddy controls
For the purpose of this application, the TOCControl and ToolbarControl will
work in conjunction with the PageLayoutControl rather than the MapControl. To
do this the PageLayoutControl must be set as the buddy control. The
TOCControl uses the buddy’s ActiveView to populate itself with maps, layers,
and symbols, while any command, tool, or menu items present on the
ToolbarControl will interact with the buddy control’s display.
1. Double-click the form to display the code window.
312 (cid:127) ArcGIS Engine Developer Guide
Ch06_DevScenarios.pmd 312 10/18/2004, 12:20 PM
BUILDING APPLICATIONS WITH ACTIVEX
2. Select the Form_Load event and enter the following after the load document
code:
Private Sub Form_Load()
' Check and load a preauthored map document into the PageLayoutControl
using relative paths.
Dim sFileName As String
sFileName = "..\..\..\..\..\..\Data\ArcGIS_Engine_Developer_Guide\Gulf
of St. Lawrence.mxd"
If PageLayoutControl1.CheckMxFile(sFileName) Then
PageLayoutControl1.LoadMxFile sFileName
End If
' Set buddy controls.
TOCControl1.SetBuddyControl PageLayoutControl1
ToolbarControl1.SetBuddyControl PageLayoutControl1
End Sub
3. Run the application. The map document has been loaded into the
PageLayoutControl, and the TOCControl lists the data layers in the map
document. Use the TOCControl to toggle layer visibility by checking and
unchecking the boxes. By default, the focus map of the map document is
loaded into the MapControl. At this point the ToolbarControl is empty be-
cause no commands have been added to it. Try resizing the form, and note that
the controls do not change size.

Handling form resize
When the form is resized at run time, the PageLayoutControl and MapControl do
not automatically resize themselves. To resize the controls so that they always fill
the extent of the form, you must respond to the Form_Resize event. If the
PageLayoutControl or MapControl contain a lot of data, redrawing this data
during the Form_Resize can be costly. To increase performance you can suppress
the data redraw until the resizing is complete. During the resize a stretched
bitmap will be drawn instead.
Chapter 6 (cid:127) Developer scenarios (cid:127) 313
Ch06_DevScenarios.pmd 313 10/18/2004, 12:20 PM
BUILDING APPLICATIONS WITH ACTIVEX
1. Double-click the form to display the code window.
2. Click the Form_Resize event and enter the following code:
Private Sub Form_Resize()
Dim dWidth As Double, dheight As Double, dMargin As Double
' Set the margin size.
dMargin = TOCControl1.Left
' Resize the PageLayoutControl.
dheight = Form1.ScaleHeight - PageLayoutControl1.Top - dMargin
If dheight > 0 Then PageLayoutControl1.Height = dheight
dWidth = Form1.ScaleWidth - TOCControl1.Width - (dMargin * 2)
If dWidth > 0 Then PageLayoutControl1.Width = dWidth
' Resize the MapControl.
dheight = Form1.ScaleHeight - MapControl1.Top - dMargin
If dheight > 0 Then MapControl1.Height = dheight
End Sub
3. Click the Form_Load event and add the following code at the end of the
procedure:
Private Sub Form_Load()
' Set buddy controls…
' Suppress drawing while resizing.
MapControl1.SuppressResizeDrawing False, Form1.hWnd
PageLayoutControl1.SuppressResizeDrawing False, Form1.hWnd
End Sub
4. Run the application and try resizing the form.
Adding commands to the ToolbarControl
ArcGIS Engine comes with more than 120 commands and tools that work with
the MapControl, the PageLayoutControl, and the ToolbarControl directly. These
commands and tools provide you with a lot of frequently used GIS functionality
for map navigation, graphics management, and feature selection. You will now
add some of these commands and tools to your application.
1. Double-click the form to display the code window.
2. Click the Form_Load event and add the following code before the load docu-
ment code:
Private Sub Form_Load()
Dim sProgID As String
' Add generic commands.
sProgID = "esriControlTools.ControlsOpenDocCommand"
ToolbarControl1.AddItem sProgID, , , False, , esriCommandStyleIconOnly
314 (cid:127) ArcGIS Engine Developer Guide
Ch06_DevScenarios.pmd 314 10/18/2004, 12:20 PM
BUILDING APPLICATIONS WITH ACTIVEX
' Add PageLayout navigation commands.
sProgID = "esriControlTools.ControlsPageZoomInTool"
ToolbarControl1.AddItem sProgID, , , True, , esriCommandStyleIconOnly
sProgID = "esriControlTools.ControlsPageZoomOutTool"
ToolbarControl1.AddItem sProgID, , , False, , esriCommandStyleIconOnly
sProgID = "esriControlTools.ControlsPagePanTool"
ToolbarControl1.AddItem sProgID, , , False, , esriCommandStyleIconOnly
sProgID = "esriControlTools.ControlsPageZoomWholePageCommand"
ToolbarControl1.AddItem sProgID, , , False, , esriCommandStyleIconOnly
sProgID = "esriControlTools.ControlsPageZoomPageToLastExtentBackCommand"
ToolbarControl1.AddItem sProgID, , , False, , esriCommandStyleIconOnly
sProgID = "esriControlTools.ControlsPageZoomPageToLastExtentForwardCommand"
ToolbarControl1.AddItem sProgID, , , False, , esriCommandStyleIconOnly
' Add Map navigation commands.
sProgID = "esriControlTools.ControlsMapZoomInTool"
ToolbarControl1.AddItem sProgID, , , True, , esriCommandStyleIconOnly
sProgID = "esriControlTools.ControlsMapZoomOutTool"
ToolbarControl1.AddItem sProgID, , , False, , esriCommandStyleIconOnly
sProgID = "esriControlTools.ControlsMapPanTool"
ToolbarControl1.AddItem sProgID, , , False, , esriCommandStyleIconOnly
sProgID = "esriControlTools.ControlsMapFullExtentCommand"
ToolbarControl1.AddItem sProgID, , , False, , esriCommandStyleIconOnly
' Load a preauthored…
End Sub
3. Run the application. The ToolbarControl now contains ArcGIS Engine com-
mands and tools that you can use to navigate the map document loaded into
the PageLayoutControl. Use the page layout commands to navigate around the
actual page layout and the map commands to navigate around the data present
in the data frames. Use the open document command to browse and load
other map documents.

Chapter 6 (cid:127) Developer scenarios (cid:127) 315
Ch06_DevScenarios.pmd 315 10/18/2004, 12:20 PM
BUILDING APPLICATIONS WITH ACTIVEX
Creating a popup menu for the PageLayoutControl
In addition to adding control commands to the ToolbarControl to work with the
buddy control, as in the previous step, you can also create popup menus from the
Control commands. You will add a popup menu to your application that works
with the PageLayoutControl. The popup menu will display whenever the right
mouse button is used on the display area of the PageLayoutControl.
1. Add the following code to the general declarations area of the form:
Option Explicit
Private m_pToolbarMenu As IToolbarMenu ' The popup menu
2. Add the following code to the Form_Load event after the code, adding the
commands to the ToolbarControl but before the load document code.
Private Sub Form_Load()
' Add Map navigation commands…
' Create a new ToolbarMenu.
Set m_pToolbarMenu = New ToolbarMenu
' Share the ToolbarControl's command pool.
Set m_pToolbarMenu.CommandPool = ToolbarControl1.CommandPool
' Add commands to the ToolbarMenu.
sProgID = "esriControlTools.ControlsPageZoomInFixedCommand"
m_pToolbarMenu.AddItem sProgID, , , False, esriCommandStyleIconAndText
sProgID = "esriControlTools.ControlsPageZoomOutFixedCommand"
m_pToolbarMenu.AddItem sProgID, , , False, esriCommandStyleIconAndText
sProgID = "esriControlTools.ControlsPageZoomWholePageCommand"
m_pToolbarMenu.AddItem sProgID, , , False, esriCommandStyleIconAndText
sProgID = "esriControlTools.ControlsPageZoomPageToLastExtentBackCommand"
m_pToolbarMenu.AddItem sProgID, , , True, esriCommandStyleIconAndText
sProgID = "esriControlTools.ControlsPageZoomPageToLastExtentForwardCommand"
m_pToolbarMenu.AddItem sProgID, , , False, esriCommandStyleIconAndText
' Set the hook to the PageLayoutControl.
m_pToolbarMenu.SetHook PageLayoutControl1
' Load a preauthored…
End Sub
3. Add the following code to the PageLayoutControl1_OnMouseDown event.
Private Sub PageLayoutControl1_OnMouseDown(ByVal button As Long, ByVal
shift As Long, ByVal x As Long, ByVal y As Long, ByVal pageX As
Double, ByVal pageY As Double)
' Popup the ToolbarMenu.
If button = vbRightButton Then
m_pToolbarMenu.PopupMenu x, y, PageLayoutControl1.hWnd
End If
End Sub
316 (cid:127) ArcGIS Engine Developer Guide
Ch06_DevScenarios.pmd 316 10/18/2004, 12:20 PM