libdeng|Widget: Added generic event routing mechanism

A Widget can now be configured to route specific types of events
to a particular widget. This is for the purpose of redirecting, say,
all mouse events temporarily to some widget.

doomsday/libdeng2/include/de/core/event.h

@@ -54,6 +54,8 @@ class DENG2_PUBLIC Event
     int type() const { return _type; }
 
     bool isKeyDown() const { return _type == KeyPress || _type == KeyRepeat; }
+    bool isMouse() const { return _type == MouseButton || _type == MouseMotion ||
+                _type == MousePosition || _type == MouseWheel; }
 
     template <typename Type>
     Type &as() {

doomsday/libdeng2/include/de/widgets/rootwidget.h

@@ -64,7 +64,8 @@ class DENG2_PUBLIC RootWidget : public Widget
 
     /**
      * Sets the focus widget. It is the first widget to be offered input
-     * events.
+     * events. As focus changes from widget to widget, they will be notified of
+     * this via the focusGained() and focusLost() methods.
      *
      * @param widget  Widget to have focus. Set to @c NULL to clear focus.
      */

doomsday/libdeng2/include/de/widgets/widget.h

@@ -25,6 +25,8 @@
 #include "../Event"
 #include "../Id"
 
+#include <QList>
+
 namespace de {
 
 class Widget;
@@ -116,6 +118,21 @@ class DENG2_PUBLIC Widget
     String focusNext() const;
     String focusPrev() const;
 
+    /**
+     * Routines specific types of events to another widget. It will be
+     * the only one offered those events.
+     *
+     * @param types    List of event types.
+     * @param routeTo  Widget to route events to. Caller must ensure
+     *                 that the widget is not destroyed while the
+     *                 routing is in effect.
+     */
+    void setEventRouting(QList<int> const &types, Widget *routeTo);
+
+    void clearEventRouting();
+
+    bool isEventRouted(int type, Widget *to) const;
+
     // Tree organization.
     void clear();
     Widget &add(Widget *child);

doomsday/libdeng2/src/widgets/widget.cpp

@@ -33,6 +33,9 @@ DENG2_PIMPL(Widget)
     String focusNext;
     String focusPrev;
 
+    typedef QMap<int, Widget *> Routing;
+    Routing routing;
+
     typedef QList<Widget *> Children;
     typedef QMap<String, Widget *> NamedChildren;
     Children children;
@@ -173,6 +176,31 @@ String Widget::focusPrev() const
     return d->focusPrev;
 }
 
+void Widget::setEventRouting(QList<int> const &types, Widget *routeTo)
+{
+    foreach(int type, types)
+    {
+        if(routeTo)
+        {
+            d->routing.insert(type, routeTo);
+        }
+        else
+        {
+            d->routing.remove(type);
+        }
+    }
+}
+
+void Widget::clearEventRouting()
+{
+    d->routing.clear();
+}
+
+bool Widget::isEventRouted(int type, Widget *to) const
+{
+    return d->routing.contains(type) && d->routing[type] == to;
+}
+
 void Widget::clear()
 {
     d->clear();
@@ -279,6 +307,12 @@ bool Widget::dispatchEvent(Event const &event, bool (Widget::*memberFunc)(Event
         return false;
     }
 
+    // Routing has priority.
+    if(d->routing.contains(event.type()))
+    {
+        return d->routing[event.type()]->dispatchEvent(event, memberFunc);
+    }
+
     // Tree is traversed in reverse order.
     for(int i = d->children.size() - 1; i >= 0; --i)
     {