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.
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.
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:
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:
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.
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.
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:
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.
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.
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 PropertyHandler is a SoloMapComponent that can search for and parse openmap.properties files, directing certain properties to components that need them.
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.
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.
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:
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:
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.
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.