--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/lispref/glyphs.texi	Mon Aug 13 11:28:15 2007 +0200
@@ -0,0 +1,1054 @@
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1995, 1996 Ben Wing.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/glyphs.info
+@node Glyphs, Annotations, Faces and Window-System Objects, top
+@chapter Glyphs
+@cindex glyphs
+
+  A @dfn{glyph} is an object that is used for pixmaps 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.
+
+@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.
+* Subwindows::          Inserting an externally-controlled subwindow
+                          into a buffer.
+@end menu
+
+@node Glyph Functions
+@section Glyph Functions
+
+@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.
+@end menu
+
+@node Creating Glyphs
+@subsection Creating Glyphs
+
+@defun make-glyph &optional spec-list type
+This function creates a new glyph object of type @var{type}.
+
+@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.
+
+@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 buffer), @code{pointer} (used for the
+mouse-pointer), or @code{icon} (used for a frame's icon), and defaults
+to @code{buffer}.  @xref{Glyph Types}.
+@end defun
+
+@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
+This function is equivalent to calling @code{make-glyph} with a
+@var{type} of @code{pointer}.
+@end defun
+
+@defun make-icon-glyph &optional spec-list
+This function is equivalent to calling @code{make-glyph} with a
+@var{type} of @code{icon}.
+@end defun
+
+@node Glyph Properties
+@subsection Glyph Properties
+
+Each glyph has a list of properties, which control all of the aspects of
+the glyph's appearance.  The following symbols have predefined meanings:
+
+@table @code
+@item image
+The image used to display the glyph.
+
+@item baseline
+Percent above baseline that glyph is to be displayed.  Only for glyphs
+displayed inside of a buffer.
+
+@item contrib-p
+Whether the glyph contributes to the height of the line it's on.
+Only for glyphs displayed inside of a buffer.
+
+@item face
+Face of this glyph (@emph{not} a specifier).
+@end table
+
+@defun set-glyph-property glyph property value &optional locale tag-set how-to-add
+This function changes a property of a @var{glyph}.
+
+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.
+
+If @var{property} is a built-in property, the specifications to be added
+to this property can be supplied in many different ways:
+
+@itemize @bullet
+@item
+If @var{value} is a simple instantiator (e.g. a string naming a pixmap
+filename) or a list of instantiators, then the instantiator(s) will be
+added as a specification of the property for the given @var{locale}
+(which defaults to @code{global} if omitted).
+
+@item
+If @var{value} is a list of specifications (each of which is a cons of a
+locale and a list of instantiators), then @var{locale} must be
+@code{nil} (it does not make sense to explicitly specify a locale in
+this case), and specifications will be added as given.
+
+@item
+If @var{value} is a specifier (as would be returned by
+@code{glyph-property} if no @var{locale} argument is given), then some
+or all of the specifications in the specifier will be added to the
+property.  In this case, the function is really equivalent to
+@code{copy-specifier} and @var{locale} has the same semantics (if it is
+a particular locale, the specification for the locale will be copied; if
+a locale type, specifications for all locales of that type will be
+copied; if @code{nil} or @code{all}, then all specifications will be
+copied).
+@end itemize
+
+@var{how-to-add} should be either @code{nil} or one of the symbols
+@code{prepend}, @code{append}, @code{remove-tag-set-prepend},
+@code{remove-tag-set-append}, @code{remove-locale},
+@code{remove-locale-type}, or @code{remove-all}.  See
+@code{copy-specifier} and @code{add-spec-to-specifier} for a description
+of what each of these means.  Most of the time, you do not need to worry
+about this argument; the default behavior usually is fine.
+
+In general, it is OK to pass an instance object (e.g. as returned by
+@code{glyph-property-instance}) as an instantiator in place of an actual
+instantiator.  In such a case, the instantiator used to create that
+instance object will be used (for example, if you set a font-instance
+object as the value of the @code{font} property, then the font name used
+to create that object will be used instead).  If some cases, however,
+doing this conversion does not make sense, and this will be noted in the
+documentation for particular types of instance objects.
+
+If @var{property} is not a built-in property, then this function will
+simply set its value if @var{locale} is @code{nil}.  However, if
+@var{locale} is given, then this function will attempt to add
+@var{value} as the instantiator for the given @var{locale}, using
+@code{add-spec-to-specifier}.  If the value of the property is not a
+specifier, it will automatically be converted into a @code{generic}
+specifier.
+@end defun
+
+@defun glyph-property glyph property &optional locale
+This function returns @var{glyph}'s value of the given @var{property}.
+
+If @var{locale} is omitted, the @var{glyph}'s actual value for
+@var{property} will be returned.  For built-in properties, this will be
+a specifier object of a type appropriate to the property (e.g. a font or
+color specifier).  For other properties, this could be anything.
+
+If @var{locale} is supplied, then instead of returning the actual value,
+the specification(s) for the given locale or locale type will be
+returned.  This will only work if the actual value of @var{property} is
+a specifier (this will always be the case for built-in properties, but
+may or may not apply to user-defined properties).  If the actual value
+of @var{property} is not a specifier, this value will simply be returned
+regardless of @var{locale}.
+
+The return value will be a list of instantiators (e.g. vectors
+specifying pixmap data), or a list of specifications, each of which is a
+cons of a locale and a list of instantiators.  Specifically, if
+@var{locale} is a particular locale (a buffer, window, frame, device, or
+@code{global}), a list of instantiators for that locale will be
+returned.  Otherwise, if @var{locale} is a locale type (one of the
+symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
+the specifications for all locales of that type will be returned.
+Finally, if @var{locale} is @code{all}, the specifications for all
+locales of all types will be returned.
+
+The specifications in a specifier determine what the value of
+@var{property} will be in a particular @dfn{domain} or set of
+circumstances, which is typically a particular Emacs window along with
+the buffer it contains and the frame and device it lies within.  The
+value is derived from the instantiator associated with the most specific
+locale (in the order buffer, window, frame, device, and @code{global})
+that matches the domain in question.  In other words, given a domain
+(i.e. an Emacs window, usually), the specifier for @var{property} will
+first be searched for a specification whose locale is the buffer
+contained within that window; then for a specification whose locale is
+the window itself; then for a specification whose locale is the frame
+that the window is contained within; etc.  The first instantiator that
+is valid for the domain (usually this means that the instantiator is
+recognized by the device [i.e. the X server or TTY device] that the
+domain is on).  The function @code{glyph-property-instance} actually does
+all this, and is used to determine how to display the glyph.
+@end defun
+
+@defun glyph-property-instance glyph property &optional domain default no-fallback
+This function returns the instance of @var{glyph}'s @var{property} in the
+specified @var{domain}.
+
+Under most circumstances, @var{domain} will be a particular window, and
+the returned instance describes how the specified property actually is
+displayed for that window and the particular buffer in it.  Note that
+this may not be the same as how the property appears when the buffer is
+displayed in a different window or frame, or how the property appears in
+the same window if you switch to another buffer in that window; and in
+those cases, the returned instance would be different.
+
+The returned instance is an image-instance object, and you can query it
+using the appropriate image instance functions.  For example, you could use
+@code{image-instance-depth} to find out the depth (number of color
+planes) of a pixmap displayed in a particular window.  The results might
+be different from the results you would get for another window (perhaps
+the user specified a different image for the frame that window is on; or
+perhaps the same image was specified but the window is on a different X
+server, and that X server has different color capabilities from this
+one).
+
+@var{domain} defaults to the selected window if omitted.
+
+@var{domain} can be a frame or device, instead of a window.  The value
+returned for such a domain is used in special circumstances when a
+more specific domain does not apply; for example, a frame value might be
+used for coloring a toolbar, which is conceptually attached to a frame
+rather than a particular window.  The value is also useful in
+determining what the value would be for a particular window within the
+frame or device, if it is not overridden by a more specific
+specification.
+
+If @var{property} does not name a built-in property, its value will
+simply be returned unless it is a specifier object, in which case it
+will be instanced using @code{specifier-instance}.
+
+Optional arguments @var{default} and @var{no-fallback} are the same as
+in @code{specifier-instance}.  @xref{Specifiers}.
+@end defun
+
+@defun remove-glyph-property glyph property &optional locale tag-set exact-p
+This function removes a property from a glyph.  For built-in properties,
+this is analogous to @code{remove-specifier}.  @xref{Specifiers,
+remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
+and @var{exact-p} arguments.
+@end defun
+
+@node Glyph Convenience Functions
+@subsection Glyph Convenience Functions
+
+  The following functions are provided for working with specific
+properties of a glyph.  Note that these are exactly like calling
+the general functions described above and passing in the
+appropriate value for @var{property}.
+
+  Remember that if you want to determine the ``value'' of a
+specific glyph property, you probably want to use the @code{*-instance}
+functions.  For example, to determine whether a glyph contributes
+to its line height, use @code{glyph-contrib-p-instance}, not
+@code{glyph-contrib-p}. (The latter will return a boolean specifier
+or a list of specifications, and you probably aren't concerned with
+these.)
+
+@defun glyph-image glyph &optional locale
+This function is equivalent to calling @code{glyph-property} with
+a property of @code{image}.  The return value will be an image
+specifier if @var{locale} is @code{nil} or omitted; otherwise,
+it will be a specification or list of specifications.
+@end defun
+
+@defun set-glyph-image glyph spec &optional locale tag-set how-to-add
+This function is equivalent to calling @code{set-glyph-property} with
+a property of @code{image}.
+@end defun
+
+@defun glyph-image-instance glyph &optional domain default no-fallback
+This function returns the instance of @var{glyph}'s image in the given
+@var{domain}, and is equivalent to calling
+@code{glyph-property-instance} with a property of @code{image}.  The
+return value will be an image instance.
+
+Normally @var{domain} will be a window or @code{nil} (meaning the
+selected window), and an instance object describing how the image
+appears in that particular window and buffer will be returned.
+@end defun
+
+@defun glyph-contrib-p glyph &optional locale
+This function is equivalent to calling @code{glyph-property} with
+a property of @code{contrib-p}.  The return value will be a boolean
+specifier if @var{locale} is @code{nil} or omitted; otherwise,
+it will be a specification or list of specifications.
+@end defun
+
+@defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
+This function is equivalent to calling @code{set-glyph-property} with
+a property of @code{contrib-p}.
+@end defun
+
+@defun glyph-contrib-p-instance glyph &optional domain default no-fallback
+This function returns whether the glyph contributes to its line height
+in the given @var{domain}, and is equivalent to calling
+@code{glyph-property-instance} with a property of @code{contrib-p}.  The
+return value will be either @code{nil} or @code{t}. (Normally @var{domain}
+will be a window or @code{nil}, meaning the selected window.)
+@end defun
+
+@defun glyph-baseline glyph &optional locale
+This function is equivalent to calling @code{glyph-property} with a
+property of @code{baseline}.  The return value will be a specifier if
+@var{locale} is @code{nil} or omitted; otherwise, it will be a
+specification or list of specifications.
+@end defun
+
+@defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
+This function is equivalent to calling @code{set-glyph-property} with
+a property of @code{baseline}.
+@end defun
+
+@defun glyph-baseline-instance glyph &optional domain default no-fallback
+This function returns the instance of @var{glyph}'s baseline value in
+the given @var{domain}, and is equivalent to calling
+@code{glyph-property-instance} with a property of @code{baseline}.  The
+return value will be an integer or @code{nil}.
+
+Normally @var{domain} will be a window or @code{nil} (meaning the
+selected window), and an instance object describing the baseline value
+appears in that particular window and buffer will be returned.
+@end defun
+
+@defun glyph-face glyph
+This function returns the face of @var{glyph}. (Remember, this is
+not a specifier, but a simple property.)
+@end defun
+
+@defun set-glyph-face glyph face
+This function changes the face of @var{glyph} to @var{face}.
+@end defun
+
+@node Glyph Dimensions
+@subsection Glyph Dimensions
+
+@defun glyph-width glyph &optional window
+This function returns the width of @var{glyph} on @var{window}.  This
+may not be exact as it does not take into account all of the context
+that redisplay will.
+@end defun
+
+@defun glyph-ascent glyph &optional window
+This function returns the ascent value of @var{glyph} on @var{window}.
+This may not be exact as it does not take into account all of the
+context that redisplay will.
+@end defun
+
+@defun glyph-descent glyph &optional window
+This function returns the descent value of @var{glyph} on @var{window}.
+This may not be exact as it does not take into account all of the
+context that redisplay will.
+@end defun
+
+@defun glyph-height glyph &optional window
+This function returns the height of @var{glyph} on @var{window}.  (This
+is equivalent to the sum of the ascent and descent values.)  This may
+not be exact as it does not take into account all of the context that
+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}.  It is unlikely that you will ever
+want to do this, but this function is provided for completeness and
+for experimentation purposes.  @xref{Specifiers}.
+@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.
+Not currently implemented.)
+@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 subwindow
+(An embedded X window; not currently implemented.)
+@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.)
+@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.)
+@end table
+
+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
+This function returns non-@code{nil} if @var{format} is a valid image
+instantiator format.  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 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
+
+@node Image Instance Functions
+@subsubsection Image Instance Functions
+
+@defun make-image-instance data &optional device dest-types no-error
+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).  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{no-error} controls what happens when the image cannot be generated.
+If @var{nil}, an error message is generated.  If @var{t}, no messages
+are generated and this function returns @var{nil}.  If anything else, a
+warning message is generated and this function returns @var{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-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
+
+  Each glyph has a particular type, which controls how the glyph's image
+is generated.  Each glyph type has a corresponding list of allowable
+image instance types that can be generated.  When you call
+@code{glyph-image-instance} to retrieve the image instance of a glyph,
+XEmacs does the equivalent of calling @code{make-image-instance} and
+passing in @var{dest-types} the list of allowable image instance types
+for the glyph's type.
+
+@itemize @bullet
+@item
+@code{buffer} glyphs can be used as the begin-glyph or end-glyph of an
+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}.
+
+@item
+@code{pointer} glyphs can be used to specify the mouse pointer.  Their
+image can be instantiated as @code{pointer}.
+
+@item
+@code{icon} glyphs can be used to specify the icon used when a frame is
+iconified.  Their image can be instantiated as @code{mono-pixmap} and
+@code{color-pixmap}.
+@end itemize
+
+@defun glyph-type glyph
+This function returns the type of the given glyph.  The return value
+will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}.
+@end defun
+
+@defun valid-glyph-type-p glyph-type
+Given a @var{glyph-type}, this function returns non-@code{nil} if it is
+valid.
+@end defun
+
+@defun glyph-type-list
+This function returns a list of valid glyph types.
+@end defun
+
+@defun buffer-glyph-p object
+This function returns non-@code{nil} if @var{object} is a glyph of type
+@code{buffer}.
+@end defun
+
+@defun icon-glyph-p object
+This function returns non-@code{nil} if @var{object} is a glyph of type
+@code{icon}.
+@end defun
+
+@defun pointer-glyph-p object
+This function returns non-@code{nil} if @var{object} is a glyph of type
+@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 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