--- a/man/lispref/glyphs.texi	Sun Jul 18 21:50:20 2004 +0000
+++ b/man/lispref/glyphs.texi	Mon Jul 19 08:24:28 2004 +0000
@@ -7,49 +7,1073 @@
 @chapter Glyphs
 @cindex glyphs
 
-  A @dfn{glyph} is an object that is used for pixmaps, widgets and
+  A @dfn{glyph} is an object that is used for pixmaps, widgets, and
 images of all sorts, as well as for things that ``act'' like pixmaps,
 such as non-textual strings (@dfn{annotations}) displayed in a buffer or
 in the margins.  It is used in begin-glyphs and end-glyphs attached to
 extents, marginal and textual annotations, overlay arrows
 (@code{overlay-arrow-*} variables), toolbar buttons, mouse pointers,
 frame icons, truncation and continuation markers, and the
-like. (Basically, any place there is an image or something that acts
-like an image, there will be a glyph object representing it.)
-
-  The actual image that is displayed (as opposed to its position or
-clipping) is defined by an @dfn{image specifier} object contained
-within the glyph.  The separation between an image specifier object
-and a glyph object is made because the glyph includes other properties
-than just the actual image: e.g. the face it is displayed in (for text
-images), the alignment of the image (when it is in a buffer), etc.
+like.  Basically, any place there is an image or something that acts
+like an image, there will be a glyph object representing it.
 
 @defun glyphp object
 This function returns @code{t} if @var{object} is a glyph.
 @end defun
 
 @menu
-* Glyph Functions::	Functions for working with glyphs.
-* Images::		Graphical images displayed in a frame.
-* Glyph Types::         Each glyph has a particular type.
-* Mouse Pointer::	Controlling the mouse pointer.
-* Redisplay Glyphs::    Glyphs controlling various redisplay functions.
-* Native GUI Widgets::  Complex active images treated as a single glyph.
-* Subwindows::          Inserting an externally-controlled subwindow
-                          into a buffer.
-* Glyph Examples::      Examples of how to work with glyphs.
+* Glyph Intro::		Glyphs are abstract image specifications.
+* Images::		Specifying the appearance of glyphs.
+* Using Glyphs::	Creating and displaying glyphs.
+* Manipulating Glyphs::	Getting and setting glyph properties.
+* Glyph Examples::	Examples of how to work with glyphs.
+@end menu
+
+
+@node Glyph Intro
+@section Glyph Introduction
+
+  In XEmacs, ``glyph'' does @strong{not} refer to a single unit of textual
+display (the XEmacs term for that is @dfn{rune}, and runes are confined
+to the internal implementation of redisplay), but rather is an
+object encapsulating a graphical element, such as an image or widget (an
+active GUI element such as a button or text entry field; X11 calls this a
+@dfn{widget}, while MS Windows uses the term @dfn{control}).
+This graphical element could appear in a buffer, a margin, a gutter, or
+a toolbar, or even externally to XEmacs as a mouse pointer or an icon,
+for example.
+
+  On the other hand, by contrast with GNU Emacs 21, an XEmacs glyph is
+not ``just'' an image.  The actual image that is displayed (as opposed
+to its position or clipping) is defined by an ``image specifier'' object
+contained within the glyph.  The separation between an image specifier
+object and a glyph object is made because the glyph includes other
+properties than just the actual image: e.g. the face it is displayed in,
+the alignment of the image, @emph{etc}.  Also, an image specifier is
+used in at least one place in XEmacs in lieu of a glyphs, namely the
+backing pixmap of a face.
+
+  An image specifier is used because glyphs often have locale-specific
+semantics.  The most important example is semantics determined by the
+display device: you can't usefully display a JPEG on stdout, or a color
+image on a monochrome display.  But because the image property is a
+specifier in XEmacs, you can specify that a given glyph appear as a
+monochrome image on monochrome displays, a color image on color
+displays, and as a string on TTYs.  (Specifying a string for the
+@code{tty} device locale would give behavior like the @code{ALT}
+attribute of an @code{IMG} element in HTML.)  Another is semantics
+determined by the buffer or mode.  (Unfortunately, currently there are
+no compelling examples of this for glyphs.)
+
+  All this means that 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.).  Often
+you need not (and should not!) create your own glyph, but rather modify
+an existing one.
+
+  In working with glyphs it is important to keep in mind the distinction
+between a locale and a domain.  A @dfn{locale} is specified by the
+programmer, and is an abstract link between a specification (for a
+glyph, its visual appearance) and a displayable object.  The displayable
+object may be a buffer or a window, or an object containing buffers or
+windows such as frame, device, or console.  A @dfn{domain} is an actual
+display context, which must be concrete enough to enable XEmacs to
+identify the device type.  (Buffers may be displayed in windows on
+different devices, even simultaneously, so a buffer cannot be a domain.
+Similarly, the global locale cannot be a domain.)  @ref{Specifiers}, for
+more information about specifier locales and domains.
+
+
+@node Images
+@section Images
+
+@menu
+* Image Specifiers::			Specifying an image's appearance.
+* Image Instantiator Conversion::	Lazy realization of graphics.
+* Image Instantiator Formats::		A catalog of image descriptors.
+* Image Instances::			Classes of graphical objects.
 @end menu
 
-@node Glyph Functions
-@section Glyph Functions
+
+@node Image Specifiers
+@subsection Image Specifiers
+@cindex image specifiers
+
+  An image specifier is a description of the actual graphical
+realization of a glyph.  For example, a typical image description is
+@emph{the file system path to a PNG file}.  Since redisplay doesn't know
+about files, and in any case the image may need to be manipulated
+(@emph{e.g.}, a face's background pixmap must be clipped and tiled), the
+PNG file must be converted internally to a window system bitmap or
+pixmap object.  We describe this process by writing that when XEmacs
+displays the image, it @dfn{instantiates} the @dfn{image instantiator}
+into an @dfn{image instance}.  Image instances are an internal object
+type (similar to font instances and color instances), describing how the
+image appears in a particular domain.  On the other hand, image
+instantiators, which are just descriptions of how the image should
+appear, are represented using Lisp strings or vectors.
+
+Furthermore the graphical realization will vary, and for some devices
+may not even be a bitmapped graphic.  These variations may be controlled
+by the program by specifying different @dfn{image instantiators} in
+different locales.  This is implemented with an @dfn{image specifier},
+a specifier whose specifications are image instantiators.
+
+Image specifiers are rarely if ever found by themselves.  However, an
+image specifier results from calling @code{glyph-image} on a glyph, or
+retrieving the @code{background-pixmap} property of a face, and you can
+check if some random object is an image specifier.
+
+@defun image-specifier-p object
+This function returns non-@code{nil} if @var{object} is an image specifier.
+@end defun
+
+@defun make-image-specifier spec-list
+This function creates a new image specifier object and initializes it
+according to @var{spec-list}.  @xref{Specifiers}.
+@end defun
+
+This function exists mainly for completeness.  In practice, you rarely,
+if ever, need to actually create an image specifier.  Instead, they are
+implicitly created by the initialization of glyphs and faces, and the
+specifier member of these objects cannot be changed after
+initialization; you may only set the specifications it contains.
+
+Image instantiators come in many formats: @code{xbm}, @code{xpm},
+@code{gif}, @code{jpeg}, etc.  These denote the format of the data
+describing the image.  The resulting image instances also come in many
+types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
+@code{pointer}, etc.  This refers to the behavior of the image and the
+sorts of places it can appear. (For example, a color-pixmap image has
+fixed colors specified for it, while a mono-pixmap image comes in two
+unspecified shades ``foreground'' and ``background'' that are determined
+from the face of the glyph or surrounding text; a text image appears as
+a string of text and has an unspecified foreground, background, and
+font; a pointer image behaves like a mono-pixmap image but can only be
+used as a mouse pointer [mono-pixmap images cannot be used as mouse
+pointers]; etc.)
+
+It is important to keep the distinction between image instantiator
+format and image instance type in mind.  Typically, a given image
+instantiator format can result in many different image instance types.
+For example, @code{xpm} can be instanced as @code{color-pixmap},
+@code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
+instanced only as @code{pointer}.  On the other hand, a particular image
+instance type can be generated by many different image instantiator
+formats (e.g.  @code{color-pixmap} can be generated by @code{xpm},
+@code{gif}, @code{jpeg}, etc.).
+
+  @xref{Image Instances}, for a more detailed discussion of image
+instance types.
+
+ An image instantiator should be a string or a vector of the form
+
+@example
+ @code{[@var{format} @var{:keyword} @var{value} ...]}
+@end example
+
+i.e. a format symbol followed by zero or more alternating keyword-value
+pairs.
+
+The form of an instantiator can be checked with
+@code{valid-instantiator-p} with a @var{TYPE} of @code{image},
+@ref{Specifier Validation Functions}.
+
+For a complete list of the format symbols and their usage,
+@ref{Image Instantiator Formats}.
+
+If the instantiator is a string, it will be converted into a vector by
+looking it up according to the specs in the
+@code{console-type-image-conversion-list} for the console type of the
+domain (usually a window; sometimes a frame or device) over which the
+image is being instantiated.
+
+If the instantiator specifies data from a file, the data will be read in
+at the time that the instantiator is added to the image specifier (which
+may be well before the image is actually displayed), and the
+instantiator will be converted into one of the inline-data forms, with
+the filename retained using a @code{:file} keyword.  This implies that
+the file must exist when the instantiator is added to the image, but
+does not need to exist at any other time (e.g. it may safely be a
+temporary file).
+
+The available keywords are given below.  Note that some keywords are
+generally available (for example, the @code{:data} keyword may be used
+with any format except @code{nothing}), while others are only available
+for one format (@code{resource-id} is unique to the
+@code{mswindows-resource} format).
+
+@table @code
+@item :data
+Inline image data.  If available for a given format, it may be specified
+directly by the program, or it may be a cache of file data previously
+read.  When present, it is used to instantiate the image in preference
+to the file named by the @code{:file} property.
+
+The format of inline data is image-format-specific.  For example, in
+pixmap formats, the value should be a string, which is interpreted as an
+octet-stream representing a bitmap or pixmap.  But for text formats,
+it's string containing the text to be displayed, and for resource
+formats, it's a string containing the name of the resource.
+
+@item :file
+Data contained in a file.  The value is the name of this file.  If both
+@code{:data} and @code{:file} are specified, the image is created from
+what is specified in @code{:data} and the string in @code{:file} becomes
+the value of the @code{image-instance-file-name} function when applied
+to the resulting image-instance.  Note that there is nothing to stop a
+program from changing either the @code{:file} or the @code{:data}
+property, and there is no way to detect such mischief.  This means that
+the data will @emph{not} be automatically reread if you change the
+@code{file} property; you must force it by removing the @code{:data}
+property.
+@c #### If there are ways to do this in-place, describe them.
+(One way to do this is replacing the whole specification with a new
+vector.)  This keyword is not valid for instantiator formats
+@code{nothing}, @code{string}, @code{formatted-string},
+@code{cursor-font}, @code{font}, and @code{autodetect}.
+
+@item :mask-data
+Inline data for @code{xbm} and @code{xface}.  This specifies a mask to
+be used with the bitmap.  Pixels which are not set in the mask will not
+be written to the imaging device.  The format is a list of width,
+height, and bits, as for @code{:data}.
+
+@item :mask-file
+For @code{xbm} and @code{xface}.  This specifies a file containing the
+mask data.  If neither a mask file nor inline mask data is given for an
+XBM image, and the XBM image comes from a file, XEmacs will look for a
+mask file with the same name as the image file but with @samp{Mask} or
+@samp{msk} appended.  For example, if you specify the XBM file
+@file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
+the associated mask file @file{left_ptrmsk} will automatically be picked
+up.
+
+@item :resource-id
+Only for @code{mswindows-resource}.  This must be either an integer
+(which directly specifies a resource number) or a string.  See the
+description of @code{mswindows-resource} for valid strings.  @xref{Image
+Instantiator Formats}.
+
+@item :foreground
+@itemx :background
+For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
+These keywords allow you to explicitly specify foreground and background
+colors.  The value should be anything acceptable to
+@code{make-color-instance}.  This will cause an external format that
+would by default be instantiated as a @code{mono-pixmap} to instead be
+instantiated as a two-color color-pixmap.  This can be used to override
+the colors specified by a glyph's face, for example.  If the image is
+instantiated as a pointer, they specify its foreground and/or
+background, instead of the defaults of black and white.
+
+@item :hotspot-x
+@itemx :hotspot-y
+For @code{xbm} and @code{xface}.  These keywords specify a hotspot if
+the image is instantiated as a @code{pointer}.  Note that if the XBM
+image file specifies a hotspot, it will automatically be picked up if no
+explicit hotspot is given.
+
+@item :color-symbols
+Only for @code{xpm}.  This specifies an alist that maps strings that
+specify symbolic color names to the actual color to be used for that
+symbolic color (in the form of a string or a color-specifier object).
+If this is not specified, the contents of @code{xpm-color-symbols} are
+used to generate the alist.
+
+@item :resource-type
+Only for @code{mswindows-resource}.  This must be a symbol, either
+@code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
+resource to be retrieved.
+
+@item :face
+For @code{inherit} and the widget formats.  This specifies the face to
+inherit from.  For widgets this specifies the face to use for display.
+It defaults to gui-element-face.
+
+@item :selected
+@itemx :active
+@itemx :suffix
+@itemx :keys
+@itemx :style
+@itemx :filter
+@itemx :config
+@itemx :included
+@itemx :key-sequence
+@itemx :accelerator
+@itemx :label
+@itemx :callback
+These keywords, accepted as menu item specs, are also accepted by images
+instantiated as @code{widget}.  For their semantics, @ref{Menu Format}.
+@end table
+
+
+@node Image Instantiator Conversion
+@subsection Image Instantiator Conversion
+@cindex image instantiator conversion
+@cindex conversion of image instantiators
+
+Conversion is applied to image instantiators at the time they are added
+to an image specifier or at the time they are passed to
+@code{make-image-instance}.
+
+@defun set-console-type-image-conversion-list console-type list
+This function sets the image-conversion-list for consoles of the given
+@var{console-type}.  The image-conversion-list specifies how image
+instantiators that are strings should be interpreted.  Each element of
+the list should be a list of two elements (a regular expression string
+and a vector) or a list of three elements (the preceding two plus an
+integer index into the vector).  The string is converted to the vector
+associated with the first matching regular expression.  If a vector
+index is specified, the string itself is substituted into that position
+in the vector.
+
+Note: The conversion above is applied when the image instantiator is
+added to an image specifier, not when the specifier is actually
+instantiated.  Therefore, changing the image-conversion-list only affects
+newly-added instantiators.  Existing instantiators in glyphs and image
+specifiers will not be affected.
+@end defun
+
+@defun console-type-image-conversion-list console-type
+This function returns the image-conversion-list for consoles of the given
+@var{console-type}.
+@end defun
+
+
+@node Image Instantiator Formats
+@subsection Image Instantiator Formats
+@cindex image instantiator formats
+
+The @dfn{format} field of an image instantiator should be a symbol
+denoting a valid format.  Which formats are valid will depend on the
+features (such as image decoding libraries) available, on platform
+support (MS Windows resource IDs make no sense on other platforms), and
+on the locale.
+
+@defun valid-image-instantiator-format-p format &optional locale
+This function returns non-@code{nil} if @var{format} is a valid image
+instantiator format.
+
+If @var{locale} is non-@code{nil} then the format is checked in that locale.
+If @var{locale} is @code{nil} the current console is used.
+
+Note that the return value for many formats listed above depends on
+whether XEmacs was compiled with support for that format.
+@end defun
+
+@defun image-instantiator-format-list
+This function returns a list of valid image-instantiator formats.
+@end defun
+
+Here is a table of image-instantiator formats, giving the keywords that
+are usable with each, and the kinds of instances that may result.
+
+@table @code
+@item nothing
+Don't display anything; no keywords are valid for this format.  Can only be
+instanced as @code{nothing}.
+
+@item string
+Display this image as a text string.  Can only be instanced
+as @code{text}, although support for instancing as @code{mono-pixmap}
+should be added.  The valid keyword is @code{:data}.  The value should
+be a string, and it is interpreted as a string of characters.
+
+@item formatted-string
+Display this image as a text string with replaceable fields,
+similar to a modeline format string.  The valid keyword is @code{:data}.
+The value should be a string, and it is interpreted as a string of
+characters containing format sequences.
+
+Not currently implemented.
+
+@item xbm
+An X bitmap; available only if X support was compiled into this XEmacs.
+
+If used in a buffer glyph, icon glyph, or face background pixmap, it
+will be instantiated as @code{mono-pixmap} unless the @code{:foreground}
+or @code{:background} keywords are present.  In the latter case it will
+be instantiated as @code{color-pixmap} with the two specified colors.
+@c #### Check this.
+(Probably if @code{:foreground} or @code{:background} is omitted, it
+defaults to black or white respectively.)  If used in a pointer glyph,
+it will be instantiated as an @code{pointer}.
+
+The valid keywords and their values are
+@table @code
+@item :data
+A list containing the height and width of the bitmap as integers, and
+a string interpreted as a bit vector according to the X11 standard XBM
+bitmap format, in that order.
+@item :file
+The name of a file containing standard XBM-format data.  If it contains
+a hotspot specification, it will be parsed and used if the hotspot is
+not explicitly specified.
+@item :mask-data
+A list containing the height and width of the bitmap as integers, and
+a string interpreted as a bit vector according to the X11 standard XBM
+bitmap format, in that order.  This bitmap is interpreted as the
+clipping region for the bitmap contained in the @code{:data} property.
+@item :mask-file
+The name of a file containing standard XBM-format data.  Interpreted as
+the clipping region for the bitmap contained in the @code{:data} property.
+@item :foreground
+@itemx :background
+These keywords allow you to explicitly specify foreground and background
+colors.  The values should be acceptable to @code{make-color-instance}.
+@item :hotspot-x
+@itemx :hotspot-y
+Integers denoting the hotspot (mouse pointer position), with (0,0) at
+the top left corner.  If given, these override any specification in the
+XBM file.
+@end table
+
+@item xpm
+An XPM pixmap; only available if XPM support was compiled into this XEmacs.
+
+Can be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
+@code{pointer}.
+
+XPM is an add-on library for X that was designed to rectify the
+shortcomings of the XBM format.  Many icons and labels used in the
+XEmacs GUI are still distributed in XPM format (although we are moving
+to standardize on the PNG format).  It is therefore highly desirable
+that XPM be available in your XEmacs.
+
+Most implementations of X include the XPM library as a standard part.
+If your vendor does not, it is highly recommended that you download it
+and install it.  You can get it from the XEmacs FTP site and mirrors, as
+well as from most sites that distribute X11.
+
+The valid keywords and their values are
+@table @code
+@item :data
+A string interpreted as the contents of a standard XPM file.
+@item :file
+The name of a file containing standard XPM-format data.  If it contains
+a hotspot specification, it will be parsed and used if the hotspot is
+not explicitly specified.
+@c #### Does XPM provide for a hotspot?
+@item :hotspot-x
+@itemx :hotspot-y
+Integers denoting the hotspot (mouse pointer position), with (0,0) at
+the top left corner.  If given, these override any specification in the
+XBM file.
+@c #### Check this.
+(This may not be true.  The original documentation doesn't mention them
+in connection with XPM, but a pointer needs a hotspot.)
+@item :color-symbols
+An alist that maps the one- or two-character strings that specify
+symbolic color names in the XPM file to the actual color to be used for
+that symbolic color (in the form of a string acceptable as a color
+instantiator, @ref{Color Specifiers}, or a color-specifier object).
+If this is not specified, the contents of @code{xpm-color-symbols} are
+used to generate the alist.
+@end table
+
+@item xface
+An X-Face bitmap, used to encode people's faces in e-mail messages;
+only available if X-Face support was compiled into this XEmacs.
+
+Will be instanced as @code{mono-pixmap}, @code{color-pixmap}, or
+@code{pointer}, depending on the target instance type and the presence
+of color keywords.
+
+The valid keywords and their values are
+@table @code
+@item :data
+A list containing the height and width of the bitmap as integers, and
+a string interpreted as a bit vector according to the X11 standard XBM
+bitmap format, in that order.
+@item :file
+The name of a file containing standard XBM-format data.  If it contains
+a hotspot specification, it will be parsed and used if the hotspot is
+not explicitly specified.
+@item :mask-data
+A list containing the height and width of the bitmap as integers, and
+a string interpreted as a bit vector according to the X11 standard XBM
+bitmap format, in that order.  This bitmap is interpreted as the
+clipping region for the bitmap contained in the @code{:data} property.
+@item :mask-file
+The name of a file containing standard XBM-format data.  Interpreted as
+the clipping region for the bitmap contained in the @code{:data} property.
+@item :foreground
+@itemx :background
+These keywords allow you to explicitly specify foreground and background
+colors.  The values should be acceptable to @code{make-color-instance}.
+@item :hotspot-x
+@itemx :hotspot-y
+Integers denoting the hotspot (mouse pointer position), with (0,0) at
+the top left corner.  If given, these override any specification in the
+XBM file.
+@end table
+
+@item gif
+@itemx jpeg
+@itemx png
+@itemx tiff
+These are GIF87- or GIF89-format, JPEG-format, PNG/GIF24-format, and
+TIFF-format images, respectively.  They are available only if
+appropriate decoding support was built into XEmacs.  XEmacs includes GIF
+decoding functions as a standard part of it, so if you have X support,
+you will normally have GIF support, unless you explicitly disable it at
+configure time.  If you have development support (both the libraries and
+the relevant C header files) available when XEmacs is built, the JPEG,
+PNG, and TIFF libraries will automatically be detected (in the ``usual
+places'') and linked into the build.
+
+Note that PNG is the standard format for images distributed with XEmacs,
+so it is highly recommended that PNG support be built in.
+
+All of these instantiators will be instanced as @code{color-pixmap}.
+
+The valid keywords and their values are
+@table @code
+@item :data
+A string interpreted as the contents of a file containing data in the
+appropriate standard format.
+@item :file
+The name of a file containing standard-format data.
+@end table
+
+@item cursor-font
+Most window systems provide a set of standard cursors, which in X11 is
+called a cursor font.  Can only be instanced as @code{pointer}.  This
+should probably be fixed.
+
+The valid keyword is @code{:data}.  Its value should be a string
+containing one of the standard cursor-font names, such as @samp{watch}
+or @samp{right_ptr} under X.  More specifically, in the X Window System
+it may be any of the standard cursor names from appendix B of the Xlib
+manual, provided in the file @file{<X11/cursorfont.h>} by most
+distributions, minus the @samp{XC_} prefix.  For MS Windows, use
+@code{mswindows-resource} instantiator format, not @code{cursor-font}.
+Other window systems may have different lists.
+
+@item font
+A glyph from a font; i.e. the name of a font, and glyph index into it
+of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
+Only if X support was compiled into this XEmacs.  Currently can only be
+instanced as @code{pointer}.  This should probably be fixed.
+@c #### The above description is not very helpful, so it's not obvious
+@c how to instantiate a font image.
+
+@item mswindows-resource
+An MS Windows pointer resource.  Specifies a resource to retrieve
+directly from the system (an OEM resource) or from a file, particularly
+an executable file.  Can be instanced as @code{pointer} or
+@code{color-pixmap}.
+
+The valid keywords and their values are
+
+@table @code
+@item :resource-type
+A string naming the type (@code{cursor}, @code{bitmap}, or @code{icon})
+of the resource.  Required.
+@item :file
+A string containing the name of the file containing the resource (often
+an executable).  If a system resource, @code{:file} should be omitted.
+@item :resource-id
+A string containing the name of a resource.   Required if @code{:file}
+is not specified.
+
+This must be either an integer (which directly specifies a resource
+number) or a string.  Valid strings are
+
+For bitmaps:
+
+"close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
+"reduce", "zoom", "restore", "reduced", "zoomd",
+"restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd",
+"mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi",
+"lfarrowi", "size", "btsize", "check", "checkboxes", and
+"btncorners".
+
+For cursors:
+
+"normal", "ibeam", "wait", "cross", "up", "sizenwse",
+"sizenesw", "sizewe", "sizens", "sizeall", and "no".
+
+For icons:
+
+"sample", "hand", "ques", "bang", "note", and "winlogo".
+@end table
+
+@item subwindow
+An embedded windowing system window.  Can only be instanced as
+@code{subwindow}.  Not implemented.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+
+@item button
+A button widget; either a push button, radio button or toggle button.
+Can only be instanced as @code{widget}.
+
+@item combo-box
+A drop list of selectable items in a widget, for editing text.
+Can only be instanced as @code{widget}.
+
+@item edit-field
+A text editing widget.  Can only be instanced as @code{widget}.
+
+@item label
+A static, text-only, widget; for displaying text.  Can only be instanced
+as @code{widget}.
+
+@item layout
+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 @dfn{glyph} and could appear
+in many of the places that expect a single glyph.  Can only be instanced
+as @code{widget}.
+
+@item native-layout
+The native version of a layout widget.
+Can only be instanced as @code{widget}.
+
+@item progress-gauge
+A sliding widget, for showing progress.  Can only be instanced as
+@code{widget}.
+
+@item tab-control
+A tab widget; a series of user selectable tabs.  Can only be instanced
+as @code{widget}.
+
+@item tree-view
+A folding widget.  Can only be instanced as @code{widget}.
+
+@item scrollbar
+A scrollbar widget.  Can only be instanced as @code{widget}.
+
+@item autodetect
+XEmacs tries to guess what format the data is in.  If X support exists,
+the data string will be checked to see if it names a filename.  If so,
+and this filename contains XBM or XPM data, the appropriate sort of
+pixmap or pointer will be created. [This includes picking up any
+specified hotspot or associated mask file.] Otherwise, if @code{pointer}
+is one of the allowable image-instance types and the string names a
+valid cursor-font name, the image will be created as a pointer.
+Otherwise, the image will be displayed as text.  If no X support exists,
+the image will always be displayed as text.
+
+@item inherit
+Inherit from the background-pixmap property of a face.  Can only be
+instanced as @code{mono-pixmap}.
+@end table
+
+There are two convenience variables for use with the XBM and XPM image
+formats.
+
+@defvar xpm-color-symbols
+This variable holds definitions of logical color-names used when reading
+XPM files.  Elements of this list should be of the form
+@code{(@var{color-name} @var{form-to-evaluate})}.  The @var{color-name}
+should be a string, which is the name of the color to define; the
+@var{form-to-evaluate} should evaluate to a color specifier object, or a
+string to be passed to @code{make-color-instance} (@pxref{Colors}).  If
+a loaded XPM file references a symbolic color called @var{color-name},
+it will display as the computed color instead.
+
+The default value of this variable defines the logical color names
+@samp{"foreground"} and @samp{"background"} to be the colors of the
+@code{default} face.
+@end defvar
+
+@defvar x-bitmap-file-path
+A list of the directories in which X bitmap files may be found.  If @code{nil},
+this is initialized from the @samp{"*bitmapFilePath"} resource.  This is
+used by the @code{make-image-instance} function (however, note that if
+the environment variable @samp{XBMLANGPATH} is set, it is consulted
+first).
+@end defvar
+
+
+@node Image Instances
+@subsection Image Instances
+@cindex image instances
+
+  Image-instance objects encapsulate the way a particular image (pixmap,
+etc.) is displayed on a particular device.
+
+  In most circumstances, you do not need to directly create image
+instances; use a glyph instead.  However, it may occasionally be useful
+to explicitly create image instances, if you want more control over the
+instantiation process.
+
+@defun image-instance-p object
+This function returns non-@code{nil} if @var{object} is an image instance.
+@end defun
+
+@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, the favicons are 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.
-* Glyph Properties::	Accessing and modifying a glyph's properties.
-* Glyph Convenience Functions::
-			Convenience functions for accessing particular
-			  properties of a glyph.
-* Glyph Dimensions::    Determining the height, width, etc. of a glyph.
+* 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
@@ -58,113 +1082,219 @@
 @defun make-glyph &optional spec-list type
 This function creates a new glyph object of type @var{type}.
 
-@var{spec-list} is used to initialize the glyph's image.  It 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.
+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}.
 
-@var{type} specifies the type of the glyph, which specifies in which
-contexts the glyph can be used, and controls the allowable image types
-into which the glyph's image can be instantiated.  @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}.  @xref{Glyph Types}.
+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
 
-A glyph in XEmacs does @strong{NOT} refer to a single unit of textual
-display (the XEmacs term for this is @dfn{rune}, and runes are confined
-to the internal implementation of redisplay), but rather is an
-object encapsulating a graphical element, such as an image or widget (an
-element such as a button or text entry field; @dfn{widget} is the term for
-this under X Windows, while @dfn{control} is the term 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.
+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, but it does specify @emph{what} the glyph will
-look like.  @var{spec-list} is used to specify this, and it 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 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}.
+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}.
 
-Some understanding of specifiers is necessary in working with glyphs,
-because they do not behave like ordinary variables, and are accessed and
-mutated with special APIs.  @xref{Specifiers}, for more information
-about specifiers.  The docstring of
-@code{make-specifier} gives a capsule summary.  The most important
-aspect of specifiers is that a specifier lets you set a value for
-each buffer, window, frame, device, or console, or it will compute an
-appropriate default if no specific value is set for a particular
-@emph{locale} or @emph{domain} (display contexts; locales are used by
-the programmer create an abstract link between an object such as a
-buffer position and an image, while domains must be concrete enough to
-enable XEmacs to identify the device type: you can't
-usefully display a JPEG on stdout).  Therefore 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.  You can specify that a given glyph
-appear as a monochrome image on monochrome displays, a color image on
-color displays, and as a string on TTYs.
-
-As well as using @var{spec-list} to initialize the glyph, you can set
-specifications using @code{set-glyph-image}.  Due to an
-arguable 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 by
-attaching it to an extent as a @emph{begin-glyph} or @emph{end-glyph}.
-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 and the glyph that
-denotes a line truncation.  Frame icons, toolbar button icons, and the
-modeline are the main non-text objects which accept glyphs as elements.
-
-@itemize @bullet
-@item
+@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
+a glyph to be displayed at the corresponding edge of the extent.  (It is
 common to create zero-width extents for this purpose.)
 
-@item
+@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}.) Then follow
-the same procedure above for inserting a glyph in a buffer, and then
+@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
+@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}.)
 
-@item
+@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
+@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}).
@@ -180,20 +1310,45 @@
 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
+@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}.
+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
 
-@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}.  (This is a unique, predefined object.
-Remember that, because of the specifier nature of glyphs, you can set
-different values for any particular buffer or frame.)
+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}.
 
-@item
+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
@@ -212,76 +1367,295 @@
 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}.
+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
 
-@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.
+@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
 
-@item
-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}.
-@end itemize
+@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
 
-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}.  @xref{Glyph Types}.
+@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
 
-@defun make-glyph-internal &optional type
-This function creates a new, uninitialized glyph of type @var{type}.
+
+@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.
+
+(There are also @dfn{native layouts}, but I don't know what these are or
+how they are used.)
+
+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.
+
+@item tree-view
+A folding widget.
+
+@item scrollbar
+A scrollbar widget.  (#### Probably not the same as the scrollbar
+controlling an Emacs window.)
+@end table
+
+
+@node Subwindows
+@subsection Subwindows
+
+Subwindows are not currently implemented.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+
+@defun subwindowp object
+This function returns non-@code{nil} if @var{object} is a subwindow.
 @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}.
-
-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}.
-@end defun
+@node Manipulating Glyphs
+@section Manipulating Glyphs
 
-@defun make-icon-glyph &optional spec-list
+  Each glyphs has properties that may be accessed.  Most of these can
+also be set after the glyph is initialized, with the exception of the
+glyph's type.  This is not a real restriction, as it is almost never
+useful to create glyphs of types other than @code{buffer}.
 
-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{icon}.
+@menu
+* Glyph Properties::	Accessing and modifying a glyph's properties.
+* Glyph Convenience Functions::  Accessing particular properties of a glyph.
+* Glyph Dimensions::	Determining the height, width, etc. of a glyph.
+* Glyph Types::		Each glyph has a particular type.
+@end menu
 
-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 the existing glyph, @code{frame-icon-glyph}.
-@end defun
 
 @node Glyph Properties
 @subsection Glyph Properties
@@ -310,10 +1684,12 @@
 
 For built-in properties, the actual value of the property is a specifier
 and you cannot change this; but you can change the specifications within
-the specifier, and that is what this function will do.  For user-defined
-properties, you can use this function to either change the actual value
-of the property or, if this value is a specifier, change the
-specifications within it.
+the specifier, and that is what this function will do.  The glyph face
+is an exception; it is a face name (a symbol) or a face object, not a
+specifier.  (The face properties themselves are typically specifiers.)
+For user-defined properties, you can use this function to either change
+the actual value of the property or, if this value is a specifier,
+change the specifications within it.
 
 If @var{property} is a built-in property, the specifications to be added
 to this property can be supplied in many different ways:
@@ -462,6 +1838,7 @@
 and @var{exact-p} arguments.
 @end defun
 
+
 @node Glyph Convenience Functions
 @subsection Glyph Convenience Functions
 
@@ -553,6 +1930,7 @@
 This function changes the face of @var{glyph} to @var{face}.
 @end defun
 
+
 @node Glyph Dimensions
 @subsection Glyph Dimensions
 
@@ -581,640 +1959,9 @@
 redisplay will.
 @end defun
 
-@node Images
-@section Images
-
-@menu
-* Image Specifiers::		Specifying how an image will appear.
-* Image Instantiator Conversion::
-				Conversion is applied to image instantiators
-				  at the time they are added to an
-				  image specifier or at the time they
-				  are passed to @code{make-image-instance}.
-* Image Instances::		What an image specifier gets instanced as.
-@end menu
-
-@node Image Specifiers
-@subsection Image Specifiers
-@cindex image specifiers
-
-  An image specifier is used to describe the actual image of a glyph.
-It works like other specifiers (@pxref{Specifiers}), in that it contains
-a number of specifications describing how the image should appear in a
-variety of circumstances.  These specifications are called @dfn{image
-instantiators}.  When XEmacs wants to display the image, it instantiates
-the image into an @dfn{image instance}.  Image instances are their own
-primitive object type (similar to font instances and color instances),
-describing how the image appears in a particular domain. (On the other
-hand, image instantiators, which are just descriptions of how the image
-should appear, are represented using strings or vectors.)
-
-@defun image-specifier-p object
-This function returns non-@code{nil} if @var{object} is an image specifier.
-Usually, an image specifier results from calling @code{glyph-image} on
-a glyph.
-@end defun
-
-@defun make-image-specifier spec-list
-This function creates a new image specifier object and initializes it
-according to @var{spec-list}. @xref{Specifiers}.
-
-Note that, in practice, you rarely, if ever, need to actually create an
-image specifier! (This function exists mainly for completeness.) Pretty
-much the only use for image specifiers is to control how glyphs are
-displayed, and the image specifier associated with a glyph (the
-@code{image} property of a glyph) is created automatically when a glyph
-is created and need not (and cannot, for that matter) ever be changed
-(@pxref{Glyphs}).  In fact, the design decision to create a separate
-image specifier type, rather than make glyphs themselves be specifiers,
-is debatable---the other properties of glyphs are rarely used and could
-conceivably have been incorporated into the glyph's instantiator.  The
-rarely used glyph types (buffer, pointer, icon) could also have been
-incorporated into the instantiator.
-@end defun
-
-  Image instantiators come in many formats: @code{xbm}, @code{xpm},
-@code{gif}, @code{jpeg}, etc.  This describes the format of the data
-describing the image.  The resulting image instances also come in many
-types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
-@code{pointer}, etc.  This refers to the behavior of the image and the
-sorts of places it can appear. (For example, a color-pixmap image has
-fixed colors specified for it, while a mono-pixmap image comes in two
-unspecified shades ``foreground'' and ``background'' that are determined
-from the face of the glyph or surrounding text; a text image appears as
-a string of text and has an unspecified foreground, background, and
-font; a pointer image behaves like a mono-pixmap image but can only be
-used as a mouse pointer [mono-pixmap images cannot be used as mouse
-pointers]; etc.) It is important to keep the distinction between image
-instantiator format and image instance type in mind.  Typically, a given
-image instantiator format can result in many different image instance
-types (for example, @code{xpm} can be instanced as @code{color-pixmap},
-@code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
-instanced only as @code{pointer}), and a particular image instance type
-can be generated by many different image instantiator formats (e.g.
-@code{color-pixmap} can be generated by @code{xpm}, @code{gif},
-@code{jpeg}, etc.).
-
-  @xref{Image Instances}, for a more detailed discussion of image
-instance types.
-
-  An image instantiator should be a string or a vector of the form
-
-@example
- @code{[@var{format} @var{:keyword} @var{value} ...]}
-@end example
-
-i.e. a format symbol followed by zero or more alternating keyword-value
-pairs.  The @dfn{format} field should be a symbol, one of
-
-@table @code
-@item nothing
-Don't display anything; no keywords are valid for this.  Can only be
-instanced as @code{nothing}.
-@item string
-Display this image as a text string.  Can only be instanced
-as @code{text}, although support for instancing as @code{mono-pixmap}
-should be added.
-@item formatted-string
-Display this image as a text string with replaceable fields,
-similar to a modeline format string; not currently implemented.
-@item xbm
-An X bitmap; only if X support was compiled into this XEmacs.  Can be
-instanced as @code{mono-pixmap}, @code{color-pixmap}, or
-@code{pointer}.
-@item xpm
-An XPM pixmap; only if XPM support was compiled into this XEmacs.  Can
-be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
-@code{pointer}.  XPM is an add-on library for X that was designed to
-rectify the shortcomings of the XBM format.  Most implementations of X
-include the XPM library as a standard part.  If your vendor does not, it
-is highly recommended that you download it and install it.  You can get
-it from the standard XEmacs FTP site, among other places.
-@item xface
-An X-Face bitmap, used to encode people's faces in e-mail messages;
-only if X-Face support was compiled into this XEmacs.  Can be instanced
-as @code{mono-pixmap}, @code{color-pixmap}, or @code{pointer}.
-@item gif
-A GIF87 or GIF89 image; only if GIF support was compiled into this
-XEmacs.  Can be instanced as @code{color-pixmap}.  Note that XEmacs
-includes GIF decoding functions as a standard part of it, so if you have
-X support, you will normally have GIF support, unless you explicitly
-disable it at configure time.
-@item jpeg
-A JPEG-format image; only if JPEG support was compiled into this
-XEmacs.  Can be instanced as @code{color-pixmap}.  If you have the JPEG
-libraries present on your system when XEmacs is built, XEmacs will
-automatically detect this and use them, unless you explicitly disable it
-at configure time.
-@item png
-A PNG/GIF24 image; only if PNG support was compiled into this XEmacs.
-Can be instanced as @code{color-pixmap}.
-@item tiff
-A TIFF-format image; only if TIFF support was compiled into this XEmacs.
-@item cursor-font
-One of the standard cursor-font names, such as @samp{watch} or
-@samp{right_ptr} under X.  Under X, this is, more specifically, any of
-the standard cursor names from appendix B of the Xlib manual [also known
-as the file @file{<X11/cursorfont.h>}] minus the @samp{XC_} prefix.  On
-other window systems, the valid names will be specific to the type of
-window system.  Can only be instanced as @code{pointer}.
-@item font
-A glyph from a font; i.e. the name of a font, and glyph index into it
-of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
-Only if X support was compiled into this XEmacs.  Currently can only be
-instanced as @code{pointer}, although this should probably be fixed.
-@item mswindows-resource
-An MS Windows pointer resource.  Specifies a resource to retrieve
-directly from the system (an OEM resource) or from a file, particularly
-an executable file.  If the resource is to be retrieved from a file, use
-:file and optionally :resource-id.  Otherwise use :resource-id.  Always
-specify :resource-type to specify the type (cursor, bitmap or icon) of
-the resource.  Possible values for :resource-id are listed below.  Can
-be instanced as @code{pointer} or @code{color-pixmap}.
-@item subwindow
-An embedded windowing system window.  Can only be instanced as
-@code{subwindow}.
-@item button
-A button widget; either a push button, radio button or toggle button.
-Can only be instanced as @code{widget}.
-@item combo-box
-A drop list of selectable items in a widget, for editing text.
-Can only be instanced as @code{widget}.
-@item edit-field
-A text editing widget.  Can only be instanced as @code{widget}.
-@item label
-A static, text-only, widget; for displaying text.  Can only be instanced
-as @code{widget}.
-@item layout
-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 @dfn{glyph} and could appear
-in many of the places that expect a single glyph.  Can only be instanced
-as @code{widget}.
-@item native-layout
-@c   #### Document me better!
-The native version of a layout widget.
-Can only be instanced as @code{widget}.
-@item progress-gauge
-A sliding widget, for showing progress.  Can only be instanced as
-@code{widget}.
-@item tab-control
-A tab widget; a series of user selectable tabs.  Can only be instanced
-as @code{widget}.
-@item tree-view
-A folding widget.  Can only be instanced as @code{widget}.
-@item scrollbar
-A scrollbar widget.  Can only be instanced as @code{widget}.
-@item autodetect
-XEmacs tries to guess what format the data is in.  If X support exists,
-the data string will be checked to see if it names a filename.  If so,
-and this filename contains XBM or XPM data, the appropriate sort of
-pixmap or pointer will be created. [This includes picking up any
-specified hotspot or associated mask file.] Otherwise, if @code{pointer}
-is one of the allowable image-instance types and the string names a
-valid cursor-font name, the image will be created as a pointer.
-Otherwise, the image will be displayed as text.  If no X support exists,
-the image will always be displayed as text.
-@item inherit
-Inherit from the background-pixmap property of a face.  Can only be
-instanced as @code{mono-pixmap}.
-@end table
-
-The valid keywords are:
-
-@table @code
-@item :data
-Inline data.  For most formats above, this should be a string.  For
-XBM images, this should be a list of three elements: width, height, and
-a string of bit data.  This keyword is not valid for instantiator
-format @code{nothing}.
-
-@item :file
-Data is contained in a file.  The value is the name of this file.  If
-both @code{:data} and @code{:file} are specified, the image is created
-from what is specified in @code{:data} and the string in @code{:file}
-becomes the value of the @code{image-instance-file-name} function when
-applied to the resulting image-instance.  This keyword is not valid for
-instantiator formats @code{nothing}, @code{string},
-@code{formatted-string}, @code{cursor-font}, @code{font}, and
-@code{autodetect}.
-
-@item :foreground
-@itemx :background
-For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
-These keywords allow you to explicitly specify foreground and background
-colors.  The argument should be anything acceptable to
-@code{make-color-instance}.  This will cause what would be a
-@code{mono-pixmap} to instead be colorized as a two-color color-pixmap,
-and specifies the foreground and/or background colors for a pointer
-instead of black and white.
-
-@item :mask-data
-For @code{xbm} and @code{xface}.  This specifies a mask to be used with the
-bitmap.  The format is a list of width, height, and bits, like for
-@code{:data}.
-
-@item :mask-file
-For @code{xbm} and @code{xface}.  This specifies a file containing the
-mask data.  If neither a mask file nor inline mask data is given for an
-XBM image, and the XBM image comes from a file, XEmacs will look for a
-mask file with the same name as the image file but with @samp{Mask} or
-@samp{msk} appended.  For example, if you specify the XBM file
-@file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
-the associated mask file @file{left_ptrmsk} will automatically be picked
-up.
-
-@item :hotspot-x
-@itemx :hotspot-y
-For @code{xbm} and @code{xface}.  These keywords specify a hotspot if
-the image is instantiated as a @code{pointer}.  Note that if the XBM
-image file specifies a hotspot, it will automatically be picked up if no
-explicit hotspot is given.
-
-@item :color-symbols
-Only for @code{xpm}.  This specifies an alist that maps strings that
-specify symbolic color names to the actual color to be used for that
-symbolic color (in the form of a string or a color-specifier object).
-If this is not specified, the contents of @code{xpm-color-symbols} are
-used to generate the alist.
-@item :resource-id
-Only for @code{mswindows-resource}.  This must be either an integer
-(which directly specifies a resource number) or a string.  Valid strings
-are
-
-For bitmaps:
-
-"close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
-"reduce", "zoom", "restore", "reduced", "zoomd",
-"restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd",
-"mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi",
-"lfarrowi", "size", "btsize", "check", "checkboxes", and
-"btncorners".
-
-For cursors:
-
-"normal", "ibeam", "wait", "cross", "up", "sizenwse",
-"sizenesw", "sizewe", "sizens", "sizeall", and "no".
-
-For icons:
-
-"sample", "hand", "ques", "bang", "note", and "winlogo".
-@item :resource-type
-Only for @code{mswindows-resource}.  This must be a symbol, either
-@code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
-resource to be retrieved.
-@item :face
-Only for @code{inherit}.  This specifies the face to inherit from.  For
-widgets this also specifies the face to use for display. It defaults to
-gui-element-face.
-@end table
-
-Keywords accepted as menu item specs are also accepted by widgets.
-These are @code{:selected}, @code{:active}, @code{:suffix},
-@code{:keys}, @code{:style}, @code{:filter}, @code{:config},
-@code{:included}, @code{:key-sequence}, @code{:accelerator},
-@code{:label} and @code{:callback}.
-
-If instead of a vector, the instantiator is a string, it will be
-converted into a vector by looking it up according to the specs in the
-@code{console-type-image-conversion-list} for the console type of
-the domain (usually a window; sometimes a frame or device) over which
-the image is being instantiated.
-
-If the instantiator specifies data from a file, the data will be read in
-at the time that the instantiator is added to the image specifier (which
-may be well before the image is actually displayed), and the
-instantiator will be converted into one of the inline-data forms, with
-the filename retained using a @code{:file} keyword.  This implies that
-the file must exist when the instantiator is added to the image, but
-does not need to exist at any other time (e.g. it may safely be a
-temporary file).
-
-@defun valid-image-instantiator-format-p format &optional locale
-This function returns non-@code{nil} if @var{format} is a valid image
-instantiator format.
-
-If @var{locale} is non-@code{nil} then the format is checked in that locale.
-If @var{locale} is @code{nil} the current console is used.
-
-Note that the return value for many formats listed above depends on
-whether XEmacs was compiled with support for that format.
-@end defun
-
-@defun image-instantiator-format-list
-This function return a list of valid image-instantiator formats.
-@end defun
-
-@defvar xpm-color-symbols
-This variable holds definitions of logical color-names used when reading
-XPM files.  Elements of this list should be of the form
-@code{(@var{color-name} @var{form-to-evaluate})}.  The @var{color-name}
-should be a string, which is the name of the color to define; the
-@var{form-to-evaluate} should evaluate to a color specifier object, or a
-string to be passed to @code{make-color-instance} (@pxref{Colors}).  If
-a loaded XPM file references a symbolic color called @var{color-name},
-it will display as the computed color instead.
-
-The default value of this variable defines the logical color names
-@samp{"foreground"} and @samp{"background"} to be the colors of the
-@code{default} face.
-@end defvar
-
-@defvar x-bitmap-file-path
-A list of the directories in which X bitmap files may be found.  If @code{nil},
-this is initialized from the @samp{"*bitmapFilePath"} resource.  This is
-used by the @code{make-image-instance} function (however, note that if
-the environment variable @samp{XBMLANGPATH} is set, it is consulted
-first).
-@end defvar
-
-@node Image Instantiator Conversion
-@subsection Image Instantiator Conversion
-@cindex image instantiator conversion
-@cindex conversion of image instantiators
-
-@defun set-console-type-image-conversion-list console-type list
-This function sets the image-conversion-list for consoles of the given
-@var{console-type}.  The image-conversion-list specifies how image
-instantiators that are strings should be interpreted.  Each element of
-the list should be a list of two elements (a regular expression string
-and a vector) or a list of three elements (the preceding two plus an
-integer index into the vector).  The string is converted to the vector
-associated with the first matching regular expression.  If a vector
-index is specified, the string itself is substituted into that position
-in the vector.
-
-Note: The conversion above is applied when the image instantiator is
-added to an image specifier, not when the specifier is actually
-instantiated.  Therefore, changing the image-conversion-list only affects
-newly-added instantiators.  Existing instantiators in glyphs and image
-specifiers will not be affected.
-@end defun
-
-@defun console-type-image-conversion-list console-type
-This function returns the image-conversion-list for consoles of the given
-@var{console-type}.
-@end defun
-
-@node Image Instances
-@subsection Image Instances
-@cindex image instances
-
-  Image-instance objects encapsulate the way a particular image (pixmap,
-etc.) is displayed on a particular device.
-
-  In most circumstances, you do not need to directly create image
-instances; use a glyph instead.  However, it may occasionally be useful
-to explicitly create image instances, if you want more control over the
-instantiation process.
-
-@defun image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image instance.
-@end defun
-
-@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.
-@end table
-
-@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
-
-@defun image-instance-type image-instance
-This function returns 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}, or @code{subwindow}.
-@end defun
-
-@defun text-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{text}.
-@end defun
-
-@defun mono-pixmap-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{mono-pixmap}.
-@end defun
-
-@defun color-pixmap-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{color-pixmap}.
-@end defun
-
-@defun pointer-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{pointer}.
-@end defun
-
-@defun subwindow-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{subwindow}.
-@end defun
-
-@defun nothing-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{nothing}.
-@end defun
-
-@defun widget-image-instance-p object
-Return @code{t} 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. (For XBM, the
-most natural types are @code{mono-pixmap}, followed by
-@code{color-pixmap}, followed by @code{pointer}.  For the other normal
-image formats, the most natural types are @code{color-pixmap}, followed
-by @code{mono-pixmap}, followed by @code{pointer}.  For the string and
-formatted-string formats, the most natural types are @code{text},
-followed by @code{mono-pixmap} (not currently implemented), followed by
-@code{color-pixmap} (not currently implemented).  For MS Windows
-resources, the most natural type for pointer resources is
-@code{pointer}, and for the others it's @code{color-pixmap}.  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, just 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. #### We should
-fix this.)
-n
-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
-
-@defun image-instance-name image-instance
-This function returns the name of the given image instance.
-@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
-
-@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
-
-@defun image-instance-hotspot-x image-instance
-This function returns the X coordinate of the image instance's hotspot,
-if known.  This 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.
-
-This will always be @code{nil} for a non-pointer image instance.
-@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
-
-@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 Glyph Types
-@section Glyph Types
+@subsection Glyph Types
 
   Each glyph has a particular type, which controls how the glyph's image
 is generated.  Each glyph type has a corresponding list of allowable
@@ -1230,6 +1977,7 @@
 extent, in the modeline, and in the toolbar.  Their image can be
 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
 @code{text}, and @code{subwindow}.
+@c #### Check status of subwindows ... I thought Andy implemented them.
 
 @item
 @code{pointer} glyphs can be used to specify the mouse pointer.  Their
@@ -1270,320 +2018,6 @@
 @code{pointer}.
 @end defun
 
-@node Mouse Pointer
-@section Mouse Pointer
-@cindex mouse cursor
-@cindex cursor (mouse)
-@cindex pointer (mouse)
-@cindex mouse pointer
-
-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.
-
-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 Redisplay Glyphs
-@section Redisplay Glyphs
-
-@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 Native GUI Widgets
-@section 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
-@subsection 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
-@subsection 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, which is that 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
-@subsection 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.
-
-(There are also @dfn{native layouts}, but I don't know what these are or
-how they are used.)
-
-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{:center}, @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
-@subsection 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.
-
-@item tree-view
-A folding widget.
-
-@item scrollbar
-A scrollbar widget.  (#### Probably not the same as the scrollbar
-controlling an Emacs window.)
-@end table
-
-
-@node Subwindows
-@section Subwindows
-
-Subwindows are not currently implemented.
-
-@defun subwindowp object
-This function returns non-@code{nil} if @var{object} is a subwindow.
-@end defun
 
 @node Glyph Examples
 @section Glyph Examples