+
+A glyph in XEmacs does @strong{NOT} refer to a single unit of textual
+display (the XEmacs term for this is @dfn{rune}), but rather is an
+object encapsulating a graphical element, such as an image or widget (an
+element such as a button or text field; @dfn{widget} is the term for
+this under X Windows, and it's called a @dfn{control} under MS Windows).
+This graphical element could appear in a buffer, a margin, a gutter, or
+a toolbar, or as a mouse pointer or an icon, for example.
+
+Creating a glyph using @code{make-glyph} does not specify @emph{where}
+the glyph will be used, but it does specify @emph{what} the glyph will
+look like. In particular, @var{spec-list} is used to specify this, and it's
+used to initialize the glyph's @code{image} property, which is an image
+specifier. (Note that @dfn{image} as used in the context of a glyph's
+@code{image} property or in the terms @dfn{image specifier}, @dfn{image
+instantiator}, or @dfn{image instance} does not refer to what people
+normally think of as an image (which in XEmacs is called a
+@dfn{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 format of the @var{spec-list} is typically an image instantiator (a string
+or a vector; @ref{Image Specifiers}), but can also be a list of such
+instantiators (each one in turn is tried until an image is successfully
+produced), a cons of a locale (frame, buffer, etc.) and an
+instantiator, a list of such conses, or any other form accepted by
+@code{canonicalize-spec-list}. @xref{Specifiers}, for more information
+about specifiers.
+
+If you're not familiar with specifiers, you should be in order to
+understand how glyphs work. The clearest introduction to specifiers
+is in the Lispref manual, available under Info. (Choose
+Help->Info->Info Contents on the menubar or type C-h i.) You can
+also see @code{make-specifier} for a capsule summary. What's important to
+keep in mind is that a specifier lets you set a different value for
+any particular buffer, window, frame, device, or console. This allows
+for a great deal of flexibility; in particular, 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.), and in these cases you do not create your own glyph, but
+rather modify the existing one.
+
+As well as using @var{spec-list} to initialize the glyph, you can set
+specifications using @code{set-glyph-image}. Note that, due to a
+possibly questionable historical design decision, a glyph itself is not
+actually a specifier, but rather is an object containing an image
+specifier (as well as other, seldom-used properties). Therefore, you
+cannot set or access specifications for the glyph's image by directly
+using @code{set-specifier}, @code{specifier-instance} or the like on the
+glyph; instead use them on @code{(glyph-image @var{glyph})} or use the
+convenience functions @code{set-glyph-image},
+@code{glyph-image-instance}, and @code{glyph-image}.
+
+Once you have created a glyph, you specify where it will be used as
+follows:
+
+@itemize @bullet
+@item
+To insert a glyph into a buffer, create an extent in the buffer and then
+use @code{set-extent-begin-glyph} or @code{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.)
+
+@item
+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
+@code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
+when using margin glyphs with layout policy @code{whitespace}.) Then follow
+the same procedure above for inserting a glyph in a buffer, and then
+set a non-default layout policy for the glyph using
+@code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
+Alternatively, use the high-level annotations API (see
+@code{make-annotation}). (In point of fact, you can also use the annotations
+API for glyphs in a buffer, by setting a layout policy of @code{text}.)
+
+@item
+To insert a glyph into the modeline, just put the glyph directly as one
+of the modeline elements. (Unfortunately you can't currently put a begin
+glyph or end glyph on one of the modeline extents---they're ignored.)
+
+@item
+To insert a glyph into a toolbar, specify it as part of a toolbar
+instantiator (typically set on the specifier @code{default-toolbar}).
+See @code{default-toolbar} for more information. (Note that it is
+standard practice to use a symbol in place of the glyph list in the
+toolbar 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 @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
+and then calling @code{(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.
+
+@item
+To insert a glyph into a gutter, create or modify a gutter instantiator
+(typically set on the specifier @code{default-gutter}). Gutter
+instantiators consist of strings or lists of strings, so to insert a
+glyph, create an extent over the string, and use
+@code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
+glyph to be displayed at the corresponding edge of the extent, just like
+for glyphs in a buffer.
+
+@item
+To use a glyph as the icon for a frame, you do not actually create a new
+glyph; rather, you change the specifications for the existing glyph
+@code{frame-icon-glyph}. (Remember that, because of the specifier nature
+of glyphs, you can set different values for any particular buffer or
+frame.)
+
+@item
+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 @code{text-pointer-glyph} for the pointer used over
+text, @code{modeline-pointer-glyph} for the pointer used over the
+modeline, etc. Do an apropos over @code{*-pointer-glyph} to find all of
+them. (Note also that you can temporarily set the mouse pointer to some
+specific shape by using @code{set-frame-pointer}, which takes an image
+instance, as obtained from calling @code{glyph-image-instance} on a glyph
+of type @code{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 @code{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 @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
+really want to get low-level.)
+
+@item
+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, as for icons and pointers above. See
+@code{continuation-glyph}, @code{control-arrow-glyph},
+@code{hscroll-glyph}, @code{invisible-text-glyph},
+@code{octal-escape-glyph}, and @code{truncation-glyph}. See also
+@code{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
+@code{overlay-arrow-position}.
+
+@item
+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 @code{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 @code{set-face-display-table} and @code{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.
+
+@item
+To use a glyph as the background pixmap of a face: Note that 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. Similarly to how the glyph's image specifier works, you don't
+create your own image specifier, but rather add specifications to the
+existing one (using @code{set-face-background-pixmap}). Note that the
+image instance that is generated in order to actually display the
+background pixmap is of type @code{mono-pixmap}, meaning that it's a
+two-color image and the foreground and background of the image get
+filled in with the corresponding colors from the face.
+@end itemize
+
+It is extremely rare that you will ever have to specify a value for
+@var{type}, which should be one of @code{buffer} (used for glyphs in an
+extent, the modeline, the toolbar, or elsewhere in a buffer),
+@code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
+frame's icon), and defaults to @code{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. @code{text-pointer-glyph} (or in general, @code{*-pointer-glyph})
+and @code{frame-icon-glyph}. @xref{Glyph Types}.
projects / chise / xemacs-chise.git- / blobdiff