Geomajas GWT face

Client-server communication in Geomajas is executed through a series of commands instantiated on the client and executed by the server. In the GWT face, all such commands are executed by org.geomajas.gwt.client.command.GwtCommandDispatcher. This class has one single method for instantiating such commands and handling the result: the execute method.

The command, required by the execute method (GwtCommand), is in fact a wrapper around a CommandRequest object (see architecture), wherein the name of the requested command is found. Each command expects a certain implementation of the CommandRequest and CommandResponse objects. Note that these request and response objects must also be known server-side, and thus will not be packaged within the GWT client packages. As additional parameters for the execute method, CommandCallback objects can be passed. These can contain methods to call after successful or unsuccessful completion of the command.

The execution will immediately return a Deferred object, that can be used to add more callback methods, both for successful as for an erroneous result of the command's execution.

        MySuperDoItRequest commandRequest = new MySuperDoItRequest();
        // .... add parameters to the request.

        // Create the command, with the correct Spring bean name:
        GwtCommand command = new GwtCommand("command.MySuperDoIt");
        command.setCommandRequest(commandRequest);

        // Execute the command, and do something with the response:
        GwtCommandDispatcher.getInstance().execute(command, new CommandCallback() {

            public void execute(CommandResponse response) {
                // Command returned successfully. Do something with the result.
            }
        });

As with any GIS framework or application, the most crucial of all entities is the Map. A map is represented by the org.geomajas.gwt.client.widget.MapWidget, but is set up using the standard model-view-controller paradigm. The widget is the actual view of a map, with Painter objects building the display. The user interaction is handled using controllers, represented by the GraphicsController interface. The third aspect, the model, is represented by the org.geomajas.gwt.client.map.MapModel.

2.3. Workflow

A work flow in the GWT face determines how editing should be handled. It can consist of several steps, called activities. When a work flow finishes, changes will typically be persisted. The package is: org.geomajas.gwt.client.map.workflow

Figure 2.1. Workflow API

Activity:

• execute: this method is called by the encompassing processor to execute the activity.

• getErrorHandler: get the error handler that is specifically tuned for the activity.

WorkflowErrorHandler:

• handleError: Executed when an activity throws an exception during execution. The WorkflowProcessor must make sure this method is executed.

WorkflowContext:

• stopProcess: informs the WorkflowProcessor to stop the processing of activities. It is the WorkflowProcessors responsibility to ask for this, and execute no more activities when "true" is returned.

• setSeedData: provide some seed information to the context. This is usually provided at the time of work flow kickoff.

WorkflowProcessor:

• supports: ensure that each activity configured in this process is supported. This method should be called by implemented subclasses for each activity that is part of the process.

• doActivities: this method kicks off the processing of work flow activities.

• setActivities: set a list of activities to be executed in the process. This would also be a good time to check if activities are supported.

• setDefaultErrorHandler: set a default error handler, which is invoked when the activity throws an uncaught exception.

2.4. Selection of features

A feature in a vector layer has the possibility to be selected. Selection usually changes the colour of the feature on the map or in a table to make it stand out. The actual selecting handled by the MapModel. In the map model, the selected features are stored. After all, it is possible that by moving away from a certain area, the selected features are no longer in sight, and perhaps no longer in the client layer-cache. Still their contents may be needed for specific tasks.

The MapModel fires events when changes in selection occur. It will fire either FeatureSelectedEvent or FeatureDeselectedEvent. The MapModel implements the HasFeatureSelectionHandler interface so other components can register with the MapModel as FeatureSelectionHandler. For example the MapWidget will register itself as a handler to know when a feature is selected or deselected and redraw it accordingly.

Figure 2.2. Selection events and handlers

When writing code that needs to react upon the selection of features, implement the FeatureSelectionHandler interface, and register yourself with the MapModel.

Note

Individual vector layers can also fire selection events. Actually the MapModel propagates the events from the individual vector layers, so that the user need only install his handlers in one place.

The spatial package (org.geomajas.gwt.client.spatial) contains a collection of math and geometry related classes and utilities to provide all the client-side calculations one should need. If really complex calculations need to be performed, it's best to let the server (probably using JTS) handle it anyway. The root of the package contains the general mathematical definitions of a Vector, Matrix, LineSegment, and so on. It also provides a general math library and the org.geomajas.gwt.client.spatial.WorldViewTransformer.

The WorldViewTransformer in particular can be a very valuable tool. It allows you to transform coordinates, bounding boxes and geometries between the 3 pre-defined spaces (world, view, pan).

@Api(allMethods = true)
public interface GeometryOperation {

    /**
     * The main edit function. It is passed a geometry object. If other values are needed, pass them through the
     * constructor, or via setters.
     *
     * @param geometry
     *            The {@link Geometry} object to be adjusted.
     * @return Returns the resulting geometry, leaving the original unharmed.
     */
    Geometry execute(Geometry geometry);
}

In the GWT face, the main render method can be found in MapWidget. The render method requires three parameters, a paintable object, a target group to paint in and a status. The paintable object is the actual object that needs to be painted. The target group (org.geomajas.gwt.client.widget.MapWidget.RenderGroup) specifies where in the DOM to draw. The usual choices here are the SCREEN or the WORLD groups. The rendering status (org.geomajas.gwt.client.widget.MapWidget.RenderStatus) determines what drawing action to take.

RenderStatus

The render status can be one of the following:

While rendering, the map uses a visitor to visit the paintable objects recursively and search for painters for each object or sub-object. The "ALL" status will paint recursively while the "UPDATE" status will not go deeper then the given paintable object. Of course, if a given paintable object has no recursive paintable objects, then the difference between "ALL" and "UPDATE" is irrelevant.

RenderGroup

The render group that needs to be specified when calling the map's render method, represents the logical place on the map to draw the paintable object. There are four choices, each having a huge impact.

4.1. GFX interfaces

As will be explained in more detail in the "rendering manual", there are 2 ways of drawing on the map: directly using some rendering context, or indirectly using Paintable objects, Painters and the MapWidget's render method (as explained above). When using the direct approach, one has to call the methods of one of the different rendering contexts. A MapWidget contains a MapContext implementation, which in turn contains 3 different contexts:

• MenuContext: used for keeping details about right mouse clicks. Not used for rendering.

• ImageContext: used for rendering images in HTML. All raster layers use this context.

• GraphicsContext: the main vector graphics renderer. Can also render images, but uses SVG or VML to do so. When rendering shapes, circles, rectangle, etc. you will always be using this context.

Figure 2.3. Main context interfaces from the GFX package

The GraphicsContext is the main vector drawing context. It has two implementations: one for SVG and one for VML.

Figure 2.4. GraphicsContext interface

Every object that appears on a Geomajas map, has to implement the Paintable interface. This interface marks types of objects that can be painted. For each type/class of paintable object, an accompanying Painter must be defined as well. The painter will ultimately decide exactly how a paintable object should be rendered. The painter will render objects using it's paint method, or delete objects from the map using it's deleteShape method.

Figure 2.5. General graphics interfaces

• GraphicsContext: this is the basic drawing interface. Different implementations will draw in different technologies (i.e. SvgGraphicsContext and VmlGraphicsContext). The whole idea of this GraphicsContext and the painters, was inspired by the Java AWT library. This context will draw basic shapes, according to their id. Since we are using web technologies, all implementations (be they SVG or VML) will use DOM elements to create their drawings.

  There are two different kinds of DOM elements we like to distinguish: group elements and non-group elements.

  Group elements are container elements that have no particular representation of themselves but are used to group other elements and create hierarchical dependency. In SVG, they are represented by <g> tags, in VML these are <group> tags. Group elements or groups can be drawn by passing an arbitrary Java object to the drawGroup()method. This object can be used for later reference to the group. To position the group in the hierarchy, a parent group object can be passed as a second parameter to the drawGroup() method.

  Non-group elements (all other elements like circle, rectangle, symbol, etc.) can be drawn by passing a group element - the parent - and a name to the element-specific drawing method (drawCircle(), drawRectangle(), etc.). These elements will be attached to their parent group in the DOM. Each non-group element in the GraphicsContext DOM tree will therefore have a name and a parent group object. This combination of name and parent can later be used to update or delete the object.

  In essence, the drawing methods will result in changes in the visuals of the map, and the painters that will call these methods.

• Paintable: the basic definition of an object that can be painted onto the map. For each Paintable class, an accompanying Painter class must be defined. The Paintable interface has only two methods. The getId method returns the Paintable objects id, which is it's key in the DOM tree within the parent group. While the accept method will be traversed by the PainterVisitor, and is used to have the object passed to the correct Painter, which will draw the object.

• WorldPaintable: extension of the Paintable interface for objects that support being rendered in world space. This means that it should be possible to transform the object's geometry/location/coordinate/bbox.

• Painter: A Painter knows how to paint a specific kind of Paintable object. Exactly what class of Paintable objects it can draw, must be made clear by it's getPaintableClassName method. Furthermore, the Painter has two methods to paint or remove Paintable objects on or from the given GraphicsContext. Basically, the Painter translates the fields and parameters of the Paintable object into calls to the GraphicsContext.

• PainterVisitor: Geomajas uses a visitor algorithm for it's client side rendering process. The MapWidget uses a PainterVisitor to recursively traverse the tree of Paintable objects, calling the accept method on each node.

  Of course this recursive system of searching for the correct Painter, can only work when the PainterVisitor has all the necessary painters registered. When registering a Painter with the MapWidget, it will actually pass it along to this PainterVisitor instance.

  An example of the recursive painting, can be found in the MapModel, which calls the accept methods of it's layers, which call the accept methods of the visible tiles, which contain features.

Rectangle rectangle = new Rectangle("myRectangle");
rectangle.setBounds(new Bbox(10, 10, 200, 200));
rectangle.setStyle(new ShapeStyle("#FF0000", .8f, "#0000FF", .6f, 2));

map.render(rectangle, RenderGroup.SCREEN, RenderStatus.ALL);

map.render(rectangle, RenderGroup.SCREEN, RenderStatus.DELETE);

Rectangle rectangle = new Rectangle("myRectangle");
rectangle.setBounds(new Bbox(-60, -60, 120, 120));
rectangle.setStyle(new ShapeStyle("#FF0000", .8f, "#0000FF", .6f, 2));

// Register the rectangle to the map, so that it gets redrawn
// automatically when the user navigates on the map.
map.registerWorldPaintable(rectangle);

// Create a parent group within screen space:
Composite parent = new Composite("myParent");
map.getVectorContext().drawGroup(map.getGroup(RenderGroup.SCREEN), parent);

// Draw a circle at (20, 20) with radius 10 pixels within parent group:
Coordinate pos = new Coordinate(20, 20);
ShapeStyle style = new ShapeStyle("#FF0000", .8f, "#0000FF", .6f, 2);
map.getVectorContext().drawCircle(parent, "myCircle", pos, 10, style);

// Translate the parent group 100 pixels to the right:
Matrix m = new Matrix(1, 0, 0, 1, 100, 0);
map.getVectorContext().drawGroup(map.getGroup(RenderGroup.SCREEN), parent, m);

This section covers the many interfaces regarding buttons, menu items and such that make up the user interface. The specific Geomajas widgets (i.e. LayerTree) require a specific way of doing things. We will cover the interfaces for the Toolbar, LayerTree, map controllers and context menus.

/**
 * Abstract class that serves as a template for building tool bar actions. A tool bar action is an action that is
 * executed immediately when the tool bar button is clicked. If you want a selectable tool bar button, have a look at
 * the {@link ToolbarModalAction} class.
 *
 * @author Pieter De Graef
 * @since 1.6.0
 */
@Api(allMethods = true)
public abstract class ToolbarAction extends ToolbarBaseAction implements ClickHandler {

    public ToolbarAction(String icon, String tooltip) {
        super(icon, tooltip);
    }
}

/**
 * Abstract class which serves as a template for selectable buttons in a tool bar. These selectable buttons can be
 * selected and deselected. With each of these actions a different method is executed. Usually this type of tool bar
 * button is used to set a new controller onto the {@link org.geomajas.gwt.client.widget.MapWidget}. If you are looking
 * for an action that should be executed immediately when clicking on it, have a look at the
 * {@link org.geomajas.gwt.client.action.ToolbarAction} class.
 *
 * @author Pieter De Graef
 * @since 1.6.0
 */
@Api(allMethods = true)
public abstract class ToolbarModalAction extends ToolbarBaseAction {

    public ToolbarModalAction(String icon, String tooltip) {
        super(icon, tooltip);
    }

    // Class specific actions:

    /**
     * When the tool bar button is selected, this method will be called.
     */
    public abstract void onSelect(ClickEvent event);

    /**
     * When the tool bar button is deselected, this method will be called.
     */
    public abstract void onDeselect(ClickEvent event);
}

public abstract class LayerTreeAction extends ToolbarBaseAction {

    private String disabledIcon;

    /**
     * Constructor setting all values.
     *
     * @param icon The default icon for the button.
     * @param tooltip The default tooltip for the button.
     * @param disabledIcon The icon used when the button is disabled.
     */
    public LayerTreeAction(String icon, String tooltip, String disabledIcon) {
        super(icon, tooltip);
        this.disabledIcon = disabledIcon;
    }

    /**
     * This method will be called when the user clicks on the button.
     *
     * @param layer The currently selected layer.
     */
    public abstract void onClick(Layer<?> layer);

    /**
     * Is the this action enabled for the layer?
     *
     * @param layer layer to test
     * @return enabled status of action for layer
     */
    public abstract boolean isEnabled(Layer<?> layer);

    /**
     * Set icon to display when button is disabled.
     *
     * @return icon shown when the button is disabled
     */
    public String getDisabledIcon() {
        return disabledIcon;
    }

    /**
     * Set icon for disabled state.
     *
     * @param disabledIcon icon for disabled state
     */
    public void setDisabledIcon(String disabledIcon) {
        this.disabledIcon = disabledIcon;
    }
}

/**
 * General definition of a <code>MenuAction</code>. All Geomajas actions in toolbars or context menus should build upon
 * this class.
 *
 * @author Pieter De Graef
 * @since 1.6.0
 */
@Api(allMethods = true)
public abstract class MenuAction extends MenuItem implements ClickHandler {

    /**
     * Constructor that expects you to immediately fill in the title and the icon.
     *
     * @param title
     *            The textual title of the menu item.
     * @param icon
     *            A picture to be used as icon for the menu item.
     */
    protected MenuAction(String title, String icon) {
        super(title, icon);
        addClickHandler(this);
    }
}

/**
 * <p>
 * General interface for a controller set on a {@link org.geomajas.gwt.client.widget.MapWidget}. It should implement all
 * of the available mouse handling events.
 * </p>
 * <p>
 * These controllers can do anything they want with these mouse events, and as a result only one controller can be
 * active on a map at any given time. This is also the difference between controllers and listeners. A
 * <code>Listener</code> passively listens to mouse events without ever interfering with them. Therefore there is no
 * maximum of listeners that can be active on a map at any given time.
 * </p>
 * 
 * @author Pieter De Graef
 * @since 1.6.0
 */
@Api(allMethods = true)
public interface GraphicsController extends MouseDownHandler, MouseUpHandler, MouseMoveHandler, MouseOutHandler,
        MouseOverHandler, MouseWheelHandler, DoubleClickHandler {

    /**
     * Function executed when the controller instance is applied on the map.
     */
    void onActivate();

    /**
     * Function executed when the controller instance is removed from the map.
     */
    void onDeactivate();

    /**
     * An offset along the X-axis expressed in pixels for event coordinates. Used when controllers are placed on
     * specific elements that have such an offset as compared to the origin of the map. Event from such elements have
     * X,Y coordinates relative from their own position, but need this extra offset so that we can still calculate the
     * correct screen and world position.
     * 
     * @since 1.8.0
     */
    int getOffsetX();

    /**
     * An offset along the X-axis expressed in pixels for event coordinates. Used when controllers are placed on
     * specific elements that have such an offset as compared to the origin of the map. Event from such elements have
     * X,Y coordinates relative from their own position, but need this extra offset so that we can still calculate the
     * correct screen and world position.
     * 
     * @param offsetX
     *            Set the actual offset value in pixels.
     * 
     * @since 1.8.0
     */
    void setOffsetX(int offsetX);

    /**
     * An offset along the Y-axis expressed in pixels for event coordinates. Used when controllers are placed on
     * specific elements that have such an offset as compared to the origin of the map. Event from such elements have
     * X,Y coordinates relative from their own position, but need this extra offset so that we can still calculate the
     * correct screen and world position.
     * 
     * @since 1.8.0
     */
    int getOffsetY();

    /**
     * An offset along the Y-axis expressed in pixels for event coordinates. Used when controllers are placed on
     * specific elements that have such an offset as compared to the origin of the map. Event from such elements have
     * X,Y coordinates relative from their own position, but need this extra offset so that we can still calculate the
     * correct screen and world position.
     * 
     * @param offsetY
     *            Set the actual offset value in pixels.
     * @since 1.8.0
     */
    void setOffsetY(int offsetY);
}

    protected Coordinate getScreenPosition(MouseEvent<?> event) {
        return GwtEventUtil.getPosition(event, offsetX, offsetY);
    }

    protected Coordinate getPanPosition(MouseEvent<?> event) {
        return getTransformer().viewToPan(GwtEventUtil.getPosition(event, offsetX, offsetY));
    }

    protected Coordinate getWorldPosition(MouseEvent<?> event) {
        return getTransformer().viewToWorld(GwtEventUtil.getPosition(event, offsetX, offsetY));
    }

    protected Element getTarget(MouseEvent<?> event) {
        return GwtEventUtil.getTarget(event);
    }

    protected String getTargetId(MouseEvent<?> event) {
        return GwtEventUtil.getTargetId(event);
    }

mapWidget.setController(new MeasureDistanceController(mapWidget));

mapWidget.setController(null);

mapWidget.setFallbackController(<the new controller>);

// Define a new Listener, starting from the AbstractListener:
Listener myListener = new AbstractListener() {
    public void onMouseMove(ListenerEvent event) {
        // Do something...
    }
};

// Add the Listener to the map:
mapWidget.addListener(myListener);

// Remove the Listener from the map:
mapWidget.removeListener(myListener);

For internationalization, Geomajas uses the default GWT i18n implementation. For Geomajas specifically, the i18n is used in several places, each having it's own list of messages. Basically all i18n message definitions are located in the package org.geomajas.gwt.client.i18n, as are the properties files containing the translations.

Several separate definitions have been created:

To avoid multiple instantiations of the constants and messages classes and have a central access point for all internationalization concerns, the I18nProvider class has been created. This class has static methods for accessing the constants and messages classes. Usage is as follows:

String dist = I18nProvider.getMenu().getMeasureDistanceString(totalDistance, radius); 
setContents( "<div><b>" + I18nProvider.getMenu().distance() + "</b>:</div><div style='margin-top:5px;'>" + dist + "</div>"); 

A GWT unit test should inherit from the GWTTestcase base class and should be named GwtTestXxx.java. GWT unit tests are run inside a development mode environment and can refer to most of the GWT API. To run a GWT test case, run the Maven command gwt:test or execute the integration test phase.

This functionality has been added to the GWT client API in version 1.9.0.

When working with vector layers, one often has a need for editing not only the vector component of the features, but also the alpha-numerical attributes. To this end, special factories have been created that can be passed to the editing widgets (FeatureAttirbuteEditor and FeatureAttributeWindow) to create such forms.

All interfaces and classes in this section can be found in the following package: org.geomajas.gwt.client.widget.attribute

Central in all this, is the FeatureForm and the FeatureFormFactory. The FeatureFormFactory is an interface that defines a single method for the creation of a FeatureForm instance.

public interface FeatureFormFactory {

   /**
    * Creates a form using the specified attribute information.
    *
    * @param infos
    *           List of attribute definitions. Normally taken from a {@link VectorLayer}.
    * @return An attribute form that allows for editing of it's values.
    */
    FeatureForm createFeatureForm(VectorLayer layer);
}

The default implementation of this factory has been implemented as DefaultFeatureFormFactory. This factory returns a default implementation for the feature form for each layer: DefaultFeatureForm. When the default layout of a feature form is sufficient use the DefaultFeatureFormFactory as is, otherwise feel free to implement your own factory that returns custom instances of a FeatureForm.

The FeatureForm is a form definition that has been tuned towards the Geomajas GWT feature definition, and is used in the central editing widgets (FeatureAttributeEditor and FeatureAttributeWindow). Note that those editing widgets have constructors to accept a FeatureFormFactory, so you have to pass them a custom factory that returns your custom form.

Of course implementing your own FeatureForm might be a bit overwhelming and fortunately is usually not necessary as you can easily extend the DefaultFeatureForm to suit your needs. The DefaultFeatureForm has several hooks to allow you to influence its layout:

Adding new form item types can also be done in a more global way. Therefore, an extra utility class has been added to create the individual form items that represent the feature's attributes. This utility class is the AttributeFormFieldRegistry. This registry keeps a pre-defined set of form item definitions and data source fields (both are necessary to successfully create forms in SmartGWT) that map onto attribute types. For example, it will map a DateItem and DataSourceDateField onto all attributes of type "DATE". This registry can now be used to create the individual items within the form, or to register custom form items types to use in the forms.

In the following sections, the details of registering custom form items and creating custom forms will be explained.

// We define the custom type "myType" in the AttributeFormItemFactory:
        AttributeFormFieldRegistry.registerCustomFormItem("myType", new DataSourceFieldFactory() {

            public DataSourceField create() {
                return new DataSourceIntegerField();
            }
        }, new FormItemFactory() {

            public FormItem create() {
                return new SliderItem();
            }
        }, null);

public class AttributeCustomForm extends DefaultFeatureForm {

 public AttributeCustomForm(VectorLayer vectorLayer) {
  super(vectorLayer);
 }

 @Override
 protected FormItem createItem(AttributeInfo info) {
  FormItem formItem = super.createItem(info); // call super to create the default item
  formItem.setWidth("*");
  if ("dateAttr".equals(info.getName())) {
   // The date attribute will span all 4 columns:
   formItem.setColSpan(4);
  }
  return formItem;
 }

 @Override
 protected void prepareForm(FormItemList formItems, DataSource source) {
  // Quickly insert a row spacer before the 'stringAttr' item (which is the text area).
  formItems.insertBefore("stringAttr", new RowSpacerItem()); // inserting an item via the FormItemList
  getWidget().setNumCols(4);
  getWidget().setWidth(450);
  getWidget().setColWidths(100, 180, 20, 150);
  getWidget().setGroupTitle("Custom Attribute Form");
  getWidget().setIsGroup(true);
 }
}

You have to include the GWT face (client) module. As this is a GWT specific jar, it already includes the source (in many other cases, you would need to explicitly add the sources as well).

<dependency>
    <groupId>org.geomajas</groupId>
    <artifactId>geomajas-gwt-client</artifactId>
</dependency>

You also include the GWT dependencies themselves. Even though these dependencies are already used by the geomajas-gwt-client module, they need to be redefined because of the scopes.

<dependency>
    <groupId>com.google.gwt</groupId>
    <artifactId>gwt-user</artifactId>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>com.google.gwt</groupId>
    <artifactId>gwt-servlet</artifactId>
    <scope>runtime</scope>
</dependency>

These snippets don't include any version info. It is assumed that you use the geomajas-dep module in a recent incarnation to assure these versions are set.

<dependencyManagement>
        <dependency>
            <groupId>org.geomajas</groupId>
            <artifactId>geomajas-dep</artifactId>
            <version>1.10.32</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

If you want to use a snapshot version of the GWT face, you should also included a dependency on the specific snapshot in the dependencyManagement section of your pom.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.geomajas</groupId>
            <artifactId>geomajas-face-gwt</artifactId>
            <version>1.9.0-SNAPS</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.geomajas</groupId>
            <artifactId>geomajas-dep</artifactId>
            <version>1.10.32</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

You need to include the Geomajas GWT service to assure the GWT files can be found. The servlet mapping has to be edited to match your module class's fully qualified name (example here from the geomajas-gwt-simple module).

<servlet>
    <servlet-name>GeomajasServiceServlet</servlet-name>
    <servlet-class>org.geomajas.gwt.server.GeomajasServiceImpl</servlet-class>
</servlet>

<servlet-mapping>
    <servlet-name>GeomajasServiceServlet</servlet-name>
    <url-pattern>/mypackage.GeomajasSimple/geomajasService</url-pattern>
</servlet-mapping>

The GWT compilation needs to be added as one of the build steps. You will need to update the module class and the i18nConstantsWithLookupBundle to match your application.

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>gwt-maven-plugin</artifactId>
    <version>1.2</version>
    <configuration>
        <inplace>true</inplace>
        <module>mypackage.GeomajasSimple</module>
        <runTarget>index.html</runTarget>
        <warSourceDirectory>war</warSourceDirectory>
        <disableCastChecking>true</disableCastChecking>
        <disableClassMetadata>true</disableClassMetadata>
        <extraJvmArgs>-Xmx512M -Xss1024k</extraJvmArgs>
        <i18nConstantsWithLookupBundle>
            mypackage.client.i18n.Simple
        </i18nConstantsWithLookupBundle>
    </configuration>
    <executions>
        <execution>
            <id>test</id>
            <goals>
                <goal>clean</goal>
                <goal>compile</goal>
                <goal>generateAsync</goal>
                <goal>test</goal>
            </goals>
        </execution>
        <execution>
            <id>i18n</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>i18n</goal>
            </goals>
        </execution>
    </executions>
</plugin>

The GraphicsWidget is the basic widget that allows drawing onto a GraphicsContext, and catches mouse events at the same time. It implements the MapContext interface and provides it's own MenuContext implementation. As for the VectorContext, it delegates to a browser specific implementation (VmlGraphicsContext or SvgGraphicsContext). It is also responsible for handling GraphicsControllers (only one global controller at a time!). The reason to place the controller handling here, is because we needed a default GWT widget to handle the events, not a SmartGWT widget. The SmartGWT events do not contain the actual DOM elements for MouseEvents, while the default GWT events do - for some functionality it is absolutely vital that it is well-known which DOM node was the target of an event.

Using the MenuContext, this widget always has the coordinates of the latest right mouse click. Usually the right mouse button is used for drawing context menus. But sometimes it is necessary to have the DOM element onto which the context menu was clicked, to influence this menu. That is why this widget always stores this latest event (or at least it's DOM element id, and screen location).

This widget is the bridge between the internal Svg or Vml rendering in GWT and the SmartGWT widget library. It is used internally in the MapWidget, but is not meant to be used directly by developers.

The main map for any Geomajas application using the GWT face. This widget controls the MapModel, the MapView objects, has an internal GraphicsWidget for the actual rendering, and much more. Being the most central of all widget, the MapWidget has quite a few responsibilities and options.

Map - initialization

A first responsibility of the map is the correct initialization of it's model and all layers from the configuration. When the MapWidget is added to the HTML (onDraw), it will automatically fetch the configuration from the server, and than initialize itself (more precisely, build the MapModel). When this is done, the MapModel will fire a MapModelEvent. Many other widgets wait for this moment to initialize themselves, as they often require the MapModel's contents.

View - rendering

A second responsibility lies in the ability to render shapes. The render() method uses a PainterVisitor to recursively go through Paintable objects and look for the correct Painter. All Painter definitions must be registered in the MapWidget, by means of the registerPainter() and unregisterPainter() methods. Also the full list of WorldPaintables is stored within the MapWidget. For more information regarding the rendering, using the render method, visit the rendering manual.

As an addition of the Paintable objects in screen-space, the definition of a MapAddon has been created as well. MapAddons are self regulating pieces of software that are visible at a certain location on the map (in screen space!), and optionally have attached behaviour. Examples are the Navigation buttons and the scale bar.

Controller

To add interactivity to a map, you can add two types of controllers: the GraphicsController and the GWT MouseWheelHandler. For both it is possible to apply a single instance using the setController() and setMouseWheelController() methods.

Options

On top of the previous list of responsibilities, the map also has a few options that allow certain functionality to be present or not. The following options are standard:

Figure 4.1. MapWidget example

The overview map is an extension of the MapWidget, which keeps the overview of a target MapWidget. It keeps track of the target map's view, and reacts whenever that target map changes it's view. The OverViewMap implements the MapViewChangedHandler to track the changes of it's target map. As it is an extension of a normal MapWidget, it has all the functionality of a normal map. So you can configure layers for an overview map, just as you would for a normal map.

Figure 4.2. OverviewMap example

What can be tricky is to properly configure the bounds of the overview map. In the image above, this is slightly bigger than the world (which in this case is probably not what you want). The bounds for the overview map normally uses the initial bounds as defined on the map. However, when you set the useTargetMapMaxExtent parameter to true when creating the overview map, following locations are checked, using the first which was configured:

The bounds are automatically extended by a percentage. The default is 5%, but this can be configured when creating the overview map.

The Geomajas tool bar is an extension of the SmartGWT ToolStrip widget, and allows for many different widgets to be added to it. A tool bar must be initialized with an instance of the MapWidget it is related to. When the MapWidget has successfully initialized itself, it's MapModel will fire the MapModelEvent saying so. The tool bar reacts on this event by searching in the map configuration for the correct list of tool bar buttons. The map configuration can contain tool ids to indicate the tools which need to be added, together with optional parameters. Using the ToolbarRegistry, which contains the mappings between these ids and the relevant ToolbarAction or ToolbarModalAction classes, the tool bar will initialize itself (for more info; see User Interaction).

Existing tools which can be defined include:

Figure 4.3. Tool bar example

This widget represents a view on the map model which is focused on layers. You see the map layers in a tree, just as they are configured. Accompanied with this view, there are buttons that define certain actions on these layers. Originally there are no buttons in this widget, so they have to be added manually or through configuration. These buttons can either be single actions or selectable buttons (similar to the Toolbar widget - see User Interaction).

Just like the tool bar, the LayerTree waits for the MapModel to be initialized, and also reacts to the MapModelEvent. The layer tree configuration is contained in the map configuration. When the MapModelEvent is fired, the LayerTree will read configuration to know the layer tree structure, which buttons to include,...

Below you see a screen shot of a simple LayerTree where no layer has been selected (and thus all the buttons are disabled):

Figure 4.4. LayerTree example

Once a layer is selected, the LayerTree will ask all buttons whether they should be enabled for that layer. For example, the org.geomajas.gwt.client.action.layertree.LabelAction, which toggles a layer's labels, is only applicable on vector layers, so if the selected layer is a raster layer, that button will remain disabled. The same LayerTree with a selected layer looks like this:

Figure 4.5. LayerTree with selected layer

The LayerTree has few public methods, but it does quite a lot behind the screen. The tree is a SmartGWT TreeGrid, where the LayerTree adds handlers to the nodes and leaves (using LeafClickHandler and FolderClickHandler), which trigger layer selection in the MapModel. The LayerTree also listens to layer selection events, to adjust it's own appearance. For example, when a layer is selected, the proper node has to be selected and all the buttons updated.

The LayerTreeAction and LayerTreeModalAction are also specifically designed to cope with the different stages that they should be able to display. The LayerTreeModalAction can be disabled, enabled and selected or enabled and deselected. For each it is imperative that clear markings are given. This means that different icons are usually used for the different stages. These different icons should be given to the actions at construction time.

Currently the following actions are defined:

The Legend is a graphical widget that shows all styles for the currently visible vector layers. In that sense it is another view on the map model that only shows the style definitions that are currently relevant. Just like the map widget, the legend is built on GraphicsWidget. It reads the available layers from the map model and draws a legend to match the style of these layers.

Figure 4.6. Legend

The FeatureListGrid is a table listing the attributes of features within a single vector layer. Each feature is represented by a row in the grid, with at the top a header that shows the attribute label, as configured in the configuration. As only vector layers can contain features, the grid will be empty for raster layers.

The FeatureListGrid has a few options that determine it's behaviour and appearance:

This table is an extension of the SmartGWT ListGrid widget. It automatically has grouping, filtering and sorting abilities (and much more...). The FeatureListGrid makes it possible to easily display features. You have to set the layer from which to display features. Then you can add features one by one. If no layer is set, then then "addFeature" method will not add any rows to the table. Setting the layer will automatically create the grid header, using the layer's attribute definitions.

Figure 4.7. FeatureListGrid example

The FeatureAttributeWindow is a floating window to display and enable editing of a feature's attributes and persist these changes. This widget is a FeatureAttributeEditor with some extra buttons like "save". When setting a feature, it first makes a clone so you are not editing the feature directly and changes are only applied when the save is clicked. This widget also checks whether or not all fields are valid, and will not allow saving when at least one of the fields is not valid.

The FeatureAttributeWindow has the following options:

Below is a screen shot of a FeatureAttributeWindow with editing allowed but not enabled. Without the editing allowed, there would be now "edit" button. The button itself triggers setting editing enabled.

Figure 4.8. FeatureAttributeWIndow, editing allowed but not enabled

This widget monitors client-server communication traffic, and displays that activity to the end-user. It's purpose is inform the user that a server request is in progress. For example, when the user zooms in, it can sometimes take a few seconds before everything is redrawn. This widget displays that traffic by listening to the GwtCommandDispatcher events. On the screen shot below, you can see the difference between it being passive and active:

Figure 4.9. ActivityMonitor example

Combo box for changing the scale on the map which can be added to a tool bar. It displays a list of possible scales to choose from, but also allows the user to type a specific scale. The scale select is constructed with a MapView as parameter. If this MapView contains pre-configured resolutions (zoom-steps - these can be set in the configuration), than the scale select will allow selection from these scales. If no resolutions are present, the scale select will automatically choose relevant scales to choose from.

Using the setScales() method, one can always override the list of scales in the widget.

Figure 4.10. ScaleSelect example

Widget that supports searching for features on the attributes. Requires a value for manualLayerSelection at construction time. If true, a select box will be shown so the user can select what layer to search in. The possible list of layers consists of all the vector layers that are present in the map model. If false, this widget will search in the currently selected layer.

When the "search" button is indicated, the search will be performed server-side. When the result returns, a SearchEvent is fired. This event holds a reference to the VectorLayer in which the search took place, and a list of all the features that were found. In order to do something with the results (such as displaying in a FeatureListGrid), add a SearchHandler. For the specific case of displaying the feature in a FeatureListGrid, there is a DefaultSearchHandler that already does this.

Note that there is a limit to the number of features that are returned. By default this limit is set to 100. Modify maximumResultSize to change this. Note that a high limit can have a serious impact on performance and memory consumption!

Figure 4.11. FeatureSearch example

Sometimes you will want to redirect the current browser window to another location (different URL). This is the expected behaviour when a user clicks on an external link, for example. When the client is still waiting for outstanding command responses, this can cause warning messages to pop up (default Geomajas behaviour). To avoid such messages, use the following code:

WindowUtil.setLocation("<put your external url here>");