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, widgets and
11 images of all sorts, as well as for things that ``act'' like pixmaps,
12 such as non-textual strings (@dfn{annotations}) displayed in a buffer or
13 in the margins. It is used in begin-glyphs and end-glyphs attached to
14 extents, marginal and textual annotations, overlay arrows
15 (@code{overlay-arrow-*} variables), toolbar buttons, mouse pointers,
16 frame icons, truncation and continuation markers, and the
17 like. (Basically, any place there is an image or something that acts
18 like an image, there will be a glyph object representing it.)
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}.
75 A glyph in XEmacs does @strong{NOT} refer to a single unit of textual
76 display (the XEmacs term for this is @dfn{rune}), but rather is an
77 object encapsulating a graphical element, such as an image or widget (an
78 element such as a button or text field; @dfn{widget} is the term for
79 this under X Windows, and it's called a @dfn{control} under MS Windows).
80 This graphical element could appear in a buffer, a margin, a gutter, or
81 a toolbar, or as a mouse pointer or an icon, for example.
83 Creating a glyph using @code{make-glyph} does not specify @emph{where}
84 the glyph will be used, but it does specify @emph{what} the glyph will
85 look like. In particular, @var{spec-list} is used to specify this, and it's
86 used to initialize the glyph's @code{image} property, which is an image
87 specifier. (Note that @dfn{image} as used in the context of a glyph's
88 @code{image} property or in the terms @dfn{image specifier}, @dfn{image
89 instantiator}, or @dfn{image instance} does not refer to what people
90 normally think of as an image (which in XEmacs is called a
91 @dfn{pixmap}), but to any graphical element---a pixmap, a widget, or
92 even a block of text, when used in the places that call for a glyph.)
93 The format of the @var{spec-list} is typically an image instantiator (a string
94 or a vector; @ref{Image Specifiers}), but can also be a list of such
95 instantiators (each one in turn is tried until an image is successfully
96 produced), a cons of a locale (frame, buffer, etc.) and an
97 instantiator, a list of such conses, or any other form accepted by
98 @code{canonicalize-spec-list}. @xref{Specifiers}, for more information
101 If you're not familiar with specifiers, you should be in order to
102 understand how glyphs work. The clearest introduction to specifiers
103 is in the Lispref manual, available under Info. (Choose
104 Help->Info->Info Contents on the menubar or type C-h i.) You can
105 also see @code{make-specifier} for a capsule summary. What's important to
106 keep in mind is that a specifier lets you set a different value for
107 any particular buffer, window, frame, device, or console. This allows
108 for a great deal of flexibility; in particular, only one global glyph
109 needs to exist for a particular purpose (e.g. the icon used to represent
110 an iconified frame, the mouse pointer used over particular areas of a
111 frame, etc.), and in these cases you do not create your own glyph, but
112 rather modify the existing one.
114 As well as using @var{spec-list} to initialize the glyph, you can set
115 specifications using @code{set-glyph-image}. Note that, due to a
116 possibly questionable historical design decision, a glyph itself is not
117 actually a specifier, but rather is an object containing an image
118 specifier (as well as other, seldom-used properties). Therefore, you
119 cannot set or access specifications for the glyph's image by directly
120 using @code{set-specifier}, @code{specifier-instance} or the like on the
121 glyph; instead use them on @code{(glyph-image @var{glyph})} or use the
122 convenience functions @code{set-glyph-image},
123 @code{glyph-image-instance}, and @code{glyph-image}.
125 Once you have created a glyph, you specify where it will be used as
130 To insert a glyph into a buffer, create an extent in the buffer and then
131 use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
132 a glyph to be displayed at the corresponding edge of the extent. (It is
133 common to create zero-width extents for this purpose.)
136 To insert a glyph into the left or right margin of a buffer, first
137 make sure the margin is visible by setting a value for the specifiers
138 @code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
139 when using margin glyphs with layout policy @code{whitespace}.) Then follow
140 the same procedure above for inserting a glyph in a buffer, and then
141 set a non-default layout policy for the glyph using
142 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
143 Alternatively, use the high-level annotations API (see
144 @code{make-annotation}). (In point of fact, you can also use the annotations
145 API for glyphs in a buffer, by setting a layout policy of @code{text}.)
148 To insert a glyph into the modeline, just put the glyph directly as one
149 of the modeline elements. (Unfortunately you can't currently put a begin
150 glyph or end glyph on one of the modeline extents---they're ignored.)
153 To insert a glyph into a toolbar, specify it as part of a toolbar
154 instantiator (typically set on the specifier @code{default-toolbar}).
155 See @code{default-toolbar} for more information. (Note that it is
156 standard practice to use a symbol in place of the glyph list in the
157 toolbar instantiator; the symbol is evalled to get the glyph list. This
158 facilitates both creating the toolbar instantiator and modifying
159 individual glyphs in a toolbar later on. For example, you can change
160 the way that the Mail toolbar button looks by modifying the value of the
161 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
162 and then calling @code{(set-specifier-dirty-flag default-toolbar)}.
163 (#### Unfortunately this doesn't quite work the way it should; the
164 change will appear in new frames, but not existing ones.
167 To insert a glyph into a gutter, create or modify a gutter instantiator
168 (typically set on the specifier @code{default-gutter}). Gutter
169 instantiators consist of strings or lists of strings, so to insert a
170 glyph, create an extent over the string, and use
171 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
172 glyph to be displayed at the corresponding edge of the extent, just like
173 for glyphs in a buffer.
176 To use a glyph as the icon for a frame, you do not actually create a new
177 glyph; rather, you change the specifications for the existing glyph
178 @code{frame-icon-glyph}. (Remember that, because of the specifier nature
179 of glyphs, you can set different values for any particular buffer or
183 To use a glyph as the mouse pointer, in general you do not create a new
184 glyph, but rather you change the specifications of various existing
185 glyphs, such as @code{text-pointer-glyph} for the pointer used over
186 text, @code{modeline-pointer-glyph} for the pointer used over the
187 modeline, etc. Do an apropos over @code{*-pointer-glyph} to find all of
188 them. (Note also that you can temporarily set the mouse pointer to some
189 specific shape by using @code{set-frame-pointer}, which takes an image
190 instance, as obtained from calling @code{glyph-image-instance} on a glyph
191 of type @code{pointer} -- either one of the above-mentioned variables or
192 one you created yourself. (See below for what it means to create a
193 glyph of type @code{pointer}.) This pointer will last only until the
194 next mouse motion event is processed or certain other things happen,
195 such as creating or deleting a window. (In fact, the above-mentioned
196 pointer glyph variables are implemented as part of the default handler
197 for mouse motion events. If you want to customize this behavior, take a
198 look at @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
199 really want to get low-level.)
202 To use a glyph to control the shape of miscellaneous redisplay effects
203 such as the truncation and continuation markers, set the appropriate
204 existing glyph variables, as for icons and pointers above. See
205 @code{continuation-glyph}, @code{control-arrow-glyph},
206 @code{hscroll-glyph}, @code{invisible-text-glyph},
207 @code{octal-escape-glyph}, and @code{truncation-glyph}. See also
208 @code{overlay-arrow-string}, an odd redisplay leftover which can be set
209 to a glyph you created, and will cause the glyph to be displayed on top
210 of the text position specified in the marker stored in
211 @code{overlay-arrow-position}.
214 To use a glyph in a display table (i.e. to control the appearance of any
215 individual character), create the appropriate character glyphs and then
216 set a specification for the specifier @code{current-display-table},
217 which controls the appearance of characters. You can also set an
218 overriding display table for use with text displayed in a particular
219 face; see @code{set-face-display-table} and @code{make-display-table}.
220 #### Note: Display tables do not currently support general Mule
221 characters. They will be overhauled at some point to support this
222 and to provide other features required under Mule.
225 To use a glyph as the background pixmap of a face: Note that the
226 background pixmap of a face is actually an image specifier -- probably
227 the only place in XEmacs where an image specifier occurs outside of a
228 glyph. Similarly to how the glyph's image specifier works, you don't
229 create your own image specifier, but rather add specifications to the
230 existing one (using @code{set-face-background-pixmap}). Note that the
231 image instance that is generated in order to actually display the
232 background pixmap is of type @code{mono-pixmap}, meaning that it's a
233 two-color image and the foreground and background of the image get
234 filled in with the corresponding colors from the face.
237 It is extremely rare that you will ever have to specify a value for
238 @var{type}, which should be one of @code{buffer} (used for glyphs in an
239 extent, the modeline, the toolbar, or elsewhere in a buffer),
240 @code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
241 frame's icon), and defaults to @code{buffer}. The only cases where it
242 needs to be specified is when creating icon or pointer glyphs, and in
243 both cases the necessary glyphs have already been created at startup and
244 are accessed through the appropriate variables,
245 e.g. @code{text-pointer-glyph} (or in general, @code{*-pointer-glyph})
246 and @code{frame-icon-glyph}. @xref{Glyph Types}.
249 @defun make-glyph-internal &optional type
250 This function creates a new, uninitialized glyph of type @var{type}.
253 @defun make-pointer-glyph &optional spec-list
255 Return a new @code{pointer-glyph} object with the specification list
256 @var{spec-list}. This function is equivalent to calling
257 @code{make-glyph} with a @var{type} of @code{pointer}.
259 It is extremely unlikely that you will ever need to create a pointer
260 glyph. Instead, you probably want to be calling @code{set-glyph-image}
261 on an existing glyph, e.g. @code{text-pointer-glyph}.
264 @defun make-icon-glyph &optional spec-list
266 Return a new @code{pointer-glyph} object with the specification list
267 @var{spec-list}. This function is equivalent to calling
268 @code{make-glyph} with a @var{type} of @code{icon}.
270 It is extremely unlikely that you will ever need to create a pointer
271 glyph. Instead, you probably want to be calling @code{set-glyph-image}
272 on an existing glyph, e.g. @code{text-pointer-glyph}.
275 @node Glyph Properties
276 @subsection Glyph Properties
278 Each glyph has a list of properties, which control all of the aspects of
279 the glyph's appearance. The following symbols have predefined meanings:
283 The image used to display the glyph.
286 Percent above baseline that glyph is to be displayed. Only for glyphs
287 displayed inside of a buffer.
290 Whether the glyph contributes to the height of the line it's on.
291 Only for glyphs displayed inside of a buffer.
294 Face of this glyph (@emph{not} a specifier).
297 @defun set-glyph-property glyph property value &optional locale tag-set how-to-add
298 This function changes a property of a @var{glyph}.
300 For built-in properties, the actual value of the property is a specifier
301 and you cannot change this; but you can change the specifications within
302 the specifier, and that is what this function will do. For user-defined
303 properties, you can use this function to either change the actual value
304 of the property or, if this value is a specifier, change the
305 specifications within it.
307 If @var{property} is a built-in property, the specifications to be added
308 to this property can be supplied in many different ways:
312 If @var{value} is a simple instantiator (e.g. a string naming a pixmap
313 filename) or a list of instantiators, then the instantiator(s) will be
314 added as a specification of the property for the given @var{locale}
315 (which defaults to @code{global} if omitted).
318 If @var{value} is a list of specifications (each of which is a cons of a
319 locale and a list of instantiators), then @var{locale} must be
320 @code{nil} (it does not make sense to explicitly specify a locale in
321 this case), and specifications will be added as given.
324 If @var{value} is a specifier (as would be returned by
325 @code{glyph-property} if no @var{locale} argument is given), then some
326 or all of the specifications in the specifier will be added to the
327 property. In this case, the function is really equivalent to
328 @code{copy-specifier} and @var{locale} has the same semantics (if it is
329 a particular locale, the specification for the locale will be copied; if
330 a locale type, specifications for all locales of that type will be
331 copied; if @code{nil} or @code{all}, then all specifications will be
335 @var{how-to-add} should be either @code{nil} or one of the symbols
336 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
337 @code{remove-tag-set-append}, @code{remove-locale},
338 @code{remove-locale-type}, or @code{remove-all}. See
339 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
340 of what each of these means. Most of the time, you do not need to worry
341 about this argument; the default behavior usually is fine.
343 In general, it is OK to pass an instance object (e.g. as returned by
344 @code{glyph-property-instance}) as an instantiator in place of an actual
345 instantiator. In such a case, the instantiator used to create that
346 instance object will be used (for example, if you set a font-instance
347 object as the value of the @code{font} property, then the font name used
348 to create that object will be used instead). If some cases, however,
349 doing this conversion does not make sense, and this will be noted in the
350 documentation for particular types of instance objects.
352 If @var{property} is not a built-in property, then this function will
353 simply set its value if @var{locale} is @code{nil}. However, if
354 @var{locale} is given, then this function will attempt to add
355 @var{value} as the instantiator for the given @var{locale}, using
356 @code{add-spec-to-specifier}. If the value of the property is not a
357 specifier, it will automatically be converted into a @code{generic}
361 @defun glyph-property glyph property &optional locale
362 This function returns @var{glyph}'s value of the given @var{property}.
364 If @var{locale} is omitted, the @var{glyph}'s actual value for
365 @var{property} will be returned. For built-in properties, this will be
366 a specifier object of a type appropriate to the property (e.g. a font or
367 color specifier). For other properties, this could be anything.
369 If @var{locale} is supplied, then instead of returning the actual value,
370 the specification(s) for the given locale or locale type will be
371 returned. This will only work if the actual value of @var{property} is
372 a specifier (this will always be the case for built-in properties, but
373 may or may not apply to user-defined properties). If the actual value
374 of @var{property} is not a specifier, this value will simply be returned
375 regardless of @var{locale}.
377 The return value will be a list of instantiators (e.g. vectors
378 specifying pixmap data), or a list of specifications, each of which is a
379 cons of a locale and a list of instantiators. Specifically, if
380 @var{locale} is a particular locale (a buffer, window, frame, device, or
381 @code{global}), a list of instantiators for that locale will be
382 returned. Otherwise, if @var{locale} is a locale type (one of the
383 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
384 the specifications for all locales of that type will be returned.
385 Finally, if @var{locale} is @code{all}, the specifications for all
386 locales of all types will be returned.
388 The specifications in a specifier determine what the value of
389 @var{property} will be in a particular @dfn{domain} or set of
390 circumstances, which is typically a particular Emacs window along with
391 the buffer it contains and the frame and device it lies within. The
392 value is derived from the instantiator associated with the most specific
393 locale (in the order buffer, window, frame, device, and @code{global})
394 that matches the domain in question. In other words, given a domain
395 (i.e. an Emacs window, usually), the specifier for @var{property} will
396 first be searched for a specification whose locale is the buffer
397 contained within that window; then for a specification whose locale is
398 the window itself; then for a specification whose locale is the frame
399 that the window is contained within; etc. The first instantiator that
400 is valid for the domain (usually this means that the instantiator is
401 recognized by the device [i.e. the X server or TTY device] that the
402 domain is on). The function @code{glyph-property-instance} actually does
403 all this, and is used to determine how to display the glyph.
406 @defun glyph-property-instance glyph property &optional domain default no-fallback
407 This function returns the instance of @var{glyph}'s @var{property} in the
408 specified @var{domain}.
410 Under most circumstances, @var{domain} will be a particular window, and
411 the returned instance describes how the specified property actually is
412 displayed for that window and the particular buffer in it. Note that
413 this may not be the same as how the property appears when the buffer is
414 displayed in a different window or frame, or how the property appears in
415 the same window if you switch to another buffer in that window; and in
416 those cases, the returned instance would be different.
418 The returned instance is an image-instance object, and you can query it
419 using the appropriate image instance functions. For example, you could use
420 @code{image-instance-depth} to find out the depth (number of color
421 planes) of a pixmap displayed in a particular window. The results might
422 be different from the results you would get for another window (perhaps
423 the user specified a different image for the frame that window is on; or
424 perhaps the same image was specified but the window is on a different X
425 server, and that X server has different color capabilities from this
428 @var{domain} defaults to the selected window if omitted.
430 @var{domain} can be a frame or device, instead of a window. The value
431 returned for such a domain is used in special circumstances when a
432 more specific domain does not apply; for example, a frame value might be
433 used for coloring a toolbar, which is conceptually attached to a frame
434 rather than a particular window. The value is also useful in
435 determining what the value would be for a particular window within the
436 frame or device, if it is not overridden by a more specific
439 If @var{property} does not name a built-in property, its value will
440 simply be returned unless it is a specifier object, in which case it
441 will be instanced using @code{specifier-instance}.
443 Optional arguments @var{default} and @var{no-fallback} are the same as
444 in @code{specifier-instance}. @xref{Specifiers}.
447 @defun remove-glyph-property glyph property &optional locale tag-set exact-p
448 This function removes a property from a glyph. For built-in properties,
449 this is analogous to @code{remove-specifier}. @xref{Specifiers,
450 remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
451 and @var{exact-p} arguments.
454 @node Glyph Convenience Functions
455 @subsection Glyph Convenience Functions
457 The following functions are provided for working with specific
458 properties of a glyph. Note that these are exactly like calling
459 the general functions described above and passing in the
460 appropriate value for @var{property}.
462 Remember that if you want to determine the ``value'' of a
463 specific glyph property, you probably want to use the @code{*-instance}
464 functions. For example, to determine whether a glyph contributes
465 to its line height, use @code{glyph-contrib-p-instance}, not
466 @code{glyph-contrib-p}. (The latter will return a boolean specifier
467 or a list of specifications, and you probably aren't concerned with
470 @defun glyph-image glyph &optional locale
471 This function is equivalent to calling @code{glyph-property} with
472 a property of @code{image}. The return value will be an image
473 specifier if @var{locale} is @code{nil} or omitted; otherwise,
474 it will be a specification or list of specifications.
477 @defun set-glyph-image glyph spec &optional locale tag-set how-to-add
478 This function is equivalent to calling @code{set-glyph-property} with
479 a property of @code{image}.
482 @defun glyph-image-instance glyph &optional domain default no-fallback
483 This function returns the instance of @var{glyph}'s image in the given
484 @var{domain}, and is equivalent to calling
485 @code{glyph-property-instance} with a property of @code{image}. The
486 return value will be an image instance.
488 Normally @var{domain} will be a window or @code{nil} (meaning the
489 selected window), and an instance object describing how the image
490 appears in that particular window and buffer will be returned.
493 @defun glyph-contrib-p glyph &optional locale
494 This function is equivalent to calling @code{glyph-property} with
495 a property of @code{contrib-p}. The return value will be a boolean
496 specifier if @var{locale} is @code{nil} or omitted; otherwise,
497 it will be a specification or list of specifications.
500 @defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
501 This function is equivalent to calling @code{set-glyph-property} with
502 a property of @code{contrib-p}.
505 @defun glyph-contrib-p-instance glyph &optional domain default no-fallback
506 This function returns whether the glyph contributes to its line height
507 in the given @var{domain}, and is equivalent to calling
508 @code{glyph-property-instance} with a property of @code{contrib-p}. The
509 return value will be either @code{nil} or @code{t}. (Normally @var{domain}
510 will be a window or @code{nil}, meaning the selected window.)
513 @defun glyph-baseline glyph &optional locale
514 This function is equivalent to calling @code{glyph-property} with a
515 property of @code{baseline}. The return value will be a specifier if
516 @var{locale} is @code{nil} or omitted; otherwise, it will be a
517 specification or list of specifications.
520 @defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
521 This function is equivalent to calling @code{set-glyph-property} with
522 a property of @code{baseline}.
525 @defun glyph-baseline-instance glyph &optional domain default no-fallback
526 This function returns the instance of @var{glyph}'s baseline value in
527 the given @var{domain}, and is equivalent to calling
528 @code{glyph-property-instance} with a property of @code{baseline}. The
529 return value will be an integer or @code{nil}.
531 Normally @var{domain} will be a window or @code{nil} (meaning the
532 selected window), and an instance object describing the baseline value
533 appears in that particular window and buffer will be returned.
536 @defun glyph-face glyph
537 This function returns the face of @var{glyph}. (Remember, this is
538 not a specifier, but a simple property.)
541 @defun set-glyph-face glyph face
542 This function changes the face of @var{glyph} to @var{face}.
545 @node Glyph Dimensions
546 @subsection Glyph Dimensions
548 @defun glyph-width glyph &optional window
549 This function returns the width of @var{glyph} on @var{window}. This
550 may not be exact as it does not take into account all of the context
554 @defun glyph-ascent glyph &optional window
555 This function returns the ascent value of @var{glyph} on @var{window}.
556 This may not be exact as it does not take into account all of the
557 context that redisplay will.
560 @defun glyph-descent glyph &optional window
561 This function returns the descent value of @var{glyph} on @var{window}.
562 This may not be exact as it does not take into account all of the
563 context that redisplay will.
566 @defun glyph-height glyph &optional window
567 This function returns the height of @var{glyph} on @var{window}. (This
568 is equivalent to the sum of the ascent and descent values.) This may
569 not be exact as it does not take into account all of the context that
577 * Image Specifiers:: Specifying how an image will appear.
578 * Image Instantiator Conversion::
579 Conversion is applied to image instantiators
580 at the time they are added to an
581 image specifier or at the time they
582 are passed to @code{make-image-instance}.
583 * Image Instances:: What an image specifier gets instanced as.
586 @node Image Specifiers
587 @subsection Image Specifiers
588 @cindex image specifiers
590 An image specifier is used to describe the actual image of a glyph.
591 It works like other specifiers (@pxref{Specifiers}), in that it contains
592 a number of specifications describing how the image should appear in a
593 variety of circumstances. These specifications are called @dfn{image
594 instantiators}. When XEmacs wants to display the image, it instantiates
595 the image into an @dfn{image instance}. Image instances are their own
596 primitive object type (similar to font instances and color instances),
597 describing how the image appears in a particular domain. (On the other
598 hand, image instantiators, which are just descriptions of how the image
599 should appear, are represented using strings or vectors.)
601 @defun image-specifier-p object
602 This function returns non-@code{nil} if @var{object} is an image specifier.
603 Usually, an image specifier results from calling @code{glyph-image} on
607 @defun make-image-specifier spec-list
608 This function creates a new image specifier object and initializes it
609 according to @var{spec-list}. @xref{Specifiers}.
611 Note that, in practice, you rarely, if ever, need to actually create an
612 image specifier! (This function exists mainly for completeness.) Pretty
613 much the only use for image specifiers is to control how glyphs are
614 displayed, and the image specifier associated with a glyph (the
615 @code{image} property of a glyph) is created automatically when a glyph
616 is created and need not (and cannot, for that matter) ever be changed
617 (@pxref{Glyphs}). In fact, the design decision to create a separate
618 image specifier type, rather than make glyphs themselves be specifiers,
619 is debatable---the other properties of glyphs are rarely used and could
620 conceivably have been incorporated into the glyph's instantiator. The
621 rarely used glyph types (buffer, pointer, icon) could also have been
622 incorporated into the instantiator.
625 Image instantiators come in many formats: @code{xbm}, @code{xpm},
626 @code{gif}, @code{jpeg}, etc. This describes the format of the data
627 describing the image. The resulting image instances also come in many
628 types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
629 @code{pointer}, etc. This refers to the behavior of the image and the
630 sorts of places it can appear. (For example, a color-pixmap image has
631 fixed colors specified for it, while a mono-pixmap image comes in two
632 unspecified shades ``foreground'' and ``background'' that are determined
633 from the face of the glyph or surrounding text; a text image appears as
634 a string of text and has an unspecified foreground, background, and
635 font; a pointer image behaves like a mono-pixmap image but can only be
636 used as a mouse pointer [mono-pixmap images cannot be used as mouse
637 pointers]; etc.) It is important to keep the distinction between image
638 instantiator format and image instance type in mind. Typically, a given
639 image instantiator format can result in many different image instance
640 types (for example, @code{xpm} can be instanced as @code{color-pixmap},
641 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
642 instanced only as @code{pointer}), and a particular image instance type
643 can be generated by many different image instantiator formats (e.g.
644 @code{color-pixmap} can be generated by @code{xpm}, @code{gif},
647 @xref{Image Instances}, for a more detailed discussion of image
650 An image instantiator should be a string or a vector of the form
653 @code{[@var{format} @var{:keyword} @var{value} ...]}
656 i.e. a format symbol followed by zero or more alternating keyword-value
657 pairs. The @dfn{format} field should be a symbol, one of
661 Don't display anything; no keywords are valid for this. Can only be
662 instanced as @code{nothing}.
664 Display this image as a text string. Can only be instanced
665 as @code{text}, although support for instancing as @code{mono-pixmap}
667 @item formatted-string
668 Display this image as a text string with replaceable fields,
669 similar to a modeline format string; not currently implemented.
671 An X bitmap; only if X support was compiled into this XEmacs. Can be
672 instanced as @code{mono-pixmap}, @code{color-pixmap}, or
675 An XPM pixmap; only if XPM support was compiled into this XEmacs. Can
676 be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
677 @code{pointer}. XPM is an add-on library for X that was designed to
678 rectify the shortcomings of the XBM format. Most implementations of X
679 include the XPM library as a standard part. If your vendor does not, it
680 is highly recommended that you download it and install it. You can get
681 it from the standard XEmacs FTP site, among other places.
683 An X-Face bitmap, used to encode people's faces in e-mail messages;
684 only if X-Face support was compiled into this XEmacs. Can be instanced
685 as @code{mono-pixmap}, @code{color-pixmap}, or @code{pointer}.
687 A GIF87 or GIF89 image; only if GIF support was compiled into this
688 XEmacs. Can be instanced as @code{color-pixmap}. Note that XEmacs
689 includes GIF decoding functions as a standard part of it, so if you have
690 X support, you will normally have GIF support, unless you explicitly
691 disable it at configure time.
693 A JPEG-format image; only if JPEG support was compiled into this
694 XEmacs. Can be instanced as @code{color-pixmap}. If you have the JPEG
695 libraries present on your system when XEmacs is built, XEmacs will
696 automatically detect this and use them, unless you explicitly disable it
699 A PNG/GIF24 image; only if PNG support was compiled into this XEmacs.
700 Can be instanced as @code{color-pixmap}.
702 A TIFF-format image; only if TIFF support was compiled into this XEmacs.
704 One of the standard cursor-font names, such as @samp{watch} or
705 @samp{right_ptr} under X. Under X, this is, more specifically, any of
706 the standard cursor names from appendix B of the Xlib manual [also known
707 as the file @file{<X11/cursorfont.h>}] minus the @samp{XC_} prefix. On
708 other window systems, the valid names will be specific to the type of
709 window system. Can only be instanced as @code{pointer}.
711 A glyph from a font; i.e. the name of a font, and glyph index into it
712 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
713 Only if X support was compiled into this XEmacs. Currently can only be
714 instanced as @code{pointer}, although this should probably be fixed.
715 @item mswindows-resource
716 An MS Windows pointer resource. Specifies a resource to retrieve
717 directly from the system (an OEM resource) or from a file, particularly
718 an executable file. If the resource is to be retrieved from a file, use
719 :file and optionally :resource-id. Otherwise use :resource-id. Always
720 specify :resource-type to specify the type (cursor, bitmap or icon) of
721 the resource. Possible values for :resource-id are listed below. Can
722 be instanced as @code{pointer} or @code{color-pixmap}.
724 An embedded windowing system window. Can only be instanced as
727 A button widget; either a push button, radio button or toggle button.
728 Can only be instanced as @code{widget}.
730 A drop list of selectable items in a widget, for editing text.
731 Can only be instanced as @code{widget}.
733 A text editing widget. Can only be instanced as @code{widget}.
735 A static, text-only, widget; for displaying text. Can only be instanced
738 A widget for controlling the positioning of children underneath it.
739 Through the use of nested layouts, a widget hierarchy can be created
740 which can have the appearance of any standard dialog box or similar
741 arrangement; all of this is counted as one @dfn{glyph} and could appear
742 in many of the places that expect a single glyph. Can only be instanced
745 @c #### Document me better!
746 The native version of a layout widget.
747 Can only be instanced as @code{widget}.
749 A sliding widget, for showing progress. Can only be instanced as
752 A tab widget; a series of user selectable tabs. Can only be instanced
755 A folding widget. Can only be instanced as @code{widget}.
757 A scrollbar widget. Can only be instanced as @code{widget}.
759 XEmacs tries to guess what format the data is in. If X support exists,
760 the data string will be checked to see if it names a filename. If so,
761 and this filename contains XBM or XPM data, the appropriate sort of
762 pixmap or pointer will be created. [This includes picking up any
763 specified hotspot or associated mask file.] Otherwise, if @code{pointer}
764 is one of the allowable image-instance types and the string names a
765 valid cursor-font name, the image will be created as a pointer.
766 Otherwise, the image will be displayed as text. If no X support exists,
767 the image will always be displayed as text.
769 Inherit from the background-pixmap property of a face. Can only be
770 instanced as @code{mono-pixmap}.
773 The valid keywords are:
777 Inline data. For most formats above, this should be a string. For
778 XBM images, this should be a list of three elements: width, height, and
779 a string of bit data. This keyword is not valid for instantiator
780 format @code{nothing}.
783 Data is contained in a file. The value is the name of this file. If
784 both @code{:data} and @code{:file} are specified, the image is created
785 from what is specified in @code{:data} and the string in @code{:file}
786 becomes the value of the @code{image-instance-file-name} function when
787 applied to the resulting image-instance. This keyword is not valid for
788 instantiator formats @code{nothing}, @code{string},
789 @code{formatted-string}, @code{cursor-font}, @code{font}, and
794 For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
795 These keywords allow you to explicitly specify foreground and background
796 colors. The argument should be anything acceptable to
797 @code{make-color-instance}. This will cause what would be a
798 @code{mono-pixmap} to instead be colorized as a two-color color-pixmap,
799 and specifies the foreground and/or background colors for a pointer
800 instead of black and white.
803 For @code{xbm} and @code{xface}. This specifies a mask to be used with the
804 bitmap. The format is a list of width, height, and bits, like for
808 For @code{xbm} and @code{xface}. This specifies a file containing the
809 mask data. If neither a mask file nor inline mask data is given for an
810 XBM image, and the XBM image comes from a file, XEmacs will look for a
811 mask file with the same name as the image file but with @samp{Mask} or
812 @samp{msk} appended. For example, if you specify the XBM file
813 @file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
814 the associated mask file @file{left_ptrmsk} will automatically be picked
819 For @code{xbm} and @code{xface}. These keywords specify a hotspot if
820 the image is instantiated as a @code{pointer}. Note that if the XBM
821 image file specifies a hotspot, it will automatically be picked up if no
822 explicit hotspot is given.
825 Only for @code{xpm}. This specifies an alist that maps strings that
826 specify symbolic color names to the actual color to be used for that
827 symbolic color (in the form of a string or a color-specifier object).
828 If this is not specified, the contents of @code{xpm-color-symbols} are
829 used to generate the alist.
831 Only for @code{mswindows-resource}. This must be either an integer
832 (which directly specifies a resource number) or a string. Valid strings
837 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
838 "reduce", "zoom", "restore", "reduced", "zoomd",
839 "restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd",
840 "mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi",
841 "lfarrowi", "size", "btsize", "check", "checkboxes", and
846 "normal", "ibeam", "wait", "cross", "up", "sizenwse",
847 "sizenesw", "sizewe", "sizens", "sizeall", and "no".
851 "sample", "hand", "ques", "bang", "note", and "winlogo".
853 Only for @code{mswindows-resource}. This must be a symbol, either
854 @code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
855 resource to be retrieved.
857 Only for @code{inherit}. This specifies the face to inherit from. For
858 widgets this also specifies the face to use for display. It defaults to
862 Keywords accepted as menu item specs are also accepted by widgets.
863 These are @code{:selected}, @code{:active}, @code{:suffix},
864 @code{:keys}, @code{:style}, @code{:filter}, @code{:config},
865 @code{:included}, @code{:key-sequence}, @code{:accelerator},
866 @code{:label} and @code{:callback}.
868 If instead of a vector, the instantiator is a string, it will be
869 converted into a vector by looking it up according to the specs in the
870 @code{console-type-image-conversion-list} for the console type of
871 the domain (usually a window; sometimes a frame or device) over which
872 the image is being instantiated.
874 If the instantiator specifies data from a file, the data will be read in
875 at the time that the instantiator is added to the image specifier (which
876 may be well before the image is actually displayed), and the
877 instantiator will be converted into one of the inline-data forms, with
878 the filename retained using a @code{:file} keyword. This implies that
879 the file must exist when the instantiator is added to the image, but
880 does not need to exist at any other time (e.g. it may safely be a
883 @defun valid-image-instantiator-format-p format &optional locale
884 This function returns non-@code{nil} if @var{format} is a valid image
887 If @var{locale} is non-@code{nil} then the format is checked in that locale.
888 If @var{locale} is @code{nil} the current console is used.
890 Note that the return value for many formats listed above depends on
891 whether XEmacs was compiled with support for that format.
894 @defun image-instantiator-format-list
895 This function return a list of valid image-instantiator formats.
898 @defvar xpm-color-symbols
899 This variable holds definitions of logical color-names used when reading
900 XPM files. Elements of this list should be of the form
901 @code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name}
902 should be a string, which is the name of the color to define; the
903 @var{form-to-evaluate} should evaluate to a color specifier object, or a
904 string to be passed to @code{make-color-instance} (@pxref{Colors}). If
905 a loaded XPM file references a symbolic color called @var{color-name},
906 it will display as the computed color instead.
908 The default value of this variable defines the logical color names
909 @samp{"foreground"} and @samp{"background"} to be the colors of the
913 @defvar x-bitmap-file-path
914 A list of the directories in which X bitmap files may be found. If @code{nil},
915 this is initialized from the @samp{"*bitmapFilePath"} resource. This is
916 used by the @code{make-image-instance} function (however, note that if
917 the environment variable @samp{XBMLANGPATH} is set, it is consulted
921 @node Image Instantiator Conversion
922 @subsection Image Instantiator Conversion
923 @cindex image instantiator conversion
924 @cindex conversion of image instantiators
926 @defun set-console-type-image-conversion-list console-type list
927 This function sets the image-conversion-list for consoles of the given
928 @var{console-type}. The image-conversion-list specifies how image
929 instantiators that are strings should be interpreted. Each element of
930 the list should be a list of two elements (a regular expression string
931 and a vector) or a list of three elements (the preceding two plus an
932 integer index into the vector). The string is converted to the vector
933 associated with the first matching regular expression. If a vector
934 index is specified, the string itself is substituted into that position
937 Note: The conversion above is applied when the image instantiator is
938 added to an image specifier, not when the specifier is actually
939 instantiated. Therefore, changing the image-conversion-list only affects
940 newly-added instantiators. Existing instantiators in glyphs and image
941 specifiers will not be affected.
944 @defun console-type-image-conversion-list console-type
945 This function returns the image-conversion-list for consoles of the given
949 @node Image Instances
950 @subsection Image Instances
951 @cindex image instances
953 Image-instance objects encapsulate the way a particular image (pixmap,
954 etc.) is displayed on a particular device.
956 In most circumstances, you do not need to directly create image
957 instances; use a glyph instead. However, it may occasionally be useful
958 to explicitly create image instances, if you want more control over the
959 instantiation process.
961 @defun image-instance-p object
962 This function returns non-@code{nil} if @var{object} is an image instance.
966 * Image Instance Types:: Each image instances has a particular type.
967 * Image Instance Functions:: Functions for working with image instances.
970 @node Image Instance Types
971 @subsubsection Image Instance Types
972 @cindex image instance types
974 Image instances come in a number of different types. The type
975 of an image instance specifies the nature of the image: Whether
976 it is a text string, a mono pixmap, a color pixmap, etc.
978 The valid image instance types are
982 Nothing is displayed.
985 Displayed as text. The foreground and background colors and the
986 font of the text are specified independent of the pixmap. Typically
987 these attributes will come from the face of the surrounding text,
988 unless a face is specified for the glyph in which the image appears.
991 Displayed as a mono pixmap (a pixmap with only two colors where the
992 foreground and background can be specified independent of the pixmap;
993 typically the pixmap assumes the foreground and background colors of
994 the text around it, unless a face is specified for the glyph in which
998 Displayed as a color pixmap.
1001 Used as the mouse pointer for a window.
1004 A child window that is treated as an image. This allows (e.g.)
1005 another program to be responsible for drawing into the window.
1006 Not currently implemented.
1009 @defun valid-image-instance-type-p type
1010 This function returns non-@code{nil} if @var{type} is a valid image
1014 @defun image-instance-type-list
1015 This function returns a list of the valid image instance types.
1018 @defun image-instance-type image-instance
1019 This function returns the type of the given image instance. The return
1020 value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
1021 @code{color-pixmap}, @code{pointer}, or @code{subwindow}.
1024 @defun text-image-instance-p object
1025 This function returns non-@code{nil} if @var{object} is an image
1026 instance of type @code{text}.
1029 @defun mono-pixmap-image-instance-p object
1030 This function returns non-@code{nil} if @var{object} is an image
1031 instance of type @code{mono-pixmap}.
1034 @defun color-pixmap-image-instance-p object
1035 This function returns non-@code{nil} if @var{object} is an image
1036 instance of type @code{color-pixmap}.
1039 @defun pointer-image-instance-p object
1040 This function returns non-@code{nil} if @var{object} is an image
1041 instance of type @code{pointer}.
1044 @defun subwindow-image-instance-p object
1045 This function returns non-@code{nil} if @var{object} is an image
1046 instance of type @code{subwindow}.
1049 @defun nothing-image-instance-p object
1050 This function returns non-@code{nil} if @var{object} is an image
1051 instance of type @code{nothing}.
1054 @defun widget-image-instance-p object
1055 Return @code{t} if @var{object} is an image instance of type @code{widget}.
1058 @node Image Instance Functions
1059 @subsubsection Image Instance Functions
1061 @defun make-image-instance data &optional domain dest-types noerror
1062 This function creates a new image-instance object.
1064 @var{data} is an image instantiator, which describes the image
1065 (@pxref{Image Specifiers}).
1067 @var{dest-types} should be a list of allowed image instance types that
1068 can be generated. The @var{dest-types} list is unordered. If multiple
1069 destination types are possible for a given instantiator, the ``most
1070 natural'' type for the instantiator's format is chosen. (For XBM, the
1071 most natural types are @code{mono-pixmap}, followed by
1072 @code{color-pixmap}, followed by @code{pointer}. For the other normal
1073 image formats, the most natural types are @code{color-pixmap}, followed
1074 by @code{mono-pixmap}, followed by @code{pointer}. For the string and
1075 formatted-string formats, the most natural types are @code{text},
1076 followed by @code{mono-pixmap} (not currently implemented), followed by
1077 @code{color-pixmap} (not currently implemented). For MS Windows
1078 resources, the most natural type for pointer resources is
1079 @code{pointer}, and for the others it's @code{color-pixmap}. The other
1080 formats can only be instantiated as one type. (If you want to control
1081 more specifically the order of the types into which an image is
1082 instantiated, just call @code{make-image-instance} repeatedly until it
1083 succeeds, passing less and less preferred destination types each time.
1085 If @var{dest-types} is omitted, all possible types are allowed.
1087 @var{domain} specifies the domain to which the image instance will be
1088 attached. This domain is termed the @dfn{governing domain}. The type
1089 of the governing domain depends on the image instantiator
1090 format. (Although, more correctly, it should probably depend on the
1091 image instance type.) For example, pixmap image instances are specific
1092 to a device, but widget image instances are specific to a particular
1093 XEmacs window because in order to display such a widget when two windows
1094 onto the same buffer want to display the widget, two separate underlying
1095 widgets must be created. (That's because a widget is actually a child
1096 window-system window, and all window-system windows have a unique
1097 existence on the screen.) This means that the governing domain for a
1098 pixmap image instance will be some device (most likely, the only
1099 existing device), whereas the governing domain for a widget image
1100 instance will be some XEmacs window.
1102 If you specify an overly general @var{domain} (e.g. a frame when a
1103 window was wanted), an error is signaled. If you specify an overly
1104 specific @var{domain} (e.g. a window when a device was wanted), the
1105 corresponding general domain is fetched and used instead. For
1106 @code{make-image-instance}, it makes no difference whether you specify
1107 an overly specific domain or the properly general domain derived from
1108 it. However, it does matter when creating an image instance by
1109 instantiating a specifier or glyph (e.g. with
1110 @code{glyph-image-instance}), because the more specific domain causes
1111 spec lookup to start there and proceed to more general domains. (It
1112 would also matter when creating an image instance with an instantiator
1113 format of @code{inherit}, but we currently disallow this. #### We should
1116 If omitted, @var{domain} defaults to the selected window.
1118 @var{noerror} controls what happens when the image cannot be generated.
1119 If @code{nil}, an error message is generated. If @code{t}, no messages
1120 are generated and this function returns @code{nil}. If anything else, a
1121 warning message is generated and this function returns @code{nil}.
1124 @defun colorize-image-instance image-instance foreground background
1125 This function makes the image instance be displayed in the given
1126 colors. Image instances come in two varieties: bitmaps, which are 1
1127 bit deep which are rendered in the prevailing foreground and background
1128 colors; and pixmaps, which are of arbitrary depth (including 1) and
1129 which have the colors explicitly specified. This function converts a
1130 bitmap to a pixmap. If the image instance was a pixmap already,
1131 nothing is done (and @code{nil} is returned). Otherwise @code{t} is
1135 @defun image-instance-name image-instance
1136 This function returns the name of the given image instance.
1139 @defun image-instance-domain image-instance
1141 Return the governing domain of the given @var{image-instance}. The
1142 governing domain of an image instance is the domain that the image
1143 instance is specific to. It is @emph{NOT} necessarily the domain that
1144 was given to the call to @code{specifier-instance} that resulted in the
1145 creation of this image instance. See @code{make-image-instance} for
1146 more information on governing domains.
1150 @defun image-instance-string image-instance
1151 This function returns the string of the given image instance. This will
1152 only be non-@code{nil} for text image instances.
1155 @defun image-instance-file-name image-instance
1156 This function returns the file name from which @var{image-instance} was
1160 @defun image-instance-mask-file-name image-instance
1161 This function returns the file name from which @var{image-instance}'s
1162 mask was read, if known.
1165 @defun image-instance-depth image-instance
1166 This function returns the depth of the image instance. This is 0 for a
1167 mono pixmap, or a positive integer for a color pixmap.
1170 @defun image-instance-height image-instance
1171 This function returns the height of the image instance, in pixels.
1174 @defun image-instance-width image-instance
1175 This function returns the width of the image instance, in pixels.
1178 @defun image-instance-hotspot-x image-instance
1179 This function returns the X coordinate of the image instance's hotspot,
1180 if known. This is a point relative to the origin of the pixmap. When
1181 an image is used as a mouse pointer, the hotspot is the point on the
1182 image that sits over the location that the pointer points to. This is,
1183 for example, the tip of the arrow or the center of the crosshairs.
1185 This will always be @code{nil} for a non-pointer image instance.
1188 @defun image-instance-hotspot-y image-instance
1189 This function returns the Y coordinate of the image instance's hotspot,
1193 @defun image-instance-foreground image-instance
1194 This function returns the foreground color of @var{image-instance}, if
1195 applicable. This will be a color instance or @code{nil}. (It will only
1196 be non-@code{nil} for colorized mono pixmaps and for pointers.)
1199 @defun image-instance-background image-instance
1200 This function returns the background color of @var{image-instance}, if
1201 applicable. This will be a color instance or @code{nil}. (It will only
1202 be non-@code{nil} for colorized mono pixmaps and for pointers.)
1207 @section Glyph Types
1209 Each glyph has a particular type, which controls how the glyph's image
1210 is generated. Each glyph type has a corresponding list of allowable
1211 image instance types that can be generated. When you call
1212 @code{glyph-image-instance} to retrieve the image instance of a glyph,
1213 XEmacs does the equivalent of calling @code{make-image-instance} and
1214 passing in @var{dest-types} the list of allowable image instance types
1215 for the glyph's type.
1219 @code{buffer} glyphs can be used as the begin-glyph or end-glyph of an
1220 extent, in the modeline, and in the toolbar. Their image can be
1221 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
1222 @code{text}, and @code{subwindow}.
1225 @code{pointer} glyphs can be used to specify the mouse pointer. Their
1226 image can be instantiated as @code{pointer}.
1229 @code{icon} glyphs can be used to specify the icon used when a frame is
1230 iconified. Their image can be instantiated as @code{mono-pixmap} and
1231 @code{color-pixmap}.
1234 @defun glyph-type glyph
1235 This function returns the type of the given glyph. The return value
1236 will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}.
1239 @defun valid-glyph-type-p glyph-type
1240 Given a @var{glyph-type}, this function returns non-@code{nil} if it is
1244 @defun glyph-type-list
1245 This function returns a list of valid glyph types.
1248 @defun buffer-glyph-p object
1249 This function returns non-@code{nil} if @var{object} is a glyph of type
1253 @defun icon-glyph-p object
1254 This function returns non-@code{nil} if @var{object} is a glyph of type
1258 @defun pointer-glyph-p object
1259 This function returns non-@code{nil} if @var{object} is a glyph of type
1264 @section Mouse Pointer
1265 @cindex mouse cursor
1266 @cindex cursor (mouse)
1267 @cindex pointer (mouse)
1268 @cindex mouse pointer
1270 The shape of the mouse pointer when over a particular section of a frame
1271 is controlled using various glyph variables. Since the image of a glyph
1272 is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
1273 or per-device basis.
1275 You should use @code{set-glyph-image} to set the following variables,
1276 @emph{not} @code{setq}.
1278 @defvr Glyph text-pointer-glyph
1279 This variable specifies the shape of the mouse pointer when over text.
1282 @defvr Glyph nontext-pointer-glyph
1283 This variable specifies the shape of the mouse pointer when over a
1284 buffer, but not over text. If unspecified in a particular domain,
1285 @code{text-pointer-glyph} is used.
1288 @defvr Glyph modeline-pointer-glyph
1289 This variable specifies the shape of the mouse pointer when over the modeline.
1290 If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
1293 @defvr Glyph selection-pointer-glyph
1294 This variable specifies the shape of the mouse pointer when over a
1295 selectable text region. If unspecified in a particular domain,
1296 @code{text-pointer-glyph} is used.
1299 @defvr Glyph gc-pointer-glyph
1300 This variable specifies the shape of the mouse pointer when a garbage
1301 collection is in progress. If the selected window is on a window system
1302 and this glyph specifies a value (i.e. a pointer image instance) in the
1303 domain of the selected window, the pointer will be changed as specified
1304 during garbage collection. Otherwise, a message will be printed in the
1305 echo area, as controlled by @code{gc-message}.
1308 @defvr Glyph busy-pointer-glyph
1309 This variable specifies the shape of the mouse pointer when XEmacs is busy.
1310 If unspecified in a particular domain, the pointer is not changed
1311 when XEmacs is busy.
1314 @defvr Glyph menubar-pointer-glyph
1315 This variable specifies the shape of the mouse pointer when over the
1316 menubar. If unspecified in a particular domain, the
1317 window-system-provided default pointer is used.
1320 @defvr Glyph scrollbar-pointer-glyph
1321 This variable specifies the shape of the mouse pointer when over a
1322 scrollbar. If unspecified in a particular domain, the
1323 window-system-provided default pointer is used.
1326 @defvr Glyph toolbar-pointer-glyph
1327 This variable specifies the shape of the mouse pointer when over a
1328 toolbar. If unspecified in a particular domain,
1329 @code{nontext-pointer-glyph} is used.
1332 Internally, these variables are implemented in
1333 @code{default-mouse-motion-handler}, and thus only take effect when the
1334 mouse moves. That function calls @code{set-frame-pointer}, which sets
1335 the current mouse pointer for a frame.
1337 @defun set-frame-pointer frame image-instance
1338 This function sets the mouse pointer of @var{frame} to the given pointer
1339 image instance. You should not call this function directly.
1340 (If you do, the pointer will change again the next time the mouse moves.)
1343 @node Redisplay Glyphs
1344 @section Redisplay Glyphs
1346 @defvr Glyph truncation-glyph
1347 This variable specifies what is displayed at the end of truncated lines.
1350 @defvr Glyph continuation-glyph
1351 This variable specifies what is displayed at the end of wrapped lines.
1354 @defvr Glyph octal-escape-glyph
1355 This variable specifies what to prefix character codes displayed in octal
1359 @defvr Glyph hscroll-glyph
1360 This variable specifies what to display at the beginning of horizontally
1364 @defvr Glyph invisible-text-glyph
1365 This variable specifies what to use to indicate the presence of
1366 invisible text. This is the glyph that is displayed when an ellipsis is
1367 called for, according to @code{selective-display-ellipses} or
1368 @code{buffer-invisibility-spec}). Normally this is three dots (``...'').
1371 @defvr Glyph control-arrow-glyph
1372 This variable specifies what to use as an arrow for control characters.
1378 Subwindows are not currently implemented.
1380 @defun subwindowp object
1381 This function returns non-@code{nil} if @var{object} is a subwindow.