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: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
55 Font Instance Characteristics
56 -----------------------------
58 - Function: font-instance-properties font
59 This function returns the properties (an alist or `nil') of
62 - Function: x-make-font-bold font &optional device
63 Given an X font specification, this attempts to make a "bold" font.
64 If it fails, it returns `nil'.
66 - Function: x-make-font-unbold font &optional device
67 Given an X font specification, this attempts to make a non-bold
68 font. If it fails, it returns `nil'.
70 - Function: x-make-font-italic font &optional device
71 Given an X font specification, this attempts to make an "italic"
72 font. If it fails, it returns `nil'.
74 - Function: x-make-font-unitalic font &optional device
75 Given an X font specification, this attempts to make a non-italic
76 font. If it fails, it returns `nil'.
78 - Function: x-make-font-bold-italic font &optional device
79 Given an X font specification, this attempts to make a
80 "bold-italic" font. If it fails, it returns `nil'.
83 File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
85 Font Convenience Functions
86 --------------------------
88 - Function: font-name font &optional domain
89 This function returns the name of the FONT in the specified
90 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
91 is normally a window and defaults to the selected window if
92 omitted. This is equivalent to using `specifier-instance' and
93 applying `font-instance-name' to the result.
95 - Function: font-truename font &optional domain
96 This function returns the truename of the FONT in the specified
97 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
98 is normally a window and defaults to the selected window if
99 omitted. This is equivalent to using `specifier-instance' and
100 applying `font-instance-truename' to the result.
102 - Function: font-properties font &optional domain
103 This function returns the properties of the FONT in the specified
104 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
105 is normally a window and defaults to the selected window if
106 omitted. This is equivalent to using `specifier-instance' and
107 applying `font-instance-properties' to the result.
110 File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
117 * Color Specifiers:: Specifying how a color will appear.
118 * Color Instances:: What a color specifier gets instanced as.
119 * Color Instance Properties:: Properties of color instances.
120 * Color Convenience Functions:: Convenience functions that automatically
121 instance and retrieve the properties
122 of a color specifier.
125 File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
130 - Function: color-specifier-p object
131 This function returns non-`nil' if OBJECT is a color specifier.
133 - Function: make-color-specifier spec-list
134 Return a new `color' specifier object with the given specification
135 list. SPEC-LIST can be a list of specifications (each of which is
136 a cons of a locale and a list of instantiators), a single
137 instantiator, or a list of instantiators. *Note Specifiers::, for
138 a detailed description of how specifiers work.
140 Valid instantiators for color specifiers are:
142 * A string naming a color (e.g. under X this might be
143 "lightseagreen2" or "#F534B2").
145 * A color instance (use that instance directly if the device
146 matches, or use the string that generated it).
148 * A vector of no elements (only on TTY's; this means to set no
149 color at all, thus using the "natural" color of the
152 * A vector of one or two elements: a face to inherit from, and
153 optionally a symbol naming which property of that face to
154 inherit, either `foreground' or `background' (if omitted,
155 defaults to the same property that this color specifier is
156 used for; if this specifier is not part of a face, the
157 instantiator would not be valid).
159 - Function: make-face-boolean-specifier spec-list
160 Return a new `face-boolean' specifier object with the given spec
161 list. SPEC-LIST can be a list of specifications (each of which is
162 a cons of a locale and a list of instantiators), a single
163 instantiator, or a list of instantiators. *Note Specifiers::, for
164 a detailed description of how specifiers work.
166 Valid instantiators for face-boolean specifiers are
170 * A vector of two or three elements: a face to inherit from,
171 optionally a symbol naming the property of that face to
172 inherit from (if omitted, defaults to the same property that
173 this face-boolean specifier is used for; if this specifier is
174 not part of a face, the instantiator would not be valid), and
175 optionally a value which, if non-nil, means to invert the
176 sense of the inherited property.
180 File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
185 A "color-instance object" is an object describing the way a color
186 specifier is instanced in a particular domain. Functions such as
187 `face-background-instance' return a color-instance object. For example,
189 (face-background-instance 'default (next-window))
190 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
192 The color-instance object returned describes the way the background
193 color of the `default' face is displayed in the next window after the
196 - Function: color-instance-p object
197 This function returns non-`nil' if OBJECT is a color-instance.
200 File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
202 Color Instance Properties
203 -------------------------
205 - Function: color-instance-name color-instance
206 This function returns the name used to allocate COLOR-INSTANCE.
208 - Function: color-instance-rgb-components color-instance
209 This function returns a three element list containing the red,
210 green, and blue color components of COLOR-INSTANCE.
212 (color-instance-rgb-components
213 (face-background-instance 'default (next-window)))
214 => (65535 58596 46517)
217 File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
219 Color Convenience Functions
220 ---------------------------
222 - Function: color-name color &optional domain
223 This function returns the name of the COLOR in the specified
224 DOMAIN, if any. COLOR should be a color specifier object and
225 DOMAIN is normally a window and defaults to the selected window if
226 omitted. This is equivalent to using `specifier-instance' and
227 applying `color-instance-name' to the result.
229 - Function: color-rgb-components color &optional domain
230 This function returns the RGB components of the COLOR in the
231 specified DOMAIN, if any. COLOR should be a color specifier
232 object and DOMAIN is normally a window and defaults to the
233 selected window if omitted. This is equivalent to using
234 `specifier-instance' and applying `color-instance-rgb-components'
237 (color-rgb-components (face-background 'default (next-window)))
238 => (65535 58596 46517)
241 File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
246 A "glyph" is an object that is used for pixmaps, widgets and images
247 of all sorts, as well as for things that "act" like pixmaps, such as
248 non-textual strings ("annotations") displayed in a buffer or in the
249 margins. It is used in begin-glyphs and end-glyphs attached to
250 extents, marginal and textual annotations, overlay arrows
251 (`overlay-arrow-*' variables), toolbar buttons, mouse pointers, frame
252 icons, truncation and continuation markers, and the like. (Basically,
253 any place there is an image or something that acts like an image, there
254 will be a glyph object representing it.)
256 The actual image that is displayed (as opposed to its position or
257 clipping) is defined by an "image specifier" object contained within
258 the glyph. The separation between an image specifier object and a
259 glyph object is made because the glyph includes other properties than
260 just the actual image: e.g. the face it is displayed in (for text
261 images), the alignment of the image (when it is in a buffer), etc.
263 - Function: glyphp object
264 This function returns `t' if OBJECT is a glyph.
268 * Glyph Functions:: Functions for working with glyphs.
269 * Images:: Graphical images displayed in a frame.
270 * Glyph Types:: Each glyph has a particular type.
271 * Mouse Pointer:: Controlling the mouse pointer.
272 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
273 * Subwindows:: Inserting an externally-controlled subwindow
277 File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
284 * Creating Glyphs:: Creating new glyphs.
285 * Glyph Properties:: Accessing and modifying a glyph's properties.
286 * Glyph Convenience Functions::
287 Convenience functions for accessing particular
288 properties of a glyph.
289 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
292 File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
297 - Function: make-glyph &optional spec-list type
298 This function creates a new glyph object of type TYPE.
300 SPEC-LIST is used to initialize the glyph's image. It is
301 typically an image instantiator (a string or a vector; *Note Image
302 Specifiers::), but can also be a list of such instantiators (each
303 one in turn is tried until an image is successfully produced), a
304 cons of a locale (frame, buffer, etc.) and an instantiator, a list
305 of such conses, or any other form accepted by
306 `canonicalize-spec-list'. *Note Specifiers::, for more
307 information about specifiers.
309 TYPE specifies the type of the glyph, which specifies in which
310 contexts the glyph can be used, and controls the allowable image
311 types into which the glyph's image can be instantiated. TYPE
312 should be one of `buffer' (used for glyphs in an extent, the
313 modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
314 for the mouse-pointer), or `icon' (used for a frame's icon), and
315 defaults to `buffer'. *Note Glyph Types::.
317 A glyph in XEmacs does *NOT* refer to a single unit of textual
318 display (the XEmacs term for this is "rune"), but rather is an
319 object encapsulating a graphical element, such as an image or
320 widget (an element such as a button or text field; "widget" is the
321 term for this under X Windows, and it's called a "control" under
322 MS Windows). This graphical element could appear in a buffer, a
323 margin, a gutter, or a toolbar, or as a mouse pointer or an icon,
326 Creating a glyph using `make-glyph' does not specify _where_ the
327 glyph will be used, but it does specify _what_ the glyph will look
328 like. In particular, SPEC-LIST is used to specify this, and it's
329 used to initialize the glyph's `image' property, which is an image
330 specifier. (Note that "image" as used in the context of a glyph's
331 `image' property or in the terms "image specifier", "image
332 instantiator", or "image instance" does not refer to what people
333 normally think of as an image (which in XEmacs is called a
334 "pixmap"), but to any graphical element--a pixmap, a widget, or
335 even a block of text, when used in the places that call for a
336 glyph.) The format of the SPEC-LIST is typically an image
337 instantiator (a string or a vector; *Note Image Specifiers::), but
338 can also be a list of such instantiators (each one in turn is
339 tried until an image is successfully produced), a cons of a locale
340 (frame, buffer, etc.) and an instantiator, a list of such conses,
341 or any other form accepted by `canonicalize-spec-list'. *Note
342 Specifiers::, for more information about specifiers.
344 If you're not familiar with specifiers, you should be in order to
345 understand how glyphs work. The clearest introduction to
346 specifiers is in the Lispref manual, available under Info. (Choose
347 Help->Info->Info Contents on the menubar or type C-h i.) You can
348 also see `make-specifier' for a capsule summary. What's important
349 to keep in mind is that a specifier lets you set a different value
350 for any particular buffer, window, frame, device, or console.
351 This allows for a great deal of flexibility; in particular, only
352 one global glyph needs to exist for a particular purpose (e.g. the
353 icon used to represent an iconified frame, the mouse pointer used
354 over particular areas of a frame, etc.), and in these cases you do
355 not create your own glyph, but rather modify the existing one.
357 As well as using SPEC-LIST to initialize the glyph, you can set
358 specifications using `set-glyph-image'. Note that, due to a
359 possibly questionable historical design decision, a glyph itself
360 is not actually a specifier, but rather is an object containing an
361 image specifier (as well as other, seldom-used properties).
362 Therefore, you cannot set or access specifications for the glyph's
363 image by directly using `set-specifier', `specifier-instance' or
364 the like on the glyph; instead use them on `(glyph-image GLYPH)'
365 or use the convenience functions `set-glyph-image',
366 `glyph-image-instance', and `glyph-image'.
368 Once you have created a glyph, you specify where it will be used as
371 * To insert a glyph into a buffer, create an extent in the
372 buffer and then use `set-extent-begin-glyph' or
373 `set-extent-end-glyph' to set a glyph to be displayed at the
374 corresponding edge of the extent. (It is common to create
375 zero-width extents for this purpose.)
377 * To insert a glyph into the left or right margin of a buffer,
378 first make sure the margin is visible by setting a value for
379 the specifiers `left-margin-width' or `right-margin-width'.
380 (Not strictly necessary when using margin glyphs with layout
381 policy `whitespace'.) Then follow the same procedure above
382 for inserting a glyph in a buffer, and then set a non-default
383 layout policy for the glyph using
384 `set-extent-begin-glyph-layout' or
385 `set-extent-end-glyph-layout'. Alternatively, use the
386 high-level annotations API (see `make-annotation'). (In point
387 of fact, you can also use the annotations API for glyphs in a
388 buffer, by setting a layout policy of `text'.)
390 * To insert a glyph into the modeline, just put the glyph
391 directly as one of the modeline elements. (Unfortunately you
392 can't currently put a begin glyph or end glyph on one of the
393 modeline extents--they're ignored.)
395 * To insert a glyph into a toolbar, specify it as part of a
396 toolbar instantiator (typically set on the specifier
397 `default-toolbar'). See `default-toolbar' for more
398 information. (Note that it is standard practice to use a
399 symbol in place of the glyph list in the toolbar
400 instantiator; the symbol is evalled to get the glyph list.
401 This facilitates both creating the toolbar instantiator and
402 modifying individual glyphs in a toolbar later on. For
403 example, you can change the way that the Mail toolbar button
404 looks by modifying the value of the variable
405 `toolbar-mail-icon' (in general, `toolbar-*-icon') and then
406 calling `(set-specifier-dirty-flag default-toolbar)'. (####
407 Unfortunately this doesn't quite work the way it should; the
408 change will appear in new frames, but not existing ones.
410 * To insert a glyph into a gutter, create or modify a gutter
411 instantiator (typically set on the specifier
412 `default-gutter'). Gutter instantiators consist of strings
413 or lists of strings, so to insert a glyph, create an extent
414 over the string, and use `set-extent-begin-glyph' or
415 `set-extent-end-glyph' to set a glyph to be displayed at the
416 corresponding edge of the extent, just like for glyphs in a
419 * To use a glyph as the icon for a frame, you do not actually
420 create a new glyph; rather, you change the specifications for
421 the existing glyph `frame-icon-glyph'. (Remember that,
422 because of the specifier nature of glyphs, you can set
423 different values for any particular buffer or frame.)
425 * To use a glyph as the mouse pointer, in general you do not
426 create a new glyph, but rather you change the specifications
427 of various existing glyphs, such as `text-pointer-glyph' for
428 the pointer used over text, `modeline-pointer-glyph' for the
429 pointer used over the modeline, etc. Do an apropos over
430 `*-pointer-glyph' to find all of them. (Note also that you
431 can temporarily set the mouse pointer to some specific shape
432 by using `set-frame-pointer', which takes an image instance,
433 as obtained from calling `glyph-image-instance' on a glyph of
434 type `pointer' - either one of the above-mentioned variables
435 or one you created yourself. (See below for what it means to
436 create a glyph of type `pointer'.) This pointer will last
437 only until the next mouse motion event is processed or
438 certain other things happen, such as creating or deleting a
439 window. (In fact, the above-mentioned pointer glyph variables
440 are implemented as part of the default handler for mouse
441 motion events. If you want to customize this behavior, take a
442 look at `mode-motion-hook', or `mouse-motion-handler' if you
443 really want to get low-level.)
445 * To use a glyph to control the shape of miscellaneous
446 redisplay effects such as the truncation and continuation
447 markers, set the appropriate existing glyph variables, as for
448 icons and pointers above. See `continuation-glyph',
449 `control-arrow-glyph', `hscroll-glyph',
450 `invisible-text-glyph', `octal-escape-glyph', and
451 `truncation-glyph'. See also `overlay-arrow-string', an odd
452 redisplay leftover which can be set to a glyph you created,
453 and will cause the glyph to be displayed on top of the text
454 position specified in the marker stored in
455 `overlay-arrow-position'.
457 * To use a glyph in a display table (i.e. to control the
458 appearance of any individual character), create the
459 appropriate character glyphs and then set a specification for
460 the specifier `current-display-table', which controls the
461 appearance of characters. You can also set an overriding
462 display table for use with text displayed in a particular
463 face; see `set-face-display-table' and `make-display-table'.
464 #### Note: Display tables do not currently support general
465 Mule characters. They will be overhauled at some point to
466 support this and to provide other features required under
469 * To use a glyph as the background pixmap of a face: Note that
470 the background pixmap of a face is actually an image
471 specifier - probably the only place in XEmacs where an image
472 specifier occurs outside of a glyph. Similarly to how the
473 glyph's image specifier works, you don't create your own
474 image specifier, but rather add specifications to the
475 existing one (using `set-face-background-pixmap'). Note that
476 the image instance that is generated in order to actually
477 display the background pixmap is of type `mono-pixmap',
478 meaning that it's a two-color image and the foreground and
479 background of the image get filled in with the corresponding
480 colors from the face.
482 It is extremely rare that you will ever have to specify a value for
483 TYPE, which should be one of `buffer' (used for glyphs in an
484 extent, the modeline, the toolbar, or elsewhere in a buffer),
485 `pointer' (used for the mouse-pointer), or `icon' (used for a
486 frame's icon), and defaults to `buffer'. The only cases where it
487 needs to be specified is when creating icon or pointer glyphs, and
488 in both cases the necessary glyphs have already been created at
489 startup and are accessed through the appropriate variables, e.g.
490 `text-pointer-glyph' (or in general, `*-pointer-glyph') and
491 `frame-icon-glyph'. *Note Glyph Types::.
493 - Function: make-glyph-internal &optional type
494 This function creates a new, uninitialized glyph of type TYPE.
496 - Function: make-pointer-glyph &optional spec-list
497 Return a new `pointer-glyph' object with the specification list
498 SPEC-LIST. This function is equivalent to calling `make-glyph'
499 with a TYPE of `pointer'.
501 It is extremely unlikely that you will ever need to create a
502 pointer glyph. Instead, you probably want to be calling
503 `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
505 - Function: make-icon-glyph &optional spec-list
506 Return a new `pointer-glyph' object with the specification list
507 SPEC-LIST. This function is equivalent to calling `make-glyph'
508 with a TYPE of `icon'.
510 It is extremely unlikely that you will ever need to create a
511 pointer glyph. Instead, you probably want to be calling
512 `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
515 File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
520 Each glyph has a list of properties, which control all of the
521 aspects of the glyph's appearance. The following symbols have
525 The image used to display the glyph.
528 Percent above baseline that glyph is to be displayed. Only for
529 glyphs displayed inside of a buffer.
532 Whether the glyph contributes to the height of the line it's on.
533 Only for glyphs displayed inside of a buffer.
536 Face of this glyph (_not_ a specifier).
538 - Function: set-glyph-property glyph property value &optional locale
540 This function changes a property of a GLYPH.
542 For built-in properties, the actual value of the property is a
543 specifier and you cannot change this; but you can change the
544 specifications within the specifier, and that is what this
545 function will do. For user-defined properties, you can use this
546 function to either change the actual value of the property or, if
547 this value is a specifier, change the specifications within it.
549 If PROPERTY is a built-in property, the specifications to be added
550 to this property can be supplied in many different ways:
552 * If VALUE is a simple instantiator (e.g. a string naming a
553 pixmap filename) or a list of instantiators, then the
554 instantiator(s) will be added as a specification of the
555 property for the given LOCALE (which defaults to `global' if
558 * If VALUE is a list of specifications (each of which is a cons
559 of a locale and a list of instantiators), then LOCALE must be
560 `nil' (it does not make sense to explicitly specify a locale
561 in this case), and specifications will be added as given.
563 * If VALUE is a specifier (as would be returned by
564 `glyph-property' if no LOCALE argument is given), then some
565 or all of the specifications in the specifier will be added
566 to the property. In this case, the function is really
567 equivalent to `copy-specifier' and LOCALE has the same
568 semantics (if it is a particular locale, the specification
569 for the locale will be copied; if a locale type,
570 specifications for all locales of that type will be copied;
571 if `nil' or `all', then all specifications will be copied).
573 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
574 `append', `remove-tag-set-prepend', `remove-tag-set-append',
575 `remove-locale', `remove-locale-type', or `remove-all'. See
576 `copy-specifier' and `add-spec-to-specifier' for a description of
577 what each of these means. Most of the time, you do not need to
578 worry about this argument; the default behavior usually is fine.
580 In general, it is OK to pass an instance object (e.g. as returned
581 by `glyph-property-instance') as an instantiator in place of an
582 actual instantiator. In such a case, the instantiator used to
583 create that instance object will be used (for example, if you set
584 a font-instance object as the value of the `font' property, then
585 the font name used to create that object will be used instead).
586 If some cases, however, doing this conversion does not make sense,
587 and this will be noted in the documentation for particular types
590 If PROPERTY is not a built-in property, then this function will
591 simply set its value if LOCALE is `nil'. However, if LOCALE is
592 given, then this function will attempt to add VALUE as the
593 instantiator for the given LOCALE, using `add-spec-to-specifier'.
594 If the value of the property is not a specifier, it will
595 automatically be converted into a `generic' specifier.
597 - Function: glyph-property glyph property &optional locale
598 This function returns GLYPH's value of the given PROPERTY.
600 If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
601 be returned. For built-in properties, this will be a specifier
602 object of a type appropriate to the property (e.g. a font or color
603 specifier). For other properties, this could be anything.
605 If LOCALE is supplied, then instead of returning the actual value,
606 the specification(s) for the given locale or locale type will be
607 returned. This will only work if the actual value of PROPERTY is
608 a specifier (this will always be the case for built-in properties,
609 but may or may not apply to user-defined properties). If the
610 actual value of PROPERTY is not a specifier, this value will
611 simply be returned regardless of LOCALE.
613 The return value will be a list of instantiators (e.g. vectors
614 specifying pixmap data), or a list of specifications, each of
615 which is a cons of a locale and a list of instantiators.
616 Specifically, if LOCALE is a particular locale (a buffer, window,
617 frame, device, or `global'), a list of instantiators for that
618 locale will be returned. Otherwise, if LOCALE is a locale type
619 (one of the symbols `buffer', `window', `frame', or `device'), the
620 specifications for all locales of that type will be returned.
621 Finally, if LOCALE is `all', the specifications for all locales of
622 all types will be returned.
624 The specifications in a specifier determine what the value of
625 PROPERTY will be in a particular "domain" or set of circumstances,
626 which is typically a particular Emacs window along with the buffer
627 it contains and the frame and device it lies within. The value is
628 derived from the instantiator associated with the most specific
629 locale (in the order buffer, window, frame, device, and `global')
630 that matches the domain in question. In other words, given a
631 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
632 will first be searched for a specification whose locale is the
633 buffer contained within that window; then for a specification
634 whose locale is the window itself; then for a specification whose
635 locale is the frame that the window is contained within; etc. The
636 first instantiator that is valid for the domain (usually this
637 means that the instantiator is recognized by the device [i.e. the
638 X server or TTY device] that the domain is on). The function
639 `glyph-property-instance' actually does all this, and is used to
640 determine how to display the glyph.
642 - Function: glyph-property-instance glyph property &optional domain
644 This function returns the instance of GLYPH's PROPERTY in the
647 Under most circumstances, DOMAIN will be a particular window, and
648 the returned instance describes how the specified property
649 actually is displayed for that window and the particular buffer in
650 it. Note that this may not be the same as how the property
651 appears when the buffer is displayed in a different window or
652 frame, or how the property appears in the same window if you
653 switch to another buffer in that window; and in those cases, the
654 returned instance would be different.
656 The returned instance is an image-instance object, and you can
657 query it using the appropriate image instance functions. For
658 example, you could use `image-instance-depth' to find out the
659 depth (number of color planes) of a pixmap displayed in a
660 particular window. The results might be different from the
661 results you would get for another window (perhaps the user
662 specified a different image for the frame that window is on; or
663 perhaps the same image was specified but the window is on a
664 different X server, and that X server has different color
665 capabilities from this one).
667 DOMAIN defaults to the selected window if omitted.
669 DOMAIN can be a frame or device, instead of a window. The value
670 returned for such a domain is used in special circumstances when a
671 more specific domain does not apply; for example, a frame value
672 might be used for coloring a toolbar, which is conceptually
673 attached to a frame rather than a particular window. The value is
674 also useful in determining what the value would be for a
675 particular window within the frame or device, if it is not
676 overridden by a more specific specification.
678 If PROPERTY does not name a built-in property, its value will
679 simply be returned unless it is a specifier object, in which case
680 it will be instanced using `specifier-instance'.
682 Optional arguments DEFAULT and NO-FALLBACK are the same as in
683 `specifier-instance'. *Note Specifiers::.
685 - Function: remove-glyph-property glyph property &optional locale
687 This function removes a property from a glyph. For built-in
688 properties, this is analogous to `remove-specifier'. *Note
689 remove-specifier-p: Specifiers, for the meaning of the LOCALE,
690 TAG-SET, and EXACT-P arguments.
693 File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
695 Glyph Convenience Functions
696 ---------------------------
698 The following functions are provided for working with specific
699 properties of a glyph. Note that these are exactly like calling the
700 general functions described above and passing in the appropriate value
703 Remember that if you want to determine the "value" of a specific
704 glyph property, you probably want to use the `*-instance' functions.
705 For example, to determine whether a glyph contributes to its line
706 height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
707 latter will return a boolean specifier or a list of specifications, and
708 you probably aren't concerned with these.)
710 - Function: glyph-image glyph &optional locale
711 This function is equivalent to calling `glyph-property' with a
712 property of `image'. The return value will be an image specifier
713 if LOCALE is `nil' or omitted; otherwise, it will be a
714 specification or list of specifications.
716 - Function: set-glyph-image glyph spec &optional locale tag-set
718 This function is equivalent to calling `set-glyph-property' with a
721 - Function: glyph-image-instance glyph &optional domain default
723 This function returns the instance of GLYPH's image in the given
724 DOMAIN, and is equivalent to calling `glyph-property-instance'
725 with a property of `image'. The return value will be an image
728 Normally DOMAIN will be a window or `nil' (meaning the selected
729 window), and an instance object describing how the image appears
730 in that particular window and buffer will be returned.
732 - Function: glyph-contrib-p glyph &optional locale
733 This function is equivalent to calling `glyph-property' with a
734 property of `contrib-p'. The return value will be a boolean
735 specifier if LOCALE is `nil' or omitted; otherwise, it will be a
736 specification or list of specifications.
738 - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
740 This function is equivalent to calling `set-glyph-property' with a
741 property of `contrib-p'.
743 - Function: glyph-contrib-p-instance glyph &optional domain default
745 This function returns whether the glyph contributes to its line
746 height in the given DOMAIN, and is equivalent to calling
747 `glyph-property-instance' with a property of `contrib-p'. The
748 return value will be either `nil' or `t'. (Normally DOMAIN will be
749 a window or `nil', meaning the selected window.)
751 - Function: glyph-baseline glyph &optional locale
752 This function is equivalent to calling `glyph-property' with a
753 property of `baseline'. The return value will be a specifier if
754 LOCALE is `nil' or omitted; otherwise, it will be a specification
755 or list of specifications.
757 - Function: set-glyph-baseline glyph spec &optional locale tag-set
759 This function is equivalent to calling `set-glyph-property' with a
760 property of `baseline'.
762 - Function: glyph-baseline-instance glyph &optional domain default
764 This function returns the instance of GLYPH's baseline value in
765 the given DOMAIN, and is equivalent to calling
766 `glyph-property-instance' with a property of `baseline'. The
767 return value will be an integer or `nil'.
769 Normally DOMAIN will be a window or `nil' (meaning the selected
770 window), and an instance object describing the baseline value
771 appears in that particular window and buffer will be returned.
773 - Function: glyph-face glyph
774 This function returns the face of GLYPH. (Remember, this is not a
775 specifier, but a simple property.)
777 - Function: set-glyph-face glyph face
778 This function changes the face of GLYPH to FACE.
781 File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
786 - Function: glyph-width glyph &optional window
787 This function returns the width of GLYPH on WINDOW. This may not
788 be exact as it does not take into account all of the context that
791 - Function: glyph-ascent glyph &optional window
792 This function returns the ascent value of GLYPH on WINDOW. This
793 may not be exact as it does not take into account all of the
794 context that redisplay will.
796 - Function: glyph-descent glyph &optional window
797 This function returns the descent value of GLYPH on WINDOW. This
798 may not be exact as it does not take into account all of the
799 context that redisplay will.
801 - Function: glyph-height glyph &optional window
802 This function returns the height of GLYPH on WINDOW. (This is
803 equivalent to the sum of the ascent and descent values.) This may
804 not be exact as it does not take into account all of the context
808 File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
815 * Image Specifiers:: Specifying how an image will appear.
816 * Image Instantiator Conversion::
817 Conversion is applied to image instantiators
818 at the time they are added to an
819 image specifier or at the time they
820 are passed to `make-image-instance'.
821 * Image Instances:: What an image specifier gets instanced as.
projects / chise / xemacs-chise.git- / blob