2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1995, 1996 Ben Wing.
4 @c Copyright (C) 2004 Free Software Foundation, Inc.
5 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
6 @c See the file lispref.texi for copying conditions.
7 @setfilename ../../info/glyphs.info
9 @node Glyphs, Annotations, Faces and Window-System Objects, top
13 A @dfn{glyph} is an object that is used for pixmaps, widgets, and
14 images of all sorts, as well as for things that ``act'' like pixmaps,
15 such as non-textual strings (@dfn{annotations}) displayed in a buffer or
16 in the margins. It is used in begin-glyphs and end-glyphs attached to
17 extents, marginal and textual annotations, overlay arrows
18 (@code{overlay-arrow-*} variables), toolbar buttons, mouse pointers,
19 frame icons, truncation and continuation markers, and the
20 like. Basically, any place there is an image or something that acts
21 like an image, there will be a glyph object representing it.
24 This function returns @code{t} if @var{object} is a glyph.
28 * Glyph Intro:: Glyphs are abstract image specifications.
29 * Images:: Specifying the appearance of glyphs.
30 * Using Glyphs:: Creating and displaying glyphs.
31 * Manipulating Glyphs:: Getting and setting glyph properties.
32 * Glyph Examples:: Examples of how to work with glyphs.
37 @section Glyph Introduction
39 In SXEmacs, ``glyph'' does @strong{not} refer to a single unit of textual
40 display (the SXEmacs term for that is @dfn{rune}, and runes are confined
41 to the internal implementation of redisplay), but rather is an
42 object encapsulating a graphical element, such as an image or widget (an
43 active GUI element such as a button or text entry field; X11 calls this a
45 This graphical element could appear in a buffer, a margin, a gutter, or
46 a toolbar, or even externally to SXEmacs as a mouse pointer or an icon,
49 On the other hand, by contrast with GNU Emacs 21, a SXEmacs glyph is
50 not ``just'' an image. The actual image that is displayed (as opposed
51 to its position or clipping) is defined by an ``image specifier'' object
52 contained within the glyph. The separation between an image specifier
53 object and a glyph object is made because the glyph includes other
54 properties than just the actual image: e.g. the face it is displayed in,
55 the alignment of the image, @emph{etc}. Also, an image specifier is
56 used in at least one place in SXEmacs in lieu of a glyph, namely the
57 backing pixmap of a face.
59 An image specifier is used because glyphs often have locale-specific
60 semantics. The most important example is semantics determined by the
61 display device: you cannot usefully display a JPEG on stdout, or a color
62 image on a monochrome display. But because the image property is a
63 specifier in SXEmacs, you can specify that a given glyph appear as a
64 monochrome image on monochrome displays, a color image on color
65 displays, and as a string on TTYs. Specifying a string for the
66 @code{tty} device locale would give behavior like the @code{ALT}
67 attribute of an @code{IMG} element in HTML. Another is semantics
68 determined by the buffer or mode. (Unfortunately, currently there are
69 no compelling examples of this for glyphs.)
71 All this means that only one global glyph needs to exist for a
72 particular purpose (e.g. the icon used to represent an iconified frame,
73 the mouse pointer used over particular areas of a frame, etc.). Often
74 you need not (and should not!) create your own glyph, but rather modify
77 In working with glyphs it is important to keep in mind the distinction
78 between a locale and a domain. A @dfn{locale} is specified by the
79 programmer, and is an abstract link between a specification (for a
80 glyph, its visual appearance) and a displayable object. The displayable
81 object may be a buffer or a window, or an object containing buffers or
82 windows such as frame, device, or console. A @dfn{domain} is an actual
83 display context, which must be concrete enough to enable SXEmacs to
84 identify the device type. (Buffers may be displayed in windows on
85 different devices, even simultaneously, so a buffer cannot be a domain.
86 Similarly, the global locale cannot be a domain.) @ref{Specifiers}, for
87 more information about specifier locales and domains.
94 * Image Specifiers:: Specifying an image's appearance.
95 * Image Instantiator Conversion:: Lazy realization of graphics.
96 * Image Instantiator Formats:: A catalog of image descriptors.
97 * Image Instances:: Classes of graphical objects.
101 @node Image Specifiers
102 @subsection Image Specifiers
103 @cindex image specifiers
105 An image specifier is a description of the actual graphical
106 realization of a glyph. For example, a typical image description is
107 @emph{the file system path to a PNG file}. Since
108 redisplay doesn't know about files, and in any case the image may need
109 to be manipulated (@emph{e.g.}, a face's background pixmap must be
110 clipped and tiled), the PNG file must be converted internally to a
111 window system bitmap or pixmap object.
113 We describe this process by writing that when SXEmacs displays the image,
114 it @dfn{instantiates} the @dfn{image instantiator} into an @dfn{image
115 instance}. Image instances are an internal object type (similar to font
116 instances and color instances), describing how the image appears in a
117 particular domain. On the other hand, image instantiators, which are
118 just descriptions of how the image should appear, are represented using
119 Lisp strings or vectors.
121 Furthermore the graphical realization will vary, and for some devices
122 may not even be a bitmapped graphic. These variations may be controlled
123 by the program by specifying different @dfn{image instantiators} in
124 different locales. This is implemented with an @dfn{image specifier},
125 a specifier whose specifications are image instantiators.
127 Image specifiers are rarely if ever found by themselves. However, an
128 image specifier results from calling @code{glyph-image} on a glyph, or
129 retrieving the @code{background-pixmap} property of a face, and you can
130 check if some random object is an image specifier.
132 @defun image-specifier-p object
133 This function returns non-@code{nil} if @var{object} is an image specifier.
136 @defun make-image-specifier spec-list
137 This function creates a new image specifier object and initializes it
138 according to @var{spec-list}. @xref{Specifiers}.
141 This function exists mainly for completeness. In practice, you rarely,
142 if ever, need to actually create an image specifier. Instead, they are
143 implicitly created by the initialization of glyphs and faces, and the
144 specifier member of these objects cannot be changed after
145 initialization; you may only set the specifications it contains.
147 Image instantiators come in many formats: @code{xbm}, @code{xpm},
148 @code{gif}, @code{jpeg}, etc. These denote the format of the data
149 describing the image. The resulting image instances also come in many
150 types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
151 @code{pointer}, etc. This refers to the behavior of the image and the
152 sorts of places it can appear.
154 For example, a color-pixmap image has fixed colors specified for it,
155 while a mono-pixmap image comes in two unspecified shades ``foreground''
156 and ``background'' that are determined from the face of the glyph or
157 surrounding text; a text image appears as a string of text and has an
158 unspecified foreground, background, and font; a pointer image behaves
159 like a mono-pixmap image but can only be used as a mouse pointer
160 [mono-pixmap images cannot be used as mouse pointers]; etc.
162 It is important to keep the distinction between image instantiator
163 format and image instance type in mind. Typically, a given image
164 instantiator format can result in many different image instance types.
166 For example, @code{xpm} can be instanced as @code{color-pixmap},
167 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
168 instanced only as @code{pointer}. On the other hand, a particular image
169 instance type can be generated by many different image instantiator
170 formats (e.g. @code{color-pixmap} can be generated by @code{xpm},
171 @code{gif}, @code{jpeg}, etc.).
173 @xref{Image Instances}, for a more detailed discussion of image
176 An image instantiator should be a string or a vector of the form
179 @code{[@var{format} @var{:keyword} @var{value} ...]}
182 i.e. a format symbol followed by zero or more alternating keyword-value
185 The form of an instantiator can be checked with
186 @code{valid-instantiator-p} with a @var{TYPE} of @code{image},
187 @ref{Specifier Validation Functions}.
189 For a complete list of the format symbols and their usage,
190 @ref{Image Instantiator Formats}.
192 If the instantiator is a string, it will be converted into a vector by
193 looking it up according to the specs in the
194 @code{console-type-image-conversion-list} for the console type of the
195 domain (usually a window; sometimes a frame or device) over which the
196 image is being instantiated.
198 If the instantiator specifies data from a file, the data will be read in
199 at the time that the instantiator is added to the image specifier (which
200 may be well before the image is actually displayed), and the
201 instantiator will be converted into one of the inline-data forms, with
202 the filename retained using a @code{:file} keyword. This implies that
203 the file must exist when the instantiator is added to the image, but
204 does not need to exist at any other time (e.g. it may safely be a
207 The available keywords are given below. Note that some keywords are
208 generally available (for example, the @code{:data} keyword may be used
209 with any format except @code{nothing}), while others are only available
214 Inline image data. If available for a given format, it may be specified
215 directly by the program, or it may be a cache of file data previously
216 read. When present, it is used to instantiate the image in preference
217 to the file named by the @code{:file} property.
219 The format of inline data is image-format-specific. For example, in
220 pixmap formats, the value should be a string, which is interpreted as an
221 octet-stream representing a bitmap or pixmap. But for text formats,
222 it's string containing the text to be displayed, and for resource
223 formats, it's a string containing the name of the resource.
226 Data contained in a file. The value is the name of this file. If both
227 @code{:data} and @code{:file} are specified, the image is created from
228 what is specified in @code{:data} and the string in @code{:file} becomes
229 the value of the @code{image-instance-file-name} function when applied
230 to the resulting image-instance. Note that there is nothing to stop a
231 program from changing either the @code{:file} or the @code{:data}
232 property, and there is no way to detect such mischief. This means that
233 the data will @emph{not} be automatically reread if you change the
234 @code{file} property; you must force it by removing the @code{:data}
236 @c #### If there are ways to do this in-place, describe them.
237 (One way to do this is replacing the whole specification with a new
238 vector.) This keyword is not valid for instantiator formats
239 @code{nothing}, @code{string}, @code{formatted-string},
240 @code{cursor-font}, @code{font}, and @code{autodetect}.
243 Inline data for @code{xbm} and @code{xface}. This specifies a mask to
244 be used with the bitmap. Pixels which are not set in the mask will not
245 be written to the imaging device. The format is a list of width,
246 height, and bits, as for @code{:data}.
249 For @code{xbm} and @code{xface}. This specifies a file containing the
250 mask data. If neither a mask file nor inline mask data is given for an
251 XBM image, and the XBM image comes from a file, XEmacs will look for a
252 mask file with the same name as the image file but with @samp{Mask} or
253 @samp{msk} appended. For example, if you specify the XBM file
254 @file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
255 the associated mask file @file{left_ptrmsk} will automatically be picked
259 Only for @code{mswindows-resource}. This must be either an integer
260 (which directly specifies a resource number) or a string. See the
261 description of @code{mswindows-resource} for valid strings. @xref{Image
262 Instantiator Formats}.
266 For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
267 These keywords allow you to explicitly specify foreground and background
268 colors. The value should be anything acceptable to
269 @code{make-color-instance}. This will cause an external format that
270 would by default be instantiated as a @code{mono-pixmap} to instead be
271 instantiated as a two-color color-pixmap. This can be used to override
272 the colors specified by a glyph's face, for example. If the image is
273 instantiated as a pointer, they specify its foreground and/or
274 background, instead of the defaults of black and white.
278 For @code{xbm} and @code{xface}. These keywords specify a hotspot if
279 the image is instantiated as a @code{pointer}. Note that if the XBM
280 image file specifies a hotspot, it will automatically be picked up if no
281 explicit hotspot is given.
284 Only for @code{xpm}. This specifies an alist that maps strings that
285 specify symbolic color names to the actual color to be used for that
286 symbolic color (in the form of a string or a color-specifier object).
287 If this is not specified, the contents of @code{xpm-color-symbols} are
288 used to generate the alist.
291 For @code{inherit} and the widget formats. This specifies the face to
292 inherit from. For widgets this specifies the face to use for display.
293 It defaults to gui-element-face.
307 These keywords, accepted as menu item specs, are also accepted by images
308 instantiated as @code{widget}. For their semantics, @ref{Menu Format}.
312 @node Image Instantiator Conversion
313 @subsection Image Instantiator Conversion
314 @cindex image instantiator conversion
315 @cindex conversion of image instantiators
317 Conversion is applied to image instantiators at the time they are added
318 to an image specifier or at the time they are passed to
319 @code{make-image-instance}.
321 @defun set-console-type-image-conversion-list console-type list
322 This function sets the image-conversion-list for consoles of the given
323 @var{console-type}. The image-conversion-list specifies how image
324 instantiators that are strings should be interpreted. Each element of
325 the list should be a list of two elements (a regular expression string
326 and a vector) or a list of three elements (the preceding two plus an
327 integer index into the vector). The string is converted to the vector
328 associated with the first matching regular expression. If a vector
329 index is specified, the string itself is substituted into that position
332 Note: The conversion above is applied when the image instantiator is
333 added to an image specifier, not when the specifier is actually
334 instantiated. Therefore, changing the image-conversion-list only affects
335 newly-added instantiators. Existing instantiators in glyphs and image
336 specifiers will not be affected.
339 @defun console-type-image-conversion-list console-type
340 This function returns the image-conversion-list for consoles of the given
345 @node Image Instantiator Formats
346 @subsection Image Instantiator Formats
347 @cindex image instantiator formats
349 The @dfn{format} field of an image instantiator should be a symbol
350 denoting a valid format. Which formats are valid will depend on the
351 features (such as image decoding libraries) available, on platform
352 support, and on the locale.
354 @defun valid-image-instantiator-format-p format &optional locale
355 This function returns non-@code{nil} if @var{format} is a valid image
358 If @var{locale} is non-@code{nil} then the format is checked in that locale.
359 If @var{locale} is @code{nil} the current console is used.
361 Note that the return value for many formats listed above depends on
362 whether SXEmacs was compiled with support for that format.
365 @defun image-instantiator-format-list
366 This function returns a list of valid image-instantiator formats.
369 Here is a table of image-instantiator formats, giving the keywords that
370 are usable with each, and the kinds of instances that may result.
374 Don't display anything; no keywords are valid for this format. Can only be
375 instanced as @code{nothing}.
378 Display this image as a text string. Can only be instanced
379 as @code{text}, although support for instancing as @code{mono-pixmap}
380 should be added. The valid keyword is @code{:data}. The value should
381 be a string, and it is interpreted as a string of characters.
383 @item formatted-string
384 Display this image as a text string with replaceable fields,
385 similar to a modeline format string. The valid keyword is @code{:data}.
386 The value should be a string, and it is interpreted as a string of
387 characters containing format sequences.
389 Not currently implemented.
392 An X bitmap; available only if X support was compiled into this XEmacs.
394 If used in a buffer glyph, icon glyph, or face background pixmap, it
395 will be instantiated as @code{mono-pixmap} unless the @code{:foreground}
396 or @code{:background} keywords are present. In the latter case it will
397 be instantiated as @code{color-pixmap} with the two specified colors.
399 (Probably if @code{:foreground} or @code{:background} is omitted, it
400 defaults to black or white respectively.) If used in a pointer glyph,
401 it will be instantiated as an @code{pointer}.
403 The valid keywords and their values are
406 A list containing the height and width of the bitmap as integers, and
407 a string interpreted as a bit vector according to the X11 standard XBM
408 bitmap format, in that order.
410 The name of a file containing standard XBM-format data. If it contains
411 a hotspot specification, it will be parsed and used if the hotspot is
412 not explicitly specified.
414 A list containing the height and width of the bitmap as integers, and
415 a string interpreted as a bit vector according to the X11 standard XBM
416 bitmap format, in that order. This bitmap is interpreted as the
417 clipping region for the bitmap contained in the @code{:data} property.
419 The name of a file containing standard XBM-format data. Interpreted as
420 the clipping region for the bitmap contained in the @code{:data} property.
423 These keywords allow you to explicitly specify foreground and background
424 colors. The values should be acceptable to @code{make-color-instance}.
427 Integers denoting the hotspot (mouse pointer position), with (0,0) at
428 the top left corner. If given, these override any specification in the
433 An XPM pixmap; only available if XPM support was compiled into this XEmacs.
435 Can be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
438 XPM is an add-on library for X that was designed to rectify the
439 shortcomings of the XBM format. Many icons and labels used in the
440 XEmacs GUI are still distributed in XPM format (although we are moving
441 to standardize on the PNG format). It is therefore highly desirable
442 that XPM be available in your SXEmacs.
444 Most implementations of X include the XPM library as a standard part.
445 If your vendor does not, it is highly recommended that you download it
446 and install it. You can get it from the XEmacs FTP site and mirrors, as
447 well as from most sites that distribute X11.
449 The valid keywords and their values are
452 A string interpreted as the contents of a standard XPM file.
454 The name of a file containing standard XPM-format data. If it contains
455 a hotspot specification, it will be parsed and used if the hotspot is
456 not explicitly specified.
457 @c #### Does XPM provide for a hotspot?
460 Integers denoting the hotspot (mouse pointer position), with (0,0) at
461 the top left corner. If given, these override any specification in the
464 (This may not be true. The original documentation doesn't mention them
465 in connection with XPM, but a pointer needs a hotspot.)
467 An alist that maps the one- or two-character strings that specify
468 symbolic color names in the XPM file to the actual color to be used for
469 that symbolic color (in the form of a string acceptable as a color
470 instantiator, @ref{Color Specifiers}, or a color-specifier object).
471 If this is not specified, the contents of @code{xpm-color-symbols} are
472 used to generate the alist.
476 An X-Face bitmap, used to encode people's faces in e-mail messages;
477 only available if X-Face support was compiled into this SXEmacs.
479 Will be instanced as @code{mono-pixmap}, @code{color-pixmap}, or
480 @code{pointer}, depending on the target instance type and the presence
483 The valid keywords and their values are
486 A list containing the height and width of the bitmap as integers, and
487 a string interpreted as a bit vector according to the X11 standard XBM
488 bitmap format, in that order.
490 The name of a file containing standard XBM-format data. If it contains
491 a hotspot specification, it will be parsed and used if the hotspot is
492 not explicitly specified.
494 A list containing the height and width of the bitmap as integers, and
495 a string interpreted as a bit vector according to the X11 standard XBM
496 bitmap format, in that order. This bitmap is interpreted as the
497 clipping region for the bitmap contained in the @code{:data} property.
499 The name of a file containing standard XBM-format data. Interpreted as
500 the clipping region for the bitmap contained in the @code{:data} property.
503 These keywords allow you to explicitly specify foreground and background
504 colors. The values should be acceptable to @code{make-color-instance}.
507 Integers denoting the hotspot (mouse pointer position), with (0,0) at
508 the top left corner. If given, these override any specification in the
516 These are GIF87- or GIF89-format, JPEG-format, PNG/GIF24-format, and
517 TIFF-format images, respectively. They are available only if
518 appropriate decoding support was built into XEmacs. XEmacs includes GIF
519 decoding functions as a standard part of it, so if you have X support,
520 you will normally have GIF support, unless you explicitly disable it at
521 configure time. If you have development support (both the libraries and
522 the relevant C header files) available when SXEmacs is built, the JPEG,
523 PNG, and TIFF libraries will automatically be detected (in the ``usual
524 places'') and linked into the build.
526 Note that PNG is the standard format for images distributed with XEmacs,
527 so it is highly recommended that PNG support be built in.
529 All of these instantiators will be instanced as @code{color-pixmap}.
531 The valid keywords and their values are
534 A string interpreted as the contents of a file containing data in the
535 appropriate standard format.
537 The name of a file containing standard-format data.
541 Most window systems provide a set of standard cursors, which in X11 is
542 called a cursor font. Can only be instanced as @code{pointer}. This
543 should probably be fixed.
545 The valid keyword is @code{:data}. Its value should be a string
546 containing one of the standard cursor-font names, such as @samp{watch}
547 or @samp{right_ptr} under X. More specifically, in the X Window System
548 it may be any of the standard cursor names from appendix B of the Xlib
549 manual, provided in the file @file{<X11/cursorfont.h>} by most
550 distributions, minus the @samp{XC_} prefix.
551 Other window systems may have different lists.
554 A glyph from a font; i.e. the name of a font, and glyph index into it
555 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
556 Only if X support was compiled into this SXEmacs. Currently can only be
557 instanced as @code{pointer}. This should probably be fixed.
558 @c #### The above description is not very helpful, so it's not obvious
559 @c how to instantiate a font image.
562 An embedded windowing system window. Can only be instanced as
563 @code{subwindow}. Not implemented.
564 @c #### Check status of subwindows ... I thought Andy implemented them.
567 A button widget; either a push button, radio button or toggle button.
568 Can only be instanced as @code{widget}.
571 A drop list of selectable items in a widget, for editing text.
572 Can only be instanced as @code{widget}.
575 A text editing widget. Can only be instanced as @code{widget}.
578 A static, text-only, widget; for displaying text. Can only be instanced
582 A widget for controlling the positioning of children underneath it.
583 Through the use of nested layouts, a widget hierarchy can be created
584 which can have the appearance of any standard dialog box or similar
585 arrangement; all of this is counted as one @dfn{glyph} and could appear
586 in many of the places that expect a single glyph. Can only be instanced
590 The native version of a layout widget.
591 Can only be instanced as @code{widget}.
594 A sliding widget, for showing progress. Can only be instanced as
598 A tab widget; a series of user selectable tabs. Can only be instanced
602 A folding widget. Can only be instanced as @code{widget}.
605 A scrollbar widget. Can only be instanced as @code{widget}.
608 XEmacs tries to guess what format the data is in. If X support exists,
609 the data string will be checked to see if it names a filename. If so,
610 and this filename contains XBM or XPM data, the appropriate sort of
611 pixmap or pointer will be created. [This includes picking up any
612 specified hotspot or associated mask file.] Otherwise, if @code{pointer}
613 is one of the allowable image-instance types and the string names a
614 valid cursor-font name, the image will be created as a pointer.
615 Otherwise, the image will be displayed as text. If no X support exists,
616 the image will always be displayed as text.
619 Inherit from the background-pixmap property of a face. Can only be
620 instanced as @code{mono-pixmap}.
623 There are two convenience variables for use with the XBM and XPM image
626 @defvar xpm-color-symbols
627 This variable holds definitions of logical color-names used when reading
628 XPM files. Elements of this list should be of the form
629 @code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name}
630 should be a string, which is the name of the color to define; the
631 @var{form-to-evaluate} should evaluate to a color specifier object, or a
632 string to be passed to @code{make-color-instance} (@pxref{Colors}). If
633 a loaded XPM file references a symbolic color called @var{color-name},
634 it will display as the computed color instead.
636 The default value of this variable defines the logical color names
637 @samp{"foreground"} and @samp{"background"} to be the colors of the
641 @defvar x-bitmap-file-path
642 A list of the directories in which X bitmap files may be found. If @code{nil},
643 this is initialized from the @samp{"*bitmapFilePath"} resource. This is
644 used by the @code{make-image-instance} function (however, note that if
645 the environment variable @samp{XBMLANGPATH} is set, it is consulted
650 @node Image Instances
651 @subsection Image Instances
652 @cindex image instances
654 Image-instance objects encapsulate the way a particular image (pixmap,
655 etc.) is displayed on a particular device.
657 In most circumstances, you do not need to directly create image
658 instances; use a glyph instead. However, it may occasionally be useful
659 to explicitly create image instances, if you want more control over the
660 instantiation process.
662 @defun image-instance-p object
663 This function returns non-@code{nil} if @var{object} is an image instance.
667 * Image Instance Types:: Each image instances has a particular type.
668 * Image Instance Functions:: Functions for working with image instances.
672 @node Image Instance Types
673 @subsubsection Image Instance Types
674 @cindex image instance types
676 Image instances come in a number of different types. The type
677 of an image instance specifies the nature of the image: Whether
678 it is a text string, a mono pixmap, a color pixmap, etc.
680 The valid image instance types are
684 Nothing is displayed.
687 Displayed as text. The foreground and background colors and the
688 font of the text are specified independent of the pixmap. Typically
689 these attributes will come from the face of the surrounding text,
690 unless a face is specified for the glyph in which the image appears.
693 Displayed as a mono pixmap (a pixmap with only two colors where the
694 foreground and background can be specified independent of the pixmap;
695 typically the pixmap assumes the foreground and background colors of
696 the text around it, unless a face is specified for the glyph in which
700 Displayed as a color pixmap.
703 Used as the mouse pointer for a window.
706 A child window that is treated as an image. This allows (e.g.)
707 another program to be responsible for drawing into the window.
708 Not currently implemented.
709 @c #### Check status of subwindows ... I thought Andy implemented them.
712 An active GUI element implemented as a ``widget'' or ``control'' of the
713 underlying window system.
716 The following functions are used to check whether an image instance type
717 is valid in the running SXEmacs.
719 @defun valid-image-instance-type-p type
720 This function returns non-@code{nil} if @var{type} is a valid image
724 @defun image-instance-type-list
725 This function returns a list of the valid image instance types.
728 The following functions are used to determine the type of an image
731 @defun image-instance-type image-instance
732 Return the type of the given image instance. The return
733 value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
734 @code{color-pixmap}, @code{pointer}, @code{subwindow}, or @code{widget}.
735 @c #### Check status of subwindows ... I thought Andy implemented them.
738 @defun text-image-instance-p object
739 Return non-@code{nil} if @var{object} is an image instance of type
743 @defun mono-pixmap-image-instance-p object
744 Return non-@code{nil} if @var{object} is an image instance of type
748 @defun color-pixmap-image-instance-p object
749 Return non-@code{nil} if @var{object} is an image instance of type
753 @defun pointer-image-instance-p object
754 Return non-@code{nil} if @var{object} is an image instance of type
758 @defun subwindow-image-instance-p object
759 Return non-@code{nil} if @var{object} is an image instance of type
761 @c #### Check status of subwindows ... I thought Andy implemented them.
764 @defun nothing-image-instance-p object
765 Return non-@code{nil} if @var{object} is an image instance of type
769 @defun widget-image-instance-p object
770 Return non-@code{nil} if @var{object} is an image instance of type
775 @node Image Instance Functions
776 @subsubsection Image Instance Functions
778 @defun make-image-instance data &optional domain dest-types noerror
779 This function creates a new image-instance object.
781 @var{data} is an image instantiator, which describes the image
782 (@pxref{Image Specifiers}).
784 @var{dest-types} should be a list of allowed image instance types that
785 can be generated. The @var{dest-types} list is unordered. If multiple
786 destination types are possible for a given instantiator, the ``most
787 natural'' type for the instantiator's format is chosen. These are
793 @code{mono-pixmap}, then @code{color-pixmap}, then @code{pointer}.
800 @code{color-pixmap}, then @code{mono-pixmap}, then @code{pointer}.
803 @itemx formatted-string formats
804 @code{text}, then @code{mono-pixmap} (not currently implemented), then
805 @code{color-pixmap} (not currently implemented).
807 For the others, @code{color-pixmap}.
810 @c #### So what? This is a reference manual, list them, you lazy bastard!
811 The other formats can only be instantiated as one type.
813 If you want to control more specifically the order of the types into
814 which an image is instantiated, call @code{make-image-instance}
815 repeatedly until it succeeds, passing less and less preferred
816 destination types each time.
818 If @var{dest-types} is omitted, all possible types are allowed.
820 @var{domain} specifies the domain to which the image instance will be
821 attached. This domain is termed the @dfn{governing domain}. The type
822 of the governing domain depends on the image instantiator format.
823 (Although, more correctly, it should probably depend on the image
826 For example, pixmap image instances are specific to a device, but widget
827 image instances are specific to a particular SXEmacs window because in
828 order to display such a widget when two windows onto the same buffer
829 want to display the widget, two separate underlying widgets must be
830 created. That's because a widget is actually a child window-system
831 window, and all window-system windows have a unique existence on the
832 screen. This means that the governing domain for a pixmap image
833 instance will be some device (most likely, the only existing device),
834 whereas the governing domain for a widget image instance will be some
837 If you specify an overly general @var{domain} (e.g. a frame when a
838 window was wanted), an error is signaled. If you specify an overly
839 specific @var{domain} (e.g. a window when a device was wanted), the
840 corresponding general domain is fetched and used instead. For
841 @code{make-image-instance}, it makes no difference whether you specify
842 an overly specific domain or the properly general domain derived from
843 it. However, it does matter when creating an image instance by
844 instantiating a specifier or glyph (e.g. with
845 @code{glyph-image-instance}), because the more specific domain causes
846 spec lookup to start there and proceed to more general domains. (It
847 would also matter when creating an image instance with an instantiator
848 format of @code{inherit}, but we currently disallow this.)
849 @c #### We should fix that.
851 If omitted, @var{domain} defaults to the selected window.
853 @var{noerror} controls what happens when the image cannot be generated.
854 If @code{nil}, an error message is generated. If @code{t}, no messages
855 are generated and this function returns @code{nil}. If anything else, a
856 warning message is generated and this function returns @code{nil}.
859 @defun colorize-image-instance image-instance foreground background
860 This function makes the image instance be displayed in the given
861 colors. Image instances come in two varieties: bitmaps, which are 1
862 bit deep which are rendered in the prevailing foreground and background
863 colors; and pixmaps, which are of arbitrary depth (including 1) and
864 which have the colors explicitly specified. This function converts a
865 bitmap to a pixmap. If the image instance was a pixmap already,
866 nothing is done (and @code{nil} is returned). Otherwise @code{t} is
870 The following functions are
872 @defun image-instance-name image-instance
873 This function returns the name of the given image instance. The name is
874 typically taken from the @code{:file} property of the instantiator if
875 present, otherwise from the @code{:data} property.
878 @defun image-instance-domain image-instance
879 Return the governing domain of the given @var{image-instance}. The
880 governing domain of an image instance is the domain that the image
881 instance is specific to. It is @emph{NOT} necessarily the domain that
882 was given to the call to @code{specifier-instance} that resulted in the
883 creation of this image instance. See @code{make-image-instance} for
884 more information on governing domains.
887 @defun image-instance-string image-instance
888 This function returns the string of the given image instance. This will
889 only be non-@code{nil} for text image instances.
892 @defun image-instance-file-name image-instance
893 This function returns the file name from which @var{image-instance} was
897 @defun image-instance-mask-file-name image-instance
898 This function returns the file name from which @var{image-instance}'s
899 mask was read, if known.
902 Pixmaps are considered to be three-dimensional. The height and width of
903 the pixel array that is displayed, and the color depth of its pixels,
904 are accessed with these functions.
906 @defun image-instance-depth image-instance
907 This function returns the depth of the image instance. This is 0 for a
908 mono pixmap, or a positive integer for a color pixmap.
911 @defun image-instance-height image-instance
912 This function returns the height of the image instance, in pixels.
915 @defun image-instance-width image-instance
916 This function returns the width of the image instance, in pixels.
919 The hotspot is a point relative to the origin of the pixmap. When
920 an image is used as a mouse pointer, the hotspot is the point on the
921 image that sits over the location that the pointer points to. This is,
922 for example, the tip of the arrow or the center of the crosshairs.
924 These functions access the coordinates of the hotspot. They simply
925 return @code{nil} for a non-pointer image instance.
927 @defun image-instance-hotspot-x image-instance
928 This function returns the X coordinate of the image instance's hotspot,
932 @defun image-instance-hotspot-y image-instance
933 This function returns the Y coordinate of the image instance's hotspot,
937 Mono pixmaps and pointers may have their foreground and background
938 colors set when instanced. Use these functions to access color
941 @defun image-instance-foreground image-instance
942 This function returns the foreground color of @var{image-instance}, if
943 applicable. This will be a color instance or @code{nil}. (It will only
944 be non-@code{nil} for colorized mono pixmaps and for pointers.)
947 @defun image-instance-background image-instance
948 This function returns the background color of @var{image-instance}, if
949 applicable. This will be a color instance or @code{nil}. (It will only
950 be non-@code{nil} for colorized mono pixmaps and for pointers.)
955 @section Using Glyphs
957 Glyph usage is unfortunately somewhat arcane. (For discussion of
958 rationale, @ref{Glyphs,,,Internals}.) Because they are not ``text,''
959 they cannot be inserted directly into a buffer. Instead, they are
960 values of properties of extents attached to buffers or strings, values
961 of global variables such as mouse pointers, or as a component of a
962 complex data structure such as a toolbar initializer. Although these
963 uses could probably streamlined, each structure has its own
964 requirements. Since glyphs are very flexible, it is possible to create
965 applications like the @file{edit-toolbar} and @file{xpm-mode} libraries
966 which display glyphs in a buffer (for reference while editing) that are
967 normally used in a different context.
969 Usage of glyphs can roughly be categorized as follows:
973 Glyphs that are inserted in a buffer may be used for their own sake (for
974 example, image display in @file{w3}), as an accurate representation of
975 text that can't be displayed in usual fonts (equation display in
976 @file{preview-latex}), or as annotations (such as a marginal indication
977 of a bookmark). Glyphs are attached to buffers via extents.
979 @item Redisplay glyphs
980 Glyphs can be used to create SXEmacs-specific ``fonts''. For example,
981 the character that indicates truncation of lines is implemented as the
982 @code{truncation-glyph}. It is also possible to have XEmacs display a
983 certain character using a custom glyph, via display tables.
986 Glyphs are used to control the appearance of various other components of
987 the frame. They can be inserted in the modeline, like the favicons used
988 in Web browsers. They are used to specify the labels on toolbar
989 buttons. Finally, they can be inserted in the gutters. (The difference
990 between a glyph inserted in a gutter and a marginal annotation is that
991 the marginal annotation is tied to the text in the buffer. If the
992 buffer line scrolls out of view, the marginal annotation will, as well.
993 A gutter glyph does not move with the text.)
995 Unfortunately, all these uses are special cases, and have their own
996 APIs, in contrast to glyphs in a buffer.
998 @item External glyphs
999 External glyphs simply allow a consistent API for images. The images
1000 are then passed to external software such as the window system itself
1001 (mouse cursor shapes) and the window manager (icons to represent
1002 minimized windows). SXEmacs has no role in managing their use.
1004 @item Subwindow and widget glyphs
1005 These do not constitute a context of use, but rather an important class of
1006 glyph types. The difference between these and other glyphs is that
1007 while their geometry is determined by SXEmacs, their behavior is managed
1008 separately, by internal mechanisms in the case of widgets, and
1009 (possibly) by another process in the case of subwindows.
1010 @c #### Check status of subwindows ... I thought Andy implemented them.
1013 Some simple concrete examples showing how to insert a glyph in a
1014 buffer are presented later. @ref{Glyph Examples}.
1016 ``Creating Glyphs'' explains how to create glyphs. Creating a glyph
1017 using @code{make-glyph} does not specify @emph{where} the glyph will be
1018 used, it only specifies @emph{what} the glyph will look like. The next
1019 four sections explain how to embed glyphs in different display
1020 contexts. Finally, the last two sections explain the special
1021 considerations of using glyphs whose behavior is not determined by the
1022 code creating them, but by the glyph itself (a ``widget'' in X11 or
1023 ``control'' in Aqua), or even by a separate process.
1026 * Creating Glyphs:: Creating new glyphs.
1027 * Buffer Glyphs:: Annotations are glyphs that appear in a buffer.
1028 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
1029 * Frame Glyphs:: Displaying glyphs in GUI components of the frame.
1030 * External Glyphs:: Icons and mouse pointers for the window system.
1031 * Native GUI Widgets:: Complex active elements treated as a single glyph.
1032 * Subwindows:: Externally-controlled subwindows in buffers.
1033 @c #### Check status of subwindows ... I thought Andy implemented them.
1037 @node Creating Glyphs
1038 @subsection Creating Glyphs
1040 @defun make-glyph &optional spec-list type
1041 This function creates a new glyph object of type @var{type}.
1043 The optional @var{spec-list} is used to initialize the glyph's image.
1044 It can be any spec-list of @dfn{image instantiator} accepted by
1045 @code{canonicalize-spec-list}, @ref{Adding Specifications}. An
1046 individual image instantiator may be a string, which is converted to a
1047 vector according to @code{console-type-image-conversion-list}, or a
1048 vector. The vector's first element specifies the @emph{external} format
1049 of the data, such as a string, a PNG file.
1051 This is followed by properties (keyword-value pairs) specifying such
1052 information as the name of a file containing an image, or pixmap data
1053 directly. @xref{Image Specifiers}.
1055 The optional @var{type} specifies the type of the glyph. @var{type}
1056 should be one of @code{buffer} (used for glyphs in an extent, the
1057 modeline, the toolbar, or elsewhere in a frame), @code{pointer} (used
1058 for the mouse-pointer), or @code{icon} (used for a frame's icon), and
1059 defaults to @code{buffer}.
1062 @var{spec-list} is the initializer for the glyph's @code{image}
1063 property, which is an image specifier. (Note that @dfn{image} as used
1064 in the context of a glyph's @code{image} property or in the terms
1065 @dfn{image specifier}, @dfn{image instantiator}, or @dfn{image instance}
1066 does not refer to what people normally think of as an image (which in
1067 SXEmacs is called a @dfn{pixmap}), but to any graphical element---a
1068 pixmap, a widget, or even a block of text, when used in the places that
1071 The most common form of @var{spec-list} is a single image instantiator.
1072 (@strong{Compatibility note:} in GNU Emacs 21, a string used to
1073 instantiate an image is interpreted as the name of an image file, which
1074 is searched for and instantiated.) The conversion controlled by
1075 @code{console-type-image-conversion-list} typically attempts to look up
1076 the string as a file name in SXEmacs's data directory path, and if this
1077 fails, defaults to displaying the string as a text image instance
1078 (@emph{i.e.}. the string itself).
1080 Fine control of a particular specification is provided by using a vector
1081 as the image instantiator. More complicated instantiators allow lists
1082 of instantiators to be specified (which are tried in order), or mappings
1083 from locales to lists of instantiators, @emph{etc}. @xref{Specifiers},
1084 for more information about specification formats.
1086 As well as using @var{spec-list} to initialize the glyph, you can set
1087 specifications using @code{set-glyph-image}. The glyph itself is not
1088 actually a specifier, but rather is an object containing an image
1089 specifier (as well as other properties seldom set by user code).
1090 Therefore, you cannot set or access specifications for the glyph's image
1091 by directly using @code{set-specifier}, @code{specifier-instance} or the
1092 like on the glyph; instead use them on @code{(glyph-image @var{glyph})}
1093 or use the convenience functions @code{set-glyph-image},
1094 @code{glyph-image-instance}, and @code{glyph-image}.
1096 Glyph types reflect the fact that glyphs are used in contexts like
1097 pointers and window manager icons, which are defined by external
1098 programs such as the window system or window manager. These require
1099 somewhat different @emph{internal} format, which is opaque to the user.
1101 It is extremely rare that you will ever have to specify a value for
1102 @var{type}, which should be one of @code{buffer} (used for glyphs in an
1103 extent, the modeline, the toolbar, or elsewhere in a buffer),
1104 @code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
1105 frame's icon), and defaults to @code{buffer}. The only cases where it
1106 needs to be specified is when creating icon or pointer glyphs, and in
1107 both cases the necessary glyphs have already been created at startup and
1108 are accessed through the appropriate variables,
1109 e.g. @code{text-pointer-glyph} (or in general, any
1110 @samp{*-pointer-glyph}) and @code{frame-icon-glyph}. User code should
1111 never need to create @code{pointer} or @code{icon} glyphs. @xref{Glyph
1114 There are a few other glyph creation functions, normally used only
1115 internally or at SXEmacs initialization.
1117 @defun make-glyph-internal &optional type
1118 This function creates a new, uninitialized glyph of type @var{type}.
1121 @defun make-pointer-glyph &optional spec-list
1123 Return a new @code{pointer-glyph} object with the specification list
1124 @var{spec-list}. This function is equivalent to calling
1125 @code{make-glyph} with a @var{type} of @code{pointer}.
1128 @code{make-pointer-glyph} is normally used only by SXEmacs initialization
1129 code. It is extremely unlikely that you will ever need to create a
1130 pointer glyph. Instead, you probably want to be calling
1131 @code{set-glyph-image} on an existing glyph,
1132 e.g. @code{text-pointer-glyph}.
1134 @defun make-icon-glyph &optional spec-list
1136 Return a new @code{icon-glyph} object with the specification list
1137 @var{spec-list}. This function is equivalent to calling
1138 @code{make-glyph} with a @var{type} of @code{icon}.
1141 @code{make-icon-glyph} is normally used only by XEmacs initialization
1142 code. It is extremely unlikely that you will ever need to create a icon
1143 glyph. Instead, you probably want to be calling @code{set-glyph-image}
1144 on the existing glyph, @code{frame-icon-glyph}.
1148 @subsection Buffer Glyphs
1150 Creating a glyph using @code{make-glyph} does not specify @emph{where}
1151 the glyph will be used, it only specifies @emph{what} the glyph will
1152 look like. Once you have created a glyph, you specify where it will be
1153 used by attaching it to an extent as a @emph{begin-glyph} or
1158 To insert a glyph into a buffer, create an extent in the buffer and then
1159 use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
1160 a glyph to be displayed at the corresponding edge of the extent. (It is
1161 common to create zero-width extents for this purpose.)
1164 To insert a glyph into the left or right margin of a buffer, first
1165 make sure the margin is visible by setting a value for the specifiers
1166 @code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
1167 when using margin glyphs with layout policy @code{whitespace}.) Follow
1168 the same procedure above for inserting a glyph in a buffer, then
1169 set a non-default layout policy for the glyph using
1170 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
1171 Alternatively, use the high-level annotations API (see
1172 @code{make-annotation}). (In fact, you can also use the annotations
1173 API for glyphs in a buffer, by setting a layout policy of @code{text}.)
1178 @node Redisplay Glyphs
1179 @subsection Redisplay Glyphs
1181 To use a glyph to control the shape of miscellaneous redisplay effects
1182 such as the truncation and continuation markers, set the appropriate
1183 existing glyph variables with @code{set-glyph-image}. See
1184 @code{continuation-glyph}, @code{control-arrow-glyph},
1185 @code{hscroll-glyph}, @code{invisible-text-glyph},
1186 @code{octal-escape-glyph}, and @code{truncation-glyph}. See also
1187 @code{overlay-arrow-string}, an odd redisplay leftover which can be set
1188 to a glyph you created, and will cause the glyph to be displayed on top
1189 of the text position specified in the marker stored in
1190 @code{overlay-arrow-position}.
1192 To use a glyph in a display table (i.e. to control the appearance of any
1193 individual character), create the appropriate character glyphs and then
1194 set a specification for the specifier @code{current-display-table},
1195 which controls the appearance of characters. You can also set an
1196 overriding display table for use with text displayed in a particular
1197 face; see @code{set-face-display-table} and @code{make-display-table}.
1198 #### Note: Display tables do not currently support general Mule
1199 characters. They will be overhauled at some point to support this
1200 and to provide other features required under Mule. @ref{Display Tables}.
1202 Glyphs are not actually used as the background pixmaps of faces, but the
1204 background pixmap of a face is actually an image specifier -- probably
1205 the only place in SXEmacs where an image specifier occurs outside of a
1206 glyph. If you would like to use a glyph's image as a background pixmap,
1207 you can extract it with @code{glyph-image}, and then add it to a face.
1208 @xref{Face Convenience Functions}.
1210 @defvr Glyph truncation-glyph
1211 This variable specifies what is displayed at the end of truncated lines.
1214 @defvr Glyph continuation-glyph
1215 This variable specifies what is displayed at the end of wrapped lines.
1218 @defvr Glyph octal-escape-glyph
1219 This variable specifies what to prefix character codes displayed in octal
1223 @defvr Glyph hscroll-glyph
1224 This variable specifies what to display at the beginning of horizontally
1228 @defvr Glyph invisible-text-glyph
1229 This variable specifies what to use to indicate the presence of
1230 invisible text. This is the glyph that is displayed when an ellipsis is
1231 called for, according to @code{selective-display-ellipses} or
1232 @code{buffer-invisibility-spec}). Normally this is three dots (``...'').
1235 @defvr Glyph control-arrow-glyph
1236 This variable specifies what to use as an arrow for control characters.
1241 @subsection Frame Glyphs
1243 There are also a number of special objects whose appearance is specified
1244 by a glyph. Most of these a global objects that you update with
1245 @code{set-glyph-image}, such as mouse pointers. Frame icons, toolbar
1246 button icons, and the modeline are the main non-text objects which
1247 accept glyphs as elements.
1251 A glyph may be displayed in the modeline by inserting the glyph as one
1252 of the elements of the modeline format. (Unfortunately you can't
1253 currently put a begin glyph or end glyph on one of the modeline
1254 extents---they're ignored.)
1257 To insert a glyph into a toolbar, specify it as the icon part of a toolbar
1258 button, which in turn must be part of a toolbar instantiator (typically
1259 set on the specifier @code{default-toolbar}).
1260 See @code{default-toolbar} for more information. (As a convenience, you
1261 may use a symbol in place of the glyph list in the toolbar button
1262 instantiator; the symbol is evalled to get the glyph list. This
1263 facilitates both creating the toolbar instantiator and modifying
1264 individual glyphs in a toolbar later on. For example, you can change
1265 the way that the Mail toolbar button looks by modifying the value of the
1266 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
1267 and then calling @code{(set-specifier-dirty-flag default-toolbar)}.
1268 (#### Unfortunately this doesn't quite work the way it should; the
1269 change will appear in new frames, but not existing ones, because once an
1270 image has been displayed the pixmap replaces the symbol for those domains.)
1273 To insert a glyph into a gutter, use
1274 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
1275 glyph to be displayed at the corresponding edge of extent in a string,
1276 similar to the way you insert glyphs in a buffer. Then insert the
1277 string into the gutter @ref{Specifying a Gutter}. Glyphs that are
1278 frequently used in this way are @code{tab control} and @code{progress
1284 @node External Glyphs
1285 @subsection External Glyphs
1288 @cindex mouse cursor
1289 @cindex cursor (mouse)
1290 @cindex pointer (mouse)
1291 @cindex mouse pointer
1293 There are two special kinds of glyph that are not displayed by SXEmacs.
1294 Instead, they are used to set the appearance of iconified frames and the
1295 mouse pointer. Because these uses are constrained by the window system,
1296 icons and pointers have their own special types @xref{Glyph Types}.
1298 You may use a glyph as the icon for a frame. Do not create a new glyph;
1299 instead, change the specifications for the existing glyph
1300 @code{frame-icon-glyph} with @code{set-glyph-image}. This is a unique,
1301 predefined object. Although the natural usage is to set specifications
1302 for the global locale or a frame locale, you can also arrange for a
1303 special icon when a frame's selected window displays a particular buffer
1304 by using a buffer locale.
1306 The shape of the mouse pointer when over a particular section of a frame
1307 is controlled using various glyph variables. Since the image of a glyph
1308 is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
1309 or per-device basis.
1311 To use a glyph as the mouse pointer, in general you do not create a new
1312 glyph, but rather you change the specifications of various existing
1313 glyphs, such as @code{text-pointer-glyph} for the pointer used over
1314 text, @code{modeline-pointer-glyph} for the pointer used over the
1315 modeline, etc. Do an apropos over @samp{pointer-glyph} to find all of
1316 them. (Note also that you can temporarily set the mouse pointer to some
1317 specific shape by using @code{set-frame-pointer}, which takes an image
1318 instance, as obtained from calling @code{glyph-image-instance} on a glyph
1319 of type @code{pointer} -- either one of the above-mentioned variables or
1320 one you created yourself. (See below for what it means to create a
1321 glyph of type @code{pointer}.) This pointer will last only until the
1322 next mouse motion event is processed or certain other things happen,
1323 such as creating or deleting a window. (In fact, the above-mentioned
1324 pointer glyph variables are implemented as part of the default handler
1325 for mouse motion events. If you want to customize this behavior, take a
1326 look at @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
1327 really want to get low-level.)
1329 You should use @code{set-glyph-image} to set the following variables,
1330 @emph{not} @code{setq}.
1332 @defvr Glyph text-pointer-glyph
1333 This variable specifies the shape of the mouse pointer when over text.
1336 @defvr Glyph nontext-pointer-glyph
1337 This variable specifies the shape of the mouse pointer when over a
1338 buffer, but not over text. If unspecified in a particular domain,
1339 @code{text-pointer-glyph} is used.
1342 @defvr Glyph modeline-pointer-glyph
1343 This variable specifies the shape of the mouse pointer when over the modeline.
1344 If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
1347 @defvr Glyph selection-pointer-glyph
1348 This variable specifies the shape of the mouse pointer when over a
1349 selectable text region. If unspecified in a particular domain,
1350 @code{text-pointer-glyph} is used.
1353 @defvr Glyph gc-pointer-glyph
1354 This variable specifies the shape of the mouse pointer when a garbage
1355 collection is in progress. If the selected window is on a window system
1356 and this glyph specifies a value (i.e. a pointer image instance) in the
1357 domain of the selected window, the pointer will be changed as specified
1358 during garbage collection. Otherwise, a message will be printed in the
1359 echo area, as controlled by @code{gc-message}.
1362 @defvr Glyph busy-pointer-glyph
1363 This variable specifies the shape of the mouse pointer when SXEmacs is busy.
1364 If unspecified in a particular domain, the pointer is not changed
1365 when SXEmacs is busy.
1368 @defvr Glyph menubar-pointer-glyph
1369 This variable specifies the shape of the mouse pointer when over the
1370 menubar. If unspecified in a particular domain, the
1371 window-system-provided default pointer is used.
1374 @defvr Glyph scrollbar-pointer-glyph
1375 This variable specifies the shape of the mouse pointer when over a
1376 scrollbar. If unspecified in a particular domain, the
1377 window-system-provided default pointer is used.
1380 @defvr Glyph toolbar-pointer-glyph
1381 This variable specifies the shape of the mouse pointer when over a
1382 toolbar. If unspecified in a particular domain,
1383 @code{nontext-pointer-glyph} is used.
1386 Internally, these variables are implemented in
1387 @code{default-mouse-motion-handler}, and thus only take effect when the
1388 mouse moves. That function calls @code{set-frame-pointer}, which sets
1389 the current mouse pointer for a frame.
1391 @defun set-frame-pointer frame image-instance
1392 This function sets the mouse pointer of @var{frame} to the given pointer
1393 image instance. You should not call this function directly.
1394 (If you do, the pointer will change again the next time the mouse moves.)
1398 @node Native GUI Widgets
1399 @subsection Native GUI Widgets
1400 @cindex native widget
1402 A ``native widget'' is a primitive GUI object defined either by the host
1403 GUI platform or an external toolkit, and accessed from Lisp as a
1407 * Introduction to Widgets:: Native widgets provide tight integration of
1408 GUI features with the platform GUI.
1409 * Lisp API to Native Widgets:: Native widgets are glyphs.
1410 * Layouts:: Specifying composite widgets from Lisp.
1411 * Primitive Widgets:: Catalogue of available native widgets.
1414 @node Introduction to Widgets
1415 @subsubsection Introduction to Native Widgets and Subwindow Glyphs
1417 Traditionally Emacsen have hidden the GUI apparatus from the Lisp
1418 programmer, but in SXEmacs 22.1 the ability to embed autonomous GUI
1419 objects, called @dfn{native widgets}, in text was added to Lisp. They
1420 are handled as @emph{glyphs}. Unlike traditional XEmacs
1421 glyphs such images and strings, native widgets are opaque to SXEmacs, and
1422 must be able to redraw themselves because they are implemented as
1423 subwindows, not as graphics drawn by SXEmacs into the text window.
1425 Primitive widgets are coded in C using the underlying GUI toolkit, and
1426 thus are beyond the scope of the @emph{SXEmacs Lisp Reference Manual}.
1427 However, composite widgets can be created in Lisp using ``layouts,''
1428 which are horizontal or vertical arrays of subwidgets. For example, the
1429 search dialog is formatted using layouts.
1432 @node Lisp API to Native Widgets
1433 @subsubsection Lisp API to Native Widgets
1435 Native widgets are manipulated as @emph{glyphs} (@pxref{Glyphs}). Thus
1436 they are created using @code{make-glyph}, with a format of one of the
1437 widget types and a @code{:data} property specific to the widget being
1440 However, there is a technical difference between widgets and other kinds
1441 of glyphs that is theoretically important. Because widgets
1442 are active (that is, they can respond to user input events themselves),
1443 it is possible for the user to become aware that two appearances of the
1444 ``same'' glyph are actually separate instances. For example, if a user
1445 changes an image glyph from red to blue, and the buffer containing the
1446 glyph appears in more than one window, the user will perceive all the
1447 appearances to change from red to blue simultaneously.
1449 However, suppose the glyph is a button glyph (@emph{e.g.}, as used in
1450 the Customize buffer for the Set, Save, and Done buttons). Then if the
1451 Customize buffer appears in several windows at the same time, and the
1452 user clicks on the button, she will only perceive the button to be
1453 depressed in the window where she clicked the button.
1455 It seems from this example that it is unlikely to be a problem in
1456 practice. When the user is faced with an active widget, it seems likely
1457 that attention will focus on the widget being manipulated, and having
1458 other instances of the widget respond simultaneously might be more
1459 disconcerting than the actual case.
1463 @subsubsection Layouts
1465 A SXEmacs @dfn{layout} is a one-dimensional array of glyphs. It is a
1466 widget for controlling the positioning of children underneath it.
1467 Through the use of nested layouts, a widget hierarchy can be created
1468 which can have the appearance of any standard dialog box or similar
1469 arrangement; all of this is counted as one "glyph" and could appear in
1470 many of the places that expect a single glyph.
1472 (There are also @dfn{native layouts}, but these are undocumented, as are
1475 A layout descriptor is an image instantiator, @emph{i.e.}, a vector of
1476 the form @samp{[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]} with format
1477 @code{layout}, and properties
1479 @c #### need defaults for these
1482 Specifies the orientation of the contained array of glyphs. The value
1483 must be one of the symbols @code{horizontal} or @code{vertical}.
1485 @item :horizontally-justify
1486 Specifies the horizontal justification of the items in the array. The
1487 value must be one of the symbols @code{:right}, @code{:center}, or
1490 @item :vertically-justify
1491 Specifies the vertical justification of the items in the array. The
1492 value must be one of the symbols @code{:top}, @code{:center}, or
1496 Specifies justification. #### not understood.
1499 A glyph to place in the border. The value must be an image
1503 The glyphs controlled by the layout. The value must be a list of image
1507 Here is the specification of the search dialog widget created by
1508 @code{make-search-dialog} in the @file{dialog-items} library, which
1509 makes use of recursive layouts.
1514 :orientation horizontal
1515 :vertically-justify top
1516 :horizontally-justify center
1517 :border [string :data "Search"]
1519 ([layout :orientation vertical
1520 :justify top ; implies left also
1522 ([string :data "Search for:"]
1523 [button :descriptor "Match Case"
1525 :selected (not case-fold-search)
1526 :callback (setq case-fold-search
1527 (not case-fold-search))]
1528 [button :descriptor "Regular Expression"
1530 :selected search-dialog-regexp
1531 :callback (setq search-dialog-regexp
1532 (not search-dialog-regexp))]
1533 [button :descriptor "Forwards"
1535 :selected search-dialog-direction
1536 :callback (setq search-dialog-direction t)]
1537 [button :descriptor "Backwards"
1539 :selected (not search-dialog-direction)
1540 :callback (setq search-dialog-direction nil)]
1542 [layout :orientation vertical
1543 :vertically-justify top
1544 :horizontally-justify right
1546 ([edit-field :width 15 :descriptor "" :active t
1548 [button :width 10 :descriptor "Find Next"
1550 (lambda (image-instance event)
1551 (search-dialog-callback ,parent
1554 [button :width 10 :descriptor "Cancel"
1556 (lambda (image-instance event)
1557 (isearch-dehighlight)
1559 (event-channel event)))])])])
1563 @node Primitive Widgets
1564 @subsubsection Primitive Widgets
1566 @c #### the following table should be replaced with a menu of nodes
1569 A button widget; either a push button, radio button or toggle
1573 A drop list of selectable items in a widget, for editing text.
1576 A text editing widget.
1579 A static, text-only, widget; for displaying text.
1581 @item progress-gauge
1582 A sliding widget, for showing progress.
1585 A tab widget; a series of user selectable tabs.
1591 A scrollbar widget. (#### Probably not the same as the scrollbar
1592 controlling an SXEmacs window.)
1597 @subsection Subwindows
1599 Subwindows are not currently implemented.
1600 @c #### Check status of subwindows ... I thought Andy implemented them.
1602 @defun subwindowp object
1603 This function returns non-@code{nil} if @var{object} is a subwindow.
1607 @node Manipulating Glyphs
1608 @section Manipulating Glyphs
1610 Each glyphs has properties that may be accessed. Most of these can
1611 also be set after the glyph is initialized, with the exception of the
1612 glyph's type. This is not a real restriction, as it is almost never
1613 useful to create glyphs of types other than @code{buffer}.
1616 * Glyph Properties:: Accessing and modifying a glyph's properties.
1617 * Glyph Convenience Functions:: Accessing particular properties of a glyph.
1618 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
1619 * Glyph Types:: Each glyph has a particular type.
1623 @node Glyph Properties
1624 @subsection Glyph Properties
1626 Each glyph has a list of properties, which control all of the aspects of
1627 the glyph's appearance. The following symbols have predefined meanings:
1631 The image used to display the glyph.
1634 Percent above baseline that glyph is to be displayed. Only for glyphs
1635 displayed inside of a buffer.
1638 Whether the glyph contributes to the height of the line it's on.
1639 Only for glyphs displayed inside of a buffer.
1642 Face of this glyph (@emph{not} a specifier).
1645 @defun set-glyph-property glyph property value &optional locale tag-set how-to-add
1646 This function changes a property of a @var{glyph}.
1648 For built-in properties, the actual value of the property is a specifier
1649 and you cannot change this; but you can change the specifications within
1650 the specifier, and that is what this function will do. The glyph face
1651 is an exception; it is a face name (a symbol) or a face object, not a
1652 specifier. (The face properties themselves are typically specifiers.)
1653 For user-defined properties, you can use this function to either change
1654 the actual value of the property or, if this value is a specifier,
1655 change the specifications within it.
1657 If @var{property} is a built-in property, the specifications to be added
1658 to this property can be supplied in many different ways:
1662 If @var{value} is a simple instantiator (e.g. a string naming a pixmap
1663 filename) or a list of instantiators, then the instantiator(s) will be
1664 added as a specification of the property for the given @var{locale}
1665 (which defaults to @code{global} if omitted).
1668 If @var{value} is a list of specifications (each of which is a cons of a
1669 locale and a list of instantiators), then @var{locale} must be
1670 @code{nil} (it does not make sense to explicitly specify a locale in
1671 this case), and specifications will be added as given.
1674 If @var{value} is a specifier (as would be returned by
1675 @code{glyph-property} if no @var{locale} argument is given), then some
1676 or all of the specifications in the specifier will be added to the
1677 property. In this case, the function is really equivalent to
1678 @code{copy-specifier} and @var{locale} has the same semantics (if it is
1679 a particular locale, the specification for the locale will be copied; if
1680 a locale type, specifications for all locales of that type will be
1681 copied; if @code{nil} or @code{all}, then all specifications will be
1685 @var{how-to-add} should be either @code{nil} or one of the symbols
1686 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
1687 @code{remove-tag-set-append}, @code{remove-locale},
1688 @code{remove-locale-type}, or @code{remove-all}. See
1689 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
1690 of what each of these means. Most of the time, you do not need to worry
1691 about this argument; the default behavior usually is fine.
1693 In general, it is OK to pass an instance object (e.g. as returned by
1694 @code{glyph-property-instance}) as an instantiator in place of an actual
1695 instantiator. In such a case, the instantiator used to create that
1696 instance object will be used (for example, if you set a font-instance
1697 object as the value of the @code{font} property, then the font name used
1698 to create that object will be used instead). In some cases, however,
1699 doing this conversion does not make sense, and this will be noted in the
1700 documentation for particular types of instance objects.
1702 If @var{property} is not a built-in property, then this function will
1703 simply set its value if @var{locale} is @code{nil}. However, if
1704 @var{locale} is given, then this function will attempt to add
1705 @var{value} as the instantiator for the given @var{locale}, using
1706 @code{add-spec-to-specifier}. If the value of the property is not a
1707 specifier, it will automatically be converted into a @code{generic}
1711 @defun glyph-property glyph property &optional locale
1712 This function returns @var{glyph}'s value of the given @var{property}.
1714 If @var{locale} is omitted, the @var{glyph}'s actual value for
1715 @var{property} will be returned. For built-in properties, this will be
1716 a specifier object of a type appropriate to the property (e.g. a font or
1717 color specifier). For other properties, this could be anything.
1719 If @var{locale} is supplied, then instead of returning the actual value,
1720 the specification(s) for the given locale or locale type will be
1721 returned. This will only work if the actual value of @var{property} is
1722 a specifier (this will always be the case for built-in properties, but
1723 may or may not apply to user-defined properties). If the actual value
1724 of @var{property} is not a specifier, this value will simply be returned
1725 regardless of @var{locale}.
1727 The return value will be a list of instantiators (e.g. vectors
1728 specifying pixmap data), or a list of specifications, each of which is a
1729 cons of a locale and a list of instantiators. Specifically, if
1730 @var{locale} is a particular locale (a buffer, window, frame, device, or
1731 @code{global}), a list of instantiators for that locale will be
1732 returned. Otherwise, if @var{locale} is a locale type (one of the
1733 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
1734 the specifications for all locales of that type will be returned.
1735 Finally, if @var{locale} is @code{all}, the specifications for all
1736 locales of all types will be returned.
1738 The specifications in a specifier determine what the value of
1739 @var{property} will be in a particular @dfn{domain} or set of
1740 circumstances, which is typically a particular Emacs window along with
1741 the buffer it contains and the frame and device it lies within. The
1742 value is derived from the instantiator associated with the most specific
1743 locale (in the order buffer, window, frame, device, and @code{global})
1744 that matches the domain in question. In other words, given a domain
1745 (i.e. an Emacs window, usually), the specifier for @var{property} will
1746 first be searched for a specification whose locale is the buffer
1747 contained within that window; then for a specification whose locale is
1748 the window itself; then for a specification whose locale is the frame
1749 that the window is contained within; etc. The first instantiator that
1750 is valid for the domain (usually this means that the instantiator is
1751 recognized by the device [i.e. the X server or TTY device] that the
1752 domain is on). The function @code{glyph-property-instance} actually does
1753 all this, and is used to determine how to display the glyph.
1756 @defun glyph-property-instance glyph property &optional domain default no-fallback
1757 This function returns the instance of @var{glyph}'s @var{property} in the
1758 specified @var{domain}.
1760 Under most circumstances, @var{domain} will be a particular window, and
1761 the returned instance describes how the specified property actually is
1762 displayed for that window and the particular buffer in it. Note that
1763 this may not be the same as how the property appears when the buffer is
1764 displayed in a different window or frame, or how the property appears in
1765 the same window if you switch to another buffer in that window; and in
1766 those cases, the returned instance would be different.
1768 The returned instance is an image-instance object, and you can query it
1769 using the appropriate image instance functions. For example, you could use
1770 @code{image-instance-depth} to find out the depth (number of color
1771 planes) of a pixmap displayed in a particular window. The results might
1772 be different from the results you would get for another window (perhaps
1773 the user specified a different image for the frame that window is on; or
1774 perhaps the same image was specified but the window is on a different X
1775 server, and that X server has different color capabilities from this
1778 @var{domain} defaults to the selected window if omitted.
1780 @var{domain} can be a frame or device, instead of a window. The value
1781 returned for such a domain is used in special circumstances when a
1782 more specific domain does not apply; for example, a frame value might be
1783 used for coloring a toolbar, which is conceptually attached to a frame
1784 rather than a particular window. The value is also useful in
1785 determining what the value would be for a particular window within the
1786 frame or device, if it is not overridden by a more specific
1789 If @var{property} does not name a built-in property, its value will
1790 simply be returned unless it is a specifier object, in which case it
1791 will be instanced using @code{specifier-instance}.
1793 Optional arguments @var{default} and @var{no-fallback} are the same as
1794 in @code{specifier-instance}. @xref{Specifiers}.
1797 @defun remove-glyph-property glyph property &optional locale tag-set exact-p
1798 This function removes a property from a glyph. For built-in properties,
1799 this is analogous to @code{remove-specifier}. @xref{Specifiers,
1800 remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
1801 and @var{exact-p} arguments.
1805 @node Glyph Convenience Functions
1806 @subsection Glyph Convenience Functions
1808 The following functions are provided for working with specific
1809 properties of a glyph. Note that these are exactly like calling
1810 the general functions described above and passing in the
1811 appropriate value for @var{property}.
1813 Remember that if you want to determine the ``value'' of a
1814 specific glyph property, you probably want to use the @code{*-instance}
1815 functions. For example, to determine whether a glyph contributes
1816 to its line height, use @code{glyph-contrib-p-instance}, not
1817 @code{glyph-contrib-p}. (The latter will return a boolean specifier
1818 or a list of specifications, and you probably aren't concerned with
1821 @defun glyph-image glyph &optional locale
1822 This function is equivalent to calling @code{glyph-property} with
1823 a property of @code{image}. The return value will be an image
1824 specifier if @var{locale} is @code{nil} or omitted; otherwise,
1825 it will be a specification or list of specifications.
1828 @defun set-glyph-image glyph spec &optional locale tag-set how-to-add
1829 This function is equivalent to calling @code{set-glyph-property} with
1830 a property of @code{image}.
1833 @defun glyph-image-instance glyph &optional domain default no-fallback
1834 This function returns the instance of @var{glyph}'s image in the given
1835 @var{domain}, and is equivalent to calling
1836 @code{glyph-property-instance} with a property of @code{image}. The
1837 return value will be an image instance.
1839 Normally @var{domain} will be a window or @code{nil} (meaning the
1840 selected window), and an instance object describing how the image
1841 appears in that particular window and buffer will be returned.
1844 @defun glyph-contrib-p glyph &optional locale
1845 This function is equivalent to calling @code{glyph-property} with
1846 a property of @code{contrib-p}. The return value will be a boolean
1847 specifier if @var{locale} is @code{nil} or omitted; otherwise,
1848 it will be a specification or list of specifications.
1851 @defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
1852 This function is equivalent to calling @code{set-glyph-property} with
1853 a property of @code{contrib-p}.
1856 @defun glyph-contrib-p-instance glyph &optional domain default no-fallback
1857 This function returns whether the glyph contributes to its line height
1858 in the given @var{domain}, and is equivalent to calling
1859 @code{glyph-property-instance} with a property of @code{contrib-p}. The
1860 return value will be either @code{nil} or @code{t}. (Normally @var{domain}
1861 will be a window or @code{nil}, meaning the selected window.)
1864 @defun glyph-baseline glyph &optional locale
1865 This function is equivalent to calling @code{glyph-property} with a
1866 property of @code{baseline}. The return value will be a specifier if
1867 @var{locale} is @code{nil} or omitted; otherwise, it will be a
1868 specification or list of specifications.
1871 @defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
1872 This function is equivalent to calling @code{set-glyph-property} with
1873 a property of @code{baseline}.
1876 @defun glyph-baseline-instance glyph &optional domain default no-fallback
1877 This function returns the instance of @var{glyph}'s baseline value in
1878 the given @var{domain}, and is equivalent to calling
1879 @code{glyph-property-instance} with a property of @code{baseline}. The
1880 return value will be an integer or @code{nil}.
1882 Normally @var{domain} will be a window or @code{nil} (meaning the
1883 selected window), and an instance object describing the baseline value
1884 appears in that particular window and buffer will be returned.
1887 @defun glyph-face glyph
1888 This function returns the face of @var{glyph}. (Remember, this is
1889 not a specifier, but a simple property.)
1892 @defun set-glyph-face glyph face
1893 This function changes the face of @var{glyph} to @var{face}.
1897 @node Glyph Dimensions
1898 @subsection Glyph Dimensions
1900 @defun glyph-width glyph &optional window
1901 This function returns the width of @var{glyph} on @var{window}. This
1902 may not be exact as it does not take into account all of the context
1903 that redisplay will.
1906 @defun glyph-ascent glyph &optional window
1907 This function returns the ascent value of @var{glyph} on @var{window}.
1908 This may not be exact as it does not take into account all of the
1909 context that redisplay will.
1912 @defun glyph-descent glyph &optional window
1913 This function returns the descent value of @var{glyph} on @var{window}.
1914 This may not be exact as it does not take into account all of the
1915 context that redisplay will.
1918 @defun glyph-height glyph &optional window
1919 This function returns the height of @var{glyph} on @var{window}. (This
1920 is equivalent to the sum of the ascent and descent values.) This may
1921 not be exact as it does not take into account all of the context that
1927 @subsection Glyph Types
1929 Each glyph has a particular type, which controls how the glyph's image
1930 is generated. Each glyph type has a corresponding list of allowable
1931 image instance types that can be generated. When you call
1932 @code{glyph-image-instance} to retrieve the image instance of a glyph,
1933 XEmacs does the equivalent of calling @code{make-image-instance} and
1934 passing in @var{dest-types} the list of allowable image instance types
1935 for the glyph's type.
1939 @code{buffer} glyphs can be used as the begin-glyph or end-glyph of an
1940 extent, in the modeline, and in the toolbar. Their image can be
1941 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
1942 @code{text}, and @code{subwindow}.
1943 @c #### Check status of subwindows ... I thought Andy implemented them.
1946 @code{pointer} glyphs can be used to specify the mouse pointer. Their
1947 image can be instantiated as @code{pointer}.
1950 @code{icon} glyphs can be used to specify the icon used when a frame is
1951 iconified. Their image can be instantiated as @code{mono-pixmap} and
1952 @code{color-pixmap}.
1955 @defun glyph-type glyph
1956 This function returns the type of the given glyph. The return value
1957 will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}.
1960 @defun valid-glyph-type-p glyph-type
1961 Given a @var{glyph-type}, this function returns non-@code{nil} if it is
1965 @defun glyph-type-list
1966 This function returns a list of valid glyph types.
1969 @defun buffer-glyph-p object
1970 This function returns non-@code{nil} if @var{object} is a glyph of type
1974 @defun icon-glyph-p object
1975 This function returns non-@code{nil} if @var{object} is a glyph of type
1979 @defun pointer-glyph-p object
1980 This function returns non-@code{nil} if @var{object} is a glyph of type
1985 @node Glyph Examples
1986 @section Glyph Examples
1988 For many applications, displaying graphics is a simple process: you
1989 create a glyph, and then you insert it into a buffer.
1991 The easiest way to create a glyph is to use a file that contains a
1992 graphical image, such as a JPEG, TIFF, or PNG file:
1995 ;; Create a glyph from a JPEG file:
1996 (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
2000 ;; Create a glyph from a XPM file:
2001 (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
2005 ;; Create a glyph from a PNG file:
2006 (setq foo (make-glyph [png :file "/tmp/file3.png"]))
2010 ;; Create a glyph from a TIFF file:
2011 (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
2014 The parameters passed to @code{make-glyph} are called "Image
2015 Specifiers", and can handle more image types than those shown above.
2016 You can also put the raw image data into a string (e.g., if you put the
2017 contents of a JPEG file into a string), and use that to create a glyph.
2018 @xref{Image Specifiers}, for more information.
2021 @strong{Caution}: In order for SXEmacs to read a particular graphics file
2022 format, support for that format must have been compiled into SXEmacs.
2023 It's possible, although somewhat unlikely, for SXEmacs to have been
2024 compiled without support for any of the various graphics file formats.
2025 To see what graphics formats your particular version of SXEmacs supports,
2026 use @kbd{M-x describe-installation}.
2028 To programmatically query whether or not a particular file format is
2029 supported, you can use the @code{featurep} function, with one of:
2030 @code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm},
2031 @code{png}, or @code{xface}. For an up-to-date list, @ref{Image
2032 Specifiers}. Example:
2035 ;; Returns `t' if TIFF is supported:
2042 ;; Returns a list of `t' or `nil', depending on whether or not the
2043 ;; corresponding feature is supported:
2044 (mapcar #'(lambda (format-symbol) (featurep format-symbol))
2045 '(gif tiff jpeg xpm png))
2050 Once you have a glyph, you can then insert it into a buffer. Example:
2053 ;; Use this function to insert a glyph at the left edge of point in the
2054 ;; current buffer. Any existing glyph at this location is replaced.
2055 (defun insert-glyph (gl)
2056 "Insert a glyph at the left edge of point."
2057 (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen
2058 ;; to (hopefully) not conflict with any
2059 ;; other properties. Change it if
2062 ;; First, check to see if one of our extents already exists at
2063 ;; point. For ease-of-programming, we are creating and using our
2064 ;; own extents (multiple extents are allowed to exist/overlap at the
2065 ;; same point, and it's quite possible for other applications to
2066 ;; embed extents in the current buffer without your knowledge).
2067 ;; Basically, if an extent, with the property stored in "prop",
2068 ;; exists at point, we assume that it is one of ours, and we re-use
2069 ;; it (this is why it is important for the property stored in "prop"
2070 ;; to be unique, and only used by us).
2071 (if (not (setq extent (extent-at (point) (current-buffer) prop)))
2073 ;; If an extent does not already exist, create a zero-length
2074 ;; extent, and give it our special property.
2075 (setq extent (make-extent (point) (point) (current-buffer)))
2076 (set-extent-property extent prop t)
2078 ;; Display the glyph by storing it as the extent's "begin-glyph".
2079 (set-extent-property extent 'begin-glyph gl)
2082 ;; You can then use this function like:
2083 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
2084 ;; This will insert the glyph at point.
2086 ;; Here's an example of how to insert two glyphs side-by-side, at point
2087 ;; (using the above code):
2089 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
2090 ;; Create a new extent at point. We can't simply call "insert-glyph",
2091 ;; as "insert-glyph" will simply replace the first glyph with the
2093 (setq extent (make-extent (point) (point) (current-buffer)))
2094 ;; Here, we're only setting the 'myimage property in case we need
2095 ;; to later identify/locate/reuse this particular extent.
2096 (set-extent-property extent 'myimage t)
2097 (set-extent-property extent 'begin-glyph
2098 (make-glyph [jpeg :file "/tmp/file2.jpg"]))
2103 Here are the gory details:
2108 Glyphs are displayed by attaching them to extents (see @ref{Extents}),
2109 either to the beginning or the end of extents.
2111 Note that extents can be used for many things, and not just for
2112 displaying images (although, in the above example, we are creating our
2113 own extent for the sole purpose of displaying an image). Also, note
2114 that multiple extents are allowed to exist at the same position, and
2118 Glyphs are often displayed inside the text area (alongside text). This
2121 Although glyphs can also be displayed in the margins, how to do this
2122 will not be described here. For more information on this, see
2123 @ref{Annotation Basics} (look for information on "layout types") and
2124 @ref{Extent Properties} (look for @code{begin-glyph-layout} and
2125 @code{end-glyph-layout}).
2128 The easiest way to insert a glyph into text is to create a zero-length
2129 extent at the point where you want the glyph to appear.
2131 Note that zero-length extents are attached to the character to the
2132 right of the extent; deleting this character will also delete the extent.
2135 It's often a good idea to assign a unique property to the newly-created
2136 extent, in case you later want to locate it, and replace any existing
2137 glyph with a different one (or just delete the existing one). In the
2138 above example, we are using "myimage" as our (hopefully) unique property
2141 If you need to locate all of the extents, you'll have to use functions
2142 like @code{extent-list} or @code{next-extent}, or provide additional
2143 parameters to the @code{extent-at} function. Assigning a unique
2144 property to the extent makes it easy to locate your extents; for
2145 example, @code{extent-list} can return only those extents with a
2146 particular property. @xref{Finding Extents}, and @ref{Mapping Over
2147 Extents}, for more information.
2150 Glyphs are displayed by assigning then to the @code{begin-glyph} or
2151 @code{end-glyph} property of the extent. For zero-length extents, it
2152 doesn't really matter if you assign the glyph to the @code{begin-glyph}
2153 or @code{end-glyph} property, as they are both at the same location;
2154 however, for non-zero-length extents (extents that cover one or more
2155 characters of text), it does matter which one you use.
2157 Assigning @code{nil} to the @code{begin-glyph} or @code{end-glyph}
2158 property will delete any existing glyph. In this case, you may also
2159 want to delete the extent, assuming that the extent is used for no other
2163 If you happen to insert two glyphs, side-by-side, note that the example
2164 @code{insert-glyph} function will have trouble, if it's again used at
2165 the same point (it can only locate one of the two extents).
2166 @xref{Finding Extents}, and @ref{Mapping Over Extents}, for more
2167 information on locating extents in a buffer.
2170 Among other things, glyphs provide a way of displaying graphics
2171 alongside text. Note, however, that glyphs only provide a way of
2172 displaying graphics; glyphs are not actually part of the text, and are
2173 only displayed alongside the text. If you save the text in the buffer,
2174 the graphics are not saved. The low-level glyph code does not provide a
2175 way of saving graphics with the text. If you need to save graphics and
2176 text, you have to write your own code to do this, and this topic is
2177 outside the scope of this discussion.