50.2.1 Image Specifiers

An image specifier is a description of the actual graphical realization of a glyph. For example, a typical image description is the file system path to a PNG file. Since redisplay doesn’t know about files, and in any case the image may need to be manipulated (e.g., a face’s background pixmap must be clipped and tiled), the PNG file must be converted internally to a window system bitmap or pixmap object.

We describe this process by writing that when SXEmacs displays the image, it instantiates the image instantiator into an image instance. Image instances are an internal object type (similar to font instances and color instances), describing how the image appears in a particular domain. On the other hand, image instantiators, which are just descriptions of how the image should appear, are represented using Lisp strings or vectors.

Furthermore the graphical realization will vary, and for some devices may not even be a bitmapped graphic. These variations may be controlled by the program by specifying different image instantiators in different locales. This is implemented with an image specifier, a specifier whose specifications are image instantiators.

Image specifiers are rarely if ever found by themselves. However, an image specifier results from calling glyph-image on a glyph, or retrieving the background-pixmap property of a face, and you can check if some random object is an image specifier.

Function: image-specifier-p object

This function returns non-nil if object is an image specifier.

Function: make-image-specifier spec-list

This function creates a new image specifier object and initializes it according to spec-list. See Specifiers.

This function exists mainly for completeness. In practice, you rarely, if ever, need to actually create an image specifier. Instead, they are implicitly created by the initialization of glyphs and faces, and the specifier member of these objects cannot be changed after initialization; you may only set the specifications it contains.

Image instantiators come in many formats: xbm, xpm, gif, jpeg, etc. These denote the format of the data describing the image. The resulting image instances also come in many types—mono-pixmap, color-pixmap, text, pointer, etc. This refers to the behavior of the image and the sorts of places it can appear.

For example, a color-pixmap image has fixed colors specified for it, while a mono-pixmap image comes in two unspecified shades “foreground” and “background” that are determined from the face of the glyph or surrounding text; a text image appears as a string of text and has an unspecified foreground, background, and font; a pointer image behaves like a mono-pixmap image but can only be used as a mouse pointer [mono-pixmap images cannot be used as mouse pointers]; etc.

It is important to keep the distinction between image instantiator format and image instance type in mind. Typically, a given image instantiator format can result in many different image instance types.

For example, xpm can be instanced as color-pixmap, mono-pixmap, or pointer; whereas cursor-font can be instanced only as pointer. On the other hand, a particular image instance type can be generated by many different image instantiator formats (e.g. color-pixmap can be generated by xpm, gif, jpeg, etc.).

See Image Instances, for a more detailed discussion of image instance types.

An image instantiator should be a string or a vector of the form

 [format :keyword value ...]

i.e. a format symbol followed by zero or more alternating keyword-value pairs.

The form of an instantiator can be checked with valid-instantiator-p with a TYPE of image, Specifier Validation Functions.

For a complete list of the format symbols and their usage, Image Instantiator Formats.

If the instantiator is a string, it will be converted into a vector by looking it up according to the specs in the console-type-image-conversion-list for the console type of the domain (usually a window; sometimes a frame or device) over which the image is being instantiated.

If the instantiator specifies data from a file, the data will be read in at the time that the instantiator is added to the image specifier (which may be well before the image is actually displayed), and the instantiator will be converted into one of the inline-data forms, with the filename retained using a :file keyword. This implies that the file must exist when the instantiator is added to the image, but does not need to exist at any other time (e.g. it may safely be a temporary file).

The available keywords are given below. Note that some keywords are generally available (for example, the :data keyword may be used with any format except nothing), while others are only available for one format.

:data

Inline image data. If available for a given format, it may be specified directly by the program, or it may be a cache of file data previously read. When present, it is used to instantiate the image in preference to the file named by the :file property.

The format of inline data is image-format-specific. For example, in pixmap formats, the value should be a string, which is interpreted as an octet-stream representing a bitmap or pixmap. But for text formats, it’s string containing the text to be displayed, and for resource formats, it’s a string containing the name of the resource.

:file

Data contained in a file. The value is the name of this file. If both :data and :file are specified, the image is created from what is specified in :data and the string in :file becomes the value of the image-instance-file-name function when applied to the resulting image-instance. Note that there is nothing to stop a program from changing either the :file or the :data property, and there is no way to detect such mischief. This means that the data will not be automatically reread if you change the file property; you must force it by removing the :data property. (One way to do this is replacing the whole specification with a new vector.) This keyword is not valid for instantiator formats nothing, string, formatted-string, cursor-font, font, and autodetect.

:mask-data

Inline data for xbm and xface. This specifies a mask to be used with the bitmap. Pixels which are not set in the mask will not be written to the imaging device. The format is a list of width, height, and bits, as for :data.

:mask-file

For xbm and xface. This specifies a file containing the mask data. If neither a mask file nor inline mask data is given for an XBM image, and the XBM image comes from a file, XEmacs will look for a mask file with the same name as the image file but with ‘Mask’ or ‘msk’ appended. For example, if you specify the XBM file left_ptr [usually located in /usr/include/X11/bitmaps], the associated mask file left_ptrmsk will automatically be picked up.

:resource-id

Only for mswindows-resource. This must be either an integer (which directly specifies a resource number) or a string. See the description of mswindows-resource for valid strings. See Image Instantiator Formats.

:foreground

:background

For xbm, xface, cursor-font, and font. These keywords allow you to explicitly specify foreground and background colors. The value should be anything acceptable to make-color-instance. This will cause an external format that would by default be instantiated as a mono-pixmap to instead be instantiated as a two-color color-pixmap. This can be used to override the colors specified by a glyph’s face, for example. If the image is instantiated as a pointer, they specify its foreground and/or background, instead of the defaults of black and white.

:hotspot-x

:hotspot-y

For xbm and xface. These keywords specify a hotspot if the image is instantiated as a pointer. Note that if the XBM image file specifies a hotspot, it will automatically be picked up if no explicit hotspot is given.

:color-symbols

Only for xpm. This specifies an alist that maps strings that specify symbolic color names to the actual color to be used for that symbolic color (in the form of a string or a color-specifier object). If this is not specified, the contents of xpm-color-symbols are used to generate the alist.

:face

For inherit and the widget formats. This specifies the face to inherit from. For widgets this specifies the face to use for display. It defaults to gui-element-face.

:selected

:active

:suffix

:keys

:style

:filter

:config

:included

:key-sequence

:accelerator

:label

:callback

These keywords, accepted as menu item specs, are also accepted by images instantiated as widget. For their semantics, Menu Format.