emacs-winum/README.org

[[https://github.com/syl20bnr/spacemacs][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]

#+TITLE: Window numbers for Emacs !

* Contents :TOC:
 - [[#introduction][Introduction]]
 - [[#installation][Installation]]
 - [[#how-to-use][How to use]]
 - [[#configuration][Configuration]]
   - [[#keybindings][Keybindings]]
   - [[#customize-options][Customize options]]
   - [[#configuration-file-example][Configuration file example]]

* Introduction
Window numbers for Emacs: Navigate your windows and frames using numbers !

This package is an extended and actively maintained version of the
https://github.com/nschum/window-numbering.el package by Nikolaj Schumacher,
with some ideas and code taken from https://github.com/abo-abo/ace-window.

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
  cd /path/to/install/folder
  git clone https://github.com/deb0ch/winum.el
#+END_SRC

- Add the following to your Emacs configuration:

#+BEGIN_SRC emacs-lisp
  (add-to-list 'load-path "/path/to/install/folder/winum.el/")

  (require 'winum)

  (winum-mode)
#+END_SRC

* How to use
- =select-window-[0..9]=

  Use ~M-1~ to ~M-9~ to navigate windows numbered 1 to 9.

  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.

  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
** Keybindings
To define your own bindings and override the default ones, override
=winum-keymap= before activating the mode:

#+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)
#+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
=convenience= > =winum=:

- =winum-scope=

  Frames affected by a number set. Choices are ='frame-local= ='visible= or
 ='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=.

  Default: =nil=

- =winum-auto-assign-0-to-minibuffer=

  If non-nil, =winum-mode= assigns 0 to the minibuffer if active.

  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.

  Default: =nil=

  Example: always assign *Calculator* the number 9 and *NeoTree* the number 0:

#+BEGIN_SRC emacs-lisp
  (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.

  Default: =t=

- =winum-mode-line-position=

  The position in the mode-line =winum-mode= displays the number.

  Default: 1

- =winum-ignored-buffers=

  List of buffers to ignore when selecting window.

  Default: '(" *which-key*")

- face: =winum-face=

  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