50. Glyphs

A glyph is an object that is used for pixmaps, widgets, and images of all sorts, as well as for things that “act” like pixmaps, such as non-textual strings (annotations) displayed in a buffer or in the margins. It is used in begin-glyphs and end-glyphs attached to extents, marginal and textual annotations, overlay arrows (overlay-arrow-* variables), toolbar buttons, mouse pointers, frame icons, truncation and continuation markers, and the like. Basically, any place there is an image or something that acts like an image, there will be a glyph object representing it.

Function: glyphp object

This function returns t if object is a glyph.

50.1 Glyph Introduction

In XEmacs, “glyph” does not refer to a single unit of textual display (the XEmacs term for that is rune, and runes are confined to the internal implementation of redisplay), but rather is an object encapsulating a graphical element, such as an image or widget (an active GUI element such as a button or text entry field; X11 calls this a widget, while MS Windows uses the term control). This graphical element could appear in a buffer, a margin, a gutter, or a toolbar, or even externally to XEmacs as a mouse pointer or an icon, for example.

On the other hand, by contrast with GNU Emacs 21, an XEmacs glyph is not “just” an image. The actual image that is displayed (as opposed to its position or clipping) is defined by an “image specifier” object contained within the glyph. The separation between an image specifier object and a glyph object is made because the glyph includes other properties than just the actual image: e.g. the face it is displayed in, the alignment of the image, etc. Also, an image specifier is used in at least one place in XEmacs in lieu of a glyphs, namely the backing pixmap of a face.

An image specifier is used because glyphs often have locale-specific semantics. The most important example is semantics determined by the display device: you can’t usefully display a JPEG on stdout, or a color image on a monochrome display. But because the image property is a specifier in XEmacs, you can specify that a given glyph appear as a monochrome image on monochrome displays, a color image on color displays, and as a string on TTYs. (Specifying a string for the tty device locale would give behavior like the ALT attribute of an IMG element in HTML.) Another is semantics determined by the buffer or mode. (Unfortunately, currently there are no compelling examples of this for glyphs.)

All this means that only one global glyph needs to exist for a particular purpose (e.g. the icon used to represent an iconified frame, the mouse pointer used over particular areas of a frame, etc.). Often you need not (and should not!) create your own glyph, but rather modify an existing one.

In working with glyphs it is important to keep in mind the distinction between a locale and a domain. A locale is specified by the programmer, and is an abstract link between a specification (for a glyph, its visual appearance) and a displayable object. The displayable object may be a buffer or a window, or an object containing buffers or windows such as frame, device, or console. A domain is an actual display context, which must be concrete enough to enable XEmacs to identify the device type. (Buffers may be displayed in windows on different devices, even simultaneously, so a buffer cannot be a domain. Similarly, the global locale cannot be a domain.) Specifiers, for more information about specifier locales and domains.

50.2 Images

50.2.1 Image Instantiators

An image instantiator 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 XEmacs 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 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 section 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 instantiated as color-pixmap, mono-pixmap, or pointer; whereas cursor-font can be instantiated 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 section 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, Functions for Checking the Validity of Specifier Components.

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 (resource-id is unique to the mswindows-resource 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 section 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.

:resource-type

Only for mswindows-resource. This must be a symbol, either cursor, icon, or bitmap, specifying the type of resource to be retrieved.

: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, Format of Menus.

50.2.2 Image Instantiator Conversion

Conversion is applied to image instantiators at the time they are added to an image specifier or at the time they are passed to make-image-instance.

Function: set-console-type-image-conversion-list console-type list

This function sets the image-conversion-list for consoles of the given console-type. The image-conversion-list specifies how image instantiators that are strings should be interpreted. Each element of the list should be a list of two elements (a regular expression string and a vector) or a list of three elements (the preceding two plus an integer index into the vector). The string is converted to the vector associated with the first matching regular expression. If a vector index is specified, the string itself is substituted into that position in the vector.

Note: The conversion above is applied when the image instantiator is added to an image specifier, not when the specifier is actually instantiated. Therefore, changing the image-conversion-list only affects newly-added instantiators. Existing instantiators in glyphs and image specifiers will not be affected.

Function: console-type-image-conversion-list console-type

This function returns the image-conversion-list for consoles of the given console-type.

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 (MS Windows resource IDs make no sense on other platforms), 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 XEmacs 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 instantiated as nothing.

string

Display this image as a text string. Can only be instantiated as text, although support for instantiation 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 instantiated 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 XEmacs.

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 XEmacs.

Will be instantiated 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. If you have development support (both the libraries and the relevant C header files) available when XEmacs is built, the JPEG, PNG, GIF, 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 instantiated 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 instantiated 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. For MS Windows, use mswindows-resource instantiator format, not cursor-font. 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 XEmacs. Currently can only be instantiated as pointer. This should probably be fixed.

mswindows-resource

An MS Windows pointer resource. Specifies a resource to retrieve directly from the system (an OEM resource) or from a file, particularly an executable file. Can be instantiated as pointer or color-pixmap.

The valid keywords and their values are

:resource-type

A string naming the type (cursor, bitmap, or icon) of the resource. Required.

:file

A string containing the name of the file containing the resource (often an executable). If a system resource, :file should be omitted.

:resource-id

A string containing the name of a resource. Required if :file is not specified.

This must be either an integer (which directly specifies a resource number) or a string. Valid strings are

For bitmaps:

"close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce", "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize", "check", "checkboxes", and "btncorners".

For cursors:

"normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw", "sizewe", "sizens", "sizeall", and "no".

For icons:

"sample", "hand", "ques", "bang", "note", and "winlogo".

subwindow

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

button

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

combo-box

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

edit-field

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

label

A static, text-only, widget; for displaying text. Can only be instantiated 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 instantiated as widget.

native-layout

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

progress-gauge

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

tab-control

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

The required keyword is :items. Its value should be a list of vectors, whose first element is a string, the second element is a callback (a Lisp expression to be eval’ed), and the remaining elements are key-value pairs. The most important keyword is :selected (a Boolean); exactly one of the elements should have a value of t for the :selected property. Other keywords accepted include :descriptor (a string), :face (a symbol naming a face), :orientation (a symbol, one of top, center, bottom, left, or right), and :pixel-width and :pixel-height (positive integers).

(The above is incomplete and may be inaccurate.)

tree-view

A folding widget. Can only be instantiated as widget.

scrollbar

A scrollbar widget. Can only be instantiated 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 instantiated 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 section 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).

50.2.4 Image Instances

Image-instance objects encapsulate the way a particular image (pixmap, etc.) is displayed on a particular device.

In most circumstances, you do not need to directly create image instances; use a glyph instead. However, it may occasionally be useful to explicitly create image instances, if you want more control over the instantiation process.

Function: image-instance-p object

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

50.2.4.1 Image Instance Types

Image instances come in a number of different types. The type of an image instance specifies the nature of the image: Whether it is a text string, a mono pixmap, a color pixmap, etc.

The valid image instance types are

nothing

Nothing is displayed.

text

Displayed as text. The foreground and background colors and the font of the text are specified independent of the pixmap. Typically these attributes will come from the face of the surrounding text, unless a face is specified for the glyph in which the image appears.

mono-pixmap

Displayed as a mono pixmap (a pixmap with only two colors where the foreground and background can be specified independent of the pixmap; typically the pixmap assumes the foreground and background colors of the text around it, unless a face is specified for the glyph in which the image appears).

color-pixmap

Displayed as a color pixmap.

pointer

Used as the mouse pointer for a window.

subwindow

A child window that is treated as an image. This allows (e.g.) another program to be responsible for drawing into the window. Not currently implemented.

widget

An active GUI element implemented as a “widget” or “control” of the underlying window system.

The following functions are used to check whether an image instance type is valid in the running XEmacs.

Function: valid-image-instance-type-p type

This function returns non-nil if type is a valid image instance type.

Function: image-instance-type-list

This function returns a list of the valid image instance types.

The following functions are used to determine the type of an image instance.

Function: image-instance-type image-instance

Return the type of the given image instance. The return value will be one of nothing, text, mono-pixmap, color-pixmap, pointer, subwindow, or widget.

Function: text-image-instance-p object

Return non-nil if object is an image instance of type text.

Function: mono-pixmap-image-instance-p object

Return non-nil if object is an image instance of type mono-pixmap.

Function: color-pixmap-image-instance-p object

Return non-nil if object is an image instance of type color-pixmap.

Function: pointer-image-instance-p object

Return non-nil if object is an image instance of type pointer.

Function: subwindow-image-instance-p object

Return non-nil if object is an image instance of type subwindow.

Function: nothing-image-instance-p object

Return non-nil if object is an image instance of type nothing.

Function: widget-image-instance-p object

Return non-nil if object is an image instance of type widget.

50.2.4.2 Image Instance Functions

Function: make-image-instance data &optional domain dest-types noerror

This function creates a new image-instance object.

data is an image instantiator, which describes the image (see section Image Instantiators).

dest-types should be a list of allowed image instance types that can be generated. The dest-types list is unordered. If multiple destination types are possible for a given instantiator, the “most natural” type for the instantiator’s format is chosen. These are

XBM

xface

mono-pixmap, then color-pixmap, then pointer.

XPM

GIF

JPEG

PNG

TIFF

color-pixmap, then mono-pixmap, then pointer.

string

formatted-string formats

text, then mono-pixmap (not currently implemented), then color-pixmap (not currently implemented).

mswindows-resource

For pointer resources, pointer.

For the others, color-pixmap.

The other formats can only be instantiated as one type.

If you want to control more specifically the order of the types into which an image is instantiated, call make-image-instance repeatedly until it succeeds, passing less and less preferred destination types each time.

If dest-types is omitted, all possible types are allowed.

domain specifies the domain to which the image instance will be attached. This domain is termed the governing domain. The type of the governing domain depends on the image instantiator format. (Although, more correctly, it should probably depend on the image instance type.) For example, pixmap image instances are specific to a device, but widget image instances are specific to a particular XEmacs window because in order to display such a widget when two windows onto the same buffer want to display the widget, two separate underlying widgets must be created. (That’s because a widget is actually a child window-system window, and all window-system windows have a unique existence on the screen.) This means that the governing domain for a pixmap image instance will be some device (most likely, the only existing device), whereas the governing domain for a widget image instance will be some XEmacs window.

If you specify an overly general domain (e.g. a frame when a window was wanted), an error is signaled. If you specify an overly specific domain (e.g. a window when a device was wanted), the corresponding general domain is fetched and used instead. For make-image-instance, it makes no difference whether you specify an overly specific domain or the properly general domain derived from it. However, it does matter when creating an image instance by instantiating a specifier or glyph (e.g. with glyph-image-instance), because the more specific domain causes spec lookup to start there and proceed to more general domains. (It would also matter when creating an image instance with an instantiator format of inherit, but we currently disallow this.)

If omitted, domain defaults to the selected window.

noerror controls what happens when the image cannot be generated. If nil, an error message is generated. If t, no messages are generated and this function returns nil. If anything else, a warning message is generated and this function returns nil.

Function: colorize-image-instance image-instance foreground background

This function makes the image instance be displayed in the given colors. Image instances come in two varieties: bitmaps, which are 1 bit deep which are rendered in the prevailing foreground and background colors; and pixmaps, which are of arbitrary depth (including 1) and which have the colors explicitly specified. This function converts a bitmap to a pixmap. If the image instance was a pixmap already, nothing is done (and nil is returned). Otherwise t is returned.

The following functions are

Function: image-instance-name image-instance

This function returns the name of the given image instance. The name is typically taken from the :file property of the instantiator if present, otherwise from the :data property.

Function: image-instance-domain image-instance

Return the governing domain of the given image-instance. The governing domain of an image instance is the domain that the image instance is specific to. It is NOT necessarily the domain that was given to the call to specifier-instance that resulted in the creation of this image instance. See make-image-instance for more information on governing domains.

Function: image-instance-string image-instance

This function returns the string of the given image instance. This will only be non-nil for text image instances.

Function: image-instance-file-name image-instance

This function returns the file name from which image-instance was read, if known.

Function: image-instance-mask-file-name image-instance

This function returns the file name from which image-instance’s mask was read, if known.

Pixmaps are considered to be three-dimensional. The height and width of the pixel array that is displayed, and the color depth of its pixels, are accessed with these functions.

Function: image-instance-depth image-instance

This function returns the depth of the image instance. This is 0 for a mono pixmap, or a positive integer for a color pixmap.

Function: image-instance-height image-instance

This function returns the height of the image instance, in pixels.

Function: image-instance-width image-instance

This function returns the width of the image instance, in pixels.

The hotspot is a point relative to the origin of the pixmap. When an image is used as a mouse pointer, the hotspot is the point on the image that sits over the location that the pointer points to. This is, for example, the tip of the arrow or the center of the crosshairs.

These functions access the coordinates of the hotspot. They simply return nil for a non-pointer image instance.

Function: image-instance-hotspot-x image-instance

This function returns the X coordinate of the image instance’s hotspot, if known.

Function: image-instance-hotspot-y image-instance

This function returns the Y coordinate of the image instance’s hotspot, if known.

Mono pixmaps and pointers may have their foreground and background colors set when instantiated. Use these functions to access color information.

Function: image-instance-foreground image-instance

This function returns the foreground color of image-instance, if applicable. This will be a color instance or nil. (It will only be non-nil for colorized mono pixmaps and for pointers.)

Function: image-instance-background image-instance

This function returns the background color of image-instance, if applicable. This will be a color instance or nil. (It will only be non-nil for colorized mono pixmaps and for pointers.)

50.3 Using Glyphs

Glyph usage is unfortunately somewhat arcane. (For discussion of rationale, (Internals)Glyphs.) Because they are not “text,” they cannot be inserted directly into a buffer. Instead, they are values of properties of extents attached to buffers or strings, values of global variables such as mouse pointers, or as a component of a complex data structure such as a toolbar initializer. Although these uses could probably streamlined, each structure has its own requirements. Since glyphs are very flexible, it is possible to create applications like the ‘edit-toolbar’ and ‘xpm-mode’ libraries which display glyphs in a buffer (for reference while editing) that are normally used in a different context.

Usage of glyphs can roughly be categorized as follows:

Buffer glyphs

Glyphs that are inserted in a buffer may be used for their own sake (for example, image display in ‘w3’), as an accurate representation of text that can’t be displayed in usual fonts (equation display in ‘preview-latex’), or as annotations (such as a marginal indication of a bookmark). Glyphs are attached to buffers via extents.

Redisplay glyphs

Glyphs can be used to create XEmacs-specific “fonts”. For example, the character that indicates truncation of lines is implemented as the truncation-glyph. It is also possible to have XEmacs display a certain character using a custom glyph, via display tables.

Frame glyphs

Glyphs are used to control the appearance of various other components of the frame. They can be inserted in the modeline, the favicons are used in Web browsers. They are used to specify the labels on toolbar buttons. Finally, they can be inserted in the gutters. (The difference between a glyph inserted in a gutter and a marginal annotation is that the marginal annotation is tied to the text in the buffer. If the buffer line scrolls out of view, the marginal annotation will, as well. A gutter glyph does not move with the text.)

Unfortunately, all these uses are special cases, and have their own APIs, in contrast to glyphs in a buffer.

External glyphs

External glyphs simply allow a consistent API for images. The images are then passed to external software such as the window system itself (mouse cursor shapes) and the window manager (icons to represent minimized windows). XEmacs has no role in managing their use.

Subwindow and widget glyphs

These do not constitute a context of use, but rather an important class of glyph types. The difference between these and other glyphs is that while their geometry is determined by XEmacs, their behavior is managed separately, by internal mechanisms in the case of widgets, and (possibly) by another process in the case of subwindows.

Some simple concrete examples showing how to insert a glyph in a buffer are presented later. Glyph Examples.

“Creating Glyphs” explains how to create glyphs. Creating a glyph using make-glyph does not specify where the glyph will be used, it only specifies what the glyph will look like. The next four sections explain how to embed glyphs in different display contexts. Finally, the last two sections explain the special considerations of using glyphs whose behavior is not determined by the code creating them, but by the glyph itself (a “widget” in X11 or “control” in MS Windows or Aqua), or even by a separate process.

50.3.1 Creating Glyphs

Function: make-glyph &optional spec-list type

This function creates a new glyph object of type type.

The optional spec-list is used to initialize the glyph’s image. It can be any spec-list of image instantiator accepted by canonicalize-spec-list, Adding specifications to a Specifier. An individual image instantiator may be a string, which is converted to a vector according to console-type-image-conversion-list, or a vector. The vector’s first element specifies the external format of the data, such as a string, a PNG file, or an MS Windows resource. This is followed by properties (keyword-value pairs) specifying such information as the name of a file containing an image, or pixmap data directly. See section Image Instantiators.

The optional type specifies the type of the glyph. type should be one of buffer (used for glyphs in an extent, the modeline, the toolbar, or elsewhere in a frame), pointer (used for the mouse-pointer), or icon (used for a frame’s icon), and defaults to buffer.

spec-list is the initializer for the glyph’s image property, which is an image specifier. (Note that image as used in the context of a glyph’s image property or in the terms image specifier, image instantiator, or image instance does not refer to what people normally think of as an image (which in XEmacs is called a pixmap), but to any graphical element—a pixmap, a widget, or even a block of text, when used in the places that call for a glyph.)

The most common form of spec-list is a single image instantiator. (Compatibility note: in GNU Emacs 21, a string used to instantiate an image is interpreted as the name of an image file, which is searched for and instantiated.) The conversion controlled by console-type-image-conversion-list typically attempts to look up the string as a file name in XEmacs’s data directory path, and if this fails, defaults to displaying the string as a text image instance (i.e.. the string itself.

Fine control of a particular specification is provided by using a vector as the image instantiator. More complicated instantiators allow lists of instantiators to be specified (which are tried in order), or mappings from locales to lists of instantiators, etc. See section Specifiers, for more information about specification formats.

As well as using spec-list to initialize the glyph, you can set specifications using set-glyph-image. The glyph itself is not actually a specifier, but rather is an object containing an image specifier (as well as other properties seldom set by user code). Therefore, you cannot set or access specifications for the glyph’s image by directly using set-specifier, specifier-instance or the like on the glyph; instead use them on (glyph-image glyph) or use the convenience functions set-glyph-image, glyph-image-instance, and glyph-image.

Glyph types reflect the fact that glyphs are used in contexts like pointers and window manager icons, which are defined by external programs such as the window system or window manager. These require somewhat different internal format, which is opaque to the user.

It is extremely rare that you will ever have to specify a value for type, which should be one of buffer (used for glyphs in an extent, the modeline, the toolbar, or elsewhere in a buffer), pointer (used for the mouse-pointer), or icon (used for a frame’s icon), and defaults to buffer. The only cases where it needs to be specified is when creating icon or pointer glyphs, and in both cases the necessary glyphs have already been created at startup and are accessed through the appropriate variables, e.g. text-pointer-glyph (or in general, any ‘*-pointer-glyph’) and frame-icon-glyph. User code should never need to create pointer or icon glyphs. See section Glyph Types.

There are a few other glyph creation functions, normally used only internally or at XEmacs initialization.

Function: make-glyph-internal &optional type

This function creates a new, uninitialized glyph of type type.

Function: make-pointer-glyph &optional spec-list

Return a new pointer-glyph object with the specification list spec-list. This function is equivalent to calling make-glyph with a type of pointer.

make-pointer-glyph is normally used only by XEmacs initialization code. It is extremely unlikely that you will ever need to create a pointer glyph. Instead, you probably want to be calling set-glyph-image on an existing glyph, e.g. text-pointer-glyph.

Function: make-icon-glyph &optional spec-list

Return a new icon-glyph object with the specification list spec-list. This function is equivalent to calling make-glyph with a type of icon.

make-icon-glyph is normally used only by XEmacs initialization code. It is extremely unlikely that you will ever need to create a icon glyph. Instead, you probably want to be calling set-glyph-image on the existing glyph, frame-icon-glyph.

50.3.2 Buffer Glyphs

Creating a glyph using make-glyph does not specify where the glyph will be used, it only specifies what the glyph will look like. Once you have created a glyph, you specify where it will be used by attaching it to an extent as a begin-glyph or end-glyph.

buffer text

To insert a glyph into a buffer, create an extent in the buffer and then use set-extent-begin-glyph or set-extent-end-glyph to set a glyph to be displayed at the corresponding edge of the extent. (It is common to create zero-width extents for this purpose.)

margins

To insert a glyph into the left or right margin of a buffer, first make sure the margin is visible by setting a value for the specifiers left-margin-width or right-margin-width. (Not strictly necessary when using margin glyphs with layout policy whitespace.) Follow the same procedure above for inserting a glyph in a buffer, then set a non-default layout policy for the glyph using set-extent-begin-glyph-layout or set-extent-end-glyph-layout. Alternatively, use the high-level annotations API (see make-annotation). (In fact, you can also use the annotations API for glyphs in a buffer, by setting a layout policy of text.)

50.3.3 Redisplay Glyphs

To use a glyph to control the shape of miscellaneous redisplay effects such as the truncation and continuation markers, set the appropriate existing glyph variables with set-glyph-image. See continuation-glyph, control-arrow-glyph, hscroll-glyph, invisible-text-glyph, octal-escape-glyph, and truncation-glyph. See also overlay-arrow-string, an odd redisplay leftover which can be set to a glyph you created, and will cause the glyph to be displayed on top of the text position specified in the marker stored in overlay-arrow-position.

To use a glyph in a display table (i.e. to control the appearance of any individual character), create the appropriate character glyphs and then set a specification for the specifier current-display-table, which controls the appearance of characters. You can also set an overriding display table for use with text displayed in a particular face; see set-face-display-table and make-display-table. #### Note: Display tables do not currently support general Mule characters. They will be overhauled at some point to support this and to provide other features required under Mule. Display Tables.

Glyphs are not actually used as the background pixmaps of faces, but the API is similar. The background pixmap of a face is actually an image specifier – probably the only place in XEmacs where an image specifier occurs outside of a glyph. If you would like to use a glyph’s image as a background pixmap, you can extract it with glyph-image, and then add it to a face. See section Face Convenience Functions.

Glyph: truncation-glyph

This variable specifies what is displayed at the end of truncated lines.

Glyph: continuation-glyph

This variable specifies what is displayed at the end of wrapped lines.

Glyph: octal-escape-glyph

This variable specifies what to prefix character codes displayed in octal with.

Glyph: hscroll-glyph

This variable specifies what to display at the beginning of horizontally scrolled lines.

Glyph: invisible-text-glyph

This variable specifies what to use to indicate the presence of invisible text. This is the glyph that is displayed when an ellipsis is called for, according to selective-display-ellipses or buffer-invisibility-spec). Normally this is three dots (“...”).

Glyph: control-arrow-glyph

This variable specifies what to use as an arrow for control characters.

50.3.4 Frame Glyphs

There are also a number of special objects whose appearance is specified by a glyph. Most of these a global objects that you update with set-glyph-image, such as mouse pointers. Frame icons, toolbar button icons, and the modeline are the main non-text objects which accept glyphs as elements.

modeline

A glyph may be displayed in the modeline by inserting the glyph as one of the elements of the modeline format. (Unfortunately you can’t currently put a begin glyph or end glyph on one of the modeline extents—they’re ignored.)

toolbar

To insert a glyph into a toolbar, specify it as the icon part of a toolbar button, which in turn must be part of a toolbar instantiator (typically set on the specifier default-toolbar). See default-toolbar for more information. (As a convenience, you may use a symbol in place of the glyph list in the toolbar button instantiator; the symbol is evalled to get the glyph list. This facilitates both creating the toolbar instantiator and modifying individual glyphs in a toolbar later on. For example, you can change the way that the Mail toolbar button looks by modifying the value of the variable toolbar-mail-icon (in general, toolbar-*-icon) and then calling (set-specifier-dirty-flag default-toolbar). (#### Unfortunately this doesn’t quite work the way it should; the change will appear in new frames, but not existing ones, because once an image has been displayed the pixmap replaces the symbol for those domains.)

gutter

To insert a glyph into a gutter, use set-extent-begin-glyph or set-extent-end-glyph to set a glyph to be displayed at the corresponding edge of extent in a string, similar to the way you insert glyphs in a buffer. Then insert the string into the gutter Specifying a Gutter. Glyphs that are frequently used in this way are tab control and progress bar glyphs.

50.3.5 External Glyphs

There are two special kinds of glyph that are not displayed by XEmacs. Instead, they are used to set the appearance of iconified frames and the mouse pointer. Because these uses are constrained by the window system, icons and pointers have their own special types See section Glyph Types.

You may use a glyph as the icon for a frame. Do not create a new glyph; instead, change the specifications for the existing glyph frame-icon-glyph with set-glyph-image. This is a unique, predefined object. Although the natural usage is to set specifications for the global locale or a frame locale, you can also arrange for a special icon when a frame’s selected window displays a particular buffer by using a buffer locale.

The shape of the mouse pointer when over a particular section of a frame is controlled using various glyph variables. Since the image of a glyph is a specifier, it can be controlled on a per-buffer, per-frame, per-window, or per-device basis.

To use a glyph as the mouse pointer, in general you do not create a new glyph, but rather you change the specifications of various existing glyphs, such as text-pointer-glyph for the pointer used over text, modeline-pointer-glyph for the pointer used over the modeline, etc. Do an apropos over ‘pointer-glyph’ to find all of them. (Note also that you can temporarily set the mouse pointer to some specific shape by using set-frame-pointer, which takes an image instance, as obtained from calling glyph-image-instance on a glyph of type pointer – either one of the above-mentioned variables or one you created yourself. (See below for what it means to create a glyph of type pointer.) This pointer will last only until the next mouse motion event is processed or certain other things happen, such as creating or deleting a window. (In fact, the above-mentioned pointer glyph variables are implemented as part of the default handler for mouse motion events. If you want to customize this behavior, take a look at mode-motion-hook, or mouse-motion-handler if you really want to get low-level.)

You should use set-glyph-image to set the following variables, not setq.

Glyph: text-pointer-glyph

This variable specifies the shape of the mouse pointer when over text.

Glyph: nontext-pointer-glyph

This variable specifies the shape of the mouse pointer when over a buffer, but not over text. If unspecified in a particular domain, text-pointer-glyph is used.

Glyph: modeline-pointer-glyph

This variable specifies the shape of the mouse pointer when over the modeline. If unspecified in a particular domain, nontext-pointer-glyph is used.

Glyph: selection-pointer-glyph

This variable specifies the shape of the mouse pointer when over a selectable text region. If unspecified in a particular domain, text-pointer-glyph is used.

Glyph: gc-pointer-glyph

This variable specifies the shape of the mouse pointer when a garbage collection is in progress. If the selected window is on a window system and this glyph specifies a value (i.e. a pointer image instance) in the domain of the selected window, the pointer will be changed as specified during garbage collection. Otherwise, a message will be printed in the echo area, as controlled by gc-message.

Glyph: busy-pointer-glyph

This variable specifies the shape of the mouse pointer when XEmacs is busy. If unspecified in a particular domain, the pointer is not changed when XEmacs is busy.

Glyph: menubar-pointer-glyph

This variable specifies the shape of the mouse pointer when over the menubar. If unspecified in a particular domain, the window-system-provided default pointer is used.

Glyph: scrollbar-pointer-glyph

This variable specifies the shape of the mouse pointer when over a scrollbar. If unspecified in a particular domain, the window-system-provided default pointer is used.

Glyph: toolbar-pointer-glyph

This variable specifies the shape of the mouse pointer when over a toolbar. If unspecified in a particular domain, nontext-pointer-glyph is used.

Internally, these variables are implemented in default-mouse-motion-handler, and thus only take effect when the mouse moves. That function calls set-frame-pointer, which sets the current mouse pointer for a frame.

Function: set-frame-pointer frame image-instance

This function sets the mouse pointer of frame to the given pointer image instance. You should not call this function directly. (If you do, the pointer will change again the next time the mouse moves.)

50.3.6 Native GUI Widgets

A “native widget” is a primitive GUI object defined either by the host GUI platform or an external toolkit, and accessed from Lisp as a “glyph.”

50.3.6.1 Introduction to Native Widgets and Subwindow Glyphs

Traditionally Emacsen have hidden the GUI apparatus from the Lisp programmer, but in XEmacs 21.4 the ability to embed autonomous GUI objects, called native widgets, in text was added to Lisp. They are handled as glyphs. Unlike traditional XEmacs glyphs such images and strings, native widgets are opaque to XEmacs, and must be able to redraw themselves because they are implemented as subwindows, not as graphics drawn by XEmacs into the text window.

Primitive widgets are coded in C using the underlying GUI toolkit, and thus are beyond the scope of the XEmacs Lisp Reference Manual. However, composite widgets can be created in Lisp using “layouts,” which are horizontal or vertical arrays of subwidgets. For example, the search dialog is formatted using layouts.

50.3.6.2 Lisp API to Native Widgets

Native widgets are manipulated as glyphs (see section Glyphs). Thus they are created using make-glyph, with a format of one of the widget types and a :data property specific to the widget being instantiated.

However, there is a technical difference between widgets and other kinds of glyphs that is theoretically important. Because widgets are active (that is, they can respond to user input events themselves), it is possible for the user to become aware that two appearances of the “same” glyph are actually separate instances. For example, if a user changes an image glyph from red to blue, and the buffer containing the glyph appears in more than one window, the user will perceive all the appearances to change from red to blue simultaneously. However, suppose the glyph is a button glyph (e.g., as used in the Customize buffer for the Set, Save, and Done buttons). Then if the Customize buffer appears in several windows at the same time, and the user clicks on the button, she will only perceive the button to be depressed in the window where she clicked the button.

It seems from this example that it is unlikely to be a problem in practice. When the user is faced with an active widget, it seems likely that attention will focus on the widget being manipulated, and having other instances of the widget respond simultaneously might be more disconcerting than the actual case.

50.3.6.3 Layouts

An XEmacs layout is a one-dimensional array of glyphs. It is 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.

(There are also native layouts, but I don’t know what these are or how they are used.)

A layout descriptor is an image instantiator, i.e., a vector of the form ‘[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]’ with format layout, and properties

:orientation

Specifies the orientation of the contained array of glyphs. The value must be one of the symbols horizontal or vertical.

:horizontally-justify

Specifies the horizontal justification of the items in the array. The value must be one of the symbols :right, :center, or :left.

:vertically-justify

Specifies the vertical justification of the items in the array. The value must be one of the symbols :top, :center, or :bottom.

:justify

Specifies justification. #### not understood.

:border

A glyph to place in the border. The value must be an image instantiator.

:items

The glyphs controlled by the layout. The value must be a list of image instantiators.

Here is the specification of the search dialog widget created by make-search-dialog in the ‘dialog-items’ library, which makes use of recursive layouts.

(make-glyph
 `[layout 
   :orientation horizontal 
   :vertically-justify top 
   :horizontally-justify center 
   :border [string :data "Search"]
   :items 
   ([layout :orientation vertical 
            :justify top	; implies left also
            :items 
            ([string :data "Search for:"]
     	[button :descriptor "Match Case"
     		:style toggle
     		:selected (not case-fold-search)
     		:callback (setq case-fold-search
     				(not case-fold-search))]
     	[button :descriptor "Regular Expression"
     		:style toggle
     		:selected search-dialog-regexp
     		:callback (setq search-dialog-regexp
     				(not search-dialog-regexp))]
     	[button :descriptor "Forwards"
     		:style radio
     		:selected search-dialog-direction
     		:callback (setq search-dialog-direction t)]
     	[button :descriptor "Backwards"
     		:style radio
     		:selected (not search-dialog-direction)
     		:callback (setq search-dialog-direction nil)]
     	)]
    [layout :orientation vertical
            :vertically-justify top
            :horizontally-justify right
            :items
            ([edit-field :width 15 :descriptor "" :active t
     		    :initial-focus t]
     	[button :width 10 :descriptor "Find Next"
     		:callback-ex
     		(lambda (image-instance event)
     		  (search-dialog-callback ,parent
     					  image-instance
     					  event))]
     	[button :width 10 :descriptor "Cancel"
     		:callback-ex
     		(lambda (image-instance event)
     		  (isearch-dehighlight)
     		  (delete-frame 
     		   (event-channel event)))])])])

50.3.6.4 Primitive Widgets

button

A button widget; either a push button, radio button or toggle button.

combo-box

A drop list of selectable items in a widget, for editing text.

edit-field

A text editing widget.

label

A static, text-only, widget; for displaying text.

progress-gauge

A sliding widget, for showing progress.

tab-control

A tab widget; a series of user selectable tabs.

tree-view

A folding widget.

scrollbar

A scrollbar widget. (#### Probably not the same as the scrollbar controlling an Emacs window.)

50.3.7 Subwindows

Subwindows are not currently implemented.

Function: subwindowp object

This function returns non-nil if object is a subwindow.

50.4 Manipulating Glyphs

Each glyphs has properties that may be accessed. Most of these can also be set after the glyph is initialized, with the exception of the glyph’s type. This is not a real restriction, as it is almost never useful to create glyphs of types other than buffer.

50.4.1 Glyph Properties

Each glyph has a list of properties, which control all of the aspects of the glyph’s appearance. The following symbols have predefined meanings:

image

The image used to display the glyph.

baseline

Percent above baseline that glyph is to be displayed. Only for glyphs displayed inside of a buffer.

contrib-p

Whether the glyph contributes to the height of the line it’s on. Only for glyphs displayed inside of a buffer.

face

Face of this glyph (not a specifier).

Function: set-glyph-property glyph property value &optional locale tag-set how-to-add

This function changes a property of a glyph.

For built-in properties, the actual value of the property is a specifier and you cannot change this; but you can change the specifications within the specifier, and that is what this function will do. The glyph face is an exception; it is a face name (a symbol) or a face object, not a specifier. (The face properties themselves are typically specifiers.) For user-defined properties, you can use this function to either change the actual value of the property or, if this value is a specifier, change the specifications within it.

If property is a built-in property, the specifications to be added to this property can be supplied in many different ways:

• If value is a simple instantiator (e.g. a string naming a pixmap filename) or a list of instantiators, then the instantiator(s) will be added as a specification of the property for the given locale (which defaults to global if omitted).
• If value is a list of specifications (each of which is a cons of a locale and a list of instantiators), then locale must be nil (it does not make sense to explicitly specify a locale in this case), and specifications will be added as given.
• If value is a specifier (as would be returned by glyph-property if no locale argument is given), then some or all of the specifications in the specifier will be added to the property. In this case, the function is really equivalent to copy-specifier and locale has the same semantics (if it is a particular locale, the specification for the locale will be copied; if a locale type, specifications for all locales of that type will be copied; if nil or all, then all specifications will be copied).

how-to-add should be either nil or one of the symbols prepend, append, remove-tag-set-prepend, remove-tag-set-append, remove-locale, remove-locale-type, or remove-all. See copy-specifier and add-spec-to-specifier for a description of what each of these means. Most of the time, you do not need to worry about this argument; the default behavior usually is fine.

In general, it is OK to pass an instance object (e.g. as returned by glyph-property-instance) as an instantiator in place of an actual instantiator. In such a case, the instantiator used to create that instance object will be used (for example, if you set a font-instance object as the value of the font property, then the font name used to create that object will be used instead). In some cases, however, doing this conversion does not make sense, and this will be noted in the documentation for particular types of instance objects.

If property is not a built-in property, then this function will simply set its value if locale is nil. However, if locale is given, then this function will attempt to add value as the instantiator for the given locale, using add-spec-to-specifier. If the value of the property is not a specifier, it will automatically be converted into a generic specifier.

Function: glyph-property glyph property &optional locale

This function returns glyph’s value of the given property.

If locale is omitted, the glyph’s actual value for property will be returned. For built-in properties, this will be a specifier object of a type appropriate to the property (e.g. a font or color specifier). For other properties, this could be anything.

If locale is supplied, then instead of returning the actual value, the specification(s) for the given locale or locale type will be returned. This will only work if the actual value of property is a specifier (this will always be the case for built-in properties, but may or may not apply to user-defined properties). If the actual value of property is not a specifier, this value will simply be returned regardless of locale.

The return value will be a list of instantiators (e.g. vectors specifying pixmap data), or a list of specifications, each of which is a cons of a locale and a list of instantiators. Specifically, if locale is a particular locale (a buffer, window, frame, device, or global), a list of instantiators for that locale will be returned. Otherwise, if locale is a locale type (one of the symbols buffer, window, frame, or device), the specifications for all locales of that type will be returned. Finally, if locale is all, the specifications for all locales of all types will be returned.

The specifications in a specifier determine what the value of property will be in a particular domain or set of circumstances, which is typically a particular Emacs window along with the buffer it contains and the frame and device it lies within. The value is derived from the instantiator associated with the most specific locale (in the order buffer, window, frame, device, and global) that matches the domain in question. In other words, given a domain (i.e. an Emacs window, usually), the specifier for property will first be searched for a specification whose locale is the buffer contained within that window; then for a specification whose locale is the window itself; then for a specification whose locale is the frame that the window is contained within; etc. The first instantiator that is valid for the domain (usually this means that the instantiator is recognized by the device [i.e. the X server or TTY device] that the domain is on). The function glyph-property-instance actually does all this, and is used to determine how to display the glyph.

Function: glyph-property-instance glyph property &optional domain default no-fallback

This function returns the instance of glyph’s property in the specified domain.

Under most circumstances, domain will be a particular window, and the returned instance describes how the specified property actually is displayed for that window and the particular buffer in it. Note that this may not be the same as how the property appears when the buffer is displayed in a different window or frame, or how the property appears in the same window if you switch to another buffer in that window; and in those cases, the returned instance would be different.

The returned instance is an image-instance object, and you can query it using the appropriate image instance functions. For example, you could use image-instance-depth to find out the depth (number of color planes) of a pixmap displayed in a particular window. The results might be different from the results you would get for another window (perhaps the user specified a different image for the frame that window is on; or perhaps the same image was specified but the window is on a different X server, and that X server has different color capabilities from this one).

domain defaults to the selected window if omitted.

domain can be a frame or device, instead of a window. The value returned for such a domain is used in special circumstances when a more specific domain does not apply; for example, a frame value might be used for coloring a toolbar, which is conceptually attached to a frame rather than a particular window. The value is also useful in determining what the value would be for a particular window within the frame or device, if it is not overridden by a more specific specification.

If property does not name a built-in property, its value will simply be returned unless it is a specifier object, in which case it will be instantiated using specifier-instance.

Optional arguments default and no-fallback are the same as in specifier-instance. See section Specifiers.

Function: remove-glyph-property glyph property &optional locale tag-set exact-p

This function removes a property from a glyph. For built-in properties, this is analogous to remove-specifier. See section remove-specifier-p, for the meaning of the locale, tag-set, and exact-p arguments.

50.4.2 Glyph Convenience Functions

The following functions are provided for working with specific properties of a glyph. Note that these are exactly like calling the general functions described above and passing in the appropriate value for property.

Remember that if you want to determine the “value” of a specific glyph property, you probably want to use the *-instance functions. For example, to determine whether a glyph contributes to its line height, use glyph-contrib-p-instance, not glyph-contrib-p. (The latter will return a boolean specifier or a list of specifications, and you probably aren’t concerned with these.)

Function: glyph-image glyph &optional locale

This function is equivalent to calling glyph-property with a property of image. The return value will be an image specifier if locale is nil or omitted; otherwise, it will be a specification or list of specifications.

Function: set-glyph-image glyph spec &optional locale tag-set how-to-add

This function is equivalent to calling set-glyph-property with a property of image.

Function: glyph-image-instance glyph &optional domain default no-fallback

This function returns the instance of glyph’s image in the given domain, and is equivalent to calling glyph-property-instance with a property of image. The return value will be an image instance.

Normally domain will be a window or nil (meaning the selected window), and an instance object describing how the image appears in that particular window and buffer will be returned.

Function: glyph-contrib-p glyph &optional locale

This function is equivalent to calling glyph-property with a property of contrib-p. The return value will be a boolean specifier if locale is nil or omitted; otherwise, it will be a specification or list of specifications.

Function: set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add

This function is equivalent to calling set-glyph-property with a property of contrib-p.

Function: glyph-contrib-p-instance glyph &optional domain default no-fallback

This function returns whether the glyph contributes to its line height in the given domain, and is equivalent to calling glyph-property-instance with a property of contrib-p. The return value will be either nil or t. (Normally domain will be a window or nil, meaning the selected window.)

Function: glyph-baseline glyph &optional locale

This function is equivalent to calling glyph-property with a property of baseline. The return value will be a specifier if locale is nil or omitted; otherwise, it will be a specification or list of specifications.

Function: set-glyph-baseline glyph spec &optional locale tag-set how-to-add

This function is equivalent to calling set-glyph-property with a property of baseline.

Function: glyph-baseline-instance glyph &optional domain default no-fallback

This function returns the instance of glyph’s baseline value in the given domain, and is equivalent to calling glyph-property-instance with a property of baseline. The return value will be an integer or nil.

Normally domain will be a window or nil (meaning the selected window), and an instance object describing the baseline value appears in that particular window and buffer will be returned.

Function: glyph-face glyph

This function returns the face of glyph. (Remember, this is not a specifier, but a simple property.)

Function: set-glyph-face glyph face

This function changes the face of glyph to face.

50.4.3 Glyph Dimensions

Function: glyph-width glyph &optional window

This function returns the width of glyph on window. This may not be exact as it does not take into account all of the context that redisplay will.

Function: glyph-ascent glyph &optional window

This function returns the ascent value of glyph on window. This may not be exact as it does not take into account all of the context that redisplay will.

Function: glyph-descent glyph &optional window

This function returns the descent value of glyph on window. This may not be exact as it does not take into account all of the context that redisplay will.

Function: glyph-height glyph &optional window

This function returns the height of glyph on window. (This is equivalent to the sum of the ascent and descent values.) This may not be exact as it does not take into account all of the context that redisplay will.

50.4.4 Glyph Types

Each glyph has a particular type, which controls how the glyph’s image is generated. Each glyph type has a corresponding list of allowable image instance types that can be generated. When you call glyph-image-instance to retrieve the image instance of a glyph, XEmacs does the equivalent of calling make-image-instance and passing in dest-types the list of allowable image instance types for the glyph’s type.

• buffer glyphs can be used as the begin-glyph or end-glyph of an extent, in the modeline, and in the toolbar. Their image can be instantiated as nothing, mono-pixmap, color-pixmap, text, and subwindow.
• pointer glyphs can be used to specify the mouse pointer. Their image can be instantiated as pointer.
• icon glyphs can be used to specify the icon used when a frame is iconified. Their image can be instantiated as mono-pixmap and color-pixmap.

Function: glyph-type glyph

This function returns the type of the given glyph. The return value will be a symbol, one of buffer, pointer, or icon.

Function: valid-glyph-type-p glyph-type

Given a glyph-type, this function returns non-nil if it is valid.

Function: glyph-type-list

This function returns a list of valid glyph types.

Function: buffer-glyph-p object

This function returns non-nil if object is a glyph of type buffer.

Function: icon-glyph-p object

This function returns non-nil if object is a glyph of type icon.

Function: pointer-glyph-p object

This function returns non-nil if object is a glyph of type pointer.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.