What is a controller?

Using a controller, you can interact with the Map independently of the UI toolkit. Examples of these interactions are:

  • Map navigation

  • Selection

  • Editing the geometry of a feature

The main controller classes

IController

Interface to implement. An IController implementation interprets received events and triggers an action on the map. It receives toolkit-independent events — IInputEvent — and has a LayerList for controller-specific visualization.

IInputEvent

Toolkit-independent events that represent interactions of the user with the view. These events can represent both low-level input events — mouse move, press, or release for example — and more high-level gestures, such as click and drag. The API offers common event types:

  • Dragging

  • Scrolling

  • Key pressed and released

Some events represent mouse interactions:

  • Mouse pressed and released

  • Mouse clicks: sequence of a mouse press and a mouse release.

  • Mouse moves

  • Mouse drags: sequence of a mouse press, one or more mouse moves and a final mouse released.

Some events can represent touch gestures:

  • A tap

  • A long press

  • A two-pointers gesture: aggregates information related to pinch and rotation in the same event

  • A touch-drag event: handles all types of single-point and multiple-point movements on the map, such as a swipe gesture with 2 pointers

If you want to use input in an IController that isn’t available out-of-the-box, you can create a custom IInputEvent implementation.

Event Handlers

Reusable building blocks that use IInputEvent input to perform an action. The API offers basic handlers that you can use for the implementation of a controller. For example:

Map

The LuciadCPillar map can have at most one controller active at any time. You activate the controller using the setController method. When you activate a controller, any controller that was already active gets de-activated first.

How to implement or customize an IController

When you implement an IController, you receive events as parameters of the onEvent method. You can then choose an action to carry out, based on the event type and properties. A convenient way to do that is to pass on the event to an existing event handler or a new one.

The following code snippets from the DefaultController class in the samples show you how you can do that:

Program (C++): Using drag events to pan and rotate the map.
auto mouseDragEvent = std::dynamic_pointer_cast<MouseDragEvent>(inputEvent);
if (mouseDragEvent) {
  auto eventResult = EventResult::NotConsumed;
  if (mouseDragEvent->getModifierKeys() == ModifierKeys::None) {
    if (mouseDragEvent->getMouseButton() == MouseButton::Left) {
      eventResult = _panEventHandler.onDragEvent(mouseDragEvent, map);
    } else if (mouseDragEvent->getMouseButton() == MouseButton::Right) {
      _rotateEventHandler.setYawEnabled(true);
      eventResult = _rotateEventHandler.onDragEvent(mouseDragEvent, map);
    }
  }
  if (eventResult == EventResult::Consumed) {
    return;
  }
}

C#

if (inputEvent is MouseDragEvent mouseDragEvent)
{
    EventResult result = EventResult.NotConsumed;
    if (mouseDragEvent.ModifierKeys == ModifierKeys.None)
    {
        if (mouseDragEvent.MouseButton == MouseButton.Left)
        {
            result = _panEventHandler.OnDragEvent(mouseDragEvent, _map);
        }
        else if (mouseDragEvent.MouseButton == MouseButton.Right)
        {
            _rotateEventHandler.IsYawEnabled = true;
            result = _rotateEventHandler.OnDragEvent(mouseDragEvent, _map);
        }
    }

    if (result == EventResult.Consumed)
    {
        return;
    }
}
Program (C++): Using scroll events with modifier keys to control zoom speed.
auto scrollEvent = std::dynamic_pointer_cast<ScrollEvent>(inputEvent);
if (scrollEvent && (scrollEvent->getModifierKeys() == ModifierKeys::None || scrollEvent->getModifierKeys() == ModifierKeys::Ctrl)) {
  double zoomFactor = scrollEvent->getModifierKeys() == ModifierKeys::Ctrl ? 2.0 : 0.5;
  ZoomEventHandler{}.onScrollEvent(scrollEvent, map, zoomFactor);
}

C#

if (inputEvent is ScrollEvent scrollEvent && (scrollEvent.ModifierKeys == ModifierKeys.None ||
                                              scrollEvent.ModifierKeys == ModifierKeys.Ctrl))
{
    var zoomFactor = scrollEvent.ModifierKeys == ModifierKeys.Ctrl ? 2.0 : 0.5;
    new ZoomEventHandler().OnScrollEvent(scrollEvent, _map, zoomFactor);
}
Program (C++): Handling touch-drag events to pan and rotate the map.
auto touchDragEvent = std::dynamic_pointer_cast<TouchDragEvent>(inputEvent);
if (touchDragEvent) {
  auto eventResult = EventResult::NotConsumed;
  if (touchDragEvent->getTouchPointCount() == 1) { // drag
    eventResult = _panEventHandler.onDragEvent(touchDragEvent, map);
  } else if (touchDragEvent->getTouchPointCount() == 2) {
    // pitch
    if (map->is3D()) {
      _rotateEventHandler.setYawEnabled(false);
      eventResult = _rotateEventHandler.onDragEvent(touchDragEvent, map);
    }
  }
  if (eventResult == EventResult::Consumed) {
    return;
  }
}

C#

if (inputEvent is TouchDragEvent touchDragEvent)
{
    eventResult = EventResult.NotConsumed;
    if (touchDragEvent.TouchPointCount == 1)
    {
        // drag
        eventResult = _panEventHandler.OnDragEvent(touchDragEvent, _map);
    }
    else if (touchDragEvent.TouchPointCount == 2)
    {
        // pitch
        if (_map.Is3D)
        {
            _rotateEventHandler.IsYawEnabled = false;
            eventResult = _rotateEventHandler.OnDragEvent(touchDragEvent, _map);
        }
    }

    if (eventResult == EventResult.Consumed)
    {
        return;
    }
}

How to handle mouse and touch input using the same handler.

The fact that MouseClickEvent and TouchTapEvent are both sub classes of the same superclass (ClickEvent) allows the event consumer to support both mouse and touch inputs the same way. The same remark goes for the MouseDragEvent and the TouchDragEvent that share the same super class: DragEvent.

As an example, the following code snippet allows the user to zoom using a double click or a double tap (used in the DefaultController in the code samples).

Program (C++): Using ClickEvent to capture both mouse click and tap events to zoom the map.
// Using the base class to allow zooming using both double-clicks and double-taps.
const auto clickEvent = std::dynamic_pointer_cast<ClickEvent>(inputEvent);
if (clickEvent && clickEvent->getClickCount() % 2 == 0) {
  ZoomEventHandler{}.onClickEvent(clickEvent, map, true, 0.5);
  return;
}

C#

if (inputEvent is ClickEvent clickEvent && clickEvent.ClickCount % 2 == 0)
{
    new ZoomEventHandler().OnClickEvent(clickEvent, _map, true, 0.5);
    return;
}

How to add visualization to an IController

To respond to some user interactions, you may need to add visual components to the map. For instance, if a user interacts with a map feature to edit it, you need to display editing handles on the feature. Users can then change the feature by manipulating those handles.

If you need to add visual components to the map to respond to user interactions, your controller can implement the getLayerList method. You use it to return a LayerList to visualize controller-specific information such as handles.

If the controller’s layer list is a dedicated one, the map retrieves it when the controller is attached, and appends this list to its own layer list with the controller list on top.

You can also let the controller add a layer to the Map’s LayerList.

Both options have their advantages:

How to integrate IController in a UI toolkit

If you want to use your own UI Toolkit, you must map the toolkit events to IInputEvent instances. Once you have those IInputEvent instances, you can send them to the active IController using the onEvent method.

The API offers utility classes to make this easier: MouseGestureRecognizer and TouchGestureRecognizer. These classes transform low-level UI events, such as move, press, or release, into more high-level IInputEvent objects, such as drag, click or pinch.

The sample integration code also has utility classes that forward Qt or WPF events to gesture recognizers and map the resulting IInputEvent to the active controller:

  • Qt (QML) : QQuickMapObject

  • Qt (QWidget) : QMapWidget

  • WPF : WpfMapControl.

See this article for more information about how to pass Qt events to the gesture recognizers.