From 08b76f4d01a643314e32af3426e32d8c8ba04547 Mon Sep 17 00:00:00 2001 From: deb0ch Date: Wed, 30 Nov 2016 03:11:05 +0100 Subject: [PATCH] Rewrite README using org-mode --- README.md | 16 ----- README.org | 145 ++++++++++++++++++++++++++++++++++++++++++++ window-numbering.el | 85 +++++++++++++------------- 3 files changed, 187 insertions(+), 59 deletions(-) delete mode 100644 README.md create mode 100644 README.org diff --git a/README.md b/README.md deleted file mode 100644 index f0aa4b9..0000000 --- a/README.md +++ /dev/null @@ -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))) diff --git a/README.org b/README.org new file mode 100644 index 0000000..1928613 --- /dev/null +++ b/README.org @@ -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. + diff --git a/window-numbering.el b/window-numbering.el index 8c645eb..48cb992 100644 --- a/window-numbering.el +++ b/window-numbering.el @@ -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)