emacs-winum/README.org

341 lines
12 KiB
Org Mode
Raw Normal View History

2016-11-29 21:11:05 -05:00
#+TITLE: Window numbers for Emacs !
[[https://github.com/syl20bnr/spacemacs][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]] [[https://melpa.org/#/winum][file:https://melpa.org/packages/winum-badge.svg]] [[https://stable.melpa.org/#/winum][file:https://stable.melpa.org/packages/winum-badge.svg]]
2016-12-17 06:58:52 -05:00
* Contents :TOC:noexport:
2018-11-19 12:05:09 -05:00
- [[#introduction][Introduction]]
- [[#changelog][Changelog]]
- [[#nov-15-2018][Nov. 15 2018]]
- [[#initial-release-whats-changed-since-window-numbering][Initial release: what's changed since window-numbering]]
- [[#installation][Installation]]
- [[#using-melpa][Using Melpa]]
- [[#manual-installation][Manual installation]]
- [[#how-to-use][How to use]]
- [[#configuration][Configuration]]
- [[#keybindings][Keybindings]]
- [[#customize-options][Customize options]]
- [[#configuration-file-example][Configuration file example]]
- [[#future-developments][Future developments]]
2016-11-29 21:11:05 -05:00
* Introduction
Window numbers for Emacs: Navigate your windows and frames using numbers !
This package is an extended and actively maintained version of the
2016-12-17 06:58:52 -05:00
[[https://github.com/nschum/window-numbering.el][window-numbering]] package by Nikolaj Schumacher, with some ideas and code taken
from [[https://github.com/abo-abo/ace-window][ace-window]].
2016-11-29 21:11:05 -05:00
This version brings, among other things, support for number sets across multiple
frames, giving the user a smoother experience of multi-screen Emacs.
2018-11-19 12:05:09 -05:00
* Changelog
** Nov. 15 2018
- Added customize variable =winum-format=, a format string to configure how the
window number appears in the mode-line
** Initial release: what's changed since window-numbering
2016-12-23 17:36:43 -05:00
This package brings a lot of additions to the old window-numbering:
- Number sets across multiple frames, giving a smoother experience of
multi-screen Emacs
- 3 possible scopes: frame-local, visible frames or all frames
- =get-window-by-number= public function, needed in Spacemacs and for future
developments.
- Unlimited window numbers
- =select-window-by-number= can now be used interactively to select a window
using prefix arg or =read-from-minibuffer=, allowing the selection of an
unlimited number.
- Ignore buffers by name
- =;;;###autoload= all functions that should have public visibility
- Improved =customize= integration
- Removed =window-numbering-before-assign-hook=, which just duplicated
=window-numbering-assign-func= in a more complicated fashion
- New default key bindings under the ~C-x w~ prefix, to be compliant with Emacs
key bindings conventions and native Emacs key bindings
- =winum-set-keymap-prefix= helper function to change the prefix more easily
- More detailed README.org
- Improved docstrings
- Simplified implementation for better readability
2016-11-29 21:11:05 -05:00
* Installation
2016-12-17 06:58:52 -05:00
** Using Melpa
The recommended way of installing =winum= is from the [[https://melpa.org/#/winum][Melpa]] package repository:
#+BEGIN_SRC emacs-lisp
M-x package-install RET winum RET
#+END_SRC
You will find instructions to setup Melpa [[https://github.com/melpa/melpa#usage][here]] if you don't have it setup yet.
2016-12-23 17:36:43 -05:00
Once the package is installed, you need to load and activate =winum-mode= in
your Emacs configuration:
2016-12-17 06:58:52 -05:00
#+BEGIN_SRC emacs-lisp
(require 'winum)
(winum-mode)
#+END_SRC
** Manual installation
2016-11-29 21:11:05 -05:00
- Clone the repo:
#+BEGIN_SRC shell
cd /path/to/install/folder
2017-01-28 16:25:17 -05:00
git clone https://github.com/deb0ch/emacs-winum
2016-11-29 21:11:05 -05:00
#+END_SRC
- Add the following to your Emacs configuration:
#+BEGIN_SRC emacs-lisp
2017-01-28 16:25:17 -05:00
(add-to-list 'load-path "/path/to/install/folder/emacs-winum/")
2016-11-29 21:11:05 -05:00
(require 'winum)
2016-11-29 21:11:05 -05:00
(winum-mode)
2016-11-29 21:11:05 -05:00
#+END_SRC
* How to use
| Key binding | Description |
|-------------+---------------------------------------------------------------------------------------------|
| ~C-x w <n>~ | select window <n>, where <n> ranges from 0 to 9. A negative argument deletes the window. |
| ~C-x w `~ | select window by number. Number can be given as prefix arg or will be read from minibuffer. |
2016-12-05 08:59:28 -05:00
- =select-window-0-or-10=
2016-12-17 07:15:20 -05:00
By default, ~C-x w 0~ is bound to =select-window-0-or-10=. If window 0 is not
assigned, it will act on the window 10 instead.
2016-12-05 08:59:28 -05:00
You can rebind this to the more straightforward =select-window-0= if you
prefer.
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
- =select-window-by-number=
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
If you happen to have more than 10 windows, you can use the
=select-window-by-number= function, bound by default to ~C-x w `~.
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
This function allows several ways to input the window number:
- Use a numbered prefix argument.\\
*Ex:* ~C-1 C-2 C-x w `~ to select window 12.
2016-12-05 08:59:28 -05:00
- Use a negative prefix argument to delete the window.\\
*Ex:* ~C-- C-1 C-2 C-x w `~ to delete window 12.
2016-12-05 08:59:28 -05:00
- Use the negative prefix argument to delete window 0.\\
*Ex:* ~C-- C-x w `~ to delete window 0.
2016-12-05 08:59:28 -05:00
- Use the default prefix argument to delete current window.\\
*Ex:* ~C-u C-x w `~ to delete current window.
2016-12-05 08:59:28 -05:00
- If no prefix argument ig given, a number is read from minibuffer. A negative
input will delete the window instead of selecting it.
2016-11-29 21:11:05 -05:00
* Configuration
2016-12-12 04:20:39 -05:00
** Keybindings
The default prefix for key bindings is ~C-x w~ for compatibility with native
Emacs bindings.
If you don't like ~C-x w~, you can set a prefix of your choosing using the
function =winum-set-keymap-prefix=:
2016-12-15 12:29:38 -05:00
#+BEGIN_SRC elisp
(winum-set-keymap-prefix (kbd "C-c"))
#+END_SRC
This function overrides the value of =winum-keymap=, so you should call it
before customization of =winum-keymap= and/or after customization of
=winum-base-map=. Its argument must be a key sequence, like the ones returned by
=kbd=.
2016-12-15 12:29:38 -05:00
If you prefer no to use a prefix and have even shorter bindings, you can also
override =winum-keymap= in the minor mode bindings table:
2016-12-05 08:59:28 -05:00
#+BEGIN_SRC emacs-lisp
(setq winum-keymap
2016-12-15 12:29:38 -05:00
(let ((map (make-sparse-keymap)))
(define-key map (kbd "C-`") 'winum-select-window-by-number)
(define-key map (kbd "C-²") 'winum-select-window-by-number)
2016-12-15 12:29:38 -05:00
(define-key map (kbd "M-0") 'winum-select-window-0-or-10)
(define-key map (kbd "M-1") 'winum-select-window-1)
(define-key map (kbd "M-2") 'winum-select-window-2)
(define-key map (kbd "M-3") 'winum-select-window-3)
(define-key map (kbd "M-4") 'winum-select-window-4)
(define-key map (kbd "M-5") 'winum-select-window-5)
(define-key map (kbd "M-6") 'winum-select-window-6)
(define-key map (kbd "M-7") 'winum-select-window-7)
(define-key map (kbd "M-8") 'winum-select-window-8)
map))
(require 'winum)
2016-12-05 08:59:28 -05:00
(winum-mode)
2016-11-29 21:11:05 -05:00
#+END_SRC
Note that it is important to set =winum-keymap= /before/ the =require=.
You can also use the more conventional =define-key= on =winum-keymap=:
#+BEGIN_SRC emacs-lisp
(define-key winum-keymap (kbd "C-x y o l o") 'winum-select-window-by-number)
#+END_SRC
2016-11-29 21:11:05 -05:00
*NB:* Both ~`~ and ~²~ are mapped to =winum-select-window-by-number= by default
to handle both =qwerty= and =azerty= keyboard layouts. If you are using a
different kind of layout, the recommended place to map it is the key
beside ~1~.
2016-12-15 12:29:38 -05:00
** Customize options
2016-12-05 08:59:28 -05:00
Several options are available through Emacs' Customize interface under
=convenience= > =winum=:
2016-11-29 21:11:05 -05:00
- =winum-scope=
2016-11-29 21:11:05 -05:00
2016-12-17 07:15:20 -05:00
Frames affected by a number set. Choices are 'frame-local 'visible or
'global.
2016-11-29 21:11:05 -05:00
2016-12-17 07:15:20 -05:00
Default: 'global
2016-11-29 21:11:05 -05:00
- =winum-reverse-frame-list=
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
If t, order frames by reverse order of creation. Has effect only when
2016-12-17 07:15:20 -05:00
=winum-scope= is not 'frame-local.
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
Default: =nil=
2016-11-29 21:11:05 -05:00
- =winum-auto-assign-0-to-minibuffer=
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
If non-nil, =winum-mode= assigns 0 to the minibuffer if active.
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
Default: =t=
2016-11-29 21:11:05 -05:00
- =winum-assign-functions=
2016-11-29 21:11:05 -05:00
List of functions called for each window by `winum-mode'.
2016-11-29 21:11:05 -05:00
These functions allow for deterministic assignment of numbers to windows. Each
function is called for every window. A function should return the number to be
assigned to a window or nil. The /first/ function to output a number for
a given window will determine this window's number (if more than 1 function
assigns a number a warning will be logged in the messages buffer).
If the list is empty or if every function returns nil for a given window winum
will proceed to automatic number assignment.
Since this list is meant to allow custom window assignment for /mutiple/
packages at once it should never be directly set, only added to and removed
from.
These functions, along with ~winum-auto-assign-0-to-minibuffer~, are the only
way to have 0 assigned to a window.
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
Example: always assign *Calculator* the number 9 and *NeoTree* the number 0:
2016-11-29 21:11:05 -05:00
#+BEGIN_SRC emacs-lisp
(defun winum-assign-9-to-calculator-8-to-flycheck-errors ()
(cond
((equal (buffer-name) "*Calculator*") 9)
((equal (buffer-name) "*Flycheck errors*") 8)))
(defun winum-assign-0-to-neotree-and ()
(when (string-match-p (buffer-name) ".*\\*NeoTree\\*.*") 10))
(add-to-list 'winum-assign-functions #'winum-assign-9-to-calculator-8-to-flycheck-errors)
(add-to-list 'winum-assign-functions #'winum-assign-0-to-neotree)
#+END_SRC
2016-11-29 21:11:05 -05:00
2016-12-17 07:59:18 -05:00
Default: =nil=
2016-12-04 14:38:42 -05:00
- =winum-auto-setup-mode-line=
2016-12-05 08:59:28 -05:00
When nil, =winum-mode= will not display window numbers in the mode-line. You
might want this to be nil if you use a package that already manages window
numbers in the mode-line.
2016-12-04 14:38:42 -05:00
2016-12-05 08:59:28 -05:00
Default: =t=
2016-12-04 14:38:42 -05:00
2018-11-19 12:05:09 -05:00
- =winum-format=
Format string defining how the window number looks like in the mode-line.
This string is passed to the =format= function along with the result of
=winum-get-number-string=.
Default: =" %s "=
- =winum-mode-line-position=
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
The position in the mode-line =winum-mode= displays the number.
2016-11-29 21:11:05 -05:00
2016-12-17 07:15:20 -05:00
Default: =1=
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
- =winum-ignored-buffers=
2016-11-29 21:11:05 -05:00
2016-12-17 07:59:18 -05:00
List of buffers to ignore when assigning numbers.
2016-11-29 21:11:05 -05:00
2016-12-12 04:20:39 -05:00
Default: '(" *which-key*")
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
- face: =winum-face=
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
Face used for the number in the mode-line.
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
** Configuration file example
Here is an example that you could put in your =.emacs=, which includes all
available winum options.
#+BEGIN_SRC emacs-lisp
(setq winum-keymap
2016-12-15 12:29:38 -05:00
(let ((map (make-sparse-keymap)))
(define-key map (kbd "C-`") 'winum-select-window-by-number)
(define-key map (kbd "C-²") 'winum-select-window-by-number)
2016-12-15 12:29:38 -05:00
(define-key map (kbd "M-0") 'winum-select-window-0-or-10)
(define-key map (kbd "M-1") 'winum-select-window-1)
(define-key map (kbd "M-2") 'winum-select-window-2)
(define-key map (kbd "M-3") 'winum-select-window-3)
(define-key map (kbd "M-4") 'winum-select-window-4)
(define-key map (kbd "M-5") 'winum-select-window-5)
(define-key map (kbd "M-6") 'winum-select-window-6)
(define-key map (kbd "M-7") 'winum-select-window-7)
(define-key map (kbd "M-8") 'winum-select-window-8)
map))
(require 'winum)
(defun winum-assign-9-to-calculator-8-to-flycheck-errors ()
2016-12-05 08:59:28 -05:00
(cond
((equal (buffer-name) "*Calculator*") 9)
((equal (buffer-name) "*Flycheck errors*") 8)))
(defun winum-assign-0-to-neotree-and ()
(when (string-match-p (buffer-name) ".*\\*NeoTree\\*.*") 10))
(add-to-list 'winum-assign-functions #'winum-assign-9-to-calculator-8-to-flycheck-errors)
(add-to-list 'winum-assign-functions #'winum-assign-0-to-neotree)
2016-12-05 08:59:28 -05:00
2016-12-15 12:29:38 -05:00
(set-face-attribute 'winum-face nil :weight 'bold)
2016-12-05 08:59:28 -05:00
(setq window-numbering-scope 'global
winum-reverse-frame-list nil
winum-auto-assign-0-to-minibuffer t
winum-assign-func 'my-winum-assign-func
winum-auto-setup-mode-line t
2018-11-19 12:05:09 -05:00
winum-format " %s "
winum-mode-line-position 1
winum-ignored-buffers '(" *which-key*"))
2016-11-29 21:11:05 -05:00
2016-12-05 08:59:28 -05:00
(winum-mode)
#+END_SRC
* Future developments
- send buffer to numbered window
2017-01-14 10:01:29 -05:00
Send current window's buffer to window N. With prefix argument focus will
follow.
- swap buffer with numbered window
2017-01-14 10:01:29 -05:00
Same as previous, but will swap buffers instead of just sending them.
- Evilify
2017-01-14 10:01:29 -05:00
Adapt the package to the famous `evil-mode` and use a leader key.
- Override native =other-window= (~C-x o~) to use window numbers
- Autocomplete read-from-minibuffer
2016-12-23 17:36:43 -05:00
- Things that you have thought of and I haven't :smile_cat: