branch: externals/window-commander
commit d46309a7a871dfa5a0a63090016d8607305c6d36
Author: Daniel Semyonov <dan...@dsemy.com>
Commit: Daniel Semyonov <dan...@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
