[sawfish] Revised recent changes in get-window-*.

[Christopher Bratusek <chrisb src gnome org>]

commit 0c204dffc4cf459d4f32762d363ec958f144ca88
Author: Teika kazura <teika lavabit com>
Date:   Tue Jan 18 12:45:10 2011 +0900

    Revised recent changes in get-window-*.
    
    * Full doc is written.
    * Moved old functions to compat.jl.

 lisp/sawfish/wm/commands/jump-or-exec.jl |    4 +-
 lisp/sawfish/wm/util/compat.jl           |   22 ++++++++++++++------
 lisp/sawfish/wm/windows.jl               |   29 +++++++++------------------
 man/news.texi                            |   10 ++++----
 man/sawfish.texi                         |   31 +++++++++++++++++++++--------
 5 files changed, 54 insertions(+), 42 deletions(-)
---
diff --git a/lisp/sawfish/wm/commands/jump-or-exec.jl b/lisp/sawfish/wm/commands/jump-or-exec.jl
index 0db1222..9f039b6 100644
--- a/lisp/sawfish/wm/commands/jump-or-exec.jl
+++ b/lisp/sawfish/wm/commands/jump-or-exec.jl
@@ -66,8 +66,8 @@
   (define (jump-or-exec regex prog #!key match-class onfocused)
     "Jump to a window, or when absent, start program."
     (let ((wind (if match-class
-		    (get-window-by-class-re regex)
-		  (get-window-by-name-re regex)))
+		    (get-window-by-class regex #:regex t)
+		  (get-window-by-name regex #:regex t)))
 	  (curwin (input-focus)))
       (cond ((and onfocused
 		  curwin
diff --git a/lisp/sawfish/wm/util/compat.jl b/lisp/sawfish/wm/util/compat.jl
index 9da33c4..bce7d82 100644
--- a/lisp/sawfish/wm/util/compat.jl
+++ b/lisp/sawfish/wm/util/compat.jl
@@ -20,16 +20,18 @@
 
 (define-structure sawfish.wm.util.compat
 
-    (export show-message
-	    ws-copy-window
-	    ws-move-window
-	    ws-insert-workspace
-	    ws-remove-workspace
-	    custom-set-color
+    (export custom-set-color
 	    custom-set-font
 	    custom-set-frame-style
+	    get-window-by-class-re
+	    get-window-by-name-re
 	    maybe-raise-window
-	    maybe-lower-window)
+	    maybe-lower-window
+	    show-message
+	    ws-copy-window
+	    ws-insert-workspace
+	    ws-move-window
+	    ws-remove-workspace)
 
     (open rep
 	  sawfish.wm.windows
@@ -66,6 +68,12 @@
   (define popup-window-menu popup-window-ops-menu)
   (define rename-window-func rename-window)
 
+  (define (get-window-by-class-re class)
+    (get-window-by-class class #:regex t))
+
+  (define (get-window-by-name-re name)
+    (get-window-by-name name #:regex t))
+
 ;;; obsolete commands
 
   (define (define-commands index)
diff --git a/lisp/sawfish/wm/windows.jl b/lisp/sawfish/wm/windows.jl
index d5220a3..7073c55 100644
--- a/lisp/sawfish/wm/windows.jl
+++ b/lisp/sawfish/wm/windows.jl
@@ -59,11 +59,7 @@
 	     avoided-windows
 	     call-after-property-changed
 	     call-after-state-changed
-	     rename-window
-	     
-	     ;; dummy
-	     get-window-by-class-re
-	     get-window-by-name-re))
+	     rename-window))
 
     (open rep
 	  rep.system
@@ -128,9 +124,10 @@
 ;;; finding windows, reading properties
 
   (define (get-window-by-name name #!key regex icon)
-    "Find a window object whose window-name is NAME. If REGEX is set then find
-a window object whose window-name matches NAME. If ICON is set then window-icon-name
-is being checked instead. Returns nil if no such window is found."
+    "Find a window object whose window-name is NAME. If REGEX is
+non-nil, then find a window object whose name matches NAME. If
+ICON is non-nil, then window-icon-name (NET_WM_ICON_NAME, _not_ EWMH
+_NET_WM_ICON_NAME) is checked instead. Returns nil if no such window is found."
     (if icon 
         (if regex
 	    (car (filter-windows (lambda (w)
@@ -143,25 +140,19 @@ is being checked instead. Returns nil if no such window is found."
         (car (filter-windows (lambda (w)
   			       (string= (window-name w) name)))))))
 
-  (define (get-window-by-name-re name)
-    (get-window-by-name name #:regex t))
-
   (define (get-window-by-class class #!key regex)
-    "Find a window object whose window-class is CLASS. If REGEX is set then find
-a window object whose window-class matches CLASS. Returns nil if no such window
-is found."
+    "Find a window object whose window-class is CLASS. If REGEX is
+non-nil then find a window object whose class matches
+CLASS. Returns nil if no such window is found."
     (if regex
         (car (filter-windows (lambda (w)
 			       (string-match class (window-class w)))))
       (car (filter-windows (lambda (w)
   			     (string= (window-class w) class))))))
 
-  (define (get-window-by-class-re class)
-    (get-window-by-class class #:regex t))
-
   (define (get-window-by-role role #!key regex)
-    "Find a window object whose window-role is ROLE. If REGEX is set then
-find a window object whose window-role matches ROLE. Returns nil if no such
+    "Find a window object whose window-role is ROLE. If REGEX is non-nil then
+find a window object whose role matches ROLE. Returns nil if no such
 window is found."
     (if regex
         (car (filter-windows (lambda (w)
diff --git a/man/news.texi b/man/news.texi
index 5d25f86..81cc09d 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -224,12 +224,12 @@ In order to support ``gnome2-globalmenu'', the reaction policy to
 @code{_NET_ACTIVE_WINDOW} if it's done by (un)grabbing the pointer.
 
 @item revised @code{get-window-by-*} functions [Christopher Bratusek]
+
+For the details, see @xref{Window Attributes}, and @xref{Getting Windows}.
 @itemize *
- item added @code{window-role} function (return NET_WM_ROLE)
- item added @code{get-window-by-role} function (takes #:regex switch)
- item merged @code{get-window-by-name-re} as #:regex switch into @code{get-window-by-name} (the old name is still supported)
- item merged @code{get-window-by-class-re} as #:regex switch into @code{get-window-by-class} (the old name is still supported)
- item added #:icon switch to @code{get-window-by-name} to get a window via NET_WM_ICON_NAME (can be used with #:regex switch, too)
+ item Added functions @code{window-role} and @code{get-window-by-role} (return NET_WM_ROLE) 
+ item Deleted @code{get-window-by-name-re} and @code{get-window-by-class-re}. Use instead @code{get-window-by-name} or @code{get-window-by-class} with the new option @code{#:regex}. (The old name is still supported.)
+ item added @code{#:icon} switch to @code{get-window-by-name} to get a window via NET_WM_ICON_NAME (can be used with #:regex switch, too)
 @end itemize
 
 @item Window-operation menu improvements [Christopher Bratusek]
diff --git a/man/sawfish.texi b/man/sawfish.texi
index 7d223ea..e1946c5 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -760,6 +760,10 @@ the symbol @code{configurator}, then the string of the form
 `` var{instance}/@var{class}'' is returned.
 @end defun
 
+ defun window-role window
+Return the window role set by @code{NET_WM_ROLE}.
+ end defun
+
 @defun window-id window
 If window object @var{window} has a client window associated with,
 return an integer defining its xid, otherwise return @code{nil}.
@@ -859,23 +863,32 @@ Functions to get specific windows.
 Return a window object with ID @var{xid}, or @code{nil}.
 @end defun
 
- defun get-window-by-name name
+ defun get-window-by-name name #!key regex icon
 Return a window object with name @var{name}, or @code{nil}.  Even if
 multiple windows are matched, one of them is returned.
- end defun
 
- defun get-window-by-name-re name
-Return a window object with name matching regular expression
- var{name}, or @code{nil}. Even if multiple windows are matched,
-one of them is returned.
+If @code{regex} is non-nil, @var{name} is treated as a regex, and
+matched against window names.
+
+If @code{icon} is non-nil, window's icon name (set by
+ code{NEW_WM_ICON_NAME}, @emph{not} EWMH @code{_NET_WM_ICON_NAME}) is
+searched, instead of the window's name.
 @end defun
 
- deffn Function: get-window-by-class class
- deffnx Function: get-window-by-class-re class
+ defun get-window-by-class class #!regex
 Same as the above, but the match is done against the window class.
 Here, the class does not include the ``instance''. (See @code{window-class} in
 @xref{Window Attributes}.)
- end deffn
+
+The option @code{regex} is boolean, not a regex, like @code{get-window-by-name}.
+ end defun
+
+ defun get-window-by-role role
+Same as the above, but the match is done against the window role.
+
+The option @code{regex} is boolean, not a regex, like @code{get-window-by-name}.
+
+ end defun
 
 @defun filter-windows pred
 Return the list of windows (mapped or unmapped) that match the