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
39 * Glyph Examples:: Examples of how to work with glyphs.
43 @section Glyph Functions
46 * Creating Glyphs:: Creating new glyphs.
47 * Glyph Properties:: Accessing and modifying a glyph's properties.
48 * Glyph Convenience Functions::
49 Convenience functions for accessing particular
50 properties of a glyph.
51 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
55 @subsection Creating Glyphs
57 @defun make-glyph &optional spec-list type
58 This function creates a new glyph object of type @var{type}.
60 @var{spec-list} is used to initialize the glyph's image. It is
61 typically an image instantiator (a string or a vector; @ref{Image
62 Specifiers}), but can also be a list of such instantiators (each one in
63 turn is tried until an image is successfully produced), a cons of a
64 locale (frame, buffer, etc.) and an instantiator, a list of such conses,
65 or any other form accepted by @code{canonicalize-spec-list}.
66 @xref{Specifiers}, for more information about specifiers.
68 @var{type} specifies the type of the glyph, which specifies in which
69 contexts the glyph can be used, and controls the allowable image types
70 into which the glyph's image can be instantiated. @var{type} should be
71 one of @code{buffer} (used for glyphs in an extent, the modeline, the
72 toolbar, or elsewhere in a buffer), @code{pointer} (used for the
73 mouse-pointer), or @code{icon} (used for a frame's icon), and defaults
74 to @code{buffer}. @xref{Glyph Types}.
76 A glyph in XEmacs does @strong{NOT} refer to a single unit of textual
77 display (the XEmacs term for this is @dfn{rune}), but rather is an
78 object encapsulating a graphical element, such as an image or widget (an
79 element such as a button or text field; @dfn{widget} is the term for
80 this under X Windows, and it's called a @dfn{control} under MS Windows).
81 This graphical element could appear in a buffer, a margin, a gutter, or
82 a toolbar, or as a mouse pointer or an icon, for example.
84 Creating a glyph using @code{make-glyph} does not specify @emph{where}
85 the glyph will be used, but it does specify @emph{what} the glyph will
86 look like. In particular, @var{spec-list} is used to specify this, and it's
87 used to initialize the glyph's @code{image} property, which is an image
88 specifier. (Note that @dfn{image} as used in the context of a glyph's
89 @code{image} property or in the terms @dfn{image specifier}, @dfn{image
90 instantiator}, or @dfn{image instance} does not refer to what people
91 normally think of as an image (which in XEmacs is called a
92 @dfn{pixmap}), but to any graphical element---a pixmap, a widget, or
93 even a block of text, when used in the places that call for a glyph.)
94 The format of the @var{spec-list} is typically an image instantiator (a string
95 or a vector; @ref{Image Specifiers}), but can also be a list of such
96 instantiators (each one in turn is tried until an image is successfully
97 produced), a cons of a locale (frame, buffer, etc.) and an
98 instantiator, a list of such conses, or any other form accepted by
99 @code{canonicalize-spec-list}. @xref{Specifiers}, for more information
102 If you're not familiar with specifiers, you should be in order to
103 understand how glyphs work. The clearest introduction to specifiers
104 is in the Lispref manual, available under Info. (Choose
105 Help->Info->Info Contents on the menubar or type C-h i.) You can
106 also see @code{make-specifier} for a capsule summary. What's important to
107 keep in mind is that a specifier lets you set a different value for
108 any particular buffer, window, frame, device, or console. This allows
109 for a great deal of flexibility; in particular, only one global glyph
110 needs to exist for a particular purpose (e.g. the icon used to represent
111 an iconified frame, the mouse pointer used over particular areas of a
112 frame, etc.), and in these cases you do not create your own glyph, but
113 rather modify the existing one.
115 As well as using @var{spec-list} to initialize the glyph, you can set
116 specifications using @code{set-glyph-image}. Note that, due to a
117 possibly questionable historical design decision, a glyph itself is not
118 actually a specifier, but rather is an object containing an image
119 specifier (as well as other, seldom-used properties). Therefore, you
120 cannot set or access specifications for the glyph's image by directly
121 using @code{set-specifier}, @code{specifier-instance} or the like on the
122 glyph; instead use them on @code{(glyph-image @var{glyph})} or use the
123 convenience functions @code{set-glyph-image},
124 @code{glyph-image-instance}, and @code{glyph-image}.
126 Once you have created a glyph, you specify where it will be used as
131 To insert a glyph into a buffer, create an extent in the buffer and then
132 use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
133 a glyph to be displayed at the corresponding edge of the extent. (It is
134 common to create zero-width extents for this purpose.)
137 To insert a glyph into the left or right margin of a buffer, first
138 make sure the margin is visible by setting a value for the specifiers
139 @code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
140 when using margin glyphs with layout policy @code{whitespace}.) Then follow
141 the same procedure above for inserting a glyph in a buffer, and then
142 set a non-default layout policy for the glyph using
143 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
144 Alternatively, use the high-level annotations API (see
145 @code{make-annotation}). (In point of fact, you can also use the annotations
146 API for glyphs in a buffer, by setting a layout policy of @code{text}.)
149 To insert a glyph into the modeline, just put the glyph directly as one
150 of the modeline elements. (Unfortunately you can't currently put a begin
151 glyph or end glyph on one of the modeline extents---they're ignored.)
154 To insert a glyph into a toolbar, specify it as part of a toolbar
155 instantiator (typically set on the specifier @code{default-toolbar}).
156 See @code{default-toolbar} for more information. (Note that it is
157 standard practice to use a symbol in place of the glyph list in the
158 toolbar instantiator; the symbol is evalled to get the glyph list. This
159 facilitates both creating the toolbar instantiator and modifying
160 individual glyphs in a toolbar later on. For example, you can change
161 the way that the Mail toolbar button looks by modifying the value of the
162 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
163 and then calling @code{(set-specifier-dirty-flag default-toolbar)}.
164 (#### Unfortunately this doesn't quite work the way it should; the
165 change will appear in new frames, but not existing ones.
168 To insert a glyph into a gutter, create or modify a gutter instantiator
169 (typically set on the specifier @code{default-gutter}). Gutter
170 instantiators consist of strings or lists of strings, so to insert a
171 glyph, create an extent over the string, and use
172 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
173 glyph to be displayed at the corresponding edge of the extent, just like
174 for glyphs in a buffer.
177 To use a glyph as the icon for a frame, you do not actually create a new
178 glyph; rather, you change the specifications for the existing glyph
179 @code{frame-icon-glyph}. (Remember that, because of the specifier nature
180 of glyphs, you can set different values for any particular buffer or
184 To use a glyph as the mouse pointer, in general you do not create a new
185 glyph, but rather you change the specifications of various existing
186 glyphs, such as @code{text-pointer-glyph} for the pointer used over
187 text, @code{modeline-pointer-glyph} for the pointer used over the
188 modeline, etc. Do an apropos over @code{*-pointer-glyph} to find all of
189 them. (Note also that you can temporarily set the mouse pointer to some
190 specific shape by using @code{set-frame-pointer}, which takes an image
191 instance, as obtained from calling @code{glyph-image-instance} on a glyph
192 of type @code{pointer} -- either one of the above-mentioned variables or
193 one you created yourself. (See below for what it means to create a
194 glyph of type @code{pointer}.) This pointer will last only until the
195 next mouse motion event is processed or certain other things happen,
196 such as creating or deleting a window. (In fact, the above-mentioned
197 pointer glyph variables are implemented as part of the default handler
198 for mouse motion events. If you want to customize this behavior, take a
199 look at @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
200 really want to get low-level.)
203 To use a glyph to control the shape of miscellaneous redisplay effects
204 such as the truncation and continuation markers, set the appropriate
205 existing glyph variables, as for icons and pointers above. See
206 @code{continuation-glyph}, @code{control-arrow-glyph},
207 @code{hscroll-glyph}, @code{invisible-text-glyph},
208 @code{octal-escape-glyph}, and @code{truncation-glyph}. See also
209 @code{overlay-arrow-string}, an odd redisplay leftover which can be set
210 to a glyph you created, and will cause the glyph to be displayed on top
211 of the text position specified in the marker stored in
212 @code{overlay-arrow-position}.
215 To use a glyph in a display table (i.e. to control the appearance of any
216 individual character), create the appropriate character glyphs and then
217 set a specification for the specifier @code{current-display-table},
218 which controls the appearance of characters. You can also set an
219 overriding display table for use with text displayed in a particular
220 face; see @code{set-face-display-table} and @code{make-display-table}.
221 #### Note: Display tables do not currently support general Mule
222 characters. They will be overhauled at some point to support this
223 and to provide other features required under Mule.
226 To use a glyph as the background pixmap of a face: Note that the
227 background pixmap of a face is actually an image specifier -- probably
228 the only place in XEmacs where an image specifier occurs outside of a
229 glyph. Similarly to how the glyph's image specifier works, you don't
230 create your own image specifier, but rather add specifications to the
231 existing one (using @code{set-face-background-pixmap}). Note that the
232 image instance that is generated in order to actually display the
233 background pixmap is of type @code{mono-pixmap}, meaning that it's a
234 two-color image and the foreground and background of the image get
235 filled in with the corresponding colors from the face.
238 It is extremely rare that you will ever have to specify a value for
239 @var{type}, which should be one of @code{buffer} (used for glyphs in an
240 extent, the modeline, the toolbar, or elsewhere in a buffer),
241 @code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
242 frame's icon), and defaults to @code{buffer}. The only cases where it
243 needs to be specified is when creating icon or pointer glyphs, and in
244 both cases the necessary glyphs have already been created at startup and
245 are accessed through the appropriate variables,
246 e.g. @code{text-pointer-glyph} (or in general, @code{*-pointer-glyph})
247 and @code{frame-icon-glyph}. @xref{Glyph Types}.
250 @defun make-glyph-internal &optional type
251 This function creates a new, uninitialized glyph of type @var{type}.
254 @defun make-pointer-glyph &optional spec-list
256 Return a new @code{pointer-glyph} object with the specification list
257 @var{spec-list}. This function is equivalent to calling
258 @code{make-glyph} with a @var{type} of @code{pointer}.
260 It is extremely unlikely that you will ever need to create a pointer
261 glyph. Instead, you probably want to be calling @code{set-glyph-image}
262 on an existing glyph, e.g. @code{text-pointer-glyph}.
265 @defun make-icon-glyph &optional spec-list
267 Return a new @code{pointer-glyph} object with the specification list
268 @var{spec-list}. This function is equivalent to calling
269 @code{make-glyph} with a @var{type} of @code{icon}.
271 It is extremely unlikely that you will ever need to create a pointer
272 glyph. Instead, you probably want to be calling @code{set-glyph-image}
273 on an existing glyph, e.g. @code{text-pointer-glyph}.
276 @node Glyph Properties
277 @subsection Glyph Properties
279 Each glyph has a list of properties, which control all of the aspects of
280 the glyph's appearance. The following symbols have predefined meanings:
284 The image used to display the glyph.
287 Percent above baseline that glyph is to be displayed. Only for glyphs
288 displayed inside of a buffer.
291 Whether the glyph contributes to the height of the line it's on.
292 Only for glyphs displayed inside of a buffer.
295 Face of this glyph (@emph{not} a specifier).
298 @defun set-glyph-property glyph property value &optional locale tag-set how-to-add
299 This function changes a property of a @var{glyph}.
301 For built-in properties, the actual value of the property is a specifier
302 and you cannot change this; but you can change the specifications within
303 the specifier, and that is what this function will do. For user-defined
304 properties, you can use this function to either change the actual value
305 of the property or, if this value is a specifier, change the
306 specifications within it.
308 If @var{property} is a built-in property, the specifications to be added
309 to this property can be supplied in many different ways:
313 If @var{value} is a simple instantiator (e.g. a string naming a pixmap
314 filename) or a list of instantiators, then the instantiator(s) will be
315 added as a specification of the property for the given @var{locale}
316 (which defaults to @code{global} if omitted).
319 If @var{value} is a list of specifications (each of which is a cons of a
320 locale and a list of instantiators), then @var{locale} must be
321 @code{nil} (it does not make sense to explicitly specify a locale in
322 this case), and specifications will be added as given.
325 If @var{value} is a specifier (as would be returned by
326 @code{glyph-property} if no @var{locale} argument is given), then some
327 or all of the specifications in the specifier will be added to the
328 property. In this case, the function is really equivalent to
329 @code{copy-specifier} and @var{locale} has the same semantics (if it is
330 a particular locale, the specification for the locale will be copied; if
331 a locale type, specifications for all locales of that type will be
332 copied; if @code{nil} or @code{all}, then all specifications will be
336 @var{how-to-add} should be either @code{nil} or one of the symbols
337 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
338 @code{remove-tag-set-append}, @code{remove-locale},
339 @code{remove-locale-type}, or @code{remove-all}. See
340 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
341 of what each of these means. Most of the time, you do not need to worry
342 about this argument; the default behavior usually is fine.
344 In general, it is OK to pass an instance object (e.g. as returned by
345 @code{glyph-property-instance}) as an instantiator in place of an actual
346 instantiator. In such a case, the instantiator used to create that
347 instance object will be used (for example, if you set a font-instance
348 object as the value of the @code{font} property, then the font name used
349 to create that object will be used instead). If some cases, however,
350 doing this conversion does not make sense, and this will be noted in the
351 documentation for particular types of instance objects.
353 If @var{property} is not a built-in property, then this function will
354 simply set its value if @var{locale} is @code{nil}. However, if
355 @var{locale} is given, then this function will attempt to add
356 @var{value} as the instantiator for the given @var{locale}, using
357 @code{add-spec-to-specifier}. If the value of the property is not a
358 specifier, it will automatically be converted into a @code{generic}
362 @defun glyph-property glyph property &optional locale
363 This function returns @var{glyph}'s value of the given @var{property}.
365 If @var{locale} is omitted, the @var{glyph}'s actual value for
366 @var{property} will be returned. For built-in properties, this will be
367 a specifier object of a type appropriate to the property (e.g. a font or
368 color specifier). For other properties, this could be anything.
370 If @var{locale} is supplied, then instead of returning the actual value,
371 the specification(s) for the given locale or locale type will be
372 returned. This will only work if the actual value of @var{property} is
373 a specifier (this will always be the case for built-in properties, but
374 may or may not apply to user-defined properties). If the actual value
375 of @var{property} is not a specifier, this value will simply be returned
376 regardless of @var{locale}.
378 The return value will be a list of instantiators (e.g. vectors
379 specifying pixmap data), or a list of specifications, each of which is a
380 cons of a locale and a list of instantiators. Specifically, if
381 @var{locale} is a particular locale (a buffer, window, frame, device, or
382 @code{global}), a list of instantiators for that locale will be
383 returned. Otherwise, if @var{locale} is a locale type (one of the
384 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
385 the specifications for all locales of that type will be returned.
386 Finally, if @var{locale} is @code{all}, the specifications for all
387 locales of all types will be returned.
389 The specifications in a specifier determine what the value of
390 @var{property} will be in a particular @dfn{domain} or set of
391 circumstances, which is typically a particular Emacs window along with
392 the buffer it contains and the frame and device it lies within. The
393 value is derived from the instantiator associated with the most specific
394 locale (in the order buffer, window, frame, device, and @code{global})
395 that matches the domain in question. In other words, given a domain
396 (i.e. an Emacs window, usually), the specifier for @var{property} will
397 first be searched for a specification whose locale is the buffer
398 contained within that window; then for a specification whose locale is
399 the window itself; then for a specification whose locale is the frame
400 that the window is contained within; etc. The first instantiator that
401 is valid for the domain (usually this means that the instantiator is
402 recognized by the device [i.e. the X server or TTY device] that the
403 domain is on). The function @code{glyph-property-instance} actually does
404 all this, and is used to determine how to display the glyph.
407 @defun glyph-property-instance glyph property &optional domain default no-fallback
408 This function returns the instance of @var{glyph}'s @var{property} in the
409 specified @var{domain}.
411 Under most circumstances, @var{domain} will be a particular window, and
412 the returned instance describes how the specified property actually is
413 displayed for that window and the particular buffer in it. Note that
414 this may not be the same as how the property appears when the buffer is
415 displayed in a different window or frame, or how the property appears in
416 the same window if you switch to another buffer in that window; and in
417 those cases, the returned instance would be different.
419 The returned instance is an image-instance object, and you can query it
420 using the appropriate image instance functions. For example, you could use
421 @code{image-instance-depth} to find out the depth (number of color
422 planes) of a pixmap displayed in a particular window. The results might
423 be different from the results you would get for another window (perhaps
424 the user specified a different image for the frame that window is on; or
425 perhaps the same image was specified but the window is on a different X
426 server, and that X server has different color capabilities from this
429 @var{domain} defaults to the selected window if omitted.
431 @var{domain} can be a frame or device, instead of a window. The value
432 returned for such a domain is used in special circumstances when a
433 more specific domain does not apply; for example, a frame value might be
434 used for coloring a toolbar, which is conceptually attached to a frame
435 rather than a particular window. The value is also useful in
436 determining what the value would be for a particular window within the
437 frame or device, if it is not overridden by a more specific
440 If @var{property} does not name a built-in property, its value will
441 simply be returned unless it is a specifier object, in which case it
442 will be instanced using @code{specifier-instance}.
444 Optional arguments @var{default} and @var{no-fallback} are the same as
445 in @code{specifier-instance}. @xref{Specifiers}.
448 @defun remove-glyph-property glyph property &optional locale tag-set exact-p
449 This function removes a property from a glyph. For built-in properties,
450 this is analogous to @code{remove-specifier}. @xref{Specifiers,
451 remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
452 and @var{exact-p} arguments.
455 @node Glyph Convenience Functions
456 @subsection Glyph Convenience Functions
458 The following functions are provided for working with specific
459 properties of a glyph. Note that these are exactly like calling
460 the general functions described above and passing in the
461 appropriate value for @var{property}.
463 Remember that if you want to determine the ``value'' of a
464 specific glyph property, you probably want to use the @code{*-instance}
465 functions. For example, to determine whether a glyph contributes
466 to its line height, use @code{glyph-contrib-p-instance}, not
467 @code{glyph-contrib-p}. (The latter will return a boolean specifier
468 or a list of specifications, and you probably aren't concerned with
471 @defun glyph-image glyph &optional locale
472 This function is equivalent to calling @code{glyph-property} with
473 a property of @code{image}. The return value will be an image
474 specifier if @var{locale} is @code{nil} or omitted; otherwise,
475 it will be a specification or list of specifications.
478 @defun set-glyph-image glyph spec &optional locale tag-set how-to-add
479 This function is equivalent to calling @code{set-glyph-property} with
480 a property of @code{image}.
483 @defun glyph-image-instance glyph &optional domain default no-fallback
484 This function returns the instance of @var{glyph}'s image in the given
485 @var{domain}, and is equivalent to calling
486 @code{glyph-property-instance} with a property of @code{image}. The
487 return value will be an image instance.
489 Normally @var{domain} will be a window or @code{nil} (meaning the
490 selected window), and an instance object describing how the image
491 appears in that particular window and buffer will be returned.
494 @defun glyph-contrib-p glyph &optional locale
495 This function is equivalent to calling @code{glyph-property} with
496 a property of @code{contrib-p}. The return value will be a boolean
497 specifier if @var{locale} is @code{nil} or omitted; otherwise,
498 it will be a specification or list of specifications.
501 @defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
502 This function is equivalent to calling @code{set-glyph-property} with
503 a property of @code{contrib-p}.
506 @defun glyph-contrib-p-instance glyph &optional domain default no-fallback
507 This function returns whether the glyph contributes to its line height
508 in the given @var{domain}, and is equivalent to calling
509 @code{glyph-property-instance} with a property of @code{contrib-p}. The
510 return value will be either @code{nil} or @code{t}. (Normally @var{domain}
511 will be a window or @code{nil}, meaning the selected window.)
514 @defun glyph-baseline glyph &optional locale
515 This function is equivalent to calling @code{glyph-property} with a
516 property of @code{baseline}. The return value will be a specifier if
517 @var{locale} is @code{nil} or omitted; otherwise, it will be a
518 specification or list of specifications.
521 @defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
522 This function is equivalent to calling @code{set-glyph-property} with
523 a property of @code{baseline}.
526 @defun glyph-baseline-instance glyph &optional domain default no-fallback
527 This function returns the instance of @var{glyph}'s baseline value in
528 the given @var{domain}, and is equivalent to calling
529 @code{glyph-property-instance} with a property of @code{baseline}. The
530 return value will be an integer or @code{nil}.
532 Normally @var{domain} will be a window or @code{nil} (meaning the
533 selected window), and an instance object describing the baseline value
534 appears in that particular window and buffer will be returned.
537 @defun glyph-face glyph
538 This function returns the face of @var{glyph}. (Remember, this is
539 not a specifier, but a simple property.)
542 @defun set-glyph-face glyph face
543 This function changes the face of @var{glyph} to @var{face}.
546 @node Glyph Dimensions
547 @subsection Glyph Dimensions
549 @defun glyph-width glyph &optional window
550 This function returns the width of @var{glyph} on @var{window}. This
551 may not be exact as it does not take into account all of the context
555 @defun glyph-ascent glyph &optional window
556 This function returns the ascent value of @var{glyph} on @var{window}.
557 This may not be exact as it does not take into account all of the
558 context that redisplay will.
561 @defun glyph-descent glyph &optional window
562 This function returns the descent value of @var{glyph} on @var{window}.
563 This may not be exact as it does not take into account all of the
564 context that redisplay will.
567 @defun glyph-height glyph &optional window
568 This function returns the height of @var{glyph} on @var{window}. (This
569 is equivalent to the sum of the ascent and descent values.) This may
570 not be exact as it does not take into account all of the context that
578 * Image Specifiers:: Specifying how an image will appear.
579 * Image Instantiator Conversion::
580 Conversion is applied to image instantiators
581 at the time they are added to an
582 image specifier or at the time they
583 are passed to @code{make-image-instance}.
584 * Image Instances:: What an image specifier gets instanced as.
587 @node Image Specifiers
588 @subsection Image Specifiers
589 @cindex image specifiers
591 An image specifier is used to describe the actual image of a glyph.
592 It works like other specifiers (@pxref{Specifiers}), in that it contains
593 a number of specifications describing how the image should appear in a
594 variety of circumstances. These specifications are called @dfn{image
595 instantiators}. When XEmacs wants to display the image, it instantiates
596 the image into an @dfn{image instance}. Image instances are their own
597 primitive object type (similar to font instances and color instances),
598 describing how the image appears in a particular domain. (On the other
599 hand, image instantiators, which are just descriptions of how the image
600 should appear, are represented using strings or vectors.)
602 @defun image-specifier-p object
603 This function returns non-@code{nil} if @var{object} is an image specifier.
604 Usually, an image specifier results from calling @code{glyph-image} on
608 @defun make-image-specifier spec-list
609 This function creates a new image specifier object and initializes it
610 according to @var{spec-list}. @xref{Specifiers}.
612 Note that, in practice, you rarely, if ever, need to actually create an
613 image specifier! (This function exists mainly for completeness.) Pretty
614 much the only use for image specifiers is to control how glyphs are
615 displayed, and the image specifier associated with a glyph (the
616 @code{image} property of a glyph) is created automatically when a glyph
617 is created and need not (and cannot, for that matter) ever be changed
618 (@pxref{Glyphs}). In fact, the design decision to create a separate
619 image specifier type, rather than make glyphs themselves be specifiers,
620 is debatable---the other properties of glyphs are rarely used and could
621 conceivably have been incorporated into the glyph's instantiator. The
622 rarely used glyph types (buffer, pointer, icon) could also have been
623 incorporated into the instantiator.
626 Image instantiators come in many formats: @code{xbm}, @code{xpm},
627 @code{gif}, @code{jpeg}, etc. This describes the format of the data
628 describing the image. The resulting image instances also come in many
629 types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
630 @code{pointer}, etc. This refers to the behavior of the image and the
631 sorts of places it can appear. (For example, a color-pixmap image has
632 fixed colors specified for it, while a mono-pixmap image comes in two
633 unspecified shades ``foreground'' and ``background'' that are determined
634 from the face of the glyph or surrounding text; a text image appears as
635 a string of text and has an unspecified foreground, background, and
636 font; a pointer image behaves like a mono-pixmap image but can only be
637 used as a mouse pointer [mono-pixmap images cannot be used as mouse
638 pointers]; etc.) It is important to keep the distinction between image
639 instantiator format and image instance type in mind. Typically, a given
640 image instantiator format can result in many different image instance
641 types (for example, @code{xpm} can be instanced as @code{color-pixmap},
642 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
643 instanced only as @code{pointer}), and a particular image instance type
644 can be generated by many different image instantiator formats (e.g.
645 @code{color-pixmap} can be generated by @code{xpm}, @code{gif},
648 @xref{Image Instances}, for a more detailed discussion of image
651 An image instantiator should be a string or a vector of the form
654 @code{[@var{format} @var{:keyword} @var{value} ...]}
657 i.e. a format symbol followed by zero or more alternating keyword-value
658 pairs. The @dfn{format} field should be a symbol, one of
662 Don't display anything; no keywords are valid for this. Can only be
663 instanced as @code{nothing}.
665 Display this image as a text string. Can only be instanced
666 as @code{text}, although support for instancing as @code{mono-pixmap}
668 @item formatted-string
669 Display this image as a text string with replaceable fields,
670 similar to a modeline format string; not currently implemented.
672 An X bitmap; only if X support was compiled into this XEmacs. Can be
673 instanced as @code{mono-pixmap}, @code{color-pixmap}, or
676 An XPM pixmap; only if XPM support was compiled into this XEmacs. Can
677 be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
678 @code{pointer}. XPM is an add-on library for X that was designed to
679 rectify the shortcomings of the XBM format. Most implementations of X
680 include the XPM library as a standard part. If your vendor does not, it
681 is highly recommended that you download it and install it. You can get
682 it from the standard XEmacs FTP site, among other places.
684 An X-Face bitmap, used to encode people's faces in e-mail messages;
685 only if X-Face support was compiled into this XEmacs. Can be instanced
686 as @code{mono-pixmap}, @code{color-pixmap}, or @code{pointer}.
688 A GIF87 or GIF89 image; only if GIF support was compiled into this
689 XEmacs. Can be instanced as @code{color-pixmap}. Note that XEmacs
690 includes GIF decoding functions as a standard part of it, so if you have
691 X support, you will normally have GIF support, unless you explicitly
692 disable it at configure time.
694 A JPEG-format image; only if JPEG support was compiled into this
695 XEmacs. Can be instanced as @code{color-pixmap}. If you have the JPEG
696 libraries present on your system when XEmacs is built, XEmacs will
697 automatically detect this and use them, unless you explicitly disable it
700 A PNG/GIF24 image; only if PNG support was compiled into this XEmacs.
701 Can be instanced as @code{color-pixmap}.
703 A TIFF-format image; only if TIFF support was compiled into this XEmacs.
705 One of the standard cursor-font names, such as @samp{watch} or
706 @samp{right_ptr} under X. Under X, this is, more specifically, any of
707 the standard cursor names from appendix B of the Xlib manual [also known
708 as the file @file{<X11/cursorfont.h>}] minus the @samp{XC_} prefix. On
709 other window systems, the valid names will be specific to the type of
710 window system. Can only be instanced as @code{pointer}.
712 A glyph from a font; i.e. the name of a font, and glyph index into it
713 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
714 Only if X support was compiled into this XEmacs. Currently can only be
715 instanced as @code{pointer}, although this should probably be fixed.
716 @item mswindows-resource
717 An MS Windows pointer resource. Specifies a resource to retrieve
718 directly from the system (an OEM resource) or from a file, particularly
719 an executable file. If the resource is to be retrieved from a file, use
720 :file and optionally :resource-id. Otherwise use :resource-id. Always
721 specify :resource-type to specify the type (cursor, bitmap or icon) of
722 the resource. Possible values for :resource-id are listed below. Can
723 be instanced as @code{pointer} or @code{color-pixmap}.
725 An embedded windowing system window. Can only be instanced as
728 A button widget; either a push button, radio button or toggle button.
729 Can only be instanced as @code{widget}.
731 A drop list of selectable items in a widget, for editing text.
732 Can only be instanced as @code{widget}.
734 A text editing widget. Can only be instanced as @code{widget}.
736 A static, text-only, widget; for displaying text. Can only be instanced
739 A widget for controlling the positioning of children underneath it.
740 Through the use of nested layouts, a widget hierarchy can be created
741 which can have the appearance of any standard dialog box or similar
742 arrangement; all of this is counted as one @dfn{glyph} and could appear
743 in many of the places that expect a single glyph. Can only be instanced
746 @c #### Document me better!
747 The native version of a layout widget.
748 Can only be instanced as @code{widget}.
750 A sliding widget, for showing progress. Can only be instanced as
753 A tab widget; a series of user selectable tabs. Can only be instanced
756 A folding widget. Can only be instanced as @code{widget}.
758 A scrollbar widget. Can only be instanced as @code{widget}.
760 XEmacs tries to guess what format the data is in. If X support exists,
761 the data string will be checked to see if it names a filename. If so,
762 and this filename contains XBM or XPM data, the appropriate sort of
763 pixmap or pointer will be created. [This includes picking up any
764 specified hotspot or associated mask file.] Otherwise, if @code{pointer}
765 is one of the allowable image-instance types and the string names a
766 valid cursor-font name, the image will be created as a pointer.
767 Otherwise, the image will be displayed as text. If no X support exists,
768 the image will always be displayed as text.
770 Inherit from the background-pixmap property of a face. Can only be
771 instanced as @code{mono-pixmap}.
774 The valid keywords are:
778 Inline data. For most formats above, this should be a string. For
779 XBM images, this should be a list of three elements: width, height, and
780 a string of bit data. This keyword is not valid for instantiator
781 format @code{nothing}.
784 Data is contained in a file. The value is the name of this file. If
785 both @code{:data} and @code{:file} are specified, the image is created
786 from what is specified in @code{:data} and the string in @code{:file}
787 becomes the value of the @code{image-instance-file-name} function when
788 applied to the resulting image-instance. This keyword is not valid for
789 instantiator formats @code{nothing}, @code{string},
790 @code{formatted-string}, @code{cursor-font}, @code{font}, and
795 For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
796 These keywords allow you to explicitly specify foreground and background
797 colors. The argument should be anything acceptable to
798 @code{make-color-instance}. This will cause what would be a
799 @code{mono-pixmap} to instead be colorized as a two-color color-pixmap,
800 and specifies the foreground and/or background colors for a pointer
801 instead of black and white.
804 For @code{xbm} and @code{xface}. This specifies a mask to be used with the
805 bitmap. The format is a list of width, height, and bits, like for
809 For @code{xbm} and @code{xface}. This specifies a file containing the
810 mask data. If neither a mask file nor inline mask data is given for an
811 XBM image, and the XBM image comes from a file, XEmacs will look for a
812 mask file with the same name as the image file but with @samp{Mask} or
813 @samp{msk} appended. For example, if you specify the XBM file
814 @file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
815 the associated mask file @file{left_ptrmsk} will automatically be picked
820 For @code{xbm} and @code{xface}. These keywords specify a hotspot if
821 the image is instantiated as a @code{pointer}. Note that if the XBM
822 image file specifies a hotspot, it will automatically be picked up if no
823 explicit hotspot is given.
826 Only for @code{xpm}. This specifies an alist that maps strings that
827 specify symbolic color names to the actual color to be used for that
828 symbolic color (in the form of a string or a color-specifier object).
829 If this is not specified, the contents of @code{xpm-color-symbols} are
830 used to generate the alist.
832 Only for @code{mswindows-resource}. This must be either an integer
833 (which directly specifies a resource number) or a string. Valid strings
838 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
839 "reduce", "zoom", "restore", "reduced", "zoomd",
840 "restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd",
841 "mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi",
842 "lfarrowi", "size", "btsize", "check", "checkboxes", and
847 "normal", "ibeam", "wait", "cross", "up", "sizenwse",
848 "sizenesw", "sizewe", "sizens", "sizeall", and "no".
852 "sample", "hand", "ques", "bang", "note", and "winlogo".
854 Only for @code{mswindows-resource}. This must be a symbol, either
855 @code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
856 resource to be retrieved.
858 Only for @code{inherit}. This specifies the face to inherit from. For
859 widgets this also specifies the face to use for display. It defaults to
863 Keywords accepted as menu item specs are also accepted by widgets.
864 These are @code{:selected}, @code{:active}, @code{:suffix},
865 @code{:keys}, @code{:style}, @code{:filter}, @code{:config},
866 @code{:included}, @code{:key-sequence}, @code{:accelerator},
867 @code{:label} and @code{:callback}.
869 If instead of a vector, the instantiator is a string, it will be
870 converted into a vector by looking it up according to the specs in the
871 @code{console-type-image-conversion-list} for the console type of
872 the domain (usually a window; sometimes a frame or device) over which
873 the image is being instantiated.
875 If the instantiator specifies data from a file, the data will be read in
876 at the time that the instantiator is added to the image specifier (which
877 may be well before the image is actually displayed), and the
878 instantiator will be converted into one of the inline-data forms, with
879 the filename retained using a @code{:file} keyword. This implies that
880 the file must exist when the instantiator is added to the image, but
881 does not need to exist at any other time (e.g. it may safely be a
884 @defun valid-image-instantiator-format-p format &optional locale
885 This function returns non-@code{nil} if @var{format} is a valid image
888 If @var{locale} is non-@code{nil} then the format is checked in that locale.
889 If @var{locale} is @code{nil} the current console is used.
891 Note that the return value for many formats listed above depends on
892 whether XEmacs was compiled with support for that format.
895 @defun image-instantiator-format-list
896 This function return a list of valid image-instantiator formats.
899 @defvar xpm-color-symbols
900 This variable holds definitions of logical color-names used when reading
901 XPM files. Elements of this list should be of the form
902 @code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name}
903 should be a string, which is the name of the color to define; the
904 @var{form-to-evaluate} should evaluate to a color specifier object, or a
905 string to be passed to @code{make-color-instance} (@pxref{Colors}). If
906 a loaded XPM file references a symbolic color called @var{color-name},
907 it will display as the computed color instead.
909 The default value of this variable defines the logical color names
910 @samp{"foreground"} and @samp{"background"} to be the colors of the
914 @defvar x-bitmap-file-path
915 A list of the directories in which X bitmap files may be found. If @code{nil},
916 this is initialized from the @samp{"*bitmapFilePath"} resource. This is
917 used by the @code{make-image-instance} function (however, note that if
918 the environment variable @samp{XBMLANGPATH} is set, it is consulted
922 @node Image Instantiator Conversion
923 @subsection Image Instantiator Conversion
924 @cindex image instantiator conversion
925 @cindex conversion of image instantiators
927 @defun set-console-type-image-conversion-list console-type list
928 This function sets the image-conversion-list for consoles of the given
929 @var{console-type}. The image-conversion-list specifies how image
930 instantiators that are strings should be interpreted. Each element of
931 the list should be a list of two elements (a regular expression string
932 and a vector) or a list of three elements (the preceding two plus an
933 integer index into the vector). The string is converted to the vector
934 associated with the first matching regular expression. If a vector
935 index is specified, the string itself is substituted into that position
938 Note: The conversion above is applied when the image instantiator is
939 added to an image specifier, not when the specifier is actually
940 instantiated. Therefore, changing the image-conversion-list only affects
941 newly-added instantiators. Existing instantiators in glyphs and image
942 specifiers will not be affected.
945 @defun console-type-image-conversion-list console-type
946 This function returns the image-conversion-list for consoles of the given
950 @node Image Instances
951 @subsection Image Instances
952 @cindex image instances
954 Image-instance objects encapsulate the way a particular image (pixmap,
955 etc.) is displayed on a particular device.
957 In most circumstances, you do not need to directly create image
958 instances; use a glyph instead. However, it may occasionally be useful
959 to explicitly create image instances, if you want more control over the
960 instantiation process.
962 @defun image-instance-p object
963 This function returns non-@code{nil} if @var{object} is an image instance.
967 * Image Instance Types:: Each image instances has a particular type.
968 * Image Instance Functions:: Functions for working with image instances.
971 @node Image Instance Types
972 @subsubsection Image Instance Types
973 @cindex image instance types
975 Image instances come in a number of different types. The type
976 of an image instance specifies the nature of the image: Whether
977 it is a text string, a mono pixmap, a color pixmap, etc.
979 The valid image instance types are
983 Nothing is displayed.
986 Displayed as text. The foreground and background colors and the
987 font of the text are specified independent of the pixmap. Typically
988 these attributes will come from the face of the surrounding text,
989 unless a face is specified for the glyph in which the image appears.
992 Displayed as a mono pixmap (a pixmap with only two colors where the
993 foreground and background can be specified independent of the pixmap;
994 typically the pixmap assumes the foreground and background colors of
995 the text around it, unless a face is specified for the glyph in which
999 Displayed as a color pixmap.
1002 Used as the mouse pointer for a window.
1005 A child window that is treated as an image. This allows (e.g.)
1006 another program to be responsible for drawing into the window.
1007 Not currently implemented.
1010 @defun valid-image-instance-type-p type
1011 This function returns non-@code{nil} if @var{type} is a valid image
1015 @defun image-instance-type-list
1016 This function returns a list of the valid image instance types.
1019 @defun image-instance-type image-instance
1020 This function returns the type of the given image instance. The return
1021 value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
1022 @code{color-pixmap}, @code{pointer}, or @code{subwindow}.
1025 @defun text-image-instance-p object
1026 This function returns non-@code{nil} if @var{object} is an image
1027 instance of type @code{text}.
1030 @defun mono-pixmap-image-instance-p object
1031 This function returns non-@code{nil} if @var{object} is an image
1032 instance of type @code{mono-pixmap}.
1035 @defun color-pixmap-image-instance-p object
1036 This function returns non-@code{nil} if @var{object} is an image
1037 instance of type @code{color-pixmap}.
1040 @defun pointer-image-instance-p object
1041 This function returns non-@code{nil} if @var{object} is an image
1042 instance of type @code{pointer}.
1045 @defun subwindow-image-instance-p object
1046 This function returns non-@code{nil} if @var{object} is an image
1047 instance of type @code{subwindow}.
1050 @defun nothing-image-instance-p object
1051 This function returns non-@code{nil} if @var{object} is an image
1052 instance of type @code{nothing}.
1055 @defun widget-image-instance-p object
1056 Return @code{t} if @var{object} is an image instance of type @code{widget}.
1059 @node Image Instance Functions
1060 @subsubsection Image Instance Functions
1062 @defun make-image-instance data &optional domain dest-types noerror
1063 This function creates a new image-instance object.
1065 @var{data} is an image instantiator, which describes the image
1066 (@pxref{Image Specifiers}).
1068 @var{dest-types} should be a list of allowed image instance types that
1069 can be generated. The @var{dest-types} list is unordered. If multiple
1070 destination types are possible for a given instantiator, the ``most
1071 natural'' type for the instantiator's format is chosen. (For XBM, the
1072 most natural types are @code{mono-pixmap}, followed by
1073 @code{color-pixmap}, followed by @code{pointer}. For the other normal
1074 image formats, the most natural types are @code{color-pixmap}, followed
1075 by @code{mono-pixmap}, followed by @code{pointer}. For the string and
1076 formatted-string formats, the most natural types are @code{text},
1077 followed by @code{mono-pixmap} (not currently implemented), followed by
1078 @code{color-pixmap} (not currently implemented). For MS Windows
1079 resources, the most natural type for pointer resources is
1080 @code{pointer}, and for the others it's @code{color-pixmap}. The other
1081 formats can only be instantiated as one type. (If you want to control
1082 more specifically the order of the types into which an image is
1083 instantiated, just call @code{make-image-instance} repeatedly until it
1084 succeeds, passing less and less preferred destination types each time.
1086 If @var{dest-types} is omitted, all possible types are allowed.
1088 @var{domain} specifies the domain to which the image instance will be
1089 attached. This domain is termed the @dfn{governing domain}. The type
1090 of the governing domain depends on the image instantiator
1091 format. (Although, more correctly, it should probably depend on the
1092 image instance type.) For example, pixmap image instances are specific
1093 to a device, but widget image instances are specific to a particular
1094 XEmacs window because in order to display such a widget when two windows
1095 onto the same buffer want to display the widget, two separate underlying
1096 widgets must be created. (That's because a widget is actually a child
1097 window-system window, and all window-system windows have a unique
1098 existence on the screen.) This means that the governing domain for a
1099 pixmap image instance will be some device (most likely, the only
1100 existing device), whereas the governing domain for a widget image
1101 instance will be some XEmacs window.
1103 If you specify an overly general @var{domain} (e.g. a frame when a
1104 window was wanted), an error is signaled. If you specify an overly
1105 specific @var{domain} (e.g. a window when a device was wanted), the
1106 corresponding general domain is fetched and used instead. For
1107 @code{make-image-instance}, it makes no difference whether you specify
1108 an overly specific domain or the properly general domain derived from
1109 it. However, it does matter when creating an image instance by
1110 instantiating a specifier or glyph (e.g. with
1111 @code{glyph-image-instance}), because the more specific domain causes
1112 spec lookup to start there and proceed to more general domains. (It
1113 would also matter when creating an image instance with an instantiator
1114 format of @code{inherit}, but we currently disallow this. #### We should
1117 If omitted, @var{domain} defaults to the selected window.
1119 @var{noerror} controls what happens when the image cannot be generated.
1120 If @code{nil}, an error message is generated. If @code{t}, no messages
1121 are generated and this function returns @code{nil}. If anything else, a
1122 warning message is generated and this function returns @code{nil}.
1125 @defun colorize-image-instance image-instance foreground background
1126 This function makes the image instance be displayed in the given
1127 colors. Image instances come in two varieties: bitmaps, which are 1
1128 bit deep which are rendered in the prevailing foreground and background
1129 colors; and pixmaps, which are of arbitrary depth (including 1) and
1130 which have the colors explicitly specified. This function converts a
1131 bitmap to a pixmap. If the image instance was a pixmap already,
1132 nothing is done (and @code{nil} is returned). Otherwise @code{t} is
1136 @defun image-instance-name image-instance
1137 This function returns the name of the given image instance.
1140 @defun image-instance-domain image-instance
1142 Return the governing domain of the given @var{image-instance}. The
1143 governing domain of an image instance is the domain that the image
1144 instance is specific to. It is @emph{NOT} necessarily the domain that
1145 was given to the call to @code{specifier-instance} that resulted in the
1146 creation of this image instance. See @code{make-image-instance} for
1147 more information on governing domains.
1151 @defun image-instance-string image-instance
1152 This function returns the string of the given image instance. This will
1153 only be non-@code{nil} for text image instances.
1156 @defun image-instance-file-name image-instance
1157 This function returns the file name from which @var{image-instance} was
1161 @defun image-instance-mask-file-name image-instance
1162 This function returns the file name from which @var{image-instance}'s
1163 mask was read, if known.
1166 @defun image-instance-depth image-instance
1167 This function returns the depth of the image instance. This is 0 for a
1168 mono pixmap, or a positive integer for a color pixmap.
1171 @defun image-instance-height image-instance
1172 This function returns the height of the image instance, in pixels.
1175 @defun image-instance-width image-instance
1176 This function returns the width of the image instance, in pixels.
1179 @defun image-instance-hotspot-x image-instance
1180 This function returns the X coordinate of the image instance's hotspot,
1181 if known. This is a point relative to the origin of the pixmap. When
1182 an image is used as a mouse pointer, the hotspot is the point on the
1183 image that sits over the location that the pointer points to. This is,
1184 for example, the tip of the arrow or the center of the crosshairs.
1186 This will always be @code{nil} for a non-pointer image instance.
1189 @defun image-instance-hotspot-y image-instance
1190 This function returns the Y coordinate of the image instance's hotspot,
1194 @defun image-instance-foreground image-instance
1195 This function returns the foreground color of @var{image-instance}, if
1196 applicable. This will be a color instance or @code{nil}. (It will only
1197 be non-@code{nil} for colorized mono pixmaps and for pointers.)
1200 @defun image-instance-background image-instance
1201 This function returns the background color of @var{image-instance}, if
1202 applicable. This will be a color instance or @code{nil}. (It will only
1203 be non-@code{nil} for colorized mono pixmaps and for pointers.)
1208 @section Glyph Types
1210 Each glyph has a particular type, which controls how the glyph's image
1211 is generated. Each glyph type has a corresponding list of allowable
1212 image instance types that can be generated. When you call
1213 @code{glyph-image-instance} to retrieve the image instance of a glyph,
1214 XEmacs does the equivalent of calling @code{make-image-instance} and
1215 passing in @var{dest-types} the list of allowable image instance types
1216 for the glyph's type.
1220 @code{buffer} glyphs can be used as the begin-glyph or end-glyph of an
1221 extent, in the modeline, and in the toolbar. Their image can be
1222 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
1223 @code{text}, and @code{subwindow}.
1226 @code{pointer} glyphs can be used to specify the mouse pointer. Their
1227 image can be instantiated as @code{pointer}.
1230 @code{icon} glyphs can be used to specify the icon used when a frame is
1231 iconified. Their image can be instantiated as @code{mono-pixmap} and
1232 @code{color-pixmap}.
1235 @defun glyph-type glyph
1236 This function returns the type of the given glyph. The return value
1237 will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}.
1240 @defun valid-glyph-type-p glyph-type
1241 Given a @var{glyph-type}, this function returns non-@code{nil} if it is
1245 @defun glyph-type-list
1246 This function returns a list of valid glyph types.
1249 @defun buffer-glyph-p object
1250 This function returns non-@code{nil} if @var{object} is a glyph of type
1254 @defun icon-glyph-p object
1255 This function returns non-@code{nil} if @var{object} is a glyph of type
1259 @defun pointer-glyph-p object
1260 This function returns non-@code{nil} if @var{object} is a glyph of type
1265 @section Mouse Pointer
1266 @cindex mouse cursor
1267 @cindex cursor (mouse)
1268 @cindex pointer (mouse)
1269 @cindex mouse pointer
1271 The shape of the mouse pointer when over a particular section of a frame
1272 is controlled using various glyph variables. Since the image of a glyph
1273 is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
1274 or per-device basis.
1276 You should use @code{set-glyph-image} to set the following variables,
1277 @emph{not} @code{setq}.
1279 @defvr Glyph text-pointer-glyph
1280 This variable specifies the shape of the mouse pointer when over text.
1283 @defvr Glyph nontext-pointer-glyph
1284 This variable specifies the shape of the mouse pointer when over a
1285 buffer, but not over text. If unspecified in a particular domain,
1286 @code{text-pointer-glyph} is used.
1289 @defvr Glyph modeline-pointer-glyph
1290 This variable specifies the shape of the mouse pointer when over the modeline.
1291 If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
1294 @defvr Glyph selection-pointer-glyph
1295 This variable specifies the shape of the mouse pointer when over a
1296 selectable text region. If unspecified in a particular domain,
1297 @code{text-pointer-glyph} is used.
1300 @defvr Glyph gc-pointer-glyph
1301 This variable specifies the shape of the mouse pointer when a garbage
1302 collection is in progress. If the selected window is on a window system
1303 and this glyph specifies a value (i.e. a pointer image instance) in the
1304 domain of the selected window, the pointer will be changed as specified
1305 during garbage collection. Otherwise, a message will be printed in the
1306 echo area, as controlled by @code{gc-message}.
1309 @defvr Glyph busy-pointer-glyph
1310 This variable specifies the shape of the mouse pointer when XEmacs is busy.
1311 If unspecified in a particular domain, the pointer is not changed
1312 when XEmacs is busy.
1315 @defvr Glyph menubar-pointer-glyph
1316 This variable specifies the shape of the mouse pointer when over the
1317 menubar. If unspecified in a particular domain, the
1318 window-system-provided default pointer is used.
1321 @defvr Glyph scrollbar-pointer-glyph
1322 This variable specifies the shape of the mouse pointer when over a
1323 scrollbar. If unspecified in a particular domain, the
1324 window-system-provided default pointer is used.
1327 @defvr Glyph toolbar-pointer-glyph
1328 This variable specifies the shape of the mouse pointer when over a
1329 toolbar. If unspecified in a particular domain,
1330 @code{nontext-pointer-glyph} is used.
1333 Internally, these variables are implemented in
1334 @code{default-mouse-motion-handler}, and thus only take effect when the
1335 mouse moves. That function calls @code{set-frame-pointer}, which sets
1336 the current mouse pointer for a frame.
1338 @defun set-frame-pointer frame image-instance
1339 This function sets the mouse pointer of @var{frame} to the given pointer
1340 image instance. You should not call this function directly.
1341 (If you do, the pointer will change again the next time the mouse moves.)
1344 @node Redisplay Glyphs
1345 @section Redisplay Glyphs
1347 @defvr Glyph truncation-glyph
1348 This variable specifies what is displayed at the end of truncated lines.
1351 @defvr Glyph continuation-glyph
1352 This variable specifies what is displayed at the end of wrapped lines.
1355 @defvr Glyph octal-escape-glyph
1356 This variable specifies what to prefix character codes displayed in octal
1360 @defvr Glyph hscroll-glyph
1361 This variable specifies what to display at the beginning of horizontally
1365 @defvr Glyph invisible-text-glyph
1366 This variable specifies what to use to indicate the presence of
1367 invisible text. This is the glyph that is displayed when an ellipsis is
1368 called for, according to @code{selective-display-ellipses} or
1369 @code{buffer-invisibility-spec}). Normally this is three dots (``...'').
1372 @defvr Glyph control-arrow-glyph
1373 This variable specifies what to use as an arrow for control characters.
1379 Subwindows are not currently implemented.
1381 @defun subwindowp object
1382 This function returns non-@code{nil} if @var{object} is a subwindow.
1385 @node Glyph Examples
1386 @section Glyph Examples
1388 For many applications, displaying graphics is a simple process: you
1389 create a glyph, and then you insert it into a buffer.
1391 The easiest way to create a glyph is to use a file that contains a
1392 graphical image, such as a JPEG, TIFF, or PNG file:
1395 ;; Create a glyph from a JPEG file:
1396 (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
1400 ;; Create a glyph from a XPM file:
1401 (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
1405 ;; Create a glyph from a PNG file:
1406 (setq foo (make-glyph [png :file "/tmp/file3.png"]))
1410 ;; Create a glyph from a TIFF file:
1411 (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
1414 The parameters passed to @code{make-glyph} are called "Image
1415 Specifiers", and can handle more image types than those shown above.
1416 You can also put the raw image data into a string (e.g., if you put the
1417 contents of a JPEG file into a string), and use that to create a glyph.
1418 @xref{Image Specifiers}, for more information.
1421 @strong{Caution}: In order for XEmacs to read a particular graphics file
1422 format, support for that format must have been compiled into XEmacs.
1423 It's possible, although somewhat unlikely, for XEmacs to have been
1424 compiled without support for any of the various graphics file formats.
1425 To see what graphics formats your particular version of XEmacs supports,
1426 use @kbd{M-x describe-installation}.
1428 To programmatically query whether or not a particular file format is
1429 supported, you can use the @code{featurep} function, with one of:
1430 @code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm},
1431 @code{png}, or @code{xface}. For an up-to-date list, @ref{Image
1432 Specifiers}. Example:
1435 ;; Returns `t' if TIFF is supported:
1442 ;; Returns a list of `t' or `nil', depending on whether or not the
1443 ;; corresponding feature is supported:
1444 (mapcar #'(lambda (format-symbol) (featurep format-symbol))
1445 '(gif tiff jpeg xpm png))
1450 Once you have a glyph, you can then insert it into a buffer. Example:
1453 ;; Use this function to insert a glyph at the left edge of point in the
1454 ;; current buffer. Any existing glyph at this location is replaced.
1455 (defun insert-glyph (gl)
1456 "Insert a glyph at the left edge of point."
1457 (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen
1458 ;; to (hopefully) not conflict with any
1459 ;; other properties. Change it if
1462 ;; First, check to see if one of our extents already exists at
1463 ;; point. For ease-of-programming, we are creating and using our
1464 ;; own extents (multiple extents are allowed to exist/overlap at the
1465 ;; same point, and it's quite possible for other applications to
1466 ;; embed extents in the current buffer without your knowledge).
1467 ;; Basically, if an extent, with the property stored in "prop",
1468 ;; exists at point, we assume that it is one of ours, and we re-use
1469 ;; it (this is why it is important for the property stored in "prop"
1470 ;; to be unique, and only used by us).
1471 (if (not (setq extent (extent-at (point) (current-buffer) prop)))
1473 ;; If an extent does not already exist, create a zero-length
1474 ;; extent, and give it our special property.
1475 (setq extent (make-extent (point) (point) (current-buffer)))
1476 (set-extent-property extent prop t)
1478 ;; Display the glyph by storing it as the extent's "begin-glyph".
1479 (set-extent-property extent 'begin-glyph gl)
1482 ;; You can then use this function like:
1483 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
1484 ;; This will insert the glyph at point.
1486 ;; Here's an example of how to insert two glyphs side-by-side, at point
1487 ;; (using the above code):
1489 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
1490 ;; Create a new extent at point. We can't simply call "insert-glyph",
1491 ;; as "insert-glyph" will simply replace the first glyph with the
1493 (setq extent (make-extent (point) (point) (current-buffer)))
1494 ;; Here, we're only setting the 'myimage property in case we need
1495 ;; to later identify/locate/reuse this particular extent.
1496 (set-extent-property extent 'myimage t)
1497 (set-extent-property extent 'begin-glyph
1498 (make-glyph [jpeg :file "/tmp/file2.jpg"]))
1503 Here are the gory details:
1508 Glyphs are displayed by attaching them to extents (see @ref{Extents}),
1509 either to the beginning or the end of extents.
1511 Note that extents can be used for many things, and not just for
1512 displaying images (although, in the above example, we are creating our
1513 own extent for the sole purpose of displaying an image). Also, note
1514 that multiple extents are allowed to exist at the same position, and
1518 Glyphs are often displayed inside the text area (alongside text). This
1521 Although glyphs can also be displayed in the margins, how to do this
1522 will not be described here. For more information on this, see
1523 @ref{Annotation Basics} (look for information on "layout types") and
1524 @ref{Extent Properties} (look for @code{begin-glyph-layout} and
1525 @code{end-glyph-layout}).
1528 The easiest way to insert a glyph into text is to create a zero-length
1529 extent at the point where you want the glyph to appear.
1531 Note that zero-length extents are attached to the character to the
1532 right of the extent; deleting this character will also delete the extent.
1535 It's often a good idea to assign a unique property to the newly-created
1536 extent, in case you later want to locate it, and replace any existing
1537 glyph with a different one (or just delete the existing one). In the
1538 above example, we are using "myimage" as our (hopefully) unique property
1541 If you need to locate all of the extents, you'll have to use functions
1542 like @code{extent-list} or @code{next-extent}, or provide additional
1543 parameters to the @code{extent-at} function. Assigning a unique
1544 property to the extent makes it easy to locate your extents; for
1545 example, @code{extent-list} can return only those extents with a
1546 particular property. @xref{Finding Extents}, and @ref{Mapping Over
1547 Extents}, for more information.
1550 Glyphs are displayed by assigning then to the @code{begin-glyph} or
1551 @code{end-glyph} property of the extent. For zero-length extents, it
1552 doesn't really matter if you assign the glyph to the @code{begin-glyph}
1553 or @code{end-glyph} property, as they are both at the same location;
1554 however, for non-zero-length extents (extents that cover one or more
1555 characters of text), it does matter which one you use.
1557 Assigning @code{nil} to the @code{begin-glyph} or @code{end-glyph}
1558 property will delete any existing glyph. In this case, you may also
1559 want to delete the extent, assuming that the extent is used for no other
1563 If you happen to insert two glyphs, side-by-side, note that the example
1564 @code{insert-glyph} function will have trouble, if it's again used at
1565 the same point (it can only locate one of the two extents).
1566 @xref{Finding Extents}, and @ref{Mapping Over Extents}, for more
1567 information on locating extents in a buffer.
1570 Among other things, glyphs provide a way of displaying graphics
1571 alongside text. Note, however, that glyphs only provide a way of
1572 displaying graphics; glyphs are not actually part of the text, and are
1573 only displayed alongside the text. If you save the text in the buffer,
1574 the graphics are not saved. The low-level glyph code does not provide a
1575 way of saving graphics with the text. If you need to save graphics and
1576 text, you have to write your own code to do this, and this topic is
1577 outside the scope of this discussion.