-
-An image specifier is used for images (pixmaps and the like). It is used
-to describe the actual image in a glyph. It is instanced as an image-
-instance.
-
-Image instantiators come in many formats: `xbm', `xpm', `gif', `jpeg',
-etc. This describes 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'), and 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 `make-image-instance' 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. FORMAT should be one of
-
-'nothing
- (Don't display anything; no keywords are valid for this.
- 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.)
-'formatted-string
- (Display this image as a text string, with replaceable fields;
- not currently implemented.)
-'xbm
- (An X bitmap; only if X or Windows support was compiled into this XEmacs.
- Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
-'xpm
- (An XPM pixmap; only if XPM support was compiled into this XEmacs.
- Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.)
-'xface
- (An X-Face bitmap, used to encode people's faces in e-mail messages;
- only if X-Face support was compiled into this XEmacs. Can be
- instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
-'gif
- (A GIF87 or GIF89 image; only if GIF support was compiled into this
- XEmacs. NOTE: only the first frame of animated gifs will be displayed.
- Can be instanced as `color-pixmap'.)
-'jpeg
- (A JPEG image; only if JPEG support was compiled into this XEmacs.
- Can be instanced as `color-pixmap'.)
-'png
- (A PNG image; only if PNG support was compiled into this XEmacs.
- Can be instanced as `color-pixmap'.)
-'tiff
- (A TIFF image; only if TIFF support was compiled into this XEmacs.
- Can be instanced as `color-pixmap'.)
-'cursor-font
- (One of the standard cursor-font names, such as "watch" or
- "right_ptr" under X. Under X, this is, more specifically, any
- of the standard cursor names from appendix B of the Xlib manual
- [also known as the file <X11/cursorfont.h>] minus the XC_ prefix.
- On other window systems, the valid names will be specific to the
- type of window system. Can only be instanced as `pointer'.)
-'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]".
- Currently can only be instanced as `pointer', although this should
- probably be fixed.)
-'subwindow
- (An embedded windowing system window.)
-'edit-field
- (A text editing widget glyph.)
-'button
- (A button widget glyph; either a push button, radio button or toggle button.)
-'tab-control
- (A tab widget glyph; a series of user selectable tabs.)
-'progress-gauge
- (A sliding widget glyph, for showing progress.)
-'combo-box
- (A drop list of selectable items in a widget glyph, for editing text.)
-'label
- (A static, text-only, widget glyph; for displaying text.)
-'tree-view
- (A folding widget glyph.)
-'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.
-
-The valid keywords are:
-
-:data
- (Inline data. For most formats above, this should be a string. For
- XBM images, this should be a list of three elements: width, height, and
- a string of bit data. This keyword is not valid for instantiator
- formats `nothing' and `inherit'.)
-:file
- (Data is 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. This keyword is not valid for
- instantiator formats `nothing', `string', `formatted-string',
- `cursor-font', `font', `autodetect', and `inherit'.)
-:foreground
-:background
- (For `xbm', `xface', `cursor-font', `widget' and `font'. These keywords
- allow you to explicitly specify foreground and background colors.
- The argument should be anything acceptable to `make-color-instance'.
- This will cause what would be a `mono-pixmap' to instead be colorized
- as a two-color color-pixmap, and specifies the foreground and/or
- background colors for a pointer instead of black and white.)
-:mask-data
- (For `xbm' and `xface'. This specifies a mask to be used with the
- bitmap. The format is a list of width, height, and bits, like 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.)
-: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
- (Only for `inherit'. This specifies the face to inherit from.
- For widget glyphs this also specifies the face to use for
- display. It defaults to gui-element-face.)
-
-Keywords accepted as menu item specs are also accepted by widget
-glyphs. These are `:selected', `:active', `:suffix', `:keys',
-`:style', `:filter', `:config', `:included', `:key-sequence',
-`:accelerator', `:label' and `:callback'.
-
-If instead of a vector, 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' (q.v.) 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 (which may
-be well before when 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).