emacs-winum/README.org

Window numbers for Emacs !

• Contents
• Introduction
• Installation
  • Using Melpa
  • Manual installation
• How to use
• Configuration
  • Keybindings
  • Customize options
  • Configuration file example
• Future developments

Contents   TOC

• Introduction

• Installation

  • Using Melpa
  • Manual installation
• How to use

• Configuration

  • Keybindings
  • Customize options
  • Configuration file example
• Future developments

Introduction

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

This package is an extended and actively maintained version of the window-numbering package by Nikolaj Schumacher, with some ideas and code taken from 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

Using Melpa

The recommended way of installing winum is from the Melpa package repository:

M-x package-install RET winum RET

You will find instructions to setup Melpa here if you don't have it setup yet.

Once the package is installed, you will need to activate winum-mode in your Emacs configuration:

  (require 'winum)

  (winum-mode)

Manual installation

• Clone the repo:

  cd /path/to/install/folder
  git clone https://github.com/deb0ch/winum.el

• Add the following to your Emacs configuration:

  (add-to-list 'load-path "/path/to/install/folder/winum.el/")

  (require 'winum)

  (winum-mode)

How to use

Key binding	Description
C-x w <n>	select window <n>, where <n> ranges from 0 to 9. A negative argument deletes the window.
C-x w `	select window by number. Number can be given as prefix arg or will be read from minibuffer.

• select-window-0-or-10 By default, C-x w 0 is bound to select-window-0-or-10. If window 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-x w `.

  This function allows several ways to input the window number:

  • Use a numbered prefix argument.
    Ex: C-1 C-2 C-x w ` to select window 12.
  • Use a negative prefix argument to delete the window.
    Ex: C-- C-1 C-2 C-x w ` to delete window 12.
  • Use the negative prefix argument to delete window 0.
    Ex: C-- C-x w ` to delete window 0.
  • Use the default prefix argument to delete current window.
    Ex: C-u C-x w ` 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.

Configuration

Keybindings

The default prefix for key bindings is C-x w for compatibility with native Emacs bindings.

If you don't like C-x w, you can set a prefix of your choosing using the function winum-set-keymap-prefix:

  (winum-set-keymap-prefix (kbd "C-c"))

This function overrides the value of winum-keymap, so you should call it before customization of winum-keymap and/or after customization of winum-base-map. Its argument must be a key sequence, like the ones returned by kbd.

If you prefer no to use a prefix and have even shorter bindings, you can also override winum-keymap in the minor mode bindings table:

  (require 'winum)

  (setcdr (assoc 'winum-mode minor-mode-map-alist)
      (let ((map (make-sparse-keymap)))
        (define-key map (kbd "C-`") 'winum-select-window-by-number)
        (define-key map (kbd "C-²") 'winum-select-window-by-number)
        (define-key map (kbd "M-0") 'winum-select-window-0-or-10)
        (define-key map (kbd "M-1") 'winum-select-window-1)
        (define-key map (kbd "M-2") 'winum-select-window-2)
        (define-key map (kbd "M-3") 'winum-select-window-3)
        (define-key map (kbd "M-4") 'winum-select-window-4)
        (define-key map (kbd "M-5") 'winum-select-window-5)
        (define-key map (kbd "M-6") 'winum-select-window-6)
        (define-key map (kbd "M-7") 'winum-select-window-7)
        (define-key map (kbd "M-8") 'winum-select-window-8)
        map))

  (winum-mode)

You can also use the more conventional define-key on winum-keymap:

  (define-key winum-keymap (kbd "C-x y o l o") 'winum-select-window-by-number)

NB: Both ` and ² are mapped to winum-select-window-by-number by default to handle both qwerty and azerty keyboard layouts. If you are using a different kind of layout, the recommended place to map it is the key beside 1.

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. This function along with `winum-auto-assign-0-to-minibuffer' are the only ways to have 0 assigned to a window. Example: always assign Calculator the number 9 and NeoTree the number 0:

  (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)

Default: nil

• 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 assigning numbers. 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.

  (require 'winum)

  (setcdr (assoc 'winum-mode minor-mode-map-alist)
      (let ((map (make-sparse-keymap)))
        (define-key map (kbd "C-`") 'winum-select-window-by-number)
        (define-key map (kbd "C-²") 'winum-select-window-by-number)
        (define-key map (kbd "M-0") 'winum-select-window-0-or-10)
        (define-key map (kbd "M-1") 'winum-select-window-1)
        (define-key map (kbd "M-2") 'winum-select-window-2)
        (define-key map (kbd "M-3") 'winum-select-window-3)
        (define-key map (kbd "M-4") 'winum-select-window-4)
        (define-key map (kbd "M-5") 'winum-select-window-5)
        (define-key map (kbd "M-6") 'winum-select-window-6)
        (define-key map (kbd "M-7") 'winum-select-window-7)
        (define-key map (kbd "M-8") 'winum-select-window-8)
        map))

  (defun my-winum-assign-func ()
    (cond
     ((equal (buffer-name) "*Calculator*")
      9)
     ((string-match-p (buffer-name) ".*\\*NeoTree\\*.*")
      0)
     (t
      nil)))

  (set-face-attribute 'winum-face nil :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-mode)

Future developments

• send buffer to numbered window Send current window's buffer to window N. With prefix argument focus will follow. Also provide a `winum-send-buffer-to-window-by-number` function (and find shorter names).
• swap buffer with numbered window Same as previous, but will swap buffers instead of just sending them. Also provide a `winum-swap-buffre-with-window-by-number` function (and find better names).
• Evilify Adapt the package to the famous `evil-mode` and use a leader key.
• Override native other-window (C-x o) to use window numbers
• Autocomplete read-from-minibuffer
• Feel free to submit any issue or a pull request, including the above mentionned points :)