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