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 !

**** 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]]

* 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
** Navigate windows
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,
where N is the maximum window number.

See [[#configuration][configuration]] to rebind them any way you prefer.

** Delete windows
Use ~M-1~ to ~M-9~ with an Emacs prefix argument to delete a window instead of
selecting it.

* Configuration
** Custom keymap
   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 the calculator window the number 9:

#+BEGIN_SRC emacs-lisp
    (setq winum-assign-func
	  (lambda () (when (equal (buffer-name) "*Calculator*") 9)))
#+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-window-number-max= 10

Max number of windows that can be numbered.

Default: 10

- =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.