Developing with ArcGIS controls

Transcription

1 3 Developing with ArcGIS controls ArcGIS Engine provides a number of high-level developer controls that enable you to build or extend applications with ArcGIS functionality and create a highquality map-based user interface. These include the MapControl, PageLayoutControl, ReaderControl, TOCControl, ToolbarControl, and LicenseControl. The GlobeControl and SceneControl are also available, but applications using these controls must be authorized with the ArcGIS Engine 3D extension. This chapter includes: an overview of each control a discussion of themes and concepts common to each of the ArcGIS controls considerations for building applications with or without the ToolbarControl.

2 WORKING WITH THE ARCGIS CONTROLS The TOC in TOCControl stands for Table of Contents. A valid ArcGIS Engine Developer Kit license enables you to create applications with all of these controls; however deployment of applications built with either GlobeControl or SceneControl requires both a core ArcGIS license Engine Runtime or Desktop and its corresponding 3D extension license. For more information on deployment of ArcGIS controls-based applications, see Chapter 5, Licensing and deployment. For information on developing with the ArcReaderControl, see the Publisher library overview topic in your ArcGIS Desktop Developer Kit s help system. ArcGIS controls are high-level developer components that enable you to build and extend applications with ArcGIS functionality and provide a graphical user interface. They simplify your development process by encapsulating ArcObjects and providing a coarser-grained API. The controls allow you to easily deploy well-crafted applications with a common look and feel. Each of the controls provided with ArcGIS Engine is available as an ActiveX Control, Motif widget,.net Windows control, and visual JavaBean. They include: MapControl PageLayoutControl ReaderControl ToolbarControl TOCControl LicenseControl SceneControl GlobeControl ArcGIS Desktop developers may also be familiar with the ArcReaderControl. This control is available to ArcGIS Desktop developers who also have the required ArcGIS Publisher extension license. This control is not included with ArcGIS Engine and therefore is not discussed in this book. ABOUT THE CONTROLS This topic discusses methodology and concepts applicable to all of the ArcGIS controls. Later topics in this section discuss specific aspects of each control individually. Embeddable components Each ArcGIS control is an embeddable component that can be dropped within a container form or dialog box provided by a visual design environment. Once within a container the ArcGIS control can be resized and repositioned along with other embeddable components, such as command buttons and combo boxes, to provide a user interface in the application. All properties accessible via the property pages can be set in code by you, the developer. Property pages Each ArcGIS control has a set of property pages that are accessible in most visual design environments, once the control is embedded within a container, by right-clicking the control and clicking Properties from the context menu. These property pages provide shortcuts to a selection of a control s properties and 42 ArcGIS Engine Developer Guide

3 WORKING WITH THE ARCGIS CONTROLS methods and allow you, as a developer, to build an application with little or no code. ArcObjects Each ArcGIS control simplifies the development process by encapsulating coarsegrained ArcObjects while still providing access to finer-grained ArcObjects. For example, the PageLayoutControl encapsulates the PageLayout object. The PageLayout contains at least one MapFrame element containing a Map, and the Map may contain multiple raster, feature, or custom Layer objects. Each ArcGIS control provides shortcuts to frequently used properties and methods on the ArcObjects they encapsulate. For example, the MapControl has a SpatialReference property that is a shortcut to the SpatialReference property of the Map object. Each ArcGIS control also has some helper methods that perform common tasks. For example, the MapControl has an AddShapeFile method. The ArcGIS controls are typically a starting point for developing applications because they provide not only a user interface but also a direct route into the object model. For more details on how the controls work together, see the TOCControl and ToolbarControl section later in this chapter. Events Each ArcGIS control fires events in response to keyboard and mouse interactions by the end user. Other events fire in response to actions occurring within the controls. For example, when a map document is loaded into the MapControl, the OnMapReplaced event is fired, or when an object is dragged over the MapControl via drag and drop, the OnOleDrop event is fired. Buddy Controls The ToolbarControl and TOCControl each work in conjunction with one other buddy control. Typically, the buddy control is a MapControl, PageLayoutControl, ReaderControl, SceneControl, or GlobeControl. The buddy control can be set at design time through the control property pages (in development environments that support property page capability) or programmatically using SetBuddyControl. Map authoring The ArcGIS Desktop applications can be used to preauthor documents that can be loaded into the ArcGIS controls to quickly produce high-quality mapping. For example, ArcMap can be used to author map documents that can be loaded into the MapControl and PageLayoutControl. Preauthoring documents can substantially reduce your development time as it saves having to programmatically build up maps and symbology from scratch. Once a document is loaded into an ArcGIS control, any layer, element, and symbol can be accessed programmatically through the object model if its appearance subsequently needs changing. You can also save the contents of your controls to map documents using the MapDocument class with the MapControl or PageLayoutControl. The documents can then be reopened by the control or by ArcMap. Using this technique it is possible to share documents between your custom application and ArcGIS Desktop. For Chapter 3 Developing with ArcGIS controls 43

4 WORKING WITH THE ARCGIS CONTROLS more information on authoring map documents, see the ArcGIS Desktop Help system. The table below summarizes the types of documents that can be loaded into each ArcGIS control. Map Document (.mxd,.mxt) Layer Files (.lyr) Scene Document (.sxd,.sxt) Globe Document (.3dd,.sdt) no permission to load in a customized application (ArcReader application only Published Map Files (.pmf) permission to load in a customized application permission to load a customized application and unrestricted access to its contents MapControl Yes Yes No No No No Yes PageLayoutControl Yes **Yes No No No No Yes SceneControl No **Yes Yes No No No No GlobeControl No **Yes No Yes No No No ReaderControl No No No No No Yes Yes *ArcReaderControl No No No No No Yes Yes * The ArcReaderControl is only available with the ArcGIS Publisher extension. However, it is listed here due to its similarity to the ReaderControl ** There are no properties available on the ArcGIS controls to directly load Layer (.lyr) files. However, they can be loaded indirectly via the MapDocument object. Application built using the MapControl MAPCONTROL AND PAGELAYOUTCONTROL The MapControl and PageLayoutControl correspond to the data and layout views of the ArcMap desktop application. The MapControl encapsulates the Map object, and the PageLayoutControl encapsulates the PageLayout object. Map documents authored with the ArcMap application can be loaded into the MapControl and PageLayoutControl to avoid programmatically composing the cartography. The map document can be set at design time though the MapControl and PageLayoutControl property pages (in development environments that support property page capability), and the control can be set to link or contain the map document. When linking, the control will read the map document whenever the control is created on the container and will display the most recent updates to the map document. When containing, the control will copy the contents of the map document into the control and will not display any further updates made to the map document from that point onward. Alternatively, a map document can be loaded into Application built using the PageLayoutControl 44 ArcGIS Engine Developer Guide

5 WORKING WITH THE ARCGIS CONTROLS ArcGIS Desktop developers may already be familiar with MapControl and PageLayoutControl since these controls were initially made available in previous ArcGIS Desktop releases. With the release of ArcGIS Engine, these controls have been incorporated into its package of developer components. As in previous releases, ArcGIS Desktop developers can build applications with MapControl or PageLayoutControl even without an ArcGIS Engine license. However, they cannot work with the additional controls provided with ArcGIS Engine unless you have an Engine Developer Kit license. Deployment of applications built with either GlobeControl or SceneControl requires both a core ArcGIS license Engine Runtime or Desktop and its corresponding 3D extension license. For more information on deployment of ArcGIS controls-based applications, see Chapter 5, Licensing and deployment. the control programmatically using the LoadMxFile method. Not only can the MapControl and PageLayoutControl read map documents, they can also write map documents. Both controls implement the IMxdContents interface that enables the MapDocument object to write the contents of the MapControl and PageLayoutControl to a new map document. Helper methods, such as TrackRectangle, TrackPolygon, TrackLine, and TrackCircle, exist on the MapControl for tracking or rubberbanding shapes on the display. The VisibleRegion property can be used to change the shape of the MapControl s display area. Helper methods, such as FindElementByName and LocateFrontElement, exist on the PageLayoutControl to help you manage elements, while the Printer and PrinterPageCount properties, together with the PrintPageLayout method, assist with printing tasks. GLOBECONTROL AND SCENECONTROL The GlobeControl and SceneControl correspond to the 3D views of the ArcGlobe and ArcScene applications. The GlobeControl encapsulates the GlobeViewer object, and the SceneControl encapsulates the SceneViewer object. Globe and Scene documents authored with the ArcGlobe and ArcScene applications can be loaded into the GlobeControl and SceneControl, respectively, to avoid programmatically composing the cartography. Both the GlobeControl and SceneControl have built-in navigation capability that allows the end user to move around the 3D view and visualize the 3D data, without having to use the available control commands or a custom command. To use the built-in navigation, the Navigate property must be set either through the property pages or programmatically. The end user can use the left mouse button to navigate backward and forward and to the left and right of the display and use the right mouse button to zoom in and out on the display. Applications built using the GlobeControl and SceneControl, respectively Chapter 3 Developing with ArcGIS controls 45

6 WORKING WITH THE ARCGIS CONTROLS ArcReader is available for download. To get your free copy, go to A ReaderControl application For more information on the ArcReaderControl, see the Publisher library overview topic in your ArcGIS Desktop Developer Kit s help system. A TOCControl application To link a custom control that you have created to the TOCControl the custom control must implement the ITOCBuddy interface. READERCONTROL The ReaderControl corresponds to the data and layout views of the ArcReader Desktop application, together with its table of contents. The ReaderControl also contains the internal windows and tools used by the ArcReader application, such as the Find window and the Identify tool. Published Map Files (PMF) authored with ArcMap and published with the ArcGIS Publisher extension can be loaded into the ReaderControl, if published with permission to load into a customized ArcReader application. The ReaderControl has a simple self-contained object model that exposes all the functionality of the ArcReader application and does not require access to ArcObjects. As such, developing applications with the ReaderControl does not require previous experience with ArcObjects. However, if a Published Map File was published with unrestricted access to its contents, you can access the underlying ArcObjects and develop with the ReaderControl in a similar way to the MapControl and PageLayoutControl. While the ArcReaderControl is not available with ArcGIS Engine, it is mentioned here due to its similarity with the ReaderControl; the ArcReaderControl has the same simple, self-contained object model as the ReaderControl. However, the ArcReaderControl cannot be used as a buddy control to work in conjunction with the TOCControl or ToolbarControl, nor can you access any underlying ArcObjects components. Developing with the ArcReaderControl requires the ArcGIS Publisher extension, and applications built with the ArcReaderControl can be deployed on any machine that has the free ArcReader application. TOCCONTROL The TOCControl works in conjunction with a buddy control. The buddy control can be a MapControl, PageLayoutControl, ReaderControl, SceneControl, or GlobeControl. The buddy control can be set at design time through the TOCControl property pages (in development environments that support property page capability) or programmatically using the SetBuddyControl method when the container hosting the TOCControl is displayed. Each TOCControl buddy control implements the ITOCBuddy interface. The TOCControl works with the buddy control to display an interactive tree view of its map, layer, and symbology contents and to keep its contents synchronized with the buddy control. For example, if the TOCControl has a MapControl as its buddy, and a map layer is removed from the MapControl, the map layer will also be removed from the TOCControl. Likewise, if the end user interacts with the TOCControl to uncheck a map layer s visibility, the layer will no longer be visible within the MapControl. 46 ArcGIS Engine Developer Guide

7 WORKING WITH THE ARCGIS CONTROLS If you are using JavaBeans, the buddy control can only be set through code as this property is not exposed in the integrated development environment (IDE) property pages. TOOLBARCONTROL The ToolbarControl works in conjunction with a buddy control. The buddy control can be a MapControl, PageLayoutControl, ReaderControl, SceneControl, or GlobeControl. The buddy control can be set at design time through the ToolbarControl property pages (in development environments that support property page capability) or programmatically using the SetBuddyControl method when the container hosting the ToolbarControl is displayed. The ToolbarControl hosts a panel of commands, tools, tool controls, and menus that work with the display of the buddy control. An application that uses the ToolbarControl and the GlobeControl To link a custom control that you have created to the ToolbarControl the custom control must implement the IToolbarBuddy interface. Each ToolbarControl buddy control implements the IToolbarBuddy interface. This interface is used to set the CurrentTool property of the buddy control. For example, imagine a ToolbarControl that is hosting a Page Zoom In tool and has a PageLayoutControl as its buddy. When the end user clicks on the Page Zoom In tool on the ToolbarControl, it will become the CurrentTool of the PageLayoutControl. The implementation of the Page Zoom In tool will query the ToolbarControl to access its buddy control the PageLayoutControl and retrieve the PageLayout. It will then provide the implementation for displaying the rectangle dragged by the end user and changing the extent of the PageLayout. CONTROL COMMANDS ArcGIS Engine provides a set of commands, tools, and menus to work with the ArcGIS controls. For example, there is a map navigation, feature selection, and graphic element commands suite that works with the MapControl and PageLayoutControl. Likewise, there is a suite of commands for the SceneControl, GlobeControl, and ReaderControl. For applications using an individual control, these commands can work directly with the control by programmatically creating a new instance of the command and passing the control to the command s OnCreate event. For applications using the ToolbarControl in conjunction with a buddy control, these commands can be added to the ToolbarControl either through the Chapter 3 Developing with ArcGIS controls 47

8 WORKING WITH THE ARCGIS CONTROLS property pages at design time, programmatically, or at runtime by the end user if the ToolbarControl is in customize mode. You can also extend the suite of commands provided by ArcGIS Engine by creating their own custom commands, tools, and menus to work with the ArcGIS controls. The HookHelper, GlobeHookHelper, and SceneHookHelper objects can be used to simplify this development. Refer to the Building applications scenarios in Chapter 6, Developer scenarios, to see how to build a custom command using the HookHelper object. The LicenseControl is only available with the COM (ActiveX Control) and.net (Windows Control) APIs. Refer to Chapter 5 Licensing and deployment for more details about the concepts of licensing. LICENSECONTROL The LicenseControl is used to initialize an application with a suitable license(s) for it to run successfully on any machine it is deployed on to. The LicenseControl will configure the licenses at application start time when the form or dialog box containing the LicenseControl is loaded. Use the LicenseControl to automatically perform license initialization within simple graphical user interface applications using the MapControl, PageLayoutControl, TOCControl, ToolbarControl, ReaderControl, SceneControl, or GlobeControl. If greater control is required over license initialization, particularly when checking out and in extension licenses (the LicenseControl will check out extension licenses for the duration of an application s life), use the AoInitialize object in the System library to programmatically perform license initialization. The LicenseControl is visible within a visual design environment but is invisible at runtime, so unlike the other controls the LicenseControl does not provide any user interface in an application. In design time the LicenseControl property pages must be used to configure the application with product and extension licenses. Products Select at least one product license with which the application can be initialized. By default, the LicenseControl will try to initialize the application with the ArcGIS Engine product license. If the product you require is not licensed, you may optionally initialize the application with a higher product license. For example, if you select the ArcGIS Engine license and the ArcView license, the 48 ArcGIS Engine Developer Guide

9 WORKING WITH THE ARCGIS CONTROLS LicenseControl will initially try to initialize the application with an ArcGIS Engine license (the lower license). If that license is not available, the LicenseControl will try to initialize the application with an ArcView license (the next higher level license selected). If no product licenses are available, then the application will fail to initialize. Note that once an application is initialized with a product license, it is not possible to reinitialize the application for the duration of the application s life. Extensions Select the extension licenses required by the application. Not every extension license is available with every product license; as such the list of available extension licenses will change as different product licenses become selected. The availability of each extension license is checked in conjunction with the product license with which the application will ultimately be initialized. If any of the selected extensions are not available, the application will fail to initialize. The LicenseControl will check out extensions directly after the application is initialized and will check in extensions when the application is shutdown. If a SceneControl or GlobeControl (requiring the 3D Analyst extension) is embedded within the same container as the LicenseControl, the 3D Analyst extension will automatically be checked. Shutdown Set whether the LicenseControl will automatically shut down the application if license initialization fails. If the LicenseControl handles license initialization failure, a License Failure dialog box will be displayed to the user before the application is shut down. If the developer handles license initialization failure, the LicenseAvailability, Status, and Summary properties can be used to obtain information on the nature of the failure before the application is programmatically shut down. Chapter 3 Developing with ArcGIS controls 49

10 BUILDING APPLICATIONS WITH THE ARCGIS CONTROLS For step-by-step scenarios walking you through the ArcGIS controls development process, refer to the Building applications scenario of your choice in Chapter 6, Developer scenarios. The ArcGIS controls can be used to build applications in two ways: the ArcGIS controls can be embedded into an existing application to add additional mapping capability, or the ArcGIS controls can be used to create a new standalone application. In either case, an individual ArcGIS control can be embedded into an application or the TOCControl and ToolbarControl can be used in conjunction with another ArcGIS control to provide part of the application s framework. The following sections discuss the application development process for the controls both when you are utilizing the ToolbarControl and when you choose not to. APPLICATION DEVELOPMENT USING THE TOOLBARCONTROL The ToolbarControl is typically used in conjunction with a buddy control and a selection of the control commands to quickly provide a functional GIS application. The ToolbarControl is not only providing a part of the user interface; it is also providing a part of the application s framework. ArcGIS Desktop applications, such as ArcMap, ArcGlobe, and ArcScene, have a powerful and flexible framework that includes user interface components such as toolbars, commands, menus, dockable windows, and status bars. This framework enables the end user to customize the application by allowing them to reposition, add, and remove most of these user interface components. Many development environments provide some pieces of a framework in the form of simple dialog boxes, forms, and multiple docking interface (MDI) applications. They also provide generic user interface components such as buttons, status bars, and list boxes. However, a substantial amount of coding can still be required to provide toolbars and menus that host commands, especially if they need to be customized by the end user. The ToolbarControl and the objects within its library can supply pieces of a framework similar to the ArcGIS Desktop application framework. You can use some or all of these framework pieces when building an application with the ToolbarControl. Commands ArcGIS Engine provides several suites of control commands that work with the ArcGIS controls to perform some specific action. You can extend this suite of control commands by creating their own customized commands that perform some specific piece of work. All of these command objects implement the ICommand interface that is used by the ToolbarControl to call methods and access properties at appropriate times. The ICommand::OnCreate method is called shortly after the Command object is hosted on the ToolbarControl. The method is passed a handle or hook to the application with which the command will work. The implementation of a command normally tests to see if the hook object is supported (that is, the command tests to see that the hook is an object that the command can work with). If the hook is not supported, the command disables itself. If the hook is supported, the command stores the hook for later use. For example, if an Open Map Document command is to work with the MapControl or PageLayoutControl, and they are passed to the OnCreate method as the hook, the command will store the hook for later use. If the ToolbarControl is passed to the OnCreate event as the hook, the command would normally check the type of buddy control being used in conjunction 50 ArcGIS Engine Developer Guide

11 BUILDING APPLICATIONS WITH THE ARCGIS CONTROLS The current tool to zoom in on the page A single click command to open a map with the ToolbarControl using the Buddy property. For example, if a command hosted on the ToolbarControl only works with the ReaderControl and the ToolbarControl buddy is a MapControl, the command should disable itself. To help you create custom commands to work with the ArcGIS controls and the ArcGIS Desktop applications, HookHelper, GlobeHookHelper, and SceneHookHelper objects exist. The HookHelper is used for custom commands that work with the MapControl, PageLayoutControl, ToolbarControl, and ArcMap Desktop application. The SceneHookHelper is used for custom commands that work with the SceneControl, ToolbarControl, and ArcScene Desktop application. The GlobeHookHelper is used for custom commands that work with the GlobeControl, ToolbarControl, and ArcGlobe Desktop application. Rather than requiring you to add code into a command s OnCreate method to determine the type of hook passed to the command, the helper object handles this. The helper objects are used to hold onto the hook and return ActiveView, PageLayout, Map, Globe, and Scene objects (depending on the type of helper object) regardless of the type of hook that is passed. Refer to the Building applications scenarios in Chapter 6, Developer scenarios, to see how to build a custom command using the HookHelper object that works with a MapControl, PageLayoutControl, and ToolbarControl. The ICommand::OnClick method is called when the end user clicks a command item hosted on the ToolbarControl. Depending on the type of command, it will typically do some work using the hook to access the required objects from the buddy control. There are three types of commands: A single-click command implementing the ICommand interface that responds to a single click. A click results in a call to the ICommand::OnClick method, and an action is performed. By changing the ICommand::Checked value, simple command items can behave like a toggle. Single-click commands are the only types of commands that can be hosted on a menu. A command item or tool implementing both the ICommand and ITool interfaces that requires end user interaction with the display of the buddy control. The A tool control displaying the current page percentage A menu containing single click map commands ToolbarControl maintains one CurrentTool. When the end user clicks the tool on the ToolbarControl, it becomes the CurrentTool, and the previous tool is deactivated. The ToolbarControl will set the CurrentTool of the buddy control. While the tool is the CurrentTool, it will receive mouse and key events from the buddy control. Chapter 3 Developing with ArcGIS controls 51

12 BUILDING APPLICATIONS WITH THE ARCGIS CONTROLS A command item or tool control implementing both the ICommand and IToolControl interfaces. This is typically a user interface component, such as a Listbox or ComboBox, hosted on the ToolbarControl. The ToolbarControl hosts a small window supplied by a window handle from the IToolControl::hWnd property. Only a single instance of a particular tool control can be added to the ToolbarControl. Commands can be added to ToolbarControl in two ways: by specifying a UID object that uniquely identifies a command (using a Globally Unique Identifier, or GUID) or by supplying an instance of an existing Command object to the AddItem method. Where possible, commands should be added to the ToolbarControl by specifying a UID. If a UID is supplied, the ToolbarControl can identify whether this command has previously been added and, if so, can reuse the previous instance of the command. When an existing instance of a Command object is added to the ToolbarControl, there is no unique identifier for the command, and multiple instances of the same command can exist on the ToolbarControl. ToolbarItem A ToolbarItem is a single command or menu hosted on a ToolbarControl or ToolbarMenu. The IToolbarItem interface has properties to determine the appearance of the item to the end user, for example, whether the item has a vertical line to its left signifying that it begins a Group and whether the Style of the item displays with a bitmap, a caption, or both. The Command and Menu properties return the actual command or menu that the ToolbarItem represents. Updating commands By default, the ToolbarControl updates itself automatically every one-half second to ensure that the appearance of each ToolbarItem hosted on the ToolbarControl is synchronized with the Enabled, Bitmap, and Caption properties of its underlying command. Changing the UpdateInterval property can alter the frequency of the update. An UpdateInterval of 0 will stop any updates from happening automatically, and you must call the Update method programmatically to refresh the state of each ToolbarItem. The first time the Update method is called in an application, the ToolbarControl will check whether the ICommand::OnCreate method of each ToolbarItem s underlying command has been called. If the method has not been called, the ToolbarControl is automatically passed as the hook to the ICommand::OnCreate method. Hosting the ToolbarMenu directly on the ToolbarControl ToolbarMenu The ToolbarControl can host an item that is a dropdown menu. A ToolbarMenu item presents a vertical list of single-click command items. The user must select one of the command items on the ToolbarMenu or click outside the ToolbarMenu to make it disappear. A ToolbarMenu can only host command items; no tools or tool controls are permitted. The ToolbarMenu itself can be hosted on the ToolbarControl, be hosted on 52 ArcGIS Engine Developer Guide

13 BUILDING APPLICATIONS WITH THE ARCGIS CONTROLS another ToolbarMenu as a submenu, or appear as a popup menu and be used for a right-click context menu. Refer to the Building applications scenarios in Chapter 6, Developer scenarios, to see how to build a popup menu hosting some control commands that work with the PageLayoutControl. Hosting thetoolbarmenu as a submenu Hosting the ToolbarMenu as a popup CommandPool Each ToolbarControl and ToolbarMenu has a CommandPool that is used to manage the collection of Command objects that it is using. Normally, you will not interact with the CommandPool. When a command is added to the ToolbarControl either through the property pages of the ToolbarControl or programmatically, the command is automatically added to the CommandPool. Command objects are added to the CommandPool either as a UID object that uniquely identifies the command using a GUID or as an existing instance of a Command object. If an existing instance of a Command object is added, there is no unique identifier for the command, and multiple instances of the same command can exist in the CommandPool. If a UID object is supplied, the CommandPool can identify whether the command already exists in the CommandPool and, if so, can reuse the previous instance of the command. The CommandPool manages this by tracking whether the OnCreate method of a command has been called. If the OnCreate method has been called, it will reuse the command and increment its UsageCount. For example, if a Zoom In tool is added to a ToolbarControl twice, with the UID supplied, when one of the Zoom In items on the ToolbarControl is selected and appears pressed, the other Zoom In item will also appear pressed because they are both using the same Command object. When an application contains multiple ToolbarControls or ToolbarMenus, you should ensure each ToolbarControl and ToolbarMenu uses the same CommandPool so only one instance of a command is created in the application. Customize The ToolbarControl has a Customize property that can be set to put the ToolbarControl into customize mode. This changes the behavior of the ToolbarControl and allows the end user to rearrange, remove, and add items as well as change their appearance. Use the left mouse button to select an item on the ToolbarControl, then either drag the selected item to a new position or drag and drop the item off the ToolbarControl to remove it. Right-click to select an item and display a customize menu. The customize menu can be used to remove the item or change the Style (bitmap, caption, or both) and Grouping of the ToolbarItem. While the ToolbarControl is in customize mode, you can programmatically launch the modeless CustomizeDialog. The CustomizeDialog lists all of the control commands, together with any custom commands, toolsets, and menus. It does this by reading entries from the ESRI Controls Commands, ESRI Controls Chapter 3 Developing with ArcGIS controls 53

14 BUILDING APPLICATIONS WITH THE ARCGIS CONTROLS The modeless CustomizeDialog box for ToolbarControl Toolbars, and ESRI Controls Menus component categories. If required you can change the CustomizeDialog to use alternative component categories. The end user can add these commands, toolsets, and menus to the ToolbarControl either by dragging and dropping them onto the ToolbarControl or double-clicking them. The CustomizeDialog is modeless to allow the user to interact with the ToolbarControl. When the CustomizeDialog is launched with the StartDialog method, the method call returns immediately while the CustomizeDialog remains open on the screen. To keep a reference to the CustomizeDialog while it is open, it is sensible practice to store a class-level variable to the CustomizeDialog and to listen to its ICustomizeDialogEvents. Refer to the Building applications scenarios in Chapter 6, Developer scenarios, to see how to display the CustomizeDialog when the ToolbarControl is in customize mode. OperationStack The ToolbarControl has an OperationStack that is used to manage undo and redo functionality. Operations are added to the operation stack by each ToolbarItem s underlying command so the operation can be rolled forward and rolled back as desired. For example, when a graphic element is moved, the operation can be undone by moving the graphic back to its original location. Whether or not a command makes use of an OperationStack depends on its implementation. Typically, you create a single ControlsOperationStack for an application (by default, the OperationStack property is Nothing) and sets it into each ToolbarControl. Undo and Redo commands can be added to the ToolbarControl that proceed through the OperationStack. APPLICATION DEVELOPMENT WITHOUT THE TOOLBARCONTROL While building applications with the ToolbarControl can quickly provide pieces of a framework similar to the ArcGIS Desktop application framework, there are times when the ToolbarControl is not required for an application: The visual appearance of the ToolbarControl may not match that of the application. The overhead of implementing Command objects for the ToolbarControl is not required. There is an existing application framework present in the application. The ToolbarControl and the commands it hosts do not easily work across multiple buddy controls. In such circumstances, you must work directly with the MapControl, PageLayoutControl, SceneControl, GlobeControl, or ReaderControl. Any additional user interface components needed by the application, such as command buttons, status bars, and list boxes, may be supplied by development environment. 54 ArcGIS Engine Developer Guide

15 BUILDING APPLICATIONS WITH THE ARCGIS CONTROLS For example, building map navigation functionality into a MapControl application can be achieved by: Setting the resulting Envelope of the IMapControl2::TrackRectangle method into the IMapControl2::Extent property within the MapControl s OnMouseDown event to create Zoom In functionality. Setting the Envelope of the IMapControl2::FullExtent property into the IMapControl2::Extent property to create Full Extent functionality. This code could be placed within the Click event of a command button supplied by the development environment. Alternatively, the control commands that are provided with ArcGIS Engine, or any custom commands that make use of the HookHelper, SceneHookHelper, or GlobeHookHelper objects, will work directly with an individual ArcGIS control. However, you become responsible for calling ICommand::OnCreate and ICommand::OnClick methods at the appropriate times and reading properties on the ICommand interface to build up the user interface as follows: A new instance of a command is created programmatically, and the individual ArcGIS control is passed to the OnCreate event. For example, if the 3D Zoom FullExtent command is to work with the GlobeControl, the GlobeControl must be passed as the hook to the OnCreate method. You can use the CommandPool object without the ToolbarControl to manage the commands used by an application. The CommandPool will provide support for calling the OnCreate method of each command based on its Hook property. If the command only implements the ICommand interface, you can call the OnClick method at the appropriate time to perform the specific action. If the command is a tool that implements both the ICommand and ITool interfaces, you must set the tool to be the CurrentTool in the ArcGIS control. The ArcGIS control will send any keyboard and mouse events to the tool. A command s Enabled, Caption, and Bitmap properties can be read and set into the properties of a command button supplied by the development environment to build up the user interface of the application. While this approach to building applications requires more programming, building from scratch does allow more flexibility. Chapter 3 Developing with ArcGIS controls 55

16