Contents in 1999-06-04-13 of release-21-2.

[chise/xemacs-chise.git.1] / man / lispref / glyphs.texi

@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