[elpa] externals/ace-window 5e733ff 35/92: ace-window.el: Documentation and minor changes

[Stefan Monnier]

branch: externals/ace-window
commit 5e733ff695062725d39acd241bf8b3c6efcc5447
Author: Bob Weiner <rsw@gnu.org>
Commit: Oleh Krehel <ohwoeowho@gmail.com>

    ace-window.el: Documentation and minor changes
    
    Fixes #118
---
 ace-window.el | 160 ++++++++++++++++++++++++++++++++++------------------------
 1 file changed, 94 insertions(+), 66 deletions(-)

diff --git a/ace-window.el b/ace-window.el
index 3ad836c..1e36d34 100644
--- a/ace-window.el
+++ b/ace-window.el
@@ -26,11 +26,12 @@
 
 ;;; Commentary:
 ;;
-;; The main function, `ace-window' is meant to replace `other-window'.
-;; In fact, when there are only two windows present, `other-window' is
-;; called.  If there are more, each window will have its first
-;; character highlighted.  Pressing that character will switch to that
-;; window.
+;; The main function, `ace-window' is meant to replace `other-window'
+;; by assigning each window a short, unique label.  When there are only
+;; two windows present, `other-window' is called (unless
+;; aw-dispatch-always is set non-nil).  If there are more, each
+;; window will have its first label character highlighted.  Once a
+;; unique label is typed, ace-window will switch to that window.
 ;;
 ;; To setup this package, just add to your .emacs:
 ;;
@@ -38,23 +39,24 @@
 ;;
 ;; replacing "M-p"  with an appropriate shortcut.
 ;;
-;; Depending on your window usage patterns, you might want to set
+;; By default, ace-window uses numbers for window labels so the window
+;; labeling is intuitively ordered.  But if you prefer to type keys on
+;; your home row for quicker access, use this setting:
 ;;
 ;;    (setq aw-keys '(?a ?s ?d ?f ?g ?h ?j ?k ?l))
 ;;
-;; This way they are all on the home row, although the intuitive
-;; ordering is lost.
-;;
-;; If you don't want the gray background that makes the red selection
-;; characters stand out more, set this:
+;; Whenever ace-window prompts for a window selection, it grays out
+;; all the window characters, highlighting window labels in red.  To
+;; disable this behavior, set this:
 ;;
 ;;    (setq aw-background nil)
 ;;
-;; If you want to know the selection characters ahead of time, you can
-;; turn on `ace-window-display-mode'.
+;; If you want to know the selection characters ahead of time, turn on
+;; `ace-window-display-mode'.
 ;;
 ;; When prefixed with one `universal-argument', instead of switching
-;; to selected window, the selected window is swapped with current one.
+;; to the selected window, the selected window is swapped with the
+;; current one.
 ;;
 ;; When prefixed with two `universal-argument', the selected window is
 ;; deleted instead.
@@ -85,11 +87,13 @@
   :type 'boolean)
 
 (defcustom aw-ignored-buffers '("*Calc Trail*" "*LV*")
-  "List of buffers to ignore when selecting window."
+  "List of buffers and major-modes to ignore when choosing a window from the 
window list.
+Active only when `aw-ignore-on' is non-nil.  Windows displaying these
+buffers can still be chosen by typing their specific labels."
   :type '(repeat string))
 
 (defcustom aw-ignore-on t
-  "When t, `ace-window' will ignore `aw-ignored-buffers'.
+  "When t, `ace-window' will ignore buffers and major-modes in 
`aw-ignored-buffers'.
 Use M-0 `ace-window' to toggle this value."
   :type 'boolean)
 
@@ -133,6 +137,42 @@ Its value is a (width . height) pair in pixels or nil for 
the default frame size
 (0 . 0) is special and means make the frame size the same as the last selected 
frame size."
   :type '(cons integer integer))
 
+;; Must be defined before `aw-make-frame-char' since its :set function 
references this.
+(defvar aw-dispatch-alist
+  '((?x aw-delete-window "Delete Window")
+    (?m aw-swap-window "Swap Windows")
+    (?M aw-move-window "Move Window")
+    (?j aw-switch-buffer-in-window "Select Buffer")
+    (?n aw-flip-window)
+    (?u aw-switch-buffer-other-window "Switch Buffer Other Window")
+    (?c aw-split-window-fair "Split Fair Window")
+    (?v aw-split-window-vert "Split Vert Window")
+    (?b aw-split-window-horz "Split Horz Window")
+    (?o delete-other-windows "Delete Other Windows")
+    (?? aw-show-dispatch-help))
+  "List of actions for `aw-dispatch-default'.
+Each action is a list of either:
+  (char function description) where function takes a single window argument
+or
+  (char function) where function takes no argument and the description is 
omitted.")
+
+(defun aw-set-make-frame-char (option value)
+  ;; Signal an error if `aw-make-frame-char' is ever set to an invalid
+  ;; or conflicting value.
+  (when value
+    (cond ((not (characterp value))
+          (user-error "`aw-make-frame-char' must be a character, not `%s'" 
value))
+         ((memq value aw-keys)
+          (user-error "`aw-make-frame-char' is `%c'; this conflicts with the 
same character in `aw-keys'" value))
+         ((assq value aw-dispatch-alist)
+          (user-error "`aw-make-frame-char' is `%c'; this conflicts with the 
same character in `aw-dispatch-alist'" value))))
+  (set option value))
+
+(defcustom aw-make-frame-char ?z
+  "Non-existing ace window label character that triggers creation of a new 
single-window frame for display."
+  :set 'aw-set-make-frame-char
+  :type 'character)
+
 (defface aw-leading-char-face
   '((((class color)) (:foreground "red"))
     (((background dark)) (:foreground "gray100"))
@@ -154,12 +194,17 @@ Its value is a (width . height) pair in pixels or nil for 
the default frame size
 
 ;;* Implementation
 (defun aw-ignored-p (window)
-  "Return t if WINDOW should be ignored."
+  "Return t if WINDOW should be ignored when choosing from the window list."
   (or (and aw-ignore-on
-           (member (buffer-name (window-buffer window))
-                   aw-ignored-buffers))
+          ;; Ignore major-modes and buffer-names in `aw-ignored-buffers'.
+          (or (memq (buffer-local-value 'major-mode (window-buffer window))
+                    aw-ignored-buffers)
+              (member (buffer-name (window-buffer window)) 
aw-ignored-buffers)))
+      ;; Ignore selected window if `aw-ignore-current' is non-nil.
       (and aw-ignore-current
            (equal window (selected-window)))
+      ;; When `ignore-window-parameters' is nil, ignore windows whose
+      ;; `no-other-window’ or `no-delete-other-windows' parameter is non-nil.
       (unless ignore-window-parameters
         (cl-case this-command
           (ace-select-window (window-parameter window 'no-other-window))
@@ -286,23 +331,10 @@ LEAF is (PT . WND)."
 (defun aw-set-mode-line (str)
   "Set mode line indicator to STR."
   (setq ace-window-mode str)
-  (if aw-minibuffer-flag (message "%s" str))
+  (when (and aw-minibuffer-flag ace-window-mode)
+    (message "%s" str))
   (force-mode-line-update))
 
-(defvar aw-dispatch-alist
-  '((?x aw-delete-window "Delete Window")
-    (?m aw-swap-window "Swap Windows")
-    (?M aw-move-window "Move Window")
-    (?j aw-switch-buffer-in-window "Select Buffer")
-    (?n aw-flip-window)
-    (?u aw-switch-buffer-other-window "Switch Buffer Other Window")
-    (?c aw-split-window-fair "Split Fair Window")
-    (?v aw-split-window-vert "Split Vert Window")
-    (?b aw-split-window-horz "Split Horz Window")
-    (?o delete-other-windows)
-    (?? aw-show-dispatch-help))
-  "List of actions for `aw-dispatch-default'.")
-
 (defun aw--dispatch-action (char)
   "Return item from `aw-dispatch-alist' matching CHAR."
   (assoc char aw-dispatch-alist))
@@ -334,42 +366,35 @@ pixels."
   (aw-switch-to-window window)
   (aw-make-frame))
 
-(defcustom aw-make-frame-char ?z
-  "Character that triggers creation of a new single-window frame for display."
-  :set 'aw-set-make-frame-char
-  :type 'character)
-
-(defun aw-set-make-frame-char (symbol value)
-  "Set SYMBOL `aw-make-frame-char' to VALUE after checking it."
-  (when value
-    (cond ((not (characterp value))
-           (user-error
-            "must be a character, not `%s'" value))
-          ((memq value aw-keys)
-           (user-error
-            "`%c' conflicts with the same character in `aw-keys'" value))
-          ((assq value aw-dispatch-alist)
-           (user-error
-            "`%c' conflicts with the same character in `aw-dispatch-alist'" 
value))))
-  (set symbol value))
-
 (defun aw-dispatch-default (char)
   "Perform an action depending on CHAR."
-  (cond ((= char (aref (kbd "C-g") 0))
-         (throw 'done 'exit))
+  (cond ((avy-mouse-event-window char))
+       ((= char (aref (kbd "C-g") 0))
+        (throw 'done 'exit))
         ((= char aw-make-frame-char)
          (aw-use-frame (selected-window))
          (throw 'done 'exit))
-        (t
+       (t
          (let ((action (aw--dispatch-action char)))
-           (cl-destructuring-bind (_key fn &optional description) action
-             (if action
-                 (if (and fn description)
-                     (prog1 (setq aw-action fn)
-                       (aw-set-mode-line (format " Ace - %s" description)))
-                   (funcall fn)
-                   (throw 'done 'exit))
-               (avy-handler-default char)))))))
+            ;; Prevent cl-destructuring-bind from triggering an error when
+            ;; given too few arguments.
+            (cl-destructuring-bind (_key fn &optional description) (or action 
'(nil nil nil))
+               (if action
+                  (if (and fn description)
+                       (prog1 (setq aw-action fn)
+                        (aw-set-mode-line (format " Ace - %s" description)))
+                    (funcall fn)
+                    (throw 'done 'exit))
+                ;; Remove any possible ace-window command char that may
+                ;; precede the last specified window label, so
+                ;; functions can use `avy-current-path' as the chosen
+                ;; window label.
+                (when (and (> (length avy-current-path) 0)
+                           (assq (aref avy-current-path 0) aw-dispatch-alist))
+                  (setq avy-current-path (substring avy-current-path 1)))
+                ;; Prevent any char from triggering an avy dispatch command.
+                (let ((avy-dispatch-alist))
+                  (avy-handler-default char))))))))
 
 (defun aw-select (mode-line &optional action)
   "Return a selected other window.
@@ -556,8 +581,11 @@ Windows are numbered top down, left to right."
                              (or description fn))))
                  aw-dispatch-alist
                  "\n"))
-  (mapc #'delete-overlay aw-overlays-back)
-  (call-interactively 'ace-window))
+  ;; Prevent this from replacing any help display
+  ;; in the minibuffer.
+  (let (aw-minibuffer-flag)
+    (mapc #'delete-overlay aw-overlays-back)
+    (call-interactively 'ace-window)))
 
 (defun aw-delete-window (window)
   "Delete window WINDOW."