## com.bbn.openmap.layer.location
Class Location

    java.lang.Object
      com.bbn.openmap.omGraphics.geom.BasicGeometry
          com.bbn.openmap.omGraphics.OMGraphic
              com.bbn.openmap.layer.location.Location

All Implemented Interfaces:
  java.lang.Cloneable, OMGeometry, OMGraphicConstants, java.io.Serializable

Direct Known Subclasses:
  BasicLocation, ByteRasterLocation, Link, URLRasterLocation

public abstract class Location
extends OMGraphic

A Location is a place. It can be thought of as a lat/lon place, with or without an pixel offset, or a place on the screen. A location is basically thought of as having a name, which get represented as a label, and some graphical represenation. It is abstract because it doesn't really know what kind of markers or labels are being used or how they are being positioned around the particular point. Therefore, it should be extended, and the setGraphicLocations methods implemented to position the marker and text as desired.

See Also:
  Serialized Form

Field Summary
`protected boolean` `allowDecluttering` Set whether you want this location label decluttered.
`protected int` `currentFontDescent`
`static int` `DECLUTTER_ANYWHERE`
`static int` `DECLUTTER_LOCALLY`
`protected int` `declutterLimit` The pixel limit where the delcutter matrix won't draw the name, if it can't put the name at least this close to the original place.
`static int` `DEFAULT_SPACING` the default distance away a label should be placed from a location marker.
`protected java.lang.String` `details` The URL to display when the object is gestured upon.
`LocationHandler` `handler` The LocationHandler that is handling the location.
`protected int` `horizontalLabelBuffer` The horizontal pixel distance you want to place the text away from the actual location - to put space between the graphic.
`protected OMText` `label` The Label of the object.
`float` `lat` The main latitude of object, in decimal degrees, for RENDERTYPE_LATLON and RENDERTYPE_OFFSET locations.
`protected OMGraphic` `location` The simple location marker of the object.
`float` `lon` The main longitude of object, in decimal degrees, for RENDERTYPE_LATLON and RENDERTYPE_OFFSET locations.
`java.lang.String` `name` The name of the location.
`int` `origXLabelOffset` The original offset/x location, kept for resetting the placement of the label after decluttering and/or location placement.
`int` `origYLabelOffset` The original offset/y location, kept for resetting the placement of the label after decluttering and/or location placement.
`protected boolean` `showLocation` The flag for displaying the location marker.
`protected boolean` `showName` The flag for displaying the name label.
`int` `x` The x object location, in pixels, for RENDERTYPE_XY locations.
`int` `xOffset` The x pixel offset from the longitude, for RENDERTYPE_OFFSET locations.
`int` `y` The y object location, in pixels, for RENDERTYPE_XY locations.
`int` `yOffset` The y pixel offset from the latitude, for RENDERTYPE_OFFSET locations.

Fields inherited from class com.bbn.openmap.omGraphics.OMGraphic
`declutterType, displayPaint, edgeMatchesFill, fillPaint, hasLabel, linePaint, matted, mattingPaint, renderType, selected, selectPaint, showEditablePalette, stroke, textureMask`

Fields inherited from class com.bbn.openmap.omGraphics.geom.BasicGeometry
`APP_OBJECT_KEY, appObject, ATT_MAP_KEY, lineType, needToRegenerate, shape, visible`

Fields inherited from interface com.bbn.openmap.omGraphics.OMGraphicConstants

`ADD_GRAPHIC_MASK, BASIC_STROKE, CHANGE_APPEARANCE, clear, DECIMAL_DEGREES, DECLUTTERTYPE_LINE, DECLUTTERTYPE_MOVE, DECLUTTERTYPE_NONE, DECLUTTERTYPE_SPACE, DEFAULT_ROTATIONANGLE, DELETE_GRAPHIC_MASK, DESELECT_GRAPHIC_MASK, DESELECTALL_GRAPHIC_MASK, GRAPHICTYPE_ARC, GRAPHICTYPE_BITMAP, GRAPHICTYPE_CIRCLE, GRAPHICTYPE_ELLIPSE, GRAPHICTYPE_GRAPHIC, GRAPHICTYPE_GRID, GRAPHICTYPE_LINE, GRAPHICTYPE_POINT, GRAPHICTYPE_POLY, GRAPHICTYPE_RASTER, GRAPHICTYPE_RECTANGLE, GRAPHICTYPE_TEXT, INFOLINE, LABEL, LINETYPE_GREATCIRCLE, LINETYPE_RHUMB, LINETYPE_STRAIGHT, LINETYPE_UNKNOWN, LOWER_GRAPHIC_MASK, LOWER_TO_BOTTOM_GRAPHIC_MASK, RADIANS, RAISE_GRAPHIC_MASK, RAISE_TO_TOP_GRAPHIC_MASK, REMOVABLE, RENDERTYPE_LATLON, RENDERTYPE_OFFSET, RENDERTYPE_UNKNOWN, RENDERTYPE_XY, SELECT_GRAPHIC_MASK, SORT_GRAPHICS_MASK, TOOLTIP, UPDATE_GRAPHIC_MASK`

Constructor Summary
`Location()` A plain contructor if you are planning on setting everything yourself.
`Location(float latitude, float longitude, int xOffset, int yOffset, java.lang.String name, OMGraphic locationMarker)` Create a location at a pixel offset from a latitude/longitude.
`Location(float latitude, float longitude, java.lang.String name, OMGraphic locationMarker)` Create a location at a latitude/longitude.
`Location(int x, int y, java.lang.String name, OMGraphic locationMarker)` Create a location at a map location.

Method Summary
`static float` `convertCoordinateString(java.lang.String coord)` A simple conversion method for the common String represention of decimal degree coordinates, which is a letter denoting the globle hemisphere (N or S for latitudes, W or E for longitudes, and then a number string.
`protected void` `declutterLabel(DeclutterMatrix declutter, Projection proj)` Given the label is this location has a height and width, find a clean place on the map for it.
`float` `distance(int x, int y)` Return the shortest distance from the graphic to an XY-point.
`boolean` `generate(Projection proj)` Prepare the graphic for rendering.
`boolean` `generate(Projection proj, DeclutterMatrix declutterMatrix)` Generate the location, and use the declutter matrix to place the label is a spot so that it doesn't interset with other labels.
`int` `getDeclutterLimit()` Get the declutter pixel distance limit.
`java.lang.String` `getDetails()` Get the details for the location.
`int` `getHorizontalLabelBuffer()` Get the pixel distance that the label will be moved to the right, to clear space for the graphic marking the location.
`OMText` `getLabel()` Get the label for the location.
`LocationHandler` `getLocationHandler()` Get the location handler for the location.
`OMGraphic` `getLocationMarker()` Get the location marker for this location.
`java.lang.String` `getName()` Get the name of the location.
`boolean` `isAllowDecluttering()` Get the decluttering allowance setting for this label.
`boolean` `isShowLocation()` See of the location is displaying it's location.
`boolean` `isShowName()` See if the location is displaying it's label.
`static void` `main(java.lang.String[] args)` We're using the main function for Location to test the convertCoordinateString function.
`void` `render(java.awt.Graphics g)` Paint the graphic and the name of the location.
`void` `renderLocation(java.awt.Graphics g)` Paint the graphic location graphic only.
`void` `renderName(java.awt.Graphics g)` Paint the graphic label (name) only.
`void` `setAllowDecluttering(boolean allow)` Set whether you want to allow the label for this location to be decluttered.
`void` `setDeclutterLimit(int value)` Set the pixel distance that us used by the declutter matrix in trying to find a place for the label.
`void` `setDetails(java.lang.String det)` Set the details for the location.
`abstract void` `setGraphicLocations(float latitude, float longitude)`
`abstract void` `setGraphicLocations(float latitude, float longitude, int offsetX, int offsetY)`
`abstract void` `setGraphicLocations(int x, int y)`
`void` `setHorizontalLabelBuffer(int buffer)` Set the pixel distance that the label will be moved to the right, to clear space for the graphic marking the location.
`void` `setLabel(OMText lable)` Set the label for the location.
`void` `setLocation(float latitude, float longitude)` Set the placement of the location.
`void` `setLocation(float latitude, float longitude, int xOffset, int yOffset)` Set the placement of the location.
`void` `setLocation(int x, int y)` Set the placement of the location.
`void` `setLocation(int x, int y, Projection proj)` Convenience method that lets you provide a screen x, y and a projection to the location, and let the location hash out how to place itself based on it's rendertype.
`void` `setLocationHandler(LocationHandler lh)` Set the location handler for the location.
`void` `setLocationMarker(OMGraphic graphic)` Set the graphic for the location.
`void` `setLocationPaint(java.awt.Paint locationPaint)` Set the edge java.awt.Paint for the marker graphic.
`void` `setName(java.lang.String name)` Set the name of this location.
`void` `setShowLocation(boolean showLocations)` Set whether this location should be shown on an individual basis.
`void` `setShowName(boolean showNames)` Set the location to display it's label.
`protected boolean` `shouldRenderLocation()` Convenience method to see if handler/global settings dictate that the location icon should be rendered.
`protected boolean` `shouldRenderName()` Convenience method to see if handler/global settings dictate that the location label should be rendered.
`void` `showDetails(Layer layer)` Fire a browser to display the location details.

Methods inherited from class com.bbn.openmap.omGraphics.OMGraphic

`clone, deselect, getDeclutterType, getDescription, getDescription, getDisplayColor, getDisplayPaint, getEdgeMatchesFill, getFillColor, getFillPaint, getHasLabel, getLineColor, getLinePaint, getMattingPaint, getRenderType, getSelectColor, getSelectPaint, getShowEditablePalette, getStroke, getTextureMask, hasLineTypeChoice, initLabelingDuringGenerate, isClear, isMatted, isSelected, normalizeDistanceForLineWidth, regenerate, renderLabel, select, setDeclutterType, setEdgeMatchesFill, setFillColor, setFillPaint, setGraphicsColor, setGraphicsForEdge, setGraphicsForFill, setHasLabel, setLabelLocation, setLabelLocation, setLabelLocation, setLineColor, setLinePaint, setMatted, setMattingPaint, setRenderType, setSelectColor, setSelected, setSelectPaint, setShape, setShowEditablePalette, setStroke, setTextureMask, shouldRenderEdge, shouldRenderFill`

Methods inherited from class com.bbn.openmap.omGraphics.geom.BasicGeometry

`_distance, appendShapeEdge, appendShapeEdge, appendShapeEdge, appendShapeEdge, checkAttributeMap, checkAttributeMap, clearAttributes, contains, createAttributeMap, createBoxShape, createShape, createShape, describeShapeDetail, describeShapeDetail, distanceToEdge, draw, fill, getAppObject, getAppObject, getAttribute, getAttributeMap, getAttributes, getLineType, getNeedToRegenerate, getShape, isRenderable, isVisible, putAttribute, removeAttribute, replaceAppObjectWithAttributeMap, setAppObject, setAppObject, setAttributes, setLineType, setNeedToRegenerate, setVisible`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface com.bbn.openmap.omGraphics.OMGeometry
`clearAttributes, contains, draw, fill, getAppObject, getAttribute, getAttributes, getLineType, getNeedToRegenerate, getShape, isRenderable, isVisible, putAttribute, removeAttribute, setAppObject, setAttributes, setLineType, setNeedToRegenerate, setVisible`

Field Detail

### lat

    public float lat

  The main latitude of object, in decimal degrees, for RENDERTYPE_LATLON and RENDERTYPE_OFFSET locations.

### lon

    public float lon

  The main longitude of object, in decimal degrees, for RENDERTYPE_LATLON and RENDERTYPE_OFFSET locations.

### xOffset

    public int xOffset

  The x pixel offset from the longitude, for RENDERTYPE_OFFSET locations.

### yOffset

    public int yOffset

  The y pixel offset from the latitude, for RENDERTYPE_OFFSET locations.

### x

    public int x

  The x object location, in pixels, for RENDERTYPE_XY locations.

### y

    public int y

  The y object location, in pixels, for RENDERTYPE_XY locations.

### name

    public java.lang.String name

  The name of the location.

### handler

    public LocationHandler handler

  The LocationHandler that is handling the location. Need this to check for more global settings for rendering.

### DECLUTTER_LOCALLY

    public static final int DECLUTTER_LOCALLY

See Also:
  Constant Field Values

### DECLUTTER_ANYWHERE

    public static final int DECLUTTER_ANYWHERE

See Also:
  Constant Field Values

### label

    protected OMText label

  The Label of the object.

### location

    protected OMGraphic location

  The simple location marker of the object.

### details

    protected java.lang.String details

  The URL to display when the object is gestured upon.

### showLocation

    protected boolean showLocation

  The flag for displaying the location marker.

### showName

    protected boolean showName

  The flag for displaying the name label.

### origYLabelOffset

    public int origYLabelOffset

  The original offset/y location, kept for resetting the placement of the label after decluttering and/or location placement.

### origXLabelOffset

    public int origXLabelOffset

  The original offset/x location, kept for resetting the placement of the label after decluttering and/or location placement.

### DEFAULT_SPACING

    public static final int DEFAULT_SPACING

  the default distance away a label should be placed from a location marker.

  See Also:
    Constant Field Values

### declutterLimit

    protected int declutterLimit

  The pixel limit where the delcutter matrix won't draw the name, if it can't put the name at least this close to the original place. DECLUTTER_LOCALLY keeps the limit to twice the height of the label. DECLUTTER_ANYWHERE will place the thing anywhere it fits. Anything else is the pixel limit.

### allowDecluttering

    protected boolean allowDecluttering

  Set whether you want this location label decluttered.

### horizontalLabelBuffer

    protected int horizontalLabelBuffer

  The horizontal pixel distance you want to place the text away from the actual location - to put space between the graphic.

### currentFontDescent

    protected int currentFontDescent

Constructor Detail

### Location

    public Location()

  A plain contructor if you are planning on setting everything yourself.

### Location

    public Location(float latitude,
                    float longitude,
                    java.lang.String name,
                    OMGraphic locationMarker)

  Create a location at a latitude/longitude. If the locationMarker is null, a small rectangle (dot) will be created to mark the location.

Parameters:
  `latitude` - the latitude, in decimal degrees, of the location.
  `longitude` - the longitude, in decimal degrees, of the location.
  `name` - the name of the location, also used in the label.
  `locationMarker` - the OMGraphic to use for the location mark.

### Location

    public Location(int x,
                    int y,
                    java.lang.String name,
                    OMGraphic locationMarker)

  Create a location at a map location. If the locationMarker is null, a small rectangle (dot) will be created to mark the location.

Parameters:
  `x` - the pixel location of the object from the let of the map.
  `y` - the pixel location of the object from the top of the map
  `name` - the name of the location, also used in the label.
  `locationMarker` - the OMGraphic to use for the location mark.

### Location

    public Location(float latitude,
                    float longitude,
                    int xOffset,
                    int yOffset,
                    java.lang.String name,
                    OMGraphic locationMarker)

  Create a location at a pixel offset from a latitude/longitude. If the locationMarker is null, a small rectangle (dot) will be created to mark the location.

Parameters:
  `latitude` - the latitude, in decimal degrees, of the location.
  `longitude` - the longitude, in decimal degrees, of the location.
  `xOffset` - the pixel location of the object from the longitude.
  `yOffset` - the pixel location of the object from the latitude.
  `name` - the name of the location, also used in the label.
  `locationMarker` - the OMGraphic to use for the location mark.

Method Detail

### setLocation

    public void setLocation(float latitude,
                            float longitude)

  Set the placement of the location.

### setLocation

    public void setLocation(int x,
                            int y)

  Set the placement of the location.

### setLocation

    public void setLocation(float latitude,
                            float longitude,
                            int xOffset,
                            int yOffset)

  Set the placement of the location.

### setLocation

    public void setLocation(int x,
                            int y,
                            Projection proj)

  Convenience method that lets you provide a screen x, y and a projection to the location, and let the location hash out how to place itself based on it's rendertype.

### setGraphicLocations

    public abstract void setGraphicLocations(float latitude,
                                             float longitude)

### setGraphicLocations

    public abstract void setGraphicLocations(int x,
                                             int y)

### setGraphicLocations

    public abstract void setGraphicLocations(float latitude,
                                             float longitude,
                                             int offsetX,
                                             int offsetY)

### setLocationHandler

    public void setLocationHandler(LocationHandler lh)

  Set the location handler for the location.

### getLocationHandler

    public LocationHandler getLocationHandler()

  Get the location handler for the location.

### setLocationPaint

    public void setLocationPaint(java.awt.Paint locationPaint)

  Set the edge java.awt.Paint for the marker graphic.

### getLabel

    public OMText getLabel()

  Get the label for the location.

### setLabel

    public void setLabel(OMText lable)

  Set the label for the location.

### getLocationMarker

    public OMGraphic getLocationMarker()

  Get the location marker for this location.

### setLocationMarker

    public void setLocationMarker(OMGraphic graphic)

  Set the graphic for the location.

### setShowLocation

    public void setShowLocation(boolean showLocations)

  Set whether this location should be shown on an individual basis.

### isShowLocation

    public boolean isShowLocation()

  See of the location is displaying it's location.

### setShowName

    public void setShowName(boolean showNames)

  Set the location to display it's label.

### isShowName

    public boolean isShowName()

  See if the location is displaying it's label.

### getName

    public java.lang.String getName()

  Get the name of the location.

### setName

    public void setName(java.lang.String name)

  Set the name of this location.

### setDetails

    public void setDetails(java.lang.String det)

  Set the details for the location. This should be the contents to be displayed in a web browser.

### getDetails

    public java.lang.String getDetails()

  Get the details for the location.

### showDetails

    public void showDetails(Layer layer)

  Fire a browser to display the location details.

### setAllowDecluttering

    public void setAllowDecluttering(boolean allow)

  Set whether you want to allow the label for this location to be decluttered.

  Parameters:
    `allow` - if true, label will be decluttered if declutter matrix is available.

### isAllowDecluttering

    public boolean isAllowDecluttering()

  Get the decluttering allowance setting for this label.

### setHorizontalLabelBuffer

    public void setHorizontalLabelBuffer(int buffer)

  Set the pixel distance that the label will be moved to the right, to clear space for the graphic marking the location.

### getHorizontalLabelBuffer

    public int getHorizontalLabelBuffer()

  Get the pixel distance that the label will be moved to the right, to clear space for the graphic marking the location.

### generate

    public boolean generate(Projection proj,
                            DeclutterMatrix declutterMatrix)

  Generate the location, and use the declutter matrix to place the label is a spot so that it doesn't interset with other labels.

  Parameters:
    `proj` - projection of the map.
    `declutterMatrix` - DeclutterMatrix for the map.

### setDeclutterLimit

    public void setDeclutterLimit(int value)

  Set the pixel distance that us used by the declutter matrix in trying to find a place for the label. If it can't find a place within this pixel limit, it woun't draw it.

### getDeclutterLimit

    public int getDeclutterLimit()

  Get the declutter pixel distance limit.

### generate

    public boolean generate(Projection proj)

  Prepare the graphic for rendering. This must be done before calling `render()`! If a vector graphic has lat-lon components, then we project these vertices into x-y space. For raster graphics we prepare in a different fashion.

  If the generate is unsuccessful, it's usually because of some oversight, (for instance if `proj` is null), and if debugging is enabled, a message may be output to the controlling terminal.

  Specified by:
    `generate` in interface `OMGeometry`
  Specified by:
    `generate` in class `OMGraphic`
  Parameters:
    `proj` - Projection
  Returns:
    boolean true if successful, false if not.
  See Also:
    `OMGraphic.regenerate(com.bbn.openmap.proj.Projection)`

### render

    public void render(java.awt.Graphics g)

  Paint the graphic and the name of the location. This should only be used if the locations are pretty spread out from each other. If you think you need to declutter, you should render all the graphics, and then render the names, so that the graphics don't cover up the names.

  This paints the graphic into the Graphics context. This is similar to `paint()` function of java.awt.Components. Note that if the graphic has not been generated, it will not be rendered. This render will take into account the layer showNames and showLocations settings.

  Overrides:
    `render` in class `OMGraphic`
  Parameters:
    `g` - Graphics context to render into.

### renderName

    public void renderName(java.awt.Graphics g)

  Paint the graphic label (name) only. This paints the graphic into the Graphics context. This is similar to `paint()` function of java.awt.Components. Note that if the graphic has not been generated, it will not be rendered. This render will take into account the layer showNames and showLocations settings.

  Parameters:
    `g` - Graphics context to render into.

### renderLocation

    public void renderLocation(java.awt.Graphics g)

  Paint the graphic location graphic only. This paints the graphic into the Graphics context. This is similar to `paint()` function of java.awt.Components. Note that if the graphic has not been generated, it will not be rendered. This render will take into account the layer showNames and showLocations settings.

  Parameters:
    `g` - Graphics context to render into.

### shouldRenderName

    protected boolean shouldRenderName()

  Convenience method to see if handler/global settings dictate that the location label should be rendered.

  Returns:
    true if the name label should be rendered.

### shouldRenderLocation

    protected boolean shouldRenderLocation()

  Convenience method to see if handler/global settings dictate that the location icon should be rendered.

  Returns:
    true of the location marker should be rendered.

### distance

    public float distance(int x,
                          int y)

  Return the shortest distance from the graphic to an XY-point.

  Specified by:
    `distance` in interface `OMGeometry`
  Overrides:
    `distance` in class `OMGraphic`
  Parameters:
    `x` - X coordinate of the point.
    `y` - Y coordinate of the point.
  Returns:
    float distance from graphic to the point

### declutterLabel

    protected void declutterLabel(DeclutterMatrix declutter,
                                  Projection proj)

  Given the label is this location has a height and width, find a clean place on the map for it. Assumes label is not null.

  Parameters:
    `declutter` - the DeclutterMatrix for the map.

### convertCoordinateString

    public static float convertCoordinateString(java.lang.String coord)
                                         throws java.lang.NumberFormatException

  A simple conversion method for the common String represention of decimal degree coordinates, which is a letter denoting the globle hemisphere (N or S for latitudes, W or E for longitudes, and then a number string. For latitudes, the first two numbers represent the whole degree value, and the rest of the numbers represent the fractional protion. For longitudes, the first three numbers represent the whole degree value. For instance N2443243 equals 24.43243 degrees North, and S2443243 results in -24.43243 degrees. Likewise, w12423443 results in -124.23443 degrees.

  Parameters:
    `coord` - the coordinate string representing the decimal degree value, following the format [NSEW]XXXXXXXXX.
  Returns:
    the decimal degrees for the string. There is no notation for you to know whether it's a latitude or longitude value.
  Throws:
    `java.lang.NumberFormatException`

### main

    public static void main(java.lang.String[] args)

  We're using the main function for Location to test the convertCoordinateString function.

Copyright (C) BBNT Solutions LLC; See http://openmap.bbn.com/ for details