annotate lisp/image.el @ 38580:446aa2cd256e

More information about how to find the Meta keys.
author Eli Zaretskii <eliz@gnu.org>
date Thu, 26 Jul 2001 15:43:08 +0000
parents b7bd53c4820a
children 00a56d6da660
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
1 ;;; image.el --- image API
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
2
37035
b7bd53c4820a (image-type-regexps): Change type for PS files
Gerd Moellmann <gerd@gnu.org>
parents: 34378
diff changeset
3 ;; Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
25309
6842eb73559c Add Keywords.
Dave Love <fx@gnu.org>
parents: 25003
diff changeset
4 ;; Keywords: multimedia
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
5
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
6 ;; This file is part of GNU Emacs.
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
7
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
8 ;; GNU Emacs is free software; you can redistribute it and/or modify
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
9 ;; it under the terms of the GNU General Public License as published by
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
10 ;; the Free Software Foundation; either version 2, or (at your option)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
11 ;; any later version.
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
12
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
13 ;; GNU Emacs is distributed in the hope that it will be useful,
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
16 ;; GNU General Public License for more details.
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
17
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
18 ;; You should have received a copy of the GNU General Public License
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
19 ;; along with GNU Emacs; see the file COPYING. If not, write to the
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
20 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
21 ;; Boston, MA 02111-1307, USA.
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
22
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
23 ;;; Commentary:
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
24
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
25 ;;; Code:
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
26
32166
e3be69cf6c81 (image): New group.
Miles Bader <miles@gnu.org>
parents: 31635
diff changeset
27
e3be69cf6c81 (image): New group.
Miles Bader <miles@gnu.org>
parents: 31635
diff changeset
28 (defgroup image ()
e3be69cf6c81 (image): New group.
Miles Bader <miles@gnu.org>
parents: 31635
diff changeset
29 "Image support."
e3be69cf6c81 (image): New group.
Miles Bader <miles@gnu.org>
parents: 31635
diff changeset
30 :group 'multimedia)
e3be69cf6c81 (image): New group.
Miles Bader <miles@gnu.org>
parents: 31635
diff changeset
31
e3be69cf6c81 (image): New group.
Miles Bader <miles@gnu.org>
parents: 31635
diff changeset
32
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
33 (defconst image-type-regexps
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
34 '(("^/\\*.*XPM.\\*/" . xpm)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
35 ("^P[1-6]" . pbm)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
36 ("^GIF8" . gif)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
37 ("JFIF" . jpeg)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
38 ("^\211PNG\r\n" . png)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
39 ("^#define" . xbm)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
40 ("^\\(MM\0\\*\\)\\|\\(II\\*\0\\)" . tiff)
37035
b7bd53c4820a (image-type-regexps): Change type for PS files
Gerd Moellmann <gerd@gnu.org>
parents: 34378
diff changeset
41 ("^%!PS" . postscript))
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
42 "Alist of (REGEXP . IMAGE-TYPE) pairs used to auto-detect image types.
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
43 When the first bytes of an image file match REGEXP, it is assumed to
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
44 be of image type IMAGE-TYPE.")
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
45
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
46
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
47 ;;;###autoload
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
48 (defun image-type-from-data (data)
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
49 "Determine the image type from image data DATA.
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
50 Value is a symbol specifying the image type or nil if type cannot
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
51 be determined."
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
52 (let ((types image-type-regexps)
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
53 type)
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
54 (while (and types (null type))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
55 (let ((regexp (car (car types)))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
56 (image-type (cdr (car types))))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
57 (when (string-match regexp data)
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
58 (setq type image-type))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
59 (setq types (cdr types))))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
60 type))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
61
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
62
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
63 ;;;###autoload
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
64 (defun image-type-from-file-header (file)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
65 "Determine the type of image file FILE from its first few bytes.
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
66 Value is a symbol specifying the image type, or nil if type cannot
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
67 be determined."
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
68 (unless (file-name-directory file)
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
69 (setq file (expand-file-name file data-directory)))
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
70 (setq file (expand-file-name file))
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
71 (let ((header (with-temp-buffer
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
72 (insert-file-contents-literally file nil 0 256)
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
73 (buffer-string))))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
74 (image-type-from-data header)))
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
75
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
76
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
77 ;;;###autoload
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
78 (defun image-type-available-p (type)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
79 "Value is non-nil if image type TYPE is available.
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
80 Image types are symbols like `xbm' or `jpeg'."
28958
56c76b64f321 (image-type-available-p): Don't reference image-types
Eli Zaretskii <eliz@gnu.org>
parents: 28721
diff changeset
81 (and (boundp 'image-types) (not (null (memq type image-types)))))
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
82
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
83
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
84 ;;;###autoload
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
85 (defun create-image (file-or-data &optional type data-p &rest props)
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
86 "Create an image.
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
87 FILE-OR-DATA is an image file name or image data.
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
88 Optional TYPE is a symbol describing the image type. If TYPE is omitted
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
89 or nil, try to determine the image type from its first few bytes
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
90 of image data. If that doesn't work, and FILE-OR-DATA is a file name,
34378
5ae7af279df7 (create-image): Doc fix; spotted by Per Cederqvist <ceder@lysator.liu.se>.
Eli Zaretskii <eliz@gnu.org>
parents: 32166
diff changeset
91 use its file extension as image type.
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
92 Optional DATA-P non-nil means FILE-OR-DATA is a string containing image data.
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
93 Optional PROPS are additional image attributes to assign to the image,
31635
208d8385ccae (create-image): Doc fix.
Gerd Moellmann <gerd@gnu.org>
parents: 30952
diff changeset
94 like, e.g. `:mask MASK'.
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
95 Value is the image created, or nil if images of type TYPE are not supported."
27075
893ec72bd6b1 (create-image, defimage): Don't assume image data is a
Gerd Moellmann <gerd@gnu.org>
parents: 27073
diff changeset
96 (when (and (not data-p) (not (stringp file-or-data)))
893ec72bd6b1 (create-image, defimage): Don't assume image data is a
Gerd Moellmann <gerd@gnu.org>
parents: 27073
diff changeset
97 (error "Invalid image file name `%s'" file-or-data))
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
98 (cond ((null data-p)
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
99 ;; FILE-OR-DATA is a file name.
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
100 (unless (or type
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
101 (setq type (image-type-from-file-header file-or-data)))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
102 (let ((extension (file-name-extension file-or-data)))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
103 (unless extension
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
104 (error "Cannot determine image type"))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
105 (setq type (intern extension)))))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
106 (t
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
107 ;; FILE-OR-DATA contains image data.
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
108 (unless type
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
109 (setq type (image-type-from-data file-or-data)))))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
110 (unless type
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
111 (error "Cannot determine image type"))
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
112 (unless (symbolp type)
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
113 (error "Invalid image type `%s'" type))
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
114 (when (image-type-available-p type)
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
115 (append (list 'image :type type (if data-p :data :file) file-or-data)
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
116 props)))
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
117
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
118
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
119 ;;;###autoload
29470
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
120 (defun put-image (image pos &optional string area)
25617
697b28471784 (put-image): Remove optional buffer parameter.
Gerd Moellmann <gerd@gnu.org>
parents: 25309
diff changeset
121 "Put image IMAGE in front of POS in the current buffer.
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
122 IMAGE must be an image created with `create-image' or `defimage'.
25816
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
123 IMAGE is displayed by putting an overlay into the current buffer with a
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
124 `before-string' STRING that has a `display' property whose value is the
29470
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
125 image. STRING is defaulted if you omit it.
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
126 POS may be an integer or marker.
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
127 AREA is where to display the image. AREA nil or omitted means
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
128 display it in the text area, a value of `left-margin' means
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
129 display it in the left marginal area, a value of `right-margin'
25816
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
130 means display it in the right marginal area."
29626
ecb96a7369d3 Fix last change to be in insert-image as intended.
Dave Love <fx@gnu.org>
parents: 29624
diff changeset
131 (unless string (setq string "x"))
25617
697b28471784 (put-image): Remove optional buffer parameter.
Gerd Moellmann <gerd@gnu.org>
parents: 25309
diff changeset
132 (let ((buffer (current-buffer)))
29470
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
133 (unless (eq (car-safe image) 'image)
25617
697b28471784 (put-image): Remove optional buffer parameter.
Gerd Moellmann <gerd@gnu.org>
parents: 25309
diff changeset
134 (error "Not an image: %s" image))
697b28471784 (put-image): Remove optional buffer parameter.
Gerd Moellmann <gerd@gnu.org>
parents: 25309
diff changeset
135 (unless (or (null area) (memq area '(left-margin right-margin)))
697b28471784 (put-image): Remove optional buffer parameter.
Gerd Moellmann <gerd@gnu.org>
parents: 25309
diff changeset
136 (error "Invalid area %s" area))
25816
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
137 (setq string (copy-sequence string))
25617
697b28471784 (put-image): Remove optional buffer parameter.
Gerd Moellmann <gerd@gnu.org>
parents: 25309
diff changeset
138 (let ((overlay (make-overlay pos pos buffer))
25816
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
139 (prop (if (null area) image (list (list 'margin area) image))))
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
140 (put-text-property 0 (length string) 'display prop string)
25617
697b28471784 (put-image): Remove optional buffer parameter.
Gerd Moellmann <gerd@gnu.org>
parents: 25309
diff changeset
141 (overlay-put overlay 'put-image t)
697b28471784 (put-image): Remove optional buffer parameter.
Gerd Moellmann <gerd@gnu.org>
parents: 25309
diff changeset
142 (overlay-put overlay 'before-string string))))
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
143
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
144
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
145 ;;;###autoload
29470
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
146 (defun insert-image (image &optional string area)
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
147 "Insert IMAGE into current buffer at point.
25816
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
148 IMAGE is displayed by inserting STRING into the current buffer
29470
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
149 with a `display' property whose value is the image. STRING is
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
150 defaulted if you omit it.
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
151 AREA is where to display the image. AREA nil or omitted means
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
152 display it in the text area, a value of `left-margin' means
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
153 display it in the left marginal area, a value of `right-margin'
25816
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
154 means display it in the right marginal area."
29626
ecb96a7369d3 Fix last change to be in insert-image as intended.
Dave Love <fx@gnu.org>
parents: 29624
diff changeset
155 ;; Use a space as least likely to cause trouble when it's a hidden
ecb96a7369d3 Fix last change to be in insert-image as intended.
Dave Love <fx@gnu.org>
parents: 29624
diff changeset
156 ;; character in the buffer.
ecb96a7369d3 Fix last change to be in insert-image as intended.
Dave Love <fx@gnu.org>
parents: 29624
diff changeset
157 (unless string (setq string " "))
29470
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
158 (unless (eq (car-safe image) 'image)
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
159 (error "Not an image: %s" image))
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
160 (unless (or (null area) (memq area '(left-margin right-margin)))
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
161 (error "Invalid area %s" area))
29607
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
162 (if area
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
163 (setq image (list (list 'margin area) image))
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
164 ;; Cons up a new spec equal but not eq to `image' so that
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
165 ;; inserting it twice in a row (adjacently) displays two copies of
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
166 ;; the image. Don't try to avoid this by looking at the display
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
167 ;; properties on either side so that we DTRT more often with
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
168 ;; cut-and-paste. (Yanking killed image text next to another copy
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
169 ;; of it loses anyway.)
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
170 (setq image (cons 'image (cdr image))))
25816
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
171 (let ((start (point)))
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
172 (insert string)
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
173 (add-text-properties start (point)
29607
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
174 (list 'display image
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
175 ;; `image' has the right properties to
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
176 ;; mark an intangible field.
42d156d8d8eb (insert-image): Save a little consing.
Dave Love <fx@gnu.org>
parents: 29470
diff changeset
177 'intangible image
25816
2d53a03a3baa (put-image, insert-image): Add string argument.
Gerd Moellmann <gerd@gnu.org>
parents: 25617
diff changeset
178 'rear-nonsticky (list 'display)))))
26007
774b2504710b (insert-image): Copy the image spec and add an intangible property.
Dave Love <fx@gnu.org>
parents: 25872
diff changeset
179
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
180
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
181 ;;;###autoload
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
182 (defun remove-images (start end &optional buffer)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
183 "Remove images between START and END in BUFFER.
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
184 Remove only images that were put in BUFFER with calls to `put-image'.
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
185 BUFFER nil or omitted means use the current buffer."
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
186 (unless buffer
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
187 (setq buffer (current-buffer)))
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
188 (let ((overlays (overlays-in start end)))
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
189 (while overlays
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
190 (let ((overlay (car overlays)))
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
191 (when (overlay-get overlay 'put-image)
25857
fdc2bd91cf63 (defimage): Remove redundant code. Substitute file on image plist.
Dave Love <fx@gnu.org>
parents: 25816
diff changeset
192 (delete-overlay overlay)))
fdc2bd91cf63 (defimage): Remove redundant code. Substitute file on image plist.
Dave Love <fx@gnu.org>
parents: 25816
diff changeset
193 (setq overlays (cdr overlays)))))
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
194
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
195
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
196 ;;;###autoload
28721
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
197 (defun find-image (specs)
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
198 "Find an image, choosing one of a list of image specifications.
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
199
29470
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
200 SPECS is a list of image specifications.
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
201
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
202 Each image specification in SPECS is a property list. The contents of
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
203 a specification are image type dependent. All specifications must at
27059
6bb2a4a0413e * image.el (defimage): Images with the :data keyword should be considered valid as well.
William M. Perry <wmperry@aventail.com>
parents: 26007
diff changeset
204 least contain the properties `:type TYPE' and either `:file FILE' or
6bb2a4a0413e * image.el (defimage): Images with the :data keyword should be considered valid as well.
William M. Perry <wmperry@aventail.com>
parents: 26007
diff changeset
205 `:data DATA', where TYPE is a symbol specifying the image type,
6bb2a4a0413e * image.el (defimage): Images with the :data keyword should be considered valid as well.
William M. Perry <wmperry@aventail.com>
parents: 26007
diff changeset
206 e.g. `xbm', FILE is the file to load the image from, and DATA is a
29470
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
207 string containing the actual image data. The specification whose TYPE
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
208 is supported, and FILE exists, is used to construct the image
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
209 specification to be returned. Return nil if no specification is
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
210 satisfied.
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
211
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
212 The image is looked for first on `load-path' and then in `data-directory'."
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
213 (let (image)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
214 (while (and specs (null image))
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
215 (let* ((spec (car specs))
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
216 (type (plist-get spec :type))
27059
6bb2a4a0413e * image.el (defimage): Images with the :data keyword should be considered valid as well.
William M. Perry <wmperry@aventail.com>
parents: 26007
diff changeset
217 (data (plist-get spec :data))
27921
ea0a2a4f20b7 (defimage): Look for image files in load-path.
Gerd Moellmann <gerd@gnu.org>
parents: 27075
diff changeset
218 (file (plist-get spec :file))
ea0a2a4f20b7 (defimage): Look for image files in load-path.
Gerd Moellmann <gerd@gnu.org>
parents: 27075
diff changeset
219 found)
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
220 (when (image-type-available-p type)
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
221 (cond ((stringp file)
27921
ea0a2a4f20b7 (defimage): Look for image files in load-path.
Gerd Moellmann <gerd@gnu.org>
parents: 27075
diff changeset
222 (let ((path load-path))
ea0a2a4f20b7 (defimage): Look for image files in load-path.
Gerd Moellmann <gerd@gnu.org>
parents: 27075
diff changeset
223 (while (and (not found) path)
ea0a2a4f20b7 (defimage): Look for image files in load-path.
Gerd Moellmann <gerd@gnu.org>
parents: 27075
diff changeset
224 (let ((try-file (expand-file-name file (car path))))
ea0a2a4f20b7 (defimage): Look for image files in load-path.
Gerd Moellmann <gerd@gnu.org>
parents: 27075
diff changeset
225 (when (file-readable-p try-file)
ea0a2a4f20b7 (defimage): Look for image files in load-path.
Gerd Moellmann <gerd@gnu.org>
parents: 27075
diff changeset
226 (setq found try-file)))
ea0a2a4f20b7 (defimage): Look for image files in load-path.
Gerd Moellmann <gerd@gnu.org>
parents: 27075
diff changeset
227 (setq path (cdr path)))
ea0a2a4f20b7 (defimage): Look for image files in load-path.
Gerd Moellmann <gerd@gnu.org>
parents: 27075
diff changeset
228 (unless found
29470
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
229 (let ((try-file (expand-file-name file data-directory)))
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
230 (if (file-readable-p try-file)
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
231 (setq found try-file))))
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
232 (if found
7bde123bed95 (find-image): Doc fix. Return nil if image not found.
Dave Love <fx@gnu.org>
parents: 28958
diff changeset
233 (setq image
30952
5042a3b24c96 (find-image): Copy `spec' before using plist-put.
Dave Love <fx@gnu.org>
parents: 29626
diff changeset
234 (cons 'image (plist-put (copy-sequence spec)
5042a3b24c96 (find-image): Copy `spec' before using plist-put.
Dave Love <fx@gnu.org>
parents: 29626
diff changeset
235 :file found))))))
27075
893ec72bd6b1 (create-image, defimage): Don't assume image data is a
Gerd Moellmann <gerd@gnu.org>
parents: 27073
diff changeset
236 ((not (null data))
27073
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
237 (setq image (cons 'image spec)))))
aad0a025b1e3 (defimage): Handle specifications containing :data
Gerd Moellmann <gerd@gnu.org>
parents: 27059
diff changeset
238 (setq specs (cdr specs))))
28721
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
239 image))
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
240
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
241
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
242 ;;;###autoload
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
243 (defmacro defimage (symbol specs &optional doc)
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
244 "Define SYMBOL as an image.
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
245
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
246 SPECS is a list of image specifications. DOC is an optional
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
247 documentation string.
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
248
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
249 Each image specification in SPECS is a property list. The contents of
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
250 a specification are image type dependent. All specifications must at
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
251 least contain the properties `:type TYPE' and either `:file FILE' or
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
252 `:data DATA', where TYPE is a symbol specifying the image type,
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
253 e.g. `xbm', FILE is the file to load the image from, and DATA is a
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
254 string containing the actual image data. The first image
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
255 specification whose TYPE is supported, and FILE exists, is used to
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
256 define SYMBOL.
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
257
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
258 Example:
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
259
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
260 (defimage test-image ((:type xpm :file \"~/test1.xpm\")
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
261 (:type xbm :file \"~/test1.xbm\")))"
b4ea18c92e38 (find-image): New function.
Gerd Moellmann <gerd@gnu.org>
parents: 27921
diff changeset
262 `(defvar ,symbol (find-image ',specs) ,doc))
25003
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
263
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
264
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
265 (provide 'image)
bb68fe3c72f8 New file.
Gerd Moellmann <gerd@gnu.org>
parents:
diff changeset
266
25872
6ae50308e8a3 Fix footer comment.
Dave Love <fx@gnu.org>
parents: 25857
diff changeset
267 ;;; image.el ends here