50.2.3 Image Instantiator Formats

The format field of an image instantiator should be a symbol denoting a valid format. Which formats are valid will depend on the features (such as image decoding libraries) available, on platform support, and on the locale.

Function: valid-image-instantiator-format-p format &optional locale

This function returns non-nil if format is a valid image instantiator format.

If locale is non-nil then the format is checked in that locale. If locale is nil the current console is used.

Note that the return value for many formats listed above depends on whether SXEmacs was compiled with support for that format.

Function: image-instantiator-format-list

This function returns a list of valid image-instantiator formats.

Here is a table of image-instantiator formats, giving the keywords that are usable with each, and the kinds of instances that may result.

nothing

Don’t display anything; no keywords are valid for this format. Can only be instanced as nothing.

string

Display this image as a text string. Can only be instanced as text, although support for instancing as mono-pixmap should be added. The valid keyword is :data. The value should be a string, and it is interpreted as a string of characters.

formatted-string

Display this image as a text string with replaceable fields, similar to a modeline format string. The valid keyword is :data. The value should be a string, and it is interpreted as a string of characters containing format sequences.

Not currently implemented.

xbm

An X bitmap; available only if X support was compiled into this XEmacs.

If used in a buffer glyph, icon glyph, or face background pixmap, it will be instantiated as mono-pixmap unless the :foreground or :background keywords are present. In the latter case it will be instantiated as color-pixmap with the two specified colors. (Probably if :foreground or :background is omitted, it defaults to black or white respectively.) If used in a pointer glyph, it will be instantiated as an pointer.

The valid keywords and their values are

:data

A list containing the height and width of the bitmap as integers, and a string interpreted as a bit vector according to the X11 standard XBM bitmap format, in that order.

:file

The name of a file containing standard XBM-format data. If it contains a hotspot specification, it will be parsed and used if the hotspot is not explicitly specified.

:mask-data

A list containing the height and width of the bitmap as integers, and a string interpreted as a bit vector according to the X11 standard XBM bitmap format, in that order. This bitmap is interpreted as the clipping region for the bitmap contained in the :data property.

:mask-file

The name of a file containing standard XBM-format data. Interpreted as the clipping region for the bitmap contained in the :data property.

:foreground

:background

These keywords allow you to explicitly specify foreground and background colors. The values should be acceptable to make-color-instance.

:hotspot-x

:hotspot-y

Integers denoting the hotspot (mouse pointer position), with (0,0) at the top left corner. If given, these override any specification in the XBM file.

xpm

An XPM pixmap; only available if XPM support was compiled into this XEmacs.

Can be instanced as color-pixmap, mono-pixmap, or pointer.

XPM is an add-on library for X that was designed to rectify the shortcomings of the XBM format. Many icons and labels used in the XEmacs GUI are still distributed in XPM format (although we are moving to standardize on the PNG format). It is therefore highly desirable that XPM be available in your SXEmacs.

Most implementations of X include the XPM library as a standard part. If your vendor does not, it is highly recommended that you download it and install it. You can get it from the XEmacs FTP site and mirrors, as well as from most sites that distribute X11.

The valid keywords and their values are

:data

A string interpreted as the contents of a standard XPM file.

:file

The name of a file containing standard XPM-format data. If it contains a hotspot specification, it will be parsed and used if the hotspot is not explicitly specified.

:hotspot-x

:hotspot-y

Integers denoting the hotspot (mouse pointer position), with (0,0) at the top left corner. If given, these override any specification in the XBM file. (This may not be true. The original documentation doesn’t mention them in connection with XPM, but a pointer needs a hotspot.)

:color-symbols

An alist that maps the one- or two-character strings that specify symbolic color names in the XPM file to the actual color to be used for that symbolic color (in the form of a string acceptable as a color instantiator, Color Specifiers, or a color-specifier object). If this is not specified, the contents of xpm-color-symbols are used to generate the alist.

xface

An X-Face bitmap, used to encode people’s faces in e-mail messages; only available if X-Face support was compiled into this SXEmacs.

Will be instanced as mono-pixmap, color-pixmap, or pointer, depending on the target instance type and the presence of color keywords.

The valid keywords and their values are

:data

A list containing the height and width of the bitmap as integers, and a string interpreted as a bit vector according to the X11 standard XBM bitmap format, in that order.

:file

The name of a file containing standard XBM-format data. If it contains a hotspot specification, it will be parsed and used if the hotspot is not explicitly specified.

:mask-data

A list containing the height and width of the bitmap as integers, and a string interpreted as a bit vector according to the X11 standard XBM bitmap format, in that order. This bitmap is interpreted as the clipping region for the bitmap contained in the :data property.

:mask-file

The name of a file containing standard XBM-format data. Interpreted as the clipping region for the bitmap contained in the :data property.

:foreground

:background

These keywords allow you to explicitly specify foreground and background colors. The values should be acceptable to make-color-instance.

:hotspot-x

:hotspot-y

Integers denoting the hotspot (mouse pointer position), with (0,0) at the top left corner. If given, these override any specification in the XBM file.

gif

jpeg

png

tiff

These are GIF87- or GIF89-format, JPEG-format, PNG/GIF24-format, and TIFF-format images, respectively. They are available only if appropriate decoding support was built into XEmacs. XEmacs includes GIF decoding functions as a standard part of it, so if you have X support, you will normally have GIF support, unless you explicitly disable it at configure time. If you have development support (both the libraries and the relevant C header files) available when SXEmacs is built, the JPEG, PNG, and TIFF libraries will automatically be detected (in the “usual places”) and linked into the build.

Note that PNG is the standard format for images distributed with XEmacs, so it is highly recommended that PNG support be built in.

All of these instantiators will be instanced as color-pixmap.

The valid keywords and their values are

:data

A string interpreted as the contents of a file containing data in the appropriate standard format.

:file

The name of a file containing standard-format data.

cursor-font

Most window systems provide a set of standard cursors, which in X11 is called a cursor font. Can only be instanced as pointer. This should probably be fixed.

The valid keyword is :data. Its value should be a string containing one of the standard cursor-font names, such as ‘watch’ or ‘right_ptr’ under X. More specifically, in the X Window System it may be any of the standard cursor names from appendix B of the Xlib manual, provided in the file <X11/cursorfont.h> by most distributions, minus the ‘XC_’ prefix. Other window systems may have different lists.

font

A glyph from a font; i.e. the name of a font, and glyph index into it of the form ‘font fontname index [[mask-font] mask-index]’. Only if X support was compiled into this SXEmacs. Currently can only be instanced as pointer. This should probably be fixed.

subwindow

An embedded windowing system window. Can only be instanced as subwindow. Not implemented.

button

A button widget; either a push button, radio button or toggle button. Can only be instanced as widget.

combo-box

A drop list of selectable items in a widget, for editing text. Can only be instanced as widget.

edit-field

A text editing widget. Can only be instanced as widget.

label

A static, text-only, widget; for displaying text. Can only be instanced as widget.

layout

A widget for controlling the positioning of children underneath it. Through the use of nested layouts, a widget hierarchy can be created which can have the appearance of any standard dialog box or similar arrangement; all of this is counted as one glyph and could appear in many of the places that expect a single glyph. Can only be instanced as widget.

native-layout

The native version of a layout widget. Can only be instanced as widget.

progress-gauge

A sliding widget, for showing progress. Can only be instanced as widget.

tab-control

A tab widget; a series of user selectable tabs. Can only be instanced as widget.

tree-view

A folding widget. Can only be instanced as widget.

scrollbar

A scrollbar widget. Can only be instanced as widget.

autodetect

XEmacs tries to guess what format the data is in. If X support exists, the data string will be checked to see if it names a filename. If so, and this filename contains XBM or XPM data, the appropriate sort of pixmap or pointer will be created. [This includes picking up any specified hotspot or associated mask file.] Otherwise, if pointer is one of the allowable image-instance types and the string names a valid cursor-font name, the image will be created as a pointer. Otherwise, the image will be displayed as text. If no X support exists, the image will always be displayed as text.

inherit

Inherit from the background-pixmap property of a face. Can only be instanced as mono-pixmap.

There are two convenience variables for use with the XBM and XPM image formats.

Variable: xpm-color-symbols

This variable holds definitions of logical color-names used when reading XPM files. Elements of this list should be of the form (color-name form-to-evaluate). The color-name should be a string, which is the name of the color to define; the form-to-evaluate should evaluate to a color specifier object, or a string to be passed to make-color-instance (see Colors). If a loaded XPM file references a symbolic color called color-name, it will display as the computed color instead.

The default value of this variable defines the logical color names ‘"foreground"’ and ‘"background"’ to be the colors of the default face.

Variable: x-bitmap-file-path

A list of the directories in which X bitmap files may be found. If nil, this is initialized from the ‘"*bitmapFilePath"’ resource. This is used by the make-image-instance function (however, note that if the environment variable ‘XBMLANGPATH’ is set, it is consulted first).