emacs-winum/README.org

352 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]]
2019-09-11 12:11:12 -04:00
- [[#sep-11-2019][Sep. 11 2019]]
2018-11-19 12:05:09 -05:00
- [[#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
This package is a fork of the [[https://github.com/deb0ch/emacs-winum][winum]] package, which is itself a fork of the
[[https://github.com/nschum/window-numbering.el][window-numbering]] package.
2016-11-29 21:11:05 -05:00
Compared to winum, this fork adds support for windows having arbitrary Lisp values
as identifiers, as opposed to strictly increasing numbers. The public
API is largely the same, however, and simple numbers are still the default.
2016-11-29 21:11:05 -05:00
2018-11-19 12:05:09 -05:00
* Changelog
2019-09-11 12:11:12 -04:00
** Sep. 11 2019
- Added customize variable =winum-ignored-buffers-regexp= to ignored buffers
based on regexps.
2018-11-19 12:05:09 -05:00
** 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)))
2019-02-18 04:37:01 -05:00
(defun winum-assign-0-to-neotree ()
(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
- =winum-ignored-buffers-regexp=
List of regexps for buffer names. Matching buffers will be ignored when
assigning numbers. See [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Regexps.html][Emacs' documentation on regexps]] for syntax.
Default: '()
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)))
2019-02-18 04:37:01 -05:00
(defun winum-assign-0-to-neotree ()
(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*")
winum-ignored-buffers-regexp '(" \\*Treemacs-.*"))
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: