[sawfish] focus revert doc / NEWS::1.5.0 rewrite

[Christopher Bratusek <chrisb src gnome org>]

commit 366c4d01e4b8fe16b6bcabad1c69042c7b571874
Author: chrisb <zanghar freenet de>
Date:   Sat Sep 12 09:46:31 2009 +0200

    focus revert doc / NEWS::1.5.0 rewrite

 ChangeLog                |    7 ++++
 lisp/sawfish/wm/focus.jl |   76 +++++++++++++++++++++++++++++----------------
 man/news.texi            |   70 +++++++++++++++++++++++++++++++++---------
 3 files changed, 111 insertions(+), 42 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 312a073..2859e10 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2009-09-12  Christopher Bratusek <zanghar freenet de>
+	* lisp/sawfish/wm/focus.jl: doc for focus-revert
+	                            indention improvements
+				    -- [Teika Kazura]
+	
+	* man/news.texi: major rewrite of 1.5.0 section [Teika Kazura]
+
 2009-09-11  Christopher Bratusek <zanghar freenet de>
 	* configure.in
 	* Makedefs.in
diff --git a/lisp/sawfish/wm/focus.jl b/lisp/sawfish/wm/focus.jl
index 9f10737..c2cacb1 100644
--- a/lisp/sawfish/wm/focus.jl
+++ b/lisp/sawfish/wm/focus.jl
@@ -28,7 +28,7 @@
 	    focus-push-map
 	    focus-pop-map
 	    warp-pointer-if-necessary
-           focus-revert
+	    focus-revert
 	    focus-within-click-event)
 
     (open rep
@@ -143,13 +143,34 @@ EVENT-NAME)', where EVENT-NAME may be one of the following symbols:
 
 ;;; modes
 
+  #|
+  From sawfish-1.5.0, enter-notify events invoked by grab are
+  ignored in enter-exit and enter-only. This has a down side, too,
+  but first let us see what's the intention.
+
+  The problem that this solves is when you press Alt F2 in KDE, the
+  Run Command popup appears and gets focused (if focus-when-mapped is
+  non-nil), you start typing, the completion list pops up and takes
+  focus, then you type a bit further and the completion list
+  disappears.  Focus used to revert to the window the pointer was in,
+  which usually was not the Run Command popup.  transient-unmap-window
+  tries hard to get it right, then the grab-induced enter-notify
+  brought focus to the wrong window anyway.
+
+  The problem that this causes is when you open the KDE main menu by
+  clicking the K icon in the panel, move the mouse into some
+  application window and click to dismiss the open menu, focus reverts
+  to the panel. You have to move the pointer out of the application
+  window and back in to get it focused.
+  |#
   (define-focus-mode 'enter-exit
     (lambda (w action . args)
       (case action
 	((pointer-in)
 	 (when (and (window-really-wants-input-p w)
-                    ;; ignore grab/ungrab enter events
-                    (eq (car args) 'normal))
+		    ;; ignore grab/ungrab enter events
+		    ;; See the above long comment
+		    (eq (car args) 'normal))
 	   (set-input-focus w)))
 	((pointer-out)
 	 ;; ignore grab/ungrab leave events
@@ -161,32 +182,33 @@ EVENT-NAME)', where EVENT-NAME may be one of the following symbols:
 	((warp-if-necessary)
 	 (unless (eq (query-pointer-window) w)
 	   (warp-cursor-to-window w)))
-        ((focus-revert)
-         (setq w (query-pointer-window))
-         (when (or (null w)
-                   (window-really-wants-input-p w))
-           (set-input-focus w))))))
+	((focus-revert)
+	 (setq w (query-pointer-window))
+	 (when (or (null w)
+		   (window-really-wants-input-p w))
+	   (set-input-focus w))))))
 
   (define-focus-mode 'enter-only
     (lambda (w action . args)
       (case action
 	((pointer-in)
 	 (when (and (window-really-wants-input-p w)
-                    ;; ignore grab/ungrab enter events
-                    (eq (car args) 'normal))
+		    ;; ignore grab/ungrab enter events
+		    ;; See the comment above enter-exit
+		    (eq (car args) 'normal))
 	   (set-input-focus w)))
 	((warp-if-necessary)
 	 (let ((current (query-pointer-window)))
 	   (unless (or (eq current w) (desktop-window-p current))
 	     (warp-cursor-to-window w))))
-        ((focus-revert)
-         (setq w (query-pointer-window))
-         (when (or (null w)
-                   (desktop-window-p w))
-           (setq w (window-order-most-recent)))
-         (when (or (null w)
-                   (window-really-wants-input-p w))
-           (set-input-focus w))))))
+	((focus-revert)
+	 (setq w (query-pointer-window))
+	 (when (or (null w)
+		   (desktop-window-p w))
+	   (setq w (window-order-most-recent)))
+	 (when (or (null w)
+		   (window-really-wants-input-p w))
+	   (set-input-focus w))))))
 
   (define (focus-click)
     (let ((w (current-event-window))
@@ -239,19 +261,19 @@ EVENT-NAME)', where EVENT-NAME may be one of the following symbols:
 	 (unless (or (not (window-really-wants-input-p w))
 		     (eq w (input-focus)))
 	   (focus-push-map w click-to-focus-map)))
-        ((focus-revert)
-         (setq w (window-order-most-recent))
-         (when (or (null w)
-                   (window-really-wants-input-p w))
-           (set-input-focus w))))))
+	((focus-revert)
+	 (setq w (window-order-most-recent))
+	 (when (or (null w)
+		   (window-really-wants-input-p w))
+	   (set-input-focus w))))))
 
   (define-focus-mode 'enter-click
     (lambda (w action . args)
       (case action
-        ((pointer-in warp-if-necessary focus-revert)
-         (apply (focus-mode-ref 'enter-only) w action args))
-        ((focus-in focus-out add-window before-mode-change after-mode-change)
-         (apply (focus-mode-ref 'click) w action args)))))
+	((pointer-in warp-if-necessary focus-revert)
+	 (apply (focus-mode-ref 'enter-only) w action args))
+	((focus-in focus-out add-window before-mode-change after-mode-change)
+	 (apply (focus-mode-ref 'click) w action args)))))
 
 ;;; hooks
 
diff --git a/man/news.texi b/man/news.texi
index c6b55fe..9fef5cd 100644
--- a/man/news.texi
+++ b/man/news.texi
@@ -150,6 +150,8 @@ your system, but the later doesn't
 
 @item Doc updates [Christopher Bratusek, Jeremy Hankins, Teika Kazura]
 
+News items for 1.5.0 are rewritten to describe them better.
+
 @item Updated OPTIONS [Christopher Bratusek]
 
 @item Added new contributors to @code{THANKS} section of @code{CONTRIBUTING} [Christopher Bratusek]
@@ -158,7 +160,9 @@ your system, but the later doesn't
 
 @heading 1.5.0
 
-The new release is Sawfish-1.5.0. We don't release 1.4 series for historical reason.
+The new release is Sawfish-1.5.0. We don't release 1.4 series for
+historical reason. The next will be 1.6, and 1.5.x are for bugfix
+branches.
 
 @itemize @bullet
 
@@ -220,44 +224,80 @@ To use the old style, put @code{(define-special-variable customize-program "sawf
 @item Fixed a speed-issue with ``microGUI'' theme [Christopher Bratusek]
 
 @item Make properly use of WM_NAME in ``Elberg-tabbed'' theme [Christopher Bratusek]
+
+ item UTF-8 Support in window menus [Wang Diancheng]
+
+ item UTF-8 Support in GTK Widgets [Christopher Bratusek]
 @end itemize
 
 @item New features:
 @itemize @minus
 
- item UTF-8 Support in Windowmenus [Wang Diancheng]
+ item Tabbed Windowing Support [Yann Hodique, Scott Scriven, Nathan Froyd, Christopher Bratusek], Raise Tabs on hover [Christopher Bratusek]
 
- item UTF-8 Support in GTK Widgets [Christopher Bratusek]
+Windows can be ``tabbed'', or multiple windows bound to one, sharing
+size and frames. It's still under development (sorry). For instructions,
+see our wiki site @url{http://sawfish.wikia.com/Tabs}.
 
- item Tabbed Windowing Support [Yann Hodique, Scott Scriven, Nathan Froyd, Christopher Bratusek]
+ item Focus enhancements [Timo Korvola]
 
- item Tabbed Windowing Support: Raise Tabs on hover [Christopher Bratusek]
+Improvements in focus are done from which KDE users will benefit.
+Some new windows can receive focus. Some undesired focus transitions
+to desktop windows are suppressed.
 
- item Improved KDE3 Integration [Timo Korvola]
+In enter-exit and enter-only focus modes, enter-notify events caused
+by grab/ungrab are ignored. This has a bad side effect, too.
 
- item Replaced hardcoded focus logic by focus-revert function [Timo Korvola]
+In lisp, replaced hardcoded focus logic by @code{focus-revert}
+function. Previously, action when the focused transient window is
+unmapped was not handled by focus modes, but coded elsewhere. Now
+ code{focus-revert} event is invoked, and passed to focus modes. (For
+detail, @pxref{Input Focus}.) This makes the modes' policy clear, and
+programmable.
 
- item Warp cursor to cycled windows, if warp-cursor is enabled [Christopher Bratusek]
+ item cursor warp enhancements. [Christopher Bratusek]
 
- item Warp cursor to unmaximized windows, if warp-cursor is enabled [Fernando Carmona Varo]
+During window cycling, cursor is warped to the current top window if
+ code{warp-to-window-enabled} and @code{cycle-raise-windows} are
+non-nil.
 
- item 3 New Window-Animators: cross, elliptical and draft [Christopher Bratusek, Teika Kazura[draft fixups]]
+When the window gets unmaximized, the cursor is retained in that
+window when @code{warp-to-window-enabled} is non-nil.
+
+ item 3 New Window-Animators for moving and resizing: cross, elliptical and draft [Christopher Bratusek, Teika Kazura (draft fixups)]
 
 @item Shrinking/Yanking Support [Timo Korvola]
 
- item Infinite Desktop Feature (make the virtual desktop bigger than the physical) [David T. McWherter]
+Shrink and yank are commands to reduce overlap with other windows ``by
+one'', with a motion in direction left/right/up/down. ``Shrink''
+commands move one edge of the window to shrink, and ``yank'' commands
+move the window.
+
+To use them, put @code{(require 'sawfish.wm.commands.shrink-yank)} in
+your configuration file, and use the configurator GUI to bind commands
+to keys.
+
+ item ``Infinite Desktop'' Feature [David T. McWherter]
+
+It makes the virtual desktop bigger than the screen, actually so big
+that there's no limit. You can scroll it with mouse continuously in
+natural manner.
+
+This is in contrast to the coventional viewport; it scrolls
+by a step of one screen size. Thus it may not work so well with
+viewports.
 
- item Make Viewport commands appear in Sawfish-UI [Christopher Bratusek]
+To use it, put @code{(require 'sawfish.wm.ext.infinite-desktop)} in
+your configuration file, and use configurator GUI.
 
- item Make Window History appear in Sawfish-UI [Christopher Bratusek]
+ item In configurator GUI, viewport commands and history appear. Under matched-window, fixed-position, never-iconify, never-maximize are available. [Christopher Bratusek]
 
- item Added cycle-among-groups(,-backwards) commands (cycle between the most recently used window of groups) [Fernando Carmano Varo]
+ item Added cycle-among-groups(,-backwards) commands (cycle among the most recently used window of groups) [Fernando Carmano Varo]
 
 @item Interactive placement-mode now also for transients [Christopher Bratusek]
 
 @item Improved prompt.jl (allows changing font, fg and bg color) [Sergey I. Sharybin]
 
- item Expose fixed-position, never-iconify, never-maximize in the Window-Matcher UI [Christopher Bratusek]
 @end itemize
 
 @item Other changes: