update.
[chise/xemacs-chise.git-] / man / lispref / glyphs.texi
1 @c -*-texinfo-*-
2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1995, 1996 Ben Wing.
4 @c Copyright (C) 2004 Free Software Foundation, Inc.
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/glyphs.info
7 @node Glyphs, Annotations, Faces and Window-System Objects, top
8 @chapter Glyphs
9 @cindex glyphs
10
11   A @dfn{glyph} is an object that is used for pixmaps, widgets, and
12 images of all sorts, as well as for things that ``act'' like pixmaps,
13 such as non-textual strings (@dfn{annotations}) displayed in a buffer or
14 in the margins.  It is used in begin-glyphs and end-glyphs attached to
15 extents, marginal and textual annotations, overlay arrows
16 (@code{overlay-arrow-*} variables), toolbar buttons, mouse pointers,
17 frame icons, truncation and continuation markers, and the
18 like.  Basically, any place there is an image or something that acts
19 like an image, there will be a glyph object representing it.
20
21 @defun glyphp object
22 This function returns @code{t} if @var{object} is a glyph.
23 @end defun
24
25 @menu
26 * Glyph Intro::         Glyphs are abstract image specifications.
27 * Images::              Specifying the appearance of glyphs.
28 * Using Glyphs::        Creating and displaying glyphs.
29 * Manipulating Glyphs:: Getting and setting glyph properties.
30 * Glyph Examples::      Examples of how to work with glyphs.
31 @end menu
32
33
34 @node Glyph Intro
35 @section Glyph Introduction
36
37   In XEmacs, ``glyph'' does @strong{not} refer to a single unit of textual
38 display (the XEmacs term for that is @dfn{rune}, and runes are confined
39 to the internal implementation of redisplay), but rather is an
40 object encapsulating a graphical element, such as an image or widget (an
41 active GUI element such as a button or text entry field; X11 calls this a
42 @dfn{widget}, while MS Windows uses the term @dfn{control}).
43 This graphical element could appear in a buffer, a margin, a gutter, or
44 a toolbar, or even externally to XEmacs as a mouse pointer or an icon,
45 for example.
46
47   On the other hand, by contrast with GNU Emacs 21, an XEmacs glyph is
48 not ``just'' an image.  The actual image that is displayed (as opposed
49 to its position or clipping) is defined by an ``image specifier'' object
50 contained within the glyph.  The separation between an image specifier
51 object and a glyph object is made because the glyph includes other
52 properties than just the actual image: e.g. the face it is displayed in,
53 the alignment of the image, @emph{etc}.  Also, an image specifier is
54 used in at least one place in XEmacs in lieu of a glyph, namely the
55 backing pixmap of a face.
56
57   An image specifier is used because glyphs often have locale-specific
58 semantics.  The most important example is semantics determined by the
59 display device: you can't usefully display a JPEG on stdout, or a color
60 image on a monochrome display.  But because the image property is a
61 specifier in XEmacs, you can specify that a given glyph appear as a
62 monochrome image on monochrome displays, a color image on color
63 displays, and as a string on TTYs.  (Specifying a string for the
64 @code{tty} device locale would give behavior like the @code{ALT}
65 attribute of an @code{IMG} element in HTML.)  Another is semantics
66 determined by the buffer or mode.  (Unfortunately, currently there are
67 no compelling examples of this for glyphs.)
68
69   All this means that only one global glyph needs to exist for a
70 particular purpose (e.g. the icon used to represent an iconified frame,
71 the mouse pointer used over particular areas of a frame, etc.).  Often
72 you need not (and should not!) create your own glyph, but rather modify
73 an existing one.
74
75   In working with glyphs it is important to keep in mind the distinction
76 between a locale and a domain.  A @dfn{locale} is specified by the
77 programmer, and is an abstract link between a specification (for a
78 glyph, its visual appearance) and a displayable object.  The displayable
79 object may be a buffer or a window, or an object containing buffers or
80 windows such as frame, device, or console.  A @dfn{domain} is an actual
81 display context, which must be concrete enough to enable XEmacs to
82 identify the device type.  (Buffers may be displayed in windows on
83 different devices, even simultaneously, so a buffer cannot be a domain.
84 Similarly, the global locale cannot be a domain.)  @ref{Specifiers}, for
85 more information about specifier locales and domains.
86
87
88 @node Images
89 @section Images
90
91 @menu
92 * Image Specifiers::                    Specifying an image's appearance.
93 * Image Instantiator Conversion::       Lazy realization of graphics.
94 * Image Instantiator Formats::          A catalog of image descriptors.
95 * Image Instances::                     Classes of graphical objects.
96 @end menu
97
98
99 @node Image Specifiers
100 @subsection Image Specifiers
101 @cindex image specifiers
102
103   An image specifier is a description of the actual graphical
104 realization of a glyph.  For example, a typical image description is
105 @emph{the file system path to a PNG file}.  Since redisplay doesn't know
106 about files, and in any case the image may need to be manipulated
107 (@emph{e.g.}, a face's background pixmap must be clipped and tiled), the
108 PNG file must be converted internally to a window system bitmap or
109 pixmap object.  We describe this process by writing that when XEmacs
110 displays the image, it @dfn{instantiates} the @dfn{image instantiator}
111 into an @dfn{image instance}.  Image instances are an internal object
112 type (similar to font instances and color instances), describing how the
113 image appears in a particular domain.  On the other hand, image
114 instantiators, which are just descriptions of how the image should
115 appear, are represented using Lisp strings or vectors.
116
117 Furthermore the graphical realization will vary, and for some devices
118 may not even be a bitmapped graphic.  These variations may be controlled
119 by the program by specifying different @dfn{image instantiators} in
120 different locales.  This is implemented with an @dfn{image specifier},
121 a specifier whose specifications are image instantiators.
122
123 Image specifiers are rarely if ever found by themselves.  However, an
124 image specifier results from calling @code{glyph-image} on a glyph, or
125 retrieving the @code{background-pixmap} property of a face, and you can
126 check if some random object is an image specifier.
127
128 @defun image-specifier-p object
129 This function returns non-@code{nil} if @var{object} is an image specifier.
130 @end defun
131
132 @defun make-image-specifier spec-list
133 This function creates a new image specifier object and initializes it
134 according to @var{spec-list}.  @xref{Specifiers}.
135 @end defun
136
137 This function exists mainly for completeness.  In practice, you rarely,
138 if ever, need to actually create an image specifier.  Instead, they are
139 implicitly created by the initialization of glyphs and faces, and the
140 specifier member of these objects cannot be changed after
141 initialization; you may only set the specifications it contains.
142
143 Image instantiators come in many formats: @code{xbm}, @code{xpm},
144 @code{gif}, @code{jpeg}, etc.  These denote the format of the data
145 describing the image.  The resulting image instances also come in many
146 types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
147 @code{pointer}, etc.  This refers to the behavior of the image and the
148 sorts of places it can appear. (For example, a color-pixmap image has
149 fixed colors specified for it, while a mono-pixmap image comes in two
150 unspecified shades ``foreground'' and ``background'' that are determined
151 from the face of the glyph or surrounding text; a text image appears as
152 a string of text and has an unspecified foreground, background, and
153 font; a pointer image behaves like a mono-pixmap image but can only be
154 used as a mouse pointer [mono-pixmap images cannot be used as mouse
155 pointers]; etc.)
156
157 It is important to keep the distinction between image instantiator
158 format and image instance type in mind.  Typically, a given image
159 instantiator format can result in many different image instance types.
160 For example, @code{xpm} can be instanced as @code{color-pixmap},
161 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
162 instanced only as @code{pointer}.  On the other hand, a particular image
163 instance type can be generated by many different image instantiator
164 formats (e.g.  @code{color-pixmap} can be generated by @code{xpm},
165 @code{gif}, @code{jpeg}, etc.).
166
167   @xref{Image Instances}, for a more detailed discussion of image
168 instance types.
169
170  An image instantiator should be a string or a vector of the form
171
172 @example
173  @code{[@var{format} @var{:keyword} @var{value} ...]}
174 @end example
175
176 i.e. a format symbol followed by zero or more alternating keyword-value
177 pairs.
178
179 The form of an instantiator can be checked with
180 @code{valid-instantiator-p} with a @var{TYPE} of @code{image},
181 @ref{Specifier Validation Functions}.
182
183 For a complete list of the format symbols and their usage,
184 @ref{Image Instantiator Formats}.
185
186 If the instantiator is a string, it will be converted into a vector by
187 looking it up according to the specs in the
188 @code{console-type-image-conversion-list} for the console type of the
189 domain (usually a window; sometimes a frame or device) over which the
190 image is being instantiated.
191
192 If the instantiator specifies data from a file, the data will be read in
193 at the time that the instantiator is added to the image specifier (which
194 may be well before the image is actually displayed), and the
195 instantiator will be converted into one of the inline-data forms, with
196 the filename retained using a @code{:file} keyword.  This implies that
197 the file must exist when the instantiator is added to the image, but
198 does not need to exist at any other time (e.g. it may safely be a
199 temporary file).
200
201 The available keywords are given below.  Note that some keywords are
202 generally available (for example, the @code{:data} keyword may be used
203 with any format except @code{nothing}), while others are only available
204 for one format (@code{resource-id} is unique to the
205 @code{mswindows-resource} format).
206
207 @table @code
208 @item :data
209 Inline image data.  If available for a given format, it may be specified
210 directly by the program, or it may be a cache of file data previously
211 read.  When present, it is used to instantiate the image in preference
212 to the file named by the @code{:file} property.
213
214 The format of inline data is image-format-specific.  For example, in
215 pixmap formats, the value should be a string, which is interpreted as an
216 octet-stream representing a bitmap or pixmap.  But for text formats,
217 it's string containing the text to be displayed, and for resource
218 formats, it's a string containing the name of the resource.
219
220 @item :file
221 Data contained in a file.  The value is the name of this file.  If both
222 @code{:data} and @code{:file} are specified, the image is created from
223 what is specified in @code{:data} and the string in @code{:file} becomes
224 the value of the @code{image-instance-file-name} function when applied
225 to the resulting image-instance.  Note that there is nothing to stop a
226 program from changing either the @code{:file} or the @code{:data}
227 property, and there is no way to detect such mischief.  This means that
228 the data will @emph{not} be automatically reread if you change the
229 @code{file} property; you must force it by removing the @code{:data}
230 property.
231 @c #### If there are ways to do this in-place, describe them.
232 (One way to do this is replacing the whole specification with a new
233 vector.)  This keyword is not valid for instantiator formats
234 @code{nothing}, @code{string}, @code{formatted-string},
235 @code{cursor-font}, @code{font}, and @code{autodetect}.
236
237 @item :mask-data
238 Inline data for @code{xbm} and @code{xface}.  This specifies a mask to
239 be used with the bitmap.  Pixels which are not set in the mask will not
240 be written to the imaging device.  The format is a list of width,
241 height, and bits, as for @code{:data}.
242
243 @item :mask-file
244 For @code{xbm} and @code{xface}.  This specifies a file containing the
245 mask data.  If neither a mask file nor inline mask data is given for an
246 XBM image, and the XBM image comes from a file, XEmacs will look for a
247 mask file with the same name as the image file but with @samp{Mask} or
248 @samp{msk} appended.  For example, if you specify the XBM file
249 @file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
250 the associated mask file @file{left_ptrmsk} will automatically be picked
251 up.
252
253 @item :resource-id
254 Only for @code{mswindows-resource}.  This must be either an integer
255 (which directly specifies a resource number) or a string.  See the
256 description of @code{mswindows-resource} for valid strings.  @xref{Image
257 Instantiator Formats}.
258
259 @item :foreground
260 @itemx :background
261 For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
262 These keywords allow you to explicitly specify foreground and background
263 colors.  The value should be anything acceptable to
264 @code{make-color-instance}.  This will cause an external format that
265 would by default be instantiated as a @code{mono-pixmap} to instead be
266 instantiated as a two-color color-pixmap.  This can be used to override
267 the colors specified by a glyph's face, for example.  If the image is
268 instantiated as a pointer, they specify its foreground and/or
269 background, instead of the defaults of black and white.
270
271 @item :hotspot-x
272 @itemx :hotspot-y
273 For @code{xbm} and @code{xface}.  These keywords specify a hotspot if
274 the image is instantiated as a @code{pointer}.  Note that if the XBM
275 image file specifies a hotspot, it will automatically be picked up if no
276 explicit hotspot is given.
277
278 @item :color-symbols
279 Only for @code{xpm}.  This specifies an alist that maps strings that
280 specify symbolic color names to the actual color to be used for that
281 symbolic color (in the form of a string or a color-specifier object).
282 If this is not specified, the contents of @code{xpm-color-symbols} are
283 used to generate the alist.
284
285 @item :resource-type
286 Only for @code{mswindows-resource}.  This must be a symbol, either
287 @code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
288 resource to be retrieved.
289
290 @item :face
291 For @code{inherit} and the widget formats.  This specifies the face to
292 inherit from.  For widgets this specifies the face to use for display.
293 It defaults to gui-element-face.
294
295 @item :selected
296 @itemx :active
297 @itemx :suffix
298 @itemx :keys
299 @itemx :style
300 @itemx :filter
301 @itemx :config
302 @itemx :included
303 @itemx :key-sequence
304 @itemx :accelerator
305 @itemx :label
306 @itemx :callback
307 These keywords, accepted as menu item specs, are also accepted by images
308 instantiated as @code{widget}.  For their semantics, @ref{Menu Format}.
309 @end table
310
311
312 @node Image Instantiator Conversion
313 @subsection Image Instantiator Conversion
314 @cindex image instantiator conversion
315 @cindex conversion of image instantiators
316
317 Conversion is applied to image instantiators at the time they are added
318 to an image specifier or at the time they are passed to
319 @code{make-image-instance}.
320
321 @defun set-console-type-image-conversion-list console-type list
322 This function sets the image-conversion-list for consoles of the given
323 @var{console-type}.  The image-conversion-list specifies how image
324 instantiators that are strings should be interpreted.  Each element of
325 the list should be a list of two elements (a regular expression string
326 and a vector) or a list of three elements (the preceding two plus an
327 integer index into the vector).  The string is converted to the vector
328 associated with the first matching regular expression.  If a vector
329 index is specified, the string itself is substituted into that position
330 in the vector.
331
332 Note: The conversion above is applied when the image instantiator is
333 added to an image specifier, not when the specifier is actually
334 instantiated.  Therefore, changing the image-conversion-list only affects
335 newly-added instantiators.  Existing instantiators in glyphs and image
336 specifiers will not be affected.
337 @end defun
338
339 @defun console-type-image-conversion-list console-type
340 This function returns the image-conversion-list for consoles of the given
341 @var{console-type}.
342 @end defun
343
344
345 @node Image Instantiator Formats
346 @subsection Image Instantiator Formats
347 @cindex image instantiator formats
348
349 The @dfn{format} field of an image instantiator should be a symbol
350 denoting a valid format.  Which formats are valid will depend on the
351 features (such as image decoding libraries) available, on platform
352 support (MS Windows resource IDs make no sense on other platforms), and
353 on the locale.
354
355 @defun valid-image-instantiator-format-p format &optional locale
356 This function returns non-@code{nil} if @var{format} is a valid image
357 instantiator format.
358
359 If @var{locale} is non-@code{nil} then the format is checked in that locale.
360 If @var{locale} is @code{nil} the current console is used.
361
362 Note that the return value for many formats listed above depends on
363 whether XEmacs was compiled with support for that format.
364 @end defun
365
366 @defun image-instantiator-format-list
367 This function returns a list of valid image-instantiator formats.
368 @end defun
369
370 Here is a table of image-instantiator formats, giving the keywords that
371 are usable with each, and the kinds of instances that may result.
372
373 @table @code
374 @item nothing
375 Don't display anything; no keywords are valid for this format.  Can only be
376 instanced as @code{nothing}.
377
378 @item string
379 Display this image as a text string.  Can only be instanced
380 as @code{text}, although support for instancing as @code{mono-pixmap}
381 should be added.  The valid keyword is @code{:data}.  The value should
382 be a string, and it is interpreted as a string of characters.
383
384 @item formatted-string
385 Display this image as a text string with replaceable fields,
386 similar to a modeline format string.  The valid keyword is @code{:data}.
387 The value should be a string, and it is interpreted as a string of
388 characters containing format sequences.
389
390 Not currently implemented.
391
392 @item xbm
393 An X bitmap; available only if X support was compiled into this XEmacs.
394
395 If used in a buffer glyph, icon glyph, or face background pixmap, it
396 will be instantiated as @code{mono-pixmap} unless the @code{:foreground}
397 or @code{:background} keywords are present.  In the latter case it will
398 be instantiated as @code{color-pixmap} with the two specified colors.
399 @c #### Check this.
400 (Probably if @code{:foreground} or @code{:background} is omitted, it
401 defaults to black or white respectively.)  If used in a pointer glyph,
402 it will be instantiated as an @code{pointer}.
403
404 The valid keywords and their values are
405 @table @code
406 @item :data
407 A list containing the height and width of the bitmap as integers, and
408 a string interpreted as a bit vector according to the X11 standard XBM
409 bitmap format, in that order.
410 @item :file
411 The name of a file containing standard XBM-format data.  If it contains
412 a hotspot specification, it will be parsed and used if the hotspot is
413 not explicitly specified.
414 @item :mask-data
415 A list containing the height and width of the bitmap as integers, and
416 a string interpreted as a bit vector according to the X11 standard XBM
417 bitmap format, in that order.  This bitmap is interpreted as the
418 clipping region for the bitmap contained in the @code{:data} property.
419 @item :mask-file
420 The name of a file containing standard XBM-format data.  Interpreted as
421 the clipping region for the bitmap contained in the @code{:data} property.
422 @item :foreground
423 @itemx :background
424 These keywords allow you to explicitly specify foreground and background
425 colors.  The values should be acceptable to @code{make-color-instance}.
426 @item :hotspot-x
427 @itemx :hotspot-y
428 Integers denoting the hotspot (mouse pointer position), with (0,0) at
429 the top left corner.  If given, these override any specification in the
430 XBM file.
431 @end table
432
433 @item xpm
434 An XPM pixmap; only available if XPM support was compiled into this XEmacs.
435
436 Can be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
437 @code{pointer}.
438
439 XPM is an add-on library for X that was designed to rectify the
440 shortcomings of the XBM format.  Many icons and labels used in the
441 XEmacs GUI are still distributed in XPM format (although we are moving
442 to standardize on the PNG format).  It is therefore highly desirable
443 that XPM be available in your XEmacs.
444
445 Most implementations of X include the XPM library as a standard part.
446 If your vendor does not, it is highly recommended that you download it
447 and install it.  You can get it from the XEmacs FTP site and mirrors, as
448 well as from most sites that distribute X11.
449
450 The valid keywords and their values are
451 @table @code
452 @item :data
453 A string interpreted as the contents of a standard XPM file.
454 @item :file
455 The name of a file containing standard XPM-format data.  If it contains
456 a hotspot specification, it will be parsed and used if the hotspot is
457 not explicitly specified.
458 @c #### Does XPM provide for a hotspot?
459 @item :hotspot-x
460 @itemx :hotspot-y
461 Integers denoting the hotspot (mouse pointer position), with (0,0) at
462 the top left corner.  If given, these override any specification in the
463 XBM file.
464 @c #### Check this.
465 (This may not be true.  The original documentation doesn't mention them
466 in connection with XPM, but a pointer needs a hotspot.)
467 @item :color-symbols
468 An alist that maps the one- or two-character strings that specify
469 symbolic color names in the XPM file to the actual color to be used for
470 that symbolic color (in the form of a string acceptable as a color
471 instantiator, @ref{Color Specifiers}, or a color-specifier object).
472 If this is not specified, the contents of @code{xpm-color-symbols} are
473 used to generate the alist.
474 @end table
475
476 @item xface
477 An X-Face bitmap, used to encode people's faces in e-mail messages;
478 only available if X-Face support was compiled into this XEmacs.
479
480 Will be instanced as @code{mono-pixmap}, @code{color-pixmap}, or
481 @code{pointer}, depending on the target instance type and the presence
482 of color keywords.
483
484 The valid keywords and their values are
485 @table @code
486 @item :data
487 A list containing the height and width of the bitmap as integers, and
488 a string interpreted as a bit vector according to the X11 standard XBM
489 bitmap format, in that order.
490 @item :file
491 The name of a file containing standard XBM-format data.  If it contains
492 a hotspot specification, it will be parsed and used if the hotspot is
493 not explicitly specified.
494 @item :mask-data
495 A list containing the height and width of the bitmap as integers, and
496 a string interpreted as a bit vector according to the X11 standard XBM
497 bitmap format, in that order.  This bitmap is interpreted as the
498 clipping region for the bitmap contained in the @code{:data} property.
499 @item :mask-file
500 The name of a file containing standard XBM-format data.  Interpreted as
501 the clipping region for the bitmap contained in the @code{:data} property.
502 @item :foreground
503 @itemx :background
504 These keywords allow you to explicitly specify foreground and background
505 colors.  The values should be acceptable to @code{make-color-instance}.
506 @item :hotspot-x
507 @itemx :hotspot-y
508 Integers denoting the hotspot (mouse pointer position), with (0,0) at
509 the top left corner.  If given, these override any specification in the
510 XBM file.
511 @end table
512
513 @item gif
514 @itemx jpeg
515 @itemx png
516 @itemx tiff
517 These are GIF87- or GIF89-format, JPEG-format, PNG/GIF24-format, and
518 TIFF-format images, respectively.  They are available only if
519 appropriate decoding support was built into XEmacs.  XEmacs includes GIF
520 decoding functions as a standard part of it, so if you have X support,
521 you will normally have GIF support, unless you explicitly disable it at
522 configure time.  If you have development support (both the libraries and
523 the relevant C header files) available when XEmacs is built, the JPEG,
524 PNG, and TIFF libraries will automatically be detected (in the ``usual
525 places'') and linked into the build.
526
527 Note that PNG is the standard format for images distributed with XEmacs,
528 so it is highly recommended that PNG support be built in.
529
530 All of these instantiators will be instanced as @code{color-pixmap}.
531
532 The valid keywords and their values are
533 @table @code
534 @item :data
535 A string interpreted as the contents of a file containing data in the
536 appropriate standard format.
537 @item :file
538 The name of a file containing standard-format data.
539 @end table
540
541 @item cursor-font
542 Most window systems provide a set of standard cursors, which in X11 is
543 called a cursor font.  Can only be instanced as @code{pointer}.  This
544 should probably be fixed.
545
546 The valid keyword is @code{:data}.  Its value should be a string
547 containing one of the standard cursor-font names, such as @samp{watch}
548 or @samp{right_ptr} under X.  More specifically, in the X Window System
549 it may be any of the standard cursor names from appendix B of the Xlib
550 manual, provided in the file @file{<X11/cursorfont.h>} by most
551 distributions, minus the @samp{XC_} prefix.  For MS Windows, use
552 @code{mswindows-resource} instantiator format, not @code{cursor-font}.
553 Other window systems may have different lists.
554
555 @item font
556 A glyph from a font; i.e. the name of a font, and glyph index into it
557 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
558 Only if X support was compiled into this XEmacs.  Currently can only be
559 instanced as @code{pointer}.  This should probably be fixed.
560 @c #### The above description is not very helpful, so it's not obvious
561 @c how to instantiate a font image.
562
563 @item mswindows-resource
564 An MS Windows pointer resource.  Specifies a resource to retrieve
565 directly from the system (an OEM resource) or from a file, particularly
566 an executable file.  Can be instanced as @code{pointer} or
567 @code{color-pixmap}.
568
569 The valid keywords and their values are
570
571 @table @code
572 @item :resource-type
573 A string naming the type (@code{cursor}, @code{bitmap}, or @code{icon})
574 of the resource.  Required.
575 @item :file
576 A string containing the name of the file containing the resource (often
577 an executable).  If a system resource, @code{:file} should be omitted.
578 @item :resource-id
579 A string containing the name of a resource.   Required if @code{:file}
580 is not specified.
581
582 This must be either an integer (which directly specifies a resource
583 number) or a string.  Valid strings are
584
585 For bitmaps:
586
587 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
588 "reduce", "zoom", "restore", "reduced", "zoomd",
589 "restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd",
590 "mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi",
591 "lfarrowi", "size", "btsize", "check", "checkboxes", and
592 "btncorners".
593
594 For cursors:
595
596 "normal", "ibeam", "wait", "cross", "up", "sizenwse",
597 "sizenesw", "sizewe", "sizens", "sizeall", and "no".
598
599 For icons:
600
601 "sample", "hand", "ques", "bang", "note", and "winlogo".
602 @end table
603
604 @item subwindow
605 An embedded windowing system window.  Can only be instanced as
606 @code{subwindow}.  Not implemented.
607 @c #### Check status of subwindows ... I thought Andy implemented them.
608
609 @item button
610 A button widget; either a push button, radio button or toggle button.
611 Can only be instanced as @code{widget}.
612
613 @item combo-box
614 A drop list of selectable items in a widget, for editing text.
615 Can only be instanced as @code{widget}.
616
617 @item edit-field
618 A text editing widget.  Can only be instanced as @code{widget}.
619
620 @item label
621 A static, text-only, widget; for displaying text.  Can only be instanced
622 as @code{widget}.
623
624 @item layout
625 A widget for controlling the positioning of children underneath it.
626 Through the use of nested layouts, a widget hierarchy can be created
627 which can have the appearance of any standard dialog box or similar
628 arrangement; all of this is counted as one @dfn{glyph} and could appear
629 in many of the places that expect a single glyph.  Can only be instanced
630 as @code{widget}.
631
632 @item native-layout
633 The native version of a layout widget.
634 Can only be instanced as @code{widget}.
635
636 @item progress-gauge
637 A sliding widget, for showing progress.  Can only be instanced as
638 @code{widget}.
639
640 @item tab-control
641 A tab widget; a series of user selectable tabs.  Can only be instanced
642 as @code{widget}.
643
644 @item tree-view
645 A folding widget.  Can only be instanced as @code{widget}.
646
647 @item scrollbar
648 A scrollbar widget.  Can only be instanced as @code{widget}.
649
650 @item autodetect
651 XEmacs tries to guess what format the data is in.  If X support exists,
652 the data string will be checked to see if it names a filename.  If so,
653 and this filename contains XBM or XPM data, the appropriate sort of
654 pixmap or pointer will be created. [This includes picking up any
655 specified hotspot or associated mask file.] Otherwise, if @code{pointer}
656 is one of the allowable image-instance types and the string names a
657 valid cursor-font name, the image will be created as a pointer.
658 Otherwise, the image will be displayed as text.  If no X support exists,
659 the image will always be displayed as text.
660
661 @item inherit
662 Inherit from the background-pixmap property of a face.  Can only be
663 instanced as @code{mono-pixmap}.
664 @end table
665
666 There are two convenience variables for use with the XBM and XPM image
667 formats.
668
669 @defvar xpm-color-symbols
670 This variable holds definitions of logical color-names used when reading
671 XPM files.  Elements of this list should be of the form
672 @code{(@var{color-name} @var{form-to-evaluate})}.  The @var{color-name}
673 should be a string, which is the name of the color to define; the
674 @var{form-to-evaluate} should evaluate to a color specifier object, or a
675 string to be passed to @code{make-color-instance} (@pxref{Colors}).  If
676 a loaded XPM file references a symbolic color called @var{color-name},
677 it will display as the computed color instead.
678
679 The default value of this variable defines the logical color names
680 @samp{"foreground"} and @samp{"background"} to be the colors of the
681 @code{default} face.
682 @end defvar
683
684 @defvar x-bitmap-file-path
685 A list of the directories in which X bitmap files may be found.  If @code{nil},
686 this is initialized from the @samp{"*bitmapFilePath"} resource.  This is
687 used by the @code{make-image-instance} function (however, note that if
688 the environment variable @samp{XBMLANGPATH} is set, it is consulted
689 first).
690 @end defvar
691
692
693 @node Image Instances
694 @subsection Image Instances
695 @cindex image instances
696
697   Image-instance objects encapsulate the way a particular image (pixmap,
698 etc.) is displayed on a particular device.
699
700   In most circumstances, you do not need to directly create image
701 instances; use a glyph instead.  However, it may occasionally be useful
702 to explicitly create image instances, if you want more control over the
703 instantiation process.
704
705 @defun image-instance-p object
706 This function returns non-@code{nil} if @var{object} is an image instance.
707 @end defun
708
709 @menu
710 * Image Instance Types::         Each image instances has a particular type.
711 * Image Instance Functions::     Functions for working with image instances.
712 @end menu
713
714
715 @node Image Instance Types
716 @subsubsection Image Instance Types
717 @cindex image instance types
718
719   Image instances come in a number of different types.  The type
720 of an image instance specifies the nature of the image: Whether
721 it is a text string, a mono pixmap, a color pixmap, etc.
722
723   The valid image instance types are
724
725 @table @code
726 @item nothing
727 Nothing is displayed.
728
729 @item text
730 Displayed as text.  The foreground and background colors and the
731 font of the text are specified independent of the pixmap.  Typically
732 these attributes will come from the face of the surrounding text,
733 unless a face is specified for the glyph in which the image appears.
734
735 @item mono-pixmap
736 Displayed as a mono pixmap (a pixmap with only two colors where the
737 foreground and background can be specified independent of the pixmap;
738 typically the pixmap assumes the foreground and background colors of
739 the text around it, unless a face is specified for the glyph in which
740 the image appears).
741 @item color-pixmap
742
743 Displayed as a color pixmap.
744
745 @item pointer
746 Used as the mouse pointer for a window.
747
748 @item subwindow
749 A child window that is treated as an image.  This allows (e.g.)
750 another program to be responsible for drawing into the window.
751 Not currently implemented.
752 @c #### Check status of subwindows ... I thought Andy implemented them.
753
754 @item widget
755 An active GUI element implemented as a ``widget'' or ``control'' of the
756 underlying window system.
757 @end table
758
759 The following functions are used to check whether an image instance type
760 is valid in the running XEmacs.
761
762 @defun valid-image-instance-type-p type
763 This function returns non-@code{nil} if @var{type} is a valid image
764 instance type.
765 @end defun
766
767 @defun image-instance-type-list
768 This function returns a list of the valid image instance types.
769 @end defun
770
771 The following functions are used to determine the type of an image
772 instance.
773
774 @defun image-instance-type image-instance
775 Return the type of the given image instance.  The return
776 value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
777 @code{color-pixmap}, @code{pointer}, @code{subwindow}, or @code{widget}.
778 @c #### Check status of subwindows ... I thought Andy implemented them.
779 @end defun
780
781 @defun text-image-instance-p object
782 Return non-@code{nil} if @var{object} is an image instance of type
783 @code{text}.
784 @end defun
785
786 @defun mono-pixmap-image-instance-p object
787 Return non-@code{nil} if @var{object} is an image instance of type
788 @code{mono-pixmap}.
789 @end defun
790
791 @defun color-pixmap-image-instance-p object
792 Return non-@code{nil} if @var{object} is an image instance of type
793 @code{color-pixmap}.
794 @end defun
795
796 @defun pointer-image-instance-p object
797 Return non-@code{nil} if @var{object} is an image instance of type
798 @code{pointer}.
799 @end defun
800
801 @defun subwindow-image-instance-p object
802 Return non-@code{nil} if @var{object} is an image instance of type
803 @code{subwindow}.
804 @c #### Check status of subwindows ... I thought Andy implemented them.
805 @end defun
806
807 @defun nothing-image-instance-p object
808 Return non-@code{nil} if @var{object} is an image instance of type
809 @code{nothing}.
810 @end defun
811
812 @defun widget-image-instance-p object
813 Return non-@code{nil} if @var{object} is an image instance of type
814 @code{widget}.
815 @end defun
816
817
818 @node Image Instance Functions
819 @subsubsection Image Instance Functions
820
821 @defun make-image-instance data &optional domain dest-types noerror
822 This function creates a new image-instance object.
823
824 @var{data} is an image instantiator, which describes the image
825 (@pxref{Image Specifiers}).
826
827 @var{dest-types} should be a list of allowed image instance types that
828 can be generated.  The @var{dest-types} list is unordered.  If multiple
829 destination types are possible for a given instantiator, the ``most
830 natural'' type for the instantiator's format is chosen.  These are
831
832 @table @code
833 @item XBM
834 @c #### check xface
835 @itemx xface
836 @code{mono-pixmap}, then @code{color-pixmap}, then @code{pointer}.
837
838 @item XPM
839 @itemx GIF
840 @itemx JPEG
841 @itemx PNG
842 @itemx TIFF
843 @code{color-pixmap}, then @code{mono-pixmap}, then @code{pointer}.
844
845 @item string
846 @itemx formatted-string formats
847 @code{text}, then @code{mono-pixmap} (not currently implemented), then
848 @code{color-pixmap} (not currently implemented).
849
850 @item mswindows-resource
851 For pointer resources, @code{pointer}.
852
853 For the others, @code{color-pixmap}.
854 @end table
855
856 @c #### So what?  This is a reference manual, list them, you lazy bastard!
857 The other formats can only be instantiated as one type.
858
859 If you want to control more specifically the order of the types into
860 which an image is instantiated, call @code{make-image-instance}
861 repeatedly until it succeeds, passing less and less preferred
862 destination types each time.
863
864 If @var{dest-types} is omitted, all possible types are allowed.
865
866 @var{domain} specifies the domain to which the image instance will be
867 attached.  This domain is termed the @dfn{governing domain}.  The type
868 of the governing domain depends on the image instantiator format.
869 (Although, more correctly, it should probably depend on the image
870 instance type.)  For example, pixmap image instances are specific to a
871 device, but widget image instances are specific to a particular XEmacs
872 window because in order to display such a widget when two windows onto
873 the same buffer want to display the widget, two separate underlying
874 widgets must be created.  (That's because a widget is actually a child
875 window-system window, and all window-system windows have a unique
876 existence on the screen.)  This means that the governing domain for a
877 pixmap image instance will be some device (most likely, the only
878 existing device), whereas the governing domain for a widget image
879 instance will be some XEmacs window.
880
881 If you specify an overly general @var{domain} (e.g. a frame when a
882 window was wanted), an error is signaled.  If you specify an overly
883 specific @var{domain} (e.g. a window when a device was wanted), the
884 corresponding general domain is fetched and used instead.  For
885 @code{make-image-instance}, it makes no difference whether you specify
886 an overly specific domain or the properly general domain derived from
887 it.  However, it does matter when creating an image instance by
888 instantiating a specifier or glyph (e.g. with
889 @code{glyph-image-instance}), because the more specific domain causes
890 spec lookup to start there and proceed to more general domains.  (It
891 would also matter when creating an image instance with an instantiator
892 format of @code{inherit}, but we currently disallow this.)
893 @c #### We should fix that.
894
895 If omitted, @var{domain} defaults to the selected window.
896
897 @var{noerror} controls what happens when the image cannot be generated.
898 If @code{nil}, an error message is generated.  If @code{t}, no messages
899 are generated and this function returns @code{nil}.  If anything else, a
900 warning message is generated and this function returns @code{nil}.
901 @end defun
902
903 @defun colorize-image-instance image-instance foreground background
904 This function makes the image instance be displayed in the given
905 colors.  Image instances come in two varieties: bitmaps, which are 1
906 bit deep which are rendered in the prevailing foreground and background
907 colors; and pixmaps, which are of arbitrary depth (including 1) and
908 which have the colors explicitly specified.  This function converts a
909 bitmap to a pixmap.  If the image instance was a pixmap already,
910 nothing is done (and @code{nil} is returned).  Otherwise @code{t} is
911 returned.
912 @end defun
913
914 The following functions are 
915
916 @defun image-instance-name image-instance
917 This function returns the name of the given image instance.  The name is
918 typically taken from the @code{:file} property of the instantiator if
919 present, otherwise from the @code{:data} property.
920 @end defun
921
922 @defun image-instance-domain image-instance
923 Return the governing domain of the given @var{image-instance}.  The
924 governing domain of an image instance is the domain that the image
925 instance is specific to.  It is @emph{NOT} necessarily the domain that
926 was given to the call to @code{specifier-instance} that resulted in the
927 creation of this image instance.  See @code{make-image-instance} for
928 more information on governing domains.
929 @end defun
930
931 @defun image-instance-string image-instance
932 This function returns the string of the given image instance.  This will
933 only be non-@code{nil} for text image instances.
934 @end defun
935
936 @defun image-instance-file-name image-instance
937 This function returns the file name from which @var{image-instance} was
938 read, if known.
939 @end defun
940
941 @defun image-instance-mask-file-name image-instance
942 This function returns the file name from which @var{image-instance}'s
943 mask was read, if known.
944 @end defun
945
946 Pixmaps are considered to be three-dimensional.  The height and width of
947 the pixel array that is displayed, and the color depth of its pixels,
948 are accessed with these functions.
949
950 @defun image-instance-depth image-instance
951 This function returns the depth of the image instance.  This is 0 for a
952 mono pixmap, or a positive integer for a color pixmap.
953 @end defun
954
955 @defun image-instance-height image-instance
956 This function returns the height of the image instance, in pixels.
957 @end defun
958
959 @defun image-instance-width image-instance
960 This function returns the width of the image instance, in pixels.
961 @end defun
962
963 The hotspot is a point relative to the origin of the pixmap.  When
964 an image is used as a mouse pointer, the hotspot is the point on the
965 image that sits over the location that the pointer points to.  This is,
966 for example, the tip of the arrow or the center of the crosshairs.
967
968 These functions access the coordinates of the hotspot.  They simply
969 return @code{nil} for a non-pointer image instance.
970
971 @defun image-instance-hotspot-x image-instance
972 This function returns the X coordinate of the image instance's hotspot,
973 if known.
974 @end defun
975
976 @defun image-instance-hotspot-y image-instance
977 This function returns the Y coordinate of the image instance's hotspot,
978 if known.
979 @end defun
980
981 Mono pixmaps and pointers may have their foreground and background
982 colors set when instanced.  Use these functions to access color
983 information.
984
985 @defun image-instance-foreground image-instance
986 This function returns the foreground color of @var{image-instance}, if
987 applicable.  This will be a color instance or @code{nil}.  (It will only
988 be non-@code{nil} for colorized mono pixmaps and for pointers.)
989 @end defun
990
991 @defun image-instance-background image-instance
992 This function returns the background color of @var{image-instance}, if
993 applicable.  This will be a color instance or @code{nil}.  (It will only
994 be non-@code{nil} for colorized mono pixmaps and for pointers.)
995 @end defun
996
997
998 @node Using Glyphs
999 @section Using Glyphs
1000
1001 Glyph usage is unfortunately somewhat arcane.  (For discussion of
1002 rationale, @ref{Glyphs,,,Internals}.)  Because they are not ``text,''
1003 they cannot be inserted directly into a buffer.  Instead, they are
1004 values of properties of extents attached to buffers or strings, values
1005 of global variables such as mouse pointers, or as a component of a
1006 complex data structure such as a toolbar initializer.  Although these
1007 uses could probably streamlined, each structure has its own
1008 requirements.  Since glyphs are very flexible, it is possible to create
1009 applications like the @file{edit-toolbar} and @file{xpm-mode} libraries
1010 which display glyphs in a buffer (for reference while editing) that are
1011 normally used in a different context.
1012
1013 Usage of glyphs can roughly be categorized as follows:
1014
1015 @table @strong
1016 @item Buffer glyphs
1017 Glyphs that are inserted in a buffer may be used for their own sake (for
1018 example, image display in @file{w3}), as an accurate representation of
1019 text that can't be displayed in usual fonts (equation display in
1020 @file{preview-latex}), or as annotations (such as a marginal indication
1021 of a bookmark).  Glyphs are attached to buffers via extents.
1022
1023 @item Redisplay glyphs
1024 Glyphs can be used to create XEmacs-specific ``fonts''.  For example,
1025 the character that indicates truncation of lines is implemented as the
1026 @code{truncation-glyph}.  It is also possible to have XEmacs display a
1027 certain character using a custom glyph, via display tables.
1028
1029 @item Frame glyphs
1030 Glyphs are used to control the appearance of various other components of
1031 the frame.  They can be inserted in the modeline, like the favicons used
1032 in Web browsers.  They are used to specify the labels on toolbar
1033 buttons.  Finally, they can be inserted in the gutters.  (The difference
1034 between a glyph inserted in a gutter and a marginal annotation is that
1035 the marginal annotation is tied to the text in the buffer.  If the
1036 buffer line scrolls out of view, the marginal annotation will, as well.
1037 A gutter glyph does not move with the text.)
1038
1039 Unfortunately, all these uses are special cases, and have their own
1040 APIs, in contrast to glyphs in a buffer.
1041
1042 @item External glyphs
1043 External glyphs simply allow a consistent API for images.  The images
1044 are then passed to external software such as the window system itself
1045 (mouse cursor shapes) and the window manager (icons to represent
1046 minimized windows).  XEmacs has no role in managing their use.
1047
1048 @item Subwindow and widget glyphs
1049 These do not constitute a context of use, but rather an important class of
1050 glyph types.  The difference between these and other glyphs is that
1051 while their geometry is determined by XEmacs, their behavior is managed
1052 separately, by internal mechanisms in the case of widgets, and
1053 (possibly) by another process in the case of subwindows.
1054 @c #### Check status of subwindows ... I thought Andy implemented them.
1055 @end table
1056
1057 Some simple concrete examples showing how to insert a glyph in a
1058 buffer are presented later.  @ref{Glyph Examples}.
1059
1060 ``Creating Glyphs'' explains how to create glyphs.  Creating a glyph
1061 using @code{make-glyph} does not specify @emph{where} the glyph will be
1062 used, it only specifies @emph{what} the glyph will look like.  The next
1063 four sections explain how to embed glyphs in different display
1064 contexts.  Finally, the last two sections explain the special
1065 considerations of using glyphs whose behavior is not determined by the
1066 code creating them, but by the glyph itself (a ``widget'' in X11 or
1067 ``control'' in MS Windows or Aqua), or even by a separate process.
1068
1069 @menu
1070 * Creating Glyphs::     Creating new glyphs.
1071 * Buffer Glyphs::       Annotations are glyphs that appear in a buffer.
1072 * Redisplay Glyphs::    Glyphs controlling various redisplay functions.
1073 * Frame Glyphs::        Displaying glyphs in GUI components of the frame.
1074 * External Glyphs::     Icons and mouse pointers for the window system.
1075 * Native GUI Widgets::  Complex active elements treated as a single glyph.
1076 * Subwindows::          Externally-controlled subwindows in buffers.
1077 @c #### Check status of subwindows ... I thought Andy implemented them.
1078 @end menu
1079
1080 @node Creating Glyphs
1081 @subsection Creating Glyphs
1082
1083 @defun make-glyph &optional spec-list type
1084 This function creates a new glyph object of type @var{type}.
1085
1086 The optional @var{spec-list} is used to initialize the glyph's image.
1087 It can be any spec-list of @dfn{image instantiator} accepted by
1088 @code{canonicalize-spec-list}, @ref{Adding Specifications}.  An
1089 individual image instantiator may be a string, which is converted to a
1090 vector according to @code{console-type-image-conversion-list}, or a
1091 vector.  The vector's first element specifies the @emph{external} format
1092 of the data, such as a string, a PNG file, or an MS Windows resource.
1093 This is followed by properties (keyword-value pairs) specifying such
1094 information as the name of a file containing an image, or pixmap data
1095 directly.  @xref{Image Specifiers}.
1096
1097 The optional @var{type} specifies the type of the glyph.  @var{type}
1098 should be one of @code{buffer} (used for glyphs in an extent, the
1099 modeline, the toolbar, or elsewhere in a frame), @code{pointer} (used
1100 for the mouse-pointer), or @code{icon} (used for a frame's icon), and
1101 defaults to @code{buffer}.
1102 @end defun
1103
1104 @var{spec-list} is the initializer for the glyph's @code{image}
1105 property, which is an image specifier.  (Note that @dfn{image} as used
1106 in the context of a glyph's @code{image} property or in the terms
1107 @dfn{image specifier}, @dfn{image instantiator}, or @dfn{image instance}
1108 does not refer to what people normally think of as an image (which in
1109 XEmacs is called a @dfn{pixmap}), but to any graphical element---a
1110 pixmap, a widget, or even a block of text, when used in the places that
1111 call for a glyph.)
1112
1113 The most common form of @var{spec-list} is a single image instantiator.
1114 (@strong{Compatibility note:} in GNU Emacs 21, a string used to
1115 instantiate an image is interpreted as the name of an image file, which
1116 is searched for and instantiated.)  The conversion controlled by
1117 @code{console-type-image-conversion-list} typically attempts to look up
1118 the string as a file name in XEmacs's data directory path, and if this
1119 fails, defaults to displaying the string as a text image instance
1120 (@emph{i.e.}. the string itself.
1121
1122 Fine control of a particular specification is provided by using a vector
1123 as the image instantiator.  More complicated instantiators allow lists
1124 of instantiators to be specified (which are tried in order), or mappings
1125 from locales to lists of instantiators, @emph{etc}.  @xref{Specifiers},
1126 for more information about specification formats.
1127
1128 As well as using @var{spec-list} to initialize the glyph, you can set
1129 specifications using @code{set-glyph-image}.  The glyph itself is not
1130 actually a specifier, but rather is an object containing an image
1131 specifier (as well as other properties seldom set by user code).
1132 Therefore, you cannot set or access specifications for the glyph's image
1133 by directly using @code{set-specifier}, @code{specifier-instance} or the
1134 like on the glyph; instead use them on @code{(glyph-image @var{glyph})}
1135 or use the convenience functions @code{set-glyph-image},
1136 @code{glyph-image-instance}, and @code{glyph-image}.
1137
1138 Glyph types reflect the fact that glyphs are used in contexts like
1139 pointers and window manager icons, which are defined by external
1140 programs such as the window system or window manager.  These require
1141 somewhat different @emph{internal} format, which is opaque to the user.
1142
1143 It is extremely rare that you will ever have to specify a value for
1144 @var{type}, which should be one of @code{buffer} (used for glyphs in an
1145 extent, the modeline, the toolbar, or elsewhere in a buffer),
1146 @code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
1147 frame's icon), and defaults to @code{buffer}.  The only cases where it
1148 needs to be specified is when creating icon or pointer glyphs, and in
1149 both cases the necessary glyphs have already been created at startup and
1150 are accessed through the appropriate variables,
1151 e.g. @code{text-pointer-glyph} (or in general, any
1152 @samp{*-pointer-glyph}) and @code{frame-icon-glyph}.  User code should
1153 never need to create @code{pointer} or @code{icon} glyphs.  @xref{Glyph
1154 Types}.
1155
1156 There are a few other glyph creation functions, normally used only
1157 internally or at XEmacs initialization.
1158
1159 @defun make-glyph-internal &optional type
1160 This function creates a new, uninitialized glyph of type @var{type}.
1161 @end defun
1162
1163 @defun make-pointer-glyph &optional spec-list
1164
1165 Return a new @code{pointer-glyph} object with the specification list
1166 @var{spec-list}.  This function is equivalent to calling
1167 @code{make-glyph} with a @var{type} of @code{pointer}.
1168 @end defun
1169
1170 @code{make-pointer-glyph} is normally used only by XEmacs initialization
1171 code.  It is extremely unlikely that you will ever need to create a
1172 pointer glyph.  Instead, you probably want to be calling
1173 @code{set-glyph-image} on an existing glyph,
1174 e.g. @code{text-pointer-glyph}.
1175
1176 @defun make-icon-glyph &optional spec-list
1177
1178 Return a new @code{icon-glyph} object with the specification list
1179 @var{spec-list}.  This function is equivalent to calling
1180 @code{make-glyph} with a @var{type} of @code{icon}.
1181 @end defun
1182
1183 @code{make-icon-glyph} is normally used only by XEmacs initialization
1184 code.  It is extremely unlikely that you will ever need to create a icon
1185 glyph.  Instead, you probably want to be calling @code{set-glyph-image}
1186 on the existing glyph, @code{frame-icon-glyph}.
1187
1188
1189 @node Buffer Glyphs
1190 @subsection Buffer Glyphs
1191
1192 Creating a glyph using @code{make-glyph} does not specify @emph{where}
1193 the glyph will be used, it only specifies @emph{what} the glyph will
1194 look like.  Once you have created a glyph, you specify where it will be
1195 used by attaching it to an extent as a @emph{begin-glyph} or
1196 @emph{end-glyph}.
1197
1198 @table @code
1199 @item buffer text
1200 To insert a glyph into a buffer, create an extent in the buffer and then
1201 use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
1202 a glyph to be displayed at the corresponding edge of the extent.  (It is
1203 common to create zero-width extents for this purpose.)
1204
1205 @item margins
1206 To insert a glyph into the left or right margin of a buffer, first
1207 make sure the margin is visible by setting a value for the specifiers
1208 @code{left-margin-width} or @code{right-margin-width}.  (Not strictly necessary
1209 when using margin glyphs with layout policy @code{whitespace}.)  Follow
1210 the same procedure above for inserting a glyph in a buffer, then
1211 set a non-default layout policy for the glyph using
1212 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
1213 Alternatively, use the high-level annotations API (see
1214 @code{make-annotation}).  (In fact, you can also use the annotations
1215 API for glyphs in a buffer, by setting a layout policy of @code{text}.)
1216
1217 @end table
1218
1219
1220 @node Redisplay Glyphs
1221 @subsection Redisplay Glyphs
1222
1223 To use a glyph to control the shape of miscellaneous redisplay effects
1224 such as the truncation and continuation markers, set the appropriate
1225 existing glyph variables with @code{set-glyph-image}.  See
1226 @code{continuation-glyph}, @code{control-arrow-glyph},
1227 @code{hscroll-glyph}, @code{invisible-text-glyph},
1228 @code{octal-escape-glyph}, and @code{truncation-glyph}.  See also
1229 @code{overlay-arrow-string}, an odd redisplay leftover which can be set
1230 to a glyph you created, and will cause the glyph to be displayed on top
1231 of the text position specified in the marker stored in
1232 @code{overlay-arrow-position}.
1233
1234 To use a glyph in a display table (i.e. to control the appearance of any
1235 individual character), create the appropriate character glyphs and then
1236 set a specification for the specifier @code{current-display-table},
1237 which controls the appearance of characters.  You can also set an
1238 overriding display table for use with text displayed in a particular
1239 face; see @code{set-face-display-table} and @code{make-display-table}.
1240 #### Note: Display tables do not currently support general Mule
1241 characters.  They will be overhauled at some point to support this
1242 and to provide other features required under Mule.  @ref{Display Tables}.
1243
1244 Glyphs are not actually used as the background pixmaps of faces, but the
1245 API is similar.  The
1246 background pixmap of a face is actually an image specifier -- probably
1247 the only place in XEmacs where an image specifier occurs outside of a
1248 glyph.  If you would like to use a glyph's image as a background pixmap,
1249 you can extract it with @code{glyph-image}, and then add it to a face.
1250 @xref{Face Convenience Functions}.
1251
1252 @defvr Glyph truncation-glyph
1253 This variable specifies what is displayed at the end of truncated lines.
1254 @end defvr
1255
1256 @defvr Glyph continuation-glyph
1257 This variable specifies what is displayed at the end of wrapped lines.
1258 @end defvr
1259
1260 @defvr Glyph octal-escape-glyph
1261 This variable specifies what to prefix character codes displayed in octal
1262 with.
1263 @end defvr
1264
1265 @defvr Glyph hscroll-glyph
1266 This variable specifies what to display at the beginning of horizontally
1267 scrolled lines.
1268 @end defvr
1269
1270 @defvr Glyph invisible-text-glyph
1271 This variable specifies what to use to indicate the presence of
1272 invisible text.  This is the glyph that is displayed when an ellipsis is
1273 called for, according to @code{selective-display-ellipses} or
1274 @code{buffer-invisibility-spec}).  Normally this is three dots (``...'').
1275 @end defvr
1276
1277 @defvr Glyph control-arrow-glyph
1278 This variable specifies what to use as an arrow for control characters.
1279 @end defvr
1280
1281
1282 @node Frame Glyphs
1283 @subsection Frame Glyphs
1284
1285 There are also a number of special objects whose appearance is specified
1286 by a glyph.  Most of these a global objects that you update with
1287 @code{set-glyph-image}, such as mouse pointers.  Frame icons, toolbar
1288 button icons, and the modeline are the main non-text objects which
1289 accept glyphs as elements.
1290
1291 @table @code
1292 @item modeline
1293 A glyph may be displayed in the modeline by inserting the glyph as one
1294 of the elements of the modeline format.  (Unfortunately you can't
1295 currently put a begin glyph or end glyph on one of the modeline
1296 extents---they're ignored.)
1297
1298 @item toolbar
1299 To insert a glyph into a toolbar, specify it as the icon part of a toolbar
1300 button, which in turn must be part of a toolbar instantiator (typically
1301 set on the specifier @code{default-toolbar}).
1302 See @code{default-toolbar} for more information. (As a convenience, you
1303 may use a symbol in place of the glyph list in the toolbar button
1304 instantiator; the symbol is evalled to get the glyph list.  This
1305 facilitates both creating the toolbar instantiator and modifying
1306 individual glyphs in a toolbar later on.  For example, you can change
1307 the way that the Mail toolbar button looks by modifying the value of the
1308 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
1309 and then calling @code{(set-specifier-dirty-flag default-toolbar)}.
1310 (#### Unfortunately this doesn't quite work the way it should; the
1311 change will appear in new frames, but not existing ones, because once an
1312 image has been displayed the pixmap replaces the symbol for those domains.)
1313
1314 @item gutter
1315 To insert a glyph into a gutter, use
1316 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
1317 glyph to be displayed at the corresponding edge of extent in a string,
1318 similar to the way you insert glyphs in a buffer.  Then insert the
1319 string into the gutter @ref{Specifying a Gutter}.  Glyphs that are
1320 frequently used in this way are @code{tab control} and @code{progress
1321 bar} glyphs.
1322
1323 @end table
1324
1325
1326 @node External Glyphs
1327 @subsection External Glyphs
1328 @cindex frame icon
1329 @cindex icon, frame
1330 @cindex mouse cursor
1331 @cindex cursor (mouse)
1332 @cindex pointer (mouse)
1333 @cindex mouse pointer
1334
1335 There are two special kinds of glyph that are not displayed by XEmacs.
1336 Instead, they are used to set the appearance of iconified frames and the
1337 mouse pointer.  Because these uses are constrained by the window system,
1338 icons and pointers have their own special types @xref{Glyph Types}.
1339
1340 You may use a glyph as the icon for a frame.  Do not create a new glyph;
1341 instead, change the specifications for the existing glyph
1342 @code{frame-icon-glyph} with @code{set-glyph-image}.  This is a unique,
1343 predefined object.  Although the natural usage is to set specifications
1344 for the global locale or a frame locale, you can also arrange for a
1345 special icon when a frame's selected window displays a particular buffer
1346 by using a buffer locale.
1347
1348 The shape of the mouse pointer when over a particular section of a frame
1349 is controlled using various glyph variables.  Since the image of a glyph
1350 is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
1351 or per-device basis.
1352
1353 To use a glyph as the mouse pointer, in general you do not create a new
1354 glyph, but rather you change the specifications of various existing
1355 glyphs, such as @code{text-pointer-glyph} for the pointer used over
1356 text, @code{modeline-pointer-glyph} for the pointer used over the
1357 modeline, etc.  Do an apropos over @samp{pointer-glyph} to find all of
1358 them.  (Note also that you can temporarily set the mouse pointer to some
1359 specific shape by using @code{set-frame-pointer}, which takes an image
1360 instance, as obtained from calling @code{glyph-image-instance} on a glyph
1361 of type @code{pointer} -- either one of the above-mentioned variables or
1362 one you created yourself.  (See below for what it means to create a
1363 glyph of type @code{pointer}.)  This pointer will last only until the
1364 next mouse motion event is processed or certain other things happen,
1365 such as creating or deleting a window. (In fact, the above-mentioned
1366 pointer glyph variables are implemented as part of the default handler
1367 for mouse motion events.  If you want to customize this behavior, take a
1368 look at @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
1369 really want to get low-level.)
1370
1371 You should use @code{set-glyph-image} to set the following variables,
1372 @emph{not} @code{setq}.
1373
1374 @defvr Glyph text-pointer-glyph
1375 This variable specifies the shape of the mouse pointer when over text.
1376 @end defvr
1377
1378 @defvr Glyph nontext-pointer-glyph
1379 This variable specifies the shape of the mouse pointer when over a
1380 buffer, but not over text.  If unspecified in a particular domain,
1381 @code{text-pointer-glyph} is used.
1382 @end defvr
1383
1384 @defvr Glyph modeline-pointer-glyph
1385 This variable specifies the shape of the mouse pointer when over the modeline.
1386 If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
1387 @end defvr
1388
1389 @defvr Glyph selection-pointer-glyph
1390 This variable specifies the shape of the mouse pointer when over a
1391 selectable text region.  If unspecified in a particular domain,
1392 @code{text-pointer-glyph} is used.
1393 @end defvr
1394
1395 @defvr Glyph gc-pointer-glyph
1396 This variable specifies the shape of the mouse pointer when a garbage
1397 collection is in progress.  If the selected window is on a window system
1398 and this glyph specifies a value (i.e. a pointer image instance) in the
1399 domain of the selected window, the pointer will be changed as specified
1400 during garbage collection.  Otherwise, a message will be printed in the
1401 echo area, as controlled by @code{gc-message}.
1402 @end defvr
1403
1404 @defvr Glyph busy-pointer-glyph
1405 This variable specifies the shape of the mouse pointer when XEmacs is busy.
1406 If unspecified in a particular domain, the pointer is not changed
1407 when XEmacs is busy.
1408 @end defvr
1409
1410 @defvr Glyph menubar-pointer-glyph
1411 This variable specifies the shape of the mouse pointer when over the
1412 menubar.  If unspecified in a particular domain, the
1413 window-system-provided default pointer is used.
1414 @end defvr
1415
1416 @defvr Glyph scrollbar-pointer-glyph
1417 This variable specifies the shape of the mouse pointer when over a
1418 scrollbar.  If unspecified in a particular domain, the
1419 window-system-provided default pointer is used.
1420 @end defvr
1421
1422 @defvr Glyph toolbar-pointer-glyph
1423 This variable specifies the shape of the mouse pointer when over a
1424 toolbar.  If unspecified in a particular domain,
1425 @code{nontext-pointer-glyph} is used.
1426 @end defvr
1427
1428 Internally, these variables are implemented in
1429 @code{default-mouse-motion-handler}, and thus only take effect when the
1430 mouse moves.  That function calls @code{set-frame-pointer}, which sets
1431 the current mouse pointer for a frame.
1432
1433 @defun set-frame-pointer frame image-instance
1434 This function sets the mouse pointer of @var{frame} to the given pointer
1435 image instance.  You should not call this function directly.
1436 (If you do, the pointer will change again the next time the mouse moves.)
1437 @end defun
1438
1439
1440 @node Native GUI Widgets
1441 @subsection Native GUI Widgets
1442 @cindex native widget
1443
1444 A ``native widget'' is a primitive GUI object defined either by the host
1445 GUI platform or an external toolkit, and accessed from Lisp as a
1446 ``glyph.''
1447
1448 @menu
1449 * Introduction to Widgets::     Native widgets provide tight integration of
1450                                 GUI features with the platform GUI.
1451 * Lisp API to Native Widgets::  Native widgets are glyphs.
1452 * Layouts::                     Specifying composite widgets from Lisp.
1453 * Primitive Widgets::           Catalogue of available native widgets.
1454 @end menu
1455
1456 @node Introduction to Widgets
1457 @subsubsection Introduction to Native Widgets and Subwindow Glyphs
1458
1459 Traditionally Emacsen have hidden the GUI apparatus from the Lisp
1460 programmer, but in XEmacs 21.4 the ability to embed autonomous GUI
1461 objects, called @dfn{native widgets}, in text was added to Lisp.  They
1462 are handled as @emph{glyphs}.  Unlike traditional XEmacs
1463 glyphs such images and strings, native widgets are opaque to XEmacs, and
1464 must be able to redraw themselves because they are implemented as
1465 subwindows, not as graphics drawn by XEmacs into the text window.
1466
1467 Primitive widgets are coded in C using the underlying GUI toolkit, and
1468 thus are beyond the scope of the @emph{XEmacs Lisp Reference Manual}.
1469 However, composite widgets can be created in Lisp using ``layouts,''
1470 which are horizontal or vertical arrays of subwidgets.  For example, the
1471 search dialog is formatted using layouts.
1472
1473 @node Lisp API to Native Widgets
1474 @subsubsection Lisp API to Native Widgets
1475
1476 Native widgets are manipulated as @emph{glyphs} (@pxref{Glyphs}).  Thus
1477 they are created using @code{make-glyph}, with a format of one of the
1478 widget types and a @code{:data} property specific to the widget being
1479 instanced.
1480
1481 However, there is a technical difference between widgets and other kinds
1482 of glyphs that is theoretically important.  Because widgets
1483 are active (that is, they can respond to user input events themselves),
1484 it is possible for the user to become aware that two appearances of the
1485 ``same'' glyph are actually separate instances.  For example, if a user
1486 changes an image glyph from red to blue, and the buffer containing the
1487 glyph appears in more than one window, the user will perceive all the
1488 appearances to change from red to blue simultaneously.  However, suppose
1489 the glyph is a button glyph (@emph{e.g.}, as used in the Customize
1490 buffer for the Set, Save, and Done buttons).  Then if the Customize
1491 buffer appears in several windows at the same time, and the user clicks
1492 on the button, she will only perceive the button to be depressed in the
1493 window where she clicked the button.
1494
1495 It seems from this example that it is unlikely to be a problem in
1496 practice.  When the user is faced with an active widget, it seems likely
1497 that attention will focus on the widget being manipulated, and having
1498 other instances of the widget respond simultaneously might be more
1499 disconcerting than the actual case.
1500
1501 @node Layouts
1502 @subsubsection Layouts
1503
1504 An XEmacs @dfn{layout} is a one-dimensional array of glyphs.  It is a
1505 widget for controlling the positioning of children underneath it.
1506 Through the use of nested layouts, a widget hierarchy can be created
1507 which can have the appearance of any standard dialog box or similar
1508 arrangement; all of this is counted as one "glyph" and could appear in
1509 many of the places that expect a single glyph.
1510 @c #### Fix me!
1511 (There are also @dfn{native layouts}, but these are undocumented, as are
1512 their uses.)
1513
1514 A layout descriptor is an image instantiator, @emph{i.e.}, a vector of
1515 the form @samp{[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]} with format
1516 @code{layout}, and properties
1517
1518 @c #### need defaults for these
1519 @table @code
1520 @item :orientation
1521 Specifies the orientation of the contained array of glyphs.  The value
1522 must be one of the symbols @code{horizontal} or @code{vertical}.
1523
1524 @item :horizontally-justify
1525 Specifies the horizontal justification of the items in the array.  The
1526 value must be one of the symbols @code{:right}, @code{:center}, or
1527 @code{:left}.
1528
1529 @item :vertically-justify
1530 Specifies the vertical justification of the items in the array.  The
1531 value must be one of the symbols @code{:top}, @code{:center}, or
1532 @code{:bottom}.
1533
1534 @item :justify
1535 Specifies justification.  #### not understood.
1536
1537 @item :border
1538 A glyph to place in the border.  The value must be an image
1539 instantiator.
1540
1541 @item :items
1542 The glyphs controlled by the layout.  The value must be a list of image
1543 instantiators.
1544 @end table
1545
1546 Here is the specification of the search dialog widget created by
1547 @code{make-search-dialog} in the @file{dialog-items} library, which
1548 makes use of recursive layouts.
1549
1550 @example
1551 (make-glyph
1552  `[layout 
1553    :orientation horizontal 
1554    :vertically-justify top 
1555    :horizontally-justify center 
1556    :border [string :data "Search"]
1557    :items 
1558    ([layout :orientation vertical 
1559             :justify top        ; implies left also
1560             :items 
1561             ([string :data "Search for:"]
1562         [button :descriptor "Match Case"
1563                 :style toggle
1564                 :selected (not case-fold-search)
1565                 :callback (setq case-fold-search
1566                                 (not case-fold-search))]
1567         [button :descriptor "Regular Expression"
1568                 :style toggle
1569                 :selected search-dialog-regexp
1570                 :callback (setq search-dialog-regexp
1571                                 (not search-dialog-regexp))]
1572         [button :descriptor "Forwards"
1573                 :style radio
1574                 :selected search-dialog-direction
1575                 :callback (setq search-dialog-direction t)]
1576         [button :descriptor "Backwards"
1577                 :style radio
1578                 :selected (not search-dialog-direction)
1579                 :callback (setq search-dialog-direction nil)]
1580         )]
1581     [layout :orientation vertical
1582             :vertically-justify top
1583             :horizontally-justify right
1584             :items
1585             ([edit-field :width 15 :descriptor "" :active t
1586                     :initial-focus t]
1587         [button :width 10 :descriptor "Find Next"
1588                 :callback-ex
1589                 (lambda (image-instance event)
1590                   (search-dialog-callback ,parent
1591                                           image-instance
1592                                           event))]
1593         [button :width 10 :descriptor "Cancel"
1594                 :callback-ex
1595                 (lambda (image-instance event)
1596                   (isearch-dehighlight)
1597                   (delete-frame 
1598                    (event-channel event)))])])])
1599 @end example
1600
1601 @node Primitive Widgets
1602 @subsubsection Primitive Widgets
1603
1604 @c #### the following table should be replaced with a menu of nodes
1605 @table @code
1606 @item button
1607 A button widget; either a push button, radio button or toggle
1608 button.
1609
1610 @item combo-box
1611 A drop list of selectable items in a widget, for editing text.
1612
1613 @item edit-field
1614 A text editing widget.
1615
1616 @item label
1617 A static, text-only, widget; for displaying text.
1618
1619 @item progress-gauge
1620 A sliding widget, for showing progress.
1621
1622 @item tab-control
1623 A tab widget; a series of user selectable tabs.
1624
1625 @item tree-view
1626 A folding widget.
1627
1628 @item scrollbar
1629 A scrollbar widget.  (#### Probably not the same as the scrollbar
1630 controlling an Emacs window.)
1631 @end table
1632
1633
1634 @node Subwindows
1635 @subsection Subwindows
1636
1637 Subwindows are not currently implemented.
1638 @c #### Check status of subwindows ... I thought Andy implemented them.
1639
1640 @defun subwindowp object
1641 This function returns non-@code{nil} if @var{object} is a subwindow.
1642 @end defun
1643
1644
1645 @node Manipulating Glyphs
1646 @section Manipulating Glyphs
1647
1648   Each glyphs has properties that may be accessed.  Most of these can
1649 also be set after the glyph is initialized, with the exception of the
1650 glyph's type.  This is not a real restriction, as it is almost never
1651 useful to create glyphs of types other than @code{buffer}.
1652
1653 @menu
1654 * Glyph Properties::    Accessing and modifying a glyph's properties.
1655 * Glyph Convenience Functions::  Accessing particular properties of a glyph.
1656 * Glyph Dimensions::    Determining the height, width, etc. of a glyph.
1657 * Glyph Types::         Each glyph has a particular type.
1658 @end menu
1659
1660
1661 @node Glyph Properties
1662 @subsection Glyph Properties
1663
1664 Each glyph has a list of properties, which control all of the aspects of
1665 the glyph's appearance.  The following symbols have predefined meanings:
1666
1667 @table @code
1668 @item image
1669 The image used to display the glyph.
1670
1671 @item baseline
1672 Percent above baseline that glyph is to be displayed.  Only for glyphs
1673 displayed inside of a buffer.
1674
1675 @item contrib-p
1676 Whether the glyph contributes to the height of the line it's on.
1677 Only for glyphs displayed inside of a buffer.
1678
1679 @item face
1680 Face of this glyph (@emph{not} a specifier).
1681 @end table
1682
1683 @defun set-glyph-property glyph property value &optional locale tag-set how-to-add
1684 This function changes a property of a @var{glyph}.
1685
1686 For built-in properties, the actual value of the property is a specifier
1687 and you cannot change this; but you can change the specifications within
1688 the specifier, and that is what this function will do.  The glyph face
1689 is an exception; it is a face name (a symbol) or a face object, not a
1690 specifier.  (The face properties themselves are typically specifiers.)
1691 For user-defined properties, you can use this function to either change
1692 the actual value of the property or, if this value is a specifier,
1693 change the specifications within it.
1694
1695 If @var{property} is a built-in property, the specifications to be added
1696 to this property can be supplied in many different ways:
1697
1698 @itemize @bullet
1699 @item
1700 If @var{value} is a simple instantiator (e.g. a string naming a pixmap
1701 filename) or a list of instantiators, then the instantiator(s) will be
1702 added as a specification of the property for the given @var{locale}
1703 (which defaults to @code{global} if omitted).
1704
1705 @item
1706 If @var{value} is a list of specifications (each of which is a cons of a
1707 locale and a list of instantiators), then @var{locale} must be
1708 @code{nil} (it does not make sense to explicitly specify a locale in
1709 this case), and specifications will be added as given.
1710
1711 @item
1712 If @var{value} is a specifier (as would be returned by
1713 @code{glyph-property} if no @var{locale} argument is given), then some
1714 or all of the specifications in the specifier will be added to the
1715 property.  In this case, the function is really equivalent to
1716 @code{copy-specifier} and @var{locale} has the same semantics (if it is
1717 a particular locale, the specification for the locale will be copied; if
1718 a locale type, specifications for all locales of that type will be
1719 copied; if @code{nil} or @code{all}, then all specifications will be
1720 copied).
1721 @end itemize
1722
1723 @var{how-to-add} should be either @code{nil} or one of the symbols
1724 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
1725 @code{remove-tag-set-append}, @code{remove-locale},
1726 @code{remove-locale-type}, or @code{remove-all}.  See
1727 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
1728 of what each of these means.  Most of the time, you do not need to worry
1729 about this argument; the default behavior usually is fine.
1730
1731 In general, it is OK to pass an instance object (e.g. as returned by
1732 @code{glyph-property-instance}) as an instantiator in place of an actual
1733 instantiator.  In such a case, the instantiator used to create that
1734 instance object will be used (for example, if you set a font-instance
1735 object as the value of the @code{font} property, then the font name used
1736 to create that object will be used instead).  In some cases, however,
1737 doing this conversion does not make sense, and this will be noted in the
1738 documentation for particular types of instance objects.
1739
1740 If @var{property} is not a built-in property, then this function will
1741 simply set its value if @var{locale} is @code{nil}.  However, if
1742 @var{locale} is given, then this function will attempt to add
1743 @var{value} as the instantiator for the given @var{locale}, using
1744 @code{add-spec-to-specifier}.  If the value of the property is not a
1745 specifier, it will automatically be converted into a @code{generic}
1746 specifier.
1747 @end defun
1748
1749 @defun glyph-property glyph property &optional locale
1750 This function returns @var{glyph}'s value of the given @var{property}.
1751
1752 If @var{locale} is omitted, the @var{glyph}'s actual value for
1753 @var{property} will be returned.  For built-in properties, this will be
1754 a specifier object of a type appropriate to the property (e.g. a font or
1755 color specifier).  For other properties, this could be anything.
1756
1757 If @var{locale} is supplied, then instead of returning the actual value,
1758 the specification(s) for the given locale or locale type will be
1759 returned.  This will only work if the actual value of @var{property} is
1760 a specifier (this will always be the case for built-in properties, but
1761 may or may not apply to user-defined properties).  If the actual value
1762 of @var{property} is not a specifier, this value will simply be returned
1763 regardless of @var{locale}.
1764
1765 The return value will be a list of instantiators (e.g. vectors
1766 specifying pixmap data), or a list of specifications, each of which is a
1767 cons of a locale and a list of instantiators.  Specifically, if
1768 @var{locale} is a particular locale (a buffer, window, frame, device, or
1769 @code{global}), a list of instantiators for that locale will be
1770 returned.  Otherwise, if @var{locale} is a locale type (one of the
1771 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
1772 the specifications for all locales of that type will be returned.
1773 Finally, if @var{locale} is @code{all}, the specifications for all
1774 locales of all types will be returned.
1775
1776 The specifications in a specifier determine what the value of
1777 @var{property} will be in a particular @dfn{domain} or set of
1778 circumstances, which is typically a particular Emacs window along with
1779 the buffer it contains and the frame and device it lies within.  The
1780 value is derived from the instantiator associated with the most specific
1781 locale (in the order buffer, window, frame, device, and @code{global})
1782 that matches the domain in question.  In other words, given a domain
1783 (i.e. an Emacs window, usually), the specifier for @var{property} will
1784 first be searched for a specification whose locale is the buffer
1785 contained within that window; then for a specification whose locale is
1786 the window itself; then for a specification whose locale is the frame
1787 that the window is contained within; etc.  The first instantiator that
1788 is valid for the domain (usually this means that the instantiator is
1789 recognized by the device [i.e. the X server or TTY device] that the
1790 domain is on).  The function @code{glyph-property-instance} actually does
1791 all this, and is used to determine how to display the glyph.
1792 @end defun
1793
1794 @defun glyph-property-instance glyph property &optional domain default no-fallback
1795 This function returns the instance of @var{glyph}'s @var{property} in the
1796 specified @var{domain}.
1797
1798 Under most circumstances, @var{domain} will be a particular window, and
1799 the returned instance describes how the specified property actually is
1800 displayed for that window and the particular buffer in it.  Note that
1801 this may not be the same as how the property appears when the buffer is
1802 displayed in a different window or frame, or how the property appears in
1803 the same window if you switch to another buffer in that window; and in
1804 those cases, the returned instance would be different.
1805
1806 The returned instance is an image-instance object, and you can query it
1807 using the appropriate image instance functions.  For example, you could use
1808 @code{image-instance-depth} to find out the depth (number of color
1809 planes) of a pixmap displayed in a particular window.  The results might
1810 be different from the results you would get for another window (perhaps
1811 the user specified a different image for the frame that window is on; or
1812 perhaps the same image was specified but the window is on a different X
1813 server, and that X server has different color capabilities from this
1814 one).
1815
1816 @var{domain} defaults to the selected window if omitted.
1817
1818 @var{domain} can be a frame or device, instead of a window.  The value
1819 returned for such a domain is used in special circumstances when a
1820 more specific domain does not apply; for example, a frame value might be
1821 used for coloring a toolbar, which is conceptually attached to a frame
1822 rather than a particular window.  The value is also useful in
1823 determining what the value would be for a particular window within the
1824 frame or device, if it is not overridden by a more specific
1825 specification.
1826
1827 If @var{property} does not name a built-in property, its value will
1828 simply be returned unless it is a specifier object, in which case it
1829 will be instanced using @code{specifier-instance}.
1830
1831 Optional arguments @var{default} and @var{no-fallback} are the same as
1832 in @code{specifier-instance}.  @xref{Specifiers}.
1833 @end defun
1834
1835 @defun remove-glyph-property glyph property &optional locale tag-set exact-p
1836 This function removes a property from a glyph.  For built-in properties,
1837 this is analogous to @code{remove-specifier}.  @xref{Specifiers,
1838 remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
1839 and @var{exact-p} arguments.
1840 @end defun
1841
1842
1843 @node Glyph Convenience Functions
1844 @subsection Glyph Convenience Functions
1845
1846   The following functions are provided for working with specific
1847 properties of a glyph.  Note that these are exactly like calling
1848 the general functions described above and passing in the
1849 appropriate value for @var{property}.
1850
1851   Remember that if you want to determine the ``value'' of a
1852 specific glyph property, you probably want to use the @code{*-instance}
1853 functions.  For example, to determine whether a glyph contributes
1854 to its line height, use @code{glyph-contrib-p-instance}, not
1855 @code{glyph-contrib-p}. (The latter will return a boolean specifier
1856 or a list of specifications, and you probably aren't concerned with
1857 these.)
1858
1859 @defun glyph-image glyph &optional locale
1860 This function is equivalent to calling @code{glyph-property} with
1861 a property of @code{image}.  The return value will be an image
1862 specifier if @var{locale} is @code{nil} or omitted; otherwise,
1863 it will be a specification or list of specifications.
1864 @end defun
1865
1866 @defun set-glyph-image glyph spec &optional locale tag-set how-to-add
1867 This function is equivalent to calling @code{set-glyph-property} with
1868 a property of @code{image}.
1869 @end defun
1870
1871 @defun glyph-image-instance glyph &optional domain default no-fallback
1872 This function returns the instance of @var{glyph}'s image in the given
1873 @var{domain}, and is equivalent to calling
1874 @code{glyph-property-instance} with a property of @code{image}.  The
1875 return value will be an image instance.
1876
1877 Normally @var{domain} will be a window or @code{nil} (meaning the
1878 selected window), and an instance object describing how the image
1879 appears in that particular window and buffer will be returned.
1880 @end defun
1881
1882 @defun glyph-contrib-p glyph &optional locale
1883 This function is equivalent to calling @code{glyph-property} with
1884 a property of @code{contrib-p}.  The return value will be a boolean
1885 specifier if @var{locale} is @code{nil} or omitted; otherwise,
1886 it will be a specification or list of specifications.
1887 @end defun
1888
1889 @defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
1890 This function is equivalent to calling @code{set-glyph-property} with
1891 a property of @code{contrib-p}.
1892 @end defun
1893
1894 @defun glyph-contrib-p-instance glyph &optional domain default no-fallback
1895 This function returns whether the glyph contributes to its line height
1896 in the given @var{domain}, and is equivalent to calling
1897 @code{glyph-property-instance} with a property of @code{contrib-p}.  The
1898 return value will be either @code{nil} or @code{t}. (Normally @var{domain}
1899 will be a window or @code{nil}, meaning the selected window.)
1900 @end defun
1901
1902 @defun glyph-baseline glyph &optional locale
1903 This function is equivalent to calling @code{glyph-property} with a
1904 property of @code{baseline}.  The return value will be a specifier if
1905 @var{locale} is @code{nil} or omitted; otherwise, it will be a
1906 specification or list of specifications.
1907 @end defun
1908
1909 @defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
1910 This function is equivalent to calling @code{set-glyph-property} with
1911 a property of @code{baseline}.
1912 @end defun
1913
1914 @defun glyph-baseline-instance glyph &optional domain default no-fallback
1915 This function returns the instance of @var{glyph}'s baseline value in
1916 the given @var{domain}, and is equivalent to calling
1917 @code{glyph-property-instance} with a property of @code{baseline}.  The
1918 return value will be an integer or @code{nil}.
1919
1920 Normally @var{domain} will be a window or @code{nil} (meaning the
1921 selected window), and an instance object describing the baseline value
1922 appears in that particular window and buffer will be returned.
1923 @end defun
1924
1925 @defun glyph-face glyph
1926 This function returns the face of @var{glyph}. (Remember, this is
1927 not a specifier, but a simple property.)
1928 @end defun
1929
1930 @defun set-glyph-face glyph face
1931 This function changes the face of @var{glyph} to @var{face}.
1932 @end defun
1933
1934
1935 @node Glyph Dimensions
1936 @subsection Glyph Dimensions
1937
1938 @defun glyph-width glyph &optional window
1939 This function returns the width of @var{glyph} on @var{window}.  This
1940 may not be exact as it does not take into account all of the context
1941 that redisplay will.
1942 @end defun
1943
1944 @defun glyph-ascent glyph &optional window
1945 This function returns the ascent value of @var{glyph} on @var{window}.
1946 This may not be exact as it does not take into account all of the
1947 context that redisplay will.
1948 @end defun
1949
1950 @defun glyph-descent glyph &optional window
1951 This function returns the descent value of @var{glyph} on @var{window}.
1952 This may not be exact as it does not take into account all of the
1953 context that redisplay will.
1954 @end defun
1955
1956 @defun glyph-height glyph &optional window
1957 This function returns the height of @var{glyph} on @var{window}.  (This
1958 is equivalent to the sum of the ascent and descent values.)  This may
1959 not be exact as it does not take into account all of the context that
1960 redisplay will.
1961 @end defun
1962
1963
1964 @node Glyph Types
1965 @subsection Glyph Types
1966
1967   Each glyph has a particular type, which controls how the glyph's image
1968 is generated.  Each glyph type has a corresponding list of allowable
1969 image instance types that can be generated.  When you call
1970 @code{glyph-image-instance} to retrieve the image instance of a glyph,
1971 XEmacs does the equivalent of calling @code{make-image-instance} and
1972 passing in @var{dest-types} the list of allowable image instance types
1973 for the glyph's type.
1974
1975 @itemize @bullet
1976 @item
1977 @code{buffer} glyphs can be used as the begin-glyph or end-glyph of an
1978 extent, in the modeline, and in the toolbar.  Their image can be
1979 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
1980 @code{text}, and @code{subwindow}.
1981 @c #### Check status of subwindows ... I thought Andy implemented them.
1982
1983 @item
1984 @code{pointer} glyphs can be used to specify the mouse pointer.  Their
1985 image can be instantiated as @code{pointer}.
1986
1987 @item
1988 @code{icon} glyphs can be used to specify the icon used when a frame is
1989 iconified.  Their image can be instantiated as @code{mono-pixmap} and
1990 @code{color-pixmap}.
1991 @end itemize
1992
1993 @defun glyph-type glyph
1994 This function returns the type of the given glyph.  The return value
1995 will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}.
1996 @end defun
1997
1998 @defun valid-glyph-type-p glyph-type
1999 Given a @var{glyph-type}, this function returns non-@code{nil} if it is
2000 valid.
2001 @end defun
2002
2003 @defun glyph-type-list
2004 This function returns a list of valid glyph types.
2005 @end defun
2006
2007 @defun buffer-glyph-p object
2008 This function returns non-@code{nil} if @var{object} is a glyph of type
2009 @code{buffer}.
2010 @end defun
2011
2012 @defun icon-glyph-p object
2013 This function returns non-@code{nil} if @var{object} is a glyph of type
2014 @code{icon}.
2015 @end defun
2016
2017 @defun pointer-glyph-p object
2018 This function returns non-@code{nil} if @var{object} is a glyph of type
2019 @code{pointer}.
2020 @end defun
2021
2022
2023 @node Glyph Examples
2024 @section Glyph Examples
2025
2026 For many applications, displaying graphics is a simple process: you
2027 create a glyph, and then you insert it into a buffer.
2028
2029 The easiest way to create a glyph is to use a file that contains a
2030 graphical image, such as a JPEG, TIFF, or PNG file:
2031
2032 @lisp
2033 ;; Create a glyph from a JPEG file:
2034 (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
2035 @end lisp
2036
2037 @lisp
2038 ;; Create a glyph from a XPM file:
2039 (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
2040 @end lisp
2041
2042 @lisp
2043 ;; Create a glyph from a PNG file:
2044 (setq foo (make-glyph [png :file "/tmp/file3.png"]))
2045 @end lisp
2046
2047 @lisp
2048 ;; Create a glyph from a TIFF file:
2049 (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
2050 @end lisp
2051
2052 The parameters passed to @code{make-glyph} are called "Image
2053 Specifiers", and can handle more image types than those shown above.
2054 You can also put the raw image data into a string (e.g., if you put the
2055 contents of a JPEG file into a string), and use that to create a glyph.
2056 @xref{Image Specifiers}, for more information.
2057
2058 @quotation
2059 @strong{Caution}: In order for XEmacs to read a particular graphics file
2060 format, support for that format must have been compiled into XEmacs.
2061 It's possible, although somewhat unlikely, for XEmacs to have been
2062 compiled without support for any of the various graphics file formats.
2063 To see what graphics formats your particular version of XEmacs supports,
2064 use @kbd{M-x describe-installation}.
2065
2066 To programmatically query whether or not a particular file format is
2067 supported, you can use the @code{featurep} function, with one of:
2068 @code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm},
2069 @code{png}, or @code{xface}.  For an up-to-date list, @ref{Image
2070 Specifiers}.  Example:
2071
2072 @example
2073 ;; Returns `t' if TIFF is supported:
2074 (featurep 'tiff)
2075 @end example
2076
2077 Another example is:
2078
2079 @example
2080 ;; Returns a list of `t' or `nil', depending on whether or not the
2081 ;; corresponding feature is supported:
2082 (mapcar #'(lambda (format-symbol) (featurep format-symbol))
2083         '(gif tiff jpeg xpm png))
2084 @end example
2085
2086 @end quotation
2087
2088 Once you have a glyph, you can then insert it into a buffer.  Example:
2089
2090 @lisp
2091 ;; Use this function to insert a glyph at the left edge of point in the
2092 ;; current buffer.  Any existing glyph at this location is replaced.
2093 (defun insert-glyph (gl)
2094   "Insert a glyph at the left edge of point."
2095   (let ( (prop 'myimage)        ;; myimage is an arbitrary name, chosen
2096                                 ;; to (hopefully) not conflict with any
2097                                 ;; other properties.  Change it if
2098                                 ;; necessary.
2099          extent )
2100     ;; First, check to see if one of our extents already exists at
2101     ;; point.  For ease-of-programming, we are creating and using our
2102     ;; own extents (multiple extents are allowed to exist/overlap at the
2103     ;; same point, and it's quite possible for other applications to
2104     ;; embed extents in the current buffer without your knowledge).
2105     ;; Basically, if an extent, with the property stored in "prop",
2106     ;; exists at point, we assume that it is one of ours, and we re-use
2107     ;; it (this is why it is important for the property stored in "prop"
2108     ;; to be unique, and only used by us).
2109     (if (not (setq extent (extent-at (point) (current-buffer) prop)))
2110       (progn
2111         ;; If an extent does not already exist, create a zero-length
2112         ;; extent, and give it our special property.
2113         (setq extent (make-extent (point) (point) (current-buffer)))
2114         (set-extent-property extent prop t)
2115         ))
2116     ;; Display the glyph by storing it as the extent's "begin-glyph".
2117     (set-extent-property extent 'begin-glyph gl)
2118     ))
2119
2120 ;; You can then use this function like:
2121 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
2122 ;; This will insert the glyph at point.
2123
2124 ;; Here's an example of how to insert two glyphs side-by-side, at point
2125 ;; (using the above code):
2126 (progn
2127   (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
2128   ;; Create a new extent at point.  We can't simply call "insert-glyph",
2129   ;; as "insert-glyph" will simply replace the first glyph with the
2130   ;; second.
2131   (setq extent (make-extent (point) (point) (current-buffer)))
2132   ;; Here, we're only setting the 'myimage property in case we need
2133   ;; to later identify/locate/reuse this particular extent.
2134   (set-extent-property extent 'myimage t)
2135   (set-extent-property extent 'begin-glyph
2136                        (make-glyph [jpeg :file "/tmp/file2.jpg"]))
2137   )
2138
2139 @end lisp
2140
2141 Here are the gory details:
2142
2143 @itemize @bullet
2144
2145 @item
2146 Glyphs are displayed by attaching them to extents (see @ref{Extents}),
2147 either to the beginning or the end of extents.
2148
2149 Note that extents can be used for many things, and not just for
2150 displaying images (although, in the above example, we are creating our
2151 own extent for the sole purpose of displaying an image).  Also, note
2152 that multiple extents are allowed to exist at the same position, and
2153 they can overlap.
2154
2155 @item
2156 Glyphs are often displayed inside the text area (alongside text).  This
2157 is the default.
2158
2159 Although glyphs can also be displayed in the margins, how to do this
2160 will not be described here.  For more information on this, see
2161 @ref{Annotation Basics} (look for information on "layout types") and
2162 @ref{Extent Properties} (look for @code{begin-glyph-layout} and
2163 @code{end-glyph-layout}).
2164
2165 @item
2166 The easiest way to insert a glyph into text is to create a zero-length
2167 extent at the point where you want the glyph to appear.
2168
2169 Note that zero-length extents are attached to the character to the
2170 right of the extent; deleting this character will also delete the extent.
2171
2172 @item
2173 It's often a good idea to assign a unique property to the newly-created
2174 extent, in case you later want to locate it, and replace any existing
2175 glyph with a different one (or just delete the existing one).  In the
2176 above example, we are using "myimage" as our (hopefully) unique property
2177 name.
2178
2179 If you need to locate all of the extents, you'll have to use functions
2180 like @code{extent-list} or @code{next-extent}, or provide additional
2181 parameters to the @code{extent-at} function.  Assigning a unique
2182 property to the extent makes it easy to locate your extents; for
2183 example, @code{extent-list} can return only those extents with a
2184 particular property.  @xref{Finding Extents}, and @ref{Mapping Over
2185 Extents}, for more information.
2186
2187 @item
2188 Glyphs are displayed by assigning then to the @code{begin-glyph} or
2189 @code{end-glyph} property of the extent.  For zero-length extents, it
2190 doesn't really matter if you assign the glyph to the @code{begin-glyph}
2191 or @code{end-glyph} property, as they are both at the same location;
2192 however, for non-zero-length extents (extents that cover one or more
2193 characters of text), it does matter which one you use.
2194
2195 Assigning @code{nil} to the @code{begin-glyph} or @code{end-glyph}
2196 property will delete any existing glyph.  In this case, you may also
2197 want to delete the extent, assuming that the extent is used for no other
2198 purpose.
2199
2200 @item
2201 If you happen to insert two glyphs, side-by-side, note that the example
2202 @code{insert-glyph} function will have trouble, if it's again used at
2203 the same point (it can only locate one of the two extents).
2204 @xref{Finding Extents}, and @ref{Mapping Over Extents}, for more
2205 information on locating extents in a buffer.
2206
2207 @item
2208 Among other things, glyphs provide a way of displaying graphics
2209 alongside text.  Note, however, that glyphs only provide a way of
2210 displaying graphics; glyphs are not actually part of the text, and are
2211 only displayed alongside the text.  If you save the text in the buffer,
2212 the graphics are not saved.  The low-level glyph code does not provide a
2213 way of saving graphics with the text.  If you need to save graphics and
2214 text, you have to write your own code to do this, and this topic is
2215 outside the scope of this discussion.
2216
2217 @end itemize