50.3 Using Glyphs
Glyph usage is unfortunately somewhat arcane. (For discussion of
rationale, 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.