[script] Find and interact with windows

This patch adds mechanisms to find and interact with windows to the
scripting API:

 - workspace.windowAt provides a way to list the windows at a given
   location on the screen.
 - workspace.stackingOrder provides a list of all windows in the order
   they are stacked on the screen.
 - workspace.raiseWindow provides a mechanism to bring a given window to
   the top of that list, making it visible above all others.

Signed-off-by: Antonio Russo <aerusso@aerusso.net>

src/scripting/workspace_wrapper.cpp

@@ -280,6 +280,16 @@ void WorkspaceWrapper::hideOutline()
     workspace()->outline()->hide();
 }
 
+QList<KWin::Window *> WorkspaceWrapper::stackingOrder() const
+{
+    return workspace()->stackingOrder();
+}
+
+void WorkspaceWrapper::raiseWindow(KWin::Window *window)
+{
+    KWin::Workspace::self()->raiseWindow(window);
+}
+
 Window *WorkspaceWrapper::getClient(qulonglong windowId)
 {
     auto window = Workspace::self()->findClient(Predicate::WindowMatch, windowId);
@@ -287,6 +297,35 @@ Window *WorkspaceWrapper::getClient(qulonglong windowId)
     return window;
 }
 
+QList<KWin::Window *> WorkspaceWrapper::windowAt(const QPointF &pos, int count) const
+{
+    QList<KWin::Window *> result;
+    int found = 0;
+    const QList<Window *> &stacking = workspace()->stackingOrder();
+    if (stacking.isEmpty()) {
+        return result;
+    }
+    auto it = stacking.end();
+    do {
+        if (found == count) {
+            return result;
+        }
+        --it;
+        Window *window = (*it);
+        if (window->isDeleted()) {
+            continue;
+        }
+        if (!window->isOnCurrentActivity() || !window->isOnCurrentDesktop() || window->isMinimized() || window->isHiddenInternal()) {
+            continue;
+        }
+        if (window->hitTest(pos)) {
+            result.append(window);
+            found++;
+        }
+    } while (it != stacking.begin());
+    return result;
+}
+
 QSize WorkspaceWrapper::desktopGridSize() const
 {
     return VirtualDesktopManager::self()->grid().size();

src/scripting/workspace_wrapper.h

@@ -54,6 +54,11 @@ class WorkspaceWrapper : public QObject
      * @see virtualScreenSize
      */
     Q_PROPERTY(QRect virtualScreenGeometry READ virtualScreenGeometry NOTIFY virtualScreenGeometryChanged)
+    /**
+     * List of Clients currently managed by KWin, orderd by
+     * their visibility (later ones cover earlier ones).
+     */
+    Q_PROPERTY(QList<KWin::Window *> stackingOrder READ stackingOrder)
     /**
      * The current position of the cursor.
      */
@@ -230,12 +235,32 @@ public:
      * Provides support information about the currently running KWin instance.
      */
     Q_SCRIPTABLE QString supportInformation() const;
+
+    /**
+     * List of Clients currently managed by KWin, orderd by
+     * their visibility (later ones cover earlier ones).
+     */
+    QList<KWin::Window *> stackingOrder() const;
+    /**
+     * Raises a Window  above all others on the screen.
+     * @param window The Window to raise
+     */
+    Q_INVOKABLE void raiseWindow(KWin::Window *window);
     /**
      * Finds the Client with the given @p windowId.
      * @param windowId The window Id of the Client
      * @return The found Client or @c null
      */
     Q_SCRIPTABLE KWin::Window *getClient(qulonglong windowId);
+    /**
+     * Finds up to count windows at a particular location,
+     * prioritizing the topmost one first.  A negative count
+     * returns all matching clients.
+     * @param pos The location to look for
+     * @param count The number of clients to return
+     * @return A list of Client objects
+     */
+    Q_INVOKABLE QList<KWin::Window *> windowAt(const QPointF &pos, int count = 1) const;
 
 public Q_SLOTS:
     // all the available key bindings