<!--
$Source: /cvs/distapps/openmap/doc/sgml/user-guide.sgml,v $
$RCSfile: user-guide.sgml,v $
$Revision: 1.12.8.1 $
$Date: 2004/04/19 13:33:34 $
$Author: bmackiew $

User's Guide for the OpenMap Viewer application.
Launch the viewer with `java com.bbn.openmap.app.OpenMap' or by
running the `openmap' script in the bin/ directory.  Make sure the
openmap.jar file and the omcontrib.jar file are in your Java CLASSPATH
environment variable.  If you get a ClassNotFoundError, the CLASSPATH
is not set up properly.

-->

<!doctype linuxdoc system>

<article>

<title>OpenMap Viewer Application
<author>BBNT Solutions LLC
<date>1 Nov 2001
<abstract>
This document is a user's guide for running the OpenMap Viewer
application.  It assumes that you have already installed the
OpenMap package.  The OpenMap classes are ready to run, but you can
modify the source code and rebuild the code if you like.
</abstract>


<toc>
<p>
The OpenMap Viewer application is our basic MapViewer application.  It
allows you to add, remove, and change the positioning of different
application components and layers, and to navigate over the map.
There are many other applications that use the OpenMap components.  We
encourage you to try out the Viewer and to tweak it to fit your own
needs.


<sect>Launch Scripts
<p>
We've included launch scripts for UNIX and Windows in the
<tt>bin/</tt> subdirectory of the installation.  They are
<tt>openmap</tt> and <tt>openmap.bat</tt>.  If you're running on
Windows, you may need to edit the paths referenced in the
<tt>openmap.bat</tt> script.  These scripts set your
<tt>CLASSPATH</tt> before invoking the Java VM.
<p>
Also, <tt><htmlurl url="http://ant.apache.org"
name="Ant"></tt> can be used to build and launch OpenMap.  The
<tt><htmlurl url="../build.xml" name="build file"></tt> is included in
the OpenMap package.


<sect>Properties File<label id="sec-props">
<p>
The OpenMap Viewer loads properties from an <tt><htmlurl
url="../openmap.properties" name="openmap.properties"></tt> file.  It
searches for this file in two locations: 1) in the JAR file or class
directory, 2) in the user's home directory.  If it finds the file in
any of these places, it loads the properties from it, overriding
previous settings.  We suggest that you copy the
<tt>openmap.properties</tt> file from the openmap directory to your
home directory, and edit the settings to your own liking.


<sect>Running the OpenMap Viewer
<p>
<#if output=html>
<img src="images/openmap.png">
</#if>
<p>
Once the OpenMap Viewer application starts you will see a map of the
Earth with a 10° graticule.

<sect1>Menu Options
<p>
<#if output=html>
<img src="images/menubar.png">
</#if>
<p>
<itemize>
<item>File Menu - This menu has main application controls, and
input/output controls.
	<p>
	<#if output=html>
	<img src="images/file-menu.png">
	</#if>
	<itemize>
	<item><em>About</em> About the underlying OpenMap software.
	<item><em>Save Map...</em> Save the current projection and
	layers in an openmap.properties file.
	<item><em>Load Map...</em> Choose and load an
	openmap.properties file containing settings for a new
	projection and layers.
	<item><em>Save As</em> Save the map as...
	<itemize>
	<item><em>JPEG</em> A JPEG image.
	</itemize>
	<item><em>Quit</em> Quit the map application.
	</itemize>
	<p>
<item>Control Menu - This menu has application controls.
	<p>
	<#if output=html>
	<img src="images/control-menu.png">
	</#if>
	<itemize>
	<item><em>Mouse Mode...</em> Change the mouse behavior.
	<itemize>
	<item><em>Navigate</em> allows you to move around on the map.
	<item><em>Gestures</em> passes mouse events through to layers.
	<item><em>Distance</em> measure distances on the map.
	<item><em>None</em> no actions performed.
	</itemize>
	<item><em>Set Background Color</em> Change the background
	color of the map.
	<item><em>Display Tool Panel</em> Toggles the Tool Panel above
	the map.
	</itemize>
	<p>
<item>Navigate Menu - This menu has map projection controls.
	<p>
	<#if output=html>
	<img src="images/navigate-menu.png">
	</#if>
	<itemize>
	<item><em>Coordinates...</em> Reposition map dialog.
	<item><em>Projection</em> Set the map display projection.
	<item><em>Zoom In</em> Zoom the map in by the specified
	amount.
	<item><em>Zoom Out</em> Zoom the map out by the specified
	amount.
	</itemize>
	<p>
<item>Layers - This menu controls which layers are on the map.
	<p>
	<#if output=html>
	<img src="images/layers-menu.png">
	</#if>
	<itemize>
	<item><em>&lt;Layer1&gt;</em> Select topmost layer on map.
	<item><em>&lt;Layer2&gt;</em> Select next layer.
	<item><em>&lt;...&gt;</em>
	<item><em>&lt;LayerN&gt;</em> Select bottommost layer on map.
	<item><em>Edit Layers...</em> Bring up the layer editor window.
	<item><em>Add Layers...</em> Add and configure a new layer.
	</itemize>
	<p>
<item>Views - This menu controls saved map locations.
	<p>
	<#if output=html>
	<img src="images/view-menu.png">
	</#if>
	<itemize>
	<item><em>Add Saved View...</em> Save the current map
	projection as a view.
	<item><em>&lt;World&gt;</em> Default world view.
	<item><em>&lt;...&gt;</em> Different defined views.
	</itemize>
	<p>
<item>Help
	<p>
	<#if output=html>
	<img src="images/help-menu.png">
	</#if>
	Bring up help in your Web Browser.  This option needs to be
	configured in your <tt><ref id="sec-props"
	name="openmap.properties"></tt> file.
</itemize>

<sect1>Toolbar Options
<p>
<#if output=html>
<img src="images/toolbar.png">
</#if>
<p>
<itemize>
	<item><em>Rosette</em>
	The rosette pans the map in the specified direction and the
	middle button recenters the view to the starting point.
	<item><em>Magnifying Glass +</em>
	Zooms in 2X over the center of the map.
	<item><em>Magnifying Glass -</em>
	Zooms out 2X over the center of the map.
	<item><em>Scale Entry</em>
	Enter the scale of the map.
	<item><em>Layer Panel Button</em> Brings up the layers panel
	to change the order of layers, control layer palettes, and to
	add/remove layers.
	<item><em>Drawing Tool Launcher</em> Draw on the map, and
	choose which layer will receive the graphic.
	<item><em>Overview Map</em> Bring up a smaller map for
	reference and navigation.
	<item><em>Mouse Mode</em> Change the mouse behavior.
	<itemize>
	<item><em>Navigate</em> allows you to move around on the map.
	<item><em>Gestures</em> passes mouse events through to layers.
	<item><em>Distance</em> measure distances on the map.
	<item><em>None</em> no actions performed.
	</itemize>
	<item><em>Projection Stack Buttons</em> Return to the previous
	projection, or move forward to the next one (if defined).
</itemize>

<sect1>Layers Panel Window
<p>
<#if output=html>
<img src="images/layers-window.png">
</#if>
<p>
In addition to adding and removing layers from the map, the Layer
Editor allows you to change their vertical position in relation to
each other, and bring up their specific palette controls.
<p>
<itemize>

<item>
<#if output=html>
<img src="images/layerNotSelected.png">
<img src="images/layerSelected.png">
</#if>
Turn layer off/on.

<item>
<#if output=html>
<img src="images/palette_off.png">
<img src="images/palette_on.png">
</#if>
Turn layer palette (GUI) controls on.  Button reflects if the palette
is active, and the palette has a control button to hide itself.

<item>
<#if output=html>
<img src="images/top.png">
</#if>
Move the selected layer to top of map.

<item>
<#if output=html>
<img src="images/up.png">
</#if>
Move the selected layer up one level in map.

<item>
<#if output=html>
<img src="images/down.png">
</#if>
Move the selected layer down one level in map.

<item>
<#if output=html>
<img src="images/bottom.png">
</#if>
Move the selected layer to bottom of map.

<item>
<#if output=html>
<img src="images/DeleteLayer.png">
</#if>
Delete the selected layer from the application.

<item>
<#if output=html>
<img src="images/AddLayer.png">
</#if>
Bring up a tool to add and configure a layer.

<p>
<#if output=html>
<img src="images/palette.png">
</#if>
<item>
An example of a layer palette.  This palette is for the Graticule
layer, and it lets you modify the layer's behavior.

</itemize>


<sect1>Coordinates Window
<p>
<#if output=html>
<img src="images/coordinates.png">
</#if>
<p>
Specify coordinates in decimal degrees or DMS.  Click apply and the map
will be recentered over the position indicated.


<sect>Extending the Viewer
<p>
A simple way to extend the Viewer is to use different map layers.  You
can add and remove layers by editing the <tt><ref id="sec-props"
name="openmap.properties"></tt> file, or by bringing up the Layers
Panel.  You can also add and remove components from the application by
modifying the openmap.components property in that file.
<p>

The source code for the OpenMap Viewer is the <tt><htmlurl
url="./api/com/bbn/openmap/app/OpenMap.html"
name="com/bbn/openmap/app/OpenMap.java"></tt> file.  It uses the
settings in the <tt><ref id="sec-props"
name="openmap.properties"></tt> file to configure the application at
runtime, using various MapBean components to create the Viewer
application.  You can configure and build your own application by
modifying the openmap.properties file.  If you place a copy of this
file in your home directory on your computer, it will override the
generic copy found in the openmap.jar file.

<p>
Be sure to check the toplevel documentation
<htmlurl url="doc-index.html" name="index"> for information on the OpenMap
core components, including the MapBean, Layer and PlugIn APIs.

</article>
