* lisp/emacs-lisp/autoload.el (make-autoload): Preload the macros's
[emacs.git] / lisp / image-mode.el
bloba34989171bbb1496f19031f899f7bc5a1448c446
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
8 ;; This file is part of GNU Emacs.
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.
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.
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/>.
23 ;;; Commentary:
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.
33 ;;; Code:
35 (require 'image)
36 (eval-when-compile (require 'cl))
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)
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)
47 ;;;###autoload (push (cons (purecopy "\\.svgz?\\'") 'xml-mode) auto-mode-alist)
48 ;;;###autoload (push (cons (purecopy "\\.svgz?\\'") 'image-mode) auto-mode-alist)
50 ;;; Image mode window-info management.
52 (defvar image-mode-winprops-alist t)
53 (make-variable-buffer-local 'image-mode-winprops-alist)
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.")
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))
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))))
87 (defsetf image-mode-window-get (prop &optional winprops) (val)
88 `(image-mode-window-put ,prop ,val ,winprops))
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)))))
95 (defun image-set-window-vscroll (vscroll)
96 (setf (image-mode-window-get 'vscroll) vscroll)
97 (set-window-vscroll (selected-window) vscroll))
99 (defun image-set-window-hscroll (ncol)
100 (setf (image-mode-window-get 'hscroll) ncol)
101 (set-window-hscroll (selected-window) ncol))
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)))))
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))
121 ;;; Image scrolling functions
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))))
129 (declare-function image-size "image.c" (spec &optional pixels frame))
131 (defun image-display-size (spec &optional pixels frame)
132 "Wrapper around `image-size', to handle slice display properties.
133 If SPEC is an image display property, call `image-size' with the
134 given arguments.
135 If SPEC is a list of properties containing `image' and `slice'
136 properties, calculate the display size from the slice property.
137 If SPEC contains `image' but not `slice', call `image-size' with
138 the specified image."
139 (if (eq (car spec) 'image)
140 (image-size spec pixels frame)
141 (let ((image (assoc 'image spec))
142 (slice (assoc 'slice spec)))
143 (cond ((and image slice)
144 (if pixels
145 (cons (nth 3 slice) (nth 4 slice))
146 (cons (/ (float (nth 3 slice)) (frame-char-width frame))
147 (/ (float (nth 4 slice)) (frame-char-height frame)))))
148 (image
149 (image-size image pixels frame))
151 (error "Invalid image specification: %s" spec))))))
153 (defun image-forward-hscroll (&optional n)
154 "Scroll image in current window to the left by N character widths.
155 Stop if the right edge of the image is reached."
156 (interactive "p")
157 (cond ((= n 0) nil)
158 ((< n 0)
159 (image-set-window-hscroll (max 0 (+ (window-hscroll) n))))
161 (let* ((image (image-get-display-property))
162 (edges (window-inside-edges))
163 (win-width (- (nth 2 edges) (nth 0 edges)))
164 (img-width (ceiling (car (image-display-size image)))))
165 (image-set-window-hscroll (min (max 0 (- img-width win-width))
166 (+ n (window-hscroll))))))))
168 (defun image-backward-hscroll (&optional n)
169 "Scroll image in current window to the right by N character widths.
170 Stop if the left edge of the image is reached."
171 (interactive "p")
172 (image-forward-hscroll (- n)))
174 (defun image-next-line (&optional n)
175 "Scroll image in current window upward by N lines.
176 Stop if the bottom edge of the image is reached."
177 (interactive "p")
178 (cond ((= n 0) nil)
179 ((< n 0)
180 (image-set-window-vscroll (max 0 (+ (window-vscroll) n))))
182 (let* ((image (image-get-display-property))
183 (edges (window-inside-edges))
184 (win-height (- (nth 3 edges) (nth 1 edges)))
185 (img-height (ceiling (cdr (image-display-size image)))))
186 (image-set-window-vscroll (min (max 0 (- img-height win-height))
187 (+ n (window-vscroll))))))))
189 (defun image-previous-line (&optional n)
190 "Scroll image in current window downward by N lines.
191 Stop if the top edge of the image is reached."
192 (interactive "p")
193 (image-next-line (- n)))
195 (defun image-scroll-up (&optional n)
196 "Scroll image in current window upward by N lines.
197 Stop if the bottom edge of the image is reached.
198 If ARG is omitted or nil, scroll upward by a near full screen.
199 A near full screen is `next-screen-context-lines' less than a full screen.
200 Negative ARG means scroll downward.
201 If ARG is the atom `-', scroll downward by nearly full screen.
202 When calling from a program, supply as argument a number, nil, or `-'."
203 (interactive "P")
204 (cond ((null n)
205 (let* ((edges (window-inside-edges))
206 (win-height (- (nth 3 edges) (nth 1 edges))))
207 (image-next-line
208 (max 0 (- win-height next-screen-context-lines)))))
209 ((eq n '-)
210 (let* ((edges (window-inside-edges))
211 (win-height (- (nth 3 edges) (nth 1 edges))))
212 (image-next-line
213 (min 0 (- next-screen-context-lines win-height)))))
214 (t (image-next-line (prefix-numeric-value n)))))
216 (defun image-scroll-down (&optional n)
217 "Scroll image in current window downward by N lines.
218 Stop if the top edge of the image is reached.
219 If ARG is omitted or nil, scroll downward by a near full screen.
220 A near full screen is `next-screen-context-lines' less than a full screen.
221 Negative ARG means scroll upward.
222 If ARG is the atom `-', scroll upward by nearly full screen.
223 When calling from a program, supply as argument a number, nil, or `-'."
224 (interactive "P")
225 (cond ((null n)
226 (let* ((edges (window-inside-edges))
227 (win-height (- (nth 3 edges) (nth 1 edges))))
228 (image-next-line
229 (min 0 (- next-screen-context-lines win-height)))))
230 ((eq n '-)
231 (let* ((edges (window-inside-edges))
232 (win-height (- (nth 3 edges) (nth 1 edges))))
233 (image-next-line
234 (max 0 (- win-height next-screen-context-lines)))))
235 (t (image-next-line (- (prefix-numeric-value n))))))
237 (defun image-bol (arg)
238 "Scroll horizontally to the left edge of the image in the current window.
239 With argument ARG not nil or 1, move forward ARG - 1 lines first,
240 stopping if the top or bottom edge of the image is reached."
241 (interactive "p")
242 (and arg
243 (/= (setq arg (prefix-numeric-value arg)) 1)
244 (image-next-line (- arg 1)))
245 (image-set-window-hscroll 0))
247 (defun image-eol (arg)
248 "Scroll horizontally to the right edge of the image in the current window.
249 With argument ARG not nil or 1, move forward ARG - 1 lines first,
250 stopping if the top or bottom edge of the image is reached."
251 (interactive "p")
252 (and arg
253 (/= (setq arg (prefix-numeric-value arg)) 1)
254 (image-next-line (- arg 1)))
255 (let* ((image (image-get-display-property))
256 (edges (window-inside-edges))
257 (win-width (- (nth 2 edges) (nth 0 edges)))
258 (img-width (ceiling (car (image-display-size image)))))
259 (image-set-window-hscroll (max 0 (- img-width win-width)))))
261 (defun image-bob ()
262 "Scroll to the top-left corner of the image in the current window."
263 (interactive)
264 (image-set-window-hscroll 0)
265 (image-set-window-vscroll 0))
267 (defun image-eob ()
268 "Scroll to the bottom-right corner of the image in the current window."
269 (interactive)
270 (let* ((image (image-get-display-property))
271 (edges (window-inside-edges))
272 (win-width (- (nth 2 edges) (nth 0 edges)))
273 (img-width (ceiling (car (image-display-size image))))
274 (win-height (- (nth 3 edges) (nth 1 edges)))
275 (img-height (ceiling (cdr (image-display-size image)))))
276 (image-set-window-hscroll (max 0 (- img-width win-width)))
277 (image-set-window-vscroll (max 0 (- img-height win-height)))))
279 ;; Adjust frame and image size.
281 (defun image-mode-fit-frame ()
282 "Fit the frame to the current image.
283 This function assumes the current frame has only one window."
284 ;; FIXME: This does not take into account decorations like mode-line,
285 ;; minibuffer, header-line, ...
286 (interactive)
287 (let* ((saved (frame-parameter nil 'image-mode-saved-size))
288 (display (image-get-display-property))
289 (size (image-display-size display)))
290 (if (and saved
291 (eq (caar saved) (frame-width))
292 (eq (cdar saved) (frame-height)))
293 (progn ;; Toggle back to previous non-fitted size.
294 (set-frame-parameter nil 'image-mode-saved-size nil)
295 (setq size (cdr saved)))
296 ;; Round up size, and save current size so we can toggle back to it.
297 (setcar size (ceiling (car size)))
298 (setcdr size (ceiling (cdr size)))
299 (set-frame-parameter nil 'image-mode-saved-size
300 (cons size (cons (frame-width) (frame-height)))))
301 (set-frame-width (selected-frame) (car size))
302 (set-frame-height (selected-frame) (cdr size))))
304 ;;; Image Mode setup
306 (defvar image-type nil
307 "Current image type.
308 This variable is used to display the current image type in the mode line.")
309 (make-variable-buffer-local 'image-type)
311 (defvar image-mode-previous-major-mode nil
312 "Internal variable to keep the previous non-image major mode.")
314 (defvar image-mode-map
315 (let ((map (make-sparse-keymap)))
316 (suppress-keymap map)
317 (define-key map "q" 'quit-window)
318 (define-key map "\C-c\C-c" 'image-toggle-display)
319 (define-key map (kbd "SPC") 'image-scroll-up)
320 (define-key map (kbd "DEL") 'image-scroll-down)
321 (define-key map [remap forward-char] 'image-forward-hscroll)
322 (define-key map [remap backward-char] 'image-backward-hscroll)
323 (define-key map [remap right-char] 'image-forward-hscroll)
324 (define-key map [remap left-char] 'image-backward-hscroll)
325 (define-key map [remap previous-line] 'image-previous-line)
326 (define-key map [remap next-line] 'image-next-line)
327 (define-key map [remap scroll-up] 'image-scroll-up)
328 (define-key map [remap scroll-down] 'image-scroll-down)
329 (define-key map [remap scroll-up-command] 'image-scroll-up)
330 (define-key map [remap scroll-down-command] 'image-scroll-down)
331 (define-key map [remap move-beginning-of-line] 'image-bol)
332 (define-key map [remap move-end-of-line] 'image-eol)
333 (define-key map [remap beginning-of-buffer] 'image-bob)
334 (define-key map [remap end-of-buffer] 'image-eob)
335 map)
336 "Major mode keymap for viewing images in Image mode.")
338 (defvar image-minor-mode-map
339 (let ((map (make-sparse-keymap)))
340 (define-key map "\C-c\C-c" 'image-toggle-display)
341 map)
342 "Minor mode keymap for viewing images as text in Image mode.")
344 (defvar bookmark-make-record-function)
346 (put 'image-mode 'mode-class 'special)
348 ;;;###autoload
349 (defun image-mode ()
350 "Major mode for image files.
351 You can use \\<image-mode-map>\\[image-toggle-display]
352 to toggle between display as an image and display as text."
353 (interactive)
354 (condition-case err
355 (progn
356 (unless (display-images-p)
357 (error "Display does not support images"))
359 (kill-all-local-variables)
360 (setq major-mode 'image-mode)
362 (if (not (image-get-display-property))
363 (progn
364 (image-toggle-display-image)
365 ;; If attempt to display the image fails.
366 (if (not (image-get-display-property))
367 (error "Invalid image")))
368 ;; Set next vars when image is already displayed but local
369 ;; variables were cleared by kill-all-local-variables
370 (setq cursor-type nil truncate-lines t
371 image-type (plist-get (cdr (image-get-display-property)) :type)))
373 (setq mode-name (if image-type (format "Image[%s]" image-type) "Image"))
374 (use-local-map image-mode-map)
376 ;; Use our own bookmarking function for images.
377 (set (make-local-variable 'bookmark-make-record-function)
378 'image-bookmark-make-record)
380 ;; Keep track of [vh]scroll when switching buffers
381 (image-mode-setup-winprops)
383 (add-hook 'change-major-mode-hook 'image-toggle-display-text nil t)
384 (add-hook 'after-revert-hook 'image-after-revert-hook nil t)
385 (run-mode-hooks 'image-mode-hook)
386 (message "%s" (concat
387 (substitute-command-keys
388 "Type \\[image-toggle-display] to view the image as ")
389 (if (image-get-display-property)
390 "text" "an image") ".")))
391 (error
392 (image-mode-as-text)
393 (funcall
394 (if (called-interactively-p 'any) 'error 'message)
395 "Cannot display image: %s" (cdr err)))))
397 ;;;###autoload
398 (define-minor-mode image-minor-mode
399 "Toggle Image minor mode.
400 With arg, turn Image minor mode on if arg is positive, off otherwise.
401 It provides the key \\<image-mode-map>\\[image-toggle-display] \
402 to switch back to `image-mode'
403 to display an image file as the actual image."
404 nil (:eval (if image-type (format " Image[%s]" image-type) " Image"))
405 image-minor-mode-map
406 :group 'image
407 :version "22.1"
408 (if image-minor-mode
409 (add-hook 'change-major-mode-hook (lambda () (image-minor-mode -1)) nil t)))
411 ;;;###autoload
412 (defun image-mode-as-text ()
413 "Set a non-image mode as major mode in combination with image minor mode.
414 A non-image major mode found from `auto-mode-alist' or Fundamental mode
415 displays an image file as text. `image-minor-mode' provides the key
416 \\<image-mode-map>\\[image-toggle-display] to switch back to `image-mode'
417 to display an image file as the actual image.
419 You can use `image-mode-as-text' in `auto-mode-alist' when you want
420 to display an image file as text initially.
422 See commands `image-mode' and `image-minor-mode' for more information
423 on these modes."
424 (interactive)
425 ;; image-mode-as-text = normal-mode + image-minor-mode
426 (let ((previous-image-type image-type)) ; preserve `image-type'
427 (if image-mode-previous-major-mode
428 ;; Restore previous major mode that was already found by this
429 ;; function and cached in `image-mode-previous-major-mode'
430 (funcall image-mode-previous-major-mode)
431 (let ((auto-mode-alist
432 (delq nil (mapcar
433 (lambda (elt)
434 (unless (memq (or (car-safe (cdr elt)) (cdr elt))
435 '(image-mode image-mode-maybe image-mode-as-text))
436 elt))
437 auto-mode-alist)))
438 (magic-fallback-mode-alist
439 (delq nil (mapcar
440 (lambda (elt)
441 (unless (memq (or (car-safe (cdr elt)) (cdr elt))
442 '(image-mode image-mode-maybe image-mode-as-text))
443 elt))
444 magic-fallback-mode-alist))))
445 (normal-mode)
446 (set (make-local-variable 'image-mode-previous-major-mode) major-mode)))
447 ;; Restore `image-type' after `kill-all-local-variables' in `normal-mode'.
448 (setq image-type previous-image-type)
449 ;; Enable image minor mode with `C-c C-c'.
450 (image-minor-mode 1)
451 ;; Show the image file as text.
452 (image-toggle-display-text)
453 (message "%s" (concat
454 (substitute-command-keys
455 "Type \\[image-toggle-display] to view the image as ")
456 (if (image-get-display-property)
457 "text" "an image") "."))))
459 (define-obsolete-function-alias 'image-mode-maybe 'image-mode "23.2")
461 (defun image-toggle-display-text ()
462 "Show the image file as text.
463 Remove text properties that display the image."
464 (let ((inhibit-read-only t)
465 (buffer-undo-list t)
466 (modified (buffer-modified-p)))
467 (remove-list-of-text-properties (point-min) (point-max)
468 '(display intangible read-nonsticky
469 read-only front-sticky))
470 (set-buffer-modified-p modified)
471 (if (called-interactively-p 'any)
472 (message "Repeat this command to go back to displaying the image"))))
474 (defvar archive-superior-buffer)
475 (defvar tar-superior-buffer)
476 (declare-function image-flush "image.c" (spec &optional frame))
478 (defun image-toggle-display-image ()
479 "Show the image of the image file.
480 Turn the image data into a real image, but only if the whole file
481 was inserted."
482 (let* ((filename (buffer-file-name))
483 (data-p (not (and filename
484 (file-readable-p filename)
485 (not (file-remote-p filename))
486 (not (buffer-modified-p))
487 (not (and (boundp 'archive-superior-buffer)
488 archive-superior-buffer))
489 (not (and (boundp 'tar-superior-buffer)
490 tar-superior-buffer)))))
491 (file-or-data (if data-p
492 (string-make-unibyte
493 (buffer-substring-no-properties (point-min) (point-max)))
494 filename))
495 (type (image-type file-or-data nil data-p))
496 (image (create-animated-image file-or-data type data-p))
497 (props
498 `(display ,image
499 intangible ,image
500 rear-nonsticky (display intangible)
501 read-only t front-sticky (read-only)))
502 (inhibit-read-only t)
503 (buffer-undo-list t)
504 (modified (buffer-modified-p)))
505 (image-flush image)
506 (let ((buffer-file-truename nil)) ; avoid changing dir mtime by lock_file
507 (add-text-properties (point-min) (point-max) props)
508 (restore-buffer-modified-p modified))
509 ;; Inhibit the cursor when the buffer contains only an image,
510 ;; because cursors look very strange on top of images.
511 (setq cursor-type nil)
512 ;; This just makes the arrow displayed in the right fringe
513 ;; area look correct when the image is wider than the window.
514 (setq truncate-lines t)
515 ;; Allow navigation of large images
516 (set (make-local-variable 'auto-hscroll-mode) nil)
517 (setq image-type type)
518 (if (eq major-mode 'image-mode)
519 (setq mode-name (format "Image[%s]" type)))
520 (if (called-interactively-p 'any)
521 (message "Repeat this command to go back to displaying the file as text"))))
523 (defun image-toggle-display ()
524 "Start or stop displaying an image file as the actual image.
525 This command toggles between `image-mode-as-text' showing the text of
526 the image file and `image-mode' showing the image as an image."
527 (interactive)
528 (if (image-get-display-property)
529 (image-mode-as-text)
530 (image-mode)))
532 (defun image-after-revert-hook ()
533 (when (image-get-display-property)
534 (image-toggle-display-text)
535 ;; Update image display.
536 (redraw-frame (selected-frame))
537 (image-toggle-display-image)))
540 ;;; Support for bookmark.el
541 (declare-function bookmark-make-record-default
542 "bookmark" (&optional no-file no-context posn))
543 (declare-function bookmark-prop-get "bookmark" (bookmark prop))
544 (declare-function bookmark-default-handler "bookmark" (bmk))
546 (defun image-bookmark-make-record ()
547 `(,@(bookmark-make-record-default nil 'no-context 0)
548 (image-type . ,image-type)
549 (handler . image-bookmark-jump)))
551 ;;;###autoload
552 (defun image-bookmark-jump (bmk)
553 ;; This implements the `handler' function interface for record type
554 ;; returned by `bookmark-make-record-function', which see.
555 (prog1 (bookmark-default-handler bmk)
556 (when (not (string= image-type (bookmark-prop-get bmk 'image-type)))
557 (image-toggle-display))))
559 (provide 'image-mode)
561 ;; arch-tag: b5b2b7e6-26a7-4b79-96e3-1546b5c4c6cb
562 ;;; image-mode.el ends here