branch: externals/window-commander
commit 51b8c1eb7cba81bca65353a903c8e2bfda9f4f75
Author: Daniel Semyonov <cm...@dsemy.com>
Commit: Daniel Semyonov <cm...@dsemy.com>
; Update documentation according to latest changes
---
NEWS | 16 +++++++++++---
README | 20 +++++++++++------
swsw.el | 14 ++++++++----
swsw.texi | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++----------
4 files changed, 100 insertions(+), 25 deletions(-)
diff --git a/NEWS b/NEWS
index b9dec53345..e510df6c97 100644
--- a/NEWS
+++ b/NEWS
@@ -1,10 +1,20 @@
swsw NEWS -- history of user-visible changes.
See the end of the file for an explanation of the versioning scheme.
-* 1.2 (currently in development)
-No user facing changes have been made yet.
+* 2.0 (currently in development)
-* 1.1.2 (currently in development)
+** Add support for custom window management commands.
+Binding a command to a key in swsw-command-map allows you to call that
+command instead of selecting an ID.
+Currently three such commands are defined: swsw-select (o),
+swsw-select-minibuffer (m), swsw-delete (0).
+
+** Breaking changes.
+swsw-minibuffer-id is no longer defined or used anywhere, instead
+providing the same functionality through swsw-select-minibuffer.
+swsw-select no longer accepts a window ID as an optional argument.
+
+* 1.1.2
** Apply customization options immediately.
Customizing swsw-id-chars and swsw-scope and applying those changes now
diff --git a/README b/README
index 5f6247824d..d0914561f1 100644
--- a/README
+++ b/README
@@ -27,7 +27,7 @@ M-x package-install-file RET /path/to/clone/swsw-VERSION.tar
RET
Usage:
-Enable `swsw-mode':
+Enable ‘swsw-mode’:
(swsw-mode)
@@ -39,15 +39,21 @@ 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').
-- A single (predefined) character corresponds to the minibuffer
- (see `swsw-minibuffer-id').
-- Window IDs are assigned to all windows on all frames (by default,
- see `swsw-scope').
+ function (see ‘swsw-display-function’).
+- Window IDs are assigned to all windows on all frames except for
+ the minibuffer(by default, see ‘swsw-scope’).
C-x o ID switches focus to the window which corresponds to ID.
-You can customize `swsw-mode' using the customize interface:
+C-x o m switches focus to the minibuffer if it's active.
+
+C-x o 0 ID deletes the window which corresponds to ID.
+
+More commands can be added through ‘swsw-command-map’:
+
+(define-key swsw-command-map [?a] #'my-command)
+
+You can customize ‘swsw-mode’ using the customize interface:
M-x customize-group RET swsw RET
diff --git a/swsw.el b/swsw.el
index b900245eb5..d53d85979e 100644
--- a/swsw.el
+++ b/swsw.el
@@ -44,13 +44,19 @@
;; When swsw-mode is active:
;; - A window ID is displayed using a mode line lighter or a display
;; function (see ‘swsw-display-function’).
-;; - A single (predefined) character corresponds to the minibuffer
-;; (see ‘swsw-minibuffer-id’).
-;; - Window IDs are assigned to all windows on all frames (by default,
-;; see ‘swsw-scope’).
+;; - Window IDs are assigned to all windows on all frames except for
+;; the minibuffer(by default, see ‘swsw-scope’).
;;
;; C-x o ID switches focus to the window which corresponds to ID.
;;
+;; C-x o m switches focus to the minibuffer if it's active.
+;;
+;; C-x o 0 ID deletes the window which corresponds to ID.
+;;
+;; More commands can be added through ‘swsw-command-map’:
+;;
+;; (define-key swsw-command-map [?a] #'my-command)
+;;
;; You can customize ‘swsw-mode’ using the customize interface:
;;
;; M-x customize-group RET swsw RET
diff --git a/swsw.texi b/swsw.texi
index 731fb0d9c1..ddb9e61efb 100644
--- a/swsw.texi
+++ b/swsw.texi
@@ -132,9 +132,8 @@ In order to use any feature of the package,
@code{swsw-mode} must be enabled:
@cindex swsw-mode
@table @asis
@item @kbd{M-x swsw-mode RET}
-@end table
-
You can also add @code{(swsw-mode)} to your init file, instead.
+@end table
By default, window IDs will be shown as mode line lighters of the
form @code{<ID>}.
@@ -142,15 +141,36 @@ form @code{<ID>}.
@kindex C-x o
@cindex swsw-select
@table @asis
-@item @kbd{C-x o ID}
+@item @kbd{C-x o}
+Start window selection (@code{swsw-select}).
+This command sets a transient key map in which several window
+commands are defined, and window IDs can be selected.
+Selecting a window ID (by pressing @kbd{ID}) will switch to window
+corresponding to it.
+
+@kindex C-x o m
+@cindex swsw-select-minibuffer
+@item @kbd{C-x o m}
+Switch focus the minibuffer if it's active
+(@code{swsw-select-minibuffer}).
+
+@kindex C-x o 0
+@cindex swsw-delete
+@item @kbd{C-x o 0}
+Start window deletion (@code{swsw-delete}).
+This command sets a transient key map in which several window
+commands are defined, and window IDs can be selected.
+Selecting a window ID (by pressing @kbd{ID}) will delete the window
+corresponding to it.
@end table
-Switch to the window corresponding to @code{ID} (@code{swsw-select}).
+
+@xref{Window commands} for information regarding defining new commands.
@node Customization
@chapter Customization
-All customization, except for defining custom display functions, can be done
-through the customize interface:
+All customization, except for defining custom display functions and
+custom window commands, can be done through the customize interface:
@table @asis
@item @kbd{M-x customize-group RET swsw RET}
@@ -162,11 +182,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-minibuffer-id
-ID reserved for the minibuffer. This should be a single character. By default,
-@code{m} 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
@@ -185,6 +200,7 @@ frames, @code{visible} means consider all windows on all
visible frames and
@menu
* Display functions::
+* Window commands::
@end menu
@node Display functions
@@ -225,6 +241,43 @@ 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}.
@end defun
+@node Window commands
+@section Window commands
+
+Window commands are used to perform operations on specific
+windows. They are normal commands (interactive functions) which are
+bound to key in @code{swsw-command-map}. @code{swsw-select},
+@code{swsw-select-minibuffer} and @code{swsw-delete} are implemented
+as window commands.
+
+@defvar swsw--id-map
+Key map which is populated automatically with elements corresponding
+to all tracked windows. The ID of each window is converted to a vector
+(to serve as a key sequence), and corresponds to a command which calls
+@code{last-command} with the window corresponding to the ID as the
+sole argument. There should be no reason to modify it directly;
+it is reset whenever window configuration is updated.
+@end defvar
+
+@defvar swsw-command-map
+Key map which holds (usually) single character key bindings to window
+commands. This key map is set as the parent of @code{swsw--id-map}, so
+all window commands are available when it's active, unless they are
+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.
+@end defvar
+
+@defun swsw--run-window-command fun
+Run FUN as a window command. Run @code{swsw-before-command-hook}, set
+@code{this-command} to FUN, and set @code{swsw--id-map} as a transient
+map which runs @code{swsw-after-command-hook} on exit. This function
+can be used to easily define new window commands.
+@end defun
+
@node Keystroke Index
@appendix Keystroke Index
