Rewrite README using org-mode

This commit is contained in:
deb0ch 2016-11-30 03:11:05 +01:00
parent 80952103b5
commit 08b76f4d01
3 changed files with 187 additions and 59 deletions

View file

@ -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
View 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.

View file

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