1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
58 Each glyph has a list of properties, which control all of the
59 aspects of the glyph's appearance. The following symbols have
63 The image used to display the glyph.
66 Percent above baseline that glyph is to be displayed. Only for
67 glyphs displayed inside of a buffer.
70 Whether the glyph contributes to the height of the line it's on.
71 Only for glyphs displayed inside of a buffer.
74 Face of this glyph (_not_ a specifier).
76 - Function: set-glyph-property glyph property value &optional locale
78 This function changes a property of a GLYPH.
80 For built-in properties, the actual value of the property is a
81 specifier and you cannot change this; but you can change the
82 specifications within the specifier, and that is what this
83 function will do. For user-defined properties, you can use this
84 function to either change the actual value of the property or, if
85 this value is a specifier, change the specifications within it.
87 If PROPERTY is a built-in property, the specifications to be added
88 to this property can be supplied in many different ways:
90 * If VALUE is a simple instantiator (e.g. a string naming a
91 pixmap filename) or a list of instantiators, then the
92 instantiator(s) will be added as a specification of the
93 property for the given LOCALE (which defaults to `global' if
96 * If VALUE is a list of specifications (each of which is a cons
97 of a locale and a list of instantiators), then LOCALE must be
98 `nil' (it does not make sense to explicitly specify a locale
99 in this case), and specifications will be added as given.
101 * If VALUE is a specifier (as would be returned by
102 `glyph-property' if no LOCALE argument is given), then some
103 or all of the specifications in the specifier will be added
104 to the property. In this case, the function is really
105 equivalent to `copy-specifier' and LOCALE has the same
106 semantics (if it is a particular locale, the specification
107 for the locale will be copied; if a locale type,
108 specifications for all locales of that type will be copied;
109 if `nil' or `all', then all specifications will be copied).
111 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
112 `append', `remove-tag-set-prepend', `remove-tag-set-append',
113 `remove-locale', `remove-locale-type', or `remove-all'. See
114 `copy-specifier' and `add-spec-to-specifier' for a description of
115 what each of these means. Most of the time, you do not need to
116 worry about this argument; the default behavior usually is fine.
118 In general, it is OK to pass an instance object (e.g. as returned
119 by `glyph-property-instance') as an instantiator in place of an
120 actual instantiator. In such a case, the instantiator used to
121 create that instance object will be used (for example, if you set
122 a font-instance object as the value of the `font' property, then
123 the font name used to create that object will be used instead).
124 If some cases, however, doing this conversion does not make sense,
125 and this will be noted in the documentation for particular types
128 If PROPERTY is not a built-in property, then this function will
129 simply set its value if LOCALE is `nil'. However, if LOCALE is
130 given, then this function will attempt to add VALUE as the
131 instantiator for the given LOCALE, using `add-spec-to-specifier'.
132 If the value of the property is not a specifier, it will
133 automatically be converted into a `generic' specifier.
135 - Function: glyph-property glyph property &optional locale
136 This function returns GLYPH's value of the given PROPERTY.
138 If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
139 be returned. For built-in properties, this will be a specifier
140 object of a type appropriate to the property (e.g. a font or color
141 specifier). For other properties, this could be anything.
143 If LOCALE is supplied, then instead of returning the actual value,
144 the specification(s) for the given locale or locale type will be
145 returned. This will only work if the actual value of PROPERTY is
146 a specifier (this will always be the case for built-in properties,
147 but may or may not apply to user-defined properties). If the
148 actual value of PROPERTY is not a specifier, this value will
149 simply be returned regardless of LOCALE.
151 The return value will be a list of instantiators (e.g. vectors
152 specifying pixmap data), or a list of specifications, each of
153 which is a cons of a locale and a list of instantiators.
154 Specifically, if LOCALE is a particular locale (a buffer, window,
155 frame, device, or `global'), a list of instantiators for that
156 locale will be returned. Otherwise, if LOCALE is a locale type
157 (one of the symbols `buffer', `window', `frame', or `device'), the
158 specifications for all locales of that type will be returned.
159 Finally, if LOCALE is `all', the specifications for all locales of
160 all types will be returned.
162 The specifications in a specifier determine what the value of
163 PROPERTY will be in a particular "domain" or set of circumstances,
164 which is typically a particular Emacs window along with the buffer
165 it contains and the frame and device it lies within. The value is
166 derived from the instantiator associated with the most specific
167 locale (in the order buffer, window, frame, device, and `global')
168 that matches the domain in question. In other words, given a
169 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
170 will first be searched for a specification whose locale is the
171 buffer contained within that window; then for a specification
172 whose locale is the window itself; then for a specification whose
173 locale is the frame that the window is contained within; etc. The
174 first instantiator that is valid for the domain (usually this
175 means that the instantiator is recognized by the device [i.e. the
176 X server or TTY device] that the domain is on). The function
177 `glyph-property-instance' actually does all this, and is used to
178 determine how to display the glyph.
180 - Function: glyph-property-instance glyph property &optional domain
182 This function returns the instance of GLYPH's PROPERTY in the
185 Under most circumstances, DOMAIN will be a particular window, and
186 the returned instance describes how the specified property
187 actually is displayed for that window and the particular buffer in
188 it. Note that this may not be the same as how the property
189 appears when the buffer is displayed in a different window or
190 frame, or how the property appears in the same window if you
191 switch to another buffer in that window; and in those cases, the
192 returned instance would be different.
194 The returned instance is an image-instance object, and you can
195 query it using the appropriate image instance functions. For
196 example, you could use `image-instance-depth' to find out the
197 depth (number of color planes) of a pixmap displayed in a
198 particular window. The results might be different from the
199 results you would get for another window (perhaps the user
200 specified a different image for the frame that window is on; or
201 perhaps the same image was specified but the window is on a
202 different X server, and that X server has different color
203 capabilities from this one).
205 DOMAIN defaults to the selected window if omitted.
207 DOMAIN can be a frame or device, instead of a window. The value
208 returned for such a domain is used in special circumstances when a
209 more specific domain does not apply; for example, a frame value
210 might be used for coloring a toolbar, which is conceptually
211 attached to a frame rather than a particular window. The value is
212 also useful in determining what the value would be for a
213 particular window within the frame or device, if it is not
214 overridden by a more specific specification.
216 If PROPERTY does not name a built-in property, its value will
217 simply be returned unless it is a specifier object, in which case
218 it will be instanced using `specifier-instance'.
220 Optional arguments DEFAULT and NO-FALLBACK are the same as in
221 `specifier-instance'. *Note Specifiers::.
223 - Function: remove-glyph-property glyph property &optional locale
225 This function removes a property from a glyph. For built-in
226 properties, this is analogous to `remove-specifier'. *Note
227 remove-specifier-p: Specifiers, for the meaning of the LOCALE,
228 TAG-SET, and EXACT-P arguments.
231 File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
233 Glyph Convenience Functions
234 ---------------------------
236 The following functions are provided for working with specific
237 properties of a glyph. Note that these are exactly like calling the
238 general functions described above and passing in the appropriate value
241 Remember that if you want to determine the "value" of a specific
242 glyph property, you probably want to use the `*-instance' functions.
243 For example, to determine whether a glyph contributes to its line
244 height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
245 latter will return a boolean specifier or a list of specifications, and
246 you probably aren't concerned with these.)
248 - Function: glyph-image glyph &optional locale
249 This function is equivalent to calling `glyph-property' with a
250 property of `image'. The return value will be an image specifier
251 if LOCALE is `nil' or omitted; otherwise, it will be a
252 specification or list of specifications.
254 - Function: set-glyph-image glyph spec &optional locale tag-set
256 This function is equivalent to calling `set-glyph-property' with a
259 - Function: glyph-image-instance glyph &optional domain default
261 This function returns the instance of GLYPH's image in the given
262 DOMAIN, and is equivalent to calling `glyph-property-instance'
263 with a property of `image'. The return value will be an image
266 Normally DOMAIN will be a window or `nil' (meaning the selected
267 window), and an instance object describing how the image appears
268 in that particular window and buffer will be returned.
270 - Function: glyph-contrib-p glyph &optional locale
271 This function is equivalent to calling `glyph-property' with a
272 property of `contrib-p'. The return value will be a boolean
273 specifier if LOCALE is `nil' or omitted; otherwise, it will be a
274 specification or list of specifications.
276 - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
278 This function is equivalent to calling `set-glyph-property' with a
279 property of `contrib-p'.
281 - Function: glyph-contrib-p-instance glyph &optional domain default
283 This function returns whether the glyph contributes to its line
284 height in the given DOMAIN, and is equivalent to calling
285 `glyph-property-instance' with a property of `contrib-p'. The
286 return value will be either `nil' or `t'. (Normally DOMAIN will be
287 a window or `nil', meaning the selected window.)
289 - Function: glyph-baseline glyph &optional locale
290 This function is equivalent to calling `glyph-property' with a
291 property of `baseline'. The return value will be a specifier if
292 LOCALE is `nil' or omitted; otherwise, it will be a specification
293 or list of specifications.
295 - Function: set-glyph-baseline glyph spec &optional locale tag-set
297 This function is equivalent to calling `set-glyph-property' with a
298 property of `baseline'.
300 - Function: glyph-baseline-instance glyph &optional domain default
302 This function returns the instance of GLYPH's baseline value in
303 the given DOMAIN, and is equivalent to calling
304 `glyph-property-instance' with a property of `baseline'. The
305 return value will be an integer or `nil'.
307 Normally DOMAIN will be a window or `nil' (meaning the selected
308 window), and an instance object describing the baseline value
309 appears in that particular window and buffer will be returned.
311 - Function: glyph-face glyph
312 This function returns the face of GLYPH. (Remember, this is not a
313 specifier, but a simple property.)
315 - Function: set-glyph-face glyph face
316 This function changes the face of GLYPH to FACE.
319 File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
324 - Function: glyph-width glyph &optional window
325 This function returns the width of GLYPH on WINDOW. This may not
326 be exact as it does not take into account all of the context that
329 - Function: glyph-ascent glyph &optional window
330 This function returns the ascent value of GLYPH on WINDOW. This
331 may not be exact as it does not take into account all of the
332 context that redisplay will.
334 - Function: glyph-descent glyph &optional window
335 This function returns the descent value of GLYPH on WINDOW. This
336 may not be exact as it does not take into account all of the
337 context that redisplay will.
339 - Function: glyph-height glyph &optional window
340 This function returns the height of GLYPH on WINDOW. (This is
341 equivalent to the sum of the ascent and descent values.) This may
342 not be exact as it does not take into account all of the context
346 File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
353 * Image Specifiers:: Specifying how an image will appear.
354 * Image Instantiator Conversion::
355 Conversion is applied to image instantiators
356 at the time they are added to an
357 image specifier or at the time they
358 are passed to `make-image-instance'.
359 * Image Instances:: What an image specifier gets instanced as.
362 File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
367 An image specifier is used to describe the actual image of a glyph.
368 It works like other specifiers (*note Specifiers::), in that it contains
369 a number of specifications describing how the image should appear in a
370 variety of circumstances. These specifications are called "image
371 instantiators". When XEmacs wants to display the image, it instantiates
372 the image into an "image instance". Image instances are their own
373 primitive object type (similar to font instances and color instances),
374 describing how the image appears in a particular domain. (On the other
375 hand, image instantiators, which are just descriptions of how the image
376 should appear, are represented using strings or vectors.)
378 - Function: image-specifier-p object
379 This function returns non-`nil' if OBJECT is an image specifier.
380 Usually, an image specifier results from calling `glyph-image' on
383 - Function: make-image-specifier spec-list
384 This function creates a new image specifier object and initializes
385 it according to SPEC-LIST. *Note Specifiers::.
387 Note that, in practice, you rarely, if ever, need to actually
388 create an image specifier! (This function exists mainly for
389 completeness.) Pretty much the only use for image specifiers is to
390 control how glyphs are displayed, and the image specifier
391 associated with a glyph (the `image' property of a glyph) is
392 created automatically when a glyph is created and need not (and
393 cannot, for that matter) ever be changed (*note Glyphs::). In
394 fact, the design decision to create a separate image specifier
395 type, rather than make glyphs themselves be specifiers, is
396 debatable--the other properties of glyphs are rarely used and could
397 conceivably have been incorporated into the glyph's instantiator.
398 The rarely used glyph types (buffer, pointer, icon) could also
399 have been incorporated into the instantiator.
401 Image instantiators come in many formats: `xbm', `xpm', `gif',
402 `jpeg', etc. This describes the format of the data describing the
403 image. The resulting image instances also come in many
404 types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This
405 refers to the behavior of the image and the sorts of places it can
406 appear. (For example, a color-pixmap image has fixed colors specified
407 for it, while a mono-pixmap image comes in two unspecified shades
408 "foreground" and "background" that are determined from the face of the
409 glyph or surrounding text; a text image appears as a string of text and
410 has an unspecified foreground, background, and font; a pointer image
411 behaves like a mono-pixmap image but can only be used as a mouse
412 pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
413 is important to keep the distinction between image instantiator format
414 and image instance type in mind. Typically, a given image instantiator
415 format can result in many different image instance types (for example,
416 `xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
417 whereas `cursor-font' can be instanced only as `pointer'), and a
418 particular image instance type can be generated by many different image
419 instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
420 `gif', `jpeg', etc.).
422 *Note Image Instances::, for a more detailed discussion of image
425 An image instantiator should be a string or a vector of the form
427 `[FORMAT :KEYWORD VALUE ...]'
429 i.e. a format symbol followed by zero or more alternating
430 keyword-value pairs. The "format" field should be a symbol, one of
433 Don't display anything; no keywords are valid for this. Can only
434 be instanced as `nothing'.
437 Display this image as a text string. Can only be instanced as
438 `text', although support for instancing as `mono-pixmap' should be
442 Display this image as a text string with replaceable fields,
443 similar to a modeline format string; not currently implemented.
446 An X bitmap; only if X support was compiled into this XEmacs. Can
447 be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
450 An XPM pixmap; only if XPM support was compiled into this XEmacs.
451 Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
452 XPM is an add-on library for X that was designed to rectify the
453 shortcomings of the XBM format. Most implementations of X include
454 the XPM library as a standard part. If your vendor does not, it
455 is highly recommended that you download it and install it. You
456 can get it from the standard XEmacs FTP site, among other places.
459 An X-Face bitmap, used to encode people's faces in e-mail messages;
460 only if X-Face support was compiled into this XEmacs. Can be
461 instanced as `mono-pixmap', `color-pixmap', or `pointer'.
464 A GIF87 or GIF89 image; only if GIF support was compiled into this
465 XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
466 includes GIF decoding functions as a standard part of it, so if
467 you have X support, you will normally have GIF support, unless you
468 explicitly disable it at configure time.
471 A JPEG-format image; only if JPEG support was compiled into this
472 XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
473 libraries present on your system when XEmacs is built, XEmacs will
474 automatically detect this and use them, unless you explicitly
475 disable it at configure time.
478 A PNG/GIF24 image; only if PNG support was compiled into this
479 XEmacs. Can be instanced as `color-pixmap'.
482 A TIFF-format image; only if TIFF support was compiled into this
486 One of the standard cursor-font names, such as `watch' or
487 `right_ptr' under X. Under X, this is, more specifically, any of
488 the standard cursor names from appendix B of the Xlib manual [also
489 known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
490 other window systems, the valid names will be specific to the type
491 of window system. Can only be instanced as `pointer'.
494 A glyph from a font; i.e. the name of a font, and glyph index into
495 it of the form `FONT fontname index [[mask-font] mask-index]'.
496 Only if X support was compiled into this XEmacs. Currently can
497 only be instanced as `pointer', although this should probably be
501 An MS Windows pointer resource. Specifies a resource to retrieve
502 directly from the system (an OEM resource) or from a file,
503 particularly an executable file. If the resource is to be
504 retrieved from a file, use :file and optionally :resource-id.
505 Otherwise use :resource-id. Always specify :resource-type to
506 specify the type (cursor, bitmap or icon) of the resource.
507 Possible values for :resource-id are listed below. Can be
508 instanced as `pointer' or `color-pixmap'.
511 An embedded windowing system window. Can only be instanced as
515 A button widget; either a push button, radio button or toggle
516 button. Can only be instanced as `widget'.
519 A drop list of selectable items in a widget, for editing text.
520 Can only be instanced as `widget'.
523 A text editing widget. Can only be instanced as `widget'.
526 A static, text-only, widget; for displaying text. Can only be
527 instanced as `widget'.
530 A widget for controlling the positioning of children underneath it.
531 Through the use of nested layouts, a widget hierarchy can be
532 created which can have the appearance of any standard dialog box
533 or similar arrangement; all of this is counted as one "glyph" and
534 could appear in many of the places that expect a single glyph.
535 Can only be instanced as `widget'.
538 The native version of a layout widget. Can only be instanced as
542 A sliding widget, for showing progress. Can only be instanced as
546 A tab widget; a series of user selectable tabs. Can only be
547 instanced as `widget'.
550 A folding widget. Can only be instanced as `widget'.
553 A scrollbar widget. Can only be instanced as `widget'.
556 XEmacs tries to guess what format the data is in. If X support
557 exists, the data string will be checked to see if it names a
558 filename. If so, and this filename contains XBM or XPM data, the
559 appropriate sort of pixmap or pointer will be created. [This
560 includes picking up any specified hotspot or associated mask
561 file.] Otherwise, if `pointer' is one of the allowable
562 image-instance types and the string names a valid cursor-font
563 name, the image will be created as a pointer. Otherwise, the
564 image will be displayed as text. If no X support exists, the
565 image will always be displayed as text.
568 Inherit from the background-pixmap property of a face. Can only be
569 instanced as `mono-pixmap'.
571 The valid keywords are:
574 Inline data. For most formats above, this should be a string. For
575 XBM images, this should be a list of three elements: width,
576 height, and a string of bit data. This keyword is not valid for
577 instantiator format `nothing'.
580 Data is contained in a file. The value is the name of this file.
581 If both `:data' and `:file' are specified, the image is created
582 from what is specified in `:data' and the string in `:file'
583 becomes the value of the `image-instance-file-name' function when
584 applied to the resulting image-instance. This keyword is not
585 valid for instantiator formats `nothing', `string',
586 `formatted-string', `cursor-font', `font', and `autodetect'.
590 For `xbm', `xface', `cursor-font', and `font'. These keywords
591 allow you to explicitly specify foreground and background colors.
592 The argument should be anything acceptable to
593 `make-color-instance'. This will cause what would be a
594 `mono-pixmap' to instead be colorized as a two-color color-pixmap,
595 and specifies the foreground and/or background colors for a pointer
596 instead of black and white.
599 For `xbm' and `xface'. This specifies a mask to be used with the
600 bitmap. The format is a list of width, height, and bits, like for
604 For `xbm' and `xface'. This specifies a file containing the mask
605 data. If neither a mask file nor inline mask data is given for an
606 XBM image, and the XBM image comes from a file, XEmacs will look
607 for a mask file with the same name as the image file but with
608 `Mask' or `msk' appended. For example, if you specify the XBM file
609 `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
610 associated mask file `left_ptrmsk' will automatically be picked up.
614 For `xbm' and `xface'. These keywords specify a hotspot if the
615 image is instantiated as a `pointer'. Note that if the XBM image
616 file specifies a hotspot, it will automatically be picked up if no
617 explicit hotspot is given.
620 Only for `xpm'. This specifies an alist that maps strings that
621 specify symbolic color names to the actual color to be used for
622 that symbolic color (in the form of a string or a color-specifier
623 object). If this is not specified, the contents of
624 `xpm-color-symbols' are used to generate the alist.
627 Only for `mswindows-resource'. This must be either an integer
628 (which directly specifies a resource number) or a string. Valid
633 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce",
634 "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd",
635 "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo",
636 "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize",
637 "check", "checkboxes", and "btncorners".
641 "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw",
642 "sizewe", "sizens", "sizeall", and "no".
646 "sample", "hand", "ques", "bang", "note", and "winlogo".
649 Only for `mswindows-resource'. This must be a symbol, either
650 `cursor', `icon', or `bitmap', specifying the type of resource to
654 Only for `inherit'. This specifies the face to inherit from. For
655 widgets this also specifies the face to use for display. It
656 defaults to gui-element-face.
658 Keywords accepted as menu item specs are also accepted by widgets.
659 These are `:selected', `:active', `:suffix', `:keys', `:style',
660 `:filter', `:config', `:included', `:key-sequence', `:accelerator',
661 `:label' and `:callback'.
663 If instead of a vector, the instantiator is a string, it will be
664 converted into a vector by looking it up according to the specs in the
665 `console-type-image-conversion-list' for the console type of the domain
666 (usually a window; sometimes a frame or device) over which the image is
669 If the instantiator specifies data from a file, the data will be
670 read in at the time that the instantiator is added to the image
671 specifier (which may be well before the image is actually displayed),
672 and the instantiator will be converted into one of the inline-data
673 forms, with the filename retained using a `:file' keyword. This
674 implies that the file must exist when the instantiator is added to the
675 image, but does not need to exist at any other time (e.g. it may safely
676 be a temporary file).
678 - Function: valid-image-instantiator-format-p format &optional locale
679 This function returns non-`nil' if FORMAT is a valid image
682 If LOCALE is non-`nil' then the format is checked in that locale.
683 If LOCALE is `nil' the current console is used.
685 Note that the return value for many formats listed above depends on
686 whether XEmacs was compiled with support for that format.
688 - Function: image-instantiator-format-list
689 This function return a list of valid image-instantiator formats.
691 - Variable: xpm-color-symbols
692 This variable holds definitions of logical color-names used when
693 reading XPM files. Elements of this list should be of the form
694 `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
695 string, which is the name of the color to define; the
696 FORM-TO-EVALUATE should evaluate to a color specifier object, or a
697 string to be passed to `make-color-instance' (*note Colors::). If
698 a loaded XPM file references a symbolic color called COLOR-NAME,
699 it will display as the computed color instead.
701 The default value of this variable defines the logical color names
702 `"foreground"' and `"background"' to be the colors of the
705 - Variable: x-bitmap-file-path
706 A list of the directories in which X bitmap files may be found.
707 If `nil', this is initialized from the `"*bitmapFilePath"'
708 resource. This is used by the `make-image-instance' function
709 (however, note that if the environment variable `XBMLANGPATH' is
710 set, it is consulted first).
713 File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
715 Image Instantiator Conversion
716 -----------------------------
718 - Function: set-console-type-image-conversion-list console-type list
719 This function sets the image-conversion-list for consoles of the
720 given CONSOLE-TYPE. The image-conversion-list specifies how image
721 instantiators that are strings should be interpreted. Each
722 element of the list should be a list of two elements (a regular
723 expression string and a vector) or a list of three elements (the
724 preceding two plus an integer index into the vector). The string
725 is converted to the vector associated with the first matching
726 regular expression. If a vector index is specified, the string
727 itself is substituted into that position in the vector.
729 Note: The conversion above is applied when the image instantiator
730 is added to an image specifier, not when the specifier is actually
731 instantiated. Therefore, changing the image-conversion-list only
732 affects newly-added instantiators. Existing instantiators in
733 glyphs and image specifiers will not be affected.
735 - Function: console-type-image-conversion-list console-type
736 This function returns the image-conversion-list for consoles of
737 the given CONSOLE-TYPE.
740 File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
745 Image-instance objects encapsulate the way a particular image
746 (pixmap, etc.) is displayed on a particular device.
748 In most circumstances, you do not need to directly create image
749 instances; use a glyph instead. However, it may occasionally be useful
750 to explicitly create image instances, if you want more control over the
751 instantiation process.
753 - Function: image-instance-p object
754 This function returns non-`nil' if OBJECT is an image instance.
758 * Image Instance Types:: Each image instances has a particular type.
759 * Image Instance Functions:: Functions for working with image instances.
762 File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
767 Image instances come in a number of different types. The type of an
768 image instance specifies the nature of the image: Whether it is a text
769 string, a mono pixmap, a color pixmap, etc.
771 The valid image instance types are
774 Nothing is displayed.
777 Displayed as text. The foreground and background colors and the
778 font of the text are specified independent of the pixmap.
779 Typically these attributes will come from the face of the
780 surrounding text, unless a face is specified for the glyph in
781 which the image appears.
784 Displayed as a mono pixmap (a pixmap with only two colors where the
785 foreground and background can be specified independent of the
786 pixmap; typically the pixmap assumes the foreground and background
787 colors of the text around it, unless a face is specified for the
788 glyph in which the image appears).
791 Displayed as a color pixmap.
794 Used as the mouse pointer for a window.
797 A child window that is treated as an image. This allows (e.g.)
798 another program to be responsible for drawing into the window.
799 Not currently implemented.
801 - Function: valid-image-instance-type-p type
802 This function returns non-`nil' if TYPE is a valid image instance
805 - Function: image-instance-type-list
806 This function returns a list of the valid image instance types.
808 - Function: image-instance-type image-instance
809 This function returns the type of the given image instance. The
810 return value will be one of `nothing', `text', `mono-pixmap',
811 `color-pixmap', `pointer', or `subwindow'.
813 - Function: text-image-instance-p object
814 This function returns non-`nil' if OBJECT is an image instance of
817 - Function: mono-pixmap-image-instance-p object
818 This function returns non-`nil' if OBJECT is an image instance of
821 - Function: color-pixmap-image-instance-p object
822 This function returns non-`nil' if OBJECT is an image instance of
825 - Function: pointer-image-instance-p object
826 This function returns non-`nil' if OBJECT is an image instance of
829 - Function: subwindow-image-instance-p object
830 This function returns non-`nil' if OBJECT is an image instance of
833 - Function: nothing-image-instance-p object
834 This function returns non-`nil' if OBJECT is an image instance of
837 - Function: widget-image-instance-p object
838 Return `t' if OBJECT is an image instance of type `widget'.
841 File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
843 Image Instance Functions
844 ........................
846 - Function: make-image-instance data &optional domain dest-types
848 This function creates a new image-instance object.
850 DATA is an image instantiator, which describes the image (*note
853 DEST-TYPES should be a list of allowed image instance types that
854 can be generated. The DEST-TYPES list is unordered. If multiple
855 destination types are possible for a given instantiator, the "most
856 natural" type for the instantiator's format is chosen. (For XBM,
857 the most natural types are `mono-pixmap', followed by
858 `color-pixmap', followed by `pointer'. For the other normal image
859 formats, the most natural types are `color-pixmap', followed by
860 `mono-pixmap', followed by `pointer'. For the string and
861 formatted-string formats, the most natural types are `text',
862 followed by `mono-pixmap' (not currently implemented), followed by
863 `color-pixmap' (not currently implemented). For MS Windows
864 resources, the most natural type for pointer resources is
865 `pointer', and for the others it's `color-pixmap'. The other
866 formats can only be instantiated as one type. (If you want to
867 control more specifically the order of the types into which an
868 image is instantiated, just call `make-image-instance' repeatedly
869 until it succeeds, passing less and less preferred destination
872 If DEST-TYPES is omitted, all possible types are allowed.
874 DOMAIN specifies the domain to which the image instance will be
875 attached. This domain is termed the "governing domain". The type
876 of the governing domain depends on the image instantiator format.
877 (Although, more correctly, it should probably depend on the image
878 instance type.) For example, pixmap image instances are specific
879 to a device, but widget image instances are specific to a
880 particular XEmacs window because in order to display such a widget
881 when two windows onto the same buffer want to display the widget,
882 two separate underlying widgets must be created. (That's because a
883 widget is actually a child window-system window, and all
884 window-system windows have a unique existence on the screen.) This
885 means that the governing domain for a pixmap image instance will
886 be some device (most likely, the only existing device), whereas
887 the governing domain for a widget image instance will be some
890 If you specify an overly general DOMAIN (e.g. a frame when a
891 window was wanted), an error is signaled. If you specify an overly
892 specific DOMAIN (e.g. a window when a device was wanted), the
893 corresponding general domain is fetched and used instead. For
894 `make-image-instance', it makes no difference whether you specify
895 an overly specific domain or the properly general domain derived
896 from it. However, it does matter when creating an image instance
897 by instantiating a specifier or glyph (e.g. with
898 `glyph-image-instance'), because the more specific domain causes
899 spec lookup to start there and proceed to more general domains. (It
900 would also matter when creating an image instance with an
901 instantiator format of `inherit', but we currently disallow this.
902 #### We should fix this.) n If omitted, DOMAIN defaults to the
905 NOERROR controls what happens when the image cannot be generated.
906 If `nil', an error message is generated. If `t', no messages are
907 generated and this function returns `nil'. If anything else, a
908 warning message is generated and this function returns `nil'.
910 - Function: colorize-image-instance image-instance foreground
912 This function makes the image instance be displayed in the given
913 colors. Image instances come in two varieties: bitmaps, which are
914 1 bit deep which are rendered in the prevailing foreground and
915 background colors; and pixmaps, which are of arbitrary depth
916 (including 1) and which have the colors explicitly specified.
917 This function converts a bitmap to a pixmap. If the image
918 instance was a pixmap already, nothing is done (and `nil' is
919 returned). Otherwise `t' is returned.
921 - Function: image-instance-name image-instance
922 This function returns the name of the given image instance.
924 - Function: image-instance-domain image-instance
925 Return the governing domain of the given IMAGE-INSTANCE. The
926 governing domain of an image instance is the domain that the image
927 instance is specific to. It is _NOT_ necessarily the domain that
928 was given to the call to `specifier-instance' that resulted in the
929 creation of this image instance. See `make-image-instance' for
930 more information on governing domains.
932 - Function: image-instance-string image-instance
933 This function returns the string of the given image instance.
934 This will only be non-`nil' for text image instances.
936 - Function: image-instance-file-name image-instance
937 This function returns the file name from which IMAGE-INSTANCE was
940 - Function: image-instance-mask-file-name image-instance
941 This function returns the file name from which IMAGE-INSTANCE's
942 mask was read, if known.
944 - Function: image-instance-depth image-instance
945 This function returns the depth of the image instance. This is 0
946 for a mono pixmap, or a positive integer for a color pixmap.
948 - Function: image-instance-height image-instance
949 This function returns the height of the image instance, in pixels.
951 - Function: image-instance-width image-instance
952 This function returns the width of the image instance, in pixels.
954 - Function: image-instance-hotspot-x image-instance
955 This function returns the X coordinate of the image instance's
956 hotspot, if known. This is a point relative to the origin of the
957 pixmap. When an image is used as a mouse pointer, the hotspot is
958 the point on the image that sits over the location that the
959 pointer points to. This is, for example, the tip of the arrow or
960 the center of the crosshairs.
962 This will always be `nil' for a non-pointer image instance.
964 - Function: image-instance-hotspot-y image-instance
965 This function returns the Y coordinate of the image instance's
968 - Function: image-instance-foreground image-instance
969 This function returns the foreground color of IMAGE-INSTANCE, if
970 applicable. This will be a color instance or `nil'. (It will only
971 be non-`nil' for colorized mono pixmaps and for pointers.)
973 - Function: image-instance-background image-instance
974 This function returns the background color of IMAGE-INSTANCE, if
975 applicable. This will be a color instance or `nil'. (It will only
976 be non-`nil' for colorized mono pixmaps and for pointers.)
979 File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
984 Each glyph has a particular type, which controls how the glyph's
985 image is generated. Each glyph type has a corresponding list of
986 allowable image instance types that can be generated. When you call
987 `glyph-image-instance' to retrieve the image instance of a glyph,
988 XEmacs does the equivalent of calling `make-image-instance' and passing
989 in DEST-TYPES the list of allowable image instance types for the
992 * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
993 extent, in the modeline, and in the toolbar. Their image can be
994 instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
997 * `pointer' glyphs can be used to specify the mouse pointer. Their
998 image can be instantiated as `pointer'.
1000 * `icon' glyphs can be used to specify the icon used when a frame is
1001 iconified. Their image can be instantiated as `mono-pixmap' and
1004 - Function: glyph-type glyph
1005 This function returns the type of the given glyph. The return
1006 value will be a symbol, one of `buffer', `pointer', or `icon'.
1008 - Function: valid-glyph-type-p glyph-type
1009 Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
1011 - Function: glyph-type-list
1012 This function returns a list of valid glyph types.
1014 - Function: buffer-glyph-p object
1015 This function returns non-`nil' if OBJECT is a glyph of type
1018 - Function: icon-glyph-p object
1019 This function returns non-`nil' if OBJECT is a glyph of type
1022 - Function: pointer-glyph-p object
1023 This function returns non-`nil' if OBJECT is a glyph of type
1027 File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
1032 The shape of the mouse pointer when over a particular section of a
1033 frame is controlled using various glyph variables. Since the image of
1034 a glyph is a specifier, it can be controlled on a per-buffer,
1035 per-frame, per-window, or per-device basis.
1037 You should use `set-glyph-image' to set the following variables,
1040 - Glyph: text-pointer-glyph
1041 This variable specifies the shape of the mouse pointer when over
1044 - Glyph: nontext-pointer-glyph
1045 This variable specifies the shape of the mouse pointer when over a
1046 buffer, but not over text. If unspecified in a particular domain,
1047 `text-pointer-glyph' is used.
1049 - Glyph: modeline-pointer-glyph
1050 This variable specifies the shape of the mouse pointer when over
1051 the modeline. If unspecified in a particular domain,
1052 `nontext-pointer-glyph' is used.
1054 - Glyph: selection-pointer-glyph
1055 This variable specifies the shape of the mouse pointer when over a
1056 selectable text region. If unspecified in a particular domain,
1057 `text-pointer-glyph' is used.
1059 - Glyph: gc-pointer-glyph
1060 This variable specifies the shape of the mouse pointer when a
1061 garbage collection is in progress. If the selected window is on a
1062 window system and this glyph specifies a value (i.e. a pointer
1063 image instance) in the domain of the selected window, the pointer
1064 will be changed as specified during garbage collection.
1065 Otherwise, a message will be printed in the echo area, as
1066 controlled by `gc-message'.
1068 - Glyph: busy-pointer-glyph
1069 This variable specifies the shape of the mouse pointer when XEmacs
1070 is busy. If unspecified in a particular domain, the pointer is
1071 not changed when XEmacs is busy.
1073 - Glyph: menubar-pointer-glyph
1074 This variable specifies the shape of the mouse pointer when over
1075 the menubar. If unspecified in a particular domain, the
1076 window-system-provided default pointer is used.
1078 - Glyph: scrollbar-pointer-glyph
1079 This variable specifies the shape of the mouse pointer when over a
1080 scrollbar. If unspecified in a particular domain, the
1081 window-system-provided default pointer is used.
1083 - Glyph: toolbar-pointer-glyph
1084 This variable specifies the shape of the mouse pointer when over a
1085 toolbar. If unspecified in a particular domain,
1086 `nontext-pointer-glyph' is used.
1088 Internally, these variables are implemented in
1089 `default-mouse-motion-handler', and thus only take effect when the
1090 mouse moves. That function calls `set-frame-pointer', which sets the
1091 current mouse pointer for a frame.
1093 - Function: set-frame-pointer frame image-instance
1094 This function sets the mouse pointer of FRAME to the given pointer
1095 image instance. You should not call this function directly. (If
1096 you do, the pointer will change again the next time the mouse
1100 File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
1105 - Glyph: truncation-glyph
1106 This variable specifies what is displayed at the end of truncated
1109 - Glyph: continuation-glyph
1110 This variable specifies what is displayed at the end of wrapped
1113 - Glyph: octal-escape-glyph
1114 This variable specifies what to prefix character codes displayed
1117 - Glyph: hscroll-glyph
1118 This variable specifies what to display at the beginning of
1119 horizontally scrolled lines.
1121 - Glyph: invisible-text-glyph
1122 This variable specifies what to use to indicate the presence of
1123 invisible text. This is the glyph that is displayed when an
1124 ellipsis is called for, according to `selective-display-ellipses'
1125 or `buffer-invisibility-spec'). Normally this is three dots
1128 - Glyph: control-arrow-glyph
1129 This variable specifies what to use as an arrow for control
1133 File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
1138 Subwindows are not currently implemented.
1140 - Function: subwindowp object
1141 This function returns non-`nil' if OBJECT is a subwindow.
1144 File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
1149 An "annotation" is a pixmap or string that is not part of a buffer's
1150 text but is displayed next to a particular location in a buffer.
1151 Annotations can be displayed intermixed with text, in any whitespace at
1152 the beginning or end of a line, or in a special area at the left or
1153 right side of the frame called a "margin", whose size is controllable.
1154 Annotations are implemented using extents (*note Extents::); but you
1155 can work with annotations without knowing how extents work.
1159 * Annotation Basics:: Introduction to annotations.
1160 * Annotation Primitives:: Creating and deleting annotations.
1161 * Annotation Properties:: Retrieving and changing the characteristics
1163 * Margin Primitives:: Controlling the size of the margins.
1164 * Locating Annotations:: Looking for annotations in a buffer.
1165 * Annotation Hooks:: Hooks called at certain times during an
1166 annotation's lifetime.