How to write an OpenMap Layer: Part 2

Introduction

This is the second part of a series of tutorials on writing OpenMap layers. The previous tutorial [hazelnutcafe.net] discussed the implementation of a simple layer, the CenteredDotPlugIn layer. This plugin simply drew a dot in the center of the map no matter what the projection or scale. In this tutorial the developed plugin will be extended with properties, allowing a developer to dictate various aspects of the layer (namely the dot) from within the properties file.

Reading Properties

Adding properties to a plugin layer is a really easy process that is implemented in almost a templated manner. The following code is an updated version of the CenteredDotPlugIn with the hooks added for retrieving properties from the properties file.

CenteredDotPlugIn.java

package net.hazelnutcafe.openmap.plugins;

...
import com.bbn.openmap.util.ColorFactory;

public class CenteredDotPlugIn extends AbstractPlugIn {
    private Color  mColor  = null;
    private String mAuthor = null;
    ...

    public void setProperties(String prefix, Properties props) {
        // Buble the properties up to the highest superclass, then deal with my own
        super.setProperties(prefix, props);

        // Get the scoped prefix of my properties
        String realPrefix = PropUtils.getScopedPropertyPrefix(prefix);

        // Get the author property
        mAuthor = props.getProperty(realPrefix + "author");

        // Get the color property, default to a fully opaque(ff) black(000000)
        mColor  = ColorFactory.parseColorFromProperties(props, realPrefix + "color", "ff000000");
    }

    ...
}

The comments explain what is going on fairly well. The plugin now has two properties, a color and an author, we'll see how these are used in just a bit. Getting string properties is rudimentary as is evident from the author property however, more complex properties (like colors) are a little tricky. Luckily the OpenMap team has provided utility methods to help in parsing these complex properties, namely the ColorFactory and PropUtils utility classes. These implement various color parsing routines and property file handling methods, respectively.

The color property needs a default provided just in case it wasn't specified in the properties file. In this case a fully opaque black is used. The ColorFactory methods can parse both 24 and 32-bit colors from text allowing the developer to choose to use transparency or not. The strings it expects are of the form AARRGGBB (32-bit) or RRGGBB (24-bit), where AA is the transparency, RR red, GG green, and BB blue. Each value is represented in hexadecimal values ranging from 00 (0) to ff (255). So, a fully opaque white would be either "ffffffff" or "ffffff" and a half transparent blue would be "800000ff".

Using Properties

Now that some properties are set within the the plugin they can be used in some novel way, such as (gasp!) setting the color of the drawn dot. The following code illustrates just that.

CenteredDotPlugIn.java

...

    public OMGraphicList getRectangle(Projection p) {
        // Create a new OMGraphicList with room allocated for 1 OMGraphic
        OMGraphicList result = new OMGraphicList(1);

        int x = p.getWidth() / 2;
        int y = p.getHeight() / 2;
        int height = 50;
        int width = 50;

        // Create a new OMGraphic designating an x/y position on the canvas with
        OMCircle graphic = new OMCircle(x, y, width, height);

        // Set the fill paint to the color specified by the color property
        graphic.setFillPaint(mColor);

        // Add the OMGraphic to the resultant array and regenerate the shapes to draw
        result.add(graphic);
        result.regenerate(p);

        // Send back the generated OMGraphicList
        return result;
    }

    ...

Setting Properties

Setting the properties of a layer is just as easy as the initial addition of the layer to the openmap.properties file. As previously stated, the properties file is nothing more than a flat text file containing key = value pairs. Also, a reference for each layer is created in the openmap.layers property and each of these references point to a specific layer class to load and its properties.

openmap.properties

...
...

### OpenMap Layers ###
openmap.layers        = centeredDot graticule shapePolitical
openmap.startUpLayers = centeredDot graticule shapePolitical


### -centeredDot- layer properties
centeredDot.class      = net.hazelnutcafe.openmap.plugins.CenteredDotPlugIn
centeredDot.prettyName = Centered Dot
centeredDot.color      = c000ff00
centeredDot.author     = Guy


### -graticule- layer properties
...

The previous code block showed how to set the two properties the plugin was expecting. Just prepend the plugin reference string (with a dot) to the name of the property and set it equal to something, easy as that!

In this case the color is set to a 75% opaque green and the author is set to the string "Guy". You may be asking yourself what the plugin is doing with the author property. The answer is nothing, it's just here to illustrate setting and retrieving a string property.

Conclusion