Rewrite README using org-mode
This commit is contained in:
parent
80952103b5
commit
08b76f4d01
16
README.md
16
README.md
|
@ -1,16 +0,0 @@
|
||||||
window-numbering
|
|
||||||
================
|
|
||||||
|
|
||||||
Numbered window shortcuts for Emacs
|
|
||||||
|
|
||||||
[![Build Status](https://travis-ci.org/nschum/window-numbering.el.png?branch=master)](https://travis-ci.org/nschum/window-numbering.el)
|
|
||||||
|
|
||||||
Enable `window-numbering-mode` and use M-1 through M-0 to navigate.
|
|
||||||
|
|
||||||
If you want to affect the numbers, use window-numbering-before-hook or
|
|
||||||
window-numbering-assign-func.
|
|
||||||
For instance, to always assign the calculator window the number 9, add the
|
|
||||||
following to your .emacs:
|
|
||||||
|
|
||||||
(setq window-numbering-assign-func
|
|
||||||
(lambda () (when (equal (buffer-name) "*Calculator*") 9)))
|
|
145
README.org
Normal file
145
README.org
Normal file
|
@ -0,0 +1,145 @@
|
||||||
|
[[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]]
|
||||||
|
- [[#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 'window-numbering)
|
||||||
|
|
||||||
|
(window-numbering-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
|
||||||
|
=window-numbering-keymap= before activating the mode:
|
||||||
|
|
||||||
|
#+BEGIN_SRC emacs-lisp
|
||||||
|
(require 'window-numbering)
|
||||||
|
|
||||||
|
(setq window-numbering-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))
|
||||||
|
(window-numbering-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= > =window-numbering=:
|
||||||
|
|
||||||
|
- =window-numbering-scope=
|
||||||
|
|
||||||
|
Frames affected by a number set. Choices are 'frame-local 'visible or 'global.
|
||||||
|
|
||||||
|
Default: 'global
|
||||||
|
|
||||||
|
- =window-numbering-reverse-frame-list=
|
||||||
|
|
||||||
|
If t, order frames by reverse order of creation. Has effect only when
|
||||||
|
`window-numbering-scope' is not 'frame-local.
|
||||||
|
|
||||||
|
Default: nil
|
||||||
|
|
||||||
|
- =window-numbering-auto-assign-0-to-minibuffer=
|
||||||
|
|
||||||
|
If non-nil, =window-numbering-mode= assigns 0 to the minibuffer if active.
|
||||||
|
|
||||||
|
Default: t
|
||||||
|
|
||||||
|
- =window-numbering-before-hook=
|
||||||
|
|
||||||
|
Hook called before =window-numbering-mode= starts assigning numbers. The list of
|
||||||
|
windows to be numbered is passed as a parameter. Use =window-numbering--assign=
|
||||||
|
to manually assign some of them a number. If you want to assign a number to just
|
||||||
|
one buffer, use =window-numbering-assign-func= instead.
|
||||||
|
|
||||||
|
Default: nil
|
||||||
|
|
||||||
|
- =window-numbering-assign-func=
|
||||||
|
|
||||||
|
Function called for each window by =window-numbering-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 window-numbering-assign-func
|
||||||
|
(lambda () (when (equal (buffer-name) "*Calculator*") 9)))
|
||||||
|
#+END_SRC
|
||||||
|
|
||||||
|
- =window-numbering-mode-line-position=
|
||||||
|
|
||||||
|
The position in the mode-line `window-numbering-mode' displays the number.
|
||||||
|
|
||||||
|
Default: 1
|
||||||
|
|
||||||
|
- =window-numbering-window-number-max= 10
|
||||||
|
|
||||||
|
Max number of windows that can be numbered.
|
||||||
|
|
||||||
|
Default: 10
|
||||||
|
|
||||||
|
- =window-numbering-ignored-buffers=
|
||||||
|
|
||||||
|
List of buffers to ignore when selecting window.
|
||||||
|
|
||||||
|
Default: '(" *which-key*")
|
||||||
|
|
||||||
|
- face: =window-numbering-face=
|
||||||
|
|
||||||
|
Face used for the number in the mode-line.
|
||||||
|
|
|
@ -47,7 +47,7 @@
|
||||||
;; force update or `window-numbering-get-number' fails and messes the
|
;; force update or `window-numbering-get-number' fails and messes the
|
||||||
;; modeline until next update.
|
;; modeline until next update.
|
||||||
(defcustom window-numbering-scope 'global
|
(defcustom window-numbering-scope 'global
|
||||||
"The scope of number sets."
|
"Frames affected by a number set."
|
||||||
:group 'window-numbering
|
:group 'window-numbering
|
||||||
:type '(choice
|
:type '(choice
|
||||||
(const :tag "frame local" frame-local)
|
(const :tag "frame local" frame-local)
|
||||||
|
@ -65,6 +65,7 @@ Has effect only when `window-numbering-scope' is not 'frame-local."
|
||||||
:group 'window-numbering
|
:group 'window-numbering
|
||||||
:type 'boolean)
|
:type 'boolean)
|
||||||
|
|
||||||
|
;; TODO see if useful
|
||||||
(defcustom window-numbering-before-hook nil
|
(defcustom window-numbering-before-hook nil
|
||||||
"Hook called before `window-numbering-mode' starts assigning numbers.
|
"Hook called before `window-numbering-mode' starts assigning numbers.
|
||||||
The list of windows to be numbered is passed as a parameter.
|
The list of windows to be numbered is passed as a parameter.
|
||||||
|
@ -86,7 +87,7 @@ return a number to have it assigned to the current-window, nil otherwise."
|
||||||
:group 'window-numbering
|
:group 'window-numbering
|
||||||
:type 'integer)
|
:type 'integer)
|
||||||
|
|
||||||
(defcustom window-numbering--window-number-max 10
|
(defcustom window-numbering-window-number-max 10
|
||||||
"Max number of windows that can be numbered."
|
"Max number of windows that can be numbered."
|
||||||
:group 'window-numbering
|
:group 'window-numbering
|
||||||
:type 'integer)
|
:type 'integer)
|
||||||
|
@ -125,7 +126,7 @@ return a number to have it assigned to the current-window, nil otherwise."
|
||||||
(window-numbering--deinit)))
|
(window-numbering--deinit)))
|
||||||
|
|
||||||
;; define interactive functions window-numbering-select-window-[0..n]
|
;; define interactive functions window-numbering-select-window-[0..n]
|
||||||
(dotimes (i window-numbering--window-number-max)
|
(dotimes (i (max 10 window-numbering-window-number-max))
|
||||||
(eval `(defun ,(intern (format "select-window-%s" i)) (&optional arg)
|
(eval `(defun ,(intern (format "select-window-%s" i)) (&optional arg)
|
||||||
,(format "Jump to window %d.\nIf prefix ARG is given, delete the\
|
,(format "Jump to window %d.\nIf prefix ARG is given, delete the\
|
||||||
window instead of selecting it." i)
|
window instead of selecting it." i)
|
||||||
|
@ -150,7 +151,7 @@ If prefix ARG is given, delete the window instead of selecting it."
|
||||||
window-numbering--frames-table))
|
window-numbering--frames-table))
|
||||||
window-numbering--window-vector))
|
window-numbering--window-vector))
|
||||||
window)
|
window)
|
||||||
(if (and (>= i 0) (< i window-numbering--window-number-max)
|
(if (and (>= i 0) (< i window-numbering-window-number-max)
|
||||||
(setq window (aref windows i)))
|
(setq window (aref windows i)))
|
||||||
window
|
window
|
||||||
(error "No window numbered %s" i))))
|
(error "No window numbered %s" i))))
|
||||||
|
@ -159,36 +160,6 @@ If prefix ARG is given, delete the window instead of selecting it."
|
||||||
;; - prefix argument
|
;; - prefix argument
|
||||||
;; - read-from-minibuffer
|
;; - read-from-minibuffer
|
||||||
|
|
||||||
;;;###autoload
|
|
||||||
(defun window-numbering-install-mode-line (&optional position)
|
|
||||||
"Install the window number from `window-numbering-mode' to the mode-line.
|
|
||||||
POSITION: position in the mode-line."
|
|
||||||
(let ((mode-line (default-value 'mode-line-format))
|
|
||||||
(res))
|
|
||||||
(dotimes (i (min (or position window-numbering-mode-line-position 1)
|
|
||||||
(length mode-line)))
|
|
||||||
(push (car mode-line) res)
|
|
||||||
(pop mode-line))
|
|
||||||
(push '(:eval (window-numbering-get-number-string)) res)
|
|
||||||
(while mode-line
|
|
||||||
(push (car mode-line) res)
|
|
||||||
(pop mode-line))
|
|
||||||
(setq-default mode-line-format (nreverse res)))
|
|
||||||
(force-mode-line-update t))
|
|
||||||
|
|
||||||
;;;###autoload
|
|
||||||
(defun window-numbering-clear-mode-line ()
|
|
||||||
"Remove the window number of `window-numbering-mode' from the mode-line."
|
|
||||||
(let ((mode-line (default-value 'mode-line-format))
|
|
||||||
(res))
|
|
||||||
(while mode-line
|
|
||||||
(let ((item (car mode-line)))
|
|
||||||
(unless (equal item '(:eval (window-numbering-get-number-string)))
|
|
||||||
(push item res)))
|
|
||||||
(pop mode-line))
|
|
||||||
(setq-default mode-line-format (nreverse res)))
|
|
||||||
(force-mode-line-update t))
|
|
||||||
|
|
||||||
;;;###autoload
|
;;;###autoload
|
||||||
(defun window-numbering-get-number-string (&optional window)
|
(defun window-numbering-get-number-string (&optional window)
|
||||||
"Get the current or specified window's current number as a propertized string.
|
"Get the current or specified window's current number as a propertized string.
|
||||||
|
@ -245,8 +216,8 @@ Such a structure allows for per-frame bidirectional fast access.")
|
||||||
"Initialize window-numbering-mode."
|
"Initialize window-numbering-mode."
|
||||||
(if (eq window-numbering-scope 'frame-local)
|
(if (eq window-numbering-scope 'frame-local)
|
||||||
(setq window-numbering--frames-table (make-hash-table :size window-numbering--max-frames))
|
(setq window-numbering--frames-table (make-hash-table :size window-numbering--max-frames))
|
||||||
(setq window-numbering--numbers-table (make-hash-table :size window-numbering--window-number-max)))
|
(setq window-numbering--numbers-table (make-hash-table :size window-numbering-window-number-max)))
|
||||||
(window-numbering-install-mode-line)
|
(window-numbering--install-mode-line)
|
||||||
(add-hook 'minibuffer-setup-hook 'window-numbering--update)
|
(add-hook 'minibuffer-setup-hook 'window-numbering--update)
|
||||||
(add-hook 'window-configuration-change-hook 'window-numbering--update)
|
(add-hook 'window-configuration-change-hook 'window-numbering--update)
|
||||||
(dolist (frame (frame-list))
|
(dolist (frame (frame-list))
|
||||||
|
@ -255,20 +226,48 @@ Such a structure allows for per-frame bidirectional fast access.")
|
||||||
|
|
||||||
(defun window-numbering--deinit ()
|
(defun window-numbering--deinit ()
|
||||||
"Actions performed when turning off window-numbering-mode."
|
"Actions performed when turning off window-numbering-mode."
|
||||||
(window-numbering-clear-mode-line)
|
(window-numbering--clear-mode-line)
|
||||||
(remove-hook 'minibuffer-setup-hook 'window-numbering--update)
|
(remove-hook 'minibuffer-setup-hook 'window-numbering--update)
|
||||||
(remove-hook 'window-configuration-change-hook 'window-numbering--update)
|
(remove-hook 'window-configuration-change-hook 'window-numbering--update)
|
||||||
(setq window-numbering--frames-table nil))
|
(setq window-numbering--frames-table nil))
|
||||||
|
|
||||||
|
(defun window-numbering--install-mode-line (&optional position)
|
||||||
|
"Install the window number from `window-numbering-mode' to the mode-line.
|
||||||
|
POSITION: position in the mode-line."
|
||||||
|
(let ((mode-line (default-value 'mode-line-format))
|
||||||
|
(res))
|
||||||
|
(dotimes (i (min (or position window-numbering-mode-line-position 1)
|
||||||
|
(length mode-line)))
|
||||||
|
(push (car mode-line) res)
|
||||||
|
(pop mode-line))
|
||||||
|
(push '(:eval (window-numbering-get-number-string)) res)
|
||||||
|
(while mode-line
|
||||||
|
(push (car mode-line) res)
|
||||||
|
(pop mode-line))
|
||||||
|
(setq-default mode-line-format (nreverse res)))
|
||||||
|
(force-mode-line-update t))
|
||||||
|
|
||||||
|
(defun window-numbering--clear-mode-line ()
|
||||||
|
"Remove the window number of `window-numbering-mode' from the mode-line."
|
||||||
|
(let ((mode-line (default-value 'mode-line-format))
|
||||||
|
(res))
|
||||||
|
(while mode-line
|
||||||
|
(let ((item (car mode-line)))
|
||||||
|
(unless (equal item '(:eval (window-numbering-get-number-string)))
|
||||||
|
(push item res)))
|
||||||
|
(pop mode-line))
|
||||||
|
(setq-default mode-line-format (nreverse res)))
|
||||||
|
(force-mode-line-update t))
|
||||||
|
|
||||||
(defun window-numbering--update ()
|
(defun window-numbering--update ()
|
||||||
"Update window numbers."
|
"Update window numbers."
|
||||||
(setq window-numbering--remaining (window-numbering--available-numbers))
|
(setq window-numbering--remaining (window-numbering--available-numbers))
|
||||||
(if (eq window-numbering-scope 'frame-local)
|
(if (eq window-numbering-scope 'frame-local)
|
||||||
(puthash (selected-frame)
|
(puthash (selected-frame)
|
||||||
(cons (make-vector window-numbering--window-number-max nil)
|
(cons (make-vector window-numbering-window-number-max nil)
|
||||||
(make-hash-table :size window-numbering--window-number-max))
|
(make-hash-table :size window-numbering-window-number-max))
|
||||||
window-numbering--frames-table)
|
window-numbering--frames-table)
|
||||||
(setq window-numbering--window-vector (make-vector window-numbering--window-number-max nil))
|
(setq window-numbering--window-vector (make-vector window-numbering-window-number-max nil))
|
||||||
(clrhash window-numbering--numbers-table))
|
(clrhash window-numbering--numbers-table))
|
||||||
(when (and window-numbering-auto-assign-0-to-minibuffer
|
(when (and window-numbering-auto-assign-0-to-minibuffer
|
||||||
(active-minibuffer-window))
|
(active-minibuffer-window))
|
||||||
|
@ -354,11 +353,11 @@ This hashtable is not stored the same way depending on the value of
|
||||||
window-numbering--numbers-table))
|
window-numbering--numbers-table))
|
||||||
|
|
||||||
(defun window-numbering--available-numbers ()
|
(defun window-numbering--available-numbers ()
|
||||||
"Return a list of numbers from 1 to `window-numbering--window-number-max'.
|
"Return a list of numbers from 1 to `window-numbering-window-number-max'.
|
||||||
0 is the last element of the list."
|
0 is the last element of the list."
|
||||||
(let ((numbers))
|
(let ((numbers))
|
||||||
(dotimes (i window-numbering--window-number-max)
|
(dotimes (i window-numbering-window-number-max)
|
||||||
(push (% (1+ i) window-numbering--window-number-max) numbers))
|
(push (% (1+ i) window-numbering-window-number-max) numbers))
|
||||||
(nreverse numbers)))
|
(nreverse numbers)))
|
||||||
|
|
||||||
(defun window-numbering--switch-to-window (window)
|
(defun window-numbering--switch-to-window (window)
|
||||||
|
|
Loading…
Reference in a new issue