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 SXEmacs-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, like the favicons 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). SXEmacs 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 SXEmacs, 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 Aqua), or even by a separate process.