elisp: Defining Images
37.17.8 Defining Images
-----------------------
The functions ‘create-image’, ‘defimage’ and ‘find-image’ provide
convenient ways to create image descriptors.
-- Function: create-image file-or-data &optional type data-p &rest
props
This function creates and returns an image descriptor which uses
the data in FILE-OR-DATA. FILE-OR-DATA can be a file name or a
string containing the image data; DATA-P should be ‘nil’ for the
former case, non-‘nil’ for the latter case.
The optional argument TYPE is a symbol specifying the image type.
If TYPE is omitted or ‘nil’, ‘create-image’ tries to determine the
image type from the file’s first few bytes, or else from the file’s
name.
The remaining arguments, PROPS, specify additional image
properties—for example,
(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
The function returns ‘nil’ if images of this type are not
supported. Otherwise it returns an image descriptor.
-- Macro: defimage symbol specs &optional doc
This macro defines SYMBOL as an image name. The arguments SPECS is
a list which specifies how to display the image. The third
argument, DOC, is an optional documentation string.
Each argument in SPECS has the form of a property list, and each
one should specify at least the ‘:type’ property and either the
‘:file’ or the ‘:data’ property. The value of ‘:type’ should be a
symbol specifying the image type, the value of ‘:file’ is the file
to load the image from, and the value of ‘:data’ is a string
containing the actual image data. Here is an example:
(defimage test-image
((:type xpm :file "~/test1.xpm")
(:type xbm :file "~/test1.xbm")))
‘defimage’ tests each argument, one by one, to see if it is
usable—that is, if the type is supported and the file exists. The
first usable argument is used to make an image descriptor which is
stored in SYMBOL.
If none of the alternatives will work, then SYMBOL is defined as
‘nil’.
-- Function: find-image specs
This function provides a convenient way to find an image satisfying
one of a list of image specifications SPECS.
Each specification in SPECS is a property list with contents
depending on image type. All specifications must at least contain
the properties ‘:type TYPE’ and either ‘:file FILE’ or
‘:data DATA’, where TYPE is a symbol specifying the image type,
e.g., ‘xbm’, FILE is the file to load the image from, and DATA is a
string containing the actual image data. The first specification
in the list whose TYPE is supported, and FILE exists, is used to
construct the image specification to be returned. If no
specification is satisfied, ‘nil’ is returned.
The image is looked for in ‘image-load-path’.
-- User Option: image-load-path
This variable’s value is a list of locations in which to search for
image files. If an element is a string or a variable symbol whose
value is a string, the string is taken to be the name of a
directory to search. If an element is a variable symbol whose
value is a list, that is taken to be a list of directory names to
search.
The default is to search in the ‘images’ subdirectory of the
directory specified by ‘data-directory’, then the directory
specified by ‘data-directory’, and finally in the directories in
‘load-path’. Subdirectories are not automatically included in the
search, so if you put an image file in a subdirectory, you have to
supply the subdirectory name explicitly. For example, to find the
image ‘images/foo/bar.xpm’ within ‘data-directory’, you should
specify the image as follows:
(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
-- Function: image-load-path-for-library library image &optional path
no-error
This function returns a suitable search path for images used by the
Lisp package LIBRARY.
The function searches for IMAGE first using ‘image-load-path’,
excluding ‘data-directory/images’, and then in ‘load-path’,
followed by a path suitable for LIBRARY, which includes
‘../../etc/images’ and ‘../etc/images’ relative to the library file
itself, and finally in ‘data-directory/images’.
Then this function returns a list of directories which contains
first the directory in which IMAGE was found, followed by the value
of ‘load-path’. If PATH is given, it is used instead of
‘load-path’.
If NO-ERROR is non-‘nil’ and a suitable path can’t be found, don’t
signal an error. Instead, return a list of directories as before,
except that ‘nil’ appears in place of the image directory.
Here is an example of using ‘image-load-path-for-library’:
(defvar image-load-path) ; shush compiler
(let* ((load-path (image-load-path-for-library
"mh-e" "mh-logo.xpm"))
(image-load-path (cons (car load-path)
image-load-path)))
(mh-tool-bar-folder-buttons-init))
Info Catalog
elisp: Other Image Types
elisp: Images
elisp: Showing Images