@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1995 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 non-textual
strings that are displayed in the text of a buffer, in the margins, or
in the toolbar.  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.

@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.
* Cursors::		Controlling the mouse cursor.
@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.
@end menu

@node Creating Glyphs
@subsection Creating Glyphs

@defun make-glyph &optional spec-list
This function creates a new @code{glyph} object, with the given
specification list used to initialize the glyph's image specifier.
@var{spec-list} can be a list of specifications (each of which is a cons
of a locale and a list of inst-pairs, each of which is a cons of a tag
and an instantiator), a single instantiator, a list of instantiators, or
almost any other reasonable form (specifically anything accepted by
@code{canonicalize-spec-list}).  @xref{Specifiers} for more information
about specifiers.
@end defun

@defun make-glyph-internal
This function creates a new, uninitialzed glyph.
@end defun

@node Glyph Properties
@subsection Glyph Properties

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.

@item contrib-p
Whether the glyph contributes to the height of the line it's on.

@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
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).

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.

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
not or not may 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 will typically be an image-instance object or a
string (@emph{this is slated to change in 19.13}), and you can query it
using the appropriate object-specific 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 a 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

@node Glyph Convenience Functions
@subsection Glyph Convenience Functions

@defun glyph-image glyph &optional locale
@end defun

@defun set-glyph-image glyph spec &optional locale tag-set how-to-add
@end defun

@defun glyph-image-instance glyph &optional domain default no-fallback
@end defun

@defun glyph-contrib-p glyph &optional locale
This function returns whether @var{glyph} contributes to its line
height.  @var{glyph} and @var{locale} are as in @code{glyph-property}.
@end defun

@defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
@end defun

@defun glyph-contrib-p-instance glyph &optional domain default no-fallback
@end defun

@defun glyph-baseline glyph &optional locale
@end defun

@defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
@end defun

@defun glyph-baseline-instance glyph &optional domain default no-fallback
@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 for images (pixmaps and the like).  It is
used to describe the actual image in a glyph.  It is instanced as an
image-instance.

An image instantiator should be a string or a vector of the form

@example
 @code{[@var{type} @var{:keyword} @var{value} ...]}
@end example

i.e. a type symbol followed by zero or more alternating keyword-value
pairs.  @var{type} should be one of

@table @code
@item nothing
(Don't display anything; no keywords are valid for this.)
@item string
(Display this image as a text string.)
@item formatted-string
(Display this image as a text string, with replaceable fields;
#### not implemented in 19.13.)
@item xbm
(An X bitmap; only if X support was compiled into this XEmacs.)
@item xpm
(An XPM pixmap; only if XPM support was compiled into this XEmacs.)
@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.)
@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 will be created.  Otherwise, the image will be displayed
as a string.  If no X support exists, the image will always be displayed
as a string.)
@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 cons of three elements: width, height, and
a string of bit data.)
@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.)
@item :mask-data
(Only for XBM images.  This specifies a mask to be used with the
bitmap.  The format is a cons of width, height, and bits, like for
@code{:data}.)
@item :mask-file
(Only for XBM images.  This specifies a file containing the mask data.)
@item :color-symbols
(Only for XPM images.  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 looked
up according to the specs in the @code{device-type-image-conversion-list}
for the device type of the domain over which the image is being
instantiated.

If the instantiator is a string, it will be read in at the time that the
instantiator is added to the image, and the instantiator will be
converted into one of the @code{[FILENAME ...]} forms.  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 be a temporary
file).

@defun image-specifier-p object
This function returns non-@code{nil} if @var{object} is an image specifier.
@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-device-type-image-conversion-list device-type list
This function sets the image-conversion-list for devices of the given
@var{device-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 device-type-image-conversion-list device-type
This function returns the image-conversion-list for devices of the given
@var{device-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 or an image-
specifier instead. (Most functions and data structures that want an image
are designed to take either a glyph or an image-specifier.)

@defun image-instance-p object
This function returns non-@code{nil} if @var{object} is an image instance.
@end defun

@defun make-image-instance data &optional device force-mono noerror
This function creates a new image-instance object.
@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-depth image-instance
This function returns the depth of the image instance.
This is 0 for a bitmap, or a positive integer for a pixmap.
@end defun

@defun image-instance-file-name image-instance
This function returns the file name from which the given image instance
was read, or @code{nil} if the image instance was created from Lisp
data (the lisp data is not retained, since it usually won't be needed
again and might be quite large).
@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 set-image-instance-hotspot image-instance x y
This function sets the image instance's hotspot.  This is a point
relative to the origin of the pixmap.  When a pixmap is used as a cursor
or similar pointing indicator, the hotspot is the point on the pixmap
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.
@end defun

@defun image-instance-hotspot-x image-instance
This function returns the X coordinate of the image instance's hotspot.
@end defun

@defun image-instance-hotspot-y image-instance
This function returns the Y coordinate of the image instance's hotspot.
@end defun

@node Cursors
@section Cursors
@cindex cursors

Cursors are scheduled to be overhauled in 19.13.
Watch this space for more info.

