2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1995, 1996 Ben Wing.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/glyphs.info
6 @node Glyphs, Annotations, Faces and Window-System Objects, top
10 A @dfn{glyph} is an object that is used for pixmaps and images of all
11 sorts, as well as for things that ``act'' like pixmaps, such as
12 non-textual strings (@dfn{annotations}) displayed in a buffer or in the
13 margins. It is used in begin-glyphs and end-glyphs attached to extents,
14 marginal and textual annotations, overlay arrows (@code{overlay-arrow-*}
15 variables), toolbar buttons, mouse pointers, frame icons, truncation and
16 continuation markers, and the like. (Basically, any place there is an
17 image or something that acts like an image, there will be a glyph object
20 The actual image that is displayed (as opposed to its position or
21 clipping) is defined by an @dfn{image specifier} object contained
22 within the glyph. The separation between an image specifier object
23 and a glyph object is made because the glyph includes other properties
24 than just the actual image: e.g. the face it is displayed in (for text
25 images), the alignment of the image (when it is in a buffer), etc.
28 This function returns @code{t} if @var{object} is a glyph.
32 * Glyph Functions:: Functions for working with glyphs.
33 * Images:: Graphical images displayed in a frame.
34 * Glyph Types:: Each glyph has a particular type.
35 * Mouse Pointer:: Controlling the mouse pointer.
36 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
37 * Subwindows:: Inserting an externally-controlled subwindow
42 @section Glyph Functions
45 * Creating Glyphs:: Creating new glyphs.
46 * Glyph Properties:: Accessing and modifying a glyph's properties.
47 * Glyph Convenience Functions::
48 Convenience functions for accessing particular
49 properties of a glyph.
50 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
54 @subsection Creating Glyphs
56 @defun make-glyph &optional spec-list type
57 This function creates a new glyph object of type @var{type}.
59 @var{spec-list} is used to initialize the glyph's image. It is
60 typically an image instantiator (a string or a vector; @ref{Image
61 Specifiers}), but can also be a list of such instantiators (each one in
62 turn is tried until an image is successfully produced), a cons of a
63 locale (frame, buffer, etc.) and an instantiator, a list of such conses,
64 or any other form accepted by @code{canonicalize-spec-list}.
65 @xref{Specifiers}, for more information about specifiers.
67 @var{type} specifies the type of the glyph, which specifies in which
68 contexts the glyph can be used, and controls the allowable image types
69 into which the glyph's image can be instantiated. @var{type} should be
70 one of @code{buffer} (used for glyphs in an extent, the modeline, the
71 toolbar, or elsewhere in a buffer), @code{pointer} (used for the
72 mouse-pointer), or @code{icon} (used for a frame's icon), and defaults
73 to @code{buffer}. @xref{Glyph Types}.
76 @defun make-glyph-internal &optional type
77 This function creates a new, uninitialized glyph of type @var{type}.
80 @defun make-pointer-glyph &optional spec-list
81 This function is equivalent to calling @code{make-glyph} with a
82 @var{type} of @code{pointer}.
85 @defun make-icon-glyph &optional spec-list
86 This function is equivalent to calling @code{make-glyph} with a
87 @var{type} of @code{icon}.
90 @node Glyph Properties
91 @subsection Glyph Properties
93 Each glyph has a list of properties, which control all of the aspects of
94 the glyph's appearance. The following symbols have predefined meanings:
98 The image used to display the glyph.
101 Percent above baseline that glyph is to be displayed. Only for glyphs
102 displayed inside of a buffer.
105 Whether the glyph contributes to the height of the line it's on.
106 Only for glyphs displayed inside of a buffer.
109 Face of this glyph (@emph{not} a specifier).
112 @defun set-glyph-property glyph property value &optional locale tag-set how-to-add
113 This function changes a property of a @var{glyph}.
115 For built-in properties, the actual value of the property is a specifier
116 and you cannot change this; but you can change the specifications within
117 the specifier, and that is what this function will do. For user-defined
118 properties, you can use this function to either change the actual value
119 of the property or, if this value is a specifier, change the
120 specifications within it.
122 If @var{property} is a built-in property, the specifications to be added
123 to this property can be supplied in many different ways:
127 If @var{value} is a simple instantiator (e.g. a string naming a pixmap
128 filename) or a list of instantiators, then the instantiator(s) will be
129 added as a specification of the property for the given @var{locale}
130 (which defaults to @code{global} if omitted).
133 If @var{value} is a list of specifications (each of which is a cons of a
134 locale and a list of instantiators), then @var{locale} must be
135 @code{nil} (it does not make sense to explicitly specify a locale in
136 this case), and specifications will be added as given.
139 If @var{value} is a specifier (as would be returned by
140 @code{glyph-property} if no @var{locale} argument is given), then some
141 or all of the specifications in the specifier will be added to the
142 property. In this case, the function is really equivalent to
143 @code{copy-specifier} and @var{locale} has the same semantics (if it is
144 a particular locale, the specification for the locale will be copied; if
145 a locale type, specifications for all locales of that type will be
146 copied; if @code{nil} or @code{all}, then all specifications will be
150 @var{how-to-add} should be either @code{nil} or one of the symbols
151 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
152 @code{remove-tag-set-append}, @code{remove-locale},
153 @code{remove-locale-type}, or @code{remove-all}. See
154 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
155 of what each of these means. Most of the time, you do not need to worry
156 about this argument; the default behavior usually is fine.
158 In general, it is OK to pass an instance object (e.g. as returned by
159 @code{glyph-property-instance}) as an instantiator in place of an actual
160 instantiator. In such a case, the instantiator used to create that
161 instance object will be used (for example, if you set a font-instance
162 object as the value of the @code{font} property, then the font name used
163 to create that object will be used instead). If some cases, however,
164 doing this conversion does not make sense, and this will be noted in the
165 documentation for particular types of instance objects.
167 If @var{property} is not a built-in property, then this function will
168 simply set its value if @var{locale} is @code{nil}. However, if
169 @var{locale} is given, then this function will attempt to add
170 @var{value} as the instantiator for the given @var{locale}, using
171 @code{add-spec-to-specifier}. If the value of the property is not a
172 specifier, it will automatically be converted into a @code{generic}
176 @defun glyph-property glyph property &optional locale
177 This function returns @var{glyph}'s value of the given @var{property}.
179 If @var{locale} is omitted, the @var{glyph}'s actual value for
180 @var{property} will be returned. For built-in properties, this will be
181 a specifier object of a type appropriate to the property (e.g. a font or
182 color specifier). For other properties, this could be anything.
184 If @var{locale} is supplied, then instead of returning the actual value,
185 the specification(s) for the given locale or locale type will be
186 returned. This will only work if the actual value of @var{property} is
187 a specifier (this will always be the case for built-in properties, but
188 may or may not apply to user-defined properties). If the actual value
189 of @var{property} is not a specifier, this value will simply be returned
190 regardless of @var{locale}.
192 The return value will be a list of instantiators (e.g. vectors
193 specifying pixmap data), or a list of specifications, each of which is a
194 cons of a locale and a list of instantiators. Specifically, if
195 @var{locale} is a particular locale (a buffer, window, frame, device, or
196 @code{global}), a list of instantiators for that locale will be
197 returned. Otherwise, if @var{locale} is a locale type (one of the
198 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
199 the specifications for all locales of that type will be returned.
200 Finally, if @var{locale} is @code{all}, the specifications for all
201 locales of all types will be returned.
203 The specifications in a specifier determine what the value of
204 @var{property} will be in a particular @dfn{domain} or set of
205 circumstances, which is typically a particular Emacs window along with
206 the buffer it contains and the frame and device it lies within. The
207 value is derived from the instantiator associated with the most specific
208 locale (in the order buffer, window, frame, device, and @code{global})
209 that matches the domain in question. In other words, given a domain
210 (i.e. an Emacs window, usually), the specifier for @var{property} will
211 first be searched for a specification whose locale is the buffer
212 contained within that window; then for a specification whose locale is
213 the window itself; then for a specification whose locale is the frame
214 that the window is contained within; etc. The first instantiator that
215 is valid for the domain (usually this means that the instantiator is
216 recognized by the device [i.e. the X server or TTY device] that the
217 domain is on). The function @code{glyph-property-instance} actually does
218 all this, and is used to determine how to display the glyph.
221 @defun glyph-property-instance glyph property &optional domain default no-fallback
222 This function returns the instance of @var{glyph}'s @var{property} in the
223 specified @var{domain}.
225 Under most circumstances, @var{domain} will be a particular window, and
226 the returned instance describes how the specified property actually is
227 displayed for that window and the particular buffer in it. Note that
228 this may not be the same as how the property appears when the buffer is
229 displayed in a different window or frame, or how the property appears in
230 the same window if you switch to another buffer in that window; and in
231 those cases, the returned instance would be different.
233 The returned instance is an image-instance object, and you can query it
234 using the appropriate image instance functions. For example, you could use
235 @code{image-instance-depth} to find out the depth (number of color
236 planes) of a pixmap displayed in a particular window. The results might
237 be different from the results you would get for another window (perhaps
238 the user specified a different image for the frame that window is on; or
239 perhaps the same image was specified but the window is on a different X
240 server, and that X server has different color capabilities from this
243 @var{domain} defaults to the selected window if omitted.
245 @var{domain} can be a frame or device, instead of a window. The value
246 returned for such a domain is used in special circumstances when a
247 more specific domain does not apply; for example, a frame value might be
248 used for coloring a toolbar, which is conceptually attached to a frame
249 rather than a particular window. The value is also useful in
250 determining what the value would be for a particular window within the
251 frame or device, if it is not overridden by a more specific
254 If @var{property} does not name a built-in property, its value will
255 simply be returned unless it is a specifier object, in which case it
256 will be instanced using @code{specifier-instance}.
258 Optional arguments @var{default} and @var{no-fallback} are the same as
259 in @code{specifier-instance}. @xref{Specifiers}.
262 @defun remove-glyph-property glyph property &optional locale tag-set exact-p
263 This function removes a property from a glyph. For built-in properties,
264 this is analogous to @code{remove-specifier}. @xref{Specifiers,
265 remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
266 and @var{exact-p} arguments.
269 @node Glyph Convenience Functions
270 @subsection Glyph Convenience Functions
272 The following functions are provided for working with specific
273 properties of a glyph. Note that these are exactly like calling
274 the general functions described above and passing in the
275 appropriate value for @var{property}.
277 Remember that if you want to determine the ``value'' of a
278 specific glyph property, you probably want to use the @code{*-instance}
279 functions. For example, to determine whether a glyph contributes
280 to its line height, use @code{glyph-contrib-p-instance}, not
281 @code{glyph-contrib-p}. (The latter will return a boolean specifier
282 or a list of specifications, and you probably aren't concerned with
285 @defun glyph-image glyph &optional locale
286 This function is equivalent to calling @code{glyph-property} with
287 a property of @code{image}. The return value will be an image
288 specifier if @var{locale} is @code{nil} or omitted; otherwise,
289 it will be a specification or list of specifications.
292 @defun set-glyph-image glyph spec &optional locale tag-set how-to-add
293 This function is equivalent to calling @code{set-glyph-property} with
294 a property of @code{image}.
297 @defun glyph-image-instance glyph &optional domain default no-fallback
298 This function returns the instance of @var{glyph}'s image in the given
299 @var{domain}, and is equivalent to calling
300 @code{glyph-property-instance} with a property of @code{image}. The
301 return value will be an image instance.
303 Normally @var{domain} will be a window or @code{nil} (meaning the
304 selected window), and an instance object describing how the image
305 appears in that particular window and buffer will be returned.
308 @defun glyph-contrib-p glyph &optional locale
309 This function is equivalent to calling @code{glyph-property} with
310 a property of @code{contrib-p}. The return value will be a boolean
311 specifier if @var{locale} is @code{nil} or omitted; otherwise,
312 it will be a specification or list of specifications.
315 @defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
316 This function is equivalent to calling @code{set-glyph-property} with
317 a property of @code{contrib-p}.
320 @defun glyph-contrib-p-instance glyph &optional domain default no-fallback
321 This function returns whether the glyph contributes to its line height
322 in the given @var{domain}, and is equivalent to calling
323 @code{glyph-property-instance} with a property of @code{contrib-p}. The
324 return value will be either @code{nil} or @code{t}. (Normally @var{domain}
325 will be a window or @code{nil}, meaning the selected window.)
328 @defun glyph-baseline glyph &optional locale
329 This function is equivalent to calling @code{glyph-property} with a
330 property of @code{baseline}. The return value will be a specifier if
331 @var{locale} is @code{nil} or omitted; otherwise, it will be a
332 specification or list of specifications.
335 @defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
336 This function is equivalent to calling @code{set-glyph-property} with
337 a property of @code{baseline}.
340 @defun glyph-baseline-instance glyph &optional domain default no-fallback
341 This function returns the instance of @var{glyph}'s baseline value in
342 the given @var{domain}, and is equivalent to calling
343 @code{glyph-property-instance} with a property of @code{baseline}. The
344 return value will be an integer or @code{nil}.
346 Normally @var{domain} will be a window or @code{nil} (meaning the
347 selected window), and an instance object describing the baseline value
348 appears in that particular window and buffer will be returned.
351 @defun glyph-face glyph
352 This function returns the face of @var{glyph}. (Remember, this is
353 not a specifier, but a simple property.)
356 @defun set-glyph-face glyph face
357 This function changes the face of @var{glyph} to @var{face}.
360 @node Glyph Dimensions
361 @subsection Glyph Dimensions
363 @defun glyph-width glyph &optional window
364 This function returns the width of @var{glyph} on @var{window}. This
365 may not be exact as it does not take into account all of the context
369 @defun glyph-ascent glyph &optional window
370 This function returns the ascent value of @var{glyph} on @var{window}.
371 This may not be exact as it does not take into account all of the
372 context that redisplay will.
375 @defun glyph-descent glyph &optional window
376 This function returns the descent value of @var{glyph} on @var{window}.
377 This may not be exact as it does not take into account all of the
378 context that redisplay will.
381 @defun glyph-height glyph &optional window
382 This function returns the height of @var{glyph} on @var{window}. (This
383 is equivalent to the sum of the ascent and descent values.) This may
384 not be exact as it does not take into account all of the context that
392 * Image Specifiers:: Specifying how an image will appear.
393 * Image Instantiator Conversion::
394 Conversion is applied to image instantiators
395 at the time they are added to an
396 image specifier or at the time they
397 are passed to @code{make-image-instance}.
398 * Image Instances:: What an image specifier gets instanced as.
401 @node Image Specifiers
402 @subsection Image Specifiers
403 @cindex image specifiers
405 An image specifier is used to describe the actual image of a glyph.
406 It works like other specifiers (@pxref{Specifiers}), in that it contains
407 a number of specifications describing how the image should appear in a
408 variety of circumstances. These specifications are called @dfn{image
409 instantiators}. When XEmacs wants to display the image, it instantiates
410 the image into an @dfn{image instance}. Image instances are their own
411 primitive object type (similar to font instances and color instances),
412 describing how the image appears in a particular domain. (On the other
413 hand, image instantiators, which are just descriptions of how the image
414 should appear, are represented using strings or vectors.)
416 @defun image-specifier-p object
417 This function returns non-@code{nil} if @var{object} is an image specifier.
418 Usually, an image specifier results from calling @code{glyph-image} on
422 @defun make-image-specifier spec-list
423 This function creates a new image specifier object and initializes
424 it according to @var{spec-list}. It is unlikely that you will ever
425 want to do this, but this function is provided for completeness and
426 for experimentation purposes. @xref{Specifiers}.
429 Image instantiators come in many formats: @code{xbm}, @code{xpm},
430 @code{gif}, @code{jpeg}, etc. This describes the format of the data
431 describing the image. The resulting image instances also come in many
432 types -- @code{mono-pixmap}, @code{color-pixmap}, @code{text},
433 @code{pointer}, etc. This refers to the behavior of the image and the
434 sorts of places it can appear. (For example, a color-pixmap image has
435 fixed colors specified for it, while a mono-pixmap image comes in two
436 unspecified shades ``foreground'' and ``background'' that are determined
437 from the face of the glyph or surrounding text; a text image appears as
438 a string of text and has an unspecified foreground, background, and
439 font; a pointer image behaves like a mono-pixmap image but can only be
440 used as a mouse pointer [mono-pixmap images cannot be used as mouse
441 pointers]; etc.) It is important to keep the distinction between image
442 instantiator format and image instance type in mind. Typically, a given
443 image instantiator format can result in many different image instance
444 types (for example, @code{xpm} can be instanced as @code{color-pixmap},
445 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
446 instanced only as @code{pointer}), and a particular image instance type
447 can be generated by many different image instantiator formats (e.g.
448 @code{color-pixmap} can be generated by @code{xpm}, @code{gif},
451 @xref{Image Instances}, for a more detailed discussion of image
454 An image instantiator should be a string or a vector of the form
457 @code{[@var{format} @var{:keyword} @var{value} ...]}
460 i.e. a format symbol followed by zero or more alternating keyword-value
461 pairs. The @dfn{format} field should be a symbol, one of
465 (Don't display anything; no keywords are valid for this. Can only be
466 instanced as @code{nothing}.)
468 (Display this image as a text string. Can only be instanced
469 as @code{text}, although support for instancing as @code{mono-pixmap}
471 @item formatted-string
472 (Display this image as a text string with replaceable fields,
473 similar to a modeline format string; not currently implemented.)
475 (An X bitmap; only if X support was compiled into this XEmacs. Can be
476 instanced as @code{mono-pixmap}, @code{color-pixmap}, or
479 (An XPM pixmap; only if XPM support was compiled into this XEmacs. Can
480 be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
481 @code{pointer}. XPM is an add-on library for X that was designed to
482 rectify the shortcomings of the XBM format. Most implementations of X
483 include the XPM library as a standard part. If your vendor does not, it
484 is highly recommended that you download it and install it. You can get
485 it from the standard XEmacs FTP site, among other places.)
487 (An X-Face bitmap, used to encode people's faces in e-mail messages;
488 only if X-Face support was compiled into this XEmacs. Can be instanced
489 as @code{mono-pixmap}, @code{color-pixmap}, or @code{pointer}.)
491 (A GIF87 or GIF89 image; only if GIF support was compiled into this
492 XEmacs. Can be instanced as @code{color-pixmap}. Note that XEmacs
493 includes GIF decoding functions as a standard part of it, so if you have
494 X support, you will normally have GIF support, unless you explicitly
495 disable it at configure time.)
497 (A JPEG-format image; only if JPEG support was compiled into this
498 XEmacs. Can be instanced as @code{color-pixmap}. If you have the JPEG
499 libraries present on your system when XEmacs is built, XEmacs will
500 automatically detect this and use them, unless you explicitly disable it
503 (A PNG/GIF24 image; only if PNG support was compiled into this XEmacs.
504 Can be instanced as @code{color-pixmap}.)
506 (A TIFF-format image; only if TIFF support was compiled into this XEmacs.
507 Not currently implemented.)
509 (One of the standard cursor-font names, such as @samp{watch} or
510 @samp{right_ptr} under X. Under X, this is, more specifically, any of
511 the standard cursor names from appendix B of the Xlib manual [also known
512 as the file @file{<X11/cursorfont.h>}] minus the @samp{XC_} prefix. On
513 other window systems, the valid names will be specific to the type of
514 window system. Can only be instanced as @code{pointer}.)
516 (A glyph from a font; i.e. the name of a font, and glyph index into it
517 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
518 Only if X support was compiled into this XEmacs. Currently can only be
519 instanced as @code{pointer}, although this should probably be fixed.)
521 (An embedded X window; not currently implemented.)
523 (XEmacs tries to guess what format the data is in. If X support exists,
524 the data string will be checked to see if it names a filename. If so,
525 and this filename contains XBM or XPM data, the appropriate sort of
526 pixmap or pointer will be created. [This includes picking up any
527 specified hotspot or associated mask file.] Otherwise, if @code{pointer}
528 is one of the allowable image-instance types and the string names a
529 valid cursor-font name, the image will be created as a pointer.
530 Otherwise, the image will be displayed as text. If no X support exists,
531 the image will always be displayed as text.)
534 The valid keywords are:
538 (Inline data. For most formats above, this should be a string. For
539 XBM images, this should be a list of three elements: width, height, and
540 a string of bit data. This keyword is not valid for instantiator
541 format @code{nothing}.)
544 (Data is contained in a file. The value is the name of this file. If
545 both @code{:data} and @code{:file} are specified, the image is created
546 from what is specified in @code{:data} and the string in @code{:file}
547 becomes the value of the @code{image-instance-file-name} function when
548 applied to the resulting image-instance. This keyword is not valid for
549 instantiator formats @code{nothing}, @code{string},
550 @code{formatted-string}, @code{cursor-font}, @code{font}, and
555 (For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
556 These keywords allow you to explicitly specify foreground and background
557 colors. The argument should be anything acceptable to
558 @code{make-color-instance}. This will cause what would be a
559 @code{mono-pixmap} to instead be colorized as a two-color color-pixmap,
560 and specifies the foreground and/or background colors for a pointer
561 instead of black and white.)
564 (For @code{xbm} and @code{xface}. This specifies a mask to be used with the
565 bitmap. The format is a list of width, height, and bits, like for
569 (For @code{xbm} and @code{xface}. This specifies a file containing the
570 mask data. If neither a mask file nor inline mask data is given for an
571 XBM image, and the XBM image comes from a file, XEmacs will look for a
572 mask file with the same name as the image file but with @samp{Mask} or
573 @samp{msk} appended. For example, if you specify the XBM file
574 @file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
575 the associated mask file @file{left_ptrmsk} will automatically be picked
580 (For @code{xbm} and @code{xface}. These keywords specify a hotspot if
581 the image is instantiated as a @code{pointer}. Note that if the XBM
582 image file specifies a hotspot, it will automatically be picked up if no
583 explicit hotspot is given.)
586 (Only for @code{xpm}. This specifies an alist that maps strings that
587 specify symbolic color names to the actual color to be used for that
588 symbolic color (in the form of a string or a color-specifier object).
589 If this is not specified, the contents of @code{xpm-color-symbols} are
590 used to generate the alist.)
593 If instead of a vector, the instantiator is a string, it will be
594 converted into a vector by looking it up according to the specs in the
595 @code{console-type-image-conversion-list} for the console type of
596 the domain (usually a window; sometimes a frame or device) over which
597 the image is being instantiated.
599 If the instantiator specifies data from a file, the data will be read in
600 at the time that the instantiator is added to the image specifier (which
601 may be well before the image is actually displayed), and the
602 instantiator will be converted into one of the inline-data forms, with
603 the filename retained using a @code{:file} keyword. This implies that
604 the file must exist when the instantiator is added to the image, but
605 does not need to exist at any other time (e.g. it may safely be a
608 @defun valid-image-instantiator-format-p format
609 This function returns non-@code{nil} if @var{format} is a valid image
610 instantiator format. Note that the return value for many formats listed
611 above depends on whether XEmacs was compiled with support for that format.
614 @defun image-instantiator-format-list
615 This function return a list of valid image-instantiator formats.
618 @defvar xpm-color-symbols
619 This variable holds definitions of logical color-names used when reading
620 XPM files. Elements of this list should be of the form
621 @code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name}
622 should be a string, which is the name of the color to define; the
623 @var{form-to-evaluate} should evaluate to a color specifier object, or a
624 string to be passed to @code{make-color-instance} (@pxref{Colors}). If
625 a loaded XPM file references a symbolic color called @var{color-name},
626 it will display as the computed color instead.
628 The default value of this variable defines the logical color names
629 @samp{"foreground"} and @samp{"background"} to be the colors of the
633 @defvar x-bitmap-file-path
634 A list of the directories in which X bitmap files may be found. If nil,
635 this is initialized from the @samp{"*bitmapFilePath"} resource. This is
636 used by the @code{make-image-instance} function (however, note that if
637 the environment variable @samp{XBMLANGPATH} is set, it is consulted
641 @node Image Instantiator Conversion
642 @subsection Image Instantiator Conversion
643 @cindex image instantiator conversion
644 @cindex conversion of image instantiators
646 @defun set-console-type-image-conversion-list console-type list
647 This function sets the image-conversion-list for consoles of the given
648 @var{console-type}. The image-conversion-list specifies how image
649 instantiators that are strings should be interpreted. Each element of
650 the list should be a list of two elements (a regular expression string
651 and a vector) or a list of three elements (the preceding two plus an
652 integer index into the vector). The string is converted to the vector
653 associated with the first matching regular expression. If a vector
654 index is specified, the string itself is substituted into that position
657 Note: The conversion above is applied when the image instantiator is
658 added to an image specifier, not when the specifier is actually
659 instantiated. Therefore, changing the image-conversion-list only affects
660 newly-added instantiators. Existing instantiators in glyphs and image
661 specifiers will not be affected.
664 @defun console-type-image-conversion-list console-type
665 This function returns the image-conversion-list for consoles of the given
669 @node Image Instances
670 @subsection Image Instances
671 @cindex image instances
673 Image-instance objects encapsulate the way a particular image (pixmap,
674 etc.) is displayed on a particular device.
676 In most circumstances, you do not need to directly create image
677 instances; use a glyph instead. However, it may occasionally be useful
678 to explicitly create image instances, if you want more control over the
679 instantiation process.
681 @defun image-instance-p object
682 This function returns non-@code{nil} if @var{object} is an image instance.
686 * Image Instance Types:: Each image instances has a particular type.
687 * Image Instance Functions:: Functions for working with image instances.
690 @node Image Instance Types
691 @subsubsection Image Instance Types
692 @cindex image instance types
694 Image instances come in a number of different types. The type
695 of an image instance specifies the nature of the image: Whether
696 it is a text string, a mono pixmap, a color pixmap, etc.
698 The valid image instance types are
702 Nothing is displayed.
705 Displayed as text. The foreground and background colors and the
706 font of the text are specified independent of the pixmap. Typically
707 these attributes will come from the face of the surrounding text,
708 unless a face is specified for the glyph in which the image appears.
711 Displayed as a mono pixmap (a pixmap with only two colors where the
712 foreground and background can be specified independent of the pixmap;
713 typically the pixmap assumes the foreground and background colors of
714 the text around it, unless a face is specified for the glyph in which
718 Displayed as a color pixmap.
721 Used as the mouse pointer for a window.
724 A child window that is treated as an image. This allows (e.g.)
725 another program to be responsible for drawing into the window.
726 Not currently implemented.
729 @defun valid-image-instance-type-p type
730 This function returns non-@code{nil} if @var{type} is a valid image
734 @defun image-instance-type-list
735 This function returns a list of the valid image instance types.
738 @defun image-instance-type image-instance
739 This function returns the type of the given image instance. The return
740 value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
741 @code{color-pixmap}, @code{pointer}, or @code{subwindow}.
744 @defun text-image-instance-p object
745 This function returns non-@code{nil} if @var{object} is an image
746 instance of type @code{text}.
749 @defun mono-pixmap-image-instance-p object
750 This function returns non-@code{nil} if @var{object} is an image
751 instance of type @code{mono-pixmap}.
754 @defun color-pixmap-image-instance-p object
755 This function returns non-@code{nil} if @var{object} is an image
756 instance of type @code{color-pixmap}.
759 @defun pointer-image-instance-p object
760 This function returns non-@code{nil} if @var{object} is an image
761 instance of type @code{pointer}.
764 @defun subwindow-image-instance-p object
765 This function returns non-@code{nil} if @var{object} is an image
766 instance of type @code{subwindow}.
769 @defun nothing-image-instance-p object
770 This function returns non-@code{nil} if @var{object} is an image
771 instance of type @code{nothing}.
774 @node Image Instance Functions
775 @subsubsection Image Instance Functions
777 @defun make-image-instance data &optional device dest-types no-error
778 This function creates a new image-instance object.
780 @var{data} is an image instantiator, which describes the image
781 (@pxref{Image Specifiers}).
783 @var{dest-types} should be a list of allowed image instance types that
784 can be generated. The @var{dest-types} list is unordered. If multiple
785 destination types are possible for a given instantiator, the ``most
786 natural'' type for the instantiator's format is chosen. (For XBM, the
787 most natural types are @code{mono-pixmap}, followed by
788 @code{color-pixmap}, followed by @code{pointer}. For the other normal
789 image formats, the most natural types are @code{color-pixmap}, followed
790 by @code{mono-pixmap}, followed by @code{pointer}. For the string and
791 formatted-string formats, the most natural types are @code{text},
792 followed by @code{mono-pixmap} (not currently implemented), followed by
793 @code{color-pixmap} (not currently implemented). The other formats can
794 only be instantiated as one type. (If you want to control more
795 specifically the order of the types into which an image is instantiated,
796 just call @code{make-image-instance} repeatedly until it succeeds,
797 passing less and less preferred destination types each time.
799 If @var{dest-types} is omitted, all possible types are allowed.
801 @var{no-error} controls what happens when the image cannot be generated.
802 If @var{nil}, an error message is generated. If @var{t}, no messages
803 are generated and this function returns @var{nil}. If anything else, a
804 warning message is generated and this function returns @var{nil}.
807 @defun colorize-image-instance image-instance foreground background
808 This function makes the image instance be displayed in the given
809 colors. Image instances come in two varieties: bitmaps, which are 1
810 bit deep which are rendered in the prevailing foreground and background
811 colors; and pixmaps, which are of arbitrary depth (including 1) and
812 which have the colors explicitly specified. This function converts a
813 bitmap to a pixmap. If the image instance was a pixmap already,
814 nothing is done (and @code{nil} is returned). Otherwise @code{t} is
818 @defun image-instance-name image-instance
819 This function returns the name of the given image instance.
822 @defun image-instance-string image-instance
823 This function returns the string of the given image instance. This will
824 only be non-@code{nil} for text image instances.
827 @defun image-instance-file-name image-instance
828 This function returns the file name from which @var{image-instance} was
832 @defun image-instance-mask-file-name image-instance
833 This function returns the file name from which @var{image-instance}'s
834 mask was read, if known.
837 @defun image-instance-depth image-instance
838 This function returns the depth of the image instance. This is 0 for a
839 mono pixmap, or a positive integer for a color pixmap.
842 @defun image-instance-height image-instance
843 This function returns the height of the image instance, in pixels.
846 @defun image-instance-width image-instance
847 This function returns the width of the image instance, in pixels.
850 @defun image-instance-hotspot-x image-instance
851 This function returns the X coordinate of the image instance's hotspot,
852 if known. This is a point relative to the origin of the pixmap. When
853 an image is used as a mouse pointer, the hotspot is the point on the
854 image that sits over the location that the pointer points to. This is,
855 for example, the tip of the arrow or the center of the crosshairs.
857 This will always be @code{nil} for a non-pointer image instance.
860 @defun image-instance-hotspot-y image-instance
861 This function returns the Y coordinate of the image instance's hotspot,
865 @defun image-instance-foreground image-instance
866 This function returns the foreground color of @var{image-instance}, if
867 applicable. This will be a color instance or @code{nil}. (It will only
868 be non-@code{nil} for colorized mono pixmaps and for pointers.)
871 @defun image-instance-background image-instance
872 This function returns the background color of @var{image-instance}, if
873 applicable. This will be a color instance or @code{nil}. (It will only
874 be non-@code{nil} for colorized mono pixmaps and for pointers.)
881 Each glyph has a particular type, which controls how the glyph's image
882 is generated. Each glyph type has a corresponding list of allowable
883 image instance types that can be generated. When you call
884 @code{glyph-image-instance} to retrieve the image instance of a glyph,
885 XEmacs does the equivalent of calling @code{make-image-instance} and
886 passing in @var{dest-types} the list of allowable image instance types
887 for the glyph's type.
891 @code{buffer} glyphs can be used as the begin-glyph or end-glyph of an
892 extent, in the modeline, and in the toolbar. Their image can be
893 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
894 @code{text}, and @code{subwindow}.
897 @code{pointer} glyphs can be used to specify the mouse pointer. Their
898 image can be instantiated as @code{pointer}.
901 @code{icon} glyphs can be used to specify the icon used when a frame is
902 iconified. Their image can be instantiated as @code{mono-pixmap} and
906 @defun glyph-type glyph
907 This function returns the type of the given glyph. The return value
908 will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}.
911 @defun valid-glyph-type-p glyph-type
912 Given a @var{glyph-type}, this function returns non-@code{nil} if it is
916 @defun glyph-type-list
917 This function returns a list of valid glyph types.
920 @defun buffer-glyph-p object
921 This function returns non-@code{nil} if @var{object} is a glyph of type
925 @defun icon-glyph-p object
926 This function returns non-@code{nil} if @var{object} is a glyph of type
930 @defun pointer-glyph-p object
931 This function returns non-@code{nil} if @var{object} is a glyph of type
936 @section Mouse Pointer
938 @cindex cursor (mouse)
939 @cindex pointer (mouse)
940 @cindex mouse pointer
942 The shape of the mouse pointer when over a particular section of a frame
943 is controlled using various glyph variables. Since the image of a glyph
944 is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
947 You should use @code{set-glyph-image} to set the following variables,
948 @emph{not} @code{setq}.
950 @defvr Glyph text-pointer-glyph
951 This variable specifies the shape of the mouse pointer when over text.
954 @defvr Glyph nontext-pointer-glyph
955 This variable specifies the shape of the mouse pointer when over a
956 buffer, but not over text. If unspecified in a particular domain,
957 @code{text-pointer-glyph} is used.
960 @defvr Glyph modeline-pointer-glyph
961 This variable specifies the shape of the mouse pointer when over the modeline.
962 If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
965 @defvr Glyph selection-pointer-glyph
966 This variable specifies the shape of the mouse pointer when over a
967 selectable text region. If unspecified in a particular domain,
968 @code{text-pointer-glyph} is used.
971 @defvr Glyph gc-pointer-glyph
972 This variable specifies the shape of the mouse pointer when a garbage
973 collection is in progress. If the selected window is on a window system
974 and this glyph specifies a value (i.e. a pointer image instance) in the
975 domain of the selected window, the pointer will be changed as specified
976 during garbage collection. Otherwise, a message will be printed in the
977 echo area, as controlled by @code{gc-message}.
980 @defvr Glyph busy-pointer-glyph
981 This variable specifies the shape of the mouse pointer when XEmacs is busy.
982 If unspecified in a particular domain, the pointer is not changed
986 @defvr Glyph menubar-pointer-glyph
987 This variable specifies the shape of the mouse pointer when over the
988 menubar. If unspecified in a particular domain, the
989 window-system-provided default pointer is used.
992 @defvr Glyph scrollbar-pointer-glyph
993 This variable specifies the shape of the mouse pointer when over a
994 scrollbar. If unspecified in a particular domain, the
995 window-system-provided default pointer is used.
998 @defvr Glyph toolbar-pointer-glyph
999 This variable specifies the shape of the mouse pointer when over a
1000 toolbar. If unspecified in a particular domain,
1001 @code{nontext-pointer-glyph} is used.
1004 Internally, these variables are implemented in
1005 @code{default-mouse-motion-handler}, and thus only take effect when the
1006 mouse moves. That function calls @code{set-frame-pointer}, which sets
1007 the current mouse pointer for a frame.
1009 @defun set-frame-pointer frame image-instance
1010 This function sets the mouse pointer of @var{frame} to the given pointer
1011 image instance. You should not call this function directly.
1012 (If you do, the pointer will change again the next time the mouse moves.)
1015 @node Redisplay Glyphs
1016 @section Redisplay Glyphs
1018 @defvr Glyph truncation-glyph
1019 This variable specifies what is displayed at the end of truncated lines.
1022 @defvr Glyph continuation-glyph
1023 This variable specifies what is displayed at the end of wrapped lines.
1026 @defvr Glyph octal-escape-glyph
1027 This variable specifies what to prefix character codes displayed in octal
1031 @defvr Glyph hscroll-glyph
1032 This variable specifies what to display at the beginning of horizontally
1036 @defvr Glyph invisible-text-glyph
1037 This variable specifies what to use to indicate the presence of
1038 invisible text. This is the glyph that is displayed when an ellipsis is
1039 called for, according to @code{selective-display-ellipses} or
1040 @code{buffer-invisibility-spec}). Normally this is three dots (``...'').
1043 @defvr Glyph control-arrow-glyph
1044 This variable specifies what to use as an arrow for control characters.
1050 Subwindows are not currently implemented.
1052 @defun subwindowp object
1053 This function returns non-@code{nil} if @var{object} is a subwindow.