## 4. Using the OpenMap components

There are several application examples available to demonstrate how to use OpenMap components. The OpenMap viewer is an application that can be easily configured to add and remove components, without code modification. This is the best place to start using OpenMap, and the easiest application to customize.

If you are interested in programatically using the components, there are several other examples to demonstrate how to do this by using the MapBean to create passive and interactive maps.

## 4.1 OpenMap Viewer

The OpenMap Viewer example is the default "face" of OpenMap. While it looks like a complex example to start with, it's really a simple framework that uses the MapHandler to add and connect the OpenMap components. See the viewer User's Guide for more information.

You can write your own components that can display your data in the OpenMap Viewer. Once you've written the layer or plugin, all you need to do is to add a reference to it in your openmap.properties file. The OpenMap Viewer reads this file to get configuration information. The properties file has instructions for adding layers and plugins to the application.

Likewise, you can change the look of the application by modifying the openmap.components property in the openmap.properties file. There are instructions in the properties file for modifying this property, but the main point is that changing the application does not require a code change. The components are defined in the openmap.properties file and are connected at runtime.

## 4.2 SimpleMap

This is a very simple example that shows how you use the MapBean and a layer which shows a map of the world. This example uses the MapBean to create a static political map in a window with these steps:

- Create a JFrame window.
- Create a MapBean.
- Create the Political boundary Layer
- Add the Layer to the MapBean.
- Add the MapBean to the ContentPane of the JFrame.
- Show the JFrame window.

## 4.3 SimpleMap2

This example is a little more complicated than the previous one, but is more usable. It shows the same political layer along with a background graticule and a foreground layer which shows hypothetical transportation routes. This RouteLayer is a good example of how to extend the Layer.java class to create your own Layer (More about this later in this document). This example program also includes OpenMap GUI widgets for navigating around on the Map. The steps involved in creating the program are:

- Create a JFrame window.
- Create a MapBean.
- Set the center and scale of the MapBean.
- Create the Political, Graticule, and Route layers.
- Add the layers to the MapBean.
- Create GUI widgets.
- Add the GUI widgets to the ContentPane of the JFrame.
- Add the MapBean to the ContentPane of the JFrame.
- Show the JFrame window.

Since the MapBean is a PanListener and ZoomListener, you can create an object that produces these events and hook it up to the MapBean in order to "drive" the map. The ToolPanel object generates PanEvents and ZoomEvents which are used to control the MapBean.

## 4.4 HelloWorld

The HelloWorld example extends the ideas developed in the SimpleMap2 example. It again uses the MapBean to show a political map of the world, but this time with a blazing "Hello World!" painted over the map. It also incorporates Mouse events to allow point-and-click navigation.

## 4.5 Integrating OpenMap into your own application

You can integrate OpenMap into your own Java application primarily by using the MapHandler, MapBean and Layers. We recommend that you use the OpenMap Viewer application as an example of using the MapHandler, and add the components you need for your application to the MapHandler.

You can use the various Map GUI Beans in your application to control the MapBean. To use them, you need to add them to the MapHandler. Here are some of the main OpenMap components and OpenMap GUI components that can be used in your application:

### LayerHandler

The LayerHandler is a SoloMapComponent that manages the set of layers available to the MapBean. You can add/remove layers in the application, turn them on and off. It also provides layer status information to other GUI widgets like the LayersPanel and LayersMenu.

### MouseDelegator

The MouseDelegator is a SoloMapComponent that uses MapMouseModes to control how mouse movement events are passed to the layers below it. Layers subscribe to the different MapMouseModes, and when the MouseDelegator makes one active, the subscribed layers receive the event and have the opportunity to consume it.

### MouseModes

In Java AWT applications, MouseEvents are sent to components which are MouseListeners when the cursor passes over the component. Because the canvas of the MapBean widget is used by many different layers and other objects, we have slightly restricted this behavior. Instead we've developed the notion of "MouseModes", in which MouseEvents get delivered to listeners registered for a mode only when that mode is active. Because of this, layers are restricted to implementing our MapMouseListener interface instead of the MouseListener interface.

The MapMouseMode interface has been implemented in four default MapMouseModes:

- The NavMouseMode manages MouseEvents that recenter or zoom the MapBean canvas. Other components can register for this mode too, but they should not interfere with the navigation handling:
  - The map is recentered when the mouse is clicked in the window.
  - A click and drag over the window draws a box, which recenters and adjusts the scale of the MapBean canvas to match up with the box.
- The SelectMouseMode passes MouseEvents to layers and other components that have registered under this mode. MouseEvents are passed down the hierarchy until a listener "consumes" the event.
- The DistanceMouseMode draws Great Circle lines on the map, measuring distances between points.
- The NullMouseMode doesn't do anything with mouse events.

### PropertyHandler

The PropertyHandler is a SoloMapComponent that can search for and parse openmap.properties files, directing certain properties to components that need them.

### Environment and Debug

The Environment and Debug classes are static classes that manage different overall functions for applications. The Environment class provides functions for initializing the starting projection, and for figuring out what type of Java environment is being used for the application. The Debug class is used for controlling output. It maintains a table that turns different Debug statements on, and can also direct standard output and error output to log files.

### Customized Menus

Menus can be customized within the OpenMap framework. At the top level is the MenuBar, which is an extension of the Java JMenuBar. This extension is the implementation of the MapHandlerChild methods that let it use the MapHandler to find MenuBarMenus which will be added to the MenuBar in the order in which they are found. The AbstractOpenMapMenu is the MapHandlerChild implementation for menus, and by extending this class menu contents can connect with the other OpenMap components they are controlling. The FileMenu, ControlMenu, NavigateMenu, and GoToMenu can be used as examples of how to write different menus.

### ToolPanel

The ToolPanel is a Component that looks for components implementing the Tool interface. It provides a quick interface to make tools and controls visible and accessable.

Some of the components available are pictured above, and explained below:

- ### OMToolSet

  The OMToolSet is a composite GUI JavaBean, set up to control the view and mouse modes of the MapBean. Any one of its parts may be hidden from view by adjusting its properties:

  - Directional control. Made from the NavigatePanel Bean. This lets you pan the screen in the direction of the button that is pressed.
  - Zoom buttons. Made from the ZoomPanel. This panel has two buttons - the plus (+) button zooms in (increases scale by 2X), and the minus (-) button zooms out (decreases scale by 2X).
  - Scale field window. This shows the current scale setting (1:scale), and also lets you enter a desired scale directly.

- LayersPanel launch button. The LayersPanel is explained here.
- Drawing Tool Launcher. The Drawing Tool lets the users draw different graphics on the map, and direct those graphics to layers or components that can use them. It uses the MapHandler to find these components.
- OverviewMapHandler. The OverviewMapHandler is a self-contained MapBean that provides a reference view of a source MapBean, and also provides control over the MapBean.
- MouseMode Selector. The MouseModePanel provides a way to control the MouseDelegator, choosing the active MapMouseMode.
- Projection Stack buttons. The ProjectionStack remembers past map projections and lets the user go back to preious projections. It also lets the user go forward again.

### InformationDelegator

The InformationDelegator is a JavaBean used for status updates and messages. The NavMouseMode uses the InformationDelegator to display the latitude, longitude, and XY pixel location of the cursor on the MapBean window. Layers can use the InformationDelegator to display one-liners, pop-up messages, and web pages. The colored lights at the right of the widget reflect whether particular layers are working (red) or are finished (green). The lights are buttons that launch the palette for the layer it represents.

### LayersPanel

The LayersPanel is used to manage the display and order of the layers in the MapBean. This panel also lets you bring up and dismiss the GUI controls for a layer, called layer palettes. Some of the buttons act on a `selected' layer. Click on the layer name to select it.

- Move the selected layer to the top of the map.
- The selected layer exchanges position with the one above it.
- The selected layer exchanges position with the one below it.
- Move the selected layer to the bottom of the map.
- Delete the selected layer from the application.
- Add a layer to the application.
- Click this to add the layer to the map.
- Click this to remove the layer from the map.
- The GUI palette for the layer is not active. Click this to display it.
- The GUI palette for the layer is active.