Commit | Line | Data |
---|---|---|
7840ced1 GM |
1 | ;;; image.el --- image API |
2 | ||
3 | ;; Copyright (C) 1998 Free Software Foundation, Inc. | |
04799cf5 | 4 | ;; Keywords: multimedia |
7840ced1 GM |
5 | |
6 | ;; This file is part of GNU Emacs. | |
7 | ||
8 | ;; GNU Emacs is free software; you can redistribute it and/or modify | |
9 | ;; it under the terms of the GNU General Public License as published by | |
10 | ;; the Free Software Foundation; either version 2, or (at your option) | |
11 | ;; any later version. | |
12 | ||
13 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
14 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
16 | ;; GNU General Public License for more details. | |
17 | ||
18 | ;; You should have received a copy of the GNU General Public License | |
19 | ;; along with GNU Emacs; see the file COPYING. If not, write to the | |
20 | ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
21 | ;; Boston, MA 02111-1307, USA. | |
22 | ||
23 | ;;; Commentary: | |
24 | ||
25 | ;;; Code: | |
26 | ||
27 | (defconst image-type-regexps | |
28 | '(("^/\\*.*XPM.\\*/" . xpm) | |
29 | ("^P[1-6]" . pbm) | |
30 | ("^GIF8" . gif) | |
31 | ("JFIF" . jpeg) | |
32 | ("^\211PNG\r\n" . png) | |
33 | ("^#define" . xbm) | |
34 | ("^\\(MM\0\\*\\)\\|\\(II\\*\0\\)" . tiff) | |
35 | ("^%!PS" . ghostscript)) | |
36 | "Alist of (REGEXP . IMAGE-TYPE) pairs used to auto-detect image types. | |
37 | When the first bytes of an image file match REGEXP, it is assumed to | |
38 | be of image type IMAGE-TYPE.") | |
39 | ||
40 | ||
41 | ;;;###autoload | |
42 | (defun image-type-from-file-header (file) | |
43 | "Determine the type of image file FILE from its first few bytes. | |
44 | Value is a symbol specifying the image type, or nil if type cannot | |
45 | be determined." | |
46 | (unless (file-name-directory file) | |
47 | (setq file (concat data-directory file))) | |
48 | (setq file (expand-file-name file)) | |
49 | (let ((header (with-temp-buffer | |
50 | (insert-file-contents-literally file nil 0 256) | |
51 | (buffer-string))) | |
52 | (types image-type-regexps) | |
53 | type) | |
54 | (while (and types (null type)) | |
55 | (let ((regexp (car (car types))) | |
56 | (image-type (cdr (car types)))) | |
57 | (when (string-match regexp header) | |
58 | (setq type image-type)) | |
59 | (setq types (cdr types)))) | |
60 | type)) | |
61 | ||
62 | ||
63 | ;;;###autoload | |
64 | (defun image-type-available-p (type) | |
65 | "Value is non-nil if image type TYPE is available. | |
66 | Image types are symbols like `xbm' or `jpeg'." | |
67 | (not (null (memq type image-types)))) | |
68 | ||
69 | ||
70 | ;;;###autoload | |
71 | (defun create-image (file &optional type &rest props) | |
72 | "Create an image which will be loaded from FILE. | |
73 | Optional TYPE is a symbol describing the image type. If TYPE is omitted | |
74 | or nil, try to determine the image file type from its first few bytes. | |
75 | If that doesn't work, use FILE's extension.as image type. | |
76 | Optional PROPS are additional image attributes to assign to the image, | |
77 | like, e.g. `:heuristic-mask t'. | |
78 | Value is the image created, or nil if images of type TYPE are not supported." | |
79 | (unless (stringp file) | |
80 | (error "Invalid image file name %s" file)) | |
81 | (unless (or type | |
82 | (setq type (image-type-from-file-header file))) | |
83 | (let ((extension (file-name-extension file))) | |
84 | (unless extension | |
85 | (error "Cannot determine image type")) | |
86 | (setq type (intern extension)))) | |
87 | (unless (symbolp type) | |
88 | (error "Invalid image type %s" type)) | |
89 | (when (image-type-available-p type) | |
90 | (append (list 'image :type type :file file) props))) | |
91 | ||
92 | ||
93 | ;;;###autoload | |
1571b5ff GM |
94 | (defun put-image (image pos &optional area) |
95 | "Put image IMAGE in front of POS in the current buffer. | |
7840ced1 GM |
96 | IMAGE must be an image created with `create-image' or `defimage'. |
97 | POS may be an integer or marker. | |
7840ced1 GM |
98 | AREA is where to display the image. AREA nil or omitted means |
99 | display it in the text area, a value of `left-margin' means | |
100 | display it in the left marginal area, a value of `right-margin' | |
101 | means display it in the right marginal area. | |
1571b5ff | 102 | IMAGE is displayed by putting an overlay into the current buffer with a |
7840ced1 GM |
103 | `before-string' that has a `display' property whose value is the |
104 | image." | |
1571b5ff GM |
105 | (let ((buffer (current-buffer))) |
106 | (unless (eq (car image) 'image) | |
107 | (error "Not an image: %s" image)) | |
108 | (unless (or (null area) (memq area '(left-margin right-margin))) | |
109 | (error "Invalid area %s" area)) | |
110 | (let ((overlay (make-overlay pos pos buffer)) | |
111 | (string (make-string 1 ?x)) | |
112 | (prop (if (null area) image (cons area image)))) | |
113 | (put-text-property 0 1 'display prop string) | |
114 | (overlay-put overlay 'put-image t) | |
115 | (overlay-put overlay 'before-string string)))) | |
7840ced1 GM |
116 | |
117 | ||
118 | ;;;###autoload | |
119 | (defun insert-image (image &optional area) | |
120 | "Insert IMAGE into current buffer at point. | |
121 | AREA is where to display the image. AREA nil or omitted means | |
122 | display it in the text area, a value of `left-margin' means | |
123 | display it in the left marginal area, a value of `right-margin' | |
124 | means display it in the right marginal area. | |
125 | IMAGE is displayed by inserting an \"x\" into the current buffer | |
126 | having a `display' property whose value is the image." | |
127 | (unless (eq (car image) 'image) | |
128 | (error "Not an image: %s" image)) | |
129 | (unless (or (null area) (memq area '(left-margin right-margin))) | |
130 | (error "Invalid area %s" area)) | |
131 | (insert "x") | |
132 | (add-text-properties (1- (point)) (point) | |
133 | (list 'display (if (null area) image (cons area image)) | |
134 | 'rear-nonsticky (list 'display)))) | |
135 | ||
136 | ||
137 | ;;;###autoload | |
138 | (defun remove-images (start end &optional buffer) | |
139 | "Remove images between START and END in BUFFER. | |
140 | Remove only images that were put in BUFFER with calls to `put-image'. | |
141 | BUFFER nil or omitted means use the current buffer." | |
142 | (unless buffer | |
143 | (setq buffer (current-buffer))) | |
144 | (let ((overlays (overlays-in start end))) | |
145 | (while overlays | |
146 | (let ((overlay (car overlays))) | |
147 | (when (overlay-get overlay 'put-image) | |
148 | (delete-overlay overlay) | |
149 | (setq overlays (cdr overlays))))))) | |
150 | ||
151 | ||
152 | ;;;###autoload | |
153 | (defmacro defimage (symbol specs &optional doc) | |
154 | "Define SYMBOL as an image. | |
155 | ||
156 | SPECS is a list of image specifications. DOC is an optional | |
157 | documentation string. | |
158 | ||
159 | Each image specification in SPECS is a property list. The contents of | |
160 | a specification are image type dependent. All specifications must at | |
161 | least contain the properties `:type TYPE' and `:file FILE', where TYPE | |
162 | is a symbol specifying the image type, e.g. `xbm', and FILE is the | |
163 | file to load the image from. The first image specification whose TYPE | |
164 | is supported, and FILE exists, is used to define SYMBOL. | |
165 | ||
166 | Example: | |
167 | ||
168 | (defimage test-image ((:type xpm :file \"~/test1.xpm\") | |
169 | (:type xbm :file \"~/test1.xbm\")))" | |
170 | (let (image) | |
171 | (while (and specs (null image)) | |
172 | (let* ((spec (car specs)) | |
173 | (type (plist-get spec :type)) | |
174 | (file (plist-get spec :file))) | |
175 | (when (and (image-type-available-p type) (stringp file)) | |
176 | (setq file (expand-file-name file)) | |
177 | (unless (file-name-absolute-p file) | |
178 | (setq file (concat data-directory "/" file))) | |
179 | (when (file-exists-p file) | |
180 | (setq image (cons 'image spec)))) | |
181 | (setq specs (cdr specs)))) | |
182 | `(defvar ,symbol ',image ,doc))) | |
183 | ||
184 | ||
185 | (provide 'image) | |
186 | ||
187 | ;; image.el ends here. | |
188 | ||
189 | ||
190 | ||
191 |