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:

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.

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.

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.

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.