[elpa] externals/window-commander d46309a7a8 151/170: Rework display functions

[ELPA Syncer]

branch: externals/window-commander
commit d46309a7a871dfa5a0a63090016d8607305c6d36
Author: Daniel Semyonov <daniel@dsemy.com>
Commit: Daniel Semyonov <daniel@dsemy.com>

    Rework display functions
    
    * swsw.el (swsw-display-function): Redefine as obsolete alias of
    'swsw-display-lighter'.
    (swsw-display-lighter, swsw-mode-hook): New custom variable.
    (swsw-mode-line-display-function):
    (swsw-mode-line-conditional-display-function): Make usage of SWITCH
    argument obsolete, use the value of 'swsw-mode' instead when SWITCH is
    omitted or nil.
    (swsw-mode): Use 'swsw-display-lighter' instead of
    'swsw-display-function'.
    * swsw.texi (Usage, Customization, Window commands): Rename 'Display
    functions' to 'ID Display'.
    (Customization, ID Display): Move description of 'swsw-id-format' to
    'ID Display'.
    (ID Display): Document 'swsw-display-lighter' and 'swsw-mode-hook',
    add more details to existing information.
    * README: Rename 'swsw-display-function' to 'swsw-display-lighter'.
    * NEWS: Document changes.
---
 NEWS      | 12 +++++++++
 README    |  2 +-
 swsw.el   | 90 +++++++++++++++++++++++++++++++++++++++++--------------------
 swsw.texi | 92 ++++++++++++++++++++++++++++++++++++++++-----------------------
 4 files changed, 133 insertions(+), 63 deletions(-)

diff --git a/NEWS b/NEWS
index 96d0f32114..b129b4dbdb 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,18 @@
 swsw NEWS -- history of user-visible changes. -*- mode: outline -*-
 See the end of the file for an explanation of the versioning scheme.
 
+* 2.2
+
+** Rework display functions
+'swsw-display-function' has been replaced by 'swsw-display-lighter',
+display functions should now be added to 'swsw-mode-hook'.
+For backwards compatibility, 'swsw-display-function' has been
+redefined as an obsolete alias of 'swsw-display-lighter', and
+'swsw-mode' currently still handles cases where the value of
+'swsw-display-lighter' is a function.
+Display functions which are added to 'swsw-mode-hook' shouldn't
+require any arguments.
+
 * 2.1.1
 
 ** Indicate that some functions are for interactive use only.
diff --git a/README b/README
index 369565d69b..8f7f12f7f8 100644
--- a/README
+++ b/README
@@ -39,7 +39,7 @@ For use-package users:
 
 When swsw-mode is active:
 - A window ID is displayed using a mode line lighter or a display
-  function (see ‘swsw-display-function’).
+  function (see ‘swsw-display-lighter’).
 - Window IDs are assigned to all windows on all frames except for
   the minibuffer(by default, see ‘swsw-scope’).
 
diff --git a/swsw.el b/swsw.el
index 146906856e..f05a79f08d 100644
--- a/swsw.el
+++ b/swsw.el
@@ -43,7 +43,7 @@
 ;;
 ;; When `swsw-mode' is active:
 ;; - A window ID is displayed using a mode line lighter or a display
-;;   function (see `swsw-display-function').
+;;   function (see `swsw-display-lighter').
 ;; - Window IDs are assigned to all windows on all frames except for
 ;;   the minibuffer(by default, see `swsw-scope').
 ;; - `other-window' (C-x o by default) is remapped to `swsw-select'.
@@ -69,7 +69,7 @@
 (eval-when-compile
   (require 'subr-x)
   ;; Avoid byte-compilation warnings.
-  (defvar swsw-display-function)
+  (defvar swsw-mode)
   (defvar swsw-command-map))
 
 ;;;; Customization:
@@ -117,29 +117,50 @@ This list should contain at least two characters."
   :risky t
   :package-version '(swsw . 1.1))
 
-(defcustom swsw-display-function 'lighter
+(define-obsolete-variable-alias 'swsw-display-function
+  'swsw-display-lighter "version 2.2 of the swsw package"
   "Function used to display the ID of each window.
 This function is called with t as the sole argument when enabling
 simple window switching, and with nil as the sole argument when
-disabling it.
-If set to `lighter', use a mode line lighter."
+disabling it.")
+
+(defcustom swsw-display-lighter t
+  "Whether or not to show a mode line lighter.
+- non-nil means show a mode line lighter.
+- nil means don't show a mode line lighter.
+
+This variable can also accept a \"display function\" for backwards
+compatibility (see `swsw-display-function')."
   :link '(info-link "(swsw)Display functions")
-  :type '(radio (const :tag "Mode line lighter" lighter)
-                (function :tag "Display function"))
+  :type '(radio (const :tag "Show mode line lighter" t)
+                (const :tag "Don't show mode line lighter" nil))
   :set (lambda (sym fun)
-         (unless (or (not (boundp 'swsw-display-function))
-                     (eq swsw-display-function 'lighter))
-           (funcall swsw-display-function nil))
+         (and (boundp sym) (functionp (symbol-value sym))
+              (funcall (symbol-value sym) nil))
          (set-default sym fun)
-         (unless (eq fun 'lighter)
+         (when (functionp fun)
            (funcall fun t)))
+  :package-version '(swsw . 2.2))
+
+(defcustom swsw-mode-hook nil
+  "Hook run when enabling or disabling simple window switching."
+  :link '(info-link "(swsw)Display functions")
+  :type 'hook
+  :options '(swsw-mode-line-display-function
+             swsw-mode-line-conditional-display-function)
+  :initialize #'custom-initialize-changed
+  :set (lambda (sym hooks)
+         (let ((swsw-mode nil))
+           (when (boundp sym) (run-hooks sym)))
+         (set-default sym hooks)
+         (run-hooks sym))
   :package-version '(swsw . 1.0))
 
 (defcustom swsw-id-format " <%s>"
   "Format string for the window ID.
 %s is replaced with a representation of the window's ID."
   :link '(info-link "(swsw)Customization")
-  :type '(string)
+  :type 'string
   :package-version '(swsw . 1.0))
 
 ;;;; Window tracking:
@@ -260,23 +281,33 @@ is t."
                  (default-value 'mode-line-format)))
   (force-mode-line-update t))
 
-(defun swsw-mode-line-display-function (switch)
+(defun swsw-mode-line-display-function (&optional switch)
   "Display window IDs at the beginning of the mode line.
-Display window IDs if SWITCH isn't nil, and disable displaying window
-IDs if SWITCH is nil.
-This display function respects `swsw-id-format'."
-  (if switch
+Display window IDs if simple window switching is enabled, and disable
+displaying window IDs if simple window switching is disabled.
+This display function respects `swsw-id-format'.
+
+It is also possible to supply a single SWITCH argument, which will
+override the value of `swsw-mode';
+this form is obsolete since version 2.2 of the swsw package."
+  (declare (advertised-calling-convention nil "2.2"))
+  (if (or switch swsw-mode)
       (swsw--mode-line-display)
     (swsw--mode-line-hide)))
 
-(defun swsw-mode-line-conditional-display-function (switch)
-  "Display window IDs at the beginning of the mode line, conditionally.
+(defun swsw-mode-line-conditional-display-function (&optional switch)
+  "Display window IDs at the beginning of the mode line during window 
selection.
 Add a hook to `swsw-before-command-hook' which displays window IDs on
 the mode line and add a hook to `swsw-after-command-hook' which hides
-window IDs from the mode line if SWITCH isn't nil, and remove those
-hooks if SWITCH is nil.
-This display function respects `swsw-id-format'."
-  (if switch
+window IDs from the mode line if simple window switching is enabled,
+and remove those hooks if simple window switching is disabled.
+This display function respects `swsw-id-format'.
+
+It is also possible to supply a single SWITCH argument, which will
+override the value of `swsw-mode';
+this form is obsolete since version 2.2 of the swsw package."
+  (declare (advertised-calling-convention nil "2.2"))
+  (if (or switch swsw-mode)
       (progn
         (add-hook 'swsw-before-command-hook #'swsw--mode-line-display)
         (add-hook 'swsw-after-command-hook #'swsw--mode-line-hide))
@@ -362,23 +393,24 @@ selection:
 
 \\{swsw-command-map}"
   :global t
-  :lighter (:eval (when (eq swsw-display-function 'lighter)
-                    (swsw-format-id (selected-window))))
+  :lighter (:eval (and swsw-display-lighter
+                       (not (functionp swsw-display-lighter))
+                       (swsw-format-id (selected-window))))
   :keymap (let ((map (make-sparse-keymap)))
             (define-key map [remap other-window] #'swsw-select)
             map)
   (if swsw-mode
       (progn
         (swsw--update)
-        (unless (eq swsw-display-function 'lighter)
-          (funcall swsw-display-function t))
+        (when (functionp swsw-display-lighter)
+          (funcall swsw-display-lighter))
         (add-hook 'window-configuration-change-hook #'swsw--update)
         (add-hook 'window-state-change-hook #'swsw--update-frame)
         (add-hook 'minibuffer-setup-hook #'swsw--update)
         (add-hook 'minibuffer-exit-hook #'swsw--update)
         (add-hook 'after-delete-frame-functions #'swsw--update))
-    (unless (eq swsw-display-function 'lighter)
-      (funcall swsw-display-function nil))
+    (when (functionp swsw-display-lighter)
+      (funcall swsw-display-lighter))
     (remove-hook 'window-configuration-change-hook #'swsw--update)
     (remove-hook 'window-state-change-hook #'swsw--update-frame)
     (remove-hook 'minibuffer-setup-hook #'swsw--update)
diff --git a/swsw.texi b/swsw.texi
index b337984ec7..194d8b4f29 100644
--- a/swsw.texi
+++ b/swsw.texi
@@ -70,7 +70,7 @@ Installation
 
 Customization
 
-* Display functions::
+* ID display::
 * Window commands::
 
 @end detailmenu
@@ -137,9 +137,8 @@ You can also add @code{(swsw-mode)} to your init file, 
instead.
 @end table
 
 When @code{swsw-mode} is enabled, window IDs are shown as mode line
-lighters of the form @code{<ID>} (by default, @xref{Display
-functions}), and @code{other-window} (@kbd{C-x o}) is remapped to
-@code{swsw-select}.
+lighters of the form @code{<ID>} (by default, @xref{ID display}), and
+@code{other-window} (@kbd{C-x o}) is remapped to @code{swsw-select}.
 
 @table @asis
 @kindex C-x o
@@ -185,13 +184,6 @@ list of characters. By default, the home row (@code{a s d 
f g h j k l}) is
 used.
 @end defopt
 
-@defopt swsw-id-format
-Format string for the window ID. Display functions may use this format string
-to display the ID, but they can also ignore it. The string should contain a
-single occurrence of @code{%s}, which will be replaced by the ID. By default,
-@code{" <%s>"} is used.
-@end defopt
-
 @defopt swsw-scope
 Scope of all window operations. Used to determine on which frames to track
 windows. A value of @code{t} means consider all windows on all frames, @code{0}
@@ -202,36 +194,69 @@ frames, @code{visible} means consider all windows on all 
visible frames and
 @end defopt
 
 @menu
-* Display functions::
+* ID display::
 * Window commands::
 @end menu
 
-@node Display functions
-@section Display functions
+@node ID display
+@section ID display
+
+By default, the ID of each tracked window is displayed as a mode line
+lighter. This behavior is controlled by @code{swsw-display-lighter}.
+
+Additionally, (custom) display functions could be added to
+@code{swsw-mode-hook}. These functions should enable ID display when
+@code{swsw-mode} is enabled, and disable ID display when
+@code{swsw-mode} is disabled. They can also make use of
+@code{swsw-before-command-hook} and @code{swsw-after-command-hook}
+(see @xref{Window commands}) to display IDs only during window
+selection. See the description and implementation of
+@code{swsw-mode-line-display-function} and
+@code{swsw-mode-line-conditional-display-function} below for more
+information.
+
+It is also possible to use @code{swsw-format-id} directly in
+e.g. @code{mode-line-format}, although details vary depending on how
+and where you want the IDs to be displayed.
+
+@defopt swsw-display-lighter
+Whether or not to show a mode line lighter. A non-nil value means show
+a mode line lighter.  A value of @code{nil} means don't show a mode
+line lighter. By default, @code{t} is used.
+@end defopt
 
-Display functions are used to display the ID of each window.
+@defopt swsw-mode-hook
+Hook run when enabling or disabling @code{swsw-mode}.
+@end defopt
 
-@defopt swsw-display-function
-Function used to display the ID of each window. This should either be a
-display function or @code{lighter}, in which case window IDs are shown using
-a mode line lighter. A display function must accept a single argument, which
-will be @code{t} when enabling @code{swsw-mode} and @code{nil} when disabling
-it. By default, @code{lighter} is used.
+@defopt swsw-id-format
+Format string for the window ID. Used in the mode line lighter, and
+display functions may use this format string to display the ID, but
+they can also ignore it. The string should contain a single occurrence
+of @code{%s}, which will be replaced by the ID. By default,
+@code{" <%s>"} is used.
 @end defopt
 
-@defun swsw-mode-line-display-function switch
-Reference implementation of a ``simple'' display function. Display window IDs 
on
-the mode line if SWITCH isn't @code{nil}, and hide window IDs from the mode
-line if SWITCH is @code{nil}. This display function respects
+@defun swsw-format-id window
+Format an ID string (according to @code{swsw-id-format}) for WINDOW.
+@end defun
+
+@defun swsw-mode-line-display-function
+Reference implementation of a ``simple'' display function, displaying
+window IDs at the beginning of the mode line. Display window IDs if
+@code{swsw-mode} is enabled, and disable displaying window IDs if
+@code{swsw-mode} is disabled.  This display function respects
 @code{swsw-id-format}.
 @end defun
 
-@defun swsw-mode-line-conditional-display-function switch
-Reference implementation of a conditional display function. Add a hook to
-@code{swsw-before-command-hook} which displays window IDs on the mode line and
-add a hook to @code{swsw-after-command-hook} which hides window IDs from the
-mode line if SWITCH isn't @code{nil}, and remove those hooks if SWITCH is
-@code{nil}. This display function respects @code{swsw-id-format}.
+@defun swsw-mode-line-conditional-display-function
+Reference implementation of a conditional display function, displaying
+window IDs at the beginning of the mode line during window selection.
+Add a hook to @code{swsw-before-command-hook} which displays window
+IDs on the mode line and add a hook to @code{swsw-after-command-hook}
+which hides window IDs from the mode line if @code{swsw-mode} is
+enabled, and remove those hooks if @code{swsw-mode} is disabled.  This
+display function respects @code{swsw-id-format}.
 @end defun
 
 @node Window commands
@@ -260,8 +285,9 @@ shadowed by a window ID.
 @end defvar
 
 @defvar swsw-window-count
-Amount of windows currently tracked. This variable can be used to
-conditionally run window commands.
+Amount of windows currently tracked, including the minibuffer (if it's
+active). It can be used to change the behavior of window commands (or
+display functions, @xref{ID display}).
 @end defvar
 
 @defun swsw-run-window-command fun