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

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 Image Specifiers.

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 SXEmacs 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 SXEmacs’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 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 Glyph Types.

There are a few other glyph creation functions, normally used only internally or at SXEmacs 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 SXEmacs 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.