libappfw: Added Untrapper for mouse untrapping convenience

doomsday/libappfw/include/de/Untrapper

@@ -0,0 +1,2 @@
+#include "framework/untrapper.h"
+

doomsday/libappfw/include/de/framework/untrapper.h

@@ -0,0 +1,47 @@
+/** @file untrapper.h  Mouse untrapping utility.
+ *
+ * @authors Copyright (c) 2014 Jaakko Keränen <jaakko.keranen@iki.fi>
+ *
+ * @par License
+ * LGPL: http://www.gnu.org/licenses/lgpl.html
+ *
+ * <small>This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or (at your
+ * option) any later version. This program is distributed in the hope that it
+ * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+ * General Public License for more details. You should have received a copy of
+ * the GNU Lesser General Public License along with this program; if not, see:
+ * http://www.gnu.org/licenses</small>
+ */
+
+#ifndef LIBAPPFW_UNTRAPPER_H
+#define LIBAPPFW_UNTRAPPER_H
+
+#include "../libappfw.h"
+#include <de/CanvasWindow>
+
+namespace de {
+
+/**
+ * Utility for untrapping the mouse. The mouse is untrapped from the specified window for
+ * the lifetime of the Untrapper instance. When Untrapper is destroyed, mouse is
+ * automatically trapped if it originally was trapped.
+ */
+class LIBAPPFW_PUBLIC Untrapper
+{
+public:
+    /**
+     * Mouse is untrapped if it has been trapped in @a window.
+     * @param window  Window where (un)trapping is done.
+     */
+    Untrapper(CanvasWindow &window);
+
+private:
+    DENG2_PRIVATE(d)
+};
+
+} // namespace de
+
+#endif // LIBAPPFW_UNTRAPPER_H

doomsday/libappfw/libappfw.pro

@@ -75,6 +75,7 @@ publicHeaders(root, \
     include/de/TabWidget \
     include/de/TextDrawable \
     include/de/ToggleWidget \
+    include/de/Untrapper \
     include/de/VRWindowTransform \
     include/de/WindowSystem \
     include/de/WindowTransform \
@@ -128,6 +129,7 @@ publicHeaders(framework, \
     include/de/framework/submenuitem.h \
     include/de/framework/subwidgetitem.h \
     include/de/framework/textdrawable.h \
+    include/de/framework/untrapper.h \
     include/de/framework/variabletoggleitem.h \
     include/de/framework/vrwindowtransform.h \
     include/de/framework/windowsystem.h \
@@ -197,6 +199,7 @@ SOURCES += \
     src/signalaction.cpp \
     src/style.cpp \
     src/textdrawable.cpp \
+    src/untrapper.cpp \
     src/vrwindowtransform.cpp \
     src/vr/oculusrift.cpp \
     src/vr/vrconfig.cpp \

doomsday/libappfw/src/untrapper.cpp

@@ -0,0 +1,49 @@
+/** @file untrapper.cpp  Mouse untrapping utility.
+ *
+ * @authors Copyright (c) 2014 Jaakko Keränen <jaakko.keranen@iki.fi>
+ *
+ * @par License
+ * LGPL: http://www.gnu.org/licenses/lgpl.html
+ *
+ * <small>This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or (at your
+ * option) any later version. This program is distributed in the hope that it
+ * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+ * General Public License for more details. You should have received a copy of
+ * the GNU Lesser General Public License along with this program; if not, see:
+ * http://www.gnu.org/licenses</small>
+ */
+
+#include "de/Untrapper"
+
+namespace de {
+
+DENG2_PIMPL(Untrapper)
+{
+    CanvasWindow &window;
+    bool wasTrapped;
+
+    Instance(Public *i, CanvasWindow &w) : Base(i), window(w)
+    {
+        wasTrapped = window.canvas().isMouseTrapped();
+        if(wasTrapped)
+        {
+            window.canvas().trapMouse(false);
+        }
+    }
+
+    ~Instance()
+    {
+        if(wasTrapped)
+        {
+            window.canvas().trapMouse();
+        }
+    }
+};
+
+Untrapper::Untrapper(CanvasWindow &window) : d(new Instance(this, window))
+{}
+
+} // namespace de