+@menu
+* Image Instance Types:: Each image instances has a particular type.
+* Image Instance Functions:: Functions for working with image instances.
+@end menu
+
+
+@node Image Instance Types
+@subsubsection Image Instance Types
+@cindex 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
+
+@table @code
+@item nothing
+Nothing is displayed.
+
+@item 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.
+
+@item 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).
+@item color-pixmap
+
+Displayed as a color pixmap.
+
+@item pointer
+Used as the mouse pointer for a window.
+
+@item 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.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+
+@item widget
+An active GUI element implemented as a ``widget'' or ``control'' of the
+underlying window system.
+@end table
+
+The following functions are used to check whether an image instance type
+is valid in the running XEmacs.
+
+@defun valid-image-instance-type-p type
+This function returns non-@code{nil} if @var{type} is a valid image
+instance type.
+@end defun
+
+@defun image-instance-type-list
+This function returns a list of the valid image instance types.
+@end defun
+
+The following functions are used to determine the type of an image
+instance.
+
+@defun image-instance-type image-instance
+Return the type of the given image instance. The return
+value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
+@code{color-pixmap}, @code{pointer}, @code{subwindow}, or @code{widget}.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+@end defun
+
+@defun text-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{text}.
+@end defun
+
+@defun mono-pixmap-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{mono-pixmap}.
+@end defun
+
+@defun color-pixmap-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{color-pixmap}.
+@end defun
+
+@defun pointer-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{pointer}.
+@end defun
+
+@defun subwindow-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{subwindow}.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+@end defun
+
+@defun nothing-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{nothing}.
+@end defun
+
+@defun widget-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{widget}.
+@end defun
+
+
+@node Image Instance Functions
+@subsubsection Image Instance Functions
+
+@defun make-image-instance data &optional domain dest-types noerror
+This function creates a new image-instance object.
+
+@var{data} is an image instantiator, which describes the image
+(@pxref{Image Specifiers}).
+
+@var{dest-types} should be a list of allowed image instance types that
+can be generated. The @var{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
+
+@table @code
+@item XBM
+@c #### check xface
+@itemx xface
+@code{mono-pixmap}, then @code{color-pixmap}, then @code{pointer}.
+
+@item XPM
+@itemx GIF
+@itemx JPEG
+@itemx PNG
+@itemx TIFF
+@code{color-pixmap}, then @code{mono-pixmap}, then @code{pointer}.
+
+@item string
+@itemx formatted-string formats
+@code{text}, then @code{mono-pixmap} (not currently implemented), then
+@code{color-pixmap} (not currently implemented).
+
+@item mswindows-resource
+For pointer resources, @code{pointer}.
+
+For the others, @code{color-pixmap}.
+@end table
+
+@c #### So what? This is a reference manual, list them, you lazy bastard!
+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 @code{make-image-instance}
+repeatedly until it succeeds, passing less and less preferred
+destination types each time.
+
+If @var{dest-types} is omitted, all possible types are allowed.
+
+@var{domain} specifies the domain to which the image instance will be
+attached. This domain is termed the @dfn{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 @var{domain} (e.g. a frame when a
+window was wanted), an error is signaled. If you specify an overly
+specific @var{domain} (e.g. a window when a device was wanted), the
+corresponding general domain is fetched and used instead. For
+@code{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
+@code{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 @code{inherit}, but we currently disallow this.)
+@c #### We should fix that.
+
+If omitted, @var{domain} defaults to the selected window.
+
+@var{noerror} controls what happens when the image cannot be generated.
+If @code{nil}, an error message is generated. If @code{t}, no messages
+are generated and this function returns @code{nil}. If anything else, a
+warning message is generated and this function returns @code{nil}.
+@end defun
+
+@defun 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 @code{nil} is returned). Otherwise @code{t} is
+returned.
+@end defun
+
+The following functions are
+
+@defun image-instance-name image-instance
+This function returns the name of the given image instance. The name is
+typically taken from the @code{:file} property of the instantiator if
+present, otherwise from the @code{:data} property.
+@end defun
+
+@defun image-instance-domain image-instance
+Return the governing domain of the given @var{image-instance}. The
+governing domain of an image instance is the domain that the image
+instance is specific to. It is @emph{NOT} necessarily the domain that
+was given to the call to @code{specifier-instance} that resulted in the
+creation of this image instance. See @code{make-image-instance} for
+more information on governing domains.
+@end defun
+
+@defun image-instance-string image-instance
+This function returns the string of the given image instance. This will
+only be non-@code{nil} for text image instances.
+@end defun
+
+@defun image-instance-file-name image-instance
+This function returns the file name from which @var{image-instance} was
+read, if known.
+@end defun
+
+@defun image-instance-mask-file-name image-instance
+This function returns the file name from which @var{image-instance}'s
+mask was read, if known.
+@end defun
+
+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.
+
+@defun 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.
+@end defun
+
+@defun image-instance-height image-instance
+This function returns the height of the image instance, in pixels.
+@end defun
+
+@defun image-instance-width image-instance
+This function returns the width of the image instance, in pixels.
+@end defun
+
+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 @code{nil} for a non-pointer image instance.
+
+@defun image-instance-hotspot-x image-instance
+This function returns the X coordinate of the image instance's hotspot,
+if known.
+@end defun
+
+@defun image-instance-hotspot-y image-instance
+This function returns the Y coordinate of the image instance's hotspot,
+if known.
+@end defun
+
+Mono pixmaps and pointers may have their foreground and background
+colors set when instanced. Use these functions to access color
+information.
+
+@defun image-instance-foreground image-instance
+This function returns the foreground color of @var{image-instance}, if
+applicable. This will be a color instance or @code{nil}. (It will only
+be non-@code{nil} for colorized mono pixmaps and for pointers.)
+@end defun
+
+@defun image-instance-background image-instance
+This function returns the background color of @var{image-instance}, if
+applicable. This will be a color instance or @code{nil}. (It will only
+be non-@code{nil} for colorized mono pixmaps and for pointers.)
+@end defun
+
+
+@node Using Glyphs
+@section Using Glyphs
+
+Glyph usage is unfortunately somewhat arcane. (For discussion of
+rationale, @ref{Glyphs,,,Internals}.) 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 @file{edit-toolbar} and @file{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:
+
+@table @strong
+@item Buffer glyphs
+Glyphs that are inserted in a buffer may be used for their own sake (for
+example, image display in @file{w3}), as an accurate representation of
+text that can't be displayed in usual fonts (equation display in
+@file{preview-latex}), or as annotations (such as a marginal indication
+of a bookmark). Glyphs are attached to buffers via extents.
+
+@item Redisplay glyphs
+Glyphs can be used to create XEmacs-specific ``fonts''. For example,
+the character that indicates truncation of lines is implemented as the
+@code{truncation-glyph}. It is also possible to have XEmacs display a
+certain character using a custom glyph, via display tables.
+
+@item 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.
+
+@item 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.
+
+@item 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.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+@end table
+
+Some simple concrete examples showing how to insert a glyph in a
+buffer are presented later. @ref{Glyph Examples}.
+
+``Creating Glyphs'' explains how to create glyphs. Creating a glyph
+using @code{make-glyph} does not specify @emph{where} the glyph will be
+used, it only specifies @emph{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.
+
+@menu
+* Creating Glyphs:: Creating new glyphs.
+* Buffer Glyphs:: Annotations are glyphs that appear in a buffer.
+* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
+* Frame Glyphs:: Displaying glyphs in GUI components of the frame.
+* External Glyphs:: Icons and mouse pointers for the window system.
+* Native GUI Widgets:: Complex active elements treated as a single glyph.
+* Subwindows:: Externally-controlled subwindows in buffers.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+@end menu
+
+@node Creating Glyphs
+@subsection Creating Glyphs
+
+@defun make-glyph &optional spec-list type
+This function creates a new glyph object of type @var{type}.
+
+The optional @var{spec-list} is used to initialize the glyph's image.
+It can be any spec-list of @dfn{image instantiator} accepted by
+@code{canonicalize-spec-list}, @ref{Adding Specifications}. An
+individual image instantiator may be a string, which is converted to a
+vector according to @code{console-type-image-conversion-list}, or a
+vector. The vector's first element specifies the @emph{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. @xref{Image Specifiers}.
+
+The optional @var{type} specifies the type of the glyph. @var{type}
+should be one of @code{buffer} (used for glyphs in an extent, the
+modeline, the toolbar, or elsewhere in a frame), @code{pointer} (used
+for the mouse-pointer), or @code{icon} (used for a frame's icon), and
+defaults to @code{buffer}.
+@end defun
+
+@var{spec-list} is the initializer for 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 most common form of @var{spec-list} is a single image instantiator.
+(@strong{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
+@code{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
+(@emph{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, @emph{etc}. @xref{Specifiers},
+for more information about specification formats.
+
+As well as using @var{spec-list} to initialize the glyph, you can set
+specifications using @code{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 @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}.
+
+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 @emph{internal} format, which is opaque to the user.
+
+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, any
+@samp{*-pointer-glyph}) and @code{frame-icon-glyph}. User code should
+never need to create @code{pointer} or @code{icon} glyphs. @xref{Glyph
+Types}.
+
+There are a few other glyph creation functions, normally used only
+internally or at XEmacs initialization.
+
+@defun make-glyph-internal &optional type
+This function creates a new, uninitialized glyph of type @var{type}.
+@end defun
+
+@defun make-pointer-glyph &optional spec-list
+
+Return a new @code{pointer-glyph} object with the specification list
+@var{spec-list}. This function is equivalent to calling
+@code{make-glyph} with a @var{type} of @code{pointer}.
+@end defun
+
+@code{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
+@code{set-glyph-image} on an existing glyph,
+e.g. @code{text-pointer-glyph}.
+
+@defun make-icon-glyph &optional spec-list
+
+Return a new @code{icon-glyph} object with the specification list
+@var{spec-list}. This function is equivalent to calling
+@code{make-glyph} with a @var{type} of @code{icon}.
+@end defun
+
+@code{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 @code{set-glyph-image}
+on the existing glyph, @code{frame-icon-glyph}.
+
+
+@node Buffer Glyphs
+@subsection Buffer Glyphs
+
+Creating a glyph using @code{make-glyph} does not specify @emph{where}
+the glyph will be used, it only specifies @emph{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 @emph{begin-glyph} or
+@emph{end-glyph}.
+
+@table @code
+@item buffer text
+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 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
+@code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
+when using margin glyphs with layout policy @code{whitespace}.) Follow
+the same procedure above for inserting a glyph in a buffer, 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 fact, you can also use the annotations
+API for glyphs in a buffer, by setting a layout policy of @code{text}.)
+
+@end table
+
+
+@node Redisplay Glyphs
+@subsection 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 @code{set-glyph-image}. 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}.
+
+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. @ref{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 @code{glyph-image}, and then add it to a face.
+@xref{Face Convenience Functions}.
+
+@defvr Glyph truncation-glyph
+This variable specifies what is displayed at the end of truncated lines.
+@end defvr
+
+@defvr Glyph continuation-glyph
+This variable specifies what is displayed at the end of wrapped lines.
+@end defvr
+
+@defvr Glyph octal-escape-glyph
+This variable specifies what to prefix character codes displayed in octal
+with.
+@end defvr
+
+@defvr Glyph hscroll-glyph
+This variable specifies what to display at the beginning of horizontally
+scrolled lines.
+@end defvr
+
+@defvr 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 @code{selective-display-ellipses} or
+@code{buffer-invisibility-spec}). Normally this is three dots (``...'').
+@end defvr
+
+@defvr Glyph control-arrow-glyph
+This variable specifies what to use as an arrow for control characters.
+@end defvr
+
+
+@node Frame Glyphs
+@subsection 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
+@code{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.
+
+@table @code
+@item 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.)
+
+@item 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 @code{default-toolbar}).
+See @code{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 @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, because once an
+image has been displayed the pixmap replaces the symbol for those domains.)
+
+@item gutter
+To insert a glyph into a gutter, use
+@code{set-extent-begin-glyph} or @code{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 @ref{Specifying a Gutter}. Glyphs that are
+frequently used in this way are @code{tab control} and @code{progress
+bar} glyphs.
+
+@end table
+
+
+@node External Glyphs
+@subsection External Glyphs
+@cindex frame icon
+@cindex icon, frame
+@cindex mouse cursor
+@cindex cursor (mouse)
+@cindex pointer (mouse)
+@cindex mouse pointer
+
+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 @xref{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
+@code{frame-icon-glyph} with @code{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 @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 @samp{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.)
+
+You should use @code{set-glyph-image} to set the following variables,
+@emph{not} @code{setq}.
+
+@defvr Glyph text-pointer-glyph
+This variable specifies the shape of the mouse pointer when over text.
+@end defvr
+
+@defvr 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,
+@code{text-pointer-glyph} is used.
+@end defvr
+
+@defvr Glyph modeline-pointer-glyph
+This variable specifies the shape of the mouse pointer when over the modeline.
+If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
+@end defvr
+
+@defvr 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,
+@code{text-pointer-glyph} is used.
+@end defvr
+
+@defvr 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 @code{gc-message}.
+@end defvr
+
+@defvr 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.
+@end defvr
+
+@defvr 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.
+@end defvr
+
+@defvr 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.
+@end defvr
+
+@defvr Glyph toolbar-pointer-glyph
+This variable specifies the shape of the mouse pointer when over a
+toolbar. If unspecified in a particular domain,
+@code{nontext-pointer-glyph} is used.
+@end defvr
+
+Internally, these variables are implemented in
+@code{default-mouse-motion-handler}, and thus only take effect when the
+mouse moves. That function calls @code{set-frame-pointer}, which sets
+the current mouse pointer for a frame.
+
+@defun set-frame-pointer frame image-instance
+This function sets the mouse pointer of @var{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.)
+@end defun
+
+
+@node Native GUI Widgets
+@subsection Native GUI Widgets
+@cindex native widget
+
+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.''
+
+@menu
+* Introduction to Widgets:: Native widgets provide tight integration of
+ GUI features with the platform GUI.
+* Lisp API to Native Widgets:: Native widgets are glyphs.
+* Layouts:: Specifying composite widgets from Lisp.
+* Primitive Widgets:: Catalogue of available native widgets.
+@end menu
+
+@node Introduction to Widgets
+@subsubsection 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 @dfn{native widgets}, in text was added to Lisp. They
+are handled as @emph{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 @emph{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.
+
+@node Lisp API to Native Widgets
+@subsubsection Lisp API to Native Widgets
+
+Native widgets are manipulated as @emph{glyphs} (@pxref{Glyphs}). Thus
+they are created using @code{make-glyph}, with a format of one of the
+widget types and a @code{:data} property specific to the widget being
+instanced.
+
+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 (@emph{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.
+
+@node Layouts
+@subsubsection Layouts
+
+An XEmacs @dfn{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.
+@c #### Fix me!
+(There are also @dfn{native layouts}, but these are undocumented, as are
+their uses.)
+
+A layout descriptor is an image instantiator, @emph{i.e.}, a vector of
+the form @samp{[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]} with format
+@code{layout}, and properties
+
+@c #### need defaults for these
+@table @code
+@item :orientation
+Specifies the orientation of the contained array of glyphs. The value
+must be one of the symbols @code{horizontal} or @code{vertical}.
+
+@item :horizontally-justify
+Specifies the horizontal justification of the items in the array. The
+value must be one of the symbols @code{:right}, @code{:center}, or
+@code{:left}.
+
+@item :vertically-justify
+Specifies the vertical justification of the items in the array. The
+value must be one of the symbols @code{:top}, @code{:center}, or
+@code{:bottom}.
+
+@item :justify
+Specifies justification. #### not understood.
+
+@item :border
+A glyph to place in the border. The value must be an image
+instantiator.
+
+@item :items
+The glyphs controlled by the layout. The value must be a list of image
+instantiators.
+@end table
+
+Here is the specification of the search dialog widget created by
+@code{make-search-dialog} in the @file{dialog-items} library, which
+makes use of recursive layouts.
+
+@example
+(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)))])])])
+@end example
+
+@node Primitive Widgets
+@subsubsection Primitive Widgets
+
+@c #### the following table should be replaced with a menu of nodes
+@table @code
+@item button
+A button widget; either a push button, radio button or toggle
+button.
+
+@item combo-box
+A drop list of selectable items in a widget, for editing text.
+
+@item edit-field
+A text editing widget.
+
+@item label
+A static, text-only, widget; for displaying text.
+
+@item progress-gauge
+A sliding widget, for showing progress.
+
+@item tab-control
+A tab widget; a series of user selectable tabs.