@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1995, 1996 Ben Wing.
+@c Copyright (C) 2004 Free Software Foundation, Inc.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/glyphs.info
@node Glyphs, Annotations, Faces and Window-System Objects, top
@chapter Glyphs
@cindex glyphs
- A @dfn{glyph} is an object that is used for pixmaps, widgets and
+ A @dfn{glyph} is an object that is used for pixmaps, widgets, and
images of all sorts, as well as for things that ``act'' like pixmaps,
such as non-textual strings (@dfn{annotations}) displayed in a buffer or
in the margins. It is used in begin-glyphs and end-glyphs attached to
extents, marginal and textual annotations, overlay arrows
(@code{overlay-arrow-*} variables), toolbar buttons, mouse pointers,
frame icons, truncation and continuation markers, and the
-like. (Basically, any place there is an image or something that acts
-like an image, there will be a glyph object representing it.)
-
- The actual image that is displayed (as opposed to its position or
-clipping) is defined by an @dfn{image specifier} object contained
-within the glyph. The separation between an image specifier object
-and a glyph object is made because the glyph includes other properties
-than just the actual image: e.g. the face it is displayed in (for text
-images), the alignment of the image (when it is in a buffer), etc.
+like. Basically, any place there is an image or something that acts
+like an image, there will be a glyph object representing it.
@defun glyphp object
This function returns @code{t} if @var{object} is a glyph.
@end defun
@menu
-* Glyph Functions:: Functions for working with glyphs.
-* Images:: Graphical images displayed in a frame.
-* Glyph Types:: Each glyph has a particular type.
-* Mouse Pointer:: Controlling the mouse pointer.
-* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
-* Subwindows:: Inserting an externally-controlled subwindow
- into a buffer.
+* Glyph Intro:: Glyphs are abstract image specifications.
+* Images:: Specifying the appearance of glyphs.
+* Using Glyphs:: Creating and displaying glyphs.
+* Manipulating Glyphs:: Getting and setting glyph properties.
+* Glyph Examples:: Examples of how to work with glyphs.
@end menu
-@node Glyph Functions
-@section Glyph Functions
+
+@node Glyph Intro
+@section Glyph Introduction
+
+ In XEmacs, ``glyph'' does @strong{not} refer to a single unit of textual
+display (the XEmacs term for that is @dfn{rune}, and runes are confined
+to the internal implementation of redisplay), but rather is an
+object encapsulating a graphical element, such as an image or widget (an
+active GUI element such as a button or text entry field; X11 calls this a
+@dfn{widget}, while MS Windows uses the term @dfn{control}).
+This graphical element could appear in a buffer, a margin, a gutter, or
+a toolbar, or even externally to XEmacs as a mouse pointer or an icon,
+for example.
+
+ On the other hand, by contrast with GNU Emacs 21, an XEmacs glyph is
+not ``just'' an image. The actual image that is displayed (as opposed
+to its position or clipping) is defined by an ``image specifier'' object
+contained within the glyph. The separation between an image specifier
+object and a glyph object is made because the glyph includes other
+properties than just the actual image: e.g. the face it is displayed in,
+the alignment of the image, @emph{etc}. Also, an image specifier is
+used in at least one place in XEmacs in lieu of a glyph, namely the
+backing pixmap of a face.
+
+ An image specifier is used because glyphs often have locale-specific
+semantics. The most important example is semantics determined by the
+display device: you can't usefully display a JPEG on stdout, or a color
+image on a monochrome display. But because the image property is a
+specifier in XEmacs, you can specify that a given glyph appear as a
+monochrome image on monochrome displays, a color image on color
+displays, and as a string on TTYs. (Specifying a string for the
+@code{tty} device locale would give behavior like the @code{ALT}
+attribute of an @code{IMG} element in HTML.) Another is semantics
+determined by the buffer or mode. (Unfortunately, currently there are
+no compelling examples of this for glyphs.)
+
+ All this means that only one global glyph needs to exist for a
+particular purpose (e.g. the icon used to represent an iconified frame,
+the mouse pointer used over particular areas of a frame, etc.). Often
+you need not (and should not!) create your own glyph, but rather modify
+an existing one.
+
+ In working with glyphs it is important to keep in mind the distinction
+between a locale and a domain. A @dfn{locale} is specified by the
+programmer, and is an abstract link between a specification (for a
+glyph, its visual appearance) and a displayable object. The displayable
+object may be a buffer or a window, or an object containing buffers or
+windows such as frame, device, or console. A @dfn{domain} is an actual
+display context, which must be concrete enough to enable XEmacs to
+identify the device type. (Buffers may be displayed in windows on
+different devices, even simultaneously, so a buffer cannot be a domain.
+Similarly, the global locale cannot be a domain.) @ref{Specifiers}, for
+more information about specifier locales and domains.
+
+
+@node Images
+@section Images
@menu
-* Creating Glyphs:: Creating new glyphs.
-* Glyph Properties:: Accessing and modifying a glyph's properties.
-* Glyph Convenience Functions::
- Convenience functions for accessing particular
- properties of a glyph.
-* Glyph Dimensions:: Determining the height, width, etc. of a glyph.
+* Image Specifiers:: Specifying an image's appearance.
+* Image Instantiator Conversion:: Lazy realization of graphics.
+* Image Instantiator Formats:: A catalog of image descriptors.
+* Image Instances:: Classes of graphical objects.
@end menu
-@node Creating Glyphs
-@subsection Creating Glyphs
-@defun make-glyph &optional spec-list type
-This function creates a new glyph object of type @var{type}.
+@node Image Specifiers
+@subsection Image Specifiers
+@cindex image specifiers
-@var{spec-list} is used to initialize the glyph's image. It is
-typically an image instantiator (a string or a vector; @ref{Image
-Specifiers}), but can also be a list of such instantiators (each one in
-turn is tried until an image is successfully produced), a cons of a
-locale (frame, buffer, etc.) and an instantiator, a list of such conses,
-or any other form accepted by @code{canonicalize-spec-list}.
-@xref{Specifiers}, for more information about specifiers.
-
-@var{type} specifies the type of the glyph, which specifies in which
-contexts the glyph can be used, and controls the allowable image types
-into which the glyph's image can be instantiated. @var{type} should be
-one of @code{buffer} (used for glyphs in an extent, the modeline, the
-toolbar, or elsewhere in a buffer), @code{pointer} (used for the
-mouse-pointer), or @code{icon} (used for a frame's icon), and defaults
-to @code{buffer}. @xref{Glyph Types}.
-
-A glyph in XEmacs does @strong{NOT} refer to a single unit of textual
-display (the XEmacs term for this is @dfn{rune}), but rather is an
-object encapsulating a graphical element, such as an image or widget (an
-element such as a button or text field; @dfn{widget} is the term for
-this under X Windows, and it's called a @dfn{control} under MS Windows).
-This graphical element could appear in a buffer, a margin, a gutter, or
-a toolbar, or as a mouse pointer or an icon, for example.
+ An image specifier is a description of the actual graphical
+realization of a glyph. For example, a typical image description is
+@emph{the file system path to a PNG file}. Since redisplay doesn't know
+about files, and in any case the image may need to be manipulated
+(@emph{e.g.}, a face's background pixmap must be clipped and tiled), the
+PNG file must be converted internally to a window system bitmap or
+pixmap object. We describe this process by writing that when XEmacs
+displays the image, it @dfn{instantiates} the @dfn{image instantiator}
+into an @dfn{image instance}. Image instances are an internal object
+type (similar to font instances and color instances), describing how the
+image appears in a particular domain. On the other hand, image
+instantiators, which are just descriptions of how the image should
+appear, are represented using Lisp strings or vectors.
+
+Furthermore the graphical realization will vary, and for some devices
+may not even be a bitmapped graphic. These variations may be controlled
+by the program by specifying different @dfn{image instantiators} in
+different locales. This is implemented with an @dfn{image specifier},
+a specifier whose specifications are image instantiators.
+
+Image specifiers are rarely if ever found by themselves. However, an
+image specifier results from calling @code{glyph-image} on a glyph, or
+retrieving the @code{background-pixmap} property of a face, and you can
+check if some random object is an image specifier.
-Creating a glyph using @code{make-glyph} does not specify @emph{where}
-the glyph will be used, but it does specify @emph{what} the glyph will
-look like. In particular, SPEC-LIST is used to specify this, and it's
-used to initialize the glyph's @code{image} property, which is an image
-specifier. (Note that @dfn{image} as used in the context of a glyph's
-@code{image} property or in the terms @dfn{image specifier}, @dfn{image
-instantiator}, or @dfn{image instance} does not refer to what people
-normally think of as an image (which in XEmacs is called a
-@dfn{pixmap}), but to any graphical element---a pixmap, a widget, or
-even a block of text, when used in the places that call for a glyph.)
-The format of the SPEC-LIST is typically an image instantiator (a string
-or a vector; @ref{Image Specifiers}), but can also be a list of such
-instantiators (each one in turn is tried until an image is successfully
-produced), a cons of a locale (frame, buffer, etc.) and an
-instantiator, a list of such conses, or any other form accepted by
-@code{canonicalize-spec-list}. @xref{Specifiers}, for more information
-about specifiers.
-
-If you're not familiar with specifiers, you should be in order to
-understand how glyphs work. The clearest introduction to specifiers
-is in the Lispref manual, available under Info. (Choose
-Help->Info->Info Contents on the menubar or type C-h i.) You can
-also see @code{make-specifier} for a capsule summary. What's important to
-keep in mind is that a specifier lets you set a different value for
-any particular buffer, window, frame, device, or console. This allows
-for a great deal of flexibility; in particular, only one global glyph
-needs to exist for a particular purpose (e.g. the icon used to represent
-an iconified frame, the mouse pointer used over particular areas of a
-frame, etc.), and in these cases you do not create your own glyph, but
-rather modify the existing one.
+@defun image-specifier-p object
+This function returns non-@code{nil} if @var{object} is an image specifier.
+@end defun
-As well as using @var{spec-list} to initialize the glyph, you can set
-specifications using @code{set-glyph-image}. Note that, due to a
-possibly questionable historical design decision, a glyph itself is not
-actually a specifier, but rather is an object containing an image
-specifier (as well as other, seldom-used properties). Therefore, you
-cannot set or access specifications for the glyph's image by directly
-using @code{set-specifier}, @code{specifier-instance} or the like on the
-glyph; instead use them on @code{(glyph-image @var{glyph})} or use the
-convenience functions @code{set-glyph-image},
-@code{glyph-image-instance}, and @code{glyph-image}.
+@defun make-image-specifier spec-list
+This function creates a new image specifier object and initializes it
+according to @var{spec-list}. @xref{Specifiers}.
+@end defun
-Once you have created a glyph, you specify where it will be used as
-follows:
+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.
-@itemize @bullet
-@item
-To insert a glyph into a buffer, create an extent in the buffer and then
-use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
-a glyph to be displayed at the corresponding edge of the extent. (It is
-common to create zero-width extents for this purpose.)
+Image instantiators come in many formats: @code{xbm}, @code{xpm},
+@code{gif}, @code{jpeg}, etc. These denote the format of the data
+describing the image. The resulting image instances also come in many
+types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
+@code{pointer}, etc. This refers to the behavior of the image and the
+sorts of places it can appear. (For example, a color-pixmap image has
+fixed colors specified for it, while a mono-pixmap image comes in two
+unspecified shades ``foreground'' and ``background'' that are determined
+from the face of the glyph or surrounding text; a text image appears as
+a string of text and has an unspecified foreground, background, and
+font; a pointer image behaves like a mono-pixmap image but can only be
+used as a mouse pointer [mono-pixmap images cannot be used as mouse
+pointers]; etc.)
-@item
-To insert a glyph into the left or right margin of a buffer, first
-make sure the margin is visible by setting a value for the specifiers
-@code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
-when using margin glyphs with layout policy @code{whitespace}.) Then follow
-the same procedure above for inserting a glyph in a buffer, and then
-set a non-default layout policy for the glyph using
-@code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
-Alternatively, use the high-level annotations API (see
-@code{make-annotation}). (In point of fact, you can also use the annotations
-API for glyphs in a buffer, by setting a layout policy of @code{text}.)
+It is important to keep the distinction between image instantiator
+format and image instance type in mind. Typically, a given image
+instantiator format can result in many different image instance types.
+For example, @code{xpm} can be instanced as @code{color-pixmap},
+@code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
+instanced only as @code{pointer}. On the other hand, a particular image
+instance type can be generated by many different image instantiator
+formats (e.g. @code{color-pixmap} can be generated by @code{xpm},
+@code{gif}, @code{jpeg}, etc.).
-@item
-To insert a glyph into the modeline, just put the glyph directly as one
-of the modeline elements. (Unfortunately you can't currently put a begin
-glyph or end glyph on one of the modeline extents---they're ignored.)
+ @xref{Image Instances}, for a more detailed discussion of image
+instance types.
-@item
-To insert a glyph into a toolbar, specify it as part of a toolbar
-instantiator (typically set on the specifier @code{default-toolbar}).
-See @code{default-toolbar} for more information. (Note that it is
-standard practice to use a symbol in place of the glyph list in the
-toolbar 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 @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
-and then calling @code{(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.
+ An image instantiator should be a string or a vector of the form
-@item
-To insert a glyph into a gutter, create or modify a gutter instantiator
-(typically set on the specifier @code{default-gutter}). Gutter
-instantiators consist of strings or lists of strings, so to insert a
-glyph, create an extent over the string, and use
-@code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
-glyph to be displayed at the corresponding edge of the extent, just like
-for glyphs in a buffer.
+@example
+ @code{[@var{format} @var{:keyword} @var{value} ...]}
+@end example
-@item
-To use a glyph as the icon for a frame, you do not actually create a new
-glyph; rather, you change the specifications for the existing glyph
-@code{frame-icon-glyph}. (Remember that, because of the specifier nature
-of glyphs, you can set different values for any particular buffer or
-frame.)
+i.e. a format symbol followed by zero or more alternating keyword-value
+pairs.
-@item
-To use a glyph as the mouse pointer, in general you do not create a new
-glyph, but rather you change the specifications of various existing
-glyphs, such as @code{text-pointer-glyph} for the pointer used over
-text, @code{modeline-pointer-glyph} for the pointer used over the
-modeline, etc. Do an apropos over @code{*-pointer-glyph} to find all of
-them. (Note also that you can temporarily set the mouse pointer to some
-specific shape by using @code{set-frame-pointer}, which takes an image
-instace, as obtained from calling @code{glyph-image-instance} on a glyph
-of type @code{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 @code{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 @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
-really want to get low-level.)
+The form of an instantiator can be checked with
+@code{valid-instantiator-p} with a @var{TYPE} of @code{image},
+@ref{Specifier Validation Functions}.
-@item
-To use a glyph to control the shape of miscellaneous redisplay effects
-such as the truncation and continuation markers, set the appropriate
-existing glyph variables, as for icons and pointers above. See
-@code{continuation-glyph}, @code{control-arrow-glyph},
-@code{hscroll-glyph}, @code{invisible-text-glyph},
-@code{octal-escape-glyph}, and @code{truncation-glyph}. See also
-@code{overlay-arrow-string}, an odd redisplay leftover which can be set
-to a glyph you created, and will cause the glyph to be displayed on top
-of the text position specified in the marker stored in
-@code{overlay-arrow-position}.
+For a complete list of the format symbols and their usage,
+@ref{Image Instantiator Formats}.
-@item
-To use a glyph in a display table (i.e. to control the appearance of any
-individual character), create the appropriate character glyphs and then
-set a specification for the specifier @code{current-display-table},
-which controls the appearance of characters. You can also set an
-overriding display table for use with text displayed in a particular
-face; see @code{set-face-display-table} and @code{make-display-table}.
-#### Note: Display tables do not currently support general Mule
-characters. They will be overhauled at some point to support this
-and to provide other features required under Mule.
+If the instantiator is a string, it will be converted into a vector by
+looking it up according to the specs in the
+@code{console-type-image-conversion-list} for the console type of the
+domain (usually a window; sometimes a frame or device) over which the
+image is being instantiated.
-@item
-To use a glyph as the background pixmap of a face: Note that 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. Similarly to how the glyph's image specifier works, you don't
-create your own image specifier, but rather add specifications to the
-existing one (using @code{set-face-background-pixmap}). Note that the
-image instance that is generated in order to actually display the
-background pixmap is of type @code{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.
-@end itemize
+If the instantiator specifies data from a file, the data will be read in
+at the time that the instantiator is added to the image specifier (which
+may be well before the image is actually displayed), and the
+instantiator will be converted into one of the inline-data forms, with
+the filename retained using a @code{:file} keyword. This implies that
+the file must exist when the instantiator is added to the image, but
+does not need to exist at any other time (e.g. it may safely be a
+temporary file).
-It is extremely rare that you will ever have to specify a value for
-TYPE, which should be one of @code{buffer} (used for glyphs in an
-extent, the modeline, the toolbar, or elsewhere in a buffer),
-@code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
-frame's icon), and defaults to @code{buffer}. The only cases where it
-needs to be specified is when creating icon or pointer glyphs, and in
-both cases the necessary glyphs have already been created at startup and
-are accessed through the appropriate variables,
-e.g. @code{text-pointer-glyph} (or in general, @code{*-pointer-glyph})
-and @code{frame-icon-glyph}. @xref{Glyph Types}.
+The available keywords are given below. Note that some keywords are
+generally available (for example, the @code{:data} keyword may be used
+with any format except @code{nothing}), while others are only available
+for one format (@code{resource-id} is unique to the
+@code{mswindows-resource} format).
+
+@table @code
+@item :data
+Inline image data. If available for a given format, it may be specified
+directly by the program, or it may be a cache of file data previously
+read. When present, it is used to instantiate the image in preference
+to the file named by the @code{:file} property.
+
+The format of inline data is image-format-specific. For example, in
+pixmap formats, the value should be a string, which is interpreted as an
+octet-stream representing a bitmap or pixmap. But for text formats,
+it's string containing the text to be displayed, and for resource
+formats, it's a string containing the name of the resource.
+
+@item :file
+Data contained in a file. The value is the name of this file. If both
+@code{:data} and @code{:file} are specified, the image is created from
+what is specified in @code{:data} and the string in @code{:file} becomes
+the value of the @code{image-instance-file-name} function when applied
+to the resulting image-instance. Note that there is nothing to stop a
+program from changing either the @code{:file} or the @code{:data}
+property, and there is no way to detect such mischief. This means that
+the data will @emph{not} be automatically reread if you change the
+@code{file} property; you must force it by removing the @code{:data}
+property.
+@c #### If there are ways to do this in-place, describe them.
+(One way to do this is replacing the whole specification with a new
+vector.) This keyword is not valid for instantiator formats
+@code{nothing}, @code{string}, @code{formatted-string},
+@code{cursor-font}, @code{font}, and @code{autodetect}.
+
+@item :mask-data
+Inline data for @code{xbm} and @code{xface}. This specifies a mask to
+be used with the bitmap. Pixels which are not set in the mask will not
+be written to the imaging device. The format is a list of width,
+height, and bits, as for @code{:data}.
+
+@item :mask-file
+For @code{xbm} and @code{xface}. This specifies a file containing the
+mask data. If neither a mask file nor inline mask data is given for an
+XBM image, and the XBM image comes from a file, XEmacs will look for a
+mask file with the same name as the image file but with @samp{Mask} or
+@samp{msk} appended. For example, if you specify the XBM file
+@file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
+the associated mask file @file{left_ptrmsk} will automatically be picked
+up.
+
+@item :resource-id
+Only for @code{mswindows-resource}. This must be either an integer
+(which directly specifies a resource number) or a string. See the
+description of @code{mswindows-resource} for valid strings. @xref{Image
+Instantiator Formats}.
+
+@item :foreground
+@itemx :background
+For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
+These keywords allow you to explicitly specify foreground and background
+colors. The value should be anything acceptable to
+@code{make-color-instance}. This will cause an external format that
+would by default be instantiated as a @code{mono-pixmap} to instead be
+instantiated as a two-color color-pixmap. This can be used to override
+the colors specified by a glyph's face, for example. If the image is
+instantiated as a pointer, they specify its foreground and/or
+background, instead of the defaults of black and white.
+
+@item :hotspot-x
+@itemx :hotspot-y
+For @code{xbm} and @code{xface}. These keywords specify a hotspot if
+the image is instantiated as a @code{pointer}. Note that if the XBM
+image file specifies a hotspot, it will automatically be picked up if no
+explicit hotspot is given.
+
+@item :color-symbols
+Only for @code{xpm}. This specifies an alist that maps strings that
+specify symbolic color names to the actual color to be used for that
+symbolic color (in the form of a string or a color-specifier object).
+If this is not specified, the contents of @code{xpm-color-symbols} are
+used to generate the alist.
+
+@item :resource-type
+Only for @code{mswindows-resource}. This must be a symbol, either
+@code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
+resource to be retrieved.
+
+@item :face
+For @code{inherit} and the widget formats. This specifies the face to
+inherit from. For widgets this specifies the face to use for display.
+It defaults to gui-element-face.
+
+@item :selected
+@itemx :active
+@itemx :suffix
+@itemx :keys
+@itemx :style
+@itemx :filter
+@itemx :config
+@itemx :included
+@itemx :key-sequence
+@itemx :accelerator
+@itemx :label
+@itemx :callback
+These keywords, accepted as menu item specs, are also accepted by images
+instantiated as @code{widget}. For their semantics, @ref{Menu Format}.
+@end table
+
+
+@node Image Instantiator Conversion
+@subsection Image Instantiator Conversion
+@cindex image instantiator conversion
+@cindex conversion of image instantiators
+
+Conversion is applied to image instantiators at the time they are added
+to an image specifier or at the time they are passed to
+@code{make-image-instance}.
+
+@defun set-console-type-image-conversion-list console-type list
+This function sets the image-conversion-list for consoles of the given
+@var{console-type}. The image-conversion-list specifies how image
+instantiators that are strings should be interpreted. Each element of
+the list should be a list of two elements (a regular expression string
+and a vector) or a list of three elements (the preceding two plus an
+integer index into the vector). The string is converted to the vector
+associated with the first matching regular expression. If a vector
+index is specified, the string itself is substituted into that position
+in the vector.
+
+Note: The conversion above is applied when the image instantiator is
+added to an image specifier, not when the specifier is actually
+instantiated. Therefore, changing the image-conversion-list only affects
+newly-added instantiators. Existing instantiators in glyphs and image
+specifiers will not be affected.
@end defun
-@defun make-glyph-internal &optional type
-This function creates a new, uninitialized glyph of type @var{type}.
+@defun console-type-image-conversion-list console-type
+This function returns the image-conversion-list for consoles of the given
+@var{console-type}.
@end defun
-@defun make-pointer-glyph &optional spec-list
-Return a new @code{pointer-glyph} object with the specification list
-@var{spec-list}. This function is equivalent to calling
-@code{make-glyph} with a @var{type} of @code{pointer}.
+@node Image Instantiator Formats
+@subsection Image Instantiator Formats
+@cindex image instantiator formats
-It is extremely unlikely that you will ever need to create a pointer
-glyph. Instead, you probably want to be calling @code{set-glyph-image}
-on an existing glyph, e.g. @code{text-pointer-glyph}.
-@end defun
+The @dfn{format} field of an image instantiator should be a symbol
+denoting a valid format. Which formats are valid will depend on the
+features (such as image decoding libraries) available, on platform
+support (MS Windows resource IDs make no sense on other platforms), and
+on the locale.
-@defun make-icon-glyph &optional spec-list
+@defun valid-image-instantiator-format-p format &optional locale
+This function returns non-@code{nil} if @var{format} is a valid image
+instantiator format.
-Return a new @code{pointer-glyph} object with the specification list
-@var{spec-list}. This function is equivalent to calling
-@code{make-glyph} with a @var{type} of @code{icon}.
+If @var{locale} is non-@code{nil} then the format is checked in that locale.
+If @var{locale} is @code{nil} the current console is used.
-It is extremely unlikely that you will ever need to create a pointer
-glyph. Instead, you probably want to be calling @code{set-glyph-image}
-on an existing glyph, e.g. @code{text-pointer-glyph}.
+Note that the return value for many formats listed above depends on
+whether XEmacs was compiled with support for that format.
@end defun
-@node Glyph Properties
-@subsection Glyph Properties
+@defun image-instantiator-format-list
+This function returns a list of valid image-instantiator formats.
+@end defun
-Each glyph has a list of properties, which control all of the aspects of
-the glyph's appearance. The following symbols have predefined meanings:
+Here is a table of image-instantiator formats, giving the keywords that
+are usable with each, and the kinds of instances that may result.
@table @code
-@item image
-The image used to display the glyph.
+@item nothing
+Don't display anything; no keywords are valid for this format. Can only be
+instanced as @code{nothing}.
-@item baseline
-Percent above baseline that glyph is to be displayed. Only for glyphs
-displayed inside of a buffer.
+@item string
+Display this image as a text string. Can only be instanced
+as @code{text}, although support for instancing as @code{mono-pixmap}
+should be added. The valid keyword is @code{:data}. The value should
+be a string, and it is interpreted as a string of characters.
-@item contrib-p
-Whether the glyph contributes to the height of the line it's on.
-Only for glyphs displayed inside of a buffer.
+@item formatted-string
+Display this image as a text string with replaceable fields,
+similar to a modeline format string. The valid keyword is @code{:data}.
+The value should be a string, and it is interpreted as a string of
+characters containing format sequences.
-@item face
-Face of this glyph (@emph{not} a specifier).
+Not currently implemented.
+
+@item xbm
+An X bitmap; available only if X support was compiled into this XEmacs.
+
+If used in a buffer glyph, icon glyph, or face background pixmap, it
+will be instantiated as @code{mono-pixmap} unless the @code{:foreground}
+or @code{:background} keywords are present. In the latter case it will
+be instantiated as @code{color-pixmap} with the two specified colors.
+@c #### Check this.
+(Probably if @code{:foreground} or @code{:background} is omitted, it
+defaults to black or white respectively.) If used in a pointer glyph,
+it will be instantiated as an @code{pointer}.
+
+The valid keywords and their values are
+@table @code
+@item :data
+A list containing the height and width of the bitmap as integers, and
+a string interpreted as a bit vector according to the X11 standard XBM
+bitmap format, in that order.
+@item :file
+The name of a file containing standard XBM-format data. If it contains
+a hotspot specification, it will be parsed and used if the hotspot is
+not explicitly specified.
+@item :mask-data
+A list containing the height and width of the bitmap as integers, and
+a string interpreted as a bit vector according to the X11 standard XBM
+bitmap format, in that order. This bitmap is interpreted as the
+clipping region for the bitmap contained in the @code{:data} property.
+@item :mask-file
+The name of a file containing standard XBM-format data. Interpreted as
+the clipping region for the bitmap contained in the @code{:data} property.
+@item :foreground
+@itemx :background
+These keywords allow you to explicitly specify foreground and background
+colors. The values should be acceptable to @code{make-color-instance}.
+@item :hotspot-x
+@itemx :hotspot-y
+Integers denoting the hotspot (mouse pointer position), with (0,0) at
+the top left corner. If given, these override any specification in the
+XBM file.
@end table
-@defun set-glyph-property glyph property value &optional locale tag-set how-to-add
-This function changes a property of a @var{glyph}.
+@item xpm
+An XPM pixmap; only available if XPM support was compiled into this XEmacs.
-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.
+Can be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
+@code{pointer}.
-If @var{property} is a built-in property, the specifications to be added
-to this property can be supplied in many different ways:
+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.
-@itemize @bullet
-@item
-If @var{value} is a simple instantiator (e.g. a string naming a pixmap
-filename) or a list of instantiators, then the instantiator(s) will be
-added as a specification of the property for the given @var{locale}
-(which defaults to @code{global} if omitted).
+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.
-@item
-If @var{value} is a list of specifications (each of which is a cons of a
-locale and a list of instantiators), then @var{locale} must be
-@code{nil} (it does not make sense to explicitly specify a locale in
-this case), and specifications will be added as given.
+The valid keywords and their values are
+@table @code
+@item :data
+A string interpreted as the contents of a standard XPM file.
+@item :file
+The name of a file containing standard XPM-format data. If it contains
+a hotspot specification, it will be parsed and used if the hotspot is
+not explicitly specified.
+@c #### Does XPM provide for a hotspot?
+@item :hotspot-x
+@itemx :hotspot-y
+Integers denoting the hotspot (mouse pointer position), with (0,0) at
+the top left corner. If given, these override any specification in the
+XBM file.
+@c #### Check this.
+(This may not be true. The original documentation doesn't mention them
+in connection with XPM, but a pointer needs a hotspot.)
+@item :color-symbols
+An alist that maps the one- or two-character strings that specify
+symbolic color names in the XPM file to the actual color to be used for
+that symbolic color (in the form of a string acceptable as a color
+instantiator, @ref{Color Specifiers}, or a color-specifier object).
+If this is not specified, the contents of @code{xpm-color-symbols} are
+used to generate the alist.
+@end table
-@item
-If @var{value} is a specifier (as would be returned by
-@code{glyph-property} if no @var{locale} argument is given), then some
-or all of the specifications in the specifier will be added to the
-property. In this case, the function is really equivalent to
-@code{copy-specifier} and @var{locale} has the same semantics (if it is
-a particular locale, the specification for the locale will be copied; if
-a locale type, specifications for all locales of that type will be
-copied; if @code{nil} or @code{all}, then all specifications will be
-copied).
-@end itemize
+@item xface
+An X-Face bitmap, used to encode people's faces in e-mail messages;
+only available if X-Face support was compiled into this XEmacs.
-@var{how-to-add} should be either @code{nil} or one of the symbols
-@code{prepend}, @code{append}, @code{remove-tag-set-prepend},
-@code{remove-tag-set-append}, @code{remove-locale},
-@code{remove-locale-type}, or @code{remove-all}. See
-@code{copy-specifier} and @code{add-spec-to-specifier} for a description
-of what each of these means. Most of the time, you do not need to worry
-about this argument; the default behavior usually is fine.
+Will be instanced as @code{mono-pixmap}, @code{color-pixmap}, or
+@code{pointer}, depending on the target instance type and the presence
+of color keywords.
-In general, it is OK to pass an instance object (e.g. as returned by
-@code{glyph-property-instance}) as an instantiator in place of an actual
-instantiator. In such a case, the instantiator used to create that
-instance object will be used (for example, if you set a font-instance
-object as the value of the @code{font} property, then the font name used
-to create that object will be used instead). If some cases, however,
-doing this conversion does not make sense, and this will be noted in the
-documentation for particular types of instance objects.
+The valid keywords and their values are
+@table @code
+@item :data
+A list containing the height and width of the bitmap as integers, and
+a string interpreted as a bit vector according to the X11 standard XBM
+bitmap format, in that order.
+@item :file
+The name of a file containing standard XBM-format data. If it contains
+a hotspot specification, it will be parsed and used if the hotspot is
+not explicitly specified.
+@item :mask-data
+A list containing the height and width of the bitmap as integers, and
+a string interpreted as a bit vector according to the X11 standard XBM
+bitmap format, in that order. This bitmap is interpreted as the
+clipping region for the bitmap contained in the @code{:data} property.
+@item :mask-file
+The name of a file containing standard XBM-format data. Interpreted as
+the clipping region for the bitmap contained in the @code{:data} property.
+@item :foreground
+@itemx :background
+These keywords allow you to explicitly specify foreground and background
+colors. The values should be acceptable to @code{make-color-instance}.
+@item :hotspot-x
+@itemx :hotspot-y
+Integers denoting the hotspot (mouse pointer position), with (0,0) at
+the top left corner. If given, these override any specification in the
+XBM file.
+@end table
-If @var{property} is not a built-in property, then this function will
-simply set its value if @var{locale} is @code{nil}. However, if
-@var{locale} is given, then this function will attempt to add
-@var{value} as the instantiator for the given @var{locale}, using
-@code{add-spec-to-specifier}. If the value of the property is not a
-specifier, it will automatically be converted into a @code{generic}
-specifier.
-@end defun
+@item gif
+@itemx jpeg
+@itemx png
+@itemx tiff
+These are GIF87- or GIF89-format, JPEG-format, PNG/GIF24-format, and
+TIFF-format images, respectively. They are available only if
+appropriate decoding support was built into XEmacs. XEmacs includes GIF
+decoding functions as a standard part of it, so if you have X support,
+you will normally have GIF support, unless you explicitly disable it at
+configure time. If you have development support (both the libraries and
+the relevant C header files) available when XEmacs is built, the JPEG,
+PNG, and TIFF libraries will automatically be detected (in the ``usual
+places'') and linked into the build.
+
+Note that PNG is the standard format for images distributed with XEmacs,
+so it is highly recommended that PNG support be built in.
+
+All of these instantiators will be instanced as @code{color-pixmap}.
+
+The valid keywords and their values are
+@table @code
+@item :data
+A string interpreted as the contents of a file containing data in the
+appropriate standard format.
+@item :file
+The name of a file containing standard-format data.
+@end table
-@defun glyph-property glyph property &optional locale
-This function returns @var{glyph}'s value of the given @var{property}.
+@item cursor-font
+Most window systems provide a set of standard cursors, which in X11 is
+called a cursor font. Can only be instanced as @code{pointer}. This
+should probably be fixed.
+
+The valid keyword is @code{:data}. Its value should be a string
+containing one of the standard cursor-font names, such as @samp{watch}
+or @samp{right_ptr} under X. More specifically, in the X Window System
+it may be any of the standard cursor names from appendix B of the Xlib
+manual, provided in the file @file{<X11/cursorfont.h>} by most
+distributions, minus the @samp{XC_} prefix. For MS Windows, use
+@code{mswindows-resource} instantiator format, not @code{cursor-font}.
+Other window systems may have different lists.
-If @var{locale} is omitted, the @var{glyph}'s actual value for
-@var{property} will be returned. For built-in properties, this will be
-a specifier object of a type appropriate to the property (e.g. a font or
-color specifier). For other properties, this could be anything.
+@item font
+A glyph from a font; i.e. the name of a font, and glyph index into it
+of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
+Only if X support was compiled into this XEmacs. Currently can only be
+instanced as @code{pointer}. This should probably be fixed.
+@c #### The above description is not very helpful, so it's not obvious
+@c how to instantiate a font image.
-If @var{locale} is supplied, then instead of returning the actual value,
-the specification(s) for the given locale or locale type will be
-returned. This will only work if the actual value of @var{property} is
-a specifier (this will always be the case for built-in properties, but
-may or may not apply to user-defined properties). If the actual value
-of @var{property} is not a specifier, this value will simply be returned
-regardless of @var{locale}.
+@item mswindows-resource
+An MS Windows pointer resource. Specifies a resource to retrieve
+directly from the system (an OEM resource) or from a file, particularly
+an executable file. Can be instanced as @code{pointer} or
+@code{color-pixmap}.
-The return value will be a list of instantiators (e.g. vectors
-specifying pixmap data), or a list of specifications, each of which is a
-cons of a locale and a list of instantiators. Specifically, if
-@var{locale} is a particular locale (a buffer, window, frame, device, or
-@code{global}), a list of instantiators for that locale will be
-returned. Otherwise, if @var{locale} is a locale type (one of the
-symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
-the specifications for all locales of that type will be returned.
-Finally, if @var{locale} is @code{all}, the specifications for all
-locales of all types will be returned.
+The valid keywords and their values are
-The specifications in a specifier determine what the value of
-@var{property} will be in a particular @dfn{domain} or set of
-circumstances, which is typically a particular Emacs window along with
-the buffer it contains and the frame and device it lies within. The
-value is derived from the instantiator associated with the most specific
-locale (in the order buffer, window, frame, device, and @code{global})
-that matches the domain in question. In other words, given a domain
-(i.e. an Emacs window, usually), the specifier for @var{property} will
-first be searched for a specification whose locale is the buffer
-contained within that window; then for a specification whose locale is
-the window itself; then for a specification whose locale is the frame
-that the window is contained within; etc. The first instantiator that
-is valid for the domain (usually this means that the instantiator is
-recognized by the device [i.e. the X server or TTY device] that the
-domain is on). The function @code{glyph-property-instance} actually does
-all this, and is used to determine how to display the glyph.
-@end defun
+@table @code
+@item :resource-type
+A string naming the type (@code{cursor}, @code{bitmap}, or @code{icon})
+of the resource. Required.
+@item :file
+A string containing the name of the file containing the resource (often
+an executable). If a system resource, @code{:file} should be omitted.
+@item :resource-id
+A string containing the name of a resource. Required if @code{:file}
+is not specified.
-@defun glyph-property-instance glyph property &optional domain default no-fallback
-This function returns the instance of @var{glyph}'s @var{property} in the
-specified @var{domain}.
+This must be either an integer (which directly specifies a resource
+number) or a string. Valid strings are
-Under most circumstances, @var{domain} will be a particular window, and
-the returned instance describes how the specified property actually is
-displayed for that window and the particular buffer in it. Note that
-this may not be the same as how the property appears when the buffer is
-displayed in a different window or frame, or how the property appears in
-the same window if you switch to another buffer in that window; and in
-those cases, the returned instance would be different.
+For bitmaps:
-The returned instance is an image-instance object, and you can query it
-using the appropriate image instance functions. For example, you could use
-@code{image-instance-depth} to find out the depth (number of color
-planes) of a pixmap displayed in a particular window. The results might
-be different from the results you would get for another window (perhaps
-the user specified a different image for the frame that window is on; or
-perhaps the same image was specified but the window is on a different X
-server, and that X server has different color capabilities from this
-one).
+"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".
-@var{domain} defaults to the selected window if omitted.
+For cursors:
-@var{domain} can be a frame or device, instead of a window. The value
-returned for such a domain is used in special circumstances when a
-more specific domain does not apply; for example, a frame value might be
-used for coloring a toolbar, which is conceptually attached to a frame
-rather than a particular window. The value is also useful in
-determining what the value would be for a particular window within the
-frame or device, if it is not overridden by a more specific
-specification.
+"normal", "ibeam", "wait", "cross", "up", "sizenwse",
+"sizenesw", "sizewe", "sizens", "sizeall", and "no".
-If @var{property} does not name a built-in property, its value will
-simply be returned unless it is a specifier object, in which case it
-will be instanced using @code{specifier-instance}.
+For icons:
-Optional arguments @var{default} and @var{no-fallback} are the same as
-in @code{specifier-instance}. @xref{Specifiers}.
-@end defun
+"sample", "hand", "ques", "bang", "note", and "winlogo".
+@end table
-@defun remove-glyph-property glyph property &optional locale tag-set exact-p
-This function removes a property from a glyph. For built-in properties,
-this is analogous to @code{remove-specifier}. @xref{Specifiers,
-remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
-and @var{exact-p} arguments.
-@end defun
+@item subwindow
+An embedded windowing system window. Can only be instanced as
+@code{subwindow}. Not implemented.
+@c #### Check status of subwindows ... I thought Andy implemented them.
-@node Glyph Convenience Functions
-@subsection Glyph Convenience Functions
+@item button
+A button widget; either a push button, radio button or toggle button.
+Can only be instanced as @code{widget}.
- The following functions are provided for working with specific
-properties of a glyph. Note that these are exactly like calling
-the general functions described above and passing in the
-appropriate value for @var{property}.
+@item combo-box
+A drop list of selectable items in a widget, for editing text.
+Can only be instanced as @code{widget}.
- Remember that if you want to determine the ``value'' of a
-specific glyph property, you probably want to use the @code{*-instance}
-functions. For example, to determine whether a glyph contributes
-to its line height, use @code{glyph-contrib-p-instance}, not
-@code{glyph-contrib-p}. (The latter will return a boolean specifier
-or a list of specifications, and you probably aren't concerned with
-these.)
+@item edit-field
+A text editing widget. Can only be instanced as @code{widget}.
-@defun glyph-image glyph &optional locale
-This function is equivalent to calling @code{glyph-property} with
-a property of @code{image}. The return value will be an image
-specifier if @var{locale} is @code{nil} or omitted; otherwise,
-it will be a specification or list of specifications.
-@end defun
+@item label
+A static, text-only, widget; for displaying text. Can only be instanced
+as @code{widget}.
-@defun set-glyph-image glyph spec &optional locale tag-set how-to-add
-This function is equivalent to calling @code{set-glyph-property} with
-a property of @code{image}.
-@end defun
+@item layout
+A widget for controlling the positioning of children underneath it.
+Through the use of nested layouts, a widget hierarchy can be created
+which can have the appearance of any standard dialog box or similar
+arrangement; all of this is counted as one @dfn{glyph} and could appear
+in many of the places that expect a single glyph. Can only be instanced
+as @code{widget}.
-@defun glyph-image-instance glyph &optional domain default no-fallback
-This function returns the instance of @var{glyph}'s image in the given
-@var{domain}, and is equivalent to calling
-@code{glyph-property-instance} with a property of @code{image}. The
-return value will be an image instance.
+@item native-layout
+The native version of a layout widget.
+Can only be instanced as @code{widget}.
-Normally @var{domain} will be a window or @code{nil} (meaning the
-selected window), and an instance object describing how the image
-appears in that particular window and buffer will be returned.
-@end defun
+@item progress-gauge
+A sliding widget, for showing progress. Can only be instanced as
+@code{widget}.
-@defun glyph-contrib-p glyph &optional locale
-This function is equivalent to calling @code{glyph-property} with
-a property of @code{contrib-p}. The return value will be a boolean
-specifier if @var{locale} is @code{nil} or omitted; otherwise,
-it will be a specification or list of specifications.
-@end defun
+@item tab-control
+A tab widget; a series of user selectable tabs. Can only be instanced
+as @code{widget}.
-@defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
-This function is equivalent to calling @code{set-glyph-property} with
-a property of @code{contrib-p}.
-@end defun
+@item tree-view
+A folding widget. Can only be instanced as @code{widget}.
-@defun glyph-contrib-p-instance glyph &optional domain default no-fallback
-This function returns whether the glyph contributes to its line height
-in the given @var{domain}, and is equivalent to calling
-@code{glyph-property-instance} with a property of @code{contrib-p}. The
-return value will be either @code{nil} or @code{t}. (Normally @var{domain}
-will be a window or @code{nil}, meaning the selected window.)
+@item scrollbar
+A scrollbar widget. Can only be instanced as @code{widget}.
+
+@item autodetect
+XEmacs tries to guess what format the data is in. If X support exists,
+the data string will be checked to see if it names a filename. If so,
+and this filename contains XBM or XPM data, the appropriate sort of
+pixmap or pointer will be created. [This includes picking up any
+specified hotspot or associated mask file.] Otherwise, if @code{pointer}
+is one of the allowable image-instance types and the string names a
+valid cursor-font name, the image will be created as a pointer.
+Otherwise, the image will be displayed as text. If no X support exists,
+the image will always be displayed as text.
+
+@item inherit
+Inherit from the background-pixmap property of a face. Can only be
+instanced as @code{mono-pixmap}.
+@end table
+
+There are two convenience variables for use with the XBM and XPM image
+formats.
+
+@defvar xpm-color-symbols
+This variable holds definitions of logical color-names used when reading
+XPM files. Elements of this list should be of the form
+@code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name}
+should be a string, which is the name of the color to define; the
+@var{form-to-evaluate} should evaluate to a color specifier object, or a
+string to be passed to @code{make-color-instance} (@pxref{Colors}). If
+a loaded XPM file references a symbolic color called @var{color-name},
+it will display as the computed color instead.
+
+The default value of this variable defines the logical color names
+@samp{"foreground"} and @samp{"background"} to be the colors of the
+@code{default} face.
+@end defvar
+
+@defvar x-bitmap-file-path
+A list of the directories in which X bitmap files may be found. If @code{nil},
+this is initialized from the @samp{"*bitmapFilePath"} resource. This is
+used by the @code{make-image-instance} function (however, note that if
+the environment variable @samp{XBMLANGPATH} is set, it is consulted
+first).
+@end defvar
+
+
+@node Image Instances
+@subsection Image Instances
+@cindex image instances
+
+ Image-instance objects encapsulate the way a particular image (pixmap,
+etc.) is displayed on a particular device.
+
+ In most circumstances, you do not need to directly create image
+instances; use a glyph instead. However, it may occasionally be useful
+to explicitly create image instances, if you want more control over the
+instantiation process.
+
+@defun image-instance-p object
+This function returns non-@code{nil} if @var{object} is an image instance.
@end defun
-@defun glyph-baseline glyph &optional locale
-This function is equivalent to calling @code{glyph-property} with a
-property of @code{baseline}. The return value will be a specifier if
-@var{locale} is @code{nil} or omitted; otherwise, it will be a
-specification or list of specifications.
+@menu
+* Image Instance Types:: Each image instances has a particular type.
+* Image Instance Functions:: Functions for working with image instances.
+@end menu
+
+
+@node Image Instance Types
+@subsubsection Image Instance Types
+@cindex image instance types
+
+ Image instances come in a number of different types. The type
+of an image instance specifies the nature of the image: Whether
+it is a text string, a mono pixmap, a color pixmap, etc.
+
+ The valid image instance types are
+
+@table @code
+@item nothing
+Nothing is displayed.
+
+@item text
+Displayed as text. The foreground and background colors and the
+font of the text are specified independent of the pixmap. Typically
+these attributes will come from the face of the surrounding text,
+unless a face is specified for the glyph in which the image appears.
+
+@item mono-pixmap
+Displayed as a mono pixmap (a pixmap with only two colors where the
+foreground and background can be specified independent of the pixmap;
+typically the pixmap assumes the foreground and background colors of
+the text around it, unless a face is specified for the glyph in which
+the image appears).
+@item color-pixmap
+
+Displayed as a color pixmap.
+
+@item pointer
+Used as the mouse pointer for a window.
+
+@item subwindow
+A child window that is treated as an image. This allows (e.g.)
+another program to be responsible for drawing into the window.
+Not currently implemented.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+
+@item widget
+An active GUI element implemented as a ``widget'' or ``control'' of the
+underlying window system.
+@end table
+
+The following functions are used to check whether an image instance type
+is valid in the running XEmacs.
+
+@defun valid-image-instance-type-p type
+This function returns non-@code{nil} if @var{type} is a valid image
+instance type.
@end defun
-@defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
-This function is equivalent to calling @code{set-glyph-property} with
-a property of @code{baseline}.
+@defun image-instance-type-list
+This function returns a list of the valid image instance types.
@end defun
-@defun glyph-baseline-instance glyph &optional domain default no-fallback
-This function returns the instance of @var{glyph}'s baseline value in
-the given @var{domain}, and is equivalent to calling
-@code{glyph-property-instance} with a property of @code{baseline}. The
-return value will be an integer or @code{nil}.
+The following functions are used to determine the type of an image
+instance.
-Normally @var{domain} will be a window or @code{nil} (meaning the
-selected window), and an instance object describing the baseline value
-appears in that particular window and buffer will be returned.
+@defun image-instance-type image-instance
+Return the type of the given image instance. The return
+value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
+@code{color-pixmap}, @code{pointer}, @code{subwindow}, or @code{widget}.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+@end defun
+
+@defun text-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{text}.
+@end defun
+
+@defun mono-pixmap-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{mono-pixmap}.
+@end defun
+
+@defun color-pixmap-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{color-pixmap}.
+@end defun
+
+@defun pointer-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{pointer}.
+@end defun
+
+@defun subwindow-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{subwindow}.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+@end defun
+
+@defun nothing-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{nothing}.
+@end defun
+
+@defun widget-image-instance-p object
+Return non-@code{nil} if @var{object} is an image instance of type
+@code{widget}.
+@end defun
+
+
+@node Image Instance Functions
+@subsubsection Image Instance Functions
+
+@defun make-image-instance data &optional domain dest-types noerror
+This function creates a new image-instance object.
+
+@var{data} is an image instantiator, which describes the image
+(@pxref{Image Specifiers}).
+
+@var{dest-types} should be a list of allowed image instance types that
+can be generated. The @var{dest-types} list is unordered. If multiple
+destination types are possible for a given instantiator, the ``most
+natural'' type for the instantiator's format is chosen. These are
+
+@table @code
+@item XBM
+@c #### check xface
+@itemx xface
+@code{mono-pixmap}, then @code{color-pixmap}, then @code{pointer}.
+
+@item XPM
+@itemx GIF
+@itemx JPEG
+@itemx PNG
+@itemx TIFF
+@code{color-pixmap}, then @code{mono-pixmap}, then @code{pointer}.
+
+@item string
+@itemx formatted-string formats
+@code{text}, then @code{mono-pixmap} (not currently implemented), then
+@code{color-pixmap} (not currently implemented).
+
+@item mswindows-resource
+For pointer resources, @code{pointer}.
+
+For the others, @code{color-pixmap}.
+@end table
+
+@c #### So what? This is a reference manual, list them, you lazy bastard!
+The other formats can only be instantiated as one type.
+
+If you want to control more specifically the order of the types into
+which an image is instantiated, call @code{make-image-instance}
+repeatedly until it succeeds, passing less and less preferred
+destination types each time.
+
+If @var{dest-types} is omitted, all possible types are allowed.
+
+@var{domain} specifies the domain to which the image instance will be
+attached. This domain is termed the @dfn{governing domain}. The type
+of the governing domain depends on the image instantiator format.
+(Although, more correctly, it should probably depend on the image
+instance type.) For example, pixmap image instances are specific to a
+device, but widget image instances are specific to a particular XEmacs
+window because in order to display such a widget when two windows onto
+the same buffer want to display the widget, two separate underlying
+widgets must be created. (That's because a widget is actually a child
+window-system window, and all window-system windows have a unique
+existence on the screen.) This means that the governing domain for a
+pixmap image instance will be some device (most likely, the only
+existing device), whereas the governing domain for a widget image
+instance will be some XEmacs window.
+
+If you specify an overly general @var{domain} (e.g. a frame when a
+window was wanted), an error is signaled. If you specify an overly
+specific @var{domain} (e.g. a window when a device was wanted), the
+corresponding general domain is fetched and used instead. For
+@code{make-image-instance}, it makes no difference whether you specify
+an overly specific domain or the properly general domain derived from
+it. However, it does matter when creating an image instance by
+instantiating a specifier or glyph (e.g. with
+@code{glyph-image-instance}), because the more specific domain causes
+spec lookup to start there and proceed to more general domains. (It
+would also matter when creating an image instance with an instantiator
+format of @code{inherit}, but we currently disallow this.)
+@c #### We should fix that.
+
+If omitted, @var{domain} defaults to the selected window.
+
+@var{noerror} controls what happens when the image cannot be generated.
+If @code{nil}, an error message is generated. If @code{t}, no messages
+are generated and this function returns @code{nil}. If anything else, a
+warning message is generated and this function returns @code{nil}.
+@end defun
+
+@defun colorize-image-instance image-instance foreground background
+This function makes the image instance be displayed in the given
+colors. Image instances come in two varieties: bitmaps, which are 1
+bit deep which are rendered in the prevailing foreground and background
+colors; and pixmaps, which are of arbitrary depth (including 1) and
+which have the colors explicitly specified. This function converts a
+bitmap to a pixmap. If the image instance was a pixmap already,
+nothing is done (and @code{nil} is returned). Otherwise @code{t} is
+returned.
+@end defun
+
+The following functions are
+
+@defun image-instance-name image-instance
+This function returns the name of the given image instance. The name is
+typically taken from the @code{:file} property of the instantiator if
+present, otherwise from the @code{:data} property.
+@end defun
+
+@defun image-instance-domain image-instance
+Return the governing domain of the given @var{image-instance}. The
+governing domain of an image instance is the domain that the image
+instance is specific to. It is @emph{NOT} necessarily the domain that
+was given to the call to @code{specifier-instance} that resulted in the
+creation of this image instance. See @code{make-image-instance} for
+more information on governing domains.
+@end defun
+
+@defun image-instance-string image-instance
+This function returns the string of the given image instance. This will
+only be non-@code{nil} for text image instances.
+@end defun
+
+@defun image-instance-file-name image-instance
+This function returns the file name from which @var{image-instance} was
+read, if known.
@end defun
-@defun glyph-face glyph
-This function returns the face of @var{glyph}. (Remember, this is
-not a specifier, but a simple property.)
-@end defun
+@defun image-instance-mask-file-name image-instance
+This function returns the file name from which @var{image-instance}'s
+mask was read, if known.
+@end defun
+
+Pixmaps are considered to be three-dimensional. The height and width of
+the pixel array that is displayed, and the color depth of its pixels,
+are accessed with these functions.
+
+@defun image-instance-depth image-instance
+This function returns the depth of the image instance. This is 0 for a
+mono pixmap, or a positive integer for a color pixmap.
+@end defun
+
+@defun image-instance-height image-instance
+This function returns the height of the image instance, in pixels.
+@end defun
+
+@defun image-instance-width image-instance
+This function returns the width of the image instance, in pixels.
+@end defun
+
+The hotspot is a point relative to the origin of the pixmap. When
+an image is used as a mouse pointer, the hotspot is the point on the
+image that sits over the location that the pointer points to. This is,
+for example, the tip of the arrow or the center of the crosshairs.
+
+These functions access the coordinates of the hotspot. They simply
+return @code{nil} for a non-pointer image instance.
+
+@defun image-instance-hotspot-x image-instance
+This function returns the X coordinate of the image instance's hotspot,
+if known.
+@end defun
+
+@defun image-instance-hotspot-y image-instance
+This function returns the Y coordinate of the image instance's hotspot,
+if known.
+@end defun
+
+Mono pixmaps and pointers may have their foreground and background
+colors set when instanced. Use these functions to access color
+information.
+
+@defun image-instance-foreground image-instance
+This function returns the foreground color of @var{image-instance}, if
+applicable. This will be a color instance or @code{nil}. (It will only
+be non-@code{nil} for colorized mono pixmaps and for pointers.)
+@end defun
+
+@defun image-instance-background image-instance
+This function returns the background color of @var{image-instance}, if
+applicable. This will be a color instance or @code{nil}. (It will only
+be non-@code{nil} for colorized mono pixmaps and for pointers.)
+@end defun
+
+
+@node Using Glyphs
+@section Using Glyphs
+
+Glyph usage is unfortunately somewhat arcane. (For discussion of
+rationale, @ref{Glyphs,,,Internals}.) Because they are not ``text,''
+they cannot be inserted directly into a buffer. Instead, they are
+values of properties of extents attached to buffers or strings, values
+of global variables such as mouse pointers, or as a component of a
+complex data structure such as a toolbar initializer. Although these
+uses could probably streamlined, each structure has its own
+requirements. Since glyphs are very flexible, it is possible to create
+applications like the @file{edit-toolbar} and @file{xpm-mode} libraries
+which display glyphs in a buffer (for reference while editing) that are
+normally used in a different context.
+
+Usage of glyphs can roughly be categorized as follows:
+
+@table @strong
+@item Buffer glyphs
+Glyphs that are inserted in a buffer may be used for their own sake (for
+example, image display in @file{w3}), as an accurate representation of
+text that can't be displayed in usual fonts (equation display in
+@file{preview-latex}), or as annotations (such as a marginal indication
+of a bookmark). Glyphs are attached to buffers via extents.
+
+@item Redisplay glyphs
+Glyphs can be used to create XEmacs-specific ``fonts''. For example,
+the character that indicates truncation of lines is implemented as the
+@code{truncation-glyph}. It is also possible to have XEmacs display a
+certain character using a custom glyph, via display tables.
+
+@item Frame glyphs
+Glyphs are used to control the appearance of various other components of
+the frame. They can be inserted in the modeline, like the favicons used
+in Web browsers. They are used to specify the labels on toolbar
+buttons. Finally, they can be inserted in the gutters. (The difference
+between a glyph inserted in a gutter and a marginal annotation is that
+the marginal annotation is tied to the text in the buffer. If the
+buffer line scrolls out of view, the marginal annotation will, as well.
+A gutter glyph does not move with the text.)
+
+Unfortunately, all these uses are special cases, and have their own
+APIs, in contrast to glyphs in a buffer.
+
+@item External glyphs
+External glyphs simply allow a consistent API for images. The images
+are then passed to external software such as the window system itself
+(mouse cursor shapes) and the window manager (icons to represent
+minimized windows). XEmacs has no role in managing their use.
+
+@item Subwindow and widget glyphs
+These do not constitute a context of use, but rather an important class of
+glyph types. The difference between these and other glyphs is that
+while their geometry is determined by XEmacs, their behavior is managed
+separately, by internal mechanisms in the case of widgets, and
+(possibly) by another process in the case of subwindows.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+@end table
+
+Some simple concrete examples showing how to insert a glyph in a
+buffer are presented later. @ref{Glyph Examples}.
+
+``Creating Glyphs'' explains how to create glyphs. Creating a glyph
+using @code{make-glyph} does not specify @emph{where} the glyph will be
+used, it only specifies @emph{what} the glyph will look like. The next
+four sections explain how to embed glyphs in different display
+contexts. Finally, the last two sections explain the special
+considerations of using glyphs whose behavior is not determined by the
+code creating them, but by the glyph itself (a ``widget'' in X11 or
+``control'' in MS Windows or Aqua), or even by a separate process.
+
+@menu
+* Creating Glyphs:: Creating new glyphs.
+* Buffer Glyphs:: Annotations are glyphs that appear in a buffer.
+* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
+* Frame Glyphs:: Displaying glyphs in GUI components of the frame.
+* External Glyphs:: Icons and mouse pointers for the window system.
+* Native GUI Widgets:: Complex active elements treated as a single glyph.
+* Subwindows:: Externally-controlled subwindows in buffers.
+@c #### Check status of subwindows ... I thought Andy implemented them.
+@end menu
+
+@node Creating Glyphs
+@subsection Creating Glyphs
+
+@defun make-glyph &optional spec-list type
+This function creates a new glyph object of type @var{type}.
+
+The optional @var{spec-list} is used to initialize the glyph's image.
+It can be any spec-list of @dfn{image instantiator} accepted by
+@code{canonicalize-spec-list}, @ref{Adding Specifications}. An
+individual image instantiator may be a string, which is converted to a
+vector according to @code{console-type-image-conversion-list}, or a
+vector. The vector's first element specifies the @emph{external} format
+of the data, such as a string, a PNG file, or an MS Windows resource.
+This is followed by properties (keyword-value pairs) specifying such
+information as the name of a file containing an image, or pixmap data
+directly. @xref{Image Specifiers}.
+
+The optional @var{type} specifies the type of the glyph. @var{type}
+should be one of @code{buffer} (used for glyphs in an extent, the
+modeline, the toolbar, or elsewhere in a frame), @code{pointer} (used
+for the mouse-pointer), or @code{icon} (used for a frame's icon), and
+defaults to @code{buffer}.
+@end defun
+
+@var{spec-list} is the initializer for the glyph's @code{image}
+property, which is an image specifier. (Note that @dfn{image} as used
+in the context of a glyph's @code{image} property or in the terms
+@dfn{image specifier}, @dfn{image instantiator}, or @dfn{image instance}
+does not refer to what people normally think of as an image (which in
+XEmacs is called a @dfn{pixmap}), but to any graphical element---a
+pixmap, a widget, or even a block of text, when used in the places that
+call for a glyph.)
+
+The most common form of @var{spec-list} is a single image instantiator.
+(@strong{Compatibility note:} in GNU Emacs 21, a string used to
+instantiate an image is interpreted as the name of an image file, which
+is searched for and instantiated.) The conversion controlled by
+@code{console-type-image-conversion-list} typically attempts to look up
+the string as a file name in XEmacs's data directory path, and if this
+fails, defaults to displaying the string as a text image instance
+(@emph{i.e.}. the string itself.
+
+Fine control of a particular specification is provided by using a vector
+as the image instantiator. More complicated instantiators allow lists
+of instantiators to be specified (which are tried in order), or mappings
+from locales to lists of instantiators, @emph{etc}. @xref{Specifiers},
+for more information about specification formats.
+
+As well as using @var{spec-list} to initialize the glyph, you can set
+specifications using @code{set-glyph-image}. The glyph itself is not
+actually a specifier, but rather is an object containing an image
+specifier (as well as other properties seldom set by user code).
+Therefore, you cannot set or access specifications for the glyph's image
+by directly using @code{set-specifier}, @code{specifier-instance} or the
+like on the glyph; instead use them on @code{(glyph-image @var{glyph})}
+or use the convenience functions @code{set-glyph-image},
+@code{glyph-image-instance}, and @code{glyph-image}.
+
+Glyph types reflect the fact that glyphs are used in contexts like
+pointers and window manager icons, which are defined by external
+programs such as the window system or window manager. These require
+somewhat different @emph{internal} format, which is opaque to the user.
+
+It is extremely rare that you will ever have to specify a value for
+@var{type}, which should be one of @code{buffer} (used for glyphs in an
+extent, the modeline, the toolbar, or elsewhere in a buffer),
+@code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
+frame's icon), and defaults to @code{buffer}. The only cases where it
+needs to be specified is when creating icon or pointer glyphs, and in
+both cases the necessary glyphs have already been created at startup and
+are accessed through the appropriate variables,
+e.g. @code{text-pointer-glyph} (or in general, any
+@samp{*-pointer-glyph}) and @code{frame-icon-glyph}. User code should
+never need to create @code{pointer} or @code{icon} glyphs. @xref{Glyph
+Types}.
+
+There are a few other glyph creation functions, normally used only
+internally or at XEmacs initialization.
+
+@defun make-glyph-internal &optional type
+This function creates a new, uninitialized glyph of type @var{type}.
+@end defun
+
+@defun make-pointer-glyph &optional spec-list
+
+Return a new @code{pointer-glyph} object with the specification list
+@var{spec-list}. This function is equivalent to calling
+@code{make-glyph} with a @var{type} of @code{pointer}.
+@end defun
+
+@code{make-pointer-glyph} is normally used only by XEmacs initialization
+code. It is extremely unlikely that you will ever need to create a
+pointer glyph. Instead, you probably want to be calling
+@code{set-glyph-image} on an existing glyph,
+e.g. @code{text-pointer-glyph}.
+
+@defun make-icon-glyph &optional spec-list
+
+Return a new @code{icon-glyph} object with the specification list
+@var{spec-list}. This function is equivalent to calling
+@code{make-glyph} with a @var{type} of @code{icon}.
+@end defun
+
+@code{make-icon-glyph} is normally used only by XEmacs initialization
+code. It is extremely unlikely that you will ever need to create a icon
+glyph. Instead, you probably want to be calling @code{set-glyph-image}
+on the existing glyph, @code{frame-icon-glyph}.
+
+
+@node Buffer Glyphs
+@subsection Buffer Glyphs
+
+Creating a glyph using @code{make-glyph} does not specify @emph{where}
+the glyph will be used, it only specifies @emph{what} the glyph will
+look like. Once you have created a glyph, you specify where it will be
+used by attaching it to an extent as a @emph{begin-glyph} or
+@emph{end-glyph}.
+
+@table @code
+@item buffer text
+To insert a glyph into a buffer, create an extent in the buffer and then
+use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
+a glyph to be displayed at the corresponding edge of the extent. (It is
+common to create zero-width extents for this purpose.)
+
+@item margins
+To insert a glyph into the left or right margin of a buffer, first
+make sure the margin is visible by setting a value for the specifiers
+@code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
+when using margin glyphs with layout policy @code{whitespace}.) Follow
+the same procedure above for inserting a glyph in a buffer, then
+set a non-default layout policy for the glyph using
+@code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
+Alternatively, use the high-level annotations API (see
+@code{make-annotation}). (In fact, you can also use the annotations
+API for glyphs in a buffer, by setting a layout policy of @code{text}.)
+
+@end table
+
+
+@node Redisplay Glyphs
+@subsection Redisplay Glyphs
+
+To use a glyph to control the shape of miscellaneous redisplay effects
+such as the truncation and continuation markers, set the appropriate
+existing glyph variables with @code{set-glyph-image}. See
+@code{continuation-glyph}, @code{control-arrow-glyph},
+@code{hscroll-glyph}, @code{invisible-text-glyph},
+@code{octal-escape-glyph}, and @code{truncation-glyph}. See also
+@code{overlay-arrow-string}, an odd redisplay leftover which can be set
+to a glyph you created, and will cause the glyph to be displayed on top
+of the text position specified in the marker stored in
+@code{overlay-arrow-position}.
+
+To use a glyph in a display table (i.e. to control the appearance of any
+individual character), create the appropriate character glyphs and then
+set a specification for the specifier @code{current-display-table},
+which controls the appearance of characters. You can also set an
+overriding display table for use with text displayed in a particular
+face; see @code{set-face-display-table} and @code{make-display-table}.
+#### Note: Display tables do not currently support general Mule
+characters. They will be overhauled at some point to support this
+and to provide other features required under Mule. @ref{Display Tables}.
+
+Glyphs are not actually used as the background pixmaps of faces, but the
+API is similar. The
+background pixmap of a face is actually an image specifier -- probably
+the only place in XEmacs where an image specifier occurs outside of a
+glyph. If you would like to use a glyph's image as a background pixmap,
+you can extract it with @code{glyph-image}, and then add it to a face.
+@xref{Face Convenience Functions}.
+
+@defvr Glyph truncation-glyph
+This variable specifies what is displayed at the end of truncated lines.
+@end defvr
+
+@defvr Glyph continuation-glyph
+This variable specifies what is displayed at the end of wrapped lines.
+@end defvr
+
+@defvr Glyph octal-escape-glyph
+This variable specifies what to prefix character codes displayed in octal
+with.
+@end defvr
+
+@defvr Glyph hscroll-glyph
+This variable specifies what to display at the beginning of horizontally
+scrolled lines.
+@end defvr
+
+@defvr Glyph invisible-text-glyph
+This variable specifies what to use to indicate the presence of
+invisible text. This is the glyph that is displayed when an ellipsis is
+called for, according to @code{selective-display-ellipses} or
+@code{buffer-invisibility-spec}). Normally this is three dots (``...'').
+@end defvr
+
+@defvr Glyph control-arrow-glyph
+This variable specifies what to use as an arrow for control characters.
+@end defvr
+
+
+@node Frame Glyphs
+@subsection Frame Glyphs
+
+There are also a number of special objects whose appearance is specified
+by a glyph. Most of these a global objects that you update with
+@code{set-glyph-image}, such as mouse pointers. Frame icons, toolbar
+button icons, and the modeline are the main non-text objects which
+accept glyphs as elements.
+
+@table @code
+@item modeline
+A glyph may be displayed in the modeline by inserting the glyph as one
+of the elements of the modeline format. (Unfortunately you can't
+currently put a begin glyph or end glyph on one of the modeline
+extents---they're ignored.)
+
+@item toolbar
+To insert a glyph into a toolbar, specify it as the icon part of a toolbar
+button, which in turn must be part of a toolbar instantiator (typically
+set on the specifier @code{default-toolbar}).
+See @code{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 @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
+and then calling @code{(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.)
+
+@item gutter
+To insert a glyph into a gutter, use
+@code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
+glyph to be displayed at the corresponding edge of extent in a string,
+similar to the way you insert glyphs in a buffer. Then insert the
+string into the gutter @ref{Specifying a Gutter}. Glyphs that are
+frequently used in this way are @code{tab control} and @code{progress
+bar} glyphs.
+
+@end table
+
+
+@node External Glyphs
+@subsection External Glyphs
+@cindex frame icon
+@cindex icon, frame
+@cindex mouse cursor
+@cindex cursor (mouse)
+@cindex pointer (mouse)
+@cindex mouse pointer
+
+There are two special kinds of glyph that are not displayed by XEmacs.
+Instead, they are used to set the appearance of iconified frames and the
+mouse pointer. Because these uses are constrained by the window system,
+icons and pointers have their own special types @xref{Glyph Types}.
+
+You may use a glyph as the icon for a frame. Do not create a new glyph;
+instead, change the specifications for the existing glyph
+@code{frame-icon-glyph} with @code{set-glyph-image}. This is a unique,
+predefined object. Although the natural usage is to set specifications
+for the global locale or a frame locale, you can also arrange for a
+special icon when a frame's selected window displays a particular buffer
+by using a buffer locale.
+
+The shape of the mouse pointer when over a particular section of a frame
+is controlled using various glyph variables. Since the image of a glyph
+is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
+or per-device basis.
+
+To use a glyph as the mouse pointer, in general you do not create a new
+glyph, but rather you change the specifications of various existing
+glyphs, such as @code{text-pointer-glyph} for the pointer used over
+text, @code{modeline-pointer-glyph} for the pointer used over the
+modeline, etc. Do an apropos over @samp{pointer-glyph} to find all of
+them. (Note also that you can temporarily set the mouse pointer to some
+specific shape by using @code{set-frame-pointer}, which takes an image
+instance, as obtained from calling @code{glyph-image-instance} on a glyph
+of type @code{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 @code{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 @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
+really want to get low-level.)
+
+You should use @code{set-glyph-image} to set the following variables,
+@emph{not} @code{setq}.
+
+@defvr Glyph text-pointer-glyph
+This variable specifies the shape of the mouse pointer when over text.
+@end defvr
+
+@defvr Glyph nontext-pointer-glyph
+This variable specifies the shape of the mouse pointer when over a
+buffer, but not over text. If unspecified in a particular domain,
+@code{text-pointer-glyph} is used.
+@end defvr
+
+@defvr Glyph modeline-pointer-glyph
+This variable specifies the shape of the mouse pointer when over the modeline.
+If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
+@end defvr
+
+@defvr Glyph selection-pointer-glyph
+This variable specifies the shape of the mouse pointer when over a
+selectable text region. If unspecified in a particular domain,
+@code{text-pointer-glyph} is used.
+@end defvr
+
+@defvr Glyph gc-pointer-glyph
+This variable specifies the shape of the mouse pointer when a garbage
+collection is in progress. If the selected window is on a window system
+and this glyph specifies a value (i.e. a pointer image instance) in the
+domain of the selected window, the pointer will be changed as specified
+during garbage collection. Otherwise, a message will be printed in the
+echo area, as controlled by @code{gc-message}.
+@end defvr
+
+@defvr Glyph busy-pointer-glyph
+This variable specifies the shape of the mouse pointer when XEmacs is busy.
+If unspecified in a particular domain, the pointer is not changed
+when XEmacs is busy.
+@end defvr
+
+@defvr Glyph menubar-pointer-glyph
+This variable specifies the shape of the mouse pointer when over the
+menubar. If unspecified in a particular domain, the
+window-system-provided default pointer is used.
+@end defvr
-@defun set-glyph-face glyph face
-This function changes the face of @var{glyph} to @var{face}.
-@end defun
+@defvr Glyph scrollbar-pointer-glyph
+This variable specifies the shape of the mouse pointer when over a
+scrollbar. If unspecified in a particular domain, the
+window-system-provided default pointer is used.
+@end defvr
-@node Glyph Dimensions
-@subsection Glyph Dimensions
+@defvr Glyph toolbar-pointer-glyph
+This variable specifies the shape of the mouse pointer when over a
+toolbar. If unspecified in a particular domain,
+@code{nontext-pointer-glyph} is used.
+@end defvr
-@defun glyph-width glyph &optional window
-This function returns the width of @var{glyph} on @var{window}. This
-may not be exact as it does not take into account all of the context
-that redisplay will.
-@end defun
+Internally, these variables are implemented in
+@code{default-mouse-motion-handler}, and thus only take effect when the
+mouse moves. That function calls @code{set-frame-pointer}, which sets
+the current mouse pointer for a frame.
-@defun glyph-ascent glyph &optional window
-This function returns the ascent value of @var{glyph} on @var{window}.
-This may not be exact as it does not take into account all of the
-context that redisplay will.
+@defun set-frame-pointer frame image-instance
+This function sets the mouse pointer of @var{frame} to the given pointer
+image instance. You should not call this function directly.
+(If you do, the pointer will change again the next time the mouse moves.)
@end defun
-@defun glyph-descent glyph &optional window
-This function returns the descent value of @var{glyph} on @var{window}.
-This may not be exact as it does not take into account all of the
-context that redisplay will.
-@end defun
-@defun glyph-height glyph &optional window
-This function returns the height of @var{glyph} on @var{window}. (This
-is equivalent to the sum of the ascent and descent values.) This may
-not be exact as it does not take into account all of the context that
-redisplay will.
-@end defun
+@node Native GUI Widgets
+@subsection Native GUI Widgets
+@cindex native widget
-@node Images
-@section Images
+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
-* Image Specifiers:: Specifying how an image will appear.
-* Image Instantiator Conversion::
- Conversion is applied to image instantiators
- at the time they are added to an
- image specifier or at the time they
- are passed to @code{make-image-instance}.
-* Image Instances:: What an image specifier gets instanced as.
+* Introduction to Widgets:: Native widgets provide tight integration of
+ GUI features with the platform GUI.
+* Lisp API to Native Widgets:: Native widgets are glyphs.
+* Layouts:: Specifying composite widgets from Lisp.
+* Primitive Widgets:: Catalogue of available native widgets.
@end menu
-@node Image Specifiers
-@subsection Image Specifiers
-@cindex image specifiers
-
- An image specifier is used to describe the actual image of a glyph.
-It works like other specifiers (@pxref{Specifiers}), in that it contains
-a number of specifications describing how the image should appear in a
-variety of circumstances. These specifications are called @dfn{image
-instantiators}. When XEmacs wants to display the image, it instantiates
-the image into an @dfn{image instance}. Image instances are their own
-primitive object type (similar to font instances and color instances),
-describing how the image appears in a particular domain. (On the other
-hand, image instantiators, which are just descriptions of how the image
-should appear, are represented using strings or vectors.)
-
-@defun image-specifier-p object
-This function returns non-@code{nil} if @var{object} is an image specifier.
-Usually, an image specifier results from calling @code{glyph-image} on
-a glyph.
-@end defun
-
-@defun make-image-specifier spec-list
-This function creates a new image specifier object and initializes it
-according to @var{spec-list}. @xref{Specifiers}.
-
-Note that, in practice, you rarely, if ever, need to actually create an
-image specifier! (This function exists mainly for completeness.) Pretty
-much the only use for image specifiers is to control how glyphs are
-displayed, and the image specifier associated with a glyph (the
-@code{image} property of a glyph) is created automatically when a glyph
-is created and need not (and cannot, for that matter) ever be changed
-(@pxref{Glyphs}). In fact, the design decision to create a separate
-image specifier type, rather than make glyphs themselves be specifiers,
-is debatable---the other properties of glyphs are rarely used and could
-conceivably have been incorporated into the glyph's instantiator. The
-rarely used glyph types (buffer, pointer, icon) could also have been
-incorporated into the instantiator.
-@end defun
+@node Introduction to Widgets
+@subsubsection Introduction to Native Widgets and Subwindow Glyphs
+
+Traditionally Emacsen have hidden the GUI apparatus from the Lisp
+programmer, but in XEmacs 21.4 the ability to embed autonomous GUI
+objects, called @dfn{native widgets}, in text was added to Lisp. They
+are handled as @emph{glyphs}. Unlike traditional XEmacs
+glyphs such images and strings, native widgets are opaque to XEmacs, and
+must be able to redraw themselves because they are implemented as
+subwindows, not as graphics drawn by XEmacs into the text window.
+
+Primitive widgets are coded in C using the underlying GUI toolkit, and
+thus are beyond the scope of the @emph{XEmacs Lisp Reference Manual}.
+However, composite widgets can be created in Lisp using ``layouts,''
+which are horizontal or vertical arrays of subwidgets. For example, the
+search dialog is formatted using layouts.
+
+@node Lisp API to Native Widgets
+@subsubsection Lisp API to Native Widgets
+
+Native widgets are manipulated as @emph{glyphs} (@pxref{Glyphs}). Thus
+they are created using @code{make-glyph}, with a format of one of the
+widget types and a @code{:data} property specific to the widget being
+instanced.
+
+However, there is a technical difference between widgets and other kinds
+of glyphs that is theoretically important. Because widgets
+are active (that is, they can respond to user input events themselves),
+it is possible for the user to become aware that two appearances of the
+``same'' glyph are actually separate instances. For example, if a user
+changes an image glyph from red to blue, and the buffer containing the
+glyph appears in more than one window, the user will perceive all the
+appearances to change from red to blue simultaneously. However, suppose
+the glyph is a button glyph (@emph{e.g.}, as used in the Customize
+buffer for the Set, Save, and Done buttons). Then if the Customize
+buffer appears in several windows at the same time, and the user clicks
+on the button, she will only perceive the button to be depressed in the
+window where she clicked the button.
+
+It seems from this example that it is unlikely to be a problem in
+practice. When the user is faced with an active widget, it seems likely
+that attention will focus on the widget being manipulated, and having
+other instances of the widget respond simultaneously might be more
+disconcerting than the actual case.
+
+@node Layouts
+@subsubsection Layouts
+
+An XEmacs @dfn{layout} is a one-dimensional array of glyphs. It is a
+widget for controlling the positioning of children underneath it.
+Through the use of nested layouts, a widget hierarchy can be created
+which can have the appearance of any standard dialog box or similar
+arrangement; all of this is counted as one "glyph" and could appear in
+many of the places that expect a single glyph.
+@c #### Fix me!
+(There are also @dfn{native layouts}, but these are undocumented, as are
+their uses.)
- Image instantiators come in many formats: @code{xbm}, @code{xpm},
-@code{gif}, @code{jpeg}, etc. This describes the format of the data
-describing the image. The resulting image instances also come in many
-types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
-@code{pointer}, etc. This refers to the behavior of the image and the
-sorts of places it can appear. (For example, a color-pixmap image has
-fixed colors specified for it, while a mono-pixmap image comes in two
-unspecified shades ``foreground'' and ``background'' that are determined
-from the face of the glyph or surrounding text; a text image appears as
-a string of text and has an unspecified foreground, background, and
-font; a pointer image behaves like a mono-pixmap image but can only be
-used as a mouse pointer [mono-pixmap images cannot be used as mouse
-pointers]; etc.) It is important to keep the distinction between image
-instantiator format and image instance type in mind. Typically, a given
-image instantiator format can result in many different image instance
-types (for example, @code{xpm} can be instanced as @code{color-pixmap},
-@code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
-instanced only as @code{pointer}), and a particular image instance type
-can be generated by many different image instantiator formats (e.g.
-@code{color-pixmap} can be generated by @code{xpm}, @code{gif},
-@code{jpeg}, etc.).
+A layout descriptor is an image instantiator, @emph{i.e.}, a vector of
+the form @samp{[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]} with format
+@code{layout}, and properties
- @xref{Image Instances}, for a more detailed discussion of image
-instance types.
+@c #### need defaults for these
+@table @code
+@item :orientation
+Specifies the orientation of the contained array of glyphs. The value
+must be one of the symbols @code{horizontal} or @code{vertical}.
+
+@item :horizontally-justify
+Specifies the horizontal justification of the items in the array. The
+value must be one of the symbols @code{:right}, @code{:center}, or
+@code{:left}.
+
+@item :vertically-justify
+Specifies the vertical justification of the items in the array. The
+value must be one of the symbols @code{:top}, @code{:center}, or
+@code{:bottom}.
+
+@item :justify
+Specifies justification. #### not understood.
+
+@item :border
+A glyph to place in the border. The value must be an image
+instantiator.
+
+@item :items
+The glyphs controlled by the layout. The value must be a list of image
+instantiators.
+@end table
- An image instantiator should be a string or a vector of the form
+Here is the specification of the search dialog widget created by
+@code{make-search-dialog} in the @file{dialog-items} library, which
+makes use of recursive layouts.
@example
- @code{[@var{format} @var{:keyword} @var{value} ...]}
+(make-glyph
+ `[layout
+ :orientation horizontal
+ :vertically-justify top
+ :horizontally-justify center
+ :border [string :data "Search"]
+ :items
+ ([layout :orientation vertical
+ :justify top ; implies left also
+ :items
+ ([string :data "Search for:"]
+ [button :descriptor "Match Case"
+ :style toggle
+ :selected (not case-fold-search)
+ :callback (setq case-fold-search
+ (not case-fold-search))]
+ [button :descriptor "Regular Expression"
+ :style toggle
+ :selected search-dialog-regexp
+ :callback (setq search-dialog-regexp
+ (not search-dialog-regexp))]
+ [button :descriptor "Forwards"
+ :style radio
+ :selected search-dialog-direction
+ :callback (setq search-dialog-direction t)]
+ [button :descriptor "Backwards"
+ :style radio
+ :selected (not search-dialog-direction)
+ :callback (setq search-dialog-direction nil)]
+ )]
+ [layout :orientation vertical
+ :vertically-justify top
+ :horizontally-justify right
+ :items
+ ([edit-field :width 15 :descriptor "" :active t
+ :initial-focus t]
+ [button :width 10 :descriptor "Find Next"
+ :callback-ex
+ (lambda (image-instance event)
+ (search-dialog-callback ,parent
+ image-instance
+ event))]
+ [button :width 10 :descriptor "Cancel"
+ :callback-ex
+ (lambda (image-instance event)
+ (isearch-dehighlight)
+ (delete-frame
+ (event-channel event)))])])])
@end example
-i.e. a format symbol followed by zero or more alternating keyword-value
-pairs. The @dfn{format} field should be a symbol, one of
+@node Primitive Widgets
+@subsubsection Primitive Widgets
+@c #### the following table should be replaced with a menu of nodes
@table @code
-@item nothing
-Don't display anything; no keywords are valid for this. Can only be
-instanced as @code{nothing}.
-@item string
-Display this image as a text string. Can only be instanced
-as @code{text}, although support for instancing as @code{mono-pixmap}
-should be added.
-@item formatted-string
-Display this image as a text string with replaceable fields,
-similar to a modeline format string; not currently implemented.
-@item xbm
-An X bitmap; only if X support was compiled into this XEmacs. Can be
-instanced as @code{mono-pixmap}, @code{color-pixmap}, or
-@code{pointer}.
-@item xpm
-An XPM pixmap; only if XPM support was compiled into this XEmacs. Can
-be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
-@code{pointer}. XPM is an add-on library for X that was designed to
-rectify the shortcomings of the XBM format. Most implementations of X
-include the XPM library as a standard part. If your vendor does not, it
-is highly recommended that you download it and install it. You can get
-it from the standard XEmacs FTP site, among other places.
-@item xface
-An X-Face bitmap, used to encode people's faces in e-mail messages;
-only if X-Face support was compiled into this XEmacs. Can be instanced
-as @code{mono-pixmap}, @code{color-pixmap}, or @code{pointer}.
-@item gif
-A GIF87 or GIF89 image; only if GIF support was compiled into this
-XEmacs. Can be instanced as @code{color-pixmap}. Note that XEmacs
-includes GIF decoding functions as a standard part of it, so if you have
-X support, you will normally have GIF support, unless you explicitly
-disable it at configure time.
-@item jpeg
-A JPEG-format image; only if JPEG support was compiled into this
-XEmacs. Can be instanced as @code{color-pixmap}. If you have the JPEG
-libraries present on your system when XEmacs is built, XEmacs will
-automatically detect this and use them, unless you explicitly disable it
-at configure time.
-@item png
-A PNG/GIF24 image; only if PNG support was compiled into this XEmacs.
-Can be instanced as @code{color-pixmap}.
-@item tiff
-A TIFF-format image; only if TIFF support was compiled into this XEmacs.
-@item cursor-font
-One of the standard cursor-font names, such as @samp{watch} or
-@samp{right_ptr} under X. Under X, this is, more specifically, any of
-the standard cursor names from appendix B of the Xlib manual [also known
-as the file @file{<X11/cursorfont.h>}] minus the @samp{XC_} prefix. On
-other window systems, the valid names will be specific to the type of
-window system. Can only be instanced as @code{pointer}.
-@item font
-A glyph from a font; i.e. the name of a font, and glyph index into it
-of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
-Only if X support was compiled into this XEmacs. Currently can only be
-instanced as @code{pointer}, although this should probably be fixed.
-@item mswindows-resource
-An MS Windows pointer resource. Specifies a resource to retrieve
-directly from the system (an OEM resource) or from a file, particularly
-an executable file. If the resource is to be retrieved from a file, use
-:file and optionally :resource-id. Otherwise use :resource-id. Always
-specify :resource-type to specify the type (cursor, bitmap or icon) of
-the resource. Possible values for :resource-id are listed below. Can
-be instanced as @code{pointer} or @code{color-pixmap}.
-@item subwindow
-An embedded windowing system window. Can only be instanced as
-@code{subwindow}.
@item button
-A button widget; either a push button, radio button or toggle button.
-Can only be instanced as @code{widget}.
+A button widget; either a push button, radio button or toggle
+button.
+
@item combo-box
A drop list of selectable items in a widget, for editing text.
-Can only be instanced as @code{widget}.
-@item edit-field
-A text editing widget. Can only be instanced as @code{widget}.
-@item label
-A static, text-only, widget; for displaying text. Can only be instanced
-as @code{widget}.
-@item layout
-A widget for controlling the positioning of children underneath it.
-Through the use of nested layouts, a widget hierarchy can be created
-which can have the appearance of any standard dialog box or similar
-arrangement; all of this is counted as one @dfn{glyph} and could appear
-in many of the places that expect a single glyph. Can only be instanced
-as @code{widget}.
-@item native-layout
-@c #### Document me better!
-The native version of a layout widget.
-Can only be instanced as @code{widget}.
-@item progress-gauge
-A sliding widget, for showing progress. Can only be instanced as
-@code{widget}.
-@item tab-control
-A tab widget; a series of user selectable tabs. Can only be instanced
-as @code{widget}.
-@item tree-view
-A folding widget. Can only be instanced as @code{widget}.
-@item scrollbar
-A scrollbar widget. Can only be instanced as @code{widget}.
-@item autodetect
-XEmacs tries to guess what format the data is in. If X support exists,
-the data string will be checked to see if it names a filename. If so,
-and this filename contains XBM or XPM data, the appropriate sort of
-pixmap or pointer will be created. [This includes picking up any
-specified hotspot or associated mask file.] Otherwise, if @code{pointer}
-is one of the allowable image-instance types and the string names a
-valid cursor-font name, the image will be created as a pointer.
-Otherwise, the image will be displayed as text. If no X support exists,
-the image will always be displayed as text.
-@item inherit
-Inherit from the background-pixmap property of a face. Can only be
-instanced as @code{mono-pixmap}.
-@end table
-
-The valid keywords are:
-
-@table @code
-@item :data
-Inline data. For most formats above, this should be a string. For
-XBM images, this should be a list of three elements: width, height, and
-a string of bit data. This keyword is not valid for instantiator
-format @code{nothing}.
-
-@item :file
-Data is contained in a file. The value is the name of this file. If
-both @code{:data} and @code{:file} are specified, the image is created
-from what is specified in @code{:data} and the string in @code{:file}
-becomes the value of the @code{image-instance-file-name} function when
-applied to the resulting image-instance. This keyword is not valid for
-instantiator formats @code{nothing}, @code{string},
-@code{formatted-string}, @code{cursor-font}, @code{font}, and
-@code{autodetect}.
-
-@item :foreground
-@itemx :background
-For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
-These keywords allow you to explicitly specify foreground and background
-colors. The argument should be anything acceptable to
-@code{make-color-instance}. This will cause what would be a
-@code{mono-pixmap} to instead be colorized as a two-color color-pixmap,
-and specifies the foreground and/or background colors for a pointer
-instead of black and white.
-
-@item :mask-data
-For @code{xbm} and @code{xface}. This specifies a mask to be used with the
-bitmap. The format is a list of width, height, and bits, like for
-@code{:data}.
-
-@item :mask-file
-For @code{xbm} and @code{xface}. This specifies a file containing the
-mask data. If neither a mask file nor inline mask data is given for an
-XBM image, and the XBM image comes from a file, XEmacs will look for a
-mask file with the same name as the image file but with @samp{Mask} or
-@samp{msk} appended. For example, if you specify the XBM file
-@file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
-the associated mask file @file{left_ptrmsk} will automatically be picked
-up.
-
-@item :hotspot-x
-@itemx :hotspot-y
-For @code{xbm} and @code{xface}. These keywords specify a hotspot if
-the image is instantiated as a @code{pointer}. Note that if the XBM
-image file specifies a hotspot, it will automatically be picked up if no
-explicit hotspot is given.
-
-@item :color-symbols
-Only for @code{xpm}. This specifies an alist that maps strings that
-specify symbolic color names to the actual color to be used for that
-symbolic color (in the form of a string or a color-specifier object).
-If this is not specified, the contents of @code{xpm-color-symbols} are
-used to generate the alist.
-@item :resource-id
-Only for @code{mswindows-resource}. This must be either an integer
-(which directly specifies a resource number) or a string. Valid strings
-are
-For bitmaps:
+@item edit-field
+A text editing widget.
-"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".
+@item label
+A static, text-only, widget; for displaying text.
-For cursors:
+@item progress-gauge
+A sliding widget, for showing progress.
-"normal", "ibeam", "wait", "cross", "up", "sizenwse",
-"sizenesw", "sizewe", "sizens", "sizeall", and "no".
+@item tab-control
+A tab widget; a series of user selectable tabs.
-For icons:
+@item tree-view
+A folding widget.
-"sample", "hand", "ques", "bang", "note", and "winlogo".
-@item :resource-type
-Only for @code{mswindows-resource}. This must be a symbol, either
-@code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
-resource to be retrieved.
-@item :face
-Only for @code{inherit}. This specifies the face to inherit from. For
-widgets this also specifies the face to use for display. It defaults to
-gui-element-face.
+@item scrollbar
+A scrollbar widget. (#### Probably not the same as the scrollbar
+controlling an Emacs window.)
@end table
-Keywords accepted as menu item specs are also accepted by widgets.
-These are @code{:selected}, @code{:active}, @code{:suffix},
-@code{:keys}, @code{:style}, @code{:filter}, @code{:config},
-@code{:included}, @code{:key-sequence}, @code{:accelerator},
-@code{:label} and @code{:callback}.
-
-If instead of a vector, the instantiator is a string, it will be
-converted into a vector by looking it up according to the specs in the
-@code{console-type-image-conversion-list} for the console type of
-the domain (usually a window; sometimes a frame or device) over which
-the image is being instantiated.
-
-If the instantiator specifies data from a file, the data will be read in
-at the time that the instantiator is added to the image specifier (which
-may be well before the image is actually displayed), and the
-instantiator will be converted into one of the inline-data forms, with
-the filename retained using a @code{:file} keyword. This implies that
-the file must exist when the instantiator is added to the image, but
-does not need to exist at any other time (e.g. it may safely be a
-temporary file).
-
-@defun valid-image-instantiator-format-p format
-This function returns non-@code{nil} if @var{format} is a valid image
-instantiator format. Note that the return value for many formats listed
-above depends on whether XEmacs was compiled with support for that format.
-@end defun
-
-@defun image-instantiator-format-list
-This function return a list of valid image-instantiator formats.
-@end defun
-
-@defvar xpm-color-symbols
-This variable holds definitions of logical color-names used when reading
-XPM files. Elements of this list should be of the form
-@code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name}
-should be a string, which is the name of the color to define; the
-@var{form-to-evaluate} should evaluate to a color specifier object, or a
-string to be passed to @code{make-color-instance} (@pxref{Colors}). If
-a loaded XPM file references a symbolic color called @var{color-name},
-it will display as the computed color instead.
-
-The default value of this variable defines the logical color names
-@samp{"foreground"} and @samp{"background"} to be the colors of the
-@code{default} face.
-@end defvar
-
-@defvar x-bitmap-file-path
-A list of the directories in which X bitmap files may be found. If nil,
-this is initialized from the @samp{"*bitmapFilePath"} resource. This is
-used by the @code{make-image-instance} function (however, note that if
-the environment variable @samp{XBMLANGPATH} is set, it is consulted
-first).
-@end defvar
-
-@node Image Instantiator Conversion
-@subsection Image Instantiator Conversion
-@cindex image instantiator conversion
-@cindex conversion of image instantiators
-@defun set-console-type-image-conversion-list console-type list
-This function sets the image-conversion-list for consoles of the given
-@var{console-type}. The image-conversion-list specifies how image
-instantiators that are strings should be interpreted. Each element of
-the list should be a list of two elements (a regular expression string
-and a vector) or a list of three elements (the preceding two plus an
-integer index into the vector). The string is converted to the vector
-associated with the first matching regular expression. If a vector
-index is specified, the string itself is substituted into that position
-in the vector.
+@node Subwindows
+@subsection Subwindows
-Note: The conversion above is applied when the image instantiator is
-added to an image specifier, not when the specifier is actually
-instantiated. Therefore, changing the image-conversion-list only affects
-newly-added instantiators. Existing instantiators in glyphs and image
-specifiers will not be affected.
-@end defun
+Subwindows are not currently implemented.
+@c #### Check status of subwindows ... I thought Andy implemented them.
-@defun console-type-image-conversion-list console-type
-This function returns the image-conversion-list for consoles of the given
-@var{console-type}.
+@defun subwindowp object
+This function returns non-@code{nil} if @var{object} is a subwindow.
@end defun
-@node Image Instances
-@subsection Image Instances
-@cindex image instances
-
- Image-instance objects encapsulate the way a particular image (pixmap,
-etc.) is displayed on a particular device.
- In most circumstances, you do not need to directly create image
-instances; use a glyph instead. However, it may occasionally be useful
-to explicitly create image instances, if you want more control over the
-instantiation process.
+@node Manipulating Glyphs
+@section Manipulating Glyphs
-@defun image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image instance.
-@end defun
+ Each glyphs has properties that may be accessed. Most of these can
+also be set after the glyph is initialized, with the exception of the
+glyph's type. This is not a real restriction, as it is almost never
+useful to create glyphs of types other than @code{buffer}.
@menu
-* Image Instance Types:: Each image instances has a particular type.
-* Image Instance Functions:: Functions for working with image instances.
+* Glyph Properties:: Accessing and modifying a glyph's properties.
+* Glyph Convenience Functions:: Accessing particular properties of a glyph.
+* Glyph Dimensions:: Determining the height, width, etc. of a glyph.
+* Glyph Types:: Each glyph has a particular type.
@end menu
-@node Image Instance Types
-@subsubsection Image Instance Types
-@cindex image instance types
- Image instances come in a number of different types. The type
-of an image instance specifies the nature of the image: Whether
-it is a text string, a mono pixmap, a color pixmap, etc.
+@node Glyph Properties
+@subsection Glyph Properties
- The valid image instance types are
+Each glyph has a list of properties, which control all of the aspects of
+the glyph's appearance. The following symbols have predefined meanings:
@table @code
-@item nothing
-Nothing is displayed.
+@item image
+The image used to display the glyph.
-@item text
-Displayed as text. The foreground and background colors and the
-font of the text are specified independent of the pixmap. Typically
-these attributes will come from the face of the surrounding text,
-unless a face is specified for the glyph in which the image appears.
+@item baseline
+Percent above baseline that glyph is to be displayed. Only for glyphs
+displayed inside of a buffer.
-@item mono-pixmap
-Displayed as a mono pixmap (a pixmap with only two colors where the
-foreground and background can be specified independent of the pixmap;
-typically the pixmap assumes the foreground and background colors of
-the text around it, unless a face is specified for the glyph in which
-the image appears).
-@item color-pixmap
+@item contrib-p
+Whether the glyph contributes to the height of the line it's on.
+Only for glyphs displayed inside of a buffer.
-Displayed as a color pixmap.
+@item face
+Face of this glyph (@emph{not} a specifier).
+@end table
-@item pointer
-Used as the mouse pointer for a window.
+@defun set-glyph-property glyph property value &optional locale tag-set how-to-add
+This function changes a property of a @var{glyph}.
-@item subwindow
-A child window that is treated as an image. This allows (e.g.)
-another program to be responsible for drawing into the window.
-Not currently implemented.
-@end table
+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.
-@defun valid-image-instance-type-p type
-This function returns non-@code{nil} if @var{type} is a valid image
-instance type.
-@end defun
+If @var{property} is a built-in property, the specifications to be added
+to this property can be supplied in many different ways:
-@defun image-instance-type-list
-This function returns a list of the valid image instance types.
-@end defun
+@itemize @bullet
+@item
+If @var{value} is a simple instantiator (e.g. a string naming a pixmap
+filename) or a list of instantiators, then the instantiator(s) will be
+added as a specification of the property for the given @var{locale}
+(which defaults to @code{global} if omitted).
-@defun image-instance-type image-instance
-This function returns the type of the given image instance. The return
-value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
-@code{color-pixmap}, @code{pointer}, or @code{subwindow}.
-@end defun
+@item
+If @var{value} is a list of specifications (each of which is a cons of a
+locale and a list of instantiators), then @var{locale} must be
+@code{nil} (it does not make sense to explicitly specify a locale in
+this case), and specifications will be added as given.
-@defun text-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{text}.
-@end defun
+@item
+If @var{value} is a specifier (as would be returned by
+@code{glyph-property} if no @var{locale} argument is given), then some
+or all of the specifications in the specifier will be added to the
+property. In this case, the function is really equivalent to
+@code{copy-specifier} and @var{locale} has the same semantics (if it is
+a particular locale, the specification for the locale will be copied; if
+a locale type, specifications for all locales of that type will be
+copied; if @code{nil} or @code{all}, then all specifications will be
+copied).
+@end itemize
-@defun mono-pixmap-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{mono-pixmap}.
-@end defun
+@var{how-to-add} should be either @code{nil} or one of the symbols
+@code{prepend}, @code{append}, @code{remove-tag-set-prepend},
+@code{remove-tag-set-append}, @code{remove-locale},
+@code{remove-locale-type}, or @code{remove-all}. See
+@code{copy-specifier} and @code{add-spec-to-specifier} for a description
+of what each of these means. Most of the time, you do not need to worry
+about this argument; the default behavior usually is fine.
-@defun color-pixmap-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{color-pixmap}.
-@end defun
+In general, it is OK to pass an instance object (e.g. as returned by
+@code{glyph-property-instance}) as an instantiator in place of an actual
+instantiator. In such a case, the instantiator used to create that
+instance object will be used (for example, if you set a font-instance
+object as the value of the @code{font} property, then the font name used
+to create that object will be used instead). 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.
-@defun pointer-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{pointer}.
+If @var{property} is not a built-in property, then this function will
+simply set its value if @var{locale} is @code{nil}. However, if
+@var{locale} is given, then this function will attempt to add
+@var{value} as the instantiator for the given @var{locale}, using
+@code{add-spec-to-specifier}. If the value of the property is not a
+specifier, it will automatically be converted into a @code{generic}
+specifier.
@end defun
-@defun subwindow-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{subwindow}.
-@end defun
+@defun glyph-property glyph property &optional locale
+This function returns @var{glyph}'s value of the given @var{property}.
-@defun nothing-image-instance-p object
-This function returns non-@code{nil} if @var{object} is an image
-instance of type @code{nothing}.
-@end defun
+If @var{locale} is omitted, the @var{glyph}'s actual value for
+@var{property} will be returned. For built-in properties, this will be
+a specifier object of a type appropriate to the property (e.g. a font or
+color specifier). For other properties, this could be anything.
-@defun widget-image-instance-p object
-Return t if @var{object} is an image instance of type @code{widget}.
+If @var{locale} is supplied, then instead of returning the actual value,
+the specification(s) for the given locale or locale type will be
+returned. This will only work if the actual value of @var{property} is
+a specifier (this will always be the case for built-in properties, but
+may or may not apply to user-defined properties). If the actual value
+of @var{property} is not a specifier, this value will simply be returned
+regardless of @var{locale}.
+
+The return value will be a list of instantiators (e.g. vectors
+specifying pixmap data), or a list of specifications, each of which is a
+cons of a locale and a list of instantiators. Specifically, if
+@var{locale} is a particular locale (a buffer, window, frame, device, or
+@code{global}), a list of instantiators for that locale will be
+returned. Otherwise, if @var{locale} is a locale type (one of the
+symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
+the specifications for all locales of that type will be returned.
+Finally, if @var{locale} is @code{all}, the specifications for all
+locales of all types will be returned.
+
+The specifications in a specifier determine what the value of
+@var{property} will be in a particular @dfn{domain} or set of
+circumstances, which is typically a particular Emacs window along with
+the buffer it contains and the frame and device it lies within. The
+value is derived from the instantiator associated with the most specific
+locale (in the order buffer, window, frame, device, and @code{global})
+that matches the domain in question. In other words, given a domain
+(i.e. an Emacs window, usually), the specifier for @var{property} will
+first be searched for a specification whose locale is the buffer
+contained within that window; then for a specification whose locale is
+the window itself; then for a specification whose locale is the frame
+that the window is contained within; etc. The first instantiator that
+is valid for the domain (usually this means that the instantiator is
+recognized by the device [i.e. the X server or TTY device] that the
+domain is on). The function @code{glyph-property-instance} actually does
+all this, and is used to determine how to display the glyph.
@end defun
-@node Image Instance Functions
-@subsubsection Image Instance Functions
+@defun glyph-property-instance glyph property &optional domain default no-fallback
+This function returns the instance of @var{glyph}'s @var{property} in the
+specified @var{domain}.
-@defun make-image-instance data &optional domain dest-types no-error
-This function creates a new image-instance object.
+Under most circumstances, @var{domain} will be a particular window, and
+the returned instance describes how the specified property actually is
+displayed for that window and the particular buffer in it. Note that
+this may not be the same as how the property appears when the buffer is
+displayed in a different window or frame, or how the property appears in
+the same window if you switch to another buffer in that window; and in
+those cases, the returned instance would be different.
-@var{data} is an image instantiator, which describes the image
-(@pxref{Image Specifiers}).
+The returned instance is an image-instance object, and you can query it
+using the appropriate image instance functions. For example, you could use
+@code{image-instance-depth} to find out the depth (number of color
+planes) of a pixmap displayed in a particular window. The results might
+be different from the results you would get for another window (perhaps
+the user specified a different image for the frame that window is on; or
+perhaps the same image was specified but the window is on a different X
+server, and that X server has different color capabilities from this
+one).
-@var{dest-types} should be a list of allowed image instance types that
-can be generated. The @var{dest-types} list is unordered. If multiple
-destination types are possible for a given instantiator, the ``most
-natural'' type for the instantiator's format is chosen. (For XBM, the
-most natural types are @code{mono-pixmap}, followed by
-@code{color-pixmap}, followed by @code{pointer}. For the other normal
-image formats, the most natural types are @code{color-pixmap}, followed
-by @code{mono-pixmap}, followed by @code{pointer}. For the string and
-formatted-string formats, the most natural types are @code{text},
-followed by @code{mono-pixmap} (not currently implemented), followed by
-@code{color-pixmap} (not currently implemented). For MS Windows
-resources, the most natural type for pointer resources is
-@code{pointer}, and for the others it's @code{color-pixmap}. The other
-formats can only be instantiated as one type. (If you want to control
-more specifically the order of the types into which an image is
-instantiated, just call @code{make-image-instance} repeatedly until it
-succeeds, passing less and less preferred destination types each time.
+@var{domain} defaults to the selected window if omitted.
-If @var{dest-types} is omitted, all possible types are allowed.
+@var{domain} can be a frame or device, instead of a window. The value
+returned for such a domain is used in special circumstances when a
+more specific domain does not apply; for example, a frame value might be
+used for coloring a toolbar, which is conceptually attached to a frame
+rather than a particular window. The value is also useful in
+determining what the value would be for a particular window within the
+frame or device, if it is not overridden by a more specific
+specification.
-@var{domain} specifies the domain to which the image instance will be
-attached. This domain is termed the @dfn{governing domain}. The type
-of the governing domain depends on the image instantiator
-format. (Although, more correctly, it should probably depend on the
-image instance type.) For example, pixmap image instances are specific
-to a device, but widget image instances are specific to a particular
-XEmacs window because in order to display such a widget when two windows
-onto the same buffer want to display the widget, two separate underlying
-widgets must be created. (That's because a widget is actually a child
-window-system window, and all window-system windows have a unique
-existence on the screen.) This means that the governing domain for a
-pixmap image instance will be some device (most likely, the only
-existing device), whereas the governing domain for a widget image
-instance will be some XEmacs window.
+If @var{property} does not name a built-in property, its value will
+simply be returned unless it is a specifier object, in which case it
+will be instanced using @code{specifier-instance}.
-If you specify an overly general @var{domain} (e.g. a frame when a
-window was wanted), an error is signaled. If you specify an overly
-specific @var{domain} (e.g. a window when a device was wanted), the
-corresponding general domain is fetched and used instead. For
-@code{make-image-instance}, it makes no difference whether you specify
-an overly specific domain or the properly general domain derived from
-it. However, it does matter when creating an image instance by
-instantiating a specifier or glyph (e.g. with
-@code{glyph-image-instance}), because the more specific domain causes
-spec lookup to start there and proceed to more general domains. (It
-would also matter when creating an image instance with an instantiator
-format of @code{inherit}, but we currently disallow this. #### We should
-fix this.)
-n
-If omitted, @var{domain} defaults to the selected window.
+Optional arguments @var{default} and @var{no-fallback} are the same as
+in @code{specifier-instance}. @xref{Specifiers}.
+@end defun
-@var{no-error} controls what happens when the image cannot be generated.
-If @var{nil}, an error message is generated. If @var{t}, no messages
-are generated and this function returns @var{nil}. If anything else, a
-warning message is generated and this function returns @var{nil}.
+@defun remove-glyph-property glyph property &optional locale tag-set exact-p
+This function removes a property from a glyph. For built-in properties,
+this is analogous to @code{remove-specifier}. @xref{Specifiers,
+remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
+and @var{exact-p} arguments.
@end defun
-@defun colorize-image-instance image-instance foreground background
-This function makes the image instance be displayed in the given
-colors. Image instances come in two varieties: bitmaps, which are 1
-bit deep which are rendered in the prevailing foreground and background
-colors; and pixmaps, which are of arbitrary depth (including 1) and
-which have the colors explicitly specified. This function converts a
-bitmap to a pixmap. If the image instance was a pixmap already,
-nothing is done (and @code{nil} is returned). Otherwise @code{t} is
-returned.
+
+@node Glyph Convenience Functions
+@subsection Glyph Convenience Functions
+
+ The following functions are provided for working with specific
+properties of a glyph. Note that these are exactly like calling
+the general functions described above and passing in the
+appropriate value for @var{property}.
+
+ Remember that if you want to determine the ``value'' of a
+specific glyph property, you probably want to use the @code{*-instance}
+functions. For example, to determine whether a glyph contributes
+to its line height, use @code{glyph-contrib-p-instance}, not
+@code{glyph-contrib-p}. (The latter will return a boolean specifier
+or a list of specifications, and you probably aren't concerned with
+these.)
+
+@defun glyph-image glyph &optional locale
+This function is equivalent to calling @code{glyph-property} with
+a property of @code{image}. The return value will be an image
+specifier if @var{locale} is @code{nil} or omitted; otherwise,
+it will be a specification or list of specifications.
@end defun
-@defun image-instance-name image-instance
-This function returns the name of the given image instance.
+@defun set-glyph-image glyph spec &optional locale tag-set how-to-add
+This function is equivalent to calling @code{set-glyph-property} with
+a property of @code{image}.
@end defun
-@defun image-instance-domain image-instance
+@defun glyph-image-instance glyph &optional domain default no-fallback
+This function returns the instance of @var{glyph}'s image in the given
+@var{domain}, and is equivalent to calling
+@code{glyph-property-instance} with a property of @code{image}. The
+return value will be an image instance.
-Return the governing domain of the given @var{image-instance}. The
-governing domain of an image instance is the domain that the image
-instance is specific to. It is @emph{NOT} necessarily the domain that
-was given to the call to @code{specifier-instance} that resulted in the
-creation of this image instance. See @code{make-image-instance} for
-more information on governing domains.
+Normally @var{domain} will be a window or @code{nil} (meaning the
+selected window), and an instance object describing how the image
+appears in that particular window and buffer will be returned.
+@end defun
+
+@defun glyph-contrib-p glyph &optional locale
+This function is equivalent to calling @code{glyph-property} with
+a property of @code{contrib-p}. The return value will be a boolean
+specifier if @var{locale} is @code{nil} or omitted; otherwise,
+it will be a specification or list of specifications.
@end defun
+@defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
+This function is equivalent to calling @code{set-glyph-property} with
+a property of @code{contrib-p}.
+@end defun
-@defun image-instance-string image-instance
-This function returns the string of the given image instance. This will
-only be non-@code{nil} for text image instances.
+@defun glyph-contrib-p-instance glyph &optional domain default no-fallback
+This function returns whether the glyph contributes to its line height
+in the given @var{domain}, and is equivalent to calling
+@code{glyph-property-instance} with a property of @code{contrib-p}. The
+return value will be either @code{nil} or @code{t}. (Normally @var{domain}
+will be a window or @code{nil}, meaning the selected window.)
@end defun
-@defun image-instance-file-name image-instance
-This function returns the file name from which @var{image-instance} was
-read, if known.
+@defun glyph-baseline glyph &optional locale
+This function is equivalent to calling @code{glyph-property} with a
+property of @code{baseline}. The return value will be a specifier if
+@var{locale} is @code{nil} or omitted; otherwise, it will be a
+specification or list of specifications.
@end defun
-@defun image-instance-mask-file-name image-instance
-This function returns the file name from which @var{image-instance}'s
-mask was read, if known.
+@defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
+This function is equivalent to calling @code{set-glyph-property} with
+a property of @code{baseline}.
@end defun
-@defun 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.
+@defun glyph-baseline-instance glyph &optional domain default no-fallback
+This function returns the instance of @var{glyph}'s baseline value in
+the given @var{domain}, and is equivalent to calling
+@code{glyph-property-instance} with a property of @code{baseline}. The
+return value will be an integer or @code{nil}.
+
+Normally @var{domain} will be a window or @code{nil} (meaning the
+selected window), and an instance object describing the baseline value
+appears in that particular window and buffer will be returned.
@end defun
-@defun image-instance-height image-instance
-This function returns the height of the image instance, in pixels.
+@defun glyph-face glyph
+This function returns the face of @var{glyph}. (Remember, this is
+not a specifier, but a simple property.)
@end defun
-@defun image-instance-width image-instance
-This function returns the width of the image instance, in pixels.
+@defun set-glyph-face glyph face
+This function changes the face of @var{glyph} to @var{face}.
@end defun
-@defun image-instance-hotspot-x image-instance
-This function returns the X coordinate of the image instance's hotspot,
-if known. This is a point relative to the origin of the pixmap. When
-an image is used as a mouse pointer, the hotspot is the point on the
-image that sits over the location that the pointer points to. This is,
-for example, the tip of the arrow or the center of the crosshairs.
-This will always be @code{nil} for a non-pointer image instance.
+@node Glyph Dimensions
+@subsection Glyph Dimensions
+
+@defun glyph-width glyph &optional window
+This function returns the width of @var{glyph} on @var{window}. This
+may not be exact as it does not take into account all of the context
+that redisplay will.
@end defun
-@defun image-instance-hotspot-y image-instance
-This function returns the Y coordinate of the image instance's hotspot,
-if known.
+@defun glyph-ascent glyph &optional window
+This function returns the ascent value of @var{glyph} on @var{window}.
+This may not be exact as it does not take into account all of the
+context that redisplay will.
@end defun
-@defun image-instance-foreground image-instance
-This function returns the foreground color of @var{image-instance}, if
-applicable. This will be a color instance or @code{nil}. (It will only
-be non-@code{nil} for colorized mono pixmaps and for pointers.)
+@defun glyph-descent glyph &optional window
+This function returns the descent value of @var{glyph} on @var{window}.
+This may not be exact as it does not take into account all of the
+context that redisplay will.
@end defun
-@defun image-instance-background image-instance
-This function returns the background color of @var{image-instance}, if
-applicable. This will be a color instance or @code{nil}. (It will only
-be non-@code{nil} for colorized mono pixmaps and for pointers.)
+@defun glyph-height glyph &optional window
+This function returns the height of @var{glyph} on @var{window}. (This
+is equivalent to the sum of the ascent and descent values.) This may
+not be exact as it does not take into account all of the context that
+redisplay will.
@end defun
@node Glyph Types
-@section Glyph Types
+@subsection Glyph Types
Each glyph has a particular type, which controls how the glyph's image
is generated. Each glyph type has a corresponding list of allowable
extent, in the modeline, and in the toolbar. Their image can be
instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
@code{text}, and @code{subwindow}.
+@c #### Check status of subwindows ... I thought Andy implemented them.
@item
@code{pointer} glyphs can be used to specify the mouse pointer. Their
@code{pointer}.
@end defun
-@node Mouse Pointer
-@section Mouse Pointer
-@cindex mouse cursor
-@cindex cursor (mouse)
-@cindex pointer (mouse)
-@cindex mouse pointer
-The shape of the mouse pointer when over a particular section of a frame
-is controlled using various glyph variables. Since the image of a glyph
-is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
-or per-device basis.
+@node Glyph Examples
+@section Glyph Examples
-You should use @code{set-glyph-image} to set the following variables,
-@emph{not} @code{setq}.
+For many applications, displaying graphics is a simple process: you
+create a glyph, and then you insert it into a buffer.
-@defvr Glyph text-pointer-glyph
-This variable specifies the shape of the mouse pointer when over text.
-@end defvr
+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:
-@defvr Glyph nontext-pointer-glyph
-This variable specifies the shape of the mouse pointer when over a
-buffer, but not over text. If unspecified in a particular domain,
-@code{text-pointer-glyph} is used.
-@end defvr
+@lisp
+;; Create a glyph from a JPEG file:
+(setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+@end lisp
-@defvr Glyph modeline-pointer-glyph
-This variable specifies the shape of the mouse pointer when over the modeline.
-If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
-@end defvr
+@lisp
+;; Create a glyph from a XPM file:
+(setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
+@end lisp
-@defvr Glyph selection-pointer-glyph
-This variable specifies the shape of the mouse pointer when over a
-selectable text region. If unspecified in a particular domain,
-@code{text-pointer-glyph} is used.
-@end defvr
+@lisp
+;; Create a glyph from a PNG file:
+(setq foo (make-glyph [png :file "/tmp/file3.png"]))
+@end lisp
-@defvr Glyph gc-pointer-glyph
-This variable specifies the shape of the mouse pointer when a garbage
-collection is in progress. If the selected window is on a window system
-and this glyph specifies a value (i.e. a pointer image instance) in the
-domain of the selected window, the pointer will be changed as specified
-during garbage collection. Otherwise, a message will be printed in the
-echo area, as controlled by @code{gc-message}.
-@end defvr
+@lisp
+;; Create a glyph from a TIFF file:
+(setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
+@end lisp
-@defvr Glyph busy-pointer-glyph
-This variable specifies the shape of the mouse pointer when XEmacs is busy.
-If unspecified in a particular domain, the pointer is not changed
-when XEmacs is busy.
-@end defvr
+The parameters passed to @code{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.
+@xref{Image Specifiers}, for more information.
-@defvr Glyph menubar-pointer-glyph
-This variable specifies the shape of the mouse pointer when over the
-menubar. If unspecified in a particular domain, the
-window-system-provided default pointer is used.
-@end defvr
+@quotation
+@strong{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 @kbd{M-x describe-installation}.
-@defvr Glyph scrollbar-pointer-glyph
-This variable specifies the shape of the mouse pointer when over a
-scrollbar. If unspecified in a particular domain, the
-window-system-provided default pointer is used.
-@end defvr
+To programmatically query whether or not a particular file format is
+supported, you can use the @code{featurep} function, with one of:
+@code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm},
+@code{png}, or @code{xface}. For an up-to-date list, @ref{Image
+Specifiers}. Example:
-@defvr Glyph toolbar-pointer-glyph
-This variable specifies the shape of the mouse pointer when over a
-toolbar. If unspecified in a particular domain,
-@code{nontext-pointer-glyph} is used.
-@end defvr
+@example
+;; Returns `t' if TIFF is supported:
+(featurep 'tiff)
+@end example
-Internally, these variables are implemented in
-@code{default-mouse-motion-handler}, and thus only take effect when the
-mouse moves. That function calls @code{set-frame-pointer}, which sets
-the current mouse pointer for a frame.
+Another example is:
-@defun set-frame-pointer frame image-instance
-This function sets the mouse pointer of @var{frame} to the given pointer
-image instance. You should not call this function directly.
-(If you do, the pointer will change again the next time the mouse moves.)
-@end defun
+@example
+;; 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))
+@end example
-@node Redisplay Glyphs
-@section Redisplay Glyphs
+@end quotation
+
+Once you have a glyph, you can then insert it into a buffer. Example:
+
+@lisp
+;; 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"]))
+ )
+
+@end lisp
+
+Here are the gory details:
-@defvr Glyph truncation-glyph
-This variable specifies what is displayed at the end of truncated lines.
-@end defvr
+@itemize @bullet
-@defvr Glyph continuation-glyph
-This variable specifies what is displayed at the end of wrapped lines.
-@end defvr
+@item
+Glyphs are displayed by attaching them to extents (see @ref{Extents}),
+either to the beginning or the end of extents.
-@defvr Glyph octal-escape-glyph
-This variable specifies what to prefix character codes displayed in octal
-with.
-@end defvr
+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.
-@defvr Glyph hscroll-glyph
-This variable specifies what to display at the beginning of horizontally
-scrolled lines.
-@end defvr
+@item
+Glyphs are often displayed inside the text area (alongside text). This
+is the default.
-@defvr Glyph invisible-text-glyph
-This variable specifies what to use to indicate the presence of
-invisible text. This is the glyph that is displayed when an ellipsis is
-called for, according to @code{selective-display-ellipses} or
-@code{buffer-invisibility-spec}). Normally this is three dots (``...'').
-@end defvr
+Although glyphs can also be displayed in the margins, how to do this
+will not be described here. For more information on this, see
+@ref{Annotation Basics} (look for information on "layout types") and
+@ref{Extent Properties} (look for @code{begin-glyph-layout} and
+@code{end-glyph-layout}).
-@defvr Glyph control-arrow-glyph
-This variable specifies what to use as an arrow for control characters.
-@end defvr
+@item
+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.
-@node Subwindows
-@section Subwindows
+Note that zero-length extents are attached to the character to the
+right of the extent; deleting this character will also delete the extent.
-Subwindows are not currently implemented.
+@item
+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 @code{extent-list} or @code{next-extent}, or provide additional
+parameters to the @code{extent-at} function. Assigning a unique
+property to the extent makes it easy to locate your extents; for
+example, @code{extent-list} can return only those extents with a
+particular property. @xref{Finding Extents}, and @ref{Mapping Over
+Extents}, for more information.
-@defun subwindowp object
-This function returns non-@code{nil} if @var{object} is a subwindow.
-@end defun
+@item
+Glyphs are displayed by assigning then to the @code{begin-glyph} or
+@code{end-glyph} property of the extent. For zero-length extents, it
+doesn't really matter if you assign the glyph to the @code{begin-glyph}
+or @code{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 @code{nil} to the @code{begin-glyph} or @code{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.
+
+@item
+If you happen to insert two glyphs, side-by-side, note that the example
+@code{insert-glyph} function will have trouble, if it's again used at
+the same point (it can only locate one of the two extents).
+@xref{Finding Extents}, and @ref{Mapping Over Extents}, for more
+information on locating extents in a buffer.
+
+@item
+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.
+
+@end itemize
projects / chise / xemacs-chise.git.1 / blobdiff