lisp/image-mode.el

   1 ;;; image-mode.el --- support for visiting image files
   2 ;;
   3 ;; Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
   4 ;;
   5 ;; Author: Richard Stallman <rms@gnu.org>
   6 ;; Keywords: multimedia
   7
   8 ;; This file is part of GNU Emacs.
   9
  10 ;; GNU Emacs is free software: you can redistribute it and/or modify
  11 ;; it under the terms of the GNU General Public License as published by
  12 ;; the Free Software Foundation, either version 3 of the License, or
  13 ;; (at your option) any later version.
  14
  15 ;; GNU Emacs is distributed in the hope that it will be useful,
  16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 ;; GNU General Public License for more details.
  19
  20 ;; You should have received a copy of the GNU General Public License
  21 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  22
  23 ;;; Commentary:
  24
  25 ;; Defines a major mode for visiting image files
  26 ;; that allows conversion between viewing the text of the file
  27 ;; and viewing the file as an image.  Viewing the image
  28 ;; works by putting a `display' text-property on the
  29 ;; image data, with the image-data still present underneath; if the
  30 ;; resulting buffer file is saved to another name it will correctly save
  31 ;; the image data to the new file.
  32
  33 ;;; Code:
  34
  35 (require 'image)
  36 (eval-when-compile (require 'cl))
  37
  38 ;;;###autoload (push (cons (purecopy "\\.jpe?g\\'")    'image-mode) auto-mode-alist)
  39 ;;;###autoload (push (cons (purecopy "\\.png\\'")      'image-mode) auto-mode-alist)
  40 ;;;###autoload (push (cons (purecopy "\\.gif\\'")      'image-mode) auto-mode-alist)
  41 ;;;###autoload (push (cons (purecopy "\\.tiff?\\'")    'image-mode) auto-mode-alist)
  42 ;;;###autoload (push (cons (purecopy "\\.p[bpgn]m\\'") 'image-mode) auto-mode-alist)
  43
  44 ;;;###autoload (push (cons (purecopy "\\.x[bp]m\\'")   'c-mode)     auto-mode-alist)
  45 ;;;###autoload (push (cons (purecopy "\\.x[bp]m\\'")   'image-mode) auto-mode-alist)
  46
  47 ;;;###autoload (push (cons (purecopy "\\.svgz?\\'")    'xml-mode)   auto-mode-alist)
  48 ;;;###autoload (push (cons (purecopy "\\.svgz?\\'")    'image-mode) auto-mode-alist)
  49
  50 ;;; Image mode window-info management.
  51
  52 (defvar image-mode-winprops-alist t)
  53 (make-variable-buffer-local 'image-mode-winprops-alist)
  54
  55 (defvar image-mode-new-window-functions nil
  56   "Special hook run when image data is requested in a new window.
  57 It is called with one argument, the initial WINPROPS.")
  58
  59 (defun image-mode-winprops (&optional window cleanup)
  60   "Return winprops of WINDOW.
  61 A winprops object has the shape (WINDOW . ALIST)."
  62   (cond ((null window)
  63          (setq window (selected-window)))
  64         ((not (windowp window))
  65          (error "Not a window: %s" window)))
  66   (when cleanup
  67     (setq image-mode-winprops-alist
  68           (delq nil (mapcar (lambda (winprop)
  69                               (if (window-live-p (car-safe winprop))
  70                                   winprop))
  71                             image-mode-winprops-alist))))
  72   (let ((winprops (assq window image-mode-winprops-alist)))
  73     ;; For new windows, set defaults from the latest.
  74     (unless winprops
  75       (setq winprops (cons window
  76                            (copy-alist (cdar image-mode-winprops-alist))))
  77       (run-hook-with-args 'image-mode-new-window-functions winprops))
  78     ;; Move window to front.
  79     (setq image-mode-winprops-alist
  80           (cons winprops (delq winprops image-mode-winprops-alist)))
  81     winprops))
  82
  83 (defun image-mode-window-get (prop &optional winprops)
  84   (unless (consp winprops) (setq winprops (image-mode-winprops winprops)))
  85   (cdr (assq prop (cdr winprops))))
  86
  87 (defsetf image-mode-window-get (prop &optional winprops) (val)
  88   `(image-mode-window-put ,prop ,val ,winprops))
  89
  90 (defun image-mode-window-put (prop val &optional winprops)
  91   (unless (consp winprops) (setq winprops (image-mode-winprops winprops)))
  92   (setcdr winprops (cons (cons prop val)
  93                          (delq (assq prop (cdr winprops)) (cdr winprops)))))
  94
  95 (defun image-set-window-vscroll (vscroll)
  96   (setf (image-mode-window-get 'vscroll) vscroll)
  97   (set-window-vscroll (selected-window) vscroll))
  98
  99 (defun image-set-window-hscroll (ncol)
 100   (setf (image-mode-window-get 'hscroll) ncol)
 101   (set-window-hscroll (selected-window) ncol))
 102
 103 (defun image-mode-reapply-winprops ()
 104   ;; When set-window-buffer, set hscroll and vscroll to what they were
 105   ;; last time the image was displayed in this window.
 106   (when (and (image-get-display-property)
 107              (listp image-mode-winprops-alist))
 108     (let* ((winprops (image-mode-winprops nil t))
 109            (hscroll (image-mode-window-get 'hscroll winprops))
 110            (vscroll (image-mode-window-get 'vscroll winprops)))
 111       (if hscroll (set-window-hscroll (selected-window) hscroll))
 112       (if vscroll (set-window-vscroll (selected-window) vscroll)))))
 113
 114 (defun image-mode-setup-winprops ()
 115   ;; Record current scroll settings.
 116   (unless (listp image-mode-winprops-alist)
 117     (setq image-mode-winprops-alist nil))
 118   (add-hook 'window-configuration-change-hook
 119             'image-mode-reapply-winprops nil t))
 120
 121 ;;; Image scrolling functions
 122
 123 (defun image-get-display-property ()
 124   (get-char-property (point-min) 'display
 125                      ;; There might be different images for different displays.
 126                      (if (eq (window-buffer) (current-buffer))
 127                          (selected-window))))
 128
 129 (declare-function image-size "image.c" (spec &optional pixels frame))
 130
 131 (defun image-forward-hscroll (&optional n)
 132   "Scroll image in current window to the left by N character widths.
 133 Stop if the right edge of the image is reached."
 134   (interactive "p")
 135   (cond ((= n 0) nil)
 136         ((< n 0)
 137          (image-set-window-hscroll (max 0 (+ (window-hscroll) n))))
 138         (t
 139          (let* ((image (image-get-display-property))
 140                 (edges (window-inside-edges))
 141                 (win-width (- (nth 2 edges) (nth 0 edges)))
 142                 (img-width (ceiling (car (image-size image)))))
 143            (image-set-window-hscroll (min (max 0 (- img-width win-width))
 144                                           (+ n (window-hscroll))))))))
 145
 146 (defun image-backward-hscroll (&optional n)
 147   "Scroll image in current window to the right by N character widths.
 148 Stop if the left edge of the image is reached."
 149   (interactive "p")
 150   (image-forward-hscroll (- n)))
 151
 152 (defun image-next-line (&optional n)
 153   "Scroll image in current window upward by N lines.
 154 Stop if the bottom edge of the image is reached."
 155   (interactive "p")
 156   (cond ((= n 0) nil)
 157         ((< n 0)
 158          (image-set-window-vscroll (max 0 (+ (window-vscroll) n))))
 159         (t
 160          (let* ((image (image-get-display-property))
 161                 (edges (window-inside-edges))
 162                 (win-height (- (nth 3 edges) (nth 1 edges)))
 163                 (img-height (ceiling (cdr (image-size image)))))
 164            (image-set-window-vscroll (min (max 0 (- img-height win-height))
 165                                           (+ n (window-vscroll))))))))
 166
 167 (defun image-previous-line (&optional n)
 168   "Scroll image in current window downward by N lines.
 169 Stop if the top edge of the image is reached."
 170   (interactive "p")
 171   (image-next-line (- n)))
 172
 173 (defun image-scroll-up (&optional n)
 174   "Scroll image in current window upward by N lines.
 175 Stop if the bottom edge of the image is reached.
 176 If ARG is omitted or nil, scroll upward by a near full screen.
 177 A near full screen is `next-screen-context-lines' less than a full screen.
 178 Negative ARG means scroll downward.
 179 If ARG is the atom `-', scroll downward by nearly full screen.
 180 When calling from a program, supply as argument a number, nil, or `-'."
 181   (interactive "P")
 182   (cond ((null n)
 183          (let* ((edges (window-inside-edges))
 184                 (win-height (- (nth 3 edges) (nth 1 edges))))
 185            (image-next-line
 186             (max 0 (- win-height next-screen-context-lines)))))
 187         ((eq n '-)
 188          (let* ((edges (window-inside-edges))
 189                 (win-height (- (nth 3 edges) (nth 1 edges))))
 190            (image-next-line
 191             (min 0 (- next-screen-context-lines win-height)))))
 192         (t (image-next-line (prefix-numeric-value n)))))
 193
 194 (defun image-scroll-down (&optional n)
 195   "Scroll image in current window downward by N lines.
 196 Stop if the top edge of the image is reached.
 197 If ARG is omitted or nil, scroll downward by a near full screen.
 198 A near full screen is `next-screen-context-lines' less than a full screen.
 199 Negative ARG means scroll upward.
 200 If ARG is the atom `-', scroll upward by nearly full screen.
 201 When calling from a program, supply as argument a number, nil, or `-'."
 202   (interactive "P")
 203   (cond ((null n)
 204          (let* ((edges (window-inside-edges))
 205                 (win-height (- (nth 3 edges) (nth 1 edges))))
 206            (image-next-line
 207             (min 0 (- next-screen-context-lines win-height)))))
 208         ((eq n '-)
 209          (let* ((edges (window-inside-edges))
 210                 (win-height (- (nth 3 edges) (nth 1 edges))))
 211            (image-next-line
 212             (max 0 (- win-height next-screen-context-lines)))))
 213         (t (image-next-line (- (prefix-numeric-value n))))))
 214
 215 (defun image-bol (arg)
 216   "Scroll horizontally to the left edge of the image in the current window.
 217 With argument ARG not nil or 1, move forward ARG - 1 lines first,
 218 stopping if the top or bottom edge of the image is reached."
 219   (interactive "p")
 220   (and arg
 221        (/= (setq arg (prefix-numeric-value arg)) 1)
 222        (image-next-line (- arg 1)))
 223   (image-set-window-hscroll 0))
 224
 225 (defun image-eol (arg)
 226   "Scroll horizontally to the right edge of the image in the current window.
 227 With argument ARG not nil or 1, move forward ARG - 1 lines first,
 228 stopping if the top or bottom edge of the image is reached."
 229   (interactive "p")
 230   (and arg
 231        (/= (setq arg (prefix-numeric-value arg)) 1)
 232        (image-next-line (- arg 1)))
 233   (let* ((image (image-get-display-property))
 234          (edges (window-inside-edges))
 235          (win-width (- (nth 2 edges) (nth 0 edges)))
 236          (img-width (ceiling (car (image-size image)))))
 237     (image-set-window-hscroll (max 0 (- img-width win-width)))))
 238
 239 (defun image-bob ()
 240   "Scroll to the top-left corner of the image in the current window."
 241   (interactive)
 242   (image-set-window-hscroll 0)
 243   (image-set-window-vscroll 0))
 244
 245 (defun image-eob ()
 246   "Scroll to the bottom-right corner of the image in the current window."
 247   (interactive)
 248   (let* ((image (image-get-display-property))
 249          (edges (window-inside-edges))
 250          (win-width (- (nth 2 edges) (nth 0 edges)))
 251          (img-width (ceiling (car (image-size image))))
 252          (win-height (- (nth 3 edges) (nth 1 edges)))
 253          (img-height (ceiling (cdr (image-size image)))))
 254     (image-set-window-hscroll (max 0 (- img-width win-width)))
 255     (image-set-window-vscroll (max 0 (- img-height win-height)))))
 256
 257 ;; Adjust frame and image size.
 258
 259 (defun image-mode-fit-frame ()
 260   "Fit the frame to the current image.
 261 This function assumes the current frame has only one window."
 262   ;; FIXME: This does not take into account decorations like mode-line,
 263   ;; minibuffer, header-line, ...
 264   (interactive)
 265   (let* ((saved (frame-parameter nil 'image-mode-saved-size))
 266          (display (image-get-display-property))
 267          (size (image-size display)))
 268     (if (and saved
 269              (eq (caar saved) (frame-width))
 270              (eq (cdar saved) (frame-height)))
 271         (progn ;; Toggle back to previous non-fitted size.
 272           (set-frame-parameter nil 'image-mode-saved-size nil)
 273           (setq size (cdr saved)))
 274       ;; Round up size, and save current size so we can toggle back to it.
 275       (setcar size (ceiling (car size)))
 276       (setcdr size (ceiling (cdr size)))
 277       (set-frame-parameter nil 'image-mode-saved-size
 278                            (cons size (cons (frame-width) (frame-height)))))
 279     (set-frame-width  (selected-frame) (car size))
 280     (set-frame-height (selected-frame) (cdr size))))
 281
 282 ;;; Image Mode setup
 283
 284 (defvar image-type nil
 285   "Current image type.
 286 This variable is used to display the current image type in the mode line.")
 287 (make-variable-buffer-local 'image-type)
 288
 289 (defvar image-mode-previous-major-mode nil
 290   "Internal variable to keep the previous non-image major mode.")
 291
 292 (defvar image-mode-map
 293   (let ((map (make-sparse-keymap)))
 294     (suppress-keymap map)
 295     (define-key map "q"         'quit-window)
 296     (define-key map "\C-c\C-c" 'image-toggle-display)
 297     (define-key map (kbd "SPC")       'image-scroll-up)
 298     (define-key map (kbd "DEL")       'image-scroll-down)
 299     (define-key map [remap forward-char] 'image-forward-hscroll)
 300     (define-key map [remap backward-char] 'image-backward-hscroll)
 301     (define-key map [remap right-char] 'image-forward-hscroll)
 302     (define-key map [remap left-char] 'image-backward-hscroll)
 303     (define-key map [remap previous-line] 'image-previous-line)
 304     (define-key map [remap next-line] 'image-next-line)
 305     (define-key map [remap scroll-up] 'image-scroll-up)
 306     (define-key map [remap scroll-down] 'image-scroll-down)
 307     (define-key map [remap scroll-up-command] 'image-scroll-up)
 308     (define-key map [remap scroll-down-command] 'image-scroll-down)
 309     (define-key map [remap move-beginning-of-line] 'image-bol)
 310     (define-key map [remap move-end-of-line] 'image-eol)
 311     (define-key map [remap beginning-of-buffer] 'image-bob)
 312     (define-key map [remap end-of-buffer] 'image-eob)
 313     map)
 314   "Major mode keymap for viewing images in Image mode.")
 315
 316 (defvar image-minor-mode-map
 317   (let ((map (make-sparse-keymap)))
 318     (define-key map "\C-c\C-c" 'image-toggle-display)
 319     map)
 320   "Minor mode keymap for viewing images as text in Image mode.")
 321
 322 (defvar bookmark-make-record-function)
 323
 324 (put 'image-mode 'mode-class 'special)
 325
 326 ;;;###autoload
 327 (defun image-mode ()
 328   "Major mode for image files.
 329 You can use \\<image-mode-map>\\[image-toggle-display]
 330 to toggle between display as an image and display as text."
 331   (interactive)
 332   (condition-case err
 333       (progn
 334         (unless (display-images-p)
 335           (error "Display does not support images"))
 336
 337         (kill-all-local-variables)
 338         (setq major-mode 'image-mode)
 339
 340         (if (not (image-get-display-property))
 341             (progn
 342               (image-toggle-display-image)
 343               ;; If attempt to display the image fails.
 344               (if (not (image-get-display-property))
 345                   (error "Invalid image")))
 346           ;; Set next vars when image is already displayed but local
 347           ;; variables were cleared by kill-all-local-variables
 348           (setq cursor-type nil truncate-lines t
 349                 image-type (plist-get (cdr (image-get-display-property)) :type)))
 350
 351         (setq mode-name (if image-type (format "Image[%s]" image-type) "Image"))
 352         (use-local-map image-mode-map)
 353
 354         ;; Use our own bookmarking function for images.
 355         (set (make-local-variable 'bookmark-make-record-function)
 356              'image-bookmark-make-record)
 357
 358         ;; Keep track of [vh]scroll when switching buffers
 359         (image-mode-setup-winprops)
 360
 361         (add-hook 'change-major-mode-hook 'image-toggle-display-text nil t)
 362         (add-hook 'after-revert-hook 'image-after-revert-hook nil t)
 363         (run-mode-hooks 'image-mode-hook)
 364         (message "%s" (concat
 365                        (substitute-command-keys
 366                         "Type \\[image-toggle-display] to view the image as ")
 367                        (if (image-get-display-property)
 368                            "text" "an image") ".")))
 369     (error
 370      (image-mode-as-text)
 371      (funcall
 372       (if (called-interactively-p 'any) 'error 'message)
 373       "Cannot display image: %s" (cdr err)))))
 374
 375 ;;;###autoload
 376 (define-minor-mode image-minor-mode
 377   "Toggle Image minor mode.
 378 With arg, turn Image minor mode on if arg is positive, off otherwise.
 379 It provides the key \\<image-mode-map>\\[image-toggle-display] \
 380 to switch back to `image-mode'
 381 to display an image file as the actual image."
 382   nil (:eval (if image-type (format " Image[%s]" image-type) " Image"))
 383   image-minor-mode-map
 384   :group 'image
 385   :version "22.1"
 386   (if image-minor-mode
 387       (add-hook 'change-major-mode-hook (lambda () (image-minor-mode -1)) nil t)))
 388
 389 ;;;###autoload
 390 (defun image-mode-as-text ()
 391   "Set a non-image mode as major mode in combination with image minor mode.
 392 A non-image major mode found from `auto-mode-alist' or Fundamental mode
 393 displays an image file as text.  `image-minor-mode' provides the key
 394 \\<image-mode-map>\\[image-toggle-display] to switch back to `image-mode'
 395 to display an image file as the actual image.
 396
 397 You can use `image-mode-as-text' in `auto-mode-alist' when you want
 398 to display an image file as text initially.
 399
 400 See commands `image-mode' and `image-minor-mode' for more information
 401 on these modes."
 402   (interactive)
 403   ;; image-mode-as-text = normal-mode + image-minor-mode
 404   (let ((previous-image-type image-type)) ; preserve `image-type'
 405     (if image-mode-previous-major-mode
 406         ;; Restore previous major mode that was already found by this
 407         ;; function and cached in `image-mode-previous-major-mode'
 408         (funcall image-mode-previous-major-mode)
 409       (let ((auto-mode-alist
 410              (delq nil (mapcar
 411                         (lambda (elt)
 412                           (unless (memq (or (car-safe (cdr elt)) (cdr elt))
 413                                         '(image-mode image-mode-maybe image-mode-as-text))
 414                             elt))
 415                         auto-mode-alist)))
 416             (magic-fallback-mode-alist
 417              (delq nil (mapcar
 418                         (lambda (elt)
 419                           (unless (memq (or (car-safe (cdr elt)) (cdr elt))
 420                                         '(image-mode image-mode-maybe image-mode-as-text))
 421                             elt))
 422                         magic-fallback-mode-alist))))
 423         (normal-mode)
 424         (set (make-local-variable 'image-mode-previous-major-mode) major-mode)))
 425     ;; Restore `image-type' after `kill-all-local-variables' in `normal-mode'.
 426     (setq image-type previous-image-type)
 427     ;; Enable image minor mode with `C-c C-c'.
 428     (image-minor-mode 1)
 429     ;; Show the image file as text.
 430     (image-toggle-display-text)
 431     (message "%s" (concat
 432                    (substitute-command-keys
 433                     "Type \\[image-toggle-display] to view the image as ")
 434                    (if (image-get-display-property)
 435                        "text" "an image") "."))))
 436
 437 (define-obsolete-function-alias 'image-mode-maybe 'image-mode "23.2")
 438
 439 (defun image-toggle-display-text ()
 440   "Show the image file as text.
 441 Remove text properties that display the image."
 442   (let ((inhibit-read-only t)
 443         (buffer-undo-list t)
 444         (modified (buffer-modified-p)))
 445     (remove-list-of-text-properties (point-min) (point-max)
 446                                     '(display intangible read-nonsticky
 447                                               read-only front-sticky))
 448     (set-buffer-modified-p modified)
 449     (if (called-interactively-p 'any)
 450         (message "Repeat this command to go back to displaying the image"))))
 451
 452 (defvar archive-superior-buffer)
 453 (defvar tar-superior-buffer)
 454 (declare-function image-flush "image.c" (spec &optional frame))
 455
 456 (defun image-toggle-display-image ()
 457   "Show the image of the image file.
 458 Turn the image data into a real image, but only if the whole file
 459 was inserted."
 460   (let* ((filename (buffer-file-name))
 461          (data-p (not (and filename
 462                            (file-readable-p filename)
 463                            (not (file-remote-p filename))
 464                            (not (buffer-modified-p))
 465                            (not (and (boundp 'archive-superior-buffer)
 466                                      archive-superior-buffer))
 467                            (not (and (boundp 'tar-superior-buffer)
 468                                      tar-superior-buffer)))))
 469          (file-or-data (if data-p
 470                            (string-make-unibyte
 471                             (buffer-substring-no-properties (point-min) (point-max)))
 472                          filename))
 473          (type (image-type file-or-data nil data-p))
 474          (image (create-animated-image file-or-data type data-p))
 475          (props
 476           `(display ,image
 477                     intangible ,image
 478                     rear-nonsticky (display intangible)
 479                     read-only t front-sticky (read-only)))
 480          (inhibit-read-only t)
 481          (buffer-undo-list t)
 482          (modified (buffer-modified-p)))
 483     (image-flush image)
 484     (let ((buffer-file-truename nil)) ; avoid changing dir mtime by lock_file
 485       (add-text-properties (point-min) (point-max) props)
 486       (restore-buffer-modified-p modified))
 487     ;; Inhibit the cursor when the buffer contains only an image,
 488     ;; because cursors look very strange on top of images.
 489     (setq cursor-type nil)
 490     ;; This just makes the arrow displayed in the right fringe
 491     ;; area look correct when the image is wider than the window.
 492     (setq truncate-lines t)
 493     ;; Allow navigation of large images
 494     (set (make-local-variable 'auto-hscroll-mode) nil)
 495     (setq image-type type)
 496     (if (eq major-mode 'image-mode)
 497         (setq mode-name (format "Image[%s]" type)))
 498     (if (called-interactively-p 'any)
 499         (message "Repeat this command to go back to displaying the file as text"))))
 500
 501 (defun image-toggle-display ()
 502   "Start or stop displaying an image file as the actual image.
 503 This command toggles between `image-mode-as-text' showing the text of
 504 the image file and `image-mode' showing the image as an image."
 505   (interactive)
 506   (if (image-get-display-property)
 507       (image-mode-as-text)
 508     (image-mode)))
 509
 510 (defun image-after-revert-hook ()
 511   (when (image-get-display-property)
 512     (image-toggle-display-text)
 513     ;; Update image display.
 514     (redraw-frame (selected-frame))
 515     (image-toggle-display-image)))
 516
 517 \f
 518 ;;; Support for bookmark.el
 519 (declare-function bookmark-make-record-default "bookmark"
 520                   (&optional point-only))
 521 (declare-function bookmark-prop-get "bookmark" (bookmark prop))
 522 (declare-function bookmark-default-handler "bookmark" (bmk))
 523
 524 (defun image-bookmark-make-record ()
 525   (nconc (bookmark-make-record-default)
 526          `((image-type . ,image-type)
 527            (handler    . image-bookmark-jump))))
 528
 529 ;;;###autoload
 530 (defun image-bookmark-jump (bmk)
 531   ;; This implements the `handler' function interface for record type
 532   ;; returned by `bookmark-make-record-function', which see.
 533   (prog1 (bookmark-default-handler bmk)
 534     (when (not (string= image-type (bookmark-prop-get bmk 'image-type)))
 535       (image-toggle-display))))
 536 \f
 537 (provide 'image-mode)
 538
 539 ;; arch-tag: b5b2b7e6-26a7-4b79-96e3-1546b5c4c6cb
 540 ;;; image-mode.el ends here