This is ../info/lispref.info, produced by makeinfo version 4.8 from
lispref/lispref.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Lispref: (lispref).		XEmacs Lisp Reference Manual.
END-INFO-DIR-ENTRY

   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.


File: lispref.info,  Node: Introduction to Specifiers,  Next: Simple Specifier Usage,  Prev: Specifiers,  Up: Specifiers

48.1 Introduction to Specifiers
===============================

Perhaps the most useful way to explain specifiers is via an analogy.
Emacs Lisp programmers are used to _buffer-local variables_ *Note
Buffer-Local Variables::. For example, the variable `modeline-format',
which controls the format of the modeline, can have different values
depending on the particular buffer being edited.  The variable has a
default value which most modes will use, but a specialized package such
as Calendar might change the variable so as to tailor the modeline to
its own purposes. Other variables are perhaps best thought of as "mode
local," such as font-lock keywords, but they are implemented as buffer
locals.

   Other properties (such as those that can be changed by the
`modify-frame-parameters' function, for example the color of the text
cursor) can have frame-local values, although it might also make sense
for them to have buffer-local values.  In other cases, you might want
the property to vary depending on the particular window within the
frame that applies (e.g. the top or bottom window in a split frame), the
device type that that frame appears on (X or tty), etc.  Perhaps you can
envision some more complicated scenario where you want a particular
value in a specified buffer, another value in all other buffers
displayed on a particular frame, another value in all other buffers
displayed in all other frames on any mono (two-color, e.g. black and
white only) displays, and a default value in all other circumstances.

   Specifiers generalize both buffer- and frame-local properties.
Specifiers vary according to the _display_ context.  Font-lock keywords
in a buffer will be the same no matter which window the buffer is
displayed in, but windows on TTY devices will simply not be capable of
the flexibility that windows on modern GUI devices are.  Specifiers
provide a way for the programmer to _declare_ that an emphasized text
should be italic on GUI devices and inverse video on TTYs.  They also
provide a way for the programmer to declare fallbacks, so that a color
specified as "chartreuse" where possible can fall back to "yellow" on
devices where only ANSI (4-bit) color is available.  The complex
calculations and device querying are transparent to both user and
programmer.  You ask for what you want; it's up to XEmacs to provide
it, or a reasonable approximation.

   We call such a declaration a "specification".  A "specification"
applies in a particular "locale", which is a window, buffer, frame,
device, or the global locale.  The value part of the specification is
called an "instantiator".  The process of determining the value in a
particular context, or "domain", is called "instantiation".  A domain
is a window, frame, or device.

   The difference between "locale" and "domain" is somewhat subtle.
You may think of a locale as a class of domains, which may span
different devices.  Since the specification is abstract (a Lisp form),
you can state it without reference to a device.  On the other hand, when
you instantiate a specification, you must know the type of the device.
It is useless to specify that "blue means emphasis" on a monochrome
device.  Thus instantiation requires specification of the device on
which it will be rendered.

   Thus a "specifier" allows a great deal of flexibility in controlling
exactly what value a property has in which circumstances.  Specifiers
are most commonly used for display properties, such as an image or the
foreground color of a face.  As a simple example, you can specify that
the foreground of the default face be

   * blue for a particular buffer

   * green for all other buffers

   As a more complicated example, you could specify that the foreground
of the default face be

   * forest green for all buffers displayed in a particular Emacs
     window, or green if the X server doesn't recognize the color
     `forest green'

   * blue for all buffers displayed in a particular frame

   * red for all other buffers displayed on a color device

   * white for all other buffers


File: lispref.info,  Node: Simple Specifier Usage,  Next: Specifiers In-Depth,  Prev: Introduction to Specifiers,  Up: Specifiers

48.2 Simple Specifier Usage
===========================

A useful specifier application is adding a button to a toolbar.  XEmacs
provides several toolbars, one along each edge of the frame.  Normally
only one is used at a time, the default.  The default toolbar is
actually a specifier object which is the value of `default-toolbar'.
*Note Toolbar Intro::.

   The specification of a toolbar is simple:  it is a list of buttons.
Each button is a vector with four elements:  an icon, a command, the
enabled flag, and a help string.  Let's retrieve the instance of the
toolbar you see in the selected frame.

     (specifier-instance default-toolbar)

   The value returned is, as promised, a list of vectors.  Now let's
build up a button, and add it to the toolbar.  Our button will invoke
the last defined keyboard macro.  This is an alternative to
`name-last-kbd-macro' for creating a persistent macro, rather than an
alias for `C-x e'.

   A toolbar button icon can be quite sophisticated, with different
images for button up, button down, and disabled states, and a similar
set with captions.  We'll use a very simple icon, but we have to jump
through a few non-obvious hoops designed to support the sophisticated
applications.  The rest of the button descriptor is straightforward.

     (setq toolbar-my-kbd-macro-button
       `[ (list (make-glyph "MyKbdMac"))
          (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
          t
          "Execute a previously defined keyboard macro." ])

     (set-specifier default-toolbar
                    (cons toolbar-my-kbd-macro-button
                          (specifier-specs default-toolbar 'global))
                    'global)

   To remove the button, just substitute the function `delete' for the
`cons' above.

   What is the difference between `specifier-instance', which we used
in the example of retrieving the toolbar descriptor, and
`specifier-specs', which was used in the toolbar manipulating code?
`specifier-specs' retrieves a copy of the instantiator, which is
abstract and does not depend on context.  `specifier-instance', on the
other hand, actually instantiates the specification, and returns the
result for the given context.  Another way to express this is:
`specifier-specs' takes a _locale_ as an argument, while
`specifier-instance' takes a _domain_.  The reason for providing
`specifier-instance' is that sometimes you wish to see the object that
XEmacs will actually use.  `specifier-specs', on the other hand, shows
you what the programmer (or user) requested.  When a program
manipulates specifications, clearly it's the latter that is desirable.

   In the case of the toolbar descriptor, it turns out that these are
the same:  the instantiation process is trivial.  However, many
specifications have non-trivial instantiation.  Compare the results of
the following forms on my system.  (The `(cdr (first ...))' form is due
to my use of Mule.  On non-Mule XEmacsen, just use `specifier-specs'.)

     (cdr (first (specifier-specs (face-font 'default) 'global)))
     => "-*--14-*jisx0208*-0"

     (specifier-instance (face-font 'default))
     #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b>

   In this case, `specifier-instance' returns an opaque object; Lisp
programs can't work on it, they can only pass it around.  Worse, in some
environments the instantiation will fail, resulting in a different value
(when another instantiation succeeds), or worse yet, an error, if all
attempts to instantiate the specifier fail.  `specifier-instance' is
context-dependent, even for the exact same specification.
`specifier-specs' is deterministic, and only depends on the
specifications.

   Note that in the toolbar-changing code we operate in the global
locale.  This means that narrower locales, if they have specifications,
will shadow our changes.  (Specifier instantiation does not merge
specifications.  It selects the "highest-priority successful
specification" and instantiates that.)

   In fact, in our example, it seems pretty likely that different
buffers _should_ have different buttons.  (The icon can be the same, but
the keyboard macro you create in a Dired buffer is highly unlikely to be
useful in a LaTeX buffer!)  Here's one way to implement this:

     (setq toolbar-my-kbd-macro-button
       `[ (list (make-glyph "MyKbdMac"))
          (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro))
          t
          "Execute a previously defined keyboard macro." ])

     (set-specifier default-toolbar
                    (cons toolbar-my-kbd-macro-button
                          (cond ((specifier-specs default-toolbar
                                                  (current-buffer)))
                                ((specifier-specs default-toolbar
                                                  'global)))
                    (current-buffer))

   Finally, a cautionary note: the use of `specifier-specs' in the code
above is for expository purposes.  Don't use it in production code.  In
fact, the `set-specifier' form above is likely to fail occasionally,
because you can add many specifications for the same locale.

   In these cases, `specifier-specs' will return a list.  A further
refinement is that a specification may be associated with a set of
"specifier tags".  If the list of specifier tags is non-nil, then
`specifier-specs' will return a cons of the tag set and the
instantiator.  Evidently `specifier-specs' is a bit unreliable.  (For
toolbars, the code above should work 99% of the time, because toolbars
are rarely changed.  Since instantiation is trivial, multiple specs are
not useful--the first one always succeeds.)

   In fact, `specifier-specs' is intended to be used to display specs
to humans with a minimum of clutter. The robust way to access
specifications is via `specifier-spec-list'. *Note Adding
Specifications::, for the definition of "spec-list". *Note Retrieving
Specifications::, for documentation of `specifier-specs' and
`specifier-spec-list'. To get the desired effect, replace the form
`(specifier-spec default-toolbar 'global)' with

     (cdr (second (first (specifier-spec-list default-toolbar 'global))))

   (It should be obvious why the example uses the lazy unreliable
method!)


File: lispref.info,  Node: Specifiers In-Depth,  Next: Specifier Instantiation,  Prev: Simple Specifier Usage,  Up: Specifiers

48.3 In-Depth Overview of a Specifier
=====================================

Having variables vary according the editing context is very useful, and
the buffer is the natural "atomic" unit of editing context.  In a GUI
environment, it can be similarly useful to have variables whose values
vary according to display context.  The atomic unit of display context
is the Emacs window.  Buffers are cleanly grouped by modes, but windows
are not so easily pigeonholed.  On the one hand, a window displays a
buffer, and thus one possible hierarchy is window, buffer, mode.  On the
other, a window is a component of a frame.  This generates the window,
frame, device hierarchy.  Finally, there are objects such as toolbars
whose properties are described by specifiers.  These do not fit
naturally into either hierarchy.  This problem is as yet not cleanly
solved.

   Another potential source of conceptual confusion is the instantiation
process.  Instantiating a buffer-local variable is simple: at any given
point in time there is a current buffer, and its local values are used
and set whenever the variable is accessed, unless the programmer goes to
some special effort (uses `default-value' and `set-default'.  However,
a specifier object encapsulates a set of "specifications", each of
which says what its value should be if a particular condition applies.
Several such conditions might apply simultaneously in a given window.

   For example, one specification might be "The value should be
darkseagreen2 on X devices" another might be "The value should be blue
in the *Help* buffer".  So what do we do for "the *Help* buffer on an X
device"?  The answer is simple: give each type of locale a priority and
check them in priority order, returning the first instantiator that
successfully instantiates a value.

   Given a specifier, a logical question is "What is its value in a
particular situation?" This involves looking through the specifications
to see which ones apply to this particular situation, and perhaps
preferring one over another if more than one applies.  In specifier
terminology, a "particular situation" is called a "domain", and
determining its value in a particular domain is called "instantiation".
Most of the time, a domain is identified by a particular window.  For
example, if the redisplay engine is drawing text in the default face in
a particular window, it retrieves the specifier for the foreground color
of the default face and "instantiates" it in the domain given by that
window; in other words, it asks the specifier, "What is your value in
this window?".

   Note that the redisplay example is in a sense canonical.  That is,
specifiers are designed to present a uniform and _efficient_ API to
redisplay.  It is the efficiency constraint that motivates the
introduction of specifier tags, and many restrictions on access (for
example, a buffer is not a domain, and you cannot instantiate a
specifier over a buffer).

   More specifically, a specifier contains a set of "specifications",
each of which associates a "locale" (a window object, a buffer object,
a frame object, a device object, or the symbol `global') with an
"inst-list", which is a list of one or more "inst-pairs". (For each
possible locale, there can be at most one specification containing that
locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
zero or more symbols, or "tags") and an "instantiator" (the allowed
form of this varies depending on the type of specifier).  In a given
specification, there may be more than one inst-pair with the same tag
set; this is unlike for locales.

   The tag set is used to restrict the sorts of devices and character
sets over which the instantiator is valid and to uniquely identify
instantiators added by a particular application, so that different
applications can work on the same specifier and not interfere with each
other.

   Each tag can have a "device-predicate" associated with it, which is
a function of one argument (a device) that specifies whether the tag
matches that particular device. (If a tag does not have a predicate, it
matches all devices.)  All tags in a tag set must match a device for the
associated inst-pair to be instantiable over that device.  (A null tag
set is perfectly valid, and trivially matches all devices.)

   Each tag can also have a "charset-predicate" associated with it;
this is a function that takes one charset argument, and specifies
whether that tag matches that particular charset.  When instantiating a
face over a given domain with a given charset, the `charset-predicate'
attribute of a tag is consulted(1) to decide whether this inst-pair
matches the charset.  If the `charset-predicate' function of a tag is
unspecified, that tag defaults to matching all charsets.

   When `charset-predicate's are being taken into account, the matching
process becomes two-stage.  The first stage pays attention to the
charset predicates and the device predicates; only if there is no match
does the second stage take place, in which charset predicates are
ignored, and only the device predicates are relevant.

   The valid device types in a build (normally `x', `tty', `stream',
`mswindows', `msprinter', and possibly `carbon') and device classes
(normally `color', `grayscale', and `mono') can always be used as tags,
and match devices of the associated type or class (*note Consoles and
Devices::).  There are also built-in tags related to font instantiation
and translation to Unicode; they are identical to the symbols used with
`specifier-matching-instance', see the documentation of that function
for their names.

   User-defined tags may be defined, with optional device and charset
predicates specified.  An application can create its own tag, use it to
mark all its instantiators, and be fairly confident that it will not
interfere with other applications that modify the same
specifier--functions that add a specification to a specifier usually
only overwrite existing inst-pairs with the same tag set as was given,
and a particular tag or tag set can be specified when removing
instantiators.

   When a specifier is instantiated in a domain, both the locale and
the tag set can be viewed as specifying necessary conditions that must
apply in that domain for an instantiator to be considered as a possible
result of the instantiation.  More specific locales always override
more general locales (thus, there is no particular ordering of the
specifications in a specifier); however, the tag sets are simply
considered in the order that the inst-pairs occur in the
specification's inst-list.

   Note also that the actual object that results from the instantiation
(called an "instance object") may not be the same as the instantiator
from which it was derived.  For some specifier types (such as integer
specifiers and boolean specifiers), the instantiator will be returned
directly as the instance object.  For other types, however, this is not
the case.  For example, for font specifiers, the instantiator is a
font-description string and the instance object is a font-instance
object, which describes how the font is displayed on a particular
device.  A font-instance object encapsulates such things as the actual
font name used to display the font on that device (a font-description
string under X is usually a wildcard specification that may resolve to
different font names, with possibly different foundries, widths, etc.,
on different devices), the extra properties of that font on that
device, etc.  Furthermore, this conversion (called "instantiation")
might fail--a font or color might not exist on a particular device, for
example.

   ---------- Footnotes ----------

   (1) Not quite the case; the result of the functions are
pre-calculated and cached whenever `define-specifier-tag' or
`make-charset' is called.


File: lispref.info,  Node: Specifier Instantiation,  Next: Specifier Types,  Prev: Specifiers In-Depth,  Up: Specifiers

48.4 How a Specifier Is Instantiated
====================================

Instantiation of a specifier in a particular window domain proceeds as
follows:

   * First, XEmacs searches for a specification whose locale is the
     same as the window.  If that fails, the search is repeated,
     looking for a locale that is the same as the window's buffer.  If
     that fails, the search is repeated using the window's frame, then
     using the device that frame is on.  Finally, the specification
     whose locale is the symbol `global' (if there is such a
     specification) is considered.

   * The inst-pairs contained in the specification that was found are
     considered in their order in the inst-list, looking for one whose
     tag set matches the device that is derived from the window domain.
     (The tag set is an unordered list of zero or more tag symbols.
     For all tags that have predicates associated with them, the
     predicate must match the device.)

   * If a matching tag set is found, the corresponding instantiator is
     passed to the specifier's instantiation method, which is specific
     to the type of the specifier.  If it succeeds, the resulting
     instance object is returned as the result of the instantiation and
     the instantiation is done.  Otherwise, the operation continues,
     looking for another matching inst-pair in the current
     specification.

   * When there are no more inst-pairs to be considered in the current
     specification, the search starts over, looking for another
     specification as in the first step above.

   * If all specifications are exhausted and no instance object can be
     derived, the instantiation fails. (Actually, this is not
     completely true.  Some specifier objects for built-in properties
     have a "fallback" value, which is either an inst-list or another
     specifier object, that is consulted if the instantiation is about
     to fail.  If it is an inst-list, the searching proceeds using the
     inst-pairs in that list.  If it is a specifier, the entire
     instantiation starts over using that specifier instead of the
     given one.  Fallback values are set by the C code and cannot be
     modified, except perhaps indirectly, using any Lisp functions.
     The purpose of them is to supply some values to make sure that
     instantiation of built-in properties can't fail and to implement
     some basic specifier inheritance, such as the fact that faces
     inherit their properties from the `default' face.)

   It is also possible to instantiate a specifier over a frame domain or
device domain instead of over a window domain.  The C code, for example,
instantiates the `top-toolbar-height' variable over a frame domain in
order to determine the height of a frame's top toolbar.  Instantiation
over a frame or device is similar to instantiation over a window except
that specifications for locales that cannot be derived from the domain
are ignored.  Specifically, instantiation over a frame looks first for
frame locales, then device locales, then the `global' locale.
Instantiation over a device domain looks only for device locales and
the `global' locale.

   Note that specifiers are instantiated on _every_ redisplay.  (This is
the concept; of course the implementation keeps track of changes and
doesn't reinstantiate unchanged specifiers.)  That means that changes in
specifiers controlling appearance are reflected immediately in the UI.
Also, since specifiers are instantiated completely, removing a
specification can be just as effective as adding one.

   _E.g._, Giacomo Boffi wanted a modeline that indicates whether the
frame containing it is selected or not.  The first proposed
implementation is natural in a world of "local" variables.  The later
implementations apply the power of specifiers.

   (The copyright notice and permission statement below apply to the
code in example format, up to the "`;;; end of neon-modeline.el'"
comment.)

     ;;; neon-modeline.el

     ;; Copyright (c) 2004  Stephen J. Turnbull <stephen@xemacs.org>

     ;; Based on a suggestion by Giacomo Boffi

     ;; This code may be used and redistributed under the GNU GPL, v.2 or any
     ;; later version as published by the FSF, or under the license used for
     ;; XEmacs Texinfo manuals, at your option.

   A few customizations:

     ;; Placate the specifier and Customize gods.

     (unless (valid-specifier-tag-p 'modeline-background)
       (define-specifier-tag 'modeline-background))

     (defgroup lisp-demos nil "Demos for Lisp programming techniques.")

     (defgroup neon-modeline nil "Neon modeline identifies selected frame."
       :group 'lisp-demos)

     (defcustom neon-modeline-selected-background "LemonChiffon"
       "Background color for modeline in selected frames."
       :type 'color
       :group 'neon-modeline)

     (defcustom neon-modeline-deselected-background "Wheat"
       "Background color for modeline in unselected frames."
       :type 'color
       :group 'neon-modeline)

   Our first try uses three functions, a setup and two hook functions.
Separate hooks are defined for entry into a frame and exit from it.
Since we're using hooks, it's a fairly natural approach: we operate on
the background on each event corresponding to an appearance change we
want to make.  This doesn't depend on the specifier API, "frame-local"
variables would serve as well.

     (defun select-modeline ()
       (set-face-background 'modeline neon-modeline-selected-background
     		       (selected-frame)))

     (defun deselect-modeline ()
       (set-face-background 'modeline neon-modeline-deselected-background
     		       (selected-frame)))

   Note that the initialization removes no specifications, and
therefore is not idempotent.  Cruft will accumulate in the specifier if
the `-setup' function is called repeatedly.  This shouldn't cause a
performance problem; specifiers are quite efficient for their purpose.
But it's ugly, and wastes a small amount of space.

     (defun neon-modeline-setup ()
       (interactive)
       (set-face-background 'modeline neon-modeline-deselected-background)
       ;; Add the distinguished background on pointer entry to the frame;
       (add-hook 'select-frame-hook 'select-modeline)
       ;; restore the ordinary background on pointer exit from the frame.
       (add-hook 'deselect-frame-hook 'deselect-modeline)

   This approach causes a decided flicker on Boffi's platform, because
the two hook functions are executed in response to separate GUI events.

   The following code should be an improvement.  First, the hook
function.

     (defun neon-modeline-reselect ()
       (set-face-background 'modeline neon-modeline-deselected-background
     		       (selected-frame) '(modeline-background)
     		       'remove-locale-type))

   Only one event triggers the configuration change, which should reduce
flicker.  Because this is implemented as a specifier, we can use the
specifier API to reset all frame-local specifications (the
`remove-locale-type' argument).  This leaves the `global' specification
alone, but removes all existing frame-local specifications.  Then it
adds the selected-frame background specification for the newly selected
frame.  _I.e._, this effectively implements a "move specification from
frame to frame" operation.

   Why does it give the desired result?  By ensuring that only one frame
has the selected-frame modeline background.  Frame-local specifications
have precedence over global ones, so when the modeline background is
instantiated in the selected frame, it matches the specification set up
for it and gets the right color.  On the other hand, in any other frame,
it does not match the selected frame, so it falls through the
frame-local specifications and picks up the global specification.  Again
we get the desired color, in this case for unselected frames.

   Here the `modeline-background' tag is simply good practice
(identifying an application's specifications allows it to avoid
interfering with other applications, and other well-behaved applications
and Customize should not munge specifications with our tag on them).
However, an alternative implementation of this functionality would be

     (defun neon-modeline-reselect-2 ()
       (set-face-background 'modeline neon-modeline-deselected-background
     		       (selected-frame) '(modeline-background)
     		       'remove-tag-set-prepend))

   `neon-modeline-reselect' may be a preferable implementation here, if
we really want only one frame to have a local specification.  The
`neon-modeline-reselect-2' style would be useful if we had groups of
frames which have _different_ modeline backgrounds when deselected.

   Here's the initialization function, with different semantics from
above.  Note that it is destructive, unless the user saves off the
state of the modeline face before invoking the function.  This is only
a problem if you remove specifications and expect the older ones to
persist.  In this example it should not be an issue.  We use the
customizations defined above.

     (defun neon-modeline-modified-setup ()
       (interactive)
       (set-face-background 'modeline neon-modeline-selected-background
     		       'global nil 'remove-all)
       (add-hook 'select-frame-hook 'neon-modeline-reselect)

     ;;; end of neon-modeline.el

   Note the use of `'remove-all' to clear out stale specifications.
Thus it will be idempotent.


File: lispref.info,  Node: Specifier Types,  Next: Adding Specifications,  Prev: Specifier Instantiation,  Up: Specifiers

48.5 Specifier Types
====================

There are various different types of specifiers.  The type of a
specifier controls what sorts of instantiators are valid, how an
instantiator is instantiated, etc.  Here is a list of built-in specifier
types:

`boolean'
     The valid instantiators are the symbols `t' and `nil'.  Instance
     objects are the same as instantiators so no special instantiation
     function is needed.

`integer'
     The valid instantiators are integers.  Instance objects are the
     same as instantiators so no special instantiation function is
     needed.  `modeline-shadow-thickness' is an example of an integer
     specifier (negative thicknesses indicate that the shadow is drawn
     recessed instead of raised).

`natnum'
     The valid instantiators are natnums (non-negative integers).
     Instance objects are the same as instantiators so no special
     instantiation function is needed.  Natnum specifiers are used for
     dimension variables such as `top-toolbar-height'.

`generic'
     All Lisp objects are valid instantiators.  Instance objects are
     the same as instantiators so no special instantiation function is
     needed.

`font'
     The valid instantiators are strings describing fonts or vectors
     indicating inheritance from the font of some face.  Instance
     objects are font-instance objects, which are specific to a
     particular device.  The instantiation method for font specifiers
     can fail, unlike for integer, natnum, boolean, and generic
     specifiers.

`color'
     The valid instantiators are strings describing colors or vectors
     indicating inheritance from the foreground or background of some
     face.  Instance objects are color-instance objects, which are
     specific to a particular device.  The instantiation method for
     color specifiers can fail, as for font specifiers.

`image'
     Images are perhaps the most complicated type of built-in
     specifier.  The valid instantiators are strings (a filename,
     inline data for a pixmap, or text to be displayed in a text glyph)
     or vectors describing inline data of various sorts or indicating
     inheritance from the background-pixmap property of some face.
     Instance objects are either strings (for text images),
     image-instance objects (for pixmap images), or subwindow objects
     (for subwindow images).  The instantiation method for image
     specifiers can fail, as for font and color specifiers.

`face-boolean'
     The valid instantiators are the symbols `t' and `nil' and vectors
     indicating inheritance from a boolean property of some face.
     Specifiers of this sort are used for all of the built-in boolean
     properties of faces.  Instance objects are either the symbol `t'
     or the symbol `nil'.

`toolbar'
     The valid instantiators are toolbar descriptors, which are lists
     of toolbar-button descriptors (each of which is a vector of two or
     four elements).  *Note Toolbar::, for more information.

   Color and font instance objects can also be used in turn as
instantiators for a new color or font instance object.  Since these
instance objects are device-specific, the instantiator can be used
directly as the new instance object, but only if they are of the same
device.  If the devices differ, the base color or font of the
instantiating object is effectively used instead as the instantiator.

   *Note Faces and Window-System Objects::, for more information on
fonts, colors, and face-boolean specifiers.  *Note Glyphs::, for more
information about image specifiers.  *Note Toolbar::, for more
information on toolbar specifiers.

 -- Function: specifier-type specifier
     This function returns the type of SPECIFIER.  The returned value
     will be a symbol: one of `integer', `boolean', etc., as listed in
     the above table.

   Functions are also provided to query whether an object is a
particular kind of specifier:

 -- Function: boolean-specifier-p object
     This function returns non-`nil' if OBJECT is a boolean specifier.

 -- Function: integer-specifier-p object
     This function returns non-`nil' if OBJECT is an integer specifier.

 -- Function: natnum-specifier-p object
     This function returns non-`nil' if OBJECT is a natnum specifier.

 -- Function: generic-specifier-p object
     This function returns non-`nil' if OBJECT is a generic specifier.

 -- Function: face-boolean-specifier-p object
     This function returns non-`nil' if OBJECT is a face-boolean
     specifier.

 -- Function: toolbar-specifier-p object
     This function returns non-`nil' if OBJECT is a toolbar specifier.

 -- Function: font-specifier-p object
     This function returns non-`nil' if OBJECT is a font specifier.

 -- Function: color-specifier-p object
     This function returns non-`nil' if OBJECT is a color specifier.

 -- Function: image-specifier-p object
     This function returns non-`nil' if OBJECT is an image specifier.


File: lispref.info,  Node: Adding Specifications,  Next: Retrieving Specifications,  Prev: Specifier Types,  Up: Specifiers

48.6 Adding specifications to a Specifier
=========================================

 -- Function: add-spec-to-specifier specifier instantiator &optional
          locale tag-set how-to-add
     This function adds a specification to SPECIFIER.  The
     specification maps from LOCALE (which should be a window, buffer,
     frame, device, or the symbol `global', and defaults to `global')
     to INSTANTIATOR, whose allowed values depend on the type of the
     specifier.  Optional argument TAG-SET limits the instantiator to
     apply only to the specified tag set, which should be a list of
     tags all of which must match the device being instantiated over
     (tags are a device type, a device class, or tags defined with
     `define-specifier-tag').  Specifying a single symbol for TAG-SET
     is equivalent to specifying a one-element list containing that
     symbol.  Optional argument HOW-TO-ADD specifies what to do if
     there are already specifications in the specifier.  It should be
     one of

    `prepend'
          Put at the beginning of the current list of instantiators for
          LOCALE.

    `append'
          Add to the end of the current list of instantiators for
          LOCALE.

    `remove-tag-set-prepend'
          This is the default.  Remove any existing instantiators whose
          tag set is the same as TAG-SET; then put the new instantiator
          at the beginning of the current list.

    `remove-tag-set-append'
          Remove any existing instantiators whose tag set is the same as
          TAG-SET; then put the new instantiator at the end of the
          current list.

    `remove-locale'
          Remove all previous instantiators for this locale before
          adding the new spec.

    `remove-locale-type'
          Remove all specifications for all locales of the same type as
          LOCALE (this includes LOCALE itself) before adding the new
          spec.

    `remove-all'
          Remove all specifications from the specifier before adding
          the new spec.

     `remove-tag-set-prepend' is the default.

     You can retrieve the specifications for a particular locale or
     locale type with the function `specifier-spec-list' or
     `specifier-specs'.

 -- Function: add-spec-list-to-specifier specifier spec-list &optional
          how-to-add
     This function adds a "spec-list" (a list of specifications) to
     SPECIFIER.  The format of a spec-list is

            `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'

     where

        * LOCALE := a window, a buffer, a frame, a device, or `global'

        * TAG-SET := an unordered list of zero or more TAGS, each of
          which is a symbol

        * TAG := a device class (*note Consoles and Devices::), a
          device type, or a tag defined with `define-specifier-tag'

        * INSTANTIATOR := format determined by the type of specifier

     The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair".  A
     list of inst-pairs is called an "inst-list".  The pair `(LOCALE .
     INST-LIST)' is called a "specification".  A spec-list, then, can
     be viewed as a list of specifications.

     HOW-TO-ADD specifies how to combine the new specifications with
     the existing ones, and has the same semantics as for
     `add-spec-to-specifier'.

     The higher-level function `set-specifier' is often more convenient
     because it allows abbreviations of spec-lists to be used instead
     of the heavily nested canonical syntax.  However, one should take
     great care in using them with specifiers types which can have lists
     as instantiators, such as toolbar specifiers and generic
     specifiers.  In those cases it's probably best to use
     `add-spec-to-specifier' or `add-spec-list-to-specifier'.

 -- Macro: let-specifier specifier-list &rest body
     This macro temporarily adds specifications to specifiers,
     evaluates forms in BODY and restores the specifiers to their
     previous states.  The specifiers and their temporary
     specifications are listed in SPECIFIER-LIST.

     The format of SPECIFIER-LIST is

          ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...)

     SPECIFIER is the specifier to be temporarily modified.  VALUE is
     the instantiator to be temporarily added to specifier in LOCALE.
     LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in
     `add-spec-to-specifier'.

     The code resulting from macro expansion will add specifications to
     specifiers using `add-spec-to-specifier'.  After forms in BODY are
     evaluated, the temporary specifications are removed and old
     specifier spec-lists are restored.

     LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to
     `nil'.  The value of the last form in BODY is returned.

     NOTE: If you want the specifier's instance to change in all
     circumstances, use `(selected-window)' as the LOCALE.  If LOCALE
     is `nil' or omitted, it defaults to `global'.

     The following example removes the 3D modeline effect in the
     currently selected window for the duration of a second:

          (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
            (sit-for 1))

 -- Function: set-specifier specifier value &optional locale tag-set
          how-to-add
     This function adds some specifications to SPECIFIER.  VALUE can be
     a single instantiator or tagged instantiator (added as a global
     specification), a list of tagged and/or untagged instantiators
     (added as a global specification), a cons of a locale and
     instantiator or locale and instantiator list, a list of such
     conses, or nearly any other reasonable form.  More specifically,
     VALUE can be anything accepted by `canonicalize-spec-list'
     (described below).

     LOCALE, TAG-SET, and HOW-TO-ADD are the same as in
     `add-spec-to-specifier'.

     Note that `set-specifier' is exactly complementary to
     `specifier-specs' except in the case where SPECIFIER has no specs
     at all in it but `nil' is a valid instantiator (in that case,
     `specifier-specs' will return `nil' (meaning no specs) and
     `set-specifier' will interpret the `nil' as meaning "I'm adding a
     global instantiator and its value is `nil'"), or in strange cases
     where there is an ambiguity between a spec-list and an inst-list,
     etc. (The built-in specifier types are designed in such a way as
     to avoid any such ambiguities.)  For robust code, `set-specifier'
     should probably be avoided for specifier types which accept lists
     as instantiators (currently toolbar specifiers and generic
     specifiers).

     If you want to work with spec-lists, you should probably not use
     these functions, but should use the lower-level functions
     `specifier-spec-list' and `add-spec-list-to-specifier'.  These
     functions always work with fully-qualified spec-lists; thus, there
     is no ambiguity.

 -- Function: canonicalize-inst-pair inst-pair specifier-type &optional
          noerror
     This function canonicalizes the given INST-PAIR.

     SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
     will be used for.

     Canonicalizing means converting to the full form for an inst-pair,
     i.e.  `(TAG-SET . INSTANTIATOR)'.  A single, untagged instantiator
     is given a tag set of `nil' (the empty set), and a single tag is
     converted into a tag set consisting only of that tag.

     If NOERROR is non-`nil', signal an error if the inst-pair is
     invalid; otherwise return `t'.

 -- Function: canonicalize-inst-list inst-list specifier-type &optional
          noerror
     This function canonicalizes the given INST-LIST (a list of
     inst-pairs).

     SPECIFIER-TYPE specifies the type of specifier that this INST-LIST
     will be used for.

     Canonicalizing means converting to the full form for an inst-list,
     i.e.  `((TAG-SET . INSTANTIATOR) ...)'.  This function accepts a
     single inst-pair or any abbreviation thereof or a list of
     (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.)

     If NOERROR is non-`nil', signal an error if the inst-list is
     invalid; otherwise return `t'.

 -- Function: canonicalize-spec spec specifier-type &optional noerror
     This function canonicalizes the given SPEC (a specification).

     SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
     will be used for.

     Canonicalizing means converting to the full form for a spec, i.e.
     `(LOCALE (TAG-SET . INSTANTIATOR) ...)'.  This function accepts a
     possibly abbreviated inst-list or a cons of a locale and a
     possibly abbreviated inst-list. (See `canonicalize-inst-list'.)

     If NOERROR is `nil', signal an error if the specification is
     invalid; otherwise return `t'.

 -- Function: canonicalize-spec-list spec-list specifier-type &optional
          noerror
     This function canonicalizes the given SPEC-LIST (a list of
     specifications).

     SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
     will be used for.

     If NOERROR is `nil', signal an error if the spec-list is invalid;
     otherwise return `t' for an invalid spec-list.  (Note that this
     cannot be confused with a canonical spec-list.)

     Canonicalizing means converting to the full form for a spec-list,
     i.e.  `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'.  This
     function accepts a possibly abbreviated specification or a list of
     such things. (See `canonicalize-spec'.) This is the function used
     to convert spec-lists accepted by `set-specifier' and such into a
     form suitable for `add-spec-list-to-specifier'.

     This function tries extremely hard to resolve any ambiguities, and
     the built-in specifier types (font, image, toolbar, etc.) are
     designed so that there won't be any ambiguities.

     The canonicalization algorithm is as follows:

       1. Attempt to parse SPEC-LIST as a single, possibly abbreviated,
          specification.

       2. If that fails, attempt to parse SPEC-LIST as a list of
          (abbreviated) specifications.

       3. If that fails, SPEC-LIST is invalid.

     A possibly abbreviated specification SPEC is parsed by

       1. Attempt to parse SPEC as a possibly abbreviated inst-list.

       2. If that fails, attempt to parse SPEC as a cons of a locale
          and an (abbreviated) inst-list.

       3. If that fails, SPEC is invalid.

     A possibly abbreviated inst-list INST-LIST is parsed by

       1. Attempt to parse INST-LIST as a possibly abbreviated
          inst-pair.

       2. If that fails, attempt to parse INST-LIST as a list of
          (abbreviated) inst-pairs.

       3. If that fails, INST-LIST is invalid.

     A possibly abbreviated inst-pair INST-PAIR is parsed by

       1. Check if INST-PAIR is `valid-instantiator-p'.

       2. If not, check if INST-PAIR is a cons of something that is a
          tag, ie, `valid-specifier-tag-p', and something that is
          `valid-instantiator-p'.

       3. If not, check if INST-PAIR is a cons of a list of tags and
          something that is `valid-instantiator-p'.

       4. Otherwise, INST-PAIR is invalid.

     In summary, this function generally prefers more abbreviated forms.


File: lispref.info,  Node: Retrieving Specifications,  Next: Specifier Tag Functions,  Prev: Adding Specifications,  Up: Specifiers

48.7 Retrieving the Specifications from a Specifier
===================================================

 -- Function: specifier-spec-list specifier &optional locale tag-set
          exact-p
     This function returns the spec-list of specifications for
     SPECIFIER in LOCALE.

     If LOCALE is a particular locale (a window, buffer, frame, device,
     or the symbol `global'), a spec-list consisting of the
     specification for that locale will be returned.

     If LOCALE is a locale type (i.e. one of the symbols `window',
     `buffer', `frame', or `device'), a spec-list of the specifications
     for all locales of that type will be returned.

     If LOCALE is `nil' or the symbol `all', a spec-list of all
     specifications in SPECIFIER will be returned.

     LOCALE can also be a list of locales, locale types, and/or `all';
     the result is as if `specifier-spec-list' were called on each
     element of the list and the results concatenated together.

     Only instantiators where TAG-SET (a list of zero or more tags) is
     a subset of (or possibly equal to) the instantiator's tag set are
     returned.  (The default value of `nil' is a subset of all tag sets,
     so in this case no instantiators will be screened out.) If EXACT-P
     is non-`nil', however, TAG-SET must be equal to an instantiator's
     tag set for the instantiator to be returned.

 -- Function: specifier-specs specifier &optional locale tag-set exact-p
     This function returns the specification(s) for SPECIFIER in LOCALE.

     If LOCALE is a single locale or is a list of one element
     containing a single locale, then a "short form" of the
     instantiators for that locale will be returned.  Otherwise, this
     function is identical to `specifier-spec-list'.

     The "short form" is designed for readability and not for ease of
     use in Lisp programs, and is as follows:

       1. If there is only one instantiator, then an inst-pair (i.e.
          cons of tag and instantiator) will be returned; otherwise a
          list of inst-pairs will be returned.

       2. For each inst-pair returned, if the instantiator's tag is
          `any', the tag will be removed and the instantiator itself
          will be returned instead of the inst-pair.

       3. If there is only one instantiator, its value is `nil', and
          its tag is `any', a one-element list containing `nil' will be
          returned rather than just `nil', to distinguish this case
          from there being no instantiators at all.


 -- Function: specifier-fallback specifier
     This function returns the fallback value for SPECIFIER.  Fallback
     values are provided by the C code for certain built-in specifiers
     to make sure that instantiation won't fail even if all specs are
     removed from the specifier, or to implement simple inheritance
     behavior (e.g. this method is used to ensure that faces other than
     `default' inherit their attributes from `default').  By design,
     you cannot change the fallback value, and specifiers created with
     `make-specifier' will never have a fallback (although a similar,
     Lisp-accessible capability may be provided in the future to allow
     for inheritance).

     The fallback value will be an inst-list that is instantiated like
     any other inst-list, a specifier of the same type as SPECIFIER
     (results in inheritance), or `nil' for no fallback.

     When you instantiate a specifier, you can explicitly request that
     the fallback not be consulted. (The C code does this, for example,
     when merging faces.) See `specifier-instance'.


File: lispref.info,  Node: Specifier Tag Functions,  Next: Specifier Instantiation Functions,  Prev: Retrieving Specifications,  Up: Specifiers

48.8 Working With Specifier Tags
================================

A specifier tag set is an entity that is attached to an instantiator
and can be used to restrict the scope of that instantiator to a
particular device class or device type and/or to mark instantiators
added by a particular package so that they can be later removed.

   A specifier tag set consists of a list of zero or more specifier
tags, each of which is a symbol that is recognized by XEmacs as a tag.
(The valid device types and device classes are always tags, as are any
tags defined by `define-specifier-tag'.) It is called a "tag set" (as
opposed to a list) because the order of the tags or the number of times
a particular tag occurs does not matter.

   Each tag has a device predicate associated with it, which specifies
whether that tag applies to a particular device.  The tags which are
device types and classes match devices of that type or class.
User-defined tags can have any device predicate, or none (meaning that
all devices match).  When attempting to instantiate a specifier, a
particular instantiator is only considered if the device of the domain
being instantiated over matches all tags in the tag set attached to
that instantiator.

   Each tag can also have a charset predicate, specifying whether that
tag applies to a particular charset. There are a few tags with
predefined charset predicates created to allow sensible fallbacks in
the face code--see the output of `(specifier-fallback (face-font
'default))' for these.

   Most of the time, a tag set is not specified, and the instantiator
gets a null tag set, which matches all devices and all character sets
(when possible; fonts with an inappropriate repertoire will not match,
for example).

 -- Function: valid-specifier-tag-p tag
     This function returns non-`nil' if TAG is a valid specifier tag.

 -- Function: valid-specifier-tag-set-p tag-set
     This function returns non-`nil' if TAG-SET is a valid specifier
     tag set.

 -- Function: canonicalize-tag-set tag-set
     This function canonicalizes the given tag set.  Two canonicalized
     tag sets can be compared with `equal' to see if they represent the
     same tag set. (Specifically, canonicalizing involves sorting by
     symbol name and removing duplicates.)

 -- Function: device-matches-specifier-tag-set-p device tag-set
     This function returns non-`nil' if DEVICE matches specifier tag
     set TAG-SET.  This means that DEVICE matches each tag in the tag
     set.

 -- Function: define-specifier-tag tag &optional device-predicate
          charset-predicate
     This function defines a new specifier tag.  If DEVICE-PREDICATE is
     specified, it should be a function of one argument (a device) that
     specifies whether the tag matches that particular device.  If
     DEVICE-PREDICATE is omitted, the tag matches all devices.

     If CHARSET-PREDICATE is specified, it should be a function taking
     one character set argument that specifies whether the tag matches
     that particular character set.

     You can redefine an existing user-defined specifier tag.  However,
     you cannot redefine the built-in specifier tags (the device types
     and classes) or the symbols `nil', `t', `all', or `global'.

 -- Function: device-matching-specifier-tag-list &optional device
     This function returns a list of all specifier tags matching
     DEVICE.  DEVICE defaults to the selected device if omitted.

 -- Function: specifier-tag-list
     This function returns a list of all currently-defined specifier
     tags.  This includes the built-in ones (the device types and
     classes).

 -- Function: specifier-tag-device-predicate tag
     This function returns the device predicate for the given specifier
     tag.

 -- Function: specifier-tag-charset-predicate tag
     This function returns the charset predicate for the given
     specifier tag.


File: lispref.info,  Node: Specifier Instantiation Functions,  Next: Specifier Examples,  Prev: Specifier Tag Functions,  Up: Specifiers

48.9 Functions for Instantiating a Specifier
============================================

 -- Function: specifier-instance specifier &optional domain default
          no-fallback
     This function instantiates SPECIFIER (returns its value) in
     DOMAIN.  If no instance can be generated for this domain, return
     DEFAULT.

     DOMAIN should be a window, frame, or device.  Other values that
     are legal as a locale (e.g. a buffer) are not valid as a domain
     because they do not provide enough information to identify a
     particular device (see `valid-specifier-domain-p').  DOMAIN
     defaults to the selected window if omitted.

     "Instantiating" a specifier in a particular domain means
     determining the specifier's "value" in that domain.  This is
     accomplished by searching through the specifications in the
     specifier that correspond to all locales that can be derived from
     the given domain, from specific to general.  In most cases, the
     domain is an Emacs window.  In that case specifications are
     searched for as follows:

       1. A specification whose locale is the window itself;

       2. A specification whose locale is the window's buffer;

       3. A specification whose locale is the window's frame;

       4. A specification whose locale is the window's frame's device;

       5. A specification whose locale is the symbol `global'.

     If all of those fail, then the C-code-provided fallback value for
     this specifier is consulted (see `specifier-fallback').  If it is
     an inst-list, then this function attempts to instantiate that list
     just as when a specification is located in the first five steps
     above.  If the fallback is a specifier, `specifier-instance' is
     called recursively on this specifier and the return value used.
     Note, however, that if the optional argument NO-FALLBACK is
     non-`nil', the fallback value will not be consulted.

     Note that there may be more than one specification matching a
     particular locale; all such specifications are considered before
     looking for any specifications for more general locales.  Any
     particular specification that is found may be rejected because it
     is tagged to a particular device class (e.g. `color') or device
     type (e.g. `x') or both and the device for the given domain does
     not match this, or because the specification is not valid for the
     device of the given domain (e.g.  the font or color name does not
     exist for this particular X server).

     The returned value is dependent on the type of specifier.  For
     example, for a font specifier (as returned by the `face-font'
     function), the returned value will be a font-instance object.  For
     images, the returned value will be a string, pixmap, or subwindow.

 -- Function: specifier-matching-instance specifier matchspec &optional
          domain default no-fallback
     This function returns an instance for SPECIFIER in DOMAIN that
     matches MATCHSPEC.  If no instance can be generated for DOMAIN,
     return DEFAULT.  *Note Specifier Compatibility Notes::.

     This function is identical to `specifier-instance' except that a
     specification will only be considered if it matches MATCHSPEC.
     The definition of "match," and allowed values for MATCHSPEC, are
     dependent on the particular type of specifier.  Here are some
     examples:

        * For chartable (e.g. display table) specifiers, MATCHSPEC
          should be a character, and the specification (a chartable)
          must give a value for that character in order to be
          considered.  This allows you to specify, _e.g._, a
          buffer-local display table that only gives values for
          particular characters.  All other characters are handled as
          if the buffer-local display table is not there. (Chartable
          specifiers are not yet implemented.)

        * For font specifiers, MATCHSPEC should be a list (CHARSET .
          STAGE).  On X11 the specification (a font string) should, for
          clarity, have a registry that matches the charset's registry,
          but the redisplay code will specify the XLFD CHARSET_REGISTRY
          and CHARSET_ENCODING fields itself.  This makes minimal sense
          without Mule support.  STAGE can be one of the symbols
          `'initial' and `'final'; on X11, `'initial' means "search for
          fonts using the charset registry of this charset" and
          `'final' means "search for fonts using `iso10646-1' as their
          charset registries, with the expectation that characters will
          be translated to Unicode at redisplay."  Their meanings are
          similar on MS Windows, with the difference that the actual
          repertoire of the font is checked when deciding if a
          matchspec with `'final' matches.

          For example, the following code emulates what redisplay does
          when deciding what font to use for ethiopic with the default
          face (ignoring, for the moment, fallbacks):
               (or
                (specifier-matching-instance (face-font 'default)
               			      (cons 'ethiopic 'initial))
                (specifier-matching-instance (face-font 'default)
               			      (cons 'ethiopic 'final)))

 -- Function: specifier-instance-from-inst-list specifier domain
          inst-list &optional default
     This function attempts to convert a particular inst-list into an
     instance.  This attempts to instantiate INST-LIST in the given
     DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
     If the instantiation fails, DEFAULT is returned.  In most
     circumstances, you should not use this function; use
     `specifier-instance' instead.


File: lispref.info,  Node: Specifier Examples,  Next: Creating Specifiers,  Prev: Specifier Instantiation Functions,  Up: Specifiers

48.10 Examples of Specifier Usage
=================================

Now let us present an example to clarify the theoretical discussions we
have been through.  In this example, we will use the general specifier
functions for clarity.  Keep in mind that many types of specifiers, and
some other types of objects that are associated with specifiers (e.g.
faces), provide convenience functions making it easier to work with
objects of that type.

   Let us consider the background color of the default face.  A
specifier is used to specify how that color will appear in different
domains.  First, let's retrieve the specifier:

     (setq sp (face-property 'default 'background))
         =>   #<color-specifier 0x3da>

     (specifier-specs sp)
         =>   ((#<buffer "device.c"> (nil . "forest green"))
                      (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
                      (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
                                                (nil . "moccasin"))
                      (#<x-frame "VM" 0x4ac> (nil . "magenta"))
                      (global ((tty) . "cyan") (nil . "white"))
                     )

   Then, say we want to determine what the background color of the
default face is for the window currently displaying the buffer
`*scratch*'.  We call

     (get-buffer-window "*scratch*")
         => #<window on "*scratch*" 0x4ad>
     (window-frame (get-buffer-window "*scratch*"))
         => #<x-frame "emacs" 0x4ac>
     (specifier-instance sp (get-buffer-window "*scratch*"))
         => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>

   Note that we passed a window to `specifier-instance', not a buffer.
We cannot pass a buffer because a buffer by itself does not provide
enough information.  The buffer might not be displayed anywhere at all,
or could be displayed in many different frames on different devices.

   The result is arrived at like this:

  1. First, we look for a specification matching the buffer displayed
     in the window, i.e. `*scratch*'.  There are none, so we proceed.

  2. Then, we look for a specification matching the window itself.
     Again, there are none.

  3. Then, we look for a specification matching the window's frame.  The
     specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
     found.  We call the instantiation method for colors, passing it the
     locale we were searching over (i.e. the window, in this case) and
     the instantiator (`"puke orange"').  However, the particular device
     which this window is on (let's say it's an X connection) doesn't
     recognize the color `"puke orange"', so the specification is
     rejected.

  4. So we continue looking for a specification matching the window's
     frame.  We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'.  Again,
     we call the instantiation method for colors.  This time, the X
     server our window is on recognizes the color `moccasin', and so the
     instantiation method succeeds and returns a color instance.

   Here's another example, which implements something like GNU Emacs's
"frame-local" variables.

     ;; Implementation

     ;; There are probably better ways to write this macro
     ;; Heaven help you if VAR is a buffer-local; you will become very
     ;; confused.  Probably should error on that.
     (defmacro define-frame-local-variable (var)
       "Make the unbound symbol VAR become a frame-local variable."
       (let ((val (if (boundp var) (symbol-value var) nil)))
         `(progn
           (setq ,var (make-specifier 'generic))
           (add-spec-to-specifier ,var ',val 'global))))

     ;; I'm not real happy about this terminology, how can `setq' be a defun?
     ;; But `frame-set' would have people writing "(frame-set 'foo value)".
     (defun frame-setq (var value &optional frame)
       "Set the local value of VAR to VALUE in FRAME.

     FRAME defaults to the selected frame."
       (and frame (not (framep frame))
            (error 'invalid-argument "FRAME must be a frame", frame))
       (add-spec-to-specifier var value (or frame (selected-frame))))

     (defun frame-value (var &optional frame)
       "Get the local value of VAR in FRAME.

     FRAME defaults to the selected frame."
       (and frame (not (framep frame))
            (error 'invalid-argument "FRAME must be a frame", frame))
       ;; this is not just a map from frames to values; it also falls back
       ;; to the global value
       (specifier-instance var (or frame (selected-frame))))

     ;; for completeness
     (defun frame-set-default (var value)
       "Set the default value of frame-local variable VAR to VALUE."
       (add-spec-to-specifier var value 'global))

     (defun frame-get-default (var)
       "Get the default value of frame-local variable VAR."
       (car (specifier-specs var 'global)))

   Now you can execute the above definitions (eg, with `eval-last-sexp')
and switch to `*scratch*' to play.  Things will work differently if you
already have a variable named `foo'.

     ;; Usage

     foo
     error--> Symbol's value as variable is void: foo

     (define-frame-local-variable foo)
     => nil

     ;; the value of foo is a specifier, which is an opaque object;
     ;; you must use accessor functions to get values

     foo
     => #<generic-specifier global=(nil) 0x4f5cb>

     ;; since no frame-local value is set, the global value (which is the
     ;; constant `nil') is returned
     (frame-value foo)
     => nil

     ;; get the default explicitly
     (frame-get-default foo)
     => nil

     ;; get the whole specification list
     (specifier-specs foo 'global)
     => (nil)

     ;; give foo a frame-local value

     (frame-setq foo 'bar)
     => nil

     ;; access foo in several ways

     ;; Note that the print function for this kind of specifier only
     ;; gives you the global setting.  To get the full list of specs for
     ;; debugging or study purposes, you must use specifier-specs or
     ;; specifier-spec-list.
     foo
     => #<generic-specifier global=(nil) 0x4f5cb>

     ;; get the whole specification list
     (specifier-specs foo)
     => ((#<x-frame "Message" 0x1bd66> (nil . bar)) (global (nil)))

     ;; get the frame-local value
     (frame-value foo)
     => bar

     ;; get the default explicitly
     (frame-get-default foo)
     => nil

     ;; Switch to another frame and evaluate:
     ;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET
     => baz

     ;; Switch back.
     ;; C-x 5 o
     (specifier-specs foo)
     => ((#<x-frame "emacs" 0x28ec> (nil . baz))
         (#<x-frame "Message" 0x1bd66> (nil . bar))
         (global (nil)))

     (frame-value foo)
     => bar

     (frame-get-default foo)
     => nil

   Note that since specifiers generalize both frame-local and
buffer-local variables in a sensible way, XEmacs is not likely to put a
high priority on implementing frame-local variables *Note Specifier
Compatibility Notes::.


File: lispref.info,  Node: Creating Specifiers,  Next: Specifier Validation Functions,  Prev: Specifier Examples,  Up: Specifiers

48.11 Creating New Specifier Objects
====================================

 -- Function: make-specifier type
     This function creates a new specifier.

     A specifier is an object that can be used to keep track of a
     property whose value can be per-buffer, per-window, per-frame, or
     per-device, and can further be restricted to a particular
     device-type or device-class.  Specifiers are used, for example,
     for the various built-in properties of a face; this allows a face
     to have different values in different frames, buffers, etc.  For
     more information, see `specifier-instance', `specifier-specs', and
     `add-spec-to-specifier'; or, for a detailed description of
     specifiers, including how they are instantiated over a particular
     domain (i.e. how their value in that domain is determined), see
     the chapter on specifiers in the XEmacs Lisp Reference Manual.

     TYPE specifies the particular type of specifier, and should be one
     of the symbols `generic', `integer', `natnum', `boolean', `color',
     `font', `image', `face-boolean', or `toolbar'.

     For more information on particular types of specifiers, see the
     functions `make-generic-specifier', `make-integer-specifier',
     `make-natnum-specifier', `make-boolean-specifier',
     `make-color-specifier', `make-font-specifier',
     `make-image-specifier', `make-face-boolean-specifier', and
     `make-toolbar-specifier'.

 -- Function: make-specifier-and-init type spec-list &optional
          dont-canonicalize
     This function creates and initializes a new specifier.

     This is a convenience API combining `make-specifier' and
     `set-specifier' that allows you to create a specifier and add
     specs to it at the same time.  TYPE specifies the specifier type.
     Allowed types are as for `make-specifier'.

     SPEC-LIST supplies the specification(s) to be added to the
     specifier.  Any abbreviation of the full spec-list form accepted
     by `canonicalize-spec-list' may be used.  However, if the optional
     argument DONT-CANONICALIZE is non-`nil', canonicalization is not
     performed, and the SPEC-LIST must already be in full form.

 -- Function: make-integer-specifier spec-list
     Return a new `integer' specifier object with the given
     specification list.  SPEC-LIST can be a list of specifications
     (each of which is a cons of a locale and a list of instantiators),
     a single instantiator, or a list of instantiators.

     Valid instantiators for integer specifiers are integers.

 -- Function: make-boolean-specifier spec-list
     Return a new `boolean' specifier object with the given
     specification list.  SPEC-LIST can be a list of specifications
     (each of which is a cons of a locale and a list of instantiators),
     a single instantiator, or a list of instantiators.

     Valid instantiators for boolean specifiers are `t' and `nil'.

 -- Function: make-natnum-specifier spec-list
     Return a new `natnum' specifier object with the given specification
     list.  SPEC-LIST can be a list of specifications (each of which is
     a cons of a locale and a list of instantiators), a single
     instantiator, or a list of instantiators.

     Valid instantiators for natnum specifiers are non-negative
     integers.

 -- Function: make-generic-specifier spec-list
     Return a new `generic' specifier object with the given
     specification list.  SPEC-LIST can be a list of specifications
     (each of which is a cons of a locale and a list of instantiators),
     a single instantiator, or a list of instantiators.

     Valid instantiators for generic specifiers are all Lisp values.
     They are returned back unchanged when a specifier is instantiated.

 -- Function: make-display-table-specifier spec-list
     Return a new `display-table' specifier object with the given spec
     list.  SPEC-LIST can be a list of specifications (each of which is
     a cons of a locale and a list of instantiators), a single
     instantiator, or a list of instantiators.

     Valid instantiators for display-table specifiers are described in
     detail in the doc string for `current-display-table' (*note Active
     Display Table::).


File: lispref.info,  Node: Specifier Validation Functions,  Next: Other Specification Functions,  Prev: Creating Specifiers,  Up: Specifiers

48.12 Functions for Checking the Validity of Specifier Components
=================================================================

 -- Function: valid-specifier-domain-p domain
     This function returns non-`nil' if DOMAIN is a valid specifier
     domain.  A domain is used to instantiate a specifier (i.e.
     determine the specifier's value in that domain).  Valid domains
     are a window, frame, or device.  (`nil' is not valid.)

 -- Function: valid-specifier-locale-p locale
     This function returns non-`nil' if LOCALE is a valid specifier
     locale.  Valid locales are a device, a frame, a window, a buffer,
     and `global'.  (`nil' is not valid.)

 -- Function: valid-specifier-locale-type-p locale-type
     Given a specifier LOCALE-TYPE, this function returns non-`nil' if
     it is valid.  Valid locale types are the symbols `global',
     `device', `frame', `window', and `buffer'. (Note, however, that in
     functions that accept either a locale or a locale type, `global'
     is considered an individual locale.)

 -- Function: valid-specifier-type-p specifier-type
     Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
     valid.  Valid types are `generic', `integer', `boolean', `color',
     `font', `image', `face-boolean', and `toolbar'.

 -- Function: valid-specifier-tag-p tag
     This function returns non-`nil' if TAG is a valid specifier tag.

 -- Function: valid-instantiator-p instantiator specifier-type
     This function returns non-`nil' if INSTANTIATOR is valid for
     SPECIFIER-TYPE.

 -- Function: valid-inst-list-p inst-list type
     This function returns non-`nil' if INST-LIST is valid for
     specifier type TYPE.

 -- Function: valid-spec-list-p spec-list type
     This function returns non-`nil' if SPEC-LIST is valid for
     specifier type TYPE.

 -- Function: check-valid-instantiator instantiator specifier-type
     This function signals an error if INSTANTIATOR is invalid for
     SPECIFIER-TYPE.

 -- Function: check-valid-inst-list inst-list type
     This function signals an error if INST-LIST is invalid for
     specifier type TYPE.

 -- Function: check-valid-spec-list spec-list type
     This function signals an error if SPEC-LIST is invalid for
     specifier type TYPE.


File: lispref.info,  Node: Other Specification Functions,  Next: Specifier Compatibility Notes,  Prev: Specifier Validation Functions,  Up: Specifiers

48.13 Other Functions for Working with Specifications in a Specifier
====================================================================

 -- Function: copy-specifier specifier &optional dest locale tag-set
          exact-p how-to-add
     This function copies SPECIFIER to DEST, or creates a new one if
     DEST is `nil'.

     If DEST is `nil' or omitted, a new specifier will be created and
     the specifications copied into it.  Otherwise, the specifications
     will be copied into the existing specifier in DEST.

     If LOCALE is `nil' or the symbol `all', all specifications will be
     copied.  If LOCALE is a particular locale, the specification for
     that particular locale will be copied.  If LOCALE is a locale
     type, the specifications for all locales of that type will be
     copied.  LOCALE can also be a list of locales, locale types,
     and/or `all'; this is equivalent to calling `copy-specifier' for
     each of the elements of the list.  See `specifier-spec-list' for
     more information about LOCALE.

     Only instantiators where TAG-SET (a list of zero or more tags) is
     a subset of (or possibly equal to) the instantiator's tag set are
     copied.  (The default value of `nil' is a subset of all tag sets,
     so in this case no instantiators will be screened out.) If EXACT-P
     is non-`nil', however, TAG-SET must be equal to an instantiator's
     tag set for the instantiator to be copied.

     Optional argument HOW-TO-ADD specifies what to do with existing
     specifications in DEST.  If `nil', then whichever locales or locale
     types are copied will first be completely erased in DEST.
     Otherwise, it is the same as in `add-spec-to-specifier'.

 -- Function: remove-specifier specifier &optional locale tag-set
          exact-p
     This function removes specification(s) for SPECIFIER.

     If LOCALE is a particular locale (a buffer, window, frame, device,
     or the symbol `global'), the specification for that locale will be
     removed.

     If instead, LOCALE is a locale type (i.e. a symbol `buffer',
     `window', `frame', or `device'), the specifications for all
     locales of that type will be removed.

     If LOCALE is `nil' or the symbol `all', all specifications will be
     removed.

     LOCALE can also be a list of locales, locale types, and/or `all';
     this is equivalent to calling `remove-specifier' for each of the
     elements in the list.

     Only instantiators where TAG-SET (a list of zero or more tags) is
     a subset of (or possibly equal to) the instantiator's tag set are
     removed.  (The default value of `nil' is a subset of all tag sets,
     so in this case no instantiators will be screened out.) If EXACT-P
     is non-`nil', however, TAG-SET must be equal to an instantiator's
     tag set for the instantiator to be removed.

 -- Function: map-specifier specifier func &optional locale maparg
     This function applies FUNC to the specification(s) for LOCALE in
     SPECIFIER.

     If optional LOCALE is a locale, FUNC will be called for that
     locale.  If LOCALE is a locale type, FUNC will be mapped over all
     locales of that type.  If LOCALE is `nil' or the symbol `all',
     FUNC will be mapped over all locales in SPECIFIER.

     Optional MS-TAG-SET and MS-EXACT-P are as in
     `specifier-spec-list''.  Optional MS-MAPARG will be passed to
     MS-FUNC.

     FUNC is called with four arguments: the SPECIFIER, the locale
     being mapped over, the inst-list for that locale, and the optional
     MAPARG.  If any invocation of FUNC returns non-`nil', the mapping
     will stop and the returned value becomes the value returned from
     `map-specifier'.  Otherwise, `map-specifier' returns `nil'.

 -- Function: specifier-locale-type-from-locale locale
     Given a specifier LOCALE, this function returns its type.


File: lispref.info,  Node: Specifier Compatibility Notes,  Prev: Other Specification Functions,  Up: Specifiers

48.14 Specifier Compatibility Notes
===================================

This node describes compatibility issues in the use of specifiers known
as of 2004-01-22.  The main text refers to XEmacs 21.5.16.

   Effort will be made to describe changes in the API or semantics
between XEmacs versions accurately.  Any inaccuracy or missing
information about backward and forward compatibility is a bug, and we
greatly appreciate your reports, whether you can provide a patch or not.

   A change is reported as "changed" when we believe that the new or
changed API will cause old code to malfunction.  When old code is
believed to be upward compatible with the changed API, the change is
reported as "added".

   We would like to also describe compatibility with GNU Emacs, but
this is not so high a priority.  Inaccuracies or omissions will be
addressed at the priority of a feature request, and as such processing
will be greatly expedited if you can provide a patch.

48.14.1 Compatibility with GNU Emacs
------------------------------------

Specifiers are not used in GNU Emacs.  If your program depends on
specifers, you will probably have to rewrite the functionality
completely for GNU Emacs.  If you wish to maximize portability, you
should plan to encapsulate use of specifiers.

   GNU Emacs provides two features for context-sensitive variables,
buffer-local variables and frame-local variables.  XEmacs implements
buffer-local variables 100%-compatibly with GNU Emacs.  If buffer-local
variables will server your purpose and portability is a major concern,
consider using them instead of specifiers.

   XEmacs does not implement frame-local variables at all.  In this case
specifiers must be used to provide equivalent functionality.

   It is not clear whether XEmacs will provide this feature in the
future.  In fact, some core XEmacs developers think that both
frame-local variables and buffer-local variables are evil, because the
declaration is both global and invisible.  That is, you cannot tell
whether a variable is "normal," buffer-local, or frame-local just by
looking at it.  So if you have namespace management problems, and some
other Lisp package happens to use a variable name that you already
declared frame- or buffer-local, weird stuff happens, and it is
extremely hard to track down.

48.14.2 Backwards Compatibility with XEmacs 21.4
------------------------------------------------

Sorry, I'm unwilling to find out exactly when these changes were made.

   Changed by 21.5.16: the second argument of
`specifier-matching-instance' is now a cons of a charset and a boolean
value.  Previously it was a charset or a symbol (a name of a charset).
It was not documented in Info.

   Changed by 21.5.16: the specifier-specific error symbols
`specifier_syntax_error', `specifier_argument_error', and
`specifier_change_error' were removed.  (This probably only affected
internal code.)

   Added by 21.5.16: `map-specifier' got two new arguments,
`ms-tag-set' and `ms-exact-p'.

   Added by 21.5.16: when skipping instantiators, XEmacs warns at level
`debug'.

   Added by 21.5.16: new convenience APIs: `instance-to-instantiator',
`device-type-matches-spec', `add-tag-to-inst-list',
`derive-domain-from-locale', `derive-device-type-from-tag-set',
`derive-device-type-from-locale-and-tag-set', and
`derive-specifier-specs-from-locale'.


File: lispref.info,  Node: Faces and Window-System Objects,  Next: Glyphs,  Prev: Specifiers,  Up: Top

49 Faces and Window-System Objects
**********************************

* Menu:

* Faces::		Controlling the way text looks.
* Fonts::		Controlling the typeface of text.
* Colors::		Controlling the color of text and pixmaps.


File: lispref.info,  Node: Faces,  Next: Fonts,  Prev: Faces and Window-System Objects,  Up: Faces and Window-System Objects

49.1 Faces
==========

A "face" is a named collection of graphical properties: font,
foreground color, background color, background pixmap, optional
underlining, and (on TTY devices) whether the text is to be highlighted,
dimmed, blinking, or displayed in reverse video.  Faces control the
display of text on the screen.  Every face has a name, which is a symbol
such as `default' or `modeline'.

   Each built-in property of a face is controlled using a specifier,
which allows it to have separate values in particular buffers, frames,
windows, and devices.  These properties are computed when the face is
instantiated, allowing them to vary according to properties of the
display device, such as type (X or TTY), visual class (color, mono, or
grayscale), and number of colors displayable on the device.  *Note
Specifiers::, for more information on specifiers.  *Note Face
Definitions::, for defining faces whose properties vary according to
their runtime environments.

   The face named `default' is used for ordinary text.  The face named
`modeline' is used for displaying the modeline.  The face named
`highlight' is used for highlighted extents (*note Extents::).  The
faces named `left-margin' and `right-margin' are used for the left and
right margin areas, respectively (*note Annotations::).  The face named
`zmacs-region' is used for the highlighted region between point and
mark.

* Menu:

* Merging Faces::		How XEmacs decides which face to use
				  for a character.
* Basic Face Functions::	How to define and examine faces.
* Face Properties::		How to access and modify a face's properties.
* Face Convenience Functions::	Convenience functions for accessing
				  particular properties of a face.
* Other Face Display Functions:: Other functions pertaining to how a
				  a face appears.


File: lispref.info,  Node: Merging Faces,  Next: Basic Face Functions,  Prev: Faces,  Up: Faces

49.1.1 Merging Faces for Display
--------------------------------

Here are all the ways to specify which face to use for display of text:

   * With defaults.  Each frame has a "default face", which is used for
     all text that doesn't somehow specify another face.  The face named
     `default' applies to the text area, while the faces `left-margin'
     and `right-margin' apply to the left and right margin areas.

   * With text properties.  A character may have a `face' property; if
     so, it's displayed with that face. (Text properties are actually
     implemented in terms of extents.) *Note Text Properties::.

   * With extents.  An extent may have a `face' property, which applies
     to all the text covered by the extent; in addition, if the
     `highlight' property is set, the `highlight' property applies when
     the mouse moves over the extent or if the extent is explicitly
     highlighted.  *Note Extents::.

   * With annotations.  Annotations that are inserted into a buffer can
     specify their own face. (Annotations are actually implemented in
     terms of extents.)  *Note Annotations::.

   If these various sources together specify more than one face for a
particular character, XEmacs merges the properties of the various faces
specified.  Extents, text properties, and annotations all use the same
underlying representation (as extents).  When multiple extents cover one
character, an extent with higher priority overrides those with lower
priority.  *Note Extents::.  If no extent covers a particular character,
the `default' face is used.

   If a background pixmap is specified, it determines what will be
displayed in the background of text characters.  If the background
pixmap is actually a pixmap, with its colors specified, those colors are
used; if it is a bitmap, the face's foreground and background colors are
used to color it.


File: lispref.info,  Node: Basic Face Functions,  Next: Face Properties,  Prev: Merging Faces,  Up: Faces

49.1.2 Basic Functions for Working with Faces
---------------------------------------------

The properties a face can specify include the font, the foreground
color, the background color, the background pixmap, the underlining,
the display table, and (for TTY devices) whether the text is to be
highlighted, dimmed, blinking, or displayed in reverse video.  The face
can also leave these unspecified, causing them to assume the value of
the corresponding property of the `default' face.

   Here are the basic primitives for working with faces.

 -- Function: make-face name &optional doc-string temporary
     This function defines and returns a new face named NAME, initially
     with all properties unspecified.  It does nothing if there is
     already a face named NAME.  Optional argument DOC-STRING specifies
     an explanatory string used for descriptive purposes.  If optional
     argument TEMPORARY is non-`nil', the face will automatically
     disappear when there are no more references to it anywhere in text
     or Lisp code (otherwise, the face will continue to exist
     indefinitely even if it is not used).

 -- Function: face-list &optional temporary
     This function returns a list of the names of all defined faces.  If
     TEMPORARY is `nil', only the permanent faces are included.  If it
     is `t', only the temporary faces are included.  If it is any other
     non-`nil' value both permanent and temporary are included.

 -- Function: facep object
     This function returns `t' if OBJECT is a face, else `nil'.

 -- Function: copy-face old-face new-name &optional locale tag-set
          exact-p how-to-add
     This function defines a new face named NEW-NAME which is a copy of
     the existing face named OLD-FACE.  If there is already a face
     named NEW-NAME, then it alters the face to have the same
     properties as OLD-FACE.

     LOCALE, TAG-SET, EXACT-P and HOW-TO-ADD let you copy just parts of
     the old face rather than the whole face, and are as in
     `copy-specifier' (*note Specifiers::).

   Finally, you have the possibility to give faces different names by
means of aliases. One typical use of this feature is to change the name
of a face while preserving backward compatibility. If a symbol has the
`face-alias' property set to another symbol, then this other symbol
will be used as the real face name instead. Recursive aliases (aliases
of aliases) are allowed, but the depth of indirection is limited to 32
to prevent alias loops.


File: lispref.info,  Node: Face Properties,  Next: Face Convenience Functions,  Prev: Basic Face Functions,  Up: Faces

49.1.3 Face Properties
----------------------

You can examine and modify the properties of an existing face with the
following functions.

   The following symbols have predefined meanings:

`foreground'
     The foreground color of the face.

`background'
     The background color of the face.

`font'
     The font used to display text covered by this face.

`display-table'
     The display table of the face.

`background-pixmap'
     The pixmap displayed in the background of the face.  Only used by
     faces on GUI devices, currently X11, GTK, and Microsoft Windows.

`underline'
     Underline all text covered by this face.

`highlight'
     Highlight all text covered by this face.  Only used by faces on TTY
     devices.

`dim'
     Dim all text covered by this face.  Only used by faces on TTY
     devices.

`blinking'
     Blink all text covered by this face.  Only used by faces on TTY
     devices.

`reverse'
     Reverse the foreground and background colors.  Only used by faces
     on TTY devices.

`doc-string'
     Description of what the face's normal use is.  NOTE: This is not a
     specifier, unlike all the other built-in properties, and cannot
     contain locale-specific values.

 -- Function: set-face-property face property value &optional locale
          tag-set how-to-add
     This function changes a property of a FACE.

     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 PROPERTY is a built-in property, the specifications to be added
     to this property can be supplied in many different ways:

        * If VALUE is a simple instantiator (e.g. a string naming a
          font or color) or a list of instantiators, then the
          instantiator(s) will be added as a specification of the
          property for the given LOCALE (which defaults to `global' if
          omitted).

        * If VALUE is a list of specifications (each of which is a cons
          of a locale and a list of instantiators), then LOCALE must be
          `nil' (it does not make sense to explicitly specify a locale
          in this case), and specifications will be added as given.

        * If VALUE is a specifier (as would be returned by
          `face-property' if no 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 `copy-specifier' and 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 `nil' or `all', then all specifications will be copied).

     HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
     `append', `remove-tag-set-prepend', `remove-tag-set-append',
     `remove-locale', `remove-locale-type', or `remove-all'.  See
     `copy-specifier' and `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 `face-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 `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 PROPERTY is not a built-in property, then this function will
     simply set its value if LOCALE is `nil'.  However, if LOCALE is
     given, then this function will attempt to add VALUE as the
     instantiator for the given LOCALE, using `add-spec-to-specifier'.
     If the value of the property is not a specifier, it will
     automatically be converted into a `generic' specifier.

 -- Function: remove-face-property face property &optional locale
          tag-set exact-p
     This function removes a property of a FACE.

     For built-in properties, this is analogous to `remove-specifier'.
     For more information, *Note Other Specification Functions::.

     When PROPERTY is not a built-in property, this function will just
     remove its value if LOCALE is `nil' or `all'.  However, if LOCALE
     is other than that, this function will attempt to remove VALUE as
     the instantiator for the given LOCALE with `remove-specifier'.  If
     the value of the property is not a specifier, it will be converted
     into a `generic' specifier automatically.

 -- Function: face-property face property &optional locale tag-set
          exact-p
     This function returns FACE's value of the given PROPERTY.

     If LOCALE is omitted, the FACE's actual value for 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 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 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 PROPERTY is not a specifier, this value will
     simply be returned regardless of LOCALE.

     The return value will be a list of instantiators (e.g. strings
     specifying a font or color name), or a list of specifications,
     each of which is a cons of a locale and a list of instantiators.
     Specifically, if LOCALE is a particular locale (a buffer, window,
     frame, device, or `global'), a list of instantiators for that
     locale will be returned.  Otherwise, if LOCALE is a locale type
     (one of the symbols `buffer', `window', `frame', or `device'), the
     specifications for all locales of that type will be returned.
     Finally, if LOCALE is `all', the specifications for all locales of
     all types will be returned.

     The specifications in a specifier determine what the value of
     PROPERTY will be in a particular "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 `global')
     that matches the domain in question.  In other words, given a
     domain (i.e. an Emacs window, usually), the specifier for 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
     `face-property-instance' actually does all this, and is used to
     determine how to display the face.

 -- Function: face-property-instance face property &optional domain
          default no-fallback
     This function returns the instance of FACE's PROPERTY in the
     specified DOMAIN.

     Under most circumstances, 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 a color-instance,
     font-instance, or pixmap-instance object, and you can query it
     using the appropriate object-specific functions.  For example, you
     could use `color-instance-rgb-components' to find out the RGB
     (red, green, and blue) components of how the `background' property
     of the `highlight' face is 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 color for
     the frame that window is on; or perhaps the same color was
     specified but the window is on a different X server, and that X
     server has different RGB values for the color from this one).

     DOMAIN defaults to the selected window if omitted.

     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 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 `specifier-instance'.

     Optional arguments DEFAULT and NO-FALLBACK are the same as in
     `specifier-instance'.  *Note Specifiers::.


File: lispref.info,  Node: Face Convenience Functions,  Next: Other Face Display Functions,  Prev: Face Properties,  Up: Faces

49.1.4 Face Convenience Functions
---------------------------------

 -- Command: set-face-foreground face color &optional locale tag-set
          how-to-add
 -- Command: set-face-background face color &optional locale tag-set
          how-to-add
     These functions set the foreground (respectively, background)
     color of face FACE to COLOR.  The argument COLOR should be a
     string (the name of a color) or a color object as returned by
     `make-color' (*note Colors::).

 -- Command: set-face-background-pixmap face pixmap &optional locale
          tag-set how-to-add
     This function sets the background pixmap of face FACE to PIXMAP.
     The argument PIXMAP should be a string (the name of a bitmap or
     pixmap file; the directories listed in the variable
     `x-bitmap-file-path' will be searched) or a glyph object as
     returned by `make-glyph' (*note Glyphs::).  The argument may also
     be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
     are the size in pixels, and DATA is a string, containing the raw
     bits of the bitmap.

     Similarly to how the glyph's image specifier works *Note Creating
     Glyphs::, you don't create your own image specifier, but rather add
     specifications to the existing one.  Note that the image instance
     that is generated in order to actually display the background
     pixmap is of type `mono-pixmap', meaning that it's a two-color
     image and the foreground and background of the image get filled in
     with the corresponding colors from the face.  (#### Is this still
     true?)

 -- Command: set-face-background-pixmap-file face file
     This function sets the background pixmap of face FACE to the image
     contained in FILE. This is just a simplified version of
     `set-face-background-pixmap' which provides filename completion.

 -- Command: set-face-font face font &optional locale tag-set how-to-add
     This function sets the font of face FACE.  The argument FONT
     should be a string or a font object as returned by `make-font'
     (*note Fonts::).

     If you want to set a face's font for a given Mule character set,
     you need to include some tags in TAG-SET that match that character
     set.  See the documentation of `define-specifier-tag' and its
     `charset-predicate' argument.

 -- Command: set-face-underline-p face underline-p &optional locale
          tag-set how-to-add
     This function sets the underline property of face FACE.

 -- Function: face-foreground face &optional locale tag-set exact-p
 -- Function: face-background face &optional locale tag-set exact-p
     These functions return the foreground (respectively, background)
     color specifier of face FACE.  *Note Colors::.

 -- Function: face-background-pixmap face &optional locale tag-set
          exact-p
     This function returns the background-pixmap image specifier of face
     FACE.

 -- Function: face-font face &optional locale tag-set exact-p
     This function returns the font specifier of face FACE.  (Note:
     This is not the same as the function `face-font' in FSF Emacs.)

     *Note Fonts::.

 -- Function: face-font-name face &optional domain
     This function returns the name of the font of face FACE, or `nil'
     if it is unspecified.  This is basically equivalent to `(font-name
     (face-font FACE) DOMAIN)' except that it does not cause an error
     if FACE's font is `nil'. (This function is named `face-font' in
     FSF Emacs.)

 -- Function: face-underline-p face &optional locale
     This function returns the underline property of face FACE.

 -- Function: face-foreground-instance face &optional domain
 -- Function: face-background-instance face &optional domain
     These functions return the foreground (respectively, background)
     color specifier of face FACE.  *Note Colors::.

 -- Function: face-background-pixmap-instance face &optional domain
     This function return the background-pixmap glyph object of face
     FACE.

 -- Function: face-font-instance face &optional domain charset
     This function returns the font specifier of face FACE in domain
     DOMAIN (defaulting to the selected device) with Mule charset
     CHARSET (defaulting to ASCII).  *Note Fonts::.


File: lispref.info,  Node: Other Face Display Functions,  Prev: Face Convenience Functions,  Up: Faces

49.1.5 Other Face Display Functions
-----------------------------------

 -- Command: invert-face face &optional locale
     Swap the foreground and background colors of face FACE.  If the
     face doesn't specify both foreground and background, then its
     foreground and background are set to the default background and
     foreground.

 -- Function: face-equal face1 face2 &optional domain
     This returns `t' if the faces FACE1 and FACE2 will display in the
     same way.  DOMAIN is as in `face-property-instance'.

 -- Function: face-differs-from-default-p face &optional domain
     This returns `t' if the face FACE displays differently from the
     default face.  DOMAIN is as in `face-property-instance'.


File: lispref.info,  Node: Fonts,  Next: Colors,  Prev: Faces,  Up: Faces and Window-System Objects

49.2 Fonts
==========

This section describes how to work with font specifier and font
instance objects, which encapsulate fonts in the window system.

* Menu:

* Font Specifiers::		Specifying how a font will appear.
* Font Instances::		What a font specifier gets instanced as.
* Font Instance Names::		The name of a font instance.
* Font Instance Size::		The size of a font instance.
* Font Instance Characteristics:: Display characteristics of font instances.
* Font Convenience Functions::	Convenience functions that automatically
				  instance and retrieve the properties
				  of a font specifier.


File: lispref.info,  Node: Font Specifiers,  Next: Font Instances,  Prev: Fonts,  Up: Fonts

49.2.1 Font Specifiers
----------------------

 -- Function: font-specifier-p object
     This predicate returns `t' if OBJECT is a font specifier, and
     `nil' otherwise.

 -- Function: make-font-specifier spec-list
     Return a new `font' specifier object with the given specification
     list.  SPEC-LIST can be a list of specifications (each of which is
     a cons of a locale and a list of instantiators), a single
     instantiator, or a list of instantiators.  *Note Specifiers::, for
     more information about specifiers.

     Valid instantiators for font specifiers are:

        * A string naming a font (e.g. under X this might be
          "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a
          14-point upright medium-weight Courier font).

        * A font instance (use that instance directly if the device
          matches, or use the string that generated it).

        * A vector of no elements (only on TTY's; this means to set no
          font at all, thus using the "natural" font of the terminal's
          text).

        * A vector of one element (a face to inherit from).


File: lispref.info,  Node: Font Instances,  Next: Font Instance Names,  Prev: Font Specifiers,  Up: Fonts

49.2.2 Font Instances
---------------------

 -- Function: font-instance-p object
     This predicate returns `t' if OBJECT is a font instance, and `nil'
     otherwise.

 -- Function: make-font-instance name &optional device noerror
     This function creates a new font-instance object of the specified
     name.  DEVICE specifies the device this object applies to and
     defaults to the selected device.  An error is signalled if the
     font is unknown or cannot be allocated; however, if NOERROR is
     non-`nil', `nil' is simply returned in this case.

     The returned object is a normal, first-class lisp object.  The way
     you "deallocate" the font is the way you deallocate any other lisp
     object: you drop all pointers to it and allow it to be garbage
     collected.  When these objects are GCed, the underlying X data is
     deallocated as well.


File: lispref.info,  Node: Font Instance Names,  Next: Font Instance Size,  Prev: Font Instances,  Up: Fonts

49.2.3 Font Instance Names
--------------------------

 -- Function: list-fonts pattern &optional device
     This function returns a list of font names matching the given
     pattern.  DEVICE specifies which device to search for names, and
     defaults to the currently selected device.

 -- Function: font-instance-name font-instance
     This function returns the name used to allocate FONT-INSTANCE.

 -- Function: font-instance-truename font-instance
     This function returns the canonical name of the given font
     instance.  Font names are patterns which may match any number of
     fonts, of which the first found is used.  This returns an
     unambiguous name for that font (but not necessarily its only
     unambiguous name).


File: lispref.info,  Node: Font Instance Size,  Next: Font Instance Characteristics,  Prev: Font Instance Names,  Up: Fonts

49.2.4 Font Instance Size
-------------------------

 -- Function: x-font-size font
     This function returns the nominal size of the given font.  This is
     done by parsing its name, so it's likely to lose.  X fonts can be
     specified (by the user) in either pixels or 10ths of points, and
     this returns the first one it finds, so you have to decide which
     units the returned value is measured in yourself ...

 -- Function: x-find-larger-font font &optional device
     This function loads a new, slightly larger version of the given
     font (or font name).  Returns the font if it succeeds, `nil'
     otherwise.  If scalable fonts are available, this returns a font
     which is 1 point larger.  Otherwise, it returns the next larger
     version of this font that is defined.

 -- Function: x-find-smaller-font font &optional device
     This function loads a new, slightly smaller version of the given
     font (or font name).  Returns the font if it succeeds, `nil'
     otherwise.  If scalable fonts are available, this returns a font
     which is 1 point smaller.  Otherwise, it returns the next smaller
     version of this font that is defined.


File: lispref.info,  Node: Font Instance Characteristics,  Next: Font Convenience Functions,  Prev: Font Instance Size,  Up: Fonts

49.2.5 Font Instance Characteristics
------------------------------------

 -- Function: font-instance-properties font-instance
     This function returns the properties (an alist or `nil') of
     FONT-INSTANCE.

 -- Function: x-make-font-bold font &optional device
     Given an X font specification, this attempts to make a "bold" font.
     If it fails, it returns `nil'.

 -- Function: x-make-font-unbold font &optional device
     Given an X font specification, this attempts to make a non-bold
     font.  If it fails, it returns `nil'.

 -- Function: x-make-font-italic font &optional device
     Given an X font specification, this attempts to make an "italic"
     font.  If it fails, it returns `nil'.

 -- Function: x-make-font-unitalic font &optional device
     Given an X font specification, this attempts to make a non-italic
     font.  If it fails, it returns `nil'.

 -- Function: x-make-font-bold-italic font &optional device
     Given an X font specification, this attempts to make a
     "bold-italic" font.  If it fails, it returns `nil'.


File: lispref.info,  Node: Font Convenience Functions,  Prev: Font Instance Characteristics,  Up: Fonts

49.2.6 Font Convenience Functions
---------------------------------

 -- Function: font-name font &optional domain
     This function returns the name of the FONT in the specified
     DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
     is normally a window and defaults to the selected window if
     omitted.  This is equivalent to using `specifier-instance' and
     applying `font-instance-name' to the result.

 -- Function: font-truename font &optional domain
     This function returns the truename of the FONT in the specified
     DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
     is normally a window and defaults to the selected window if
     omitted.  This is equivalent to using `specifier-instance' and
     applying `font-instance-truename' to the result.

 -- Function: font-properties font &optional domain
     This function returns the properties of the FONT in the specified
     DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
     is normally a window and defaults to the selected window if
     omitted.  This is equivalent to using `specifier-instance' and
     applying `font-instance-properties' to the result.


File: lispref.info,  Node: Colors,  Prev: Fonts,  Up: Faces and Window-System Objects

49.3 Colors
===========

* Menu:

* Color Specifiers::		Specifying how a color will appear.
* Color Instances::		What a color specifier gets instanced as.
* Color Instance Properties::	Properties of color instances.
* Color Convenience Functions::	Convenience functions that automatically
				  instance and retrieve the properties
				  of a color specifier.


File: lispref.info,  Node: Color Specifiers,  Next: Color Instances,  Prev: Colors,  Up: Colors

49.3.1 Color Specifiers
-----------------------

 -- Function: color-specifier-p object
     This function returns non-`nil' if OBJECT is a color specifier.

 -- Function: make-color-specifier spec-list
     Return a new `color' specifier object with the given specification
     list.  SPEC-LIST can be a list of specifications (each of which is
     a cons of a locale and a list of instantiators), a single
     instantiator, or a list of instantiators.  *Note Specifiers::, for
     a detailed description of how specifiers work.

     Valid instantiators for color specifiers are:

        * A string naming a color (e.g. under X this might be
          "lightseagreen2" or "#F534B2").

        * A color instance (use that instance directly if the device
          matches, or use the string that generated it).

        * A vector of no elements (only on TTY's; this means to set no
          color at all, thus using the "natural" color of the
          terminal's text).

        * A vector of one or two elements: a face to inherit from, and
          optionally a symbol naming which property of that face to
          inherit, either `foreground' or `background' (if omitted,
          defaults to the same property that this color specifier is
          used for; if this specifier is not part of a face, the
          instantiator would not be valid).

 -- Function: make-face-boolean-specifier spec-list
     Return a new `face-boolean' specifier object with the given spec
     list.  SPEC-LIST can be a list of specifications (each of which is
     a cons of a locale and a list of instantiators), a single
     instantiator, or a list of instantiators.  *Note Specifiers::, for
     a detailed description of how specifiers work.

     Valid instantiators for face-boolean specifiers are

        * t or nil.

        * A vector of two or three elements: a face to inherit from,
          optionally a symbol naming the property of that face to
          inherit from (if omitted, defaults to the same property that
          this face-boolean specifier is used for; if this specifier is
          not part of a face, the instantiator would not be valid), and
          optionally a value which, if non-`nil', means to invert the
          sense of the inherited property.



File: lispref.info,  Node: Color Instances,  Next: Color Instance Properties,  Prev: Color Specifiers,  Up: Colors

49.3.2 Color Instances
----------------------

A "color-instance object" is an object describing the way a color
specifier is instanced in a particular domain.  Functions such as
`face-background-instance' return a color-instance object.  For example,

     (face-background-instance 'default (next-window))
         => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>

   The color-instance object returned describes the way the background
color of the `default' face is displayed in the next window after the
selected one.

 -- Function: color-instance-p object
     This function returns non-`nil' if OBJECT is a color-instance.


File: lispref.info,  Node: Color Instance Properties,  Next: Color Convenience Functions,  Prev: Color Instances,  Up: Colors

49.3.3 Color Instance Properties
--------------------------------

 -- Function: color-instance-name color-instance
     This function returns the name used to allocate COLOR-INSTANCE.

 -- Function: color-instance-rgb-components color-instance
     This function returns a three element list containing the red,
     green, and blue color components of COLOR-INSTANCE.

          (color-instance-rgb-components
            (face-background-instance 'default (next-window)))
              => (65535 58596 46517)


File: lispref.info,  Node: Color Convenience Functions,  Prev: Color Instance Properties,  Up: Colors

49.3.4 Color Convenience Functions
----------------------------------

 -- Function: color-name color &optional domain
     This function returns the name of the COLOR in the specified
     DOMAIN, if any.  COLOR should be a color specifier object and
     DOMAIN is normally a window and defaults to the selected window if
     omitted.  This is equivalent to using `specifier-instance' and
     applying `color-instance-name' to the result.

 -- Function: color-rgb-components color &optional domain
     This function returns the RGB components of the COLOR in the
     specified DOMAIN, if any.  COLOR should be a color specifier
     object and DOMAIN is normally a window and defaults to the
     selected window if omitted.  This is equivalent to using
     `specifier-instance' and applying `color-instance-rgb-components'
     to the result.

          (color-rgb-components (face-background 'default (next-window)))
              => (65535 58596 46517)


File: lispref.info,  Node: Glyphs,  Next: Annotations,  Prev: Faces and Window-System Objects,  Up: Top

50 Glyphs
*********

A "glyph" is an object that is used for pixmaps, widgets, and images of
all sorts, as well as for things that "act" like pixmaps, such as
non-textual strings ("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
(`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.

 -- Function: glyphp object
     This function returns `t' if OBJECT is a glyph.

* Menu:

* Glyph Intro::		Glyphs are abstract image specifications.
* Images::		Specifying the appearance of glyphs.
* Using Glyphs::	Creating and displaying glyphs.
* Manipulating Glyphs::	Getting and setting glyph properties.
* Glyph Examples::	Examples of how to work with glyphs.


File: lispref.info,  Node: Glyph Intro,  Next: Images,  Prev: Glyphs,  Up: Glyphs

50.1 Glyph Introduction
=======================

In XEmacs, "glyph" does *not* refer to a single unit of textual display
(the XEmacs term for that is "rune", and runes are confined to the
internal implementation of redisplay), but rather is an object
encapsulating a graphical element, such as an image or widget (an
active GUI element such as a button or text entry field; X11 calls this
a "widget", while MS Windows uses the term "control").  This graphical
element could appear in a buffer, a margin, a gutter, or a toolbar, or
even externally to XEmacs as a mouse pointer or an icon, for example.

   On the other hand, by contrast with GNU Emacs 21, an XEmacs glyph is
not "just" an image.  The actual image that is displayed (as opposed to
its position or clipping) is defined by an "image specifier" object
contained within the glyph.  The separation between an image specifier
object and a glyph object is made because the glyph includes other
properties than just the actual image: e.g. the face it is displayed in,
the alignment of the image, _etc_.  Also, an image specifier is used in
at least one place in XEmacs in lieu of a glyphs, namely the backing
pixmap of a face.

   An image specifier is used because glyphs often have locale-specific
semantics.  The most important example is semantics determined by the
display device: you can't usefully display a JPEG on stdout, or a color
image on a monochrome display.  But because the image property is a
specifier in XEmacs, you can specify that a given glyph appear as a
monochrome image on monochrome displays, a color image on color
displays, and as a string on TTYs.  (Specifying a string for the `tty'
device locale would give behavior like the `ALT' attribute of an `IMG'
element in HTML.)  Another is semantics determined by the buffer or
mode.  (Unfortunately, currently there are no compelling examples of
this for glyphs.)

   All this means that only one global glyph needs to exist for a
particular purpose (e.g. the icon used to represent an iconified frame,
the mouse pointer used over particular areas of a frame, etc.).  Often
you need not (and should not!) create your own glyph, but rather modify
an existing one.

   In working with glyphs it is important to keep in mind the
distinction between a locale and a domain.  A "locale" is specified by
the programmer, and is an abstract link between a specification (for a
glyph, its visual appearance) and a displayable object.  The displayable
object may be a buffer or a window, or an object containing buffers or
windows such as frame, device, or console.  A "domain" is an actual
display context, which must be concrete enough to enable XEmacs to
identify the device type.  (Buffers may be displayed in windows on
different devices, even simultaneously, so a buffer cannot be a domain.
Similarly, the global locale cannot be a domain.)  *Note Specifiers::,
for more information about specifier locales and domains.


File: lispref.info,  Node: Images,  Next: Using Glyphs,  Prev: Glyph Intro,  Up: Glyphs

50.2 Images
===========

* Menu:

* Image Instantiators::			Specifying an image's appearance.
* Image Instantiator Conversion::	Lazy realization of graphics.
* Image Instantiator Formats::		A catalog of image descriptors.
* Image Instances::			Classes of graphical objects.


File: lispref.info,  Node: Image Instantiators,  Next: Image Instantiator Conversion,  Prev: Images,  Up: Images

50.2.1 Image Instantiators
--------------------------

An "image instantiator" is a description of the actual graphical
realization of a glyph.  For example, a typical image description is
_the file system path to a PNG file_.  Since redisplay doesn't know
about files, and in any case the image may need to be manipulated
(_e.g._, a face's background pixmap must be clipped and tiled), the PNG
file must be converted internally to a window system bitmap or pixmap
object.  We describe this process by writing that when XEmacs displays
the image, it "instantiates" the image instantiator into an "image
instance".  Image instances are an internal object type (similar to
font instances and color instances), describing how the image appears
in a particular domain.  On the other hand, image instantiators, which
are just descriptions of how the image should appear, are represented
using Lisp strings or vectors.

   Furthermore the graphical realization will vary, and for some devices
may not even be a bitmapped graphic.  These variations may be
controlled by the program by specifying different instantiators in
different locales.  This is implemented with an "image specifier", a
specifier whose specifications are image instantiators.

   Image specifiers are rarely if ever found by themselves.  However, an
image specifier results from calling `glyph-image' on a glyph, or
retrieving the `background-pixmap' property of a face, and you can
check if some random object is an image specifier.

 -- Function: image-specifier-p object
     This function returns non-`nil' if OBJECT is an image specifier.

 -- Function: make-image-specifier spec-list
     This function creates a new image specifier object and initializes
     it according to SPEC-LIST.  *Note Specifiers::.

   This function exists mainly for completeness.  In practice, you
rarely, if ever, need to actually create an image specifier.  Instead,
they are implicitly created by the initialization of glyphs and faces,
and the specifier member of these objects cannot be changed after
initialization; you may only set the specifications it contains.

   Image instantiators come in many formats: `xbm', `xpm', `gif',
`jpeg', etc.  These denote the format of the data describing the image.
The resulting image instances also come in many types--`mono-pixmap',
`color-pixmap', `text', `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, `xpm' can be instantiated as `color-pixmap',
`mono-pixmap', or `pointer'; whereas `cursor-font' can be instantiated
only as `pointer'.  On the other hand, a particular image instance type
can be generated by many different image instantiator formats (e.g.
`color-pixmap' can be generated by `xpm', `gif', `jpeg', etc.).

   *Note Image Instances::, for a more detailed discussion of image
instance types.

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

      `[FORMAT :KEYWORD VALUE ...]'

   i.e. a format symbol followed by zero or more alternating
keyword-value pairs.

   The form of an instantiator can be checked with
`valid-instantiator-p' with a TYPE of `image', *Note Specifier
Validation Functions::.

   For a complete list of the format symbols and their usage, *Note
Image Instantiator Formats::.

   If the instantiator is a string, it will be converted into a vector
by looking it up according to the specs in the
`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 `:file' keyword.  This
implies that the file must exist when the instantiator is added to the
image, but does not need to exist at any other time (e.g. it may safely
be a temporary file).

   The available keywords are given below.  Note that some keywords are
generally available (for example, the `:data' keyword may be used with
any format except `nothing'), while others are only available for one
format (`resource-id' is unique to the `mswindows-resource' format).

`:data'
     Inline image data.  If available for a given format, it may be
     specified directly by the program, or it may be a cache of file
     data previously read.  When present, it is used to instantiate the
     image in preference to the file named by the `:file' property.

     The format of inline data is image-format-specific.  For example,
     in pixmap formats, the value should be a string, which is
     interpreted as an octet-stream representing a bitmap or pixmap.
     But for text formats, it's string containing the text to be
     displayed, and for resource formats, it's a string containing the
     name of the resource.

`:file'
     Data contained in a file.  The value is the name of this file.  If
     both `:data' and `:file' are specified, the image is created from
     what is specified in `:data' and the string in `:file' becomes the
     value of the `image-instance-file-name' function when applied to
     the resulting image-instance.  Note that there is nothing to stop a
     program from changing either the `:file' or the `:data' property,
     and there is no way to detect such mischief.  This means that the
     data will _not_ be automatically reread if you change the `file'
     property; you must force it by removing the `:data' property.
     (One way to do this is replacing the whole specification with a new
     vector.)  This keyword is not valid for instantiator formats
     `nothing', `string', `formatted-string', `cursor-font', `font',
     and `autodetect'.

`:mask-data'
     Inline data for `xbm' and `xface'.  This specifies a mask to be
     used with the bitmap.  Pixels which are not set in the mask will
     not be written to the imaging device.  The format is a list of
     width, height, and bits, as for `:data'.

`:mask-file'
     For `xbm' and `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
     `Mask' or `msk' appended.  For example, if you specify the XBM file
     `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
     associated mask file `left_ptrmsk' will automatically be picked up.

`:resource-id'
     Only for `mswindows-resource'.  This must be either an integer
     (which directly specifies a resource number) or a string.  See the
     description of `mswindows-resource' for valid strings.  *Note
     Image Instantiator Formats::.

`:foreground'
`:background'
     For `xbm', `xface', `cursor-font', and `font'.  These keywords
     allow you to explicitly specify foreground and background colors.
     The value should be anything acceptable to `make-color-instance'.
     This will cause an external format that would by default be
     instantiated as a `mono-pixmap' to instead be instantiated as a
     two-color color-pixmap.  This can be used to override the colors
     specified by a glyph's face, for example.  If the image is
     instantiated as a pointer, they specify its foreground and/or
     background, instead of the defaults of black and white.

`:hotspot-x'
`:hotspot-y'
     For `xbm' and `xface'.  These keywords specify a hotspot if the
     image is instantiated as a `pointer'.  Note that if the XBM image
     file specifies a hotspot, it will automatically be picked up if no
     explicit hotspot is given.

`:color-symbols'
     Only for `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
     `xpm-color-symbols' are used to generate the alist.

`:resource-type'
     Only for `mswindows-resource'.  This must be a symbol, either
     `cursor', `icon', or `bitmap', specifying the type of resource to
     be retrieved.

`:face'
     For `inherit' and the widget formats.  This specifies the face to
     inherit from.  For widgets this specifies the face to use for
     display.  It defaults to gui-element-face.

`:selected'
`:active'
`:suffix'
`:keys'
`:style'
`:filter'
`:config'
`:included'
`:visible'
`:key-sequence'
`:accelerator'
`:label'
`:callback'
     These keywords, accepted as menu item specs, are also accepted by
     images instantiated as `widget'.  For their semantics, *Note Menu
     Format::.


File: lispref.info,  Node: Image Instantiator Conversion,  Next: Image Instantiator Formats,  Prev: Image Instantiators,  Up: Images

50.2.2 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
`make-image-instance'.

 -- Function: set-console-type-image-conversion-list console-type list
     This function sets the image-conversion-list for consoles of the
     given 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.

 -- Function: console-type-image-conversion-list console-type
     This function returns the image-conversion-list for consoles of
     the given CONSOLE-TYPE.


File: lispref.info,  Node: Image Instantiator Formats,  Next: Image Instances,  Prev: Image Instantiator Conversion,  Up: Images

50.2.3 Image Instantiator Formats
---------------------------------

The "format" field of an image instantiator should be a symbol denoting
a valid format.  Which formats are valid will depend on the features
(such as image decoding libraries) available, on platform support (MS
Windows resource IDs make no sense on other platforms), and on the
locale.

 -- Function: valid-image-instantiator-format-p format &optional locale
     This function returns non-`nil' if FORMAT is a valid image
     instantiator format.

     If LOCALE is non-`nil' then the format is checked in that locale.
     If LOCALE is `nil' the current console is used.

     Note that the return value for many formats listed above depends on
     whether XEmacs was compiled with support for that format.

 -- Function: image-instantiator-format-list
     This function returns a list of valid image-instantiator formats.

   Here is a table of image-instantiator formats, giving the keywords
that are usable with each, and the kinds of instances that may result.

`nothing'
     Don't display anything; no keywords are valid for this format.
     Can only be instantiated as `nothing'.

`string'
     Display this image as a text string.  Can only be instantiated as
     `text', although support for instantiation as `mono-pixmap' should
     be added.  The valid keyword is `:data'.  The value should be a
     string, and it is interpreted as a string of characters.

`formatted-string'
     Display this image as a text string with replaceable fields,
     similar to a modeline format string.  The valid keyword is `:data'.
     The value should be a string, and it is interpreted as a string of
     characters containing format sequences.

     Not currently implemented.

`xbm'
     An X bitmap; available only if X support was compiled into this
     XEmacs.

     If used in a buffer glyph, icon glyph, or face background pixmap,
     it will be instantiated as `mono-pixmap' unless the `:foreground'
     or `:background' keywords are present.  In the latter case it will
     be instantiated as `color-pixmap' with the two specified colors.
     (Probably if `:foreground' or `:background' is omitted, it
     defaults to black or white respectively.)  If used in a pointer
     glyph, it will be instantiated as an `pointer'.

     The valid keywords and their values are
    `:data'
          A list containing the height and width of the bitmap as
          integers, and a string interpreted as a bit vector according
          to the X11 standard XBM bitmap format, in that order.

    `:file'
          The name of a file containing standard XBM-format data.  If
          it contains a hotspot specification, it will be parsed and
          used if the hotspot is not explicitly specified.

    `:mask-data'
          A list containing the height and width of the bitmap as
          integers, and a string interpreted as a bit vector according
          to the X11 standard XBM bitmap format, in that order.  This
          bitmap is interpreted as the clipping region for the bitmap
          contained in the `:data' property.

    `:mask-file'
          The name of a file containing standard XBM-format data.
          Interpreted as the clipping region for the bitmap contained
          in the `:data' property.

    `:foreground'
    `:background'
          These keywords allow you to explicitly specify foreground and
          background colors.  The values should be acceptable to
          `make-color-instance'.

    `:hotspot-x'
    `:hotspot-y'
          Integers denoting the hotspot (mouse pointer position), with
          (0,0) at the top left corner.  If given, these override any
          specification in the XBM file.

`xpm'
     An XPM pixmap; only available if XPM support was compiled into
     this XEmacs.

     Can be instantiated as `color-pixmap', `mono-pixmap', or `pointer'.

     XPM is an add-on library for X that was designed to rectify the
     shortcomings of the XBM format.  Many icons and labels used in the
     XEmacs GUI are still distributed in XPM format (although we are
     moving to standardize on the PNG format).  It is therefore highly
     desirable that XPM be available in your XEmacs.

     Most implementations of X include the XPM library as a standard
     part.  If your vendor does not, it is highly recommended that you
     download it and install it.  You can get it from the XEmacs FTP
     site and mirrors, as well as from most sites that distribute X11.

     The valid keywords and their values are
    `:data'
          A string interpreted as the contents of a standard XPM file.

    `:file'
          The name of a file containing standard XPM-format data.  If
          it contains a hotspot specification, it will be parsed and
          used if the hotspot is not explicitly specified.

    `:hotspot-x'
    `:hotspot-y'
          Integers denoting the hotspot (mouse pointer position), with
          (0,0) at the top left corner.  If given, these override any
          specification in the XBM file.  (This may not be true.  The
          original documentation doesn't mention them in connection
          with XPM, but a pointer needs a hotspot.)

    `:color-symbols'
          An alist that maps the one- or two-character strings that
          specify symbolic color names in the XPM file to the actual
          color to be used for that symbolic color (in the form of a
          string acceptable as a color instantiator, *Note Color
          Specifiers::, or a color-specifier object).  If this is not
          specified, the contents of `xpm-color-symbols' are used to
          generate the alist.

`xface'
     An X-Face bitmap, used to encode people's faces in e-mail messages;
     only available if X-Face support was compiled into this XEmacs.

     Will be instantiated as `mono-pixmap', `color-pixmap', or
     `pointer', depending on the target instance type and the presence
     of color keywords.

     The valid keywords and their values are
    `:data'
          A list containing the height and width of the bitmap as
          integers, and a string interpreted as a bit vector according
          to the X11 standard XBM bitmap format, in that order.

    `:file'
          The name of a file containing standard XBM-format data.  If
          it contains a hotspot specification, it will be parsed and
          used if the hotspot is not explicitly specified.

    `:mask-data'
          A list containing the height and width of the bitmap as
          integers, and a string interpreted as a bit vector according
          to the X11 standard XBM bitmap format, in that order.  This
          bitmap is interpreted as the clipping region for the bitmap
          contained in the `:data' property.

    `:mask-file'
          The name of a file containing standard XBM-format data.
          Interpreted as the clipping region for the bitmap contained
          in the `:data' property.

    `:foreground'
    `:background'
          These keywords allow you to explicitly specify foreground and
          background colors.  The values should be acceptable to
          `make-color-instance'.

    `:hotspot-x'
    `:hotspot-y'
          Integers denoting the hotspot (mouse pointer position), with
          (0,0) at the top left corner.  If given, these override any
          specification in the XBM file.

`gif'
`jpeg'
`png'
`tiff'
     These are GIF87- or GIF89-format, JPEG-format, PNG/GIF24-format,
     and TIFF-format images, respectively.  They are available only if
     appropriate decoding support was built into XEmacs.  If you have
     development support (both the libraries and the relevant C header
     files) available when XEmacs is built, the JPEG, PNG, GIF, and
     TIFF libraries will automatically be detected (in the "usual
     places") and linked into the build.

     Note that PNG is the standard format for images distributed with
     XEmacs, so it is highly recommended that PNG support be built in.

     All of these instantiators will be instantiated as `color-pixmap'.

     The valid keywords and their values are
    `:data'
          A string interpreted as the contents of a file containing
          data in the appropriate standard format.

    `:file'
          The name of a file containing standard-format data.

`cursor-font'
     Most window systems provide a set of standard cursors, which in
     X11 is called a cursor font.  Can only be instantiated as
     `pointer'.  This should probably be fixed.

     The valid keyword is `:data'.  Its value should be a string
     containing one of the standard cursor-font names, such as `watch'
     or `right_ptr' under X.  More specifically, in the X Window System
     it may be any of the standard cursor names from appendix B of the
     Xlib manual, provided in the file `<X11/cursorfont.h>' by most
     distributions, minus the `XC_' prefix.  For MS Windows, use
     `mswindows-resource' instantiator format, not `cursor-font'.
     Other window systems may have different lists.

`font'
     A glyph from a font; i.e. the name of a font, and glyph index into
     it of the form `FONT fontname index [[mask-font] mask-index]'.
     Only if X support was compiled into this XEmacs.  Currently can
     only be instantiated as `pointer'.  This should probably be fixed.

`mswindows-resource'
     An MS Windows pointer resource.  Specifies a resource to retrieve
     directly from the system (an OEM resource) or from a file,
     particularly an executable file.  Can be instantiated as `pointer'
     or `color-pixmap'.

     The valid keywords and their values are

    `:resource-type'
          A string naming the type (`cursor', `bitmap', or `icon') of
          the resource.  Required.

    `:file'
          A string containing the name of the file containing the
          resource (often an executable).  If a system resource,
          `:file' should be omitted.

    `:resource-id'
          A string containing the name of a resource.   Required if
          `:file' is not specified.

          This must be either an integer (which directly specifies a
          resource number) or a string.  Valid strings are

          For bitmaps:

          "close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
          "reduce", "zoom", "restore", "reduced", "zoomd", "restored",
          "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow",
          "combo", "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi",
          "size", "btsize", "check", "checkboxes", and "btncorners".

          For cursors:

          "normal", "ibeam", "wait", "cross", "up", "sizenwse",
          "sizenesw", "sizewe", "sizens", "sizeall", and "no".

          For icons:

          "sample", "hand", "ques", "bang", "note", and "winlogo".

`subwindow'
     An embedded windowing system window.  Can only be instantiated as
     `subwindow'.  Not implemented.

`button'
     A button widget; either a push button, radio button or toggle
     button.  Can only be instantiated as `widget'.

`combo-box'
     A drop list of selectable items in a widget, for editing text.
     Can only be instantiated as `widget'.

`edit-field'
     A text editing widget.  Can only be instantiated as `widget'.

`label'
     A static, text-only, widget; for displaying text.  Can only be
     instantiated as `widget'.

`layout'
     A widget for controlling the positioning of children underneath it.
     Through the use of nested layouts, a widget hierarchy can be
     created which can have the appearance of any standard dialog box
     or similar arrangement; all of this is counted as one "glyph" and
     could appear in many of the places that expect a single glyph.
     Can only be instantiated as `widget'.

`native-layout'
     The native version of a layout widget.  Can only be instantiated
     as `widget'.

`progress-gauge'
     A sliding widget, for showing progress.  Can only be instantiated
     as `widget'.

`tab-control'
     A tab widget; a series of user selectable tabs.  Can only be
     instantiated as `widget'.

     The required keyword is `:items'.  Its value should be a list of
     vectors, whose first element is a string, the second element is a
     callback (a Lisp expression to be eval'ed), and the remaining
     elements are key-value pairs.  The most important keyword is
     `:selected' (a Boolean); exactly one of the elements should have a
     value of `t' for the `:selected' property.  Other keywords
     accepted include `:descriptor' (a string), `:face' (a symbol
     naming a face), `:orientation' (a symbol, one of `top', `center',
     `bottom', `left', or `right'), and `:pixel-width' and
     `:pixel-height' (positive integers).

     (The above is incomplete and may be inaccurate.)

`tree-view'
     A folding widget.  Can only be instantiated as `widget'.

`scrollbar'
     A scrollbar widget.  Can only be instantiated as `widget'.

`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 `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.

`inherit'
     Inherit from the background-pixmap property of a face.  Can only be
     instantiated as `mono-pixmap'.

   There are two convenience variables for use with the XBM and XPM
image formats.

 -- Variable: 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
     `(COLOR-NAME FORM-TO-EVALUATE)'.  The COLOR-NAME should be a
     string, which is the name of the color to define; the
     FORM-TO-EVALUATE should evaluate to a color specifier object, or a
     string to be passed to `make-color-instance' (*note Colors::).  If
     a loaded XPM file references a symbolic color called COLOR-NAME,
     it will display as the computed color instead.

     The default value of this variable defines the logical color names
     `"foreground"' and `"background"' to be the colors of the
     `default' face.

 -- Variable: x-bitmap-file-path
     A list of the directories in which X bitmap files may be found.
     If `nil', this is initialized from the `"*bitmapFilePath"'
     resource.  This is used by the `make-image-instance' function
     (however, note that if the environment variable `XBMLANGPATH' is
     set, it is consulted first).


File: lispref.info,  Node: Image Instances,  Prev: Image Instantiator Formats,  Up: Images

50.2.4 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.

 -- Function: image-instance-p object
     This function returns non-`nil' if OBJECT is an image instance.

* Menu:

* Image Instance Types::         Each image instance has a particular type.
* Image Instance Functions::	 Functions for working with image instances.


File: lispref.info,  Node: Image Instance Types,  Next: Image Instance Functions,  Prev: Image Instances,  Up: Image Instances

50.2.4.1 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

`nothing'
     Nothing is displayed.

`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.

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

`color-pixmap'
     Displayed as a color pixmap.

`pointer'
     Used as the mouse pointer for a window.

`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.

`widget'
     An active GUI element implemented as a "widget" or "control" of the
     underlying window system.

   The following functions are used to check whether an image instance
type is valid in the running XEmacs.

 -- Function: valid-image-instance-type-p type
     This function returns non-`nil' if TYPE is a valid image instance
     type.

 -- Function: image-instance-type-list
     This function returns a list of the valid image instance types.

   The following functions are used to determine the type of an image
instance.

 -- Function: image-instance-type image-instance
     Return the type of the given image instance.  The return value
     will be one of `nothing', `text', `mono-pixmap', `color-pixmap',
     `pointer', `subwindow', or `widget'.

 -- Function: text-image-instance-p object
     Return non-`nil' if OBJECT is an image instance of type `text'.

 -- Function: mono-pixmap-image-instance-p object
     Return non-`nil' if OBJECT is an image instance of type
     `mono-pixmap'.

 -- Function: color-pixmap-image-instance-p object
     Return non-`nil' if OBJECT is an image instance of type
     `color-pixmap'.

 -- Function: pointer-image-instance-p object
     Return non-`nil' if OBJECT is an image instance of type `pointer'.

 -- Function: subwindow-image-instance-p object
     Return non-`nil' if OBJECT is an image instance of type
     `subwindow'.

 -- Function: nothing-image-instance-p object
     Return non-`nil' if OBJECT is an image instance of type `nothing'.

 -- Function: widget-image-instance-p object
     Return non-`nil' if OBJECT is an image instance of type `widget'.


File: lispref.info,  Node: Image Instance Functions,  Prev: Image Instance Types,  Up: Image Instances

50.2.4.2 Image Instance Functions
.................................

 -- Function: make-image-instance data &optional domain dest-types
          noerror
     This function creates a new image-instance object.

     DATA is an image instantiator, which describes the image (*note
     Image Instantiators::).

     DEST-TYPES should be a list of allowed image instance types that
     can be generated.  The DEST-TYPES list is unordered.  If multiple
     destination types are possible for a given instantiator, the "most
     natural" type for the instantiator's format is chosen.  These are

    `XBM'
    `xface'
          `mono-pixmap', then `color-pixmap', then `pointer'.

    `XPM'
    `GIF'
    `JPEG'
    `PNG'
    `TIFF'
          `color-pixmap', then `mono-pixmap', then `pointer'.

    `string'
    `formatted-string formats'
          `text', then `mono-pixmap' (not currently implemented), then
          `color-pixmap' (not currently implemented).

    `mswindows-resource'
          For pointer resources, `pointer'.

          For the others, `color-pixmap'.

     The other formats can only be instantiated as one type.

     If you want to control more specifically the order of the types
     into which an image is instantiated, call `make-image-instance'
     repeatedly until it succeeds, passing less and less preferred
     destination types each time.

     If DEST-TYPES is omitted, all possible types are allowed.

     DOMAIN specifies the domain to which the image instance will be
     attached.  This domain is termed the "governing domain".  The type
     of the governing domain depends on the image instantiator format.
     (Although, more correctly, it should probably depend on the image
     instance type.)  For example, pixmap image instances are specific
     to a device, but widget image instances are specific to a
     particular XEmacs window because in order to display such a widget
     when two windows onto the same buffer want to display the widget,
     two separate underlying widgets must be created.  (That's because
     a widget is actually a child window-system window, and all
     window-system windows have a unique existence on the screen.)
     This means that the governing domain for a pixmap image instance
     will be some device (most likely, the only existing device),
     whereas the governing domain for a widget image instance will be
     some XEmacs window.

     If you specify an overly general DOMAIN (e.g. a frame when a
     window was wanted), an error is signaled.  If you specify an overly
     specific DOMAIN (e.g. a window when a device was wanted), the
     corresponding general domain is fetched and used instead.  For
     `make-image-instance', it makes no difference whether you specify
     an overly specific domain or the properly general domain derived
     from it.  However, it does matter when creating an image instance
     by instantiating a specifier or glyph (e.g. with
     `glyph-image-instance'), because the more specific domain causes
     spec lookup to start there and proceed to more general domains.
     (It would also matter when creating an image instance with an
     instantiator format of `inherit', but we currently disallow this.)

     If omitted, DOMAIN defaults to the selected window.

     NOERROR controls what happens when the image cannot be generated.
     If `nil', an error message is generated.  If `t', no messages are
     generated and this function returns `nil'.  If anything else, a
     warning message is generated and this function returns `nil'.

 -- Function: 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 `nil' is
     returned).  Otherwise `t' is returned.

   The following functions are

 -- Function: image-instance-name image-instance
     This function returns the name of the given image instance.  The
     name is typically taken from the `:file' property of the
     instantiator if present, otherwise from the `:data' property.

 -- Function: image-instance-domain image-instance
     Return the governing domain of the given IMAGE-INSTANCE.  The
     governing domain of an image instance is the domain that the image
     instance is specific to.  It is _NOT_ necessarily the domain that
     was given to the call to `specifier-instance' that resulted in the
     creation of this image instance.  See `make-image-instance' for
     more information on governing domains.

 -- Function: image-instance-string image-instance
     This function returns the string of the given image instance.
     This will only be non-`nil' for text image instances.

 -- Function: image-instance-file-name image-instance
     This function returns the file name from which IMAGE-INSTANCE was
     read, if known.

 -- Function: image-instance-mask-file-name image-instance
     This function returns the file name from which IMAGE-INSTANCE's
     mask was read, if known.

   Pixmaps are considered to be three-dimensional.  The height and
width of the pixel array that is displayed, and the color depth of its
pixels, are accessed with these functions.

 -- Function: 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.

 -- Function: image-instance-height image-instance
     This function returns the height of the image instance, in pixels.

 -- Function: image-instance-width image-instance
     This function returns the width of the image instance, in pixels.

   The hotspot is a point relative to the origin of the pixmap.  When
an image is used as a mouse pointer, the hotspot is the point on the
image that sits over the location that the pointer points to.  This is,
for example, the tip of the arrow or the center of the crosshairs.

   These functions access the coordinates of the hotspot.  They simply
return `nil' for a non-pointer image instance.

 -- Function: image-instance-hotspot-x image-instance
     This function returns the X coordinate of the image instance's
     hotspot, if known.

 -- Function: image-instance-hotspot-y image-instance
     This function returns the Y coordinate of the image instance's
     hotspot, if known.

   Mono pixmaps and pointers may have their foreground and background
colors set when instantiated.  Use these functions to access color
information.

 -- Function: image-instance-foreground image-instance
     This function returns the foreground color of IMAGE-INSTANCE, if
     applicable.  This will be a color instance or `nil'.  (It will only
     be non-`nil' for colorized mono pixmaps and for pointers.)

 -- Function: image-instance-background image-instance
     This function returns the background color of IMAGE-INSTANCE, if
     applicable.  This will be a color instance or `nil'.  (It will only
     be non-`nil' for colorized mono pixmaps and for pointers.)


File: lispref.info,  Node: Using Glyphs,  Next: Manipulating Glyphs,  Prev: Images,  Up: Glyphs

50.3 Using Glyphs
=================

Glyph usage is unfortunately somewhat arcane.  (For discussion of
rationale, *Note Glyphs: (Internals)Glyphs.)  Because they are not
"text," they cannot be inserted directly into a buffer.  Instead, they
are values of properties of extents attached to buffers or strings,
values of global variables such as mouse pointers, or as a component of
a complex data structure such as a toolbar initializer.  Although these
uses could probably streamlined, each structure has its own
requirements.  Since glyphs are very flexible, it is possible to create
applications like the `edit-toolbar' and `xpm-mode' libraries which
display glyphs in a buffer (for reference while editing) that are
normally used in a different context.

   Usage of glyphs can roughly be categorized as follows:

*Buffer glyphs*
     Glyphs that are inserted in a buffer may be used for their own
     sake (for example, image display in `w3'), as an accurate
     representation of text that can't be displayed in usual fonts
     (equation display in `preview-latex'), or as annotations (such as
     a marginal indication of a bookmark).  Glyphs are attached to
     buffers via extents.

*Redisplay glyphs*
     Glyphs can be used to create XEmacs-specific "fonts".  For example,
     the character that indicates truncation of lines is implemented as
     the `truncation-glyph'.  It is also possible to have XEmacs
     display a certain character using a custom glyph, via display
     tables.

*Frame glyphs*
     Glyphs are used to control the appearance of various other
     components of the frame.  They can be inserted in the modeline,
     the favicons are used in Web browsers.  They are used to specify
     the labels on toolbar buttons.  Finally, they can be inserted in
     the gutters.  (The difference between a glyph inserted in a gutter
     and a marginal annotation is that the marginal annotation is tied
     to the text in the buffer.  If the buffer line scrolls out of
     view, the marginal annotation will, as well.  A gutter glyph does
     not move with the text.)

     Unfortunately, all these uses are special cases, and have their own
     APIs, in contrast to glyphs in a buffer.

*External glyphs*
     External glyphs simply allow a consistent API for images.  The
     images are then passed to external software such as the window
     system itself (mouse cursor shapes) and the window manager (icons
     to represent minimized windows).  XEmacs has no role in managing
     their use.

*Subwindow and widget glyphs*
     These do not constitute a context of use, but rather an important
     class of glyph types.  The difference between these and other
     glyphs is that while their geometry is determined by XEmacs, their
     behavior is managed separately, by internal mechanisms in the case
     of widgets, and (possibly) by another process in the case of
     subwindows.

   Some simple concrete examples showing how to insert a glyph in a
buffer are presented later.  *Note Glyph Examples::.

   "Creating Glyphs" explains how to create glyphs.  Creating a glyph
using `make-glyph' does not specify _where_ the glyph will be used, it
only specifies _what_ the glyph will look like.  The next four sections
explain how to embed glyphs in different display contexts.  Finally,
the last two sections explain the special considerations of using
glyphs whose behavior is not determined by the code creating them, but
by the glyph itself (a "widget" in X11 or "control" in MS Windows or
Aqua), or even by a separate process.

* Menu:

* Creating Glyphs::	Creating new glyphs.
* Buffer Glyphs::	Annotations are glyphs that appear in a buffer.
* Redisplay Glyphs::	Glyphs controlling various redisplay functions.
* Frame Glyphs::	Displaying glyphs in GUI components of the frame.
* External Glyphs::	Icons and mouse pointers for the window system.
* Native GUI Widgets::	Complex active elements treated as a single glyph.
* Subwindows::		Externally-controlled subwindows in buffers.


File: lispref.info,  Node: Creating Glyphs,  Next: Buffer Glyphs,  Prev: Using Glyphs,  Up: Using Glyphs

50.3.1 Creating Glyphs
----------------------

 -- Function: make-glyph &optional spec-list type
     This function creates a new glyph object of type TYPE.

     The optional SPEC-LIST is used to initialize the glyph's image.
     It can be any spec-list of "image instantiator" accepted by
     `canonicalize-spec-list', *Note Adding Specifications::.  An
     individual image instantiator may be a string, which is converted
     to a vector according to `console-type-image-conversion-list', or a
     vector.  The vector's first element specifies the _external_ format
     of the data, such as a string, a PNG file, or an MS Windows
     resource.  This is followed by properties (keyword-value pairs)
     specifying such information as the name of a file containing an
     image, or pixmap data directly.  *Note Image Instantiators::.

     The optional TYPE specifies the type of the glyph.  TYPE should be
     one of `buffer' (used for glyphs in an extent, the modeline, the
     toolbar, or elsewhere in a frame), `pointer' (used for the
     mouse-pointer), or `icon' (used for a frame's icon), and defaults
     to `buffer'.

   SPEC-LIST is the initializer for the glyph's `image' property, which
is an image specifier.  (Note that "image" as used in the context of a
glyph's `image' property or in the terms "image specifier", "image
instantiator", or "image instance" does not refer to what people
normally think of as an image (which in XEmacs is called a "pixmap"),
but to any graphical element--a pixmap, a widget, or even a block of
text, when used in the places that call for a glyph.)

   The most common form of SPEC-LIST is a single image instantiator.
(*Compatibility note:* in GNU Emacs 21, a string used to instantiate an
image is interpreted as the name of an image file, which is searched
for and instantiated.)  The conversion controlled by
`console-type-image-conversion-list' typically attempts to look up the
string as a file name in XEmacs's data directory path, and if this
fails, defaults to displaying the string as a text image instance
(_i.e._. the string itself.

   Fine control of a particular specification is provided by using a
vector as the image instantiator.  More complicated instantiators allow
lists of instantiators to be specified (which are tried in order), or
mappings from locales to lists of instantiators, _etc_.  *Note
Specifiers::, for more information about specification formats.

   As well as using SPEC-LIST to initialize the glyph, you can set
specifications using `set-glyph-image'.  The glyph itself is not
actually a specifier, but rather is an object containing an image
specifier (as well as other properties seldom set by user code).
Therefore, you cannot set or access specifications for the glyph's image
by directly using `set-specifier', `specifier-instance' or the like on
the glyph; instead use them on `(glyph-image GLYPH)' or use the
convenience functions `set-glyph-image', `glyph-image-instance', and
`glyph-image'.

   Glyph types reflect the fact that glyphs are used in contexts like
pointers and window manager icons, which are defined by external
programs such as the window system or window manager.  These require
somewhat different _internal_ format, which is opaque to the user.

   It is extremely rare that you will ever have to specify a value for
TYPE, which should be one of `buffer' (used for glyphs in an extent,
the modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
for the mouse-pointer), or `icon' (used for a frame's icon), and
defaults to `buffer'.  The only cases where it needs to be specified is
when creating icon or pointer glyphs, and in both cases the necessary
glyphs have already been created at startup and are accessed through
the appropriate variables, e.g. `text-pointer-glyph' (or in general, any
`*-pointer-glyph') and `frame-icon-glyph'.  User code should never need
to create `pointer' or `icon' glyphs.  *Note Glyph Types::.

   There are a few other glyph creation functions, normally used only
internally or at XEmacs initialization.

 -- Function: make-glyph-internal &optional type
     This function creates a new, uninitialized glyph of type TYPE.

 -- Function: make-pointer-glyph &optional spec-list
     Return a new `pointer-glyph' object with the specification list
     SPEC-LIST.  This function is equivalent to calling `make-glyph'
     with a TYPE of `pointer'.

   `make-pointer-glyph' is normally used only by XEmacs initialization
code.  It is extremely unlikely that you will ever need to create a
pointer glyph.  Instead, you probably want to be calling
`set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.

 -- Function: make-icon-glyph &optional spec-list
     Return a new `icon-glyph' object with the specification list
     SPEC-LIST.  This function is equivalent to calling `make-glyph'
     with a TYPE of `icon'.

   `make-icon-glyph' is normally used only by XEmacs initialization
code.  It is extremely unlikely that you will ever need to create a icon
glyph.  Instead, you probably want to be calling `set-glyph-image' on
the existing glyph, `frame-icon-glyph'.


File: lispref.info,  Node: Buffer Glyphs,  Next: Redisplay Glyphs,  Prev: Creating Glyphs,  Up: Using Glyphs

50.3.2 Buffer Glyphs
--------------------

Creating a glyph using `make-glyph' does not specify _where_ the glyph
will be used, it only specifies _what_ the glyph will look like.  Once
you have created a glyph, you specify where it will be used by
attaching it to an extent as a _begin-glyph_ or _end-glyph_.

`buffer text'
     To insert a glyph into a buffer, create an extent in the buffer
     and then use `set-extent-begin-glyph' or `set-extent-end-glyph' to
     set a glyph to be displayed at the corresponding edge of the
     extent.  (It is common to create zero-width extents for this
     purpose.)

`margins'
     To insert a glyph into the left or right margin of a buffer, first
     make sure the margin is visible by setting a value for the
     specifiers `left-margin-width' or `right-margin-width'.  (Not
     strictly necessary when using margin glyphs with layout policy
     `whitespace'.)  Follow the same procedure above for inserting a
     glyph in a buffer, then set a non-default layout policy for the
     glyph using `set-extent-begin-glyph-layout' or
     `set-extent-end-glyph-layout'.  Alternatively, use the high-level
     annotations API (see `make-annotation').  (In fact, you can also
     use the annotations API for glyphs in a buffer, by setting a
     layout policy of `text'.)



File: lispref.info,  Node: Redisplay Glyphs,  Next: Frame Glyphs,  Prev: Buffer Glyphs,  Up: Using Glyphs

50.3.3 Redisplay Glyphs
-----------------------

To use a glyph to control the shape of miscellaneous redisplay effects
such as the truncation and continuation markers, set the appropriate
existing glyph variables with `set-glyph-image'.  See
`continuation-glyph', `control-arrow-glyph', `hscroll-glyph',
`invisible-text-glyph', `octal-escape-glyph', and `truncation-glyph'.
See also `overlay-arrow-string', an odd redisplay leftover which can be
set to a glyph you created, and will cause the glyph to be displayed on
top of the text position specified in the marker stored in
`overlay-arrow-position'.

   To use a glyph in a display table (i.e. to control the appearance of
any individual character), create the appropriate character glyphs and
then set a specification for the specifier `current-display-table',
which controls the appearance of characters.  You can also set an
overriding display table for use with text displayed in a particular
face; see `set-face-display-table' and `make-display-table'.  ####
Note: Display tables do not currently support general Mule characters.
They will be overhauled at some point to support this and to provide
other features required under Mule.  *Note Display Tables::.

   Glyphs are not actually used as the background pixmaps of faces, but
the API is similar.  The background pixmap of a face is actually an
image specifier - probably the only place in XEmacs where an image
specifier occurs outside of a glyph.  If you would like to use a
glyph's image as a background pixmap, you can extract it with
`glyph-image', and then add it to a face.  *Note Face Convenience
Functions::.

 -- Glyph: truncation-glyph
     This variable specifies what is displayed at the end of truncated
     lines.

 -- Glyph: continuation-glyph
     This variable specifies what is displayed at the end of wrapped
     lines.

 -- Glyph: octal-escape-glyph
     This variable specifies what to prefix character codes displayed
     in octal with.

 -- Glyph: hscroll-glyph
     This variable specifies what to display at the beginning of
     horizontally scrolled lines.

 -- 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 `selective-display-ellipses'
     or `buffer-invisibility-spec').  Normally this is three dots
     ("...").

 -- Glyph: control-arrow-glyph
     This variable specifies what to use as an arrow for control
     characters.


File: lispref.info,  Node: Frame Glyphs,  Next: External Glyphs,  Prev: Redisplay Glyphs,  Up: Using Glyphs

50.3.4 Frame Glyphs
-------------------

There are also a number of special objects whose appearance is specified
by a glyph.  Most of these a global objects that you update with
`set-glyph-image', such as mouse pointers.  Frame icons, toolbar button
icons, and the modeline are the main non-text objects which accept
glyphs as elements.

`modeline'
     A glyph may be displayed in the modeline by inserting the glyph as
     one of the elements of the modeline format.  (Unfortunately you
     can't currently put a begin glyph or end glyph on one of the
     modeline extents--they're ignored.)

`toolbar'
     To insert a glyph into a toolbar, specify it as the icon part of a
     toolbar button, which in turn must be part of a toolbar
     instantiator (typically set on the specifier `default-toolbar').
     See `default-toolbar' for more information. (As a convenience, you
     may use a symbol in place of the glyph list in the toolbar button
     instantiator; the symbol is evalled to get the glyph list.  This
     facilitates both creating the toolbar instantiator and modifying
     individual glyphs in a toolbar later on.  For example, you can
     change the way that the Mail toolbar button looks by modifying the
     value of the variable `toolbar-mail-icon' (in general,
     `toolbar-*-icon') and then calling `(set-specifier-dirty-flag
     default-toolbar)'.  (#### Unfortunately this doesn't quite work
     the way it should; the change will appear in new frames, but not
     existing ones, because once an image has been displayed the pixmap
     replaces the symbol for those domains.)

`gutter'
     To insert a glyph into a gutter, use `set-extent-begin-glyph' or
     `set-extent-end-glyph' to set a glyph to be displayed at the
     corresponding edge of extent in a string, similar to the way you
     insert glyphs in a buffer.  Then insert the string into the gutter
     *Note Specifying a Gutter::.  Glyphs that are frequently used in
     this way are `tab control' and `progress bar' glyphs.



File: lispref.info,  Node: External Glyphs,  Next: Native GUI Widgets,  Prev: Frame Glyphs,  Up: Using Glyphs

50.3.5 External Glyphs
----------------------

There are two special kinds of glyph that are not displayed by XEmacs.
Instead, they are used to set the appearance of iconified frames and the
mouse pointer.  Because these uses are constrained by the window system,
icons and pointers have their own special types *Note Glyph Types::.

   You may use a glyph as the icon for a frame.  Do not create a new
glyph; instead, change the specifications for the existing glyph
`frame-icon-glyph' with `set-glyph-image'.  This is a unique,
predefined object.  Although the natural usage is to set specifications
for the global locale or a frame locale, you can also arrange for a
special icon when a frame's selected window displays a particular buffer
by using a buffer locale.

   The shape of the mouse pointer when over a particular section of a
frame is controlled using various glyph variables.  Since the image of
a glyph is a specifier, it can be controlled on a per-buffer,
per-frame, per-window, or per-device basis.

   To use a glyph as the mouse pointer, in general you do not create a
new glyph, but rather you change the specifications of various existing
glyphs, such as `text-pointer-glyph' for the pointer used over text,
`modeline-pointer-glyph' for the pointer used over the modeline, etc.
Do an apropos over `pointer-glyph' to find all of them.  (Note also
that you can temporarily set the mouse pointer to some specific shape
by using `set-frame-pointer', which takes an image instance, as
obtained from calling `glyph-image-instance' on a glyph of type
`pointer' - either one of the above-mentioned variables or one you
created yourself.  (See below for what it means to create a glyph of
type `pointer'.)  This pointer will last only until the next mouse
motion event is processed or certain other things happen, such as
creating or deleting a window. (In fact, the above-mentioned pointer
glyph variables are implemented as part of the default handler for
mouse motion events.  If you want to customize this behavior, take a
look at `mode-motion-hook', or `mouse-motion-handler' if you really
want to get low-level.)

   You should use `set-glyph-image' to set the following variables,
_not_ `setq'.

 -- Glyph: text-pointer-glyph
     This variable specifies the shape of the mouse pointer when over
     text.

 -- 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,
     `text-pointer-glyph' is used.

 -- Glyph: modeline-pointer-glyph
     This variable specifies the shape of the mouse pointer when over
     the modeline.  If unspecified in a particular domain,
     `nontext-pointer-glyph' is used.

 -- 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,
     `text-pointer-glyph' is used.

 -- 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 `gc-message'.

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

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

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

 -- Glyph: toolbar-pointer-glyph
     This variable specifies the shape of the mouse pointer when over a
     toolbar.  If unspecified in a particular domain,
     `nontext-pointer-glyph' is used.

   Internally, these variables are implemented in
`default-mouse-motion-handler', and thus only take effect when the
mouse moves.  That function calls `set-frame-pointer', which sets the
current mouse pointer for a frame.

 -- Function: set-frame-pointer frame image-instance
     This function sets the mouse pointer of 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.)


File: lispref.info,  Node: Native GUI Widgets,  Next: Subwindows,  Prev: External Glyphs,  Up: Using Glyphs

50.3.6 Native GUI Widgets
-------------------------

A "native widget" is a primitive GUI object defined either by the host
GUI platform or an external toolkit, and accessed from Lisp as a
"glyph."

* Menu:

* Introduction to Widgets::     Native widgets provide tight integration of
                                GUI features with the platform GUI.
* Lisp API to Native Widgets::  Native widgets are glyphs.
* Layouts::                     Specifying composite widgets from Lisp.
* Primitive Widgets::           Catalogue of available native widgets.


File: lispref.info,  Node: Introduction to Widgets,  Next: Lisp API to Native Widgets,  Prev: Native GUI Widgets,  Up: Native GUI Widgets

50.3.6.1 Introduction to Native Widgets and Subwindow Glyphs
............................................................

Traditionally Emacsen have hidden the GUI apparatus from the Lisp
programmer, but in XEmacs 21.4 the ability to embed autonomous GUI
objects, called "native widgets", in text was added to Lisp.  They are
handled as _glyphs_.  Unlike traditional XEmacs glyphs such images and
strings, native widgets are opaque to XEmacs, and must be able to
redraw themselves because they are implemented as subwindows, not as
graphics drawn by XEmacs into the text window.

   Primitive widgets are coded in C using the underlying GUI toolkit,
and thus are beyond the scope of the _XEmacs Lisp Reference Manual_.
However, composite widgets can be created in Lisp using "layouts,"
which are horizontal or vertical arrays of subwidgets.  For example, the
search dialog is formatted using layouts.


File: lispref.info,  Node: Lisp API to Native Widgets,  Next: Layouts,  Prev: Introduction to Widgets,  Up: Native GUI Widgets

50.3.6.2 Lisp API to Native Widgets
...................................

Native widgets are manipulated as _glyphs_ (*note Glyphs::).  Thus they
are created using `make-glyph', with a format of one of the widget
types and a `:data' property specific to the widget being instantiated.

   However, there is a technical difference between widgets and other
kinds of glyphs that is theoretically important.  Because widgets are
active (that is, they can respond to user input events themselves), it
is possible for the user to become aware that two appearances of the
"same" glyph are actually separate instances.  For example, if a user
changes an image glyph from red to blue, and the buffer containing the
glyph appears in more than one window, the user will perceive all the
appearances to change from red to blue simultaneously.  However, suppose
the glyph is a button glyph (_e.g._, as used in the Customize buffer
for the Set, Save, and Done buttons).  Then if the Customize buffer
appears in several windows at the same time, and the user clicks on the
button, she will only perceive the button to be depressed in the window
where she clicked the button.

   It seems from this example that it is unlikely to be a problem in
practice.  When the user is faced with an active widget, it seems likely
that attention will focus on the widget being manipulated, and having
other instances of the widget respond simultaneously might be more
disconcerting than the actual case.


File: lispref.info,  Node: Layouts,  Next: Primitive Widgets,  Prev: Lisp API to Native Widgets,  Up: Native GUI Widgets

50.3.6.3 Layouts
................

An XEmacs "layout" is a one-dimensional array of glyphs.  It is a
widget for controlling the positioning of children underneath it.
Through the use of nested layouts, a widget hierarchy can be created
which can have the appearance of any standard dialog box or similar
arrangement; all of this is counted as one "glyph" and could appear in
many of the places that expect a single glyph.

   (There are also "native layouts", but I don't know what these are or
how they are used.)

   A layout descriptor is an image instantiator, _i.e._, a vector of
the form `[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]' with format
`layout', and properties

`:orientation'
     Specifies the orientation of the contained array of glyphs.  The
     value must be one of the symbols `horizontal' or `vertical'.

`:horizontally-justify'
     Specifies the horizontal justification of the items in the array.
     The value must be one of the symbols `:right', `:center', or
     `:left'.

`:vertically-justify'
     Specifies the vertical justification of the items in the array.
     The value must be one of the symbols `:top', `:center', or
     `:bottom'.

`:justify'
     Specifies justification.  #### not understood.

`:border'
     A glyph to place in the border.  The value must be an image
     instantiator.

`:items'
     The glyphs controlled by the layout.  The value must be a list of
     image instantiators.

   Here is the specification of the search dialog widget created by
`make-search-dialog' in the `dialog-items' library, which makes use of
recursive layouts.

     (make-glyph
      `[layout
        :orientation horizontal
        :vertically-justify top
        :horizontally-justify center
        :border [string :data "Search"]
        :items
        ([layout :orientation vertical
                 :justify top	; implies left also
                 :items
                 ([string :data "Search for:"]
          	[button :descriptor "Match Case"
          		:style toggle
          		:selected (not case-fold-search)
          		:callback (setq case-fold-search
          				(not case-fold-search))]
          	[button :descriptor "Regular Expression"
          		:style toggle
          		:selected search-dialog-regexp
          		:callback (setq search-dialog-regexp
          				(not search-dialog-regexp))]
          	[button :descriptor "Forwards"
          		:style radio
          		:selected search-dialog-direction
          		:callback (setq search-dialog-direction t)]
          	[button :descriptor "Backwards"
          		:style radio
          		:selected (not search-dialog-direction)
          		:callback (setq search-dialog-direction nil)]
          	)]
         [layout :orientation vertical
                 :vertically-justify top
                 :horizontally-justify right
                 :items
                 ([edit-field :width 15 :descriptor "" :active t
          		    :initial-focus t]
          	[button :width 10 :descriptor "Find Next"
          		:callback-ex
          		(lambda (image-instance event)
          		  (search-dialog-callback ,parent
          					  image-instance
          					  event))]
          	[button :width 10 :descriptor "Cancel"
          		:callback-ex
          		(lambda (image-instance event)
          		  (isearch-dehighlight)
          		  (delete-frame
          		   (event-channel event)))])])])


File: lispref.info,  Node: Primitive Widgets,  Prev: Layouts,  Up: Native GUI Widgets

50.3.6.4 Primitive Widgets
..........................

`button'
     A button widget; either a push button, radio button or toggle
     button.

`combo-box'
     A drop list of selectable items in a widget, for editing text.

`edit-field'
     A text editing widget.

`label'
     A static, text-only, widget; for displaying text.

`progress-gauge'
     A sliding widget, for showing progress.

`tab-control'
     A tab widget; a series of user selectable tabs.

`tree-view'
     A folding widget.

`scrollbar'
     A scrollbar widget.  (#### Probably not the same as the scrollbar
     controlling an Emacs window.)


File: lispref.info,  Node: Subwindows,  Prev: Native GUI Widgets,  Up: Using Glyphs

50.3.7 Subwindows
-----------------

Subwindows are not currently implemented.

 -- Function: subwindowp object
     This function returns non-`nil' if OBJECT is a subwindow.


File: lispref.info,  Node: Manipulating Glyphs,  Next: Glyph Examples,  Prev: Using Glyphs,  Up: Glyphs

50.4 Manipulating Glyphs
========================

Each glyphs has properties that may be accessed.  Most of these can
also be set after the glyph is initialized, with the exception of the
glyph's type.  This is not a real restriction, as it is almost never
useful to create glyphs of types other than `buffer'.

* Menu:

* Glyph Properties::	Accessing and modifying a glyph's properties.
* Glyph Convenience Functions::  Accessing particular properties of a glyph.
* Glyph Dimensions::	Determining the height, width, etc. of a glyph.
* Glyph Types::		Each glyph has a particular type.


File: lispref.info,  Node: Glyph Properties,  Next: Glyph Convenience Functions,  Prev: Manipulating Glyphs,  Up: Manipulating Glyphs

50.4.1 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:

`image'
     The image used to display the glyph.

`baseline'
     Percent above baseline that glyph is to be displayed.  Only for
     glyphs displayed inside of a buffer.

`contrib-p'
     Whether the glyph contributes to the height of the line it's on.
     Only for glyphs displayed inside of a buffer.

`face'
     Face of this glyph (_not_ a specifier).

 -- Function: set-glyph-property glyph property value &optional locale
          tag-set how-to-add
     This function changes a property of a 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.  The glyph face is an exception; it is a face
     name (a symbol) or a face object, not a specifier.  (The face
     properties themselves are typically specifiers.)  For user-defined
     properties, you can use this function to either change the actual
     value of the property or, if this value is a specifier, change the
     specifications within it.

     If PROPERTY is a built-in property, the specifications to be added
     to this property can be supplied in many different ways:

        * If 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 LOCALE (which defaults to `global' if
          omitted).

        * If VALUE is a list of specifications (each of which is a cons
          of a locale and a list of instantiators), then LOCALE must be
          `nil' (it does not make sense to explicitly specify a locale
          in this case), and specifications will be added as given.

        * If VALUE is a specifier (as would be returned by
          `glyph-property' if no 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 `copy-specifier' and 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 `nil' or `all', then all specifications will be copied).

     HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
     `append', `remove-tag-set-prepend', `remove-tag-set-append',
     `remove-locale', `remove-locale-type', or `remove-all'.  See
     `copy-specifier' and `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 `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 `font' property, then
     the font name used to create that object will be used instead).
     In 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 PROPERTY is not a built-in property, then this function will
     simply set its value if LOCALE is `nil'.  However, if LOCALE is
     given, then this function will attempt to add VALUE as the
     instantiator for the given LOCALE, using `add-spec-to-specifier'.
     If the value of the property is not a specifier, it will
     automatically be converted into a `generic' specifier.

 -- Function: glyph-property glyph property &optional locale
     This function returns GLYPH's value of the given PROPERTY.

     If LOCALE is omitted, the GLYPH's actual value for 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 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 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 PROPERTY is not a specifier, this value will
     simply be returned regardless of 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 LOCALE is a particular locale (a buffer, window,
     frame, device, or `global'), a list of instantiators for that
     locale will be returned.  Otherwise, if LOCALE is a locale type
     (one of the symbols `buffer', `window', `frame', or `device'), the
     specifications for all locales of that type will be returned.
     Finally, if LOCALE is `all', the specifications for all locales of
     all types will be returned.

     The specifications in a specifier determine what the value of
     PROPERTY will be in a particular "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 `global')
     that matches the domain in question.  In other words, given a
     domain (i.e. an Emacs window, usually), the specifier for 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
     `glyph-property-instance' actually does all this, and is used to
     determine how to display the glyph.

 -- Function: glyph-property-instance glyph property &optional domain
          default no-fallback
     This function returns the instance of GLYPH's PROPERTY in the
     specified DOMAIN.

     Under most circumstances, 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 `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).

     DOMAIN defaults to the selected window if omitted.

     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 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 instantiated using `specifier-instance'.

     Optional arguments DEFAULT and NO-FALLBACK are the same as in
     `specifier-instance'.  *Note Specifiers::.

 -- Function: 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 `remove-specifier'.  *Note
     remove-specifier-p: Specifiers, for the meaning of the LOCALE,
     TAG-SET, and EXACT-P arguments.


File: lispref.info,  Node: Glyph Convenience Functions,  Next: Glyph Dimensions,  Prev: Glyph Properties,  Up: Manipulating Glyphs

50.4.2 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 PROPERTY.

   Remember that if you want to determine the "value" of a specific
glyph property, you probably want to use the `*-instance' functions.
For example, to determine whether a glyph contributes to its line
height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
latter will return a boolean specifier or a list of specifications, and
you probably aren't concerned with these.)

 -- Function: glyph-image glyph &optional locale
     This function is equivalent to calling `glyph-property' with a
     property of `image'.  The return value will be an image specifier
     if LOCALE is `nil' or omitted; otherwise, it will be a
     specification or list of specifications.

 -- Function: set-glyph-image glyph spec &optional locale tag-set
          how-to-add
     This function is equivalent to calling `set-glyph-property' with a
     property of `image'.

 -- Function: glyph-image-instance glyph &optional domain default
          no-fallback
     This function returns the instance of GLYPH's image in the given
     DOMAIN, and is equivalent to calling `glyph-property-instance'
     with a property of `image'.  The return value will be an image
     instance.

     Normally DOMAIN will be a window or `nil' (meaning the selected
     window), and an instance object describing how the image appears
     in that particular window and buffer will be returned.

 -- Function: glyph-contrib-p glyph &optional locale
     This function is equivalent to calling `glyph-property' with a
     property of `contrib-p'.  The return value will be a boolean
     specifier if LOCALE is `nil' or omitted; otherwise, it will be a
     specification or list of specifications.

 -- Function: set-glyph-contrib-p glyph spec &optional locale tag-set
          how-to-add
     This function is equivalent to calling `set-glyph-property' with a
     property of `contrib-p'.

 -- Function: glyph-contrib-p-instance glyph &optional domain default
          no-fallback
     This function returns whether the glyph contributes to its line
     height in the given DOMAIN, and is equivalent to calling
     `glyph-property-instance' with a property of `contrib-p'.  The
     return value will be either `nil' or `t'. (Normally DOMAIN will be
     a window or `nil', meaning the selected window.)

 -- Function: glyph-baseline glyph &optional locale
     This function is equivalent to calling `glyph-property' with a
     property of `baseline'.  The return value will be a specifier if
     LOCALE is `nil' or omitted; otherwise, it will be a specification
     or list of specifications.

 -- Function: set-glyph-baseline glyph spec &optional locale tag-set
          how-to-add
     This function is equivalent to calling `set-glyph-property' with a
     property of `baseline'.

 -- Function: glyph-baseline-instance glyph &optional domain default
          no-fallback
     This function returns the instance of GLYPH's baseline value in
     the given DOMAIN, and is equivalent to calling
     `glyph-property-instance' with a property of `baseline'.  The
     return value will be an integer or `nil'.

     Normally DOMAIN will be a window or `nil' (meaning the selected
     window), and an instance object describing the baseline value
     appears in that particular window and buffer will be returned.

 -- Function: glyph-face glyph
     This function returns the face of GLYPH. (Remember, this is not a
     specifier, but a simple property.)

 -- Function: set-glyph-face glyph face
     This function changes the face of GLYPH to FACE.


File: lispref.info,  Node: Glyph Dimensions,  Next: Glyph Types,  Prev: Glyph Convenience Functions,  Up: Manipulating Glyphs

50.4.3 Glyph Dimensions
-----------------------

 -- Function: glyph-width glyph &optional window
     This function returns the width of GLYPH on WINDOW.  This may not
     be exact as it does not take into account all of the context that
     redisplay will.

 -- Function: glyph-ascent glyph &optional window
     This function returns the ascent value of GLYPH on WINDOW.  This
     may not be exact as it does not take into account all of the
     context that redisplay will.

 -- Function: glyph-descent glyph &optional window
     This function returns the descent value of GLYPH on WINDOW.  This
     may not be exact as it does not take into account all of the
     context that redisplay will.

 -- Function: glyph-height glyph &optional window
     This function returns the height of GLYPH on 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.


File: lispref.info,  Node: Glyph Types,  Prev: Glyph Dimensions,  Up: Manipulating Glyphs

50.4.4 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
`glyph-image-instance' to retrieve the image instance of a glyph,
XEmacs does the equivalent of calling `make-image-instance' and passing
in DEST-TYPES the list of allowable image instance types for the
glyph's type.

   * `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 `nothing', `mono-pixmap', `color-pixmap', `text',
     and `subwindow'.

   * `pointer' glyphs can be used to specify the mouse pointer.  Their
     image can be instantiated as `pointer'.

   * `icon' glyphs can be used to specify the icon used when a frame is
     iconified.  Their image can be instantiated as `mono-pixmap' and
     `color-pixmap'.

 -- Function: glyph-type glyph
     This function returns the type of the given glyph.  The return
     value will be a symbol, one of `buffer', `pointer', or `icon'.

 -- Function: valid-glyph-type-p glyph-type
     Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.

 -- Function: glyph-type-list
     This function returns a list of valid glyph types.

 -- Function: buffer-glyph-p object
     This function returns non-`nil' if OBJECT is a glyph of type
     `buffer'.

 -- Function: icon-glyph-p object
     This function returns non-`nil' if OBJECT is a glyph of type
     `icon'.

 -- Function: pointer-glyph-p object
     This function returns non-`nil' if OBJECT is a glyph of type
     `pointer'.


File: lispref.info,  Node: Glyph Examples,  Prev: Manipulating Glyphs,  Up: Glyphs

50.5 Glyph Examples
===================

For many applications, displaying graphics is a simple process: you
create a glyph, and then you insert it into a buffer.

   The easiest way to create a glyph is to use a file that contains a
graphical image, such as a JPEG, TIFF, or PNG file:

     ;; Create a glyph from a JPEG file:
     (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))

     ;; Create a glyph from a XPM file:
     (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))

     ;; Create a glyph from a PNG file:
     (setq foo (make-glyph [png :file "/tmp/file3.png"]))

     ;; Create a glyph from a TIFF file:
     (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))

   The parameters passed to `make-glyph' are called "Image Specifiers",
and can handle more image types than those shown above.  You can also
put the raw image data into a string (e.g., if you put the contents of
a JPEG file into a string), and use that to create a glyph.  *Note
Image Instantiators::, for more information.

     *Caution*: In order for XEmacs to read a particular graphics file
     format, support for that format must have been compiled into
     XEmacs.  It's possible, although somewhat unlikely, for XEmacs to
     have been compiled without support for any of the various graphics
     file formats.  To see what graphics formats your particular
     version of XEmacs supports, use `M-x describe-installation'.

     To programmatically query whether or not a particular file format
     is supported, you can use the `featurep' function, with one of:
     `gif', `tiff', `jpeg', `xpm', `xbm', `png', or `xface'.  For an
     up-to-date list, *Note Image Instantiators::.  Example:

          ;; Returns `t' if TIFF is supported:
          (featurep 'tiff)

     Another example is:

          ;; Returns a list of `t' or `nil', depending on whether or not the
          ;; corresponding feature is supported:
          (mapcar #'(lambda (format-symbol) (featurep format-symbol))
                  '(gif tiff jpeg xpm png))


   Once you have a glyph, you can then insert it into a buffer.
Example:

     ;; Use this function to insert a glyph at the left edge of point in the
     ;; current buffer.  Any existing glyph at this location is replaced.
     (defun insert-glyph (gl)
       "Insert a glyph at the left edge of point."
       (let ( (prop 'myimage)        ;; myimage is an arbitrary name, chosen
                                     ;; to (hopefully) not conflict with any
                                     ;; other properties.  Change it if
                                     ;; necessary.
              extent )
         ;; First, check to see if one of our extents already exists at
         ;; point.  For ease-of-programming, we are creating and using our
         ;; own extents (multiple extents are allowed to exist/overlap at the
         ;; same point, and it's quite possible for other applications to
         ;; embed extents in the current buffer without your knowledge).
         ;; Basically, if an extent, with the property stored in "prop",
         ;; exists at point, we assume that it is one of ours, and we re-use
         ;; it (this is why it is important for the property stored in "prop"
         ;; to be unique, and only used by us).
         (if (not (setq extent (extent-at (point) (current-buffer) prop)))
           (progn
             ;; If an extent does not already exist, create a zero-length
             ;; extent, and give it our special property.
             (setq extent (make-extent (point) (point) (current-buffer)))
             (set-extent-property extent prop t)
             ))
         ;; Display the glyph by storing it as the extent's "begin-glyph".
         (set-extent-property extent 'begin-glyph gl)
         ))

     ;; You can then use this function like:
     (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
     ;; This will insert the glyph at point.

     ;; Here's an example of how to insert two glyphs side-by-side, at point
     ;; (using the above code):
     (progn
       (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
       ;; Create a new extent at point.  We can't simply call "insert-glyph",
       ;; as "insert-glyph" will simply replace the first glyph with the
       ;; second.
       (setq extent (make-extent (point) (point) (current-buffer)))
       ;; Here, we're only setting the 'myimage property in case we need
       ;; to later identify/locate/reuse this particular extent.
       (set-extent-property extent 'myimage t)
       (set-extent-property extent 'begin-glyph
                            (make-glyph [jpeg :file "/tmp/file2.jpg"]))
       )

   Here are the gory details:

   * Glyphs are displayed by attaching them to extents (see *Note
     Extents::), either to the beginning or the end of extents.

     Note that extents can be used for many things, and not just for
     displaying images (although, in the above example, we are creating
     our own extent for the sole purpose of displaying an image).
     Also, note that multiple extents are allowed to exist at the same
     position, and they can overlap.

   * Glyphs are often displayed inside the text area (alongside text).
     This is the default.

     Although glyphs can also be displayed in the margins, how to do
     this will not be described here.  For more information on this, see
     *Note Annotation Basics:: (look for information on "layout types")
     and *Note Extent Properties:: (look for `begin-glyph-layout' and
     `end-glyph-layout').

   * The easiest way to insert a glyph into text is to create a
     zero-length extent at the point where you want the glyph to appear.

     Note that zero-length extents are attached to the character to the
     right of the extent; deleting this character will also delete the
     extent.

   * It's often a good idea to assign a unique property to the
     newly-created extent, in case you later want to locate it, and
     replace any existing glyph with a different one (or just delete
     the existing one).  In the above example, we are using "myimage"
     as our (hopefully) unique property name.

     If you need to locate all of the extents, you'll have to use
     functions like `extent-list' or `next-extent', or provide
     additional parameters to the `extent-at' function.  Assigning a
     unique property to the extent makes it easy to locate your
     extents; for example, `extent-list' can return only those extents
     with a particular property.  *Note Finding Extents::, and *Note
     Mapping Over Extents::, for more information.

   * Glyphs are displayed by assigning then to the `begin-glyph' or
     `end-glyph' property of the extent.  For zero-length extents, it
     doesn't really matter if you assign the glyph to the `begin-glyph'
     or `end-glyph' property, as they are both at the same location;
     however, for non-zero-length extents (extents that cover one or
     more characters of text), it does matter which one you use.

     Assigning `nil' to the `begin-glyph' or `end-glyph' property will
     delete any existing glyph.  In this case, you may also want to
     delete the extent, assuming that the extent is used for no other
     purpose.

   * If you happen to insert two glyphs, side-by-side, note that the
     example `insert-glyph' function will have trouble, if it's again
     used at the same point (it can only locate one of the two extents).
     *Note Finding Extents::, and *Note Mapping Over Extents::, for more
     information on locating extents in a buffer.

   * Among other things, glyphs provide a way of displaying graphics
     alongside text.  Note, however, that glyphs only provide a way of
     displaying graphics; glyphs are not actually part of the text, and
     are only displayed alongside the text.  If you save the text in
     the buffer, the graphics are not saved.  The low-level glyph code
     does not provide a way of saving graphics with the text.  If you
     need to save graphics and text, you have to write your own code to
     do this, and this topic is outside the scope of this discussion.



File: lispref.info,  Node: Annotations,  Next: Display,  Prev: Glyphs,  Up: Top

51 Annotations
**************

An "annotation" is a pixmap or string that is not part of a buffer's
text but is displayed next to a particular location in a buffer.
Annotations can be displayed intermixed with text, in any whitespace at
the beginning or end of a line, or in a special area at the left or
right side of the frame called a "margin", whose size is controllable.
Annotations are implemented using extents (*note Extents::); but you
can work with annotations without knowing how extents work.

* Menu:

* Annotation Basics::		Introduction to annotations.
* Annotation Primitives::	Creating and deleting annotations.
* Annotation Properties::	Retrieving and changing the characteristics
				  of an annotation.
* Margin Primitives::		Controlling the size of the margins.
* Locating Annotations::	Looking for annotations in a buffer.
* Annotation Hooks::		Hooks called at certain times during an
				  annotation's lifetime.


File: lispref.info,  Node: Annotation Basics,  Next: Annotation Primitives,  Prev: Annotations,  Up: Annotations

51.1 Annotation Basics
======================

Marginal annotations are notes associated with a particular location in
a buffer.  They may be displayed in a margin created on the left-hand or
right-hand side of the frame, in any whitespace at the beginning or end
of a line, or inside of the text itself.  Every annotation may have an
associated action to be performed when the annotation is selected.  The
term "annotation" is used to refer to an individual note.  The term
"margin" is generically used to refer to the whitespace before the
first character on a line or after the last character on a line.

   Each annotation has the following characteristics:
GLYPH
     This is a glyph object and is used as the displayed representation
     of the annotation.

DOWN-GLYPH
     If given, this glyph is used as the displayed representation of
     the annotation when the mouse is pressed down over the annotation.

FACE
     The face with which to display the glyph.

SIDE
     Which side of the text (left or right) the annotation is displayed
     at.

ACTION
     If non-`nil', this field must contain a function capable of being
     the first argument to `funcall'.  This function is normally
     evaluated with a single argument, the value of the DATA field,
     each time the annotation is selected.  However, if the WITH-EVENT
     parameter to `make-annotation' is non-`nil', the function is
     called with two arguments.  The first argument is the same as
     before, and the second argument is the event (a button-up event,
     usually) that activated the annotation.

DATA
     Not used internally.  This field can contain any E-Lisp object.
     It is passed as the first argument to ACTION described above.

MENU
     A menu displayed when the right mouse button is pressed over the
     annotation.

   The margin is divided into "outside" and "inside".  The outside
margin is space on the left or right side of the frame which normal text
cannot be displayed in.  The inside margin is that space between the
leftmost or rightmost point at which text can be displayed and where the
first or last character actually is.

   There are four different "layout types" which affect the exact
location an annotation appears.

`outside-margin'
     The annotation is placed in the outside margin area. as close as
     possible to the edge of the frame.  If the outside margin is not
     wide enough for an annotation to fit, it is not displayed.

`inside-margin'
     The annotation is placed in the inside margin area, as close as
     possible to the edge of the frame.  If the inside margin is not
     wide enough for the annotation to fit, it will be displayed using
     any available outside margin space if and only if the specifier
     `use-left-overflow' or `use-right-overflow' (depending on which
     side the annotation appears in) is non-`nil'.

`whitespace'
     The annotation is placed in the inside margin area, as close as
     possible to the first or last non-whitespace character on a line.
     If the inside margin is not wide enough for the annotation to fit,
     it will be displayed if and only if the specifier
     `use-left-overflow' or `use-right-overflow' (depending on which
     side the annotation appears in) is non-`nil'.

`text'
     The annotation is placed at the position it is inserted.  It will
     create enough space for itself inside of the text area.  It does
     not take up a place in the logical buffer, only in the display of
     the buffer.

   The current layout policy is that all `whitespace' annotations are
displayed first.  Next, all `inside-margin' annotations are displayed
using any remaining space.  Finally as many `outside-margin'
annotations are displayed as possible.  The `text' annotations will
always display as they create their own space to display in.


File: lispref.info,  Node: Annotation Primitives,  Next: Annotation Properties,  Prev: Annotation Basics,  Up: Annotations

51.2 Annotation Primitives
==========================

 -- Function: make-annotation glyph &optional position layout buffer
          with-event d-glyph rightp
     This function creates a marginal annotation at position POSITION in
     BUFFER.  The annotation is displayed using GLYPH, which should be
     a glyph object or a string, and is positioned using layout policy
     LAYOUT.  If POSITION is `nil', point is used.  If LAYOUT is `nil',
     `whitespace' is used.  If BUFFER is `nil', the current buffer is
     used.

     If WITH-EVENT is non-`nil', then when an annotation is activated,
     the triggering event is passed as the second arg to the annotation
     function.  If D-GLYPH is non-`nil' then it is used as the glyph
     that will be displayed when button1 is down.  If RIGHTP is
     non-`nil' then the glyph will be displayed on the right side of
     the buffer instead of the left.

     The newly created annotation is returned.

 -- Function: delete-annotation annotation
     This function removes ANNOTATION from its buffer.  This does not
     modify the buffer text.

 -- Function: annotationp annotation
     This function returns `t' if ANNOTATION is an annotation, `nil'
     otherwise.


File: lispref.info,  Node: Annotation Properties,  Next: Locating Annotations,  Prev: Annotation Primitives,  Up: Annotations

51.3 Annotation Properties
==========================

 -- Function: annotation-glyph annotation
     This function returns the glyph object used to display ANNOTATION.

 -- Function: set-annotation-glyph annotation glyph &optional layout
          side
     This function sets the glyph of ANNOTATION to GLYPH, which should
     be a glyph object.  If LAYOUT is non-`nil', set the layout policy
     of ANNOTATION to LAYOUT.  If SIDE is `left' or `right', change the
     side of the buffer at which the annotation is displayed to the
     given side.  The new value of `annotation-glyph' is returned.

 -- Function: annotation-down-glyph annotation
     This function returns the glyph used to display ANNOTATION when
     the left mouse button is depressed on the annotation.

 -- Function: set-annotation-down-glyph annotation glyph
     This function returns the glyph used to display ANNOTATION when
     the left mouse button is depressed on the annotation to GLYPH,
     which should be a glyph object.

 -- Function: annotation-face annotation
     This function returns the face associated with ANNOTATION.

 -- Function: set-annotation-face annotation face
     This function sets the face associated with ANNOTATION to FACE.

 -- Function: annotation-layout annotation
     This function returns the layout policy of ANNOTATION.

 -- Function: set-annotation-layout annotation layout
     This function sets the layout policy of ANNOTATION to LAYOUT.

 -- Function: annotation-side annotation
     This function returns the side of the buffer that ANNOTATION is
     displayed on.  Return value is a symbol, either `left' or `right'.

 -- Function: annotation-data annotation
     This function returns the data associated with ANNOTATION.

 -- Function: set-annotation-data annotation data
     This function sets the data field of ANNOTATION to DATA.  DATA is
     returned.

 -- Function: annotation-action annotation
     This function returns the action associated with ANNOTATION.

 -- Function: set-annotation-action annotation action
     This function sets the action field of ANNOTATION to ACTION.
     ACTION is returned..

 -- Function: annotation-menu annotation
     This function returns the menu associated with ANNOTATION.

 -- Function: set-annotation-menu annotation menu
     This function sets the menu associated with ANNOTATION to MENU.
     This menu will be displayed when the right mouse button is pressed
     over the annotation.

 -- Function: annotation-visible annotation
     This function returns `t' if there is enough available space to
     display ANNOTATION, `nil' otherwise.

 -- Function: annotation-width annotation
     This function returns the width of ANNOTATION in pixels.

 -- Function: hide-annotation annotation
     This function removes ANNOTATION's glyph, making it invisible.

 -- Function: reveal-annotation annotation
     This function restores ANNOTATION's glyph, making it visible.


File: lispref.info,  Node: Locating Annotations,  Next: Margin Primitives,  Prev: Annotation Properties,  Up: Annotations

51.4 Locating Annotations
=========================

 -- Function: annotations-in-region start end buffer
     This function returns a list of all annotations in BUFFER which
     are between START and END inclusively.

 -- Function: annotations-at &optional position buffer
     This function returns a list of all annotations at POSITION in
     BUFFER.  If POSITION is `nil' point is used.  If BUFFER is `nil'
     the current buffer is used.

 -- Function: annotation-list &optional buffer
     This function returns a list of all annotations in BUFFER.  If
     BUFFER is `nil', the current buffer is used.

 -- Function: all-annotations
     This function returns a list of all annotations in all buffers in
     existence.


File: lispref.info,  Node: Margin Primitives,  Next: Annotation Hooks,  Prev: Locating Annotations,  Up: Annotations

51.5 Margin Primitives
======================

The margin widths are controllable on a buffer-local, window-local,
frame-local, device-local, or device-type-local basis through the use
of specifiers.  *Note Specifiers::.

 -- Specifier: left-margin-width
     This is a specifier variable controlling the width of the left
     outside margin, in characters.  Use `set-specifier' to change its
     value.

 -- Specifier: right-margin-width
     This is a specifier variable controlling the width of the right
     outside margin, in characters.  Use `set-specifier' to change its
     value.

 -- Specifier: use-left-overflow
     If non-`nil', use the left outside margin as extra whitespace when
     displaying `whitespace' and `inside-margin' annotations.  Defaults
     to `nil'.  This is a specifier variable; use `set-specifier' to
     change its value.

 -- Specifier: use-right-overflow
     If non-`nil', use the right outside margin as extra whitespace when
     displaying `whitespace' and `inside-margin' annotations.  Defaults
     to `nil'.  This is a specifier variable; use `set-specifier' to
     change its value.

 -- Function: window-left-margin-pixel-width &optional window
     This function returns the width in pixels of the left outside
     margin of WINDOW.  If WINDOW is `nil', the selected window is
     assumed.

 -- Function: window-right-margin-pixel-width &optional window
     This function returns the width in pixels of the right outside
     margin of WINDOW.  If WINDOW is `nil', the selected window is
     assumed.

   The margin colors are controlled by the faces `left-margin' and
`right-margin'.  These can be set using the X resources
`Emacs.left-margin.background' and `Emacs.left-margin.foreground';
likewise for the right margin.


File: lispref.info,  Node: Annotation Hooks,  Prev: Margin Primitives,  Up: Annotations

51.6 Annotation Hooks
=====================

The following three hooks are provided for use with the marginal
annotations:

`before-delete-annotation-hook'
     This hook is called immediately before an annotation is destroyed.
     It is passed a single argument, the annotation being destroyed.

`after-delete-annotation-hook'
     This normal hook is called immediately after an annotation is
     destroyed.

`make-annotation-hook'
     This hook is called immediately after an annotation is created.
     It is passed a single argument, the newly created annotation.


File: lispref.info,  Node: Display,  Next: Hash Tables,  Prev: Annotations,  Up: Top

52 Emacs Display
****************

This chapter describes a number of other features related to the display
that XEmacs presents to the user.

* Menu:

* Refresh Screen::      Clearing the screen and redrawing everything on it.
* Truncation::          Folding or wrapping long text lines.
* The Echo Area::       Where messages are displayed.
* Warnings::            Display of Warnings.
* Invisible Text::      Hiding part of the buffer text.
* Selective Display::   Hiding part of the buffer text (the old way).
* Overlay Arrow::       Display of an arrow to indicate position.
* Temporary Displays::  Displays that go away automatically.
* Blinking::            How XEmacs shows the matching open parenthesis.
* Usual Display::	The usual conventions for displaying nonprinting chars.
* Display Tables::	How to specify other conventions.
* Beeping::             Audible signal to the user.


File: lispref.info,  Node: Refresh Screen,  Next: Truncation,  Prev: Display,  Up: Display

52.1 Refreshing the Screen
==========================

The function `redraw-frame' redisplays the entire contents of a given
frame.  *Note Frames::.

 -- Function: redraw-frame &optional frame no-preempt
     This function clears and redisplays frame FRAME.

     FRAME defaults to the selected frame if omitted.

     Normally, redisplay is preempted as normal if input arrives.
     However, if optional second arg NO-PREEMPT is non-`nil', redisplay
     will not stop for input and is guaranteed to proceed to completion.

   Even more powerful is `redraw-display':

 -- Command: redraw-display &optional device
     This function redraws all frames on DEVICE marked as having their
     image garbled.  DEVICE defaults to the selected device.  If DEVICE
     is `t', all devices will have their frames checked.

   Processing user input takes absolute priority over redisplay.  If you
call these functions when input is available, they do nothing
immediately, but a full redisplay does happen eventually--after all the
input has been processed.

   Normally, suspending and resuming XEmacs also refreshes the screen.
Some terminal emulators record separate contents for display-oriented
programs such as XEmacs and for ordinary sequential display.  If you are
using such a terminal, you might want to inhibit the redisplay on
resumption.  *Note Suspending XEmacs::.

 -- Variable: no-redraw-on-reenter
     This variable controls whether XEmacs redraws the entire screen
     after it has been suspended and resumed.  Non-`nil' means yes,
     `nil' means no.

   The above functions do not actually cause the display to be updated;
rather, they clear out the internal display records that XEmacs
maintains, so that the next time the display is updated it will be
redrawn from scratch.  Normally this occurs the next time that
`next-event' or `sit-for' is called; however, a display update will not
occur if there is input pending.  *Note Command Loop::.

 -- Function: force-cursor-redisplay &optional frame
     This function causes an immediate update of the cursor on FRAME,
     which defaults to the selected frame.


File: lispref.info,  Node: Truncation,  Next: The Echo Area,  Prev: Refresh Screen,  Up: Display

52.2 Truncation
===============

When a line of text extends beyond the right edge of a window, the line
can either be truncated or continued on the next line.  When a line is
truncated, this is normally shown with a `\' in the rightmost column of
the window on X displays, and with a `$' on TTY devices.  When a line
is continued or "wrapped" onto the next line, this is shown with a
curved arrow in the rightmost column of the window (or with a `\' on
TTY devices).  The additional screen lines used to display a long text
line are called "continuation" lines.

   Normally, whenever line truncation is in effect for a particular
window, a horizontal scrollbar is displayed in that window if the
device supports scrollbars.  *Note Scrollbars::.

   Note that continuation is different from filling; continuation
happens on the screen only, not in the buffer contents, and it breaks a
line precisely at the right margin, not at a word boundary.  *Note
Filling::.

 -- User Option: truncate-lines
     This buffer-local variable controls how XEmacs displays lines that
     extend beyond the right edge of the window.  If it is non-`nil',
     then XEmacs does not display continuation lines; rather each line
     of text occupies exactly one screen line, and a backslash appears
     at the edge of any line that extends to or beyond the edge of the
     window.  The default is `nil'.

     If the variable `truncate-partial-width-windows' is non-`nil',
     then truncation is always used for side-by-side windows (within one
     frame) regardless of the value of `truncate-lines'.

 -- User Option: default-truncate-lines
     This variable is the default value for `truncate-lines', for
     buffers that do not have local values for it.

 -- User Option: truncate-partial-width-windows
     This variable controls display of lines that extend beyond the
     right edge of the window, in side-by-side windows (*note Splitting
     Windows::).  If it is non-`nil', these lines are truncated;
     otherwise, `truncate-lines' says what to do with them.

   The backslash and curved arrow used to indicate truncated or
continued lines are only defaults, and can be changed.  These images
are actually glyphs (*note Glyphs::).  XEmacs provides a great deal of
flexibility in how glyphs can be controlled. (This differs from FSF
Emacs, which uses display tables to control these images.)

   For details, *Note Redisplay Glyphs::.


File: lispref.info,  Node: The Echo Area,  Next: Warnings,  Prev: Truncation,  Up: Display

52.3 The Echo Area
==================

The "echo area" is used for displaying messages made with the `message'
primitive, and for echoing keystrokes.  It is not the same as the
minibuffer, despite the fact that the minibuffer appears (when active)
in the same place on the screen as the echo area.  The `XEmacs Lisp
Reference Manual' specifies the rules for resolving conflicts between
the echo area and the minibuffer for use of that screen space (*note
The Minibuffer: (xemacs)Minibuffer.).  Such a conflicts may be avoided
at all as described in *Note Customizing Message Display::.

   Error messages appear in the echo area; see *Note Errors::.

   You can write output in the echo area by using the Lisp printing
functions with `t' as the stream (*note Output Functions::), or as
follows:

 -- Function: message string &rest arguments
     This function displays a one-line message in the echo area.  The
     argument STRING is similar to a C language `printf' control
     string.  See `format' in *Note String Conversion::, for the details
     on the conversion specifications.  `message' returns the
     constructed string.

     In batch mode, `message' prints the message text on the standard
     error stream, followed by a newline.

     If STRING is `nil', `message' clears the echo area.  If the
     minibuffer is active, this brings the minibuffer contents back onto
     the screen immediately.

          (message "Minibuffer depth is %d."
                   (minibuffer-depth))
           -| Minibuffer depth is 0.
          => "Minibuffer depth is 0."

          ---------- Echo Area ----------
          Minibuffer depth is 0.
          ---------- Echo Area ----------

   In addition to only displaying a message, XEmacs allows you to
"label" your messages, giving you fine-grained control of their
display.  Message label is a symbol denoting the message type.  Some
standard labels are:

   * `message'--default label used by the `message' function;

   * `error'--default label used for reporting errors;

   * `progress'--progress indicators like `Converting... 45%' (not
     logged by default);

   * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
     default);

   * `command'--helper command messages like `Mark set' (not logged by
     default);

   * `no-log'--messages that should never be logged

   Several messages may be stacked in the echo area at once.  Lisp
programs may access these messages, or remove them as appropriate, via
the message stack.

 -- Function: display-message label message &optional frame stdout-p
     This function displays MESSAGE (a string) labeled as LABEL, as
     described above.

     The FRAME argument specifies the frame to whose minibuffer the
     message should be printed.  This is currently unimplemented.  The
     STDOUT-P argument is used internally.

          (display-message 'command "Mark set")

 -- Function: lmessage label string &rest arguments
     This function displays a message STRING with label LABEL.  It is
     similar to `message' in that it accepts a `printf'-like strings
     and any number of arguments.

          ;; Display a command message.
          (lmessage 'command "Comment column set to %d" comment-column)

          ;; Display a progress message.
          (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)

          ;; Display a message that should not be logged.
          (lmessage 'no-log "Done")

 -- Function: clear-message &optional label frame stdout-p no-restore
     This function remove any message with the given LABEL from the
     message-stack, erasing it from the echo area if it's currently
     displayed there.

     If a message remains at the head of the message-stack and
     NO-RESTORE is `nil', it will be displayed.  The string which
     remains in the echo area will be returned, or `nil' if the
     message-stack is now empty.  If LABEL is `nil', the entire
     message-stack is cleared.

          ;; Show a message, wait for 2 seconds, and restore old minibuffer
          ;; contents.
          (message "A message")
           -| A message
          => "A Message"
          (lmessage 'my-label "Newsflash!  Newsflash!")
           -| Newsflash!  Newsflash!
          => "Newsflash!  Newsflash!"
          (sit-for 2)
          (clear-message 'my-label)
           -| A message
          => "A message"

     Unless you need the return value or you need to specify a label,
     you should just use `(message nil)'.

 -- Function: current-message &optional frame
     This function returns the current message in the echo area, or
     `nil'.  The FRAME argument is currently unused.

   Some of the messages displayed in the echo area are also recorded in
the ` *Message-Log*' buffer.  Exactly which messages will be recorded
can be tuned using the following variables.

 -- User Option: log-message-max-size
     This variable specifies the maximum size of the ` *Message-log*'
     buffer.

 -- Variable: log-message-ignore-labels
     This variable specifies the labels whose messages will not be
     logged.  It should be a list of symbols.

 -- Variable: log-message-ignore-regexps
     This variable specifies the regular expressions matching messages
     that will not be logged.  It should be a list of regular
     expressions.

     Normally, packages that generate messages that might need to be
     ignored should label them with `progress', `prompt', or `no-log',
     so they can be filtered by `log-message-ignore-labels'.

 -- Variable: echo-keystrokes
     This variable determines how much time should elapse before command
     characters echo.  Its value must be a number, which specifies the
     number of seconds to wait before echoing.  If the user types a
     prefix key (such as `C-x') and then delays this many seconds
     before continuing, the prefix key is echoed in the echo area.  Any
     subsequent characters in the same command will be echoed as well.

     If the value is zero, then command input is not echoed.

 -- Variable: cursor-in-echo-area
     This variable controls where the cursor appears when a message is
     displayed in the echo area.  If it is non-`nil', then the cursor
     appears at the end of the message.  Otherwise, the cursor appears
     at point--not in the echo area at all.

     The value is normally `nil'; Lisp programs bind it to `t' for
     brief periods of time.

* Menu:

* Customizing Message Display::


File: lispref.info,  Node: Customizing Message Display,  Prev: The Echo Area,  Up: The Echo Area

52.3.1 Customizing Message Display
----------------------------------

Message display function specify message intended for echo area by
putting message text into `" *Echo Area*"' buffer.  When event loop
code decides to update display after displaying the message, text of
this buffer is erased.  How exactly the text will be displayed may be
affected by the following.

 -- Variable: redisplay-echo-area-function
     The function called to display echo area text.  The default
     variable value, `redisplay-echo-area' function, does that by
     displaying the text in the same place on the screen as the echo
     area.  So does other redisplay code.  User code can avoid this
     regardless of what redisplay code will run afterwards by erasing
     text of `" *Echo Area*"' buffer.

 -- Variable: undisplay-echo-area-function
     The variable value, if non-`nil', is called by command loop after
     erasing text of `" *Echo Area*"' buffer.  It must clean up data
     created by `redisplay-echo-area-function' value.

 -- Variable: minibuffer-echo-wait-function
     The function is called by command loop only when minibuffer was
     active and message was displayed (text appeared in `" *Echo Area*"'
     buffer).  It must wait after displaying message so that user can
     read it.  By default, when the variable value is `nil', the
     equivalent of `(sit-for 2)' is run.


File: lispref.info,  Node: Warnings,  Next: Invisible Text,  Prev: The Echo Area,  Up: Display

52.4 Warnings
=============

XEmacs contains a facility for unified display of various warnings.
Unlike errors, warnings are displayed in the situations when XEmacs
encounters a problem that is recoverable, but which should be fixed for
safe future operation.

   For example, warnings are printed by the startup code when it
encounters problems with X keysyms, when there is an error in `.emacs',
and in other problematic situations.  Unlike messages, warnings are
displayed in a separate buffer, and include an explanatory message that
may span across several lines.  Here is an example of how a warning is
displayed:

     (1) (initialization/error) An error has occurred while loading ~/.emacs:

     Symbol's value as variable is void: bogus-variable

     To ensure normal operation, you should investigate the cause of the error
     in your initialization file and remove it.  Use the `-debug-init' option
     to XEmacs to view a complete error backtrace.

   Each warning has a "class" and a "priority level".  The class is a
symbol describing what sort of warning this is, such as
`initialization', `resource' or `key-mapping'.

   The warning priority level specifies how important the warning is.
The recognized warning levels, in increased order of priority, are:
`debug', `info', `notice', `warning', `error', `critical', `alert' and
`emergency'.

 -- Function: display-warning class message &optional level
     This function displays a warning message MESSAGE (a string).
     CLASS should be a warning class symbol, as described above, or a
     list of such symbols.  LEVEL describes the warning priority level.
     If unspecified, it default to `warning'.

          (display-warning 'resource
            "Bad resource specification encountered:
          something like

              Emacs*foo: bar

          You should replace the * with a . in order to get proper behavior when
          you use the specifier and/or `set-face-*' functions.")

          ---------- Warning buffer ----------
          (1) (resource/warning) Bad resource specification encountered:
          something like

              Emacs*foo: bar

          You should replace the * with a . in order to get proper behavior when
          you use the specifier and/or `set-face-*' functions.
          ---------- Warning buffer ----------

 -- Function: lwarn class level message &rest args
     This function displays a formatted labeled warning message.  As
     above, CLASS should be the warning class symbol, or a list of such
     symbols, and LEVEL should specify the warning priority level
     (`warning' by default).

     Unlike in `display-warning', MESSAGE may be a formatted message,
     which will be, together with the rest of the arguments, passed to
     `format'.

          (lwarn 'message-log 'warning
            "Error caught in `remove-message-hook': %s"
            (error-message-string e))

 -- Variable: log-warning-minimum-level
     This variable specifies the minimum level of warnings that should
     be generated.  Warnings with level lower than defined by this
     variable are completely ignored, as if they never happened.

 -- Variable: display-warning-minimum-level
     This variable specifies the minimum level of warnings that should
     be displayed.  Unlike `log-warning-minimum-level', setting this
     function does not suppress warnings entirely--they are still
     generated in the `*Warnings*' buffer, only they are not displayed
     by default.

 -- Variable: log-warning-suppressed-classes
     This variable specifies a list of classes that should not be
     logged or displayed.  If any of the class symbols associated with
     a warning is the same as any of the symbols listed here, the
     warning will be completely ignored, as it they never happened.

 -- Variable: display-warning-suppressed-classes
     This variable specifies a list of classes that should not be
     logged or displayed.  If any of the class symbols associated with
     a warning is the same as any of the symbols listed here, the
     warning will not be displayed.  The warning will still logged in
     the *Warnings* buffer (unless also contained in
     `log-warning-suppressed-classes'), but the buffer will not be
     automatically popped up.


File: lispref.info,  Node: Invisible Text,  Next: Selective Display,  Prev: Warnings,  Up: Display

52.5 Invisible Text
===================

You can make characters "invisible", so that they do not appear on the
screen, with the `invisible' property.  This can be either a text
property or a property of an overlay.

   In the simplest case, any non-`nil' `invisible' property makes a
character invisible.  This is the default case--if you don't alter the
default value of `buffer-invisibility-spec', this is how the
`invisibility' property works.  This feature is much like selective
display (*note Selective Display::), but more general and cleaner.

   More generally, you can use the variable `buffer-invisibility-spec'
to control which values of the `invisible' property make text
invisible.  This permits you to classify the text into different subsets
in advance, by giving them different `invisible' values, and
subsequently make various subsets visible or invisible by changing the
value of `buffer-invisibility-spec'.

   Controlling visibility with `buffer-invisibility-spec' is especially
useful in a program to display the list of entries in a data base.  It
permits the implementation of convenient filtering commands to view
just a part of the entries in the data base.  Setting this variable is
very fast, much faster than scanning all the text in the buffer looking
for properties to change.

 -- Variable: buffer-invisibility-spec
     This variable specifies which kinds of `invisible' properties
     actually make a character invisible.

    `t'
          A character is invisible if its `invisible' property is
          non-`nil'.  This is the default.

    a list
          Each element of the list makes certain characters invisible.
          Ultimately, a character is invisible if any of the elements
          of this list applies to it.  The list can have two kinds of
          elements:

         `ATOM'
               A character is invisible if its `invisible' property
               value is ATOM or if it is a list with ATOM as a member.

         `(ATOM . t)'
               A character is invisible if its `invisible' property
               value is ATOM or if it is a list with ATOM as a member.
               Moreover, if this character is at the end of a line and
               is followed by a visible newline, it displays an
               ellipsis.

   Ordinarily, commands that operate on text or move point do not care
whether the text is invisible.  However, the user-level line motion
commands explicitly ignore invisible newlines.  Since this causes a
slow-down of these commands it is turned off by default, controlled by
the variable `line-move-ignore-invisible'.


File: lispref.info,  Node: Selective Display,  Next: Overlay Arrow,  Prev: Invisible Text,  Up: Display

52.6 Selective Display
======================

"Selective display" is a pair of features that hide certain lines on
the screen.

   The first variant, explicit selective display, is designed for use in
a Lisp program.  The program controls which lines are hidden by altering
the text.  Outline mode has traditionally used this variant.  It has
been partially replaced by the invisible text feature (*note Invisible
Text::); there is a new version of Outline mode which uses that instead.

   In the second variant, the choice of lines to hide is made
automatically based on indentation.  This variant is designed to be a
user-level feature.

   The way you control explicit selective display is by replacing a
newline (control-j) with a carriage return (control-m).  The text that
was formerly a line following that newline is now invisible.  Strictly
speaking, it is temporarily no longer a line at all, since only newlines
can separate lines; it is now part of the previous line.

   Selective display does not directly affect editing commands.  For
example, `C-f' (`forward-char') moves point unhesitatingly into
invisible text.  However, the replacement of newline characters with
carriage return characters affects some editing commands.  For example,
`next-line' skips invisible lines, since it searches only for newlines.
Modes that use selective display can also define commands that take
account of the newlines, or that make parts of the text visible or
invisible.

   When you write a selectively displayed buffer into a file, all the
control-m's are output as newlines.  This means that when you next read
in the file, it looks OK, with nothing invisible.  The selective display
effect is seen only within XEmacs.

 -- Variable: selective-display
     This buffer-local variable enables selective display.  This means
     that lines, or portions of lines, may be made invisible.

        * If the value of `selective-display' is `t', then any portion
          of a line that follows a control-m is not displayed.

        * If the value of `selective-display' is a positive integer,
          then lines that start with more than that many columns of
          indentation are not displayed.

     When some portion of a buffer is invisible, the vertical movement
     commands operate as if that portion did not exist, allowing a
     single `next-line' command to skip any number of invisible lines.
     However, character movement commands (such as `forward-char') do
     not skip the invisible portion, and it is possible (if tricky) to
     insert or delete text in an invisible portion.

     In the examples below, we show the _display appearance_ of the
     buffer `foo', which changes with the value of `selective-display'.
     The _contents_ of the buffer do not change.

          (setq selective-display nil)
               => nil

          ---------- Buffer: foo ----------
          1 on this column
           2on this column
            3n this column
            3n this column
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

          (setq selective-display 2)
               => 2

          ---------- Buffer: foo ----------
          1 on this column
           2on this column
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

 -- Variable: selective-display-ellipses
     If this buffer-local variable is non-`nil', then XEmacs displays
     `...' at the end of a line that is followed by invisible text.
     This example is a continuation of the previous one.

          (setq selective-display-ellipses t)
               => t

          ---------- Buffer: foo ----------
          1 on this column
           2on this column ...
           2on this column
          1 on this column
          ---------- Buffer: foo ----------

     You can use a display table to substitute other text for the
     ellipsis (`...').  *Note Display Tables::.


File: lispref.info,  Node: Overlay Arrow,  Next: Temporary Displays,  Prev: Selective Display,  Up: Display

52.7 The Overlay Arrow
======================

The "overlay arrow" is useful for directing the user's attention to a
particular line in a buffer.  For example, in the modes used for
interface to debuggers, the overlay arrow indicates the line of code
about to be executed.

 -- Variable: overlay-arrow-string
     This variable holds the string to display to call attention to a
     particular line, or `nil' if the arrow feature is not in use.
     Despite its name, the value of this variable can be either a string
     or a glyph (*note Glyphs::).

 -- Variable: overlay-arrow-position
     This variable holds a marker that indicates where to display the
     overlay arrow.  It should point at the beginning of a line.  The
     arrow text appears at the beginning of that line, overlaying any
     text that would otherwise appear.  Since the arrow is usually
     short, and the line usually begins with indentation, normally
     nothing significant is overwritten.

     The overlay string is displayed only in the buffer that this marker
     points into.  Thus, only one buffer can have an overlay arrow at
     any given time.

   You can do the same job by creating an extent with a `begin-glyph'
property.  *Note Extent Properties::.


File: lispref.info,  Node: Temporary Displays,  Next: Blinking,  Prev: Overlay Arrow,  Up: Display

52.8 Temporary Displays
=======================

Temporary displays are used by commands to put output into a buffer and
then present it to the user for perusal rather than for editing.  Many
of the help commands use this feature.

 -- Special Operator: with-output-to-temp-buffer buffer-name forms...
     This function executes FORMS while arranging to insert any output
     they print into the buffer named BUFFER-NAME.  The buffer is then
     shown in some window for viewing, displayed but not selected.

     The string BUFFER-NAME specifies the temporary buffer, which need
     not already exist.  The argument must be a string, not a buffer.
     The buffer is erased initially (with no questions asked), and it is
     marked as unmodified after `with-output-to-temp-buffer' exits.

     `with-output-to-temp-buffer' binds `standard-output' to the
     temporary buffer, then it evaluates the forms in FORMS.  Output
     using the Lisp output functions within FORMS goes by default to
     that buffer (but screen display and messages in the echo area,
     although they are "output" in the general sense of the word, are
     not affected).  *Note Output Functions::.

     The value of the last form in FORMS is returned.

          ---------- Buffer: foo ----------
           This is the contents of foo.
          ---------- Buffer: foo ----------

          (with-output-to-temp-buffer "foo"
              (print 20)
              (print standard-output))
          => #<buffer foo>

          ---------- Buffer: foo ----------
          20

          #<buffer foo>

          ---------- Buffer: foo ----------

 -- Variable: temp-buffer-show-function
     If this variable is non-`nil', `with-output-to-temp-buffer' calls
     it as a function to do the job of displaying a help buffer.  The
     function gets one argument, which is the buffer it should display.

     In Emacs versions 18 and earlier, this variable was called
     `temp-buffer-show-hook'.

 -- Function: momentary-string-display string position &optional char
          message
     This function momentarily displays STRING in the current buffer at
     POSITION.  It has no effect on the undo list or on the buffer's
     modification status.

     The momentary display remains until the next input event.  If the
     next input event is CHAR, `momentary-string-display' ignores it
     and returns.  Otherwise, that event remains buffered for
     subsequent use as input.  Thus, typing CHAR will simply remove the
     string from the display, while typing (say) `C-f' will remove the
     string from the display and later (presumably) move point forward.
     The argument CHAR is a space by default.

     The return value of `momentary-string-display' is not meaningful.

     You can do the same job in a more general way by creating an extent
     with a begin-glyph property.  *Note Extent Properties::.

     If MESSAGE is non-`nil', it is displayed in the echo area while
     STRING is displayed in the buffer.  If it is `nil', a default
     message says to type CHAR to continue.

     In this example, point is initially located at the beginning of the
     second line:

          ---------- Buffer: foo ----------
          This is the contents of foo.
          -!-Second line.
          ---------- Buffer: foo ----------

          (momentary-string-display
            "**** Important Message! ****"
            (point) ?\r
            "Type RET when done reading")
          => t

          ---------- Buffer: foo ----------
          This is the contents of foo.
          **** Important Message! ****Second line.
          ---------- Buffer: foo ----------

          ---------- Echo Area ----------
          Type RET when done reading
          ---------- Echo Area ----------

     This function works by actually changing the text in the buffer.
     As a result, if you later undo in this buffer, you will see the
     message come and go.


File: lispref.info,  Node: Blinking,  Next: Usual Display,  Prev: Temporary Displays,  Up: Display

52.9 Blinking Parentheses
=========================

This section describes the mechanism by which XEmacs shows a matching
open parenthesis when the user inserts a close parenthesis.

 -- Variable: blink-paren-function
     The value of this variable should be a function (of no arguments)
     to be called whenever a character with close parenthesis syntax is
     inserted.  The value of `blink-paren-function' may be `nil', in
     which case nothing is done.

          *Please note:* This variable was named `blink-paren-hook' in
          older Emacs versions, but since it is not called with the
          standard convention for hooks, it was renamed to
          `blink-paren-function' in version 19.

 -- Variable: blink-matching-paren
     If this variable is `nil', then `blink-matching-open' does nothing.

 -- Variable: blink-matching-paren-distance
     This variable specifies the maximum distance to scan for a matching
     parenthesis before giving up.

 -- Variable: blink-matching-paren-delay
     This variable specifies the number of seconds for the cursor to
     remain at the matching parenthesis.  A fraction of a second often
     gives good results, but the default is 1, which works on all
     systems.

 -- Command: blink-matching-open
     This function is the default value of `blink-paren-function'.  It
     assumes that point follows a character with close parenthesis
     syntax and moves the cursor momentarily to the matching opening
     character.  If that character is not already on the screen, it
     displays the character's context in the echo area.  To avoid long
     delays, this function does not search farther than
     `blink-matching-paren-distance' characters.

     Here is an example of calling this function explicitly.

          (defun interactive-blink-matching-open ()
            "Indicate momentarily the start of sexp before point."
            (interactive)
            (let ((blink-matching-paren-distance
                   (buffer-size))
                  (blink-matching-paren t))
              (blink-matching-open)))


File: lispref.info,  Node: Usual Display,  Next: Display Tables,  Prev: Blinking,  Up: Display

52.10 Usual Display Conventions
===============================

The usual display conventions define how to display each character
code.  You can override these conventions by setting up a display table
(*note Display Tables::).  Here are the usual display conventions:

   * Character codes 32 through 126 map to glyph codes 32 through 126.
     Normally this means they display as themselves.

   * Character code 9 is a horizontal tab.  It displays as whitespace
     up to a position determined by `tab-width'.

   * Character code 10 is a newline.

   * All other codes in the range 0 through 31, and code 127, display
     in one of two ways according to the value of `ctl-arrow'.  If it is
     non-`nil', these codes map to sequences of two glyphs, where the
     first glyph is the ASCII code for `^'.  (A display table can
     specify a glyph to use instead of `^'.)  Otherwise, these codes map
     just like the codes in the range 128 to 255.

   * Character codes 128 through 255 map to sequences of four glyphs,
     where the first glyph is the ASCII code for `\', and the others are
     digit characters representing the code in octal.  (A display table
     can specify a glyph to use instead of `\'.)

   The usual display conventions apply even when there is a display
table, for any character whose entry in the active display table is
`nil'.  Thus, when you set up a display table, you need only specify
the characters for which you want unusual behavior.

   These variables affect the way certain characters are displayed on
the screen.  Since they change the number of columns the characters
occupy, they also affect the indentation functions.

 -- User Option: ctl-arrow
     This buffer-local variable controls how control characters are
     displayed.  If it is non-`nil', they are displayed as a caret
     followed by the character: `^A'.  If it is `nil', they are
     displayed as a backslash followed by three octal digits: `\001'.

 -- Variable: default-ctl-arrow
     The value of this variable is the default value for `ctl-arrow' in
     buffers that do not override it.  *Note Default Value::.

 -- User Option: tab-width
     The value of this variable is the spacing between tab stops used
     for displaying tab characters in Emacs buffers.  The default is 8.
     Note that this feature is completely independent from the
     user-settable tab stops used by the command `tab-to-tab-stop'.
     *Note Indent Tabs::.


File: lispref.info,  Node: Display Tables,  Next: Beeping,  Prev: Usual Display,  Up: Display

52.11 Display Tables
====================

You can use the "display table" feature to control how all 256 possible
character codes display on the screen.  This is useful for displaying
European languages that have letters not in the ASCII character set.

   The display table maps each character code into a sequence of
"runes", each rune being an image that takes up one character position
on the screen.  You can also define how to display each rune on your
terminal, using the "rune table".

* Menu:

* Display Table Format::	What a display table consists of.
* Active Display Table::	How XEmacs selects a display table to use.
* Character Descriptors::	Format of an individual element of a
				  display table.


File: lispref.info,  Node: Display Table Format,  Next: Active Display Table,  Prev: Display Tables,  Up: Display Tables

52.11.1 Display Table Format
----------------------------

A display table is an array of 256 elements. (In FSF Emacs, a display
table is 262 elements.  The six extra elements specify the truncation
and continuation glyphs, etc.  This method is very kludgey, and in
XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
used.  *Note Truncation::.)

 -- Function: make-display-table
     This creates and returns a display table.  The table initially has
     `nil' in all elements.

   The 256 elements correspond to character codes; the Nth element says
how to display the character code N.  The value should be `nil', a
string, a glyph, or a vector of strings and glyphs (*note Character
Descriptors::).  If an element is `nil', it says to display that
character according to the usual display conventions (*note Usual
Display::).

   If you use the display table to change the display of newline
characters, the whole buffer will be displayed as one long "line."

   For example, here is how to construct a display table that mimics the
effect of setting `ctl-arrow' to a non-`nil' value:

     (setq disptab (make-display-table))
     (let ((i 0))
       (while (< i 32)
         (or (= i ?\t) (= i ?\n)
             (aset disptab i (concat "^" (char-to-string (+ i 64)))))
         (setq i (1+ i)))
       (aset disptab 127 "^?"))


File: lispref.info,  Node: Active Display Table,  Next: Character Descriptors,  Prev: Display Table Format,  Up: Display Tables

52.11.2 Active Display Table
----------------------------

The active display table is controlled by the variable
`current-display-table'.  This is a specifier, which means that you can
specify separate values for it in individual buffers, windows, frames,
and devices, as well as a global value.  It also means that you cannot
set this variable using `setq'; use `set-specifier' instead.  *Note
Specifiers::. (FSF Emacs uses `window-display-table',
`buffer-display-table', `standard-display-table', etc. to control the
display table.  However, specifiers are a cleaner and more powerful way
of doing the same thing.  FSF Emacs also uses a different format for
the contents of a display table, using additional indirection to a
"glyph table" and such.  Note that "glyph" has a different meaning in
XEmacs.)

 -- Variable: current-display-table
     The display table currently in use.  This is a specifier.

     Display tables are used to control how characters are displayed.
     Each time that redisplay processes a character, it is looked up in
     all the display tables that apply (obtained by calling
     `specifier-instance' on `current-display-table' and any overriding
     display tables specified in currently active faces).  The first
     entry found that matches the character determines how the
     character is displayed.  If there is no matching entry, the
     default display method is used. (Non-control characters are
     displayed as themselves and control characters are displayed
     according to the buffer-local variable `ctl-arrow'.  Control
     characters are further affected by `control-arrow-glyph' and
     `octal-escape-glyph'.)

     Each instantiator in this specifier and the display-table
     specifiers in faces is a display table or a list of such tables.
     If a list, each table will be searched in turn for an entry
     matching a particular character.  Each display table is one of

        * A vector, specifying values for characters starting at 0.

        * A char table, either of type `char' or `generic'.

        * A range table.

     Each entry in a display table should be one of

        * nil (this entry is ignored and the search continues).

        * A character (use this character; if it happens to be the same
          as the original character, default processing happens,
          otherwise redisplay attempts to display this character
          directly; #### At some point recursive display-table lookup
          will be implemented).

        * A string (display each character in the string directly; ####
          At some point recursive display-table lookup will be
          implemented).

        * A glyph (display the glyph; #### At some point recursive
          display-table lookup will be implemented when a string glyph
          is being processed).

        * A cons of the form (format "STRING") where STRING is a
          printf-like spec used to process the character. ####
          Unfortunately no formatting directives other than %% are
          implemented.

        * A vector (each element of the vector is processed recursively;
          in such a case, nil elements in the vector are simply
          ignored).

          #### At some point in the near future, display tables are
          likely to be expanded to include other features, such as
          referencing characters in particular fonts and allowing the
          character search to continue all the way up the chain of
          specifier instantiators.  These features are necessary to
          properly display Unicode characters.

   Individual faces can also specify an overriding display table; this
is set using `set-face-display-table'.  *Note Faces::.

   If no display table can be determined for a particular window, then
XEmacs uses the usual display conventions.  *Note Usual Display::.


File: lispref.info,  Node: Character Descriptors,  Prev: Active Display Table,  Up: Display Tables

52.11.3 Character Descriptors
-----------------------------

Each element of the display-table vector describes how to display a
particular character and is called a "character descriptor".  A
character descriptor can be:

a string
     Display this particular string wherever the character is to be
     displayed.

a glyph
     Display this particular glyph wherever the character is to be
     displayed.

a vector
     The vector may contain strings and/or glyphs.  Display the
     elements of the vector one after another wherever the character is
     to be displayed.

`nil'
     Display according to the standard interpretation (*note Usual
     Display::).


File: lispref.info,  Node: Beeping,  Prev: Display Tables,  Up: Display

52.12 Beeping
=============

You can make XEmacs ring a bell, play a sound, or blink the screen to
attract the user's attention.  Be conservative about how often you do
this; frequent bells can become irritating.  Also be careful not to use
beeping alone when signaling an error is appropriate.  (*Note Errors::.)

 -- Function: ding &optional dont-terminate sound device
     This function beeps, or flashes the screen (see `visible-bell'
     below).  It also terminates any keyboard macro currently executing
     unless DONT-TERMINATE is non-`nil'.  If SOUND is specified, it
     should be a symbol specifying which sound to make.  This sound
     will be played if `visible-bell' is `nil'. (This only works if
     sound support was compiled into the executable and you are running
     on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
     PC. Otherwise you just get a beep.) The optional third argument
     specifies what device to make the sound on, and defaults to the
     selected device.

 -- Function: beep &optional dont-terminate sound device
     This is a synonym for `ding'.

 -- User Option: visible-bell
     This variable determines whether XEmacs should flash the screen to
     represent a bell.  Non-`nil' means yes, `nil' means no.  On TTY
     devices, this is effective only if the Termcap entry for the
     terminal type has the visible bell flag (`vb') set.

 -- Variable: sound-alist
     This variable holds an alist associating names with sounds.  When
     `beep' or `ding' is called with one of the name symbols, the
     associated sound will be generated instead of the standard beep.

     Each element of `sound-alist' is a list describing a sound.  The
     first element of the list is the name of the sound being defined.
     Subsequent elements of the list are alternating keyword/value
     pairs:

    `sound'
          A string of raw sound data, or the name of another sound to
          play.  The symbol `t' here means use the default X beep.

    `volume'
          An integer from 0-100, defaulting to `bell-volume'.

    `pitch'
          If using the default X beep, the pitch (Hz) to generate.

    `duration'
          If using the default X beep, the duration (milliseconds).

     For compatibility, elements of `sound-alist' may also be:

        * `( sound-name . <sound> )'

        * `( sound-name <volume> <sound> )'

     You should probably add things to this list by calling the function
     `load-sound-file'.

     Caveats:

        - You can only play audio data if running on the console screen
          of a Sun SparcStation, SGI, or HP9000s700.

        - The pitch, duration, and volume options are available
          everywhere, but many X servers ignore the `pitch' option.

     The following beep-types are used by XEmacs itself:

    `auto-save-error'
          when an auto-save does not succeed

    `command-error'
          when the XEmacs command loop catches an error

    `undefined-key'
          when you type a key that is undefined

    `undefined-click'
          when you use an undefined mouse-click combination

    `no-completion'
          during completing-read

    `y-or-n-p'
          when you type something other than 'y' or 'n'

    `yes-or-no-p'
          when you type something other than 'yes' or 'no'

    `default'
          used when nothing else is appropriate.

     Other lisp packages may use other beep types, but these are the
     ones that the C kernel of XEmacs uses.

 -- User Option: bell-volume
     This variable specifies the default volume for sounds, from 0 to
     100.

 -- Command: load-default-sounds
     This function loads and installs some sound files as beep-types.

 -- Command: load-sound-file filename sound-name &optional volume
     This function reads in an audio file and adds it to `sound-alist'.
     The sound file must be in the Sun/NeXT U-LAW format.  SOUND-NAME
     should be a symbol, specifying the name of the sound.  If VOLUME
     is specified, the sound will be played at that volume; otherwise,
     the value of `bell-volume' will be used.

 -- Function: play-sound sound &optional volume device
     This function plays sound SOUND, which should be a symbol
     mentioned in `sound-alist'.  If VOLUME is specified, it overrides
     the value (if any) specified in `sound-alist'.  DEVICE specifies
     the device to play the sound on, and defaults to the selected
     device.

 -- Command: play-sound-file file &optional volume device
     This function plays the named sound file at volume VOLUME, which
     defaults to `bell-volume'.  DEVICE specifies the device to play
     the sound on, and defaults to the selected device.


File: lispref.info,  Node: Hash Tables,  Next: Range Tables,  Prev: Display,  Up: Top

53 Hash Tables
**************

 -- Function: hash-table-p object
     This function returns `t' if OBJECT is a hash table, else `nil'.

* Menu:

* Introduction to Hash Tables::	Hash tables are fast data structures for
                                implementing simple tables (i.e. finite
                                mappings from keys to values).
* Working With Hash Tables::    Hash table functions.
* Weak Hash Tables::            Hash tables with special garbage-collection
                                behavior.


File: lispref.info,  Node: Introduction to Hash Tables,  Next: Working With Hash Tables,  Prev: Hash Tables,  Up: Hash Tables

53.1 Introduction to Hash Tables
================================

A "hash table" is a data structure that provides mappings from
arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
called "values".  A key/value pair is sometimes called an "entry" in
the hash table.  There are many ways other than hash tables of
implementing the same sort of mapping, e.g.  association lists (*note
Association Lists::) and property lists (*note Property Lists::), but
hash tables provide much faster lookup when there are many entries in
the mapping.  Hash tables are an implementation of the abstract data
type "dictionary", also known as "associative array".

   Internally, hash tables are hashed using the "linear probing" hash
table implementation method.  This method hashes each key to a
particular spot in the hash table, and then scans forward sequentially
until a blank entry is found.  To look up a key, hash to the appropriate
spot, then search forward for the key until either a key is found or a
blank entry stops the search.  This method is used in preference to
double hashing because of changes in recent hardware.  The penalty for
non-sequential access to memory has been increasing, and this
compensates for the problem of clustering that linear probing entails.

   When hash tables are created, the user may (but is not required to)
specify initial properties that influence performance.

   Use the `:size' parameter to specify the number of entries that are
likely to be stored in the hash table, to avoid the overhead of resizing
the table.  But if the pre-allocated space for the entries is never
used, it is simply wasted and makes XEmacs slower.  Excess unused hash
table entries exact a small continuous performance penalty, since they
must be scanned at every garbage collection.  If the number of entries
in the hash table is unknown, simply avoid using the `:size' keyword.

   Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
the algorithm for deciding when to rehash the hash table.  For
temporary hash tables that are going to be very heavily used, use a
small rehash threshold, for example, 0.4 and a large rehash size, for
example 2.0.  For permanent hash tables that will be infrequently used,
specify a large rehash threshold, for example 0.8.

   Hash tables can also be created by the lisp reader using structure
syntax, for example:
     #s(hash-table :size 20 :data (foo 1 bar 2))

   The structure syntax accepts the same keywords as `make-hash-table',
as well as the additional keyword `data', which specifies the initial
hash table contents.  Older versions of XEmacs required that the
keywords not have the initial ":" in the structure syntax, and this
version of XEmacs still supports that syntax, but you cannot mix the
two styles within one structure.

 -- Function: make-hash-table &key `test' `size' `rehash-size'
          `rehash-threshold' `weakness'
     This function returns a new empty hash table object.

     Keyword `:test' can be `eq', `eql' (default), `equal', or `equalp'.
     Comparison between keys is done using this function.  If speed is
     important, consider using `eq'.  When storing strings in the hash
     table, you will likely need to use `equal', or `equalp' for
     case-insensitivity.

     Keyword `:size' specifies the number of keys likely to be inserted.
     This number of entries can be inserted without enlarging the hash
     table.

     Keyword `:rehash-size' must be a float greater than 1.0, and
     specifies the factor by which to increase the size of the hash
     table when enlarging.

     Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
     and specifies the load factor of the hash table which triggers
     enlarging.

     Non-standard keyword `:weakness' can be `nil' (default), `t',
     `key-and-value', `key', `value' or `key-or-value'.  `t' is an
     alias for `key-and-value'.

     A key-and-value-weak hash table, also known as a fully-weak or
     simply as a weak hash table, is one whose pointers do not count as
     GC referents: for any key-value pair in the hash table, if the only
     remaining pointer to either the key or the value is in a weak hash
     table, then the pair will be removed from the hash table, and the
     key and value collected.  A non-weak hash table (or any other
     pointer) would prevent the object from being collected.

     A key-weak hash table is similar to a fully-weak hash table except
     that a key-value pair will be removed only if the key remains
     unmarked outside of weak hash tables.  The pair will remain in the
     hash table if the key is pointed to by something other than a weak
     hash table, even if the value is not.

     A value-weak hash table is similar to a fully-weak hash table
     except that a key-value pair will be removed only if the value
     remains unmarked outside of weak hash tables.  The pair will
     remain in the hash table if the value is pointed to by something
     other than a weak hash table, even if the key is not.

     A key-or-value-weak hash table is similar to a fully-weak hash
     table except that a key-value pair will be removed only if the
     value and the key remain unmarked outside of weak hash tables.
     The pair will remain in the hash table if the value or key are
     pointed to by something other than a weak hash table, even if the
     other is not.

 -- Function: copy-hash-table hash-table
     This function returns a new hash table which contains the same
     keys and values as HASH-TABLE.  The keys and values will not
     themselves be copied.

 -- Function: hash-table-count hash-table
     This function returns the number of entries in HASH-TABLE.

 -- Function: hash-table-test hash-table
     This function returns the test function of HASH-TABLE.  This can
     be one of `eq', `eql', `equal', `equalp', or some NAME parameter
     given to `define-hash-table-test'.

 -- Function: hash-table-size hash-table
     This function returns the current number of slots in HASH-TABLE,
     whether occupied or not.

 -- Function: hash-table-rehash-size hash-table
     This function returns the current rehash size of HASH-TABLE.  This
     is a float greater than 1.0; the factor by which HASH-TABLE is
     enlarged when the rehash threshold is exceeded.

 -- Function: hash-table-rehash-threshold hash-table
     This function returns the current rehash threshold of HASH-TABLE.
     This is a float between 0.0 and 1.0; the maximum "load factor" of
     HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.

 -- Function: hash-table-weakness hash-table
     This function returns the weakness of HASH-TABLE.  This can be one
     of `nil', `t', `key' or `value'.


File: lispref.info,  Node: Working With Hash Tables,  Next: Weak Hash Tables,  Prev: Introduction to Hash Tables,  Up: Hash Tables

53.2 Working With Hash Tables
=============================

 -- Function: puthash key value hash-table
     This function hashes KEY to VALUE in HASH-TABLE.

 -- Function: gethash key hash-table &optional default
     This function finds the hash value for KEY in HASH-TABLE.  If
     there is no entry for KEY in HASH-TABLE, DEFAULT is returned
     (which in turn defaults to `nil').

 -- Function: remhash key hash-table
     This function removes the entry for KEY from HASH-TABLE.  Does
     nothing if there is no entry for KEY in HASH-TABLE.

 -- Function: clrhash hash-table
     This function removes all entries from HASH-TABLE, leaving it
     empty.

 -- Function: maphash function hash-table
     This function maps FUNCTION over entries in HASH-TABLE, calling it
     with two args, each key and value in the hash table.

     FUNCTION may not modify HASH-TABLE, with the one exception that
     FUNCTION may remhash or puthash the entry currently being
     processed by FUNCTION.

 -- Function: define-hash-table-test name test-function hash-function
     Creates a new hash table test function, beyond the four specified
     by Common Lisp.  NAME is a symbol, and `define-hash-table-test'
     will error if there exists a hash table test with that name
     already.  (If you want to repeatedly define hash tables, use a
     symbol generated with `gensym' for NAME).

     TEST-FUNCTION must accept two arguments and return non-nil if both
     arguments are the same.

     HASH-FUNCTION must accept one argument and return an integer hash
     code for its argument.  HASH-FUNCTION should use the entire range
     of the underlying C long type, typically represented with two more
     value bits than the Lisp fixnum type.

     Returns t on success, an incompatibility with GNU Emacs, which
     returns a list comprising TEST-FUNCTION and HASH-FUNCTION.


File: lispref.info,  Node: Weak Hash Tables,  Prev: Working With Hash Tables,  Up: Hash Tables

53.3 Weak Hash Tables
=====================

A "weak hash table" is a special variety of hash table whose elements
do not count as GC referents.  For any key-value pair in such a hash
table, if either the key or value (or in some cases, if one particular
one of the two) has no references to it outside of weak hash tables
(and similar structures such as weak lists), the pair will be removed
from the table, and the key and value collected.  A non-weak hash table
(or any other pointer) would prevent the objects from being collected.

   Weak hash tables are useful for keeping track of information in a
non-obtrusive way, for example to implement caching.  If the cache
contains objects such as buffers, markers, image instances, etc. that
will eventually disappear and get garbage-collected, using a weak hash
table ensures that these objects are collected normally rather than
remaining around forever, long past their actual period of use.
(Otherwise, you'd have to explicitly map over the hash table every so
often and remove unnecessary elements.)

   There are four types of weak hash tables:

key-and-value-weak hash tables
     In these hash tables, also known as fully weak or simply as weak
     hash tables, a pair disappears if either the key or the value is
     unreferenced outside of the table.

key-weak hash tables
     In these hash tables, a pair disappears if the key is unreferenced
     outside of the table, regardless of how the value is referenced.

value-weak hash tables
     In these hash tables, a pair disappears if the value is
     unreferenced outside of the table, regardless of how the key is
     referenced.

key-or-value-weak hash tables
     In these hash tables, a pair disappears if both the key and the
     value are unreferenced outside of the table.

   Also see *Note Weak Lists::.

   Weak hash tables are created by specifying the `:weakness' keyword to
`make-hash-table'.


File: lispref.info,  Node: Range Tables,  Next: Databases,  Prev: Hash Tables,  Up: Top

54 Range Tables
***************

A range table is a table that efficiently associates values with ranges
of fixnums.

   Note that range tables have a read syntax, like this:

     #s(range-table type start-closed-end-open data ((-3 2) foo (5 20) bar))

   This maps integers in the range [-3, 2) to `foo' and integers in the
range [5, 20) to `bar'.

   By default, range tables have a TYPE of `start-closed-end-open'.
(*NOTE*: This is a change from 21.4 and earlier, where there was no
TYPE and range tables were always closed on both ends.) This makes them
work like text properties.

 -- Function: range-table-p object
     Return non-`nil' if OBJECT is a range table.

* Menu:

* Introduction to Range Tables:: Range tables efficiently map ranges of
                                 integers to values.
* Working With Range Tables::    Range table functions.


File: lispref.info,  Node: Introduction to Range Tables,  Next: Working With Range Tables,  Prev: Range Tables,  Up: Range Tables

54.1 Introduction to Range Tables
=================================

 -- Function: make-range-table &optional type
     Make a new, empty range table.

     TYPE is a symbol indicating how ranges are assumed to function at
     their ends.  It can be one of

          SYMBOL                                     RANGE-START         RANGE-END
          ------                                     -----------         ---------
          `start-closed-end-open'  (the default)     closed              open
          `start-closed-end-closed'                  closed              closed
          `start-open-end-open'                      open                open
          `start-open-end-closed'                    open                closed

     A "closed" endpoint of a range means that the number at that end
     is included in the range.  For an "open" endpoint, the number
     would not be included.

     For example, a closed-open range from 5 to 20 would be indicated as
     `[5, 20)' where a bracket indicates a closed end and a parenthesis
     an open end, and would mean `all the numbers between 5 and 20',
     including 5 but not 20.  This seems a little strange at first but
     is in fact extremely common in the outside world as well as in
     computers and makes things work sensibly.  For example, if I say
     "there are seven days between today and next week today", I'm
     including today but not next week today; if I included both, there
     would be eight days.  Similarly, there are 15 (= 20 - 5) elements
     in the range `[5, 20)', but 16 in the range `[5, 20]'.

 -- Function: copy-range-table range-table
     This function returns a new range table which contains the same
     values for the same ranges as RANGE-TABLE.  The values will not
     themselves be copied.


File: lispref.info,  Node: Working With Range Tables,  Prev: Introduction to Range Tables,  Up: Range Tables

54.2 Working With Range Tables
==============================

 -- Function: get-range-table pos range-table &optional default
     This function finds value for position POS in RANGE-TABLE.  If
     there is no corresponding value, return DEFAULT (defaults to
     `nil').

     *NOTE*: If you are working with ranges that are closed at the
     start and open at the end (the default), and you put a value for a
     range with START equal to END, `get-range-table' will *not* return
     that value!  You would need to set END one greater than START.

 -- Function: put-range-table start end value range-table
     This function sets the value for range (START, END) to be VALUE in
     RANGE-TABLE.

     *NOTE*: Unless you are working with ranges that are closed at both
     ends, nothing will happen if START equals END.

 -- Function: remove-range-table start end range-table
     This function removes the value for range (START, END) in
     RANGE-TABLE.

 -- Function: clear-range-table range-table
     This function flushes RANGE-TABLE.

 -- Function: map-range-table function range-table
     This function maps FUNCTION over entries in RANGE-TABLE, calling
     it with three args, the beginning and end of the range and the
     corresponding value.


File: lispref.info,  Node: Databases,  Next: Processes,  Prev: Range Tables,  Up: Top

55 Databases
************

 -- Function: databasep object
     This function returns non-`nil' if OBJECT is a database.

* Menu:

* Connecting to a Database::
* Working With a Database::
* Other Database Functions::


File: lispref.info,  Node: Connecting to a Database,  Next: Working With a Database,  Prev: Databases,  Up: Databases

55.1 Connecting to a Database
=============================

 -- Function: open-database file &optional type subtype access mode
     This function opens database FILE, using database method TYPE and
     SUBTYPE, with access rights ACCESS and permissions MODE.  ACCESS
     can be any combination of `r' `w' and `+', for read, write, and
     creation flags.

     TYPE can have the value `'dbm' or `'berkeley-db' to select the
     type of database file to use.  (Note:  XEmacs may not support both
     of these types.)

     For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be
     `nil'.

     For a TYPE of `'berkeley-db', the following subtypes are
     available:  `'hash', `'btree', and `'recno'.  See the manpages for
     the Berkeley DB functions for more information about these types.

 -- Function: close-database database
     This function closes database DATABASE.

 -- Function: database-live-p object
     This function returns `t' if OBJECT is an active database, else
     `nil'.


File: lispref.info,  Node: Working With a Database,  Next: Other Database Functions,  Prev: Connecting to a Database,  Up: Databases

55.2 Working With a Database
============================

 -- Function: get-database key database &optional default
     This function finds the value for KEY in DATABASE.  If there is no
     corresponding value, DEFAULT is returned (`nil' if DEFAULT is
     omitted).

 -- Function: map-database function database
     This function maps FUNCTION over entries in DATABASE, calling it
     with two args, each key and value in the database.

 -- Function: put-database key value database &optional replace
     This function stores KEY and VALUE in DATABASE.  If optional
     fourth arg REPLACE is non-`nil', replace any existing entry in the
     database.

 -- Function: remove-database key database
     This function removes KEY from DATABASE.


File: lispref.info,  Node: Other Database Functions,  Prev: Working With a Database,  Up: Databases

55.3 Other Database Functions
=============================

 -- Function: database-file-name database
     This function returns the filename associated with DATABASE.

 -- Function: database-last-error &optional database
     This function returns the last error associated with DATABASE.

 -- Function: database-subtype database
     This function returns the subtype of DATABASE, if any.

 -- Function: database-type database
     This function returns the type of DATABASE.


File: lispref.info,  Node: Processes,  Next: System Interface,  Prev: Databases,  Up: Top

56 Processes
************

In the terminology of operating systems, a "process" is a space in
which a program can execute.  XEmacs runs in a process.  XEmacs Lisp
programs can invoke other programs in processes of their own.  These are
called "subprocesses" or "child processes" of the XEmacs process, which
is their "parent process".

   A subprocess of XEmacs may be "synchronous" or "asynchronous",
depending on how it is created.  When you create a synchronous
subprocess, the Lisp program waits for the subprocess to terminate
before continuing execution.  When you create an asynchronous
subprocess, it can run in parallel with the Lisp program.  This kind of
subprocess is represented within XEmacs by a Lisp object which is also
called a "process".  Lisp programs can use this object to communicate
with the subprocess or to control it.  For example, you can send
signals, obtain status information, receive output from the process, or
send input to it.

 -- Function: processp object
     This function returns `t' if OBJECT is a process, `nil' otherwise.

* Menu:

* Subprocess Creation::      Functions that start subprocesses.
* Synchronous Processes::    Details of using synchronous subprocesses.
* MS-DOS Subprocesses::      On MS-DOS, you must indicate text vs binary
                                for data sent to and from a subprocess.
* Asynchronous Processes::   Starting up an asynchronous subprocess.
* Deleting Processes::       Eliminating an asynchronous subprocess.
* Process Information::      Accessing run-status and other attributes.
* Input to Processes::       Sending input to an asynchronous subprocess.
* Signals to Processes::     Stopping, continuing or interrupting
                               an asynchronous subprocess.
* Output from Processes::    Collecting output from an asynchronous subprocess.
* Sentinels::                Sentinels run when process run-status changes.
* Process Window Size::      Changing the logical window size of a process.
* Transaction Queues::	     Transaction-based communication with subprocesses.
* Network::                  Opening network connections.


File: lispref.info,  Node: Subprocess Creation,  Next: Synchronous Processes,  Prev: Processes,  Up: Processes

56.1 Functions that Create Subprocesses
=======================================

There are three functions that create a new subprocess in which to run
a program.  One of them, `start-process', creates an asynchronous
process and returns a process object (*note Asynchronous Processes::).
The other two, `call-process' and `call-process-region', create a
synchronous process and do not return a process object (*note
Synchronous Processes::).

   Synchronous and asynchronous processes are explained in the following
sections.  Since the three functions are all called in a similar
fashion, their common arguments are described here.

   In all cases, the function's PROGRAM argument specifies the program
to be run.  An error is signaled if the file is not found or cannot be
executed.  If the file name is relative, the variable `exec-path'
contains a list of directories to search.  Emacs initializes
`exec-path' when it starts up, based on the value of the environment
variable `PATH'.  The standard file name constructs, `~', `.', and
`..', are interpreted as usual in `exec-path', but environment variable
substitutions (`$HOME', etc.) are not recognized; use
`substitute-in-file-name' to perform them (*note File Name Expansion::).

   Each of the subprocess-creating functions has a BUFFER-OR-NAME
argument which specifies where the standard output from the program will
go.  If BUFFER-OR-NAME is `nil', that says to discard the output unless
a filter function handles it.  (*Note Filter Functions::, and *Note
Read and Print::.)  Normally, you should avoid having multiple
processes send output to the same buffer because their output would be
intermixed randomly.

   All three of the subprocess-creating functions have a `&rest'
argument, ARGS.  The ARGS must all be strings, and they are supplied to
PROGRAM as separate command line arguments.  Wildcard characters and
other shell constructs are not allowed in these strings, since they are
passed directly to the specified program.

   *Please note:* The argument PROGRAM contains only the name of the
program; it may not contain any command-line arguments.  You must use
ARGS to provide those.

   If you want to use features of the shell, then invoke the shell
directly using, for example, PROGRAM of `"sh"', and ARGS of `"-c"' and
"COMMAND LINE...".

   The subprocess gets its current directory from the value of
`default-directory' (*note File Name Expansion::).

   The subprocess inherits its environment from XEmacs; but you can
specify overrides for it with `process-environment'.  *Note System
Environment::.

 -- Variable: exec-directory
     The value of this variable is the name of a directory (a string)
     that contains programs that come with XEmacs, that are intended
     for XEmacs to invoke.  The program `etags' is an example of such a
     program.

 -- User Option: exec-path
     The value of this variable is a list of directories to search for
     programs to run in subprocesses.  Each element is either the name
     of a directory (i.e., a string), or `nil', which stands for the
     default directory (which is the value of `default-directory').  

     The value of `exec-path' is used by `call-process' and
     `start-process' when the PROGRAM argument is not an absolute file
     name.

