1 ;;; ruler-mode.el --- display a ruler in the header line
3 ;; Copyright (C) 2001-2011 Free Software Foundation, Inc.
5 ;; Author: David Ponce <david@dponce.com>
6 ;; Maintainer: David Ponce <david@dponce.com>
7 ;; Created: 24 Mar 2001
9 ;; Keywords: convenience
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
28 ;; This library provides a minor mode to display a ruler in the header
29 ;; line. It works from Emacs 21 onwards.
31 ;; You can use the mouse to change the `fill-column' `comment-column',
32 ;; `goal-column', `window-margins' and `tab-stop-list' settings:
34 ;; [header-line (shift down-mouse-1)] set left margin end to the ruler
35 ;; graduation where the mouse pointer is on.
37 ;; [header-line (shift down-mouse-3)] set right margin beginning to
38 ;; the ruler graduation where the mouse pointer is on.
40 ;; [header-line down-mouse-2] Drag the `fill-column', `comment-column'
41 ;; or `goal-column' to a ruler graduation.
43 ;; [header-line (control down-mouse-1)] add a tab stop to the ruler
44 ;; graduation where the mouse pointer is on.
46 ;; [header-line (control down-mouse-3)] remove the tab stop at the
47 ;; ruler graduation where the mouse pointer is on.
49 ;; [header-line (control down-mouse-2)] or M-x
50 ;; `ruler-mode-toggle-show-tab-stops' toggle showing and visually
51 ;; editing `tab-stop-list' setting. The `ruler-mode-show-tab-stops'
52 ;; option controls if the ruler shows tab stops by default.
54 ;; In the ruler the character `ruler-mode-current-column-char' shows
55 ;; the `current-column' location, `ruler-mode-fill-column-char' shows
56 ;; the `fill-column' location, `ruler-mode-comment-column-char' shows
57 ;; the `comment-column' location, `ruler-mode-goal-column-char' shows
58 ;; the `goal-column' and `ruler-mode-tab-stop-char' shows tab stop
59 ;; locations. Graduations in `window-margins' and `window-fringes'
60 ;; areas are shown with a different foreground color.
62 ;; It is also possible to customize the following characters:
64 ;; - `ruler-mode-basic-graduation-char' character used for basic
65 ;; graduations ('.' by default).
66 ;; - `ruler-mode-inter-graduation-char' character used for
67 ;; intermediate graduations ('!' by default).
69 ;; The following faces are customizable:
71 ;; - `ruler-mode-default' the ruler default face.
72 ;; - `ruler-mode-fill-column' the face used to highlight the
73 ;; `fill-column' character.
74 ;; - `ruler-mode-comment-column' the face used to highlight the
75 ;; `comment-column' character.
76 ;; - `ruler-mode-goal-column' the face used to highlight the
77 ;; `goal-column' character.
78 ;; - `ruler-mode-current-column' the face used to highlight the
79 ;; `current-column' character.
80 ;; - `ruler-mode-tab-stop' the face used to highlight tab stop
82 ;; - `ruler-mode-margins' the face used to highlight graduations
83 ;; in the `window-margins' areas.
84 ;; - `ruler-mode-fringes' the face used to highlight graduations
85 ;; in the `window-fringes' areas.
86 ;; - `ruler-mode-column-number' the face used to highlight the
87 ;; numbered graduations.
89 ;; `ruler-mode-default' inherits from the built-in `default' face.
90 ;; All `ruler-mode' faces inherit from `ruler-mode-default'.
92 ;; WARNING: To keep ruler graduations aligned on text columns it is
93 ;; important to use the same font family and size for ruler and text
96 ;; You can override the ruler format by defining an appropriate
97 ;; function as the buffer-local value of `ruler-mode-ruler-function'.
101 ;; To automatically display the ruler in specific major modes use:
103 ;; (add-hook '<major-mode>-hook 'ruler-mode)
112 (require 'scroll-bar)
115 (defgroup ruler-mode nil
116 "Display a ruler in the header line."
120 (defcustom ruler-mode-show-tab-stops nil
121 "If non-nil the ruler shows tab stop positions.
122 Also allowing to visually change `tab-stop-list' setting using
123 <C-down-mouse-1> and <C-down-mouse-3> on the ruler to respectively add
124 or remove a tab stop. \\[ruler-mode-toggle-show-tab-stops] or
125 <C-down-mouse-2> on the ruler toggles showing/editing of tab stops."
129 ;; IMPORTANT: This function must be defined before the following
130 ;; defcustoms because it is used in their :validate clause.
131 (defun ruler-mode-character-validate (widget)
132 "Ensure WIDGET value is a valid character value."
134 (let ((value (widget-value widget)))
135 (unless (characterp value)
136 (widget-put widget :error
137 (format "Invalid character value: %S" value))
140 (defcustom ruler-mode-fill-column-char (if (char-displayable-p ?¶)
143 "Character used at the `fill-column' location."
146 (character :tag "Character")
147 (integer :tag "Integer char value"
148 :validate ruler-mode-character-validate)))
150 (defcustom ruler-mode-comment-column-char ?\#
151 "Character used at the `comment-column' location."
154 (character :tag "Character")
155 (integer :tag "Integer char value"
156 :validate ruler-mode-character-validate)))
158 (defcustom ruler-mode-goal-column-char ?G
159 "Character used at the `goal-column' location."
162 (character :tag "Character")
163 (integer :tag "Integer char value"
164 :validate ruler-mode-character-validate)))
166 (defcustom ruler-mode-current-column-char (if (char-displayable-p ?¦)
169 "Character used at the `current-column' location."
172 (character :tag "Character")
173 (integer :tag "Integer char value"
174 :validate ruler-mode-character-validate)))
176 (defcustom ruler-mode-tab-stop-char ?\T
177 "Character used at `tab-stop-list' locations."
180 (character :tag "Character")
181 (integer :tag "Integer char value"
182 :validate ruler-mode-character-validate)))
184 (defcustom ruler-mode-basic-graduation-char ?\.
185 "Character used for basic graduations."
188 (character :tag "Character")
189 (integer :tag "Integer char value"
190 :validate ruler-mode-character-validate)))
192 (defcustom ruler-mode-inter-graduation-char ?\!
193 "Character used for intermediate graduations."
196 (character :tag "Character")
197 (integer :tag "Integer char value"
198 :validate ruler-mode-character-validate)))
200 (defcustom ruler-mode-set-goal-column-ding-flag t
201 "Non-nil means do `ding' when `goal-column' is set."
205 (defface ruler-mode-default
215 :box (:color "grey76"
217 :style released-button)
219 "Default face used by the ruler."
222 (defface ruler-mode-pad
224 (:inherit ruler-mode-default
228 (:inherit ruler-mode-default
231 "Face used to pad inactive ruler areas."
234 (defface ruler-mode-margins
236 (:inherit ruler-mode-default
239 "Face used to highlight margin areas."
242 (defface ruler-mode-fringes
244 (:inherit ruler-mode-default
247 "Face used to highlight fringes areas."
250 (defface ruler-mode-column-number
252 (:inherit ruler-mode-default
255 "Face used to highlight number graduations."
258 (defface ruler-mode-fill-column
260 (:inherit ruler-mode-default
263 "Face used to highlight the fill column character."
266 (defface ruler-mode-comment-column
268 (:inherit ruler-mode-default
271 "Face used to highlight the comment column character."
274 (defface ruler-mode-goal-column
276 (:inherit ruler-mode-default
279 "Face used to highlight the goal column character."
282 (defface ruler-mode-tab-stop
284 (:inherit ruler-mode-default
285 :foreground "steelblue"
287 "Face used to highlight tab stop characters."
290 (defface ruler-mode-current-column
292 (:inherit ruler-mode-default
296 "Face used to highlight the `current-column' character."
300 (defsubst ruler-mode-full-window-width ()
301 "Return the full width of the selected window."
302 (let ((edges (window-edges)))
303 (- (nth 2 edges) (nth 0 edges))))
305 (defsubst ruler-mode-window-col (n)
306 "Return a column number relative to the selected window.
307 N is a column number relative to selected frame."
310 (or (car (window-margins)) 0)
311 (fringe-columns 'left)
312 (scroll-bar-columns 'left)))
314 (defun ruler-mode-mouse-set-left-margin (start-event)
315 "Set left margin end to the graduation where the mouse pointer is on.
316 START-EVENT is the mouse click event."
318 (let* ((start (event-start start-event))
319 (end (event-end start-event))
321 (when (eq start end) ;; mouse click
322 (save-selected-window
323 (select-window (posn-window start))
324 (setq col (- (car (posn-col-row start)) (car (window-edges))
325 (scroll-bar-columns 'left))
326 w (- (ruler-mode-full-window-width)
327 (scroll-bar-columns 'left)
328 (scroll-bar-columns 'right)))
329 (when (and (>= col 0) (< col w))
330 (setq lm (window-margins)
333 (message "Left margin set to %d (was %d)" col lm)
334 (set-window-margins nil col rm))))))
336 (defun ruler-mode-mouse-set-right-margin (start-event)
337 "Set right margin beginning to the graduation where the mouse pointer is on.
338 START-EVENT is the mouse click event."
340 (let* ((start (event-start start-event))
341 (end (event-end start-event))
343 (when (eq start end) ;; mouse click
344 (save-selected-window
345 (select-window (posn-window start))
346 (setq col (- (car (posn-col-row start)) (car (window-edges))
347 (scroll-bar-columns 'left))
348 w (- (ruler-mode-full-window-width)
349 (scroll-bar-columns 'left)
350 (scroll-bar-columns 'right)))
351 (when (and (>= col 0) (< col w))
352 (setq lm (window-margins)
356 (message "Right margin set to %d (was %d)" col rm)
357 (set-window-margins nil lm col))))))
359 (defvar ruler-mode-dragged-symbol nil
360 "Column symbol dragged in the ruler.
361 That is `fill-column', `comment-column', `goal-column', or nil when
362 nothing is dragged.")
364 (defun ruler-mode-mouse-grab-any-column (start-event)
365 "Drag a column symbol on the ruler.
366 Start dragging on mouse down event START-EVENT, and update the column
367 symbol value with the current value of the ruler graduation while
368 dragging. See also the variable `ruler-mode-dragged-symbol'."
370 (setq ruler-mode-dragged-symbol nil)
371 (let* ((start (event-start start-event))
373 (save-selected-window
374 (select-window (posn-window start))
375 (setq col (ruler-mode-window-col (car (posn-col-row start)))
376 newc (+ col (window-hscroll)))
378 (>= col 0) (< col (window-width))
381 ;; Handle the fill column.
382 ((eq newc fill-column)
383 (setq oldc fill-column
384 ruler-mode-dragged-symbol 'fill-column)
387 ;; Handle the comment column.
388 ((eq newc comment-column)
389 (setq oldc comment-column
390 ruler-mode-dragged-symbol 'comment-column)
393 ;; Handle the goal column.
394 ;; A. On mouse down on the goal column character on the ruler,
395 ;; update the `goal-column' value while dragging.
396 ;; B. If `goal-column' is nil, set the goal column where the
398 ;; C. On mouse click on the goal column character on the
399 ;; ruler, unset the goal column.
400 ((eq newc goal-column) ; A. Drag the goal column.
401 (setq oldc goal-column
402 ruler-mode-dragged-symbol 'goal-column)
405 ((null goal-column) ; B. Set the goal column.
406 (setq oldc goal-column
408 ;; mouse-2 coming AFTER drag-mouse-2 invokes `ding'. This
409 ;; `ding' flushes the next messages about setting goal
410 ;; column. So here I force fetch the event(mouse-2) and
413 ;; Ding BEFORE `message' is OK.
414 (when ruler-mode-set-goal-column-ding-flag
416 (message "Goal column set to %d (click on %s again to unset it)"
418 (propertize (char-to-string ruler-mode-goal-column-char)
419 'face 'ruler-mode-goal-column))
420 nil) ;; Don't start dragging.
422 (if (eq 'click (ruler-mode-mouse-drag-any-column-iteration
423 (posn-window start)))
424 (when (eq 'goal-column ruler-mode-dragged-symbol)
425 ;; C. Unset the goal column.
427 ;; At end of dragging, report the updated column symbol.
428 (message "%s is set to %d (was %d)"
429 ruler-mode-dragged-symbol
430 (symbol-value ruler-mode-dragged-symbol)
433 (defun ruler-mode-mouse-drag-any-column-iteration (window)
434 "Update the ruler while dragging the mouse.
435 WINDOW is the window where occurred the last down-mouse event.
436 Return the symbol `drag' if the mouse has been dragged, or `click' if
437 the mouse has been clicked."
441 (while (mouse-movement-p (setq event (read-event)))
442 (setq drags (1+ drags))
443 (when (eq window (posn-window (event-end event)))
444 (ruler-mode-mouse-drag-any-column event)
445 (force-mode-line-update))))
446 (if (and (zerop drags) (eq 'click (car (event-modifiers event))))
450 (defun ruler-mode-mouse-drag-any-column (start-event)
451 "Update the value of the symbol dragged on the ruler.
452 Called on each mouse motion event START-EVENT."
453 (let* ((start (event-start start-event))
454 (end (event-end start-event))
456 (save-selected-window
457 (select-window (posn-window start))
458 (setq col (ruler-mode-window-col (car (posn-col-row end)))
459 newc (+ col (window-hscroll)))
460 (when (and (>= col 0) (< col (window-width)))
461 (set ruler-mode-dragged-symbol newc)))))
463 (defun ruler-mode-mouse-add-tab-stop (start-event)
464 "Add a tab stop to the graduation where the mouse pointer is on.
465 START-EVENT is the mouse click event."
467 (when ruler-mode-show-tab-stops
468 (let* ((start (event-start start-event))
469 (end (event-end start-event))
471 (when (eq start end) ;; mouse click
472 (save-selected-window
473 (select-window (posn-window start))
474 (setq col (ruler-mode-window-col (car (posn-col-row start)))
475 ts (+ col (window-hscroll)))
476 (and (>= col 0) (< col (window-width))
477 (not (member ts tab-stop-list))
479 (message "Tab stop set to %d" ts)
480 (setq tab-stop-list (sort (cons ts tab-stop-list)
483 (defun ruler-mode-mouse-del-tab-stop (start-event)
484 "Delete tab stop at the graduation where the mouse pointer is on.
485 START-EVENT is the mouse click event."
487 (when ruler-mode-show-tab-stops
488 (let* ((start (event-start start-event))
489 (end (event-end start-event))
491 (when (eq start end) ;; mouse click
492 (save-selected-window
493 (select-window (posn-window start))
494 (setq col (ruler-mode-window-col (car (posn-col-row start)))
495 ts (+ col (window-hscroll)))
496 (and (>= col 0) (< col (window-width))
497 (member ts tab-stop-list)
499 (message "Tab stop at %d deleted" ts)
500 (setq tab-stop-list (delete ts tab-stop-list)))))))))
502 (defun ruler-mode-toggle-show-tab-stops ()
503 "Toggle showing of tab stops on the ruler."
505 (setq ruler-mode-show-tab-stops (not ruler-mode-show-tab-stops))
506 (force-mode-line-update))
508 (defvar ruler-mode-map
509 (let ((km (make-sparse-keymap)))
510 (define-key km [header-line down-mouse-1]
512 (define-key km [header-line down-mouse-3]
514 (define-key km [header-line down-mouse-2]
515 #'ruler-mode-mouse-grab-any-column)
516 (define-key km [header-line (shift down-mouse-1)]
517 #'ruler-mode-mouse-set-left-margin)
518 (define-key km [header-line (shift down-mouse-3)]
519 #'ruler-mode-mouse-set-right-margin)
520 (define-key km [header-line (control down-mouse-1)]
521 #'ruler-mode-mouse-add-tab-stop)
522 (define-key km [header-line (control down-mouse-3)]
523 #'ruler-mode-mouse-del-tab-stop)
524 (define-key km [header-line (control down-mouse-2)]
525 #'ruler-mode-toggle-show-tab-stops)
526 (define-key km [header-line (shift mouse-1)]
528 (define-key km [header-line (shift mouse-3)]
530 (define-key km [header-line (control mouse-1)]
532 (define-key km [header-line (control mouse-3)]
534 (define-key km [header-line (control mouse-2)]
537 "Keymap for ruler minor mode.")
539 (defvar ruler-mode-header-line-format-old nil
540 "Hold previous value of `header-line-format'.")
542 (defvar ruler-mode-ruler-function 'ruler-mode-ruler
543 "Function to call to return ruler header line format.
544 This variable is expected to be made buffer-local by modes.")
546 (defconst ruler-mode-header-line-format
547 '(:eval (funcall ruler-mode-ruler-function))
548 "`header-line-format' used in ruler mode.
549 Call `ruler-mode-ruler-function' to compute the ruler value.")
552 (defvar ruler-mode nil
553 "Non-nil if Ruler mode is enabled.
554 Use the command `ruler-mode' to change this variable.")
555 (make-variable-buffer-local 'ruler-mode)
557 (defun ruler--save-header-line-format ()
558 "Install the header line format for Ruler mode.
559 Unless Ruler mode is already enabled, save the old header line
561 (when (and (not ruler-mode)
562 (local-variable-p 'header-line-format)
563 (not (local-variable-p 'ruler-mode-header-line-format-old)))
564 (set (make-local-variable 'ruler-mode-header-line-format-old)
566 (setq header-line-format ruler-mode-header-line-format))
569 (define-minor-mode ruler-mode
571 In Ruler mode, Emacs displays a ruler in the header line."
575 :variable (ruler-mode
578 (ruler--save-header-line-format))
579 (setq ruler-mode enable)))
581 (add-hook 'post-command-hook 'force-mode-line-update nil t)
582 ;; When `ruler-mode' is off restore previous header line format if
583 ;; the current one is the ruler header line format.
584 (when (eq header-line-format ruler-mode-header-line-format)
585 (kill-local-variable 'header-line-format)
586 (when (local-variable-p 'ruler-mode-header-line-format-old)
587 (setq header-line-format ruler-mode-header-line-format-old)
588 (kill-local-variable 'ruler-mode-header-line-format-old)))
589 (remove-hook 'post-command-hook 'force-mode-line-update t)))
591 ;; Add ruler-mode to the minor mode menu in the mode line
592 (define-key mode-line-mode-menu [ruler-mode]
593 `(menu-item "Ruler" ruler-mode
594 :button (:toggle . ruler-mode)))
596 (defconst ruler-mode-ruler-help-echo
598 S-mouse-1/3: set L/R margin, \
599 mouse-2: set goal column, \
600 C-mouse-2: show tabs"
601 "Help string shown when mouse is over the ruler.
602 `ruler-mode-show-tab-stops' is nil.")
604 (defconst ruler-mode-ruler-help-echo-when-goal-column
606 S-mouse-1/3: set L/R margin, \
607 C-mouse-2: show tabs"
608 "Help string shown when mouse is over the ruler.
609 `goal-column' is set and `ruler-mode-show-tab-stops' is nil.")
611 (defconst ruler-mode-ruler-help-echo-when-tab-stops
613 C-mouse1/3: set/unset tab, \
614 C-mouse-2: hide tabs"
615 "Help string shown when mouse is over the ruler.
616 `ruler-mode-show-tab-stops' is non-nil.")
618 (defconst ruler-mode-fill-column-help-echo
619 "drag-mouse-2: set fill column"
620 "Help string shown when mouse is on the fill column character.")
622 (defconst ruler-mode-comment-column-help-echo
623 "drag-mouse-2: set comment column"
624 "Help string shown when mouse is on the comment column character.")
626 (defconst ruler-mode-goal-column-help-echo
628 drag-mouse-2: set goal column, \
629 mouse-2: unset goal column"
630 "Help string shown when mouse is on the goal column character.")
632 (defconst ruler-mode-margin-help-echo
634 "Help string shown when mouse is over a margin area.")
636 (defconst ruler-mode-fringe-help-echo
638 "Help string shown when mouse is over a fringe area.")
640 (defsubst ruler-mode-space (width &rest props)
641 "Return a single space string of WIDTH times the normal character width.
642 Optional argument PROPS specifies other text properties to apply."
643 (apply 'propertize " " 'display (list 'space :width width) props))
645 (defun ruler-mode-ruler ()
646 "Compute and return a header line ruler."
647 (let* ((w (window-width))
652 ;; Setup the scrollbar, fringes, and margins areas.
653 (lf (ruler-mode-space
655 'face 'ruler-mode-fringes
656 'help-echo (format ruler-mode-fringe-help-echo
657 "Left" (or (car f) 0))))
658 (rf (ruler-mode-space
660 'face 'ruler-mode-fringes
661 'help-echo (format ruler-mode-fringe-help-echo
662 "Right" (or (cadr f) 0))))
663 (lm (ruler-mode-space
665 'face 'ruler-mode-margins
666 'help-echo (format ruler-mode-margin-help-echo
667 "Left" (or (car m) 0))))
668 (rm (ruler-mode-space
670 'face 'ruler-mode-margins
671 'help-echo (format ruler-mode-margin-help-echo
672 "Right" (or (cdr m) 0))))
673 (sb (ruler-mode-space
675 'face 'ruler-mode-pad))
676 ;; Remember the scrollbar vertical type.
677 (sbvt (car (window-current-scroll-bars)))
678 ;; Create an "clean" ruler.
682 (make-string w ruler-mode-basic-graduation-char))
683 'face 'ruler-mode-default
684 'local-map ruler-mode-map
686 (ruler-mode-show-tab-stops
687 ruler-mode-ruler-help-echo-when-tab-stops)
689 ruler-mode-ruler-help-echo-when-goal-column)
690 (ruler-mode-ruler-help-echo))))
692 ;; Setup the active area.
696 ;; Show a number graduation.
698 (setq c (number-to-string (/ j 10))
702 i (1+ i) 'face 'ruler-mode-column-number
704 (while (and (> m 0) (>= k 0))
705 (aset ruler k (aref c (setq m (1- m))))
707 ;; Show an intermediate graduation.
709 (aset ruler i ruler-mode-inter-graduation-char)))
712 ;; Show the `current-column' marker.
713 ((= j (current-column))
714 (aset ruler i ruler-mode-current-column-char)
716 i (1+ i) 'face 'ruler-mode-current-column
718 ;; Show the `goal-column' marker.
719 ((and goal-column (= j goal-column))
720 (aset ruler i ruler-mode-goal-column-char)
722 i (1+ i) 'face 'ruler-mode-goal-column
725 i (1+ i) 'mouse-face 'mode-line-highlight
728 i (1+ i) 'help-echo ruler-mode-goal-column-help-echo
730 ;; Show the `comment-column' marker.
731 ((= j comment-column)
732 (aset ruler i ruler-mode-comment-column-char)
734 i (1+ i) 'face 'ruler-mode-comment-column
737 i (1+ i) 'mouse-face 'mode-line-highlight
740 i (1+ i) 'help-echo ruler-mode-comment-column-help-echo
742 ;; Show the `fill-column' marker.
744 (aset ruler i ruler-mode-fill-column-char)
746 i (1+ i) 'face 'ruler-mode-fill-column
749 i (1+ i) 'mouse-face 'mode-line-highlight
752 i (1+ i) 'help-echo ruler-mode-fill-column-help-echo
754 ;; Show the `tab-stop-list' markers.
755 ((and ruler-mode-show-tab-stops (member j tab-stop-list))
756 (aset ruler i ruler-mode-tab-stop-char)
758 i (1+ i) 'face 'ruler-mode-tab-stop
762 ;; Return the ruler propertized string. Using list here,
763 ;; instead of concat visually separate the different areas.
764 (if (nth 2 (window-fringes))
765 ;; fringes outside margins.
766 (list "" (and (eq 'left sbvt) sb) lf lm
767 ruler rm rf (and (eq 'right sbvt) sb))
768 ;; fringes inside margins.
769 (list "" (and (eq 'left sbvt) sb) lm lf
770 ruler rf rm (and (eq 'right sbvt) sb)))))
772 (provide 'ruler-mode)
775 ;; coding: iso-latin-1
778 ;;; ruler-mode.el ends here