improve README.org

This commit is contained in:
deb0ch 2016-12-05 14:59:28 +01:00
parent a77e97fd0f
commit e947f05c93

View file

@ -2,20 +2,14 @@
#+TITLE: Window numbers for Emacs !
**** TODO better example for assign-func
**** TODO example with all options
* Contents :TOC:
- [[#better-example-for-assign-func][better example for assign-func]]
- [[#example-with-all-options][example with all options]]
- [[#introduction][Introduction]]
- [[#installation][Installation]]
- [[#how-to-use][How to use]]
- [[#navigate-windows][Navigate windows]]
- [[#delete-windows][Delete windows]]
- [[#configuration][Configuration]]
- [[#custom-keymap][Custom keymap]]
- [[#customize-options][Customize options]]
- [[#configuration-file-example][Configuration file example]]
* Introduction
Window numbers for Emacs: Navigate your windows and frames using numbers !
@ -28,7 +22,6 @@ This version brings, among other things, support for number sets across multiple
frames, giving the user a smoother experience of multi-screen Emacs.
* Installation
- Clone the repo:
#+BEGIN_SRC shell
@ -46,104 +39,170 @@ frames, giving the user a smoother experience of multi-screen Emacs.
(winum-mode)
#+END_SRC
* How to use
** Navigate windows
Use ~M-1~ to ~M-9~ to navigate windows numbered 1 to 9.
- =select-window-[0..9]=
The functions for selecting windows are the =select-window-[1..N]= functions,
where N is the maximum window number.
Use ~M-1~ to ~M-9~ to navigate windows numbered 1 to 9.
See [[#configuration][configuration]] to rebind them any way you prefer.
By default, ~M-0~ is bound to =select-window-0-or-10=, which behaves like
the other ones except that if 0 is not assigned it will act on the window 10
instead.
** Delete windows
Use ~M-1~ to ~M-9~ with an Emacs prefix argument to delete a window instead of
selecting it.
You can rebind this to the more straightforward =select-window-0= if you
prefer.
- =select-window-by-number=
If you happen to have more than 10 windows, you can use the
=select-window-by-number= function, bound by default to ~C-`~.
This function allows several ways to input the window number:
- Use a numbered prefix argument.\\
*Ex:* ~C-1 C-2 C`~ to select window 12.
- Use a negative prefix argument to delete the window.\\
*Ex:* ~C-- C-1 C-2 C`~ to delete window 12.
- Use the negative prefix argument to delete window 0.\\
*Ex:* ~C-- C-`~ to delete window 0.
- Use the default prefix argument to delete current window.\\
*Ex:* ~C-u C-`~ to delete current window.
- If no prefix argument ig given, a number is read from minibuffer. A negative
input will delete the window instead of selecting it.
*NB:* On Spacemacs you can specify the prefix argument using ~SPC u~.
*Ex:* ~SPC u - 1 2 C-`~ to delete window 12.
* Configuration
** Custom keymap
To define your own bindings and override the default ones, override
=winum-keymap= before activating the mode:
To define your own bindings and override the default ones, override
=winum-keymap= before activating the mode:
#+BEGIN_SRC emacs-lisp
(require 'winum)
#+BEGIN_SRC emacs-lisp
(require 'winum)
(setq winum-keymap (let ((map (make-sparse-keymap)))
(define-key map "\M-m 0" 'select-window-0)
; ...
(define-key map "\M-m 9" 'select-window-9)
map))
(winum-mode)
(setq winum-keymap (let ((map (make-sparse-keymap)))
(define-key map "\M-m 0" 'select-window-0)
; ...
(define-key map "\M-m 9" 'select-window-9)
map))
(winum-mode)
#+END_SRC
This way your bindings will not error when the mode is turned off.
** Customize options
Several options are available through Emacs' =Customize= interface under
Several options are available through Emacs' Customize interface under
=convenience= > =winum=:
- =winum-scope=
Frames affected by a number set. Choices are 'frame-local 'visible or 'global.
Frames affected by a number set. Choices are ='frame-local= ='visible= or
='global=.
Default: 'global
Default: ='global=
- =winum-reverse-frame-list=
If t, order frames by reverse order of creation. Has effect only when
`winum-scope' is not 'frame-local.
If t, order frames by reverse order of creation. Has effect only when
=winum-scope= is not ='frame-local=.
Default: nil
Default: =nil=
- =winum-auto-assign-0-to-minibuffer=
If non-nil, =winum-mode= assigns 0 to the minibuffer if active.
If non-nil, =winum-mode= assigns 0 to the minibuffer if active.
Default: t
Default: =t=
- =winum-assign-func=
Function called for each window by =winum-mode=. This is called
before automatic assignment begins. The function should return a number to have
it assigned to the current-window, nil otherwise.
Function called for each window by =winum-mode=. This is called before
automatic assignment begins. The function should return a number to have it
assigned to the current-window, =nil= otherwise.
Default: nil
Default: =nil=
Example: always assign the calculator window the number 9:
Example: always assign *Calculator* the number 9 and *NeoTree* the number 0:
#+BEGIN_SRC emacs-lisp
(setq winum-assign-func
(lambda () (when (equal (buffer-name) "*Calculator*") 9)))
(defun my-winum-assign-func ()
(cond
((equal (buffer-name) "*Calculator*")
9)
((string-match-p (buffer-name) ".*\\*NeoTree\\*.*")
0)
(t
nil)))
(setq winum-assign-func 'my-winum-assign-func)
#+END_SRC
- =winum-auto-setup-mode-line=
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.
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.
Default: t
Default: =t=
- =winum-mode-line-position=
The position in the mode-line `winum-mode' displays the number.
The position in the mode-line =winum-mode= displays the number.
Default: 1
- =winum-window-number-max= 10
Max number of windows that can be numbered.
Default: 10
Default: 1
- =winum-ignored-buffers=
List of buffers to ignore when selecting window.
List of buffers to ignore when selecting window.
Default: '(" *which-key*")
Default: ='(" *which-key*")=
- face: =winum-face=
Face used for the number in the mode-line.
Face used for the number in the mode-line.
** Configuration file example
Here is an example that you could put in your =.emacs=, which includes all
available winum options.
#+BEGIN_SRC emacs-lisp
(add-to-list 'load-path "/path/to/install/folder/winum.el/")
(require 'winum)
(defun my-winum-assign-func ()
(cond
((equal (buffer-name) "*Calculator*")
9)
((string-match-p (buffer-name) ".*\\*NeoTree\\*.*")
0)
(t
nil)))
(set-face-property 'winum-face :weight 'bold)
(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
winum-mode-line-position 1
winum-ignored-buffers '(" *which-key*")
winum-keymap (let ((map (make-sparse-keymap)))
(define-key map (kbd "C-`") 'select-window-by-number)
(define-key map (kbd "M-0") 'select-window-0-or-10)
(define-key map (kbd "M-1") 'select-window-1)
(define-key map (kbd "M-2") 'select-window-2)
(define-key map (kbd "M-3") 'select-window-3)
(define-key map (kbd "M-4") 'select-window-4)
(define-key map (kbd "M-5") 'select-window-5)
(define-key map (kbd "M-6") 'select-window-6)
(define-key map (kbd "M-7") 'select-window-7)
(define-key map (kbd "M-8") 'select-window-8)
(define-key map (kbd "M-9") 'select-window-9)
map))
(winum-mode)
#+END_SRC