From e947f05c9373346b93bd99557eae350e0de71c18 Mon Sep 17 00:00:00 2001 From: deb0ch Date: Mon, 5 Dec 2016 14:59:28 +0100 Subject: [PATCH] improve README.org --- README.org | 173 +++++++++++++++++++++++++++++++++++------------------ 1 file changed, 116 insertions(+), 57 deletions(-) diff --git a/README.org b/README.org index 732f0e9..39798ac 100644 --- a/README.org +++ b/README.org @@ -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