# HG changeset patch
# User paulb
# Date 1197743561 0
# Node ID 78e3d3dc86ab5d7b7e36a7c7b536bb29ffbcfd2d
# Parent  8a06d39d1ed6c9502aabedbbdea27aa17fbb43a3
[project @ 2007-12-15 18:32:40 by paulb]
Added more support for inspecting desktop windows.
Updated the copyright information.

diff -r 8a06d39d1ed6 -r 78e3d3dc86ab desktop/dialog.py
--- a/desktop/dialog.py	Thu Dec 13 21:41:26 2007 +0000
+++ b/desktop/dialog.py	Sat Dec 15 18:32:41 2007 +0000
@@ -3,7 +3,7 @@
 """
 Simple desktop dialogue box support for Python.
 
-Copyright (C) 2005, 2006, 2007 Paul Boddie <paul@boddie.org.uk>
+Copyright (C) 2007 Paul Boddie <paul@boddie.org.uk>
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -38,6 +38,9 @@
 question.open("GNOME") # Insists on GNOME
 
 The dialogue box options are documented in each class's docstring.
+
+Available dialogue box classes are listed in the desktop.dialog.available
+attribute.
 """
 
 from desktop import use_desktop, _run, _readfrom, _status
diff -r 8a06d39d1ed6 -r 78e3d3dc86ab desktop/windows.py
--- a/desktop/windows.py	Thu Dec 13 21:41:26 2007 +0000
+++ b/desktop/windows.py	Sat Dec 15 18:32:41 2007 +0000
@@ -3,7 +3,7 @@
 """
 Simple desktop window enumeration for Python.
 
-Copyright (C) 2005, 2006, 2007 Paul Boddie <paul@boddie.org.uk>
+Copyright (C) 2007 Paul Boddie <paul@boddie.org.uk>
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -26,16 +26,107 @@
 
 To obtain a list of windows, use the desktop.windows.list function as follows:
 
-desktop.windows.list()
+windows = desktop.windows.list()
+
+Each window object can be inspected through a number of methods. For example:
+
+name = window.name()
+width, height = window.size()
+x, y = window.position()
+child_windows = window.children()
+
+See the desktop.windows.Window class for more information.
 """
 
 from desktop import _is_x11, _get_x11_vars, _readfrom, use_desktop
 
+def _xwininfo(s):
+    d = {}
+    for line in s.split("\n"):
+        fields = line.split(":")
+        if len(fields) < 2:
+            continue
+        key, values = fields[0].strip(), fields[1:]
+        d[key] = values
+    return d
+
+def _get_int_properties(d, properties):
+    results = []
+    for property in properties:
+        results.append(int(d[property][0].strip()))
+    return results
+
+# Window classes.
+# NOTE: X11 is the only supported desktop so far.
+
+class Window:
+
+    "A window on the desktop."
+
+    def __init__(self, identifier):
+
+        "Initialise the window with the given 'identifier'."
+
+        self.identifier = identifier
+
+    def __repr__(self):
+        return "Window(%r)" % self.identifier
+
+    def children(self):
+
+        "Return a list of windows which are children of this window."
+
+        s = _readfrom(_get_x11_vars() + "xwininfo -id %s -children" % self.identifier, shell=1)
+        handles = []
+        adding = 0
+        for line in s.split("\n"):
+            if not adding and line.endswith("children:"):
+                adding = 1
+            elif adding and line:
+                handles.append(line.strip().split()[0])
+        return [Window(handle) for handle in handles]
+
+    def name(self):
+
+        "Return the name of the window."
+
+        s = _readfrom(_get_x11_vars() + "xwininfo -id %s -stats" % self.identifier, shell=1)
+        for line in s.split("\n"):
+            if line.startswith("xwininfo:"):
+
+                # Format is 'xwininfo: Window id: <handle> "<name>"
+
+                fields = line.split(":")
+                handle_and_name = fields[2].strip()
+                fields2 = handle_and_name.split(" ")
+
+                # Get the "<name>" part, stripping off the quotes.
+
+                return " ".join(fields2[1:]).strip('"')
+
+        return None
+
+    def size(self):
+
+        "Return a tuple containing the width and height of this window."
+
+        s = _readfrom(_get_x11_vars() + "xwininfo -id %s -stats" % self.identifier, shell=1)
+        d = _xwininfo(s)
+        return _get_int_properties(d, ["Width", "Height"])
+
+    def position(self):
+
+        "Return a tuple containing the upper left co-ordinates of this window."
+
+        s = _readfrom(_get_x11_vars() + "xwininfo -id %s -stats" % self.identifier, shell=1)
+        d = _xwininfo(s)
+        return _get_int_properties(d, ["Absolute upper-left X", "Absolute upper-left Y"])
+
 def list(desktop=None):
 
     """
-    Return a list of window handles for the current desktop. If the optional
-    'desktop' parameter is specified then attempt to use that particular desktop
+    Return a list of windows for the current desktop. If the optional 'desktop'
+    parameter is specified then attempt to use that particular desktop
     environment's mechanisms to look for windows.
     """
 
@@ -54,6 +145,6 @@
     else:
         raise OSError, "Desktop '%s' not supported" % use_desktop(desktop)
 
-    return handles
+    return [Window(handle) for handle in handles]
 
 # vim: tabstop=4 expandtab shiftwidth=4