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 ! #+TITLE: Window numbers for Emacs !
**** TODO better example for assign-func
**** TODO example with all options
* Contents :TOC: * Contents :TOC:
- [[#better-example-for-assign-func][better example for assign-func]]
- [[#example-with-all-options][example with all options]]
- [[#introduction][Introduction]] - [[#introduction][Introduction]]
- [[#installation][Installation]] - [[#installation][Installation]]
- [[#how-to-use][How to use]] - [[#how-to-use][How to use]]
- [[#navigate-windows][Navigate windows]]
- [[#delete-windows][Delete windows]]
- [[#configuration][Configuration]] - [[#configuration][Configuration]]
- [[#custom-keymap][Custom keymap]] - [[#custom-keymap][Custom keymap]]
- [[#customize-options][Customize options]] - [[#customize-options][Customize options]]
- [[#configuration-file-example][Configuration file example]]
* Introduction * Introduction
Window numbers for Emacs: Navigate your windows and frames using numbers ! 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. frames, giving the user a smoother experience of multi-screen Emacs.
* Installation * Installation
- Clone the repo: - Clone the repo:
#+BEGIN_SRC shell #+BEGIN_SRC shell
@ -46,19 +39,38 @@ frames, giving the user a smoother experience of multi-screen Emacs.
(winum-mode) (winum-mode)
#+END_SRC #+END_SRC
* How to use * How to use
** Navigate windows - =select-window-[0..9]=
Use ~M-1~ to ~M-9~ to navigate windows numbered 1 to 9. Use ~M-1~ to ~M-9~ to navigate windows numbered 1 to 9.
The functions for selecting windows are the =select-window-[1..N]= functions, By default, ~M-0~ is bound to =select-window-0-or-10=, which behaves like
where N is the maximum window number. the other ones except that if 0 is not assigned it will act on the window 10
instead.
See [[#configuration][configuration]] to rebind them any way you prefer. You can rebind this to the more straightforward =select-window-0= if you
prefer.
** Delete windows - =select-window-by-number=
Use ~M-1~ to ~M-9~ with an Emacs prefix argument to delete a window instead of
selecting it. 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 * Configuration
** Custom keymap ** Custom keymap
@ -80,70 +92,117 @@ This way your bindings will not error when the mode is turned off.
** Customize options ** Customize options
Several options are available through Emacs' =Customize= interface under Several options are available through Emacs' Customize interface under
=convenience= > =winum=: =convenience= > =winum=:
- =winum-scope= - =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= - =winum-reverse-frame-list=
If t, order frames by reverse order of creation. Has effect only when If t, order frames by reverse order of creation. Has effect only when
`winum-scope' is not 'frame-local. =winum-scope= is not ='frame-local=.
Default: nil Default: =nil=
- =winum-auto-assign-0-to-minibuffer= - =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= - =winum-assign-func=
Function called for each window by =winum-mode=. This is called Function called for each window by =winum-mode=. This is called before
before automatic assignment begins. The function should return a number to have automatic assignment begins. The function should return a number to have it
it assigned to the current-window, nil otherwise. 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 #+BEGIN_SRC emacs-lisp
(setq winum-assign-func (defun my-winum-assign-func ()
(lambda () (when (equal (buffer-name) "*Calculator*") 9))) (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 #+END_SRC
- =winum-auto-setup-mode-line= - =winum-auto-setup-mode-line=
When nil, `winum-mode' will not display window numbers in the mode-line. When nil, =winum-mode= will not display window numbers in the mode-line. You
You might want this to be nil if you use a package that already manages window might want this to be nil if you use a package that already manages window
numbers in the mode-line. numbers in the mode-line.
Default: t Default: =t=
- =winum-mode-line-position= - =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 Default: 1
- =winum-window-number-max= 10
Max number of windows that can be numbered.
Default: 10
- =winum-ignored-buffers= - =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: =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