emacs-winum/README.org

150 lines
3.8 KiB
Org Mode
Raw Normal View History

2016-11-29 21:11:05 -05:00
[[https://github.com/syl20bnr/spacemacs][file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]
#+TITLE: Window numbers for Emacs !
2016-12-03 07:40:40 -05:00
**** TODO better example for assign-func
**** TODO example with all options
2016-11-29 21:11:05 -05:00
* Contents :TOC:
2016-12-03 07:40:40 -05:00
- [[#better-example-for-assign-func][better example for assign-func]]
- [[#example-with-all-options][example with all options]]
2016-11-29 21:11:05 -05:00
- [[#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)
2016-11-29 21:11:05 -05:00
(winum-mode)
2016-11-29 21:11:05 -05:00
#+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:
2016-11-29 21:11:05 -05:00
#+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)
2016-11-29 21:11:05 -05:00
#+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=:
2016-11-29 21:11:05 -05:00
- =winum-scope=
2016-11-29 21:11:05 -05:00
Frames affected by a number set. Choices are 'frame-local 'visible or 'global.
Default: 'global
- =winum-reverse-frame-list=
2016-11-29 21:11:05 -05:00
If t, order frames by reverse order of creation. Has effect only when
`winum-scope' is not 'frame-local.
2016-11-29 21:11:05 -05:00
Default: nil
- =winum-auto-assign-0-to-minibuffer=
2016-11-29 21:11:05 -05:00
If non-nil, =winum-mode= assigns 0 to the minibuffer if active.
2016-11-29 21:11:05 -05:00
Default: t
- =winum-assign-func=
2016-11-29 21:11:05 -05:00
Function called for each window by =winum-mode=. This is called
2016-11-29 21:11:05 -05:00
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
2016-11-29 21:11:05 -05:00
(lambda () (when (equal (buffer-name) "*Calculator*") 9)))
#+END_SRC
2016-12-04 14:38:42 -05:00
- =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=
2016-11-29 21:11:05 -05:00
The position in the mode-line `winum-mode' displays the number.
2016-11-29 21:11:05 -05:00
Default: 1
- =winum-window-number-max= 10
2016-11-29 21:11:05 -05:00
Max number of windows that can be numbered.
Default: 10
- =winum-ignored-buffers=
2016-11-29 21:11:05 -05:00
List of buffers to ignore when selecting window.
Default: '(" *which-key*")
- face: =winum-face=
2016-11-29 21:11:05 -05:00
Face used for the number in the mode-line.