code.delx.au - gnu-emacs-elpa/blob - packages/ace-window/README.md

   1 # ace-window
   2
   3 **GNU Emacs package for selecting a window to switch to**
   4
   5 ## What and why
   6
   7 I'm sure you're aware of `other-window` command. While it's great for
   8 two windows, it quickly loses it's value when there are more windows:
   9 you need to call it many times, and since it's not easily predictable,
  10 you have to check each time if you're in the window that you wanted.
  11
  12 Another approach is to use `windmove-left`, `windmove-up` etc.  These
  13 are fast and predictable. Their disadvantage is that they need 4 key
  14 bindings.  The default ones are shift+arrows, which are hard to reach.
  15
  16 This package aims to take the speed and predictability of `windmove`
  17 and pack it into a single key binding, similar to `other-window`.
  18
  19 ## Setup
  20
  21 Just assign `ace-window` to a short key binding, as switching windows
  22 is a common task. I suggest <kbd>M-p</kbd>, as it's short and not
  23 bound in the default Emacs.
  24
  25 ## Usage
  26
  27 When there are two windows, `ace-window` will call `other-window`.  If
  28 there are more, each window will have its first character highlighted.
  29 Pressing that character will switch to that window.  Note that, unlike
  30 `ace-jump-mode`, the point position will not be changed: it's the same
  31 behavior as that of `other-window`.
  32
  33 The windows are ordered top-down, left-to-right. This means that if
  34 you remember your window layouts, you can switch windows without even
  35 looking at the leading char.  For instance, the top left window will
  36 always be `1`.
  37
  38 `ace-window` works across multiple frames, as you can see from the
  39 [in-action gif](http://oremacs.com/download/ace-window.gif).
  40
  41 ## Swap and delete window
  42
  43 - You can swap windows by calling `ace-window` with a prefix argument <kbd>C-u</kbd>.
  44
  45 - You can delete the selected window by calling `ace-window` with a double prefix argument, i.e. <kbd>C-u C-u</kbd>.
  46
  47 ## Change the action midway
  48
  49 You can also start by calling `ace-window` and then decide to switch the action to `delete` or `swap` etc.  By default the bindings are:
  50
  51 - <kbd>x</kbd> - delete window
  52 - <kbd>m</kbd> - swap (move) window
  53 - <kbd>v</kbd> - split window vertically
  54 - <kbd>b</kbd> - split window horizontally
  55 - <kbd>n</kbd> - select the previous window
  56 - <kbd>i</kbd> - maximize window (select which window)
  57 - <kbd>o</kbd> - maximize current window
  58
  59 In order for it to work, these keys *must not* be in `aw-keys` and you have to have `aw-dispatch-always` set to `t`.
  60
  61 ## Customization
  62 Aside from binding `ace-window`:
  63
  64     (global-set-key (kbd "M-p") 'ace-window)
  65
  66 maybe you'd like the following customizations:
  67
  68 ### `aw-keys`
  69 `aw-keys` - the sequence of leading characters for each window:
  70
  71     (setq aw-keys '(?a ?s ?d ?f ?g ?h ?j ?k ?l))
  72
  73 `aw-keys` are 0-9 by default, which is reasonable, but in the setup
  74 above, the keys are on the home row.
  75
  76 ### `aw-scope`
  77 The default one is `global`, which means that `ace-window` will work
  78 across frames. If you set this to `frame`, `ace-window` will offer you
  79 the windows only on current frame.
  80
  81 ### `aw-background`
  82
  83 By default, `ace-window` temporarily sets a gray background and
  84 removes color from available windows in order to make the
  85 window-switching characters more visible. This is the behavior
  86 inherited from `ace-jump-mode`.
  87
  88 This behavior might not be necessary, as you already know the locations
  89 where to look, i.e. the top-left corners of each window.
  90 So you can turn off the gray background with:
  91
  92     (setq aw-background nil)
  93
  94 ### `aw-dispatch-always`
  95
  96 When non-nil, `ace-window` will issue a `read-char` even for one window.
  97 This will make `ace-window` act differently from `other-window` for one
  98 or two windows. This is useful to change the action midway
  99 and execute other action other than the *jump* default.
 100 By default is set to `nil`
 101
 102 ### `aw-dispatch-alist`
 103
 104 This is the list of actions that you can trigger from `ace-window` other than the
 105 *jump* default.
 106 By default is:
 107
 108     (defvar aw-dispatch-alist
 109     '((?x aw-delete-window " Ace - Delete Window")
 110         (?m aw-swap-window " Ace - Swap Window")
 111         (?n aw-flip-window)
 112         (?v aw-split-window-vert " Ace - Split Vert Window")
 113         (?b aw-split-window-horz " Ace - Split Horz Window")
 114         (?i delete-other-windows " Ace - Maximize Window")
 115         (?o delete-other-windows))
 116     "List of actions for `aw-dispatch-default'.")
 117
 118 If the pair key-action is followed by a string, then `ace-window` will be
 119 invoked again to be able to select on which window you want to select the
 120 action. Otherwise the current window is selected.