[sawfish: 5/10] Doc on window types.

[Christopher Bratusek <chrisb src gnome org>]

commit 56da4d1861923dccce393ec2b3734c3f0844f088
Author: Teika kazura <teika lavabit com>
Date:   Thu Oct 1 16:05:05 2009 +0900

    Doc on window types.

 OPTIONS                    |   23 ++++++++++++++++++++---
 lisp/sawfish/wm/frames.jl  |   11 +++++++----
 lisp/sawfish/wm/windows.jl |   10 +++++-----
 man/sawfish.texi           |   36 +++++++++++++++++++++++++-----------
 4 files changed, 57 insertions(+), 23 deletions(-)
---
diff --git a/OPTIONS b/OPTIONS
index 8342ce0..d811d67 100644
--- a/OPTIONS
+++ b/OPTIONS
@@ -94,8 +94,15 @@
 ;;      (shaded . shaped)
 ;;      (shaded-transient . shaped-transient)
 ;;      (icon . shaped-transient)
-;;      (dock . unframed))
-;;    "Frame type fallbacks.")
+;;      (dock . unframed)
+;;      (utility . default)
+;;      (shaded-utility . shaded-transient)
+;;      (toolbar . unframed)
+;;      (menu . unframed)
+;;      (splash . unframed))
+;;    "Frame type fallbacks. This is an alist whose elements are
+;;   (required-type . fallback-type). When REQUIRED-TYPE is not supported
+;;   by the current theme, then FALLBACK-TYPE is used instead.")
 
 ;;  (define-special-variable decorate-transients nil
 ;;    "Decorate dialog windows similarly to application windows.")
@@ -519,7 +526,17 @@
 ;;    '(window-list-skip cycle-skip fixed-position focus-click-through
 ;;      avoid no-history never-iconify never-maximize sticky
 ;;      stick-viewport placed)
-;;    "List of properties set (to true) on windows marked as docks.")
+;;    "List of properties set (to true) on windows when they are marked as docks.")
+
+;; (define-special-variable desktop-window-properties
+;;   '(fixed-position sticky sticky-viewport)
+;;   "List of properties set (to true) on windows when they are marked as desktops.")
+
+;; (define-special-variable desktop-window-depth -4
+;;   "The stacking depth of desktop windows.")
+
+;; (define-special-variable dock-window-depth 0
+;;   "The stacking depth of dock windows.")
 
 ;;  (define-special-variable select-window-cursor-shape 'crosshair
 ;;    "Cursor used by select-window function.")
diff --git a/lisp/sawfish/wm/frames.jl b/lisp/sawfish/wm/frames.jl
index 98b4596..07fbe83 100644
--- a/lisp/sawfish/wm/frames.jl
+++ b/lisp/sawfish/wm/frames.jl
@@ -155,11 +155,14 @@ that overrides settings set elsewhere.")
       (utility . default)
       (shaded-utility . shaded-transient)
       (toolbar . unframed)
-      ;;    (shaded-toolbar . shaded-utility)
       (menu . unframed)
-      ;;    (shaded-menu . shaded-utility)
-      (splash . unframed))
-    "Frame type fallbacks.")
+      (splash . unframed)
+      ;; (shaded-toolbar . shaded-utility)
+      ;; (shaded-menu . shaded-utility)
+      )
+    "Frame type fallbacks. This is an alist whose elements are
+(required-type . fallback-type). When REQUIRED-TYPE is not supported
+by the current theme, then FALLBACK-TYPE is used instead.")
 
   ;; Re-Coloring Options for Themes
 
diff --git a/lisp/sawfish/wm/windows.jl b/lisp/sawfish/wm/windows.jl
index bf5cef1..b00843d 100644
--- a/lisp/sawfish/wm/windows.jl
+++ b/lisp/sawfish/wm/windows.jl
@@ -104,13 +104,13 @@
 
   (defvar dock-window-properties
     '(window-list-skip cycle-skip fixed-position focus-click-through
-                       avoid no-history never-iconify never-maximize sticky
-                       sticky-viewport placed)
-    "List of properties set (to true) on windows marked as docks.")
+		       avoid no-history never-iconify never-maximize sticky
+		       sticky-viewport placed)
+    "List of properties set (to true) on windows when they are marked as docks.")
 
   (defvar desktop-window-properties
     '(fixed-position sticky sticky-viewport)
-    "List of properties set (to true) on windows marked as desktops.")
+    "List of properties set (to true) on windows when they are marked as desktops.")
 
   (defvar desktop-window-depth -4
     "The stacking depth of desktop windows.")
@@ -191,7 +191,7 @@ then be the numeric id of its parent window."
   (define-command 'focus-desktop focus-desktop)
 
   (define (dock-window-p arg)
-    "Return true if ARG represents a dock window (i.e. the GNOME panel)."
+    "Return true if ARG represents a dock window."
     (and (windowp arg) (window-get arg 'dock-type)))
 
   (define (mark-window-as-dock w)
diff --git a/man/sawfish.texi b/man/sawfish.texi
index 4d14006..2126d34 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -877,9 +877,16 @@ Remove @var{property} of @var{window}. Returns @code{t} for success,
 @cindex Types, of windows
 @cindex Windows, types of
 
-Transient windows are pop-up or dialog windows associated with a main
-application.  They tend to have less window decorations, and are
-intended to last a short time only.
+Some window ``types'' are defined. They represent the window's special
+nature based on the role. Defined types are ``transient'',
+``desktop'', and ``dock''.
+
+A type is usually set by applications through hints when the
+window appears. Many windows do not have any types.
+
+``Transient'' windows are pop-up or dialog windows associated with
+a main application.  They tend to have less window decorations, and
+are intended to last a short time only.
 
 @defun window-transient-p arg
 Returns @code{t} if @var{arg} represents a transient window.
@@ -954,7 +961,9 @@ Decorate dialog windows similarly to application windows.  Defaults to
 false.
 @end defvar
 
-Desktop windows are root windows or viewport windows.
+``Desktop'' windows are root windows or viewport windows. They
+accept keys as if it is a root window. (I.e.,
+ code{root-window-keymap} is used.) They don't have a frame.
 
 @defun desktop-window-p arg
 Returns @code{t} if @var{arg} represents a desktop window.
@@ -966,8 +975,8 @@ window.
 @end defun
 
 @defvar desktop-window-properties
-List of properties set (to true) on windows marked as desktops.
-Defaults to
+List of properties set (to true) on windows when they are marked as
+desktops.  Defaults to
 @lisp
 '(fixed-position sticky sticky-viewport)
 @end lisp
@@ -977,9 +986,8 @@ Defaults to
 The stacking depth of desktop windows.  Defaults to -4.
 @end defvar
 
-Dock windows are simply those with the @code{dock-type} property.
-GNOME panels are one example.  Sawfish does not currently assign them
-any special behavior.
+``Dock'' windows are docks or panels. They don't have frame by
+default.
 
 @defun dock-window-p arg
 Returns @code{t} if @var{arg} represents a dock window.
@@ -991,8 +999,8 @@ window.
 @end defun
 
 @defvar dock-window-properties
-List of properties set (to true) on windows marked as docks.
-Defaults to
+List of properties set (to true) on windows when they are marked as
+docks. Defaults to
 @lisp
 '(window-list-skip cycle-skip fixed-position focus-click-through
   avoid no-history never-iconify never-maximize sticky
@@ -3824,6 +3832,12 @@ If @code{t}, non-nil themes are assumed to be malicious.  They will be
 evaluated in a restricted environment.
 @end defvar
 
+ defvar frame-type-fallback-alist
+Frame type fallbacks. This is an alist whose elements are
+(required-type . fallback-type). When REQUIRED-TYPE is not supported
+by the current theme, then FALLBACK-TYPE is used instead."
+ end defvar
+
 @node Removing Frame Parts,  , Themes, Window Frames
 @section Removing Frame Parts
 @cindex Removing frame parts