lisp/ruler-mode.el

   1 ;;; ruler-mode.el --- display a ruler in the header line
   2
   3 ;; Copyright (C) 2001 Free Software Foundation, Inc.
   4
   5 ;; Author: David Ponce <david@dponce.com>
   6 ;; Maintainer: David Ponce <david@dponce.com>
   7 ;; Created: 24 Mar 2001
   8 ;; Version: 1.4
   9 ;; Keywords: environment convenience
  10
  11 ;; This file is part of GNU Emacs.
  12
  13 ;; This program is free software; you can redistribute it and/or
  14 ;; modify it under the terms of the GNU General Public License as
  15 ;; published by the Free Software Foundation; either version 2, or (at
  16 ;; your option) any later version.
  17
  18 ;; This program is distributed in the hope that it will be useful, but
  19 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
  20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21 ;; General Public License for more details.
  22
  23 ;; You should have received a copy of the GNU General Public License
  24 ;; along with this program; see the file COPYING.  If not, write to
  25 ;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  26 ;; Boston, MA 02111-1307, USA.
  27
  28 ;;; Commentary:
  29
  30 ;; This library provides a minor mode to display a ruler in the header
  31 ;; line.  It works only on Emacs 21.
  32 ;;
  33 ;; You can use the mouse to change the `fill-column', `window-margins'
  34 ;; and `tab-stop-list' settings:
  35 ;;
  36 ;; [header-line (shift down-mouse-1)] set left margin to the ruler
  37 ;; graduation where the mouse pointer is on.
  38 ;;
  39 ;; [header-line (shift down-mouse-3)] set right margin to the ruler
  40 ;; graduation where the mouse pointer is on.
  41 ;;
  42 ;; [header-line down-mouse-2] set `fill-column' to the ruler
  43 ;; graduation where the mouse pointer is on.
  44 ;;
  45 ;; [header-line (control down-mouse-1)] add a tab stop to the ruler
  46 ;; graduation where the mouse pointer is on.
  47 ;;
  48 ;; [header-line (control down-mouse-3)] remove the tab stop at the
  49 ;; ruler graduation where the mouse pointer is on.
  50 ;;
  51 ;; [header-line (control down-mouse-2)] or M-x
  52 ;; `ruler-mode-toggle-show-tab-stops' toggle showing and visually
  53 ;; editing `tab-stop-list' setting.  The `ruler-mode-show-tab-stops'
  54 ;; option controls if the ruler shows tab stops by default.
  55 ;;
  56 ;; In the ruler the character `ruler-mode-current-column-char' shows
  57 ;; the `current-column' location, `ruler-mode-fill-column-char' shows
  58 ;; the `fill-column' location and `ruler-mode-tab-stop-char' shows tab
  59 ;; stop locations.  `window-margins' areas are shown with a different
  60 ;; background color.
  61 ;;
  62 ;; It is also possible to customize the following characters:
  63 ;;
  64 ;; - `ruler-mode-margins-char' character used to pad margin areas
  65 ;;   (space by default).
  66 ;; - `ruler-mode-basic-graduation-char' character used for basic
  67 ;;   graduations ('.' by default).
  68 ;; - `ruler-mode-inter-graduation-char' character used for
  69 ;;   intermediate graduations ('!' by default).
  70 ;;
  71 ;; The following faces are customizable:
  72 ;;
  73 ;; - `ruler-mode-default-face' the ruler default face.
  74 ;; - `ruler-mode-fill-column-face' the face used to highlight the
  75 ;;   `fill-column' character.
  76 ;; - `ruler-mode-current-column-face' the face used to highlight the
  77 ;;   `current-column' character.
  78 ;; - `ruler-mode-tab-stop-face' the face used to highlight tab stop
  79 ;;   characters.
  80 ;; - `ruler-mode-margins-face' the face used to highlight the
  81 ;;   `window-margins' areas.
  82 ;; - `ruler-mode-column-number-face' the face used to highlight the
  83 ;;   number graduations.
  84 ;;
  85 ;; `ruler-mode-default-face' inherits from the built-in `default' face.
  86 ;; All `ruler-mode' faces inerit from `ruler-mode-default-face'.
  87 ;;
  88 ;; WARNING: To keep ruler graduations aligned on text columns it is
  89 ;; important to use the same font family and size for ruler and text
  90 ;; areas.
  91
  92 ;; Installation
  93 ;;
  94 ;; To automatically display the ruler in specific major modes use:
  95 ;;
  96 ;;    (add-hook '<major-mode>-hook 'ruler-mode)
  97 ;;
  98
  99 ;;; History:
 100 ;;
 101 \f
 102 ;;; Code:
 103 (eval-when-compile
 104   (require 'wid-edit))
 105
 106 (defgroup ruler-mode nil
 107   "Display a ruler in the header line."
 108   :version "21.3"
 109   :group 'environment)
 110
 111 (defcustom ruler-mode-show-tab-stops nil
 112   "*If non-nil the ruler shows tab stop positions.
 113 Also allowing to visually change `tab-stop-list' setting using
 114 <C-down-mouse-1> and <C-down-mouse-3> on the ruler to respectively add
 115 or remove a tab stop.  \\[ruler-mode-toggle-show-tab-stops] or
 116 <C-down-mouse-2> on the ruler toggles showing/editing of tab stops."
 117   :group 'ruler-mode
 118   :type 'boolean)
 119
 120 ;; IMPORTANT: This function must be defined before the following
 121 ;; defcustoms because it is used in their :validate clause.
 122 (defun ruler-mode-character-validate (widget)
 123   "Ensure WIDGET value is a valid character value."
 124   (save-excursion
 125     (let ((value (widget-value widget)))
 126       (unless (characterp value)
 127         (widget-put widget :error
 128                     (format "Invalid character value: %S" value))
 129         widget))))
 130
 131 (defcustom ruler-mode-fill-column-char (if window-system
 132                                            ?\¶
 133                                          ?\|)
 134   "*Character used at the `fill-column' location."
 135   :group 'ruler-mode
 136   :type '(choice
 137           (character :tag "Character")
 138           (integer :tag "Integer char value"
 139                    :validate ruler-mode-character-validate)))
 140
 141 (defcustom ruler-mode-current-column-char (if window-system
 142                                               ?\¦
 143                                             ?\@)
 144   "*Character used at the `current-column' location."
 145   :group 'ruler-mode
 146   :type '(choice
 147           (character :tag "Character")
 148           (integer :tag "Integer char value"
 149                    :validate ruler-mode-character-validate)))
 150
 151 (defcustom ruler-mode-tab-stop-char ?\T
 152   "*Character used at `tab-stop-list' locations."
 153   :group 'ruler-mode
 154   :type '(choice
 155           (character :tag "Character")
 156           (integer :tag "Integer char value"
 157                    :validate ruler-mode-character-validate)))
 158
 159 (defcustom ruler-mode-margins-char ?\
 160   "*Character used in margin areas."
 161   :group 'ruler-mode
 162   :type '(choice
 163           (character :tag "Character")
 164           (integer :tag "Integer char value"
 165                    :validate ruler-mode-character-validate)))
 166
 167 (defcustom ruler-mode-basic-graduation-char ?\.
 168   "*Character used for basic graduations."
 169   :group 'ruler-mode
 170   :type '(choice
 171           (character :tag "Character")
 172           (integer :tag "Integer char value"
 173                    :validate ruler-mode-character-validate)))
 174
 175 (defcustom ruler-mode-inter-graduation-char ?\!
 176   "*Character used for intermediate graduations."
 177   :group 'ruler-mode
 178   :type '(choice
 179           (character :tag "Character")
 180           (integer :tag "Integer char value"
 181                    :validate ruler-mode-character-validate)))
 182 \f
 183 (defface ruler-mode-default-face
 184   '((((type tty))
 185      (:inherit default
 186                :background "grey64"
 187                :foreground "grey50"
 188                ))
 189     (t
 190      (:inherit default
 191                :background "grey76"
 192                :foreground "grey64"
 193                :box (:color "grey76"
 194                             :line-width 1
 195                             :style released-button)
 196                )))
 197   "Default face used by the ruler."
 198   :group 'ruler-mode)
 199
 200 (defface ruler-mode-column-number-face
 201   '((t
 202      (:inherit ruler-mode-default-face
 203                :foreground "black"
 204                )))
 205   "Face used to highlight number graduations."
 206   :group 'ruler-mode)
 207
 208 (defface ruler-mode-fill-column-face
 209   '((t
 210      (:inherit ruler-mode-default-face
 211                :foreground "red"
 212                )))
 213   "Face used to highlight the fill column character."
 214   :group 'ruler-mode)
 215
 216 (defface ruler-mode-tab-stop-face
 217   '((t
 218      (:inherit ruler-mode-default-face
 219                :foreground "steelblue"
 220                )))
 221   "Face used to highlight tab stop characters."
 222   :group 'ruler-mode)
 223
 224 (defface ruler-mode-margins-face
 225   '((((type tty))
 226      (:inherit ruler-mode-default-face
 227                :background "grey50"
 228                ))
 229     (t
 230      (:inherit ruler-mode-default-face
 231                :background "grey64"
 232                )))
 233   "Face used to highlight the `window-margins' areas."
 234   :group 'ruler-mode)
 235
 236 (defface ruler-mode-current-column-face
 237   '((t
 238      (:inherit ruler-mode-default-face
 239                :weight bold
 240                :foreground "yellow"
 241                )))
 242   "Face used to highlight the `current-column' character."
 243   :group 'ruler-mode)
 244 \f
 245 (defun ruler-mode-mouse-set-left-margin (start-event)
 246   "Set left margin to the graduation where the mouse pointer is on.
 247 START-EVENT is the mouse click event."
 248   (interactive "e")
 249   (let* ((start (event-start start-event))
 250          (end   (event-end   start-event))
 251          w col m lm0 lm rm)
 252     (if (eq start end) ;; mouse click
 253         (save-selected-window
 254           (select-window (posn-window start))
 255           (setq m   (window-margins)
 256                 lm0 (or (car m) 0)
 257                 rm  (or (cdr m) 0)
 258                 w   (window-width)
 259                 col (car (posn-col-row start))
 260                 lm  (min (- w rm) col))
 261           (message "Left margin set to %d (was %d)" lm lm0)
 262           (set-window-margins nil lm rm)))))
 263
 264 (defun ruler-mode-mouse-set-right-margin (start-event)
 265   "Set right margin to the graduation where the mouse pointer is on.
 266 START-EVENT is the mouse click event."
 267   (interactive "e")
 268   (let* ((start (event-start start-event))
 269          (end   (event-end   start-event))
 270          m col w lm rm0 rm)
 271     (if (eq start end) ;; mouse click
 272         (save-selected-window
 273           (select-window (posn-window start))
 274           (setq m   (window-margins)
 275                 rm0 (or (cdr m) 0)
 276                 lm  (or (car m) 0)
 277                 col (car (posn-col-row start))
 278                 w   (window-width)
 279                 rm  (max 0 (- w col)))
 280           (message "Right margin set to %d (was %d)" rm rm0)
 281           (set-window-margins nil lm rm)))))
 282
 283 (defun ruler-mode-mouse-set-fill-column (start-event)
 284   "Set `fill-column' to the graduation where the mouse pointer is on.
 285 START-EVENT is the mouse click event."
 286   (interactive "e")
 287   (let* ((start (event-start start-event))
 288          (end   (event-end   start-event))
 289          m col w lm rm hs fc)
 290     (if (eq start end) ;; mouse click
 291         (save-selected-window
 292           (select-window (posn-window start))
 293           (setq m   (window-margins)
 294                 lm  (or (car m) 0)
 295                 rm  (or (cdr m) 0)
 296                 col (- (car (posn-col-row start)) lm)
 297                 w   (window-width)
 298                 hs  (window-hscroll)
 299                 fc  (+ col hs))
 300           (and (>= col 0) (< (+ col lm rm) w)
 301                (progn
 302                  (message "Fill column set to %d (was %d)" fc fill-column)
 303                  (setq fill-column fc)))))))
 304 \f
 305 (defun ruler-mode-mouse-add-tab-stop (start-event)
 306   "Add a tab stop to the graduation where the mouse pointer is on.
 307 START-EVENT is the mouse click event."
 308   (interactive "e")
 309   (if ruler-mode-show-tab-stops
 310       (let* ((start (event-start start-event))
 311              (end   (event-end   start-event))
 312              m col w lm rm hs ts)
 313         (if (eq start end) ;; mouse click
 314             (save-selected-window
 315               (select-window (posn-window start))
 316               (setq m   (window-margins)
 317                     lm  (or (car m) 0)
 318                     rm  (or (cdr m) 0)
 319                     col (- (car (posn-col-row start)) lm)
 320                     w   (window-width)
 321                     hs  (window-hscroll)
 322                     ts  (+ col hs))
 323               (and (>= col 0) (< (+ col lm rm) w)
 324                    (not (member ts tab-stop-list))
 325                    (progn
 326                      (message "Tab stop set to %d" ts)
 327                      (setq tab-stop-list
 328                            (sort (cons ts tab-stop-list)
 329                                  #'<)))))))))
 330
 331 (defun ruler-mode-mouse-del-tab-stop (start-event)
 332   "Delete tab stop at the graduation where the mouse pointer is on.
 333 START-EVENT is the mouse click event."
 334   (interactive "e")
 335   (if ruler-mode-show-tab-stops
 336       (let* ((start (event-start start-event))
 337              (end   (event-end   start-event))
 338              m col w lm rm hs ts)
 339         (if (eq start end) ;; mouse click
 340             (save-selected-window
 341               (select-window (posn-window start))
 342               (setq m   (window-margins)
 343                     lm  (or (car m) 0)
 344                     rm  (or (cdr m) 0)
 345                     col (- (car (posn-col-row start)) lm)
 346                     w   (window-width)
 347                     hs  (window-hscroll)
 348                     ts  (+ col hs))
 349               (and (>= col 0) (< (+ col lm rm) w)
 350                    (member ts tab-stop-list)
 351                    (progn
 352                      (message "Tab stop at %d deleted" ts)
 353                      (setq tab-stop-list
 354                            (delete ts tab-stop-list)))))))))
 355
 356 (defun ruler-mode-toggle-show-tab-stops ()
 357   "Toggle showing of tab stops on the ruler."
 358   (interactive)
 359   (setq ruler-mode-show-tab-stops (not ruler-mode-show-tab-stops))
 360   (force-mode-line-update))
 361 \f
 362 (defvar ruler-mode-map
 363   (let ((km (make-sparse-keymap)))
 364     (define-key km [header-line down-mouse-1]
 365       #'ignore)
 366     (define-key km [header-line down-mouse-3]
 367       #'ignore)
 368     (define-key km [header-line down-mouse-2]
 369       #'ruler-mode-mouse-set-fill-column)
 370     (define-key km [header-line (shift down-mouse-1)]
 371       #'ruler-mode-mouse-set-left-margin)
 372     (define-key km [header-line (shift down-mouse-3)]
 373       #'ruler-mode-mouse-set-right-margin)
 374     (define-key km [header-line (control down-mouse-1)]
 375       #'ruler-mode-mouse-add-tab-stop)
 376     (define-key km [header-line (control down-mouse-3)]
 377       #'ruler-mode-mouse-del-tab-stop)
 378     (define-key km [header-line (control down-mouse-2)]
 379       #'ruler-mode-toggle-show-tab-stops)
 380     km)
 381   "Keymap for ruler minor mode.")
 382
 383 (defvar ruler-mode-header-line-format-old nil
 384   "Hold previous value of `header-line-format'.")
 385 (make-variable-buffer-local 'ruler-mode-header-line-format-old)
 386
 387 (defconst ruler-mode-header-line-format
 388   '(:eval (ruler-mode-ruler))
 389   "`header-line-format' used in ruler mode.")
 390
 391 ;;;###autoload
 392 (define-minor-mode ruler-mode
 393   "Display a ruler in the header line if ARG > 0."
 394   nil nil
 395   ruler-mode-map
 396   :group 'ruler-mode
 397   (if ruler-mode
 398       (progn
 399         ;; When `ruler-mode' is on save previous header line format
 400         ;; and install the ruler header line format.
 401         (setq ruler-mode-header-line-format-old header-line-format
 402               header-line-format ruler-mode-header-line-format)
 403         (add-hook 'post-command-hook    ; add local hook
 404                   #'force-mode-line-update nil t))
 405     ;; When `ruler-mode' is off restore previous header line format if
 406     ;; the current one is the ruler header line format.
 407     (if (eq header-line-format ruler-mode-header-line-format)
 408         (setq header-line-format ruler-mode-header-line-format-old))
 409     (remove-hook 'post-command-hook     ; remove local hook
 410                  #'force-mode-line-update t)))
 411 \f
 412 ;; Add ruler-mode to the minor mode menu in the mode line
 413 (define-key mode-line-mode-menu [ruler-mode]
 414   `(menu-item "Ruler" ruler-mode
 415               :button (:toggle . ruler-mode)))
 416
 417 (defconst ruler-mode-ruler-help-echo
 418   "\
 419 S-mouse-1/3: set L/R margin, \
 420 mouse-2: set fill col, \
 421 C-mouse-2: show tabs"
 422   "Help string shown when mouse pointer is over the ruler.
 423 `ruler-mode-show-tab-stops' is nil.")
 424
 425 (defconst ruler-mode-ruler-help-echo-tab
 426   "\
 427 C-mouse1/3: set/unset tab, \
 428 C-mouse-2: hide tabs"
 429   "Help string shown when mouse pointer is over the ruler.
 430 `ruler-mode-show-tab-stops' is non-nil.")
 431
 432 (defconst ruler-mode-left-margin-help-echo
 433   "Left margin %S"
 434   "Help string shown when mouse is over the left margin area.")
 435
 436 (defconst ruler-mode-right-margin-help-echo
 437   "Right margin %S"
 438   "Help string shown when mouse is over the right margin area.")
 439
 440 (defmacro ruler-mode-left-fringe-cols ()
 441   "Return the width, measured in columns, of the left fringe area."
 442   '(round (or (frame-parameter nil 'left-fringe) 0)
 443           (frame-char-width)))
 444
 445 (defmacro ruler-mode-right-fringe-cols ()
 446   "Return the width, measured in columns, of the right fringe area."
 447   '(round (or (frame-parameter nil 'right-fringe) 0)
 448           (frame-char-width)))
 449
 450 (defmacro ruler-mode-left-scroll-bar-cols ()
 451   "Return the width, measured in columns, of the left vertical scrollbar."
 452   '(if (eq (frame-parameter nil 'vertical-scroll-bars) 'left)
 453        (round (or (frame-parameter nil 'scroll-bar-width) 0)
 454               (frame-char-width))
 455      0))
 456
 457 (defmacro ruler-mode-right-scroll-bar-cols ()
 458   "Return the width, measured in columns, of the right vertical scrollbar."
 459   '(if (eq (frame-parameter nil 'vertical-scroll-bars) 'right)
 460        (round (or (frame-parameter nil 'scroll-bar-width) 0)
 461               (frame-char-width))
 462      0))
 463 \f
 464 (defun ruler-mode-ruler ()
 465   "Return a string ruler."
 466   (if ruler-mode
 467       (let* ((j     (+ (ruler-mode-left-fringe-cols)
 468                        (ruler-mode-left-scroll-bar-cols)))
 469              (w     (+ (window-width) j))
 470              (m     (window-margins))
 471              (l     (or (car m) 0))
 472              (r     (or (cdr m) 0))
 473              (o     (- (window-hscroll) l j))
 474              (i     0)
 475              (ruler (concat
 476                      ;; unit graduations
 477                      (make-string w ruler-mode-basic-graduation-char)
 478                      ;; extra space to fill the header line
 479                      (make-string (+ (ruler-mode-right-fringe-cols)
 480                                      (ruler-mode-right-scroll-bar-cols))
 481                                   ?\ )))
 482              c k)
 483
 484         ;; Setup default face and help echo.
 485         (put-text-property 0 (length ruler)
 486                            'face 'ruler-mode-default-face
 487                            ruler)
 488         (put-text-property 0 (length ruler)
 489                            'help-echo
 490                            (if ruler-mode-show-tab-stops
 491                                ruler-mode-ruler-help-echo-tab
 492                              ruler-mode-ruler-help-echo)
 493                            ruler)
 494         ;; Setup the local map.
 495         (put-text-property 0 (length ruler)
 496                            'local-map ruler-mode-map
 497                            ruler)
 498
 499         (setq j (+ l j))
 500         ;; Setup the left margin area.
 501         (put-text-property
 502          i j 'face 'ruler-mode-margins-face
 503          ruler)
 504         (put-text-property
 505          i j 'help-echo (format ruler-mode-left-margin-help-echo l)
 506          ruler)
 507         (while (< i j)
 508           (aset ruler i ruler-mode-margins-char)
 509           (setq i (1+ i)))
 510
 511         ;; Setup the ruler area.
 512         (setq r (- w r))
 513         (while (< i r)
 514           (setq j (+ i o))
 515           (cond
 516            ((= (mod j 10) 0)
 517             (setq c (number-to-string (/ j 10))
 518                   m (length c)
 519                   k i)
 520             (put-text-property
 521              i (1+ i) 'face 'ruler-mode-column-number-face
 522              ruler)
 523             (while (and (> m 0) (>= k 0))
 524               (aset ruler k (aref c (setq m (1- m))))
 525               (setq k (1- k)))
 526             )
 527            ((= (mod j 5) 0)
 528             (aset ruler i ruler-mode-inter-graduation-char)
 529             )
 530            )
 531           (setq i (1+ i)))
 532
 533         ;; Setup the right margin area.
 534         (put-text-property
 535          i (length ruler) 'face 'ruler-mode-margins-face
 536          ruler)
 537         (put-text-property
 538          i (length ruler) 'help-echo
 539          (format ruler-mode-right-margin-help-echo (- w r))
 540          ruler)
 541         (while (< i (length ruler))
 542           (aset ruler i ruler-mode-margins-char)
 543           (setq i (1+ i)))
 544
 545         ;; Show the `fill-column' marker.
 546         (setq i (- fill-column o))
 547         (and (>= i 0) (< i r)
 548              (aset ruler i ruler-mode-fill-column-char)
 549              (put-text-property
 550               i (1+ i) 'face 'ruler-mode-fill-column-face
 551               ruler))
 552
 553         ;; Show the `tab-stop-list' markers.
 554         (if ruler-mode-show-tab-stops
 555             (let ((tsl tab-stop-list) ts)
 556               (while tsl
 557                 (setq ts  (car tsl)
 558                       tsl (cdr tsl)
 559                       i   (- ts o))
 560                 (and (>= i 0) (< i r)
 561                      (aset ruler i ruler-mode-tab-stop-char)
 562                      (put-text-property
 563                       i (1+ i)
 564                       'face (cond
 565                              ;; Don't override the fill-column face
 566                              ((eq ts fill-column)
 567                               'ruler-mode-fill-column-face)
 568                              (t
 569                               'ruler-mode-tab-stop-face))
 570                       ruler)))))
 571
 572         ;; Show the `current-column' marker.
 573         (setq i (- (current-column) o))
 574         (and (>= i 0) (< i r)
 575              (aset ruler i ruler-mode-current-column-char)
 576              (put-text-property
 577               i (1+ i) 'face 'ruler-mode-current-column-face
 578               ruler))
 579
 580         ruler)))
 581
 582 (provide 'ruler-mode)
 583
 584 ;; Local Variables:
 585 ;; coding: iso-latin-1
 586 ;; End:
 587
 588 ;;; ruler-mode.el ends here