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
|
||||
;; modeline until next update.
|
||||
(defcustom window-numbering-scope 'global
|
||||
"The scope of number sets."
|
||||
"Frames affected by a number set."
|
||||
:group 'window-numbering
|
||||
:type '(choice
|
||||
(const :tag "frame local" frame-local)
|
||||
|
@ -65,6 +65,7 @@ Has effect only when `window-numbering-scope' is not 'frame-local."
|
|||
:group 'window-numbering
|
||||
:type 'boolean)
|
||||
|
||||
;; TODO see if useful
|
||||
(defcustom window-numbering-before-hook nil
|
||||
"Hook called before `window-numbering-mode' starts assigning numbers.
|
||||
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
|
||||
:type 'integer)
|
||||
|
||||
(defcustom window-numbering--window-number-max 10
|
||||
(defcustom window-numbering-window-number-max 10
|
||||
"Max number of windows that can be numbered."
|
||||
:group 'window-numbering
|
||||
:type 'integer)
|
||||
|
@ -125,7 +126,7 @@ return a number to have it assigned to the current-window, nil otherwise."
|
|||
(window-numbering--deinit)))
|
||||
|
||||
;; 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)
|
||||
,(format "Jump to window %d.\nIf prefix ARG is given, delete the\
|
||||
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--window-vector))
|
||||
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)))
|
||||
window
|
||||
(error "No window numbered %s" i))))
|
||||
|
@ -159,36 +160,6 @@ If prefix ARG is given, delete the window instead of selecting it."
|
|||
;; - prefix argument
|
||||
;; - 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
|
||||
(defun window-numbering-get-number-string (&optional window)
|
||||
"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."
|
||||
(if (eq window-numbering-scope 'frame-local)
|
||||
(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)))
|
||||
(window-numbering-install-mode-line)
|
||||
(setq window-numbering--numbers-table (make-hash-table :size window-numbering-window-number-max)))
|
||||
(window-numbering--install-mode-line)
|
||||
(add-hook 'minibuffer-setup-hook 'window-numbering--update)
|
||||
(add-hook 'window-configuration-change-hook 'window-numbering--update)
|
||||
(dolist (frame (frame-list))
|
||||
|
@ -255,20 +226,48 @@ Such a structure allows for per-frame bidirectional fast access.")
|
|||
|
||||
(defun window-numbering--deinit ()
|
||||
"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 'window-configuration-change-hook 'window-numbering--update)
|
||||
(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 ()
|
||||
"Update window numbers."
|
||||
(setq window-numbering--remaining (window-numbering--available-numbers))
|
||||
(if (eq window-numbering-scope 'frame-local)
|
||||
(puthash (selected-frame)
|
||||
(cons (make-vector window-numbering--window-number-max nil)
|
||||
(make-hash-table :size window-numbering--window-number-max))
|
||||
(cons (make-vector window-numbering-window-number-max nil)
|
||||
(make-hash-table :size window-numbering-window-number-max))
|
||||
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))
|
||||
(when (and window-numbering-auto-assign-0-to-minibuffer
|
||||
(active-minibuffer-window))
|
||||
|
@ -354,11 +353,11 @@ This hashtable is not stored the same way depending on the value of
|
|||
window-numbering--numbers-table))
|
||||
|
||||
(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."
|
||||
(let ((numbers))
|
||||
(dotimes (i window-numbering--window-number-max)
|
||||
(push (% (1+ i) window-numbering--window-number-max) numbers))
|
||||
(dotimes (i window-numbering-window-number-max)
|
||||
(push (% (1+ i) window-numbering-window-number-max) numbers))
|
||||
(nreverse numbers)))
|
||||
|
||||
(defun window-numbering--switch-to-window (window)
|
||||
|
|
Loading…
Reference in a new issue