|
428
|
1 @c -*-texinfo-*-
|
|
|
2 @c This is part of the XEmacs Lisp Reference Manual.
|
|
|
3 @c Copyright (C) 1995, 1996 Ben Wing.
|
|
|
4 @c See the file lispref.texi for copying conditions.
|
|
|
5 @setfilename ../../info/glyphs.info
|
|
|
6 @node Glyphs, Annotations, Faces and Window-System Objects, top
|
|
|
7 @chapter Glyphs
|
|
|
8 @cindex glyphs
|
|
|
9
|
|
2182
|
10 A @dfn{glyph} is an object that is used for pixmaps, widgets, and
|
|
442
|
11 images of all sorts, as well as for things that ``act'' like pixmaps,
|
|
|
12 such as non-textual strings (@dfn{annotations}) displayed in a buffer or
|
|
|
13 in the margins. It is used in begin-glyphs and end-glyphs attached to
|
|
|
14 extents, marginal and textual annotations, overlay arrows
|
|
|
15 (@code{overlay-arrow-*} variables), toolbar buttons, mouse pointers,
|
|
|
16 frame icons, truncation and continuation markers, and the
|
|
2182
|
17 like. Basically, any place there is an image or something that acts
|
|
|
18 like an image, there will be a glyph object representing it.
|
|
428
|
19
|
|
|
20 @defun glyphp object
|
|
|
21 This function returns @code{t} if @var{object} is a glyph.
|
|
|
22 @end defun
|
|
|
23
|
|
|
24 @menu
|
|
2182
|
25 * Glyph Intro:: Glyphs are abstract image specifications.
|
|
|
26 * Images:: Specifying the appearance of glyphs.
|
|
|
27 * Using Glyphs:: Creating and displaying glyphs.
|
|
|
28 * Manipulating Glyphs:: Getting and setting glyph properties.
|
|
|
29 * Glyph Examples:: Examples of how to work with glyphs.
|
|
|
30 @end menu
|
|
|
31
|
|
|
32
|
|
|
33 @node Glyph Intro
|
|
|
34 @section Glyph Introduction
|
|
|
35
|
|
|
36 In XEmacs, ``glyph'' does @strong{not} refer to a single unit of textual
|
|
|
37 display (the XEmacs term for that is @dfn{rune}, and runes are confined
|
|
|
38 to the internal implementation of redisplay), but rather is an
|
|
|
39 object encapsulating a graphical element, such as an image or widget (an
|
|
|
40 active GUI element such as a button or text entry field; X11 calls this a
|
|
|
41 @dfn{widget}, while MS Windows uses the term @dfn{control}).
|
|
|
42 This graphical element could appear in a buffer, a margin, a gutter, or
|
|
|
43 a toolbar, or even externally to XEmacs as a mouse pointer or an icon,
|
|
|
44 for example.
|
|
|
45
|
|
|
46 On the other hand, by contrast with GNU Emacs 21, an XEmacs glyph is
|
|
|
47 not ``just'' an image. The actual image that is displayed (as opposed
|
|
|
48 to its position or clipping) is defined by an ``image specifier'' object
|
|
|
49 contained within the glyph. The separation between an image specifier
|
|
|
50 object and a glyph object is made because the glyph includes other
|
|
|
51 properties than just the actual image: e.g. the face it is displayed in,
|
|
|
52 the alignment of the image, @emph{etc}. Also, an image specifier is
|
|
|
53 used in at least one place in XEmacs in lieu of a glyphs, namely the
|
|
|
54 backing pixmap of a face.
|
|
|
55
|
|
|
56 An image specifier is used because glyphs often have locale-specific
|
|
|
57 semantics. The most important example is semantics determined by the
|
|
|
58 display device: you can't usefully display a JPEG on stdout, or a color
|
|
|
59 image on a monochrome display. But because the image property is a
|
|
|
60 specifier in XEmacs, you can specify that a given glyph appear as a
|
|
|
61 monochrome image on monochrome displays, a color image on color
|
|
|
62 displays, and as a string on TTYs. (Specifying a string for the
|
|
|
63 @code{tty} device locale would give behavior like the @code{ALT}
|
|
|
64 attribute of an @code{IMG} element in HTML.) Another is semantics
|
|
|
65 determined by the buffer or mode. (Unfortunately, currently there are
|
|
|
66 no compelling examples of this for glyphs.)
|
|
|
67
|
|
|
68 All this means that only one global glyph needs to exist for a
|
|
|
69 particular purpose (e.g. the icon used to represent an iconified frame,
|
|
|
70 the mouse pointer used over particular areas of a frame, etc.). Often
|
|
|
71 you need not (and should not!) create your own glyph, but rather modify
|
|
|
72 an existing one.
|
|
|
73
|
|
|
74 In working with glyphs it is important to keep in mind the distinction
|
|
|
75 between a locale and a domain. A @dfn{locale} is specified by the
|
|
|
76 programmer, and is an abstract link between a specification (for a
|
|
|
77 glyph, its visual appearance) and a displayable object. The displayable
|
|
|
78 object may be a buffer or a window, or an object containing buffers or
|
|
|
79 windows such as frame, device, or console. A @dfn{domain} is an actual
|
|
|
80 display context, which must be concrete enough to enable XEmacs to
|
|
|
81 identify the device type. (Buffers may be displayed in windows on
|
|
|
82 different devices, even simultaneously, so a buffer cannot be a domain.
|
|
|
83 Similarly, the global locale cannot be a domain.) @ref{Specifiers}, for
|
|
|
84 more information about specifier locales and domains.
|
|
|
85
|
|
|
86
|
|
|
87 @node Images
|
|
|
88 @section Images
|
|
|
89
|
|
|
90 @menu
|
|
2953
|
91 * Image Instantiators:: Specifying an image's appearance.
|
|
2182
|
92 * Image Instantiator Conversion:: Lazy realization of graphics.
|
|
|
93 * Image Instantiator Formats:: A catalog of image descriptors.
|
|
|
94 * Image Instances:: Classes of graphical objects.
|
|
428
|
95 @end menu
|
|
|
96
|
|
2182
|
97
|
|
2953
|
98 @node Image Instantiators
|
|
|
99 @subsection Image Instantiators
|
|
|
100 @cindex image instantiators
|
|
2182
|
101
|
|
2953
|
102 An @dfn{image instantiator} is a description of the actual graphical
|
|
2182
|
103 realization of a glyph. For example, a typical image description is
|
|
|
104 @emph{the file system path to a PNG file}. Since redisplay doesn't know
|
|
|
105 about files, and in any case the image may need to be manipulated
|
|
|
106 (@emph{e.g.}, a face's background pixmap must be clipped and tiled), the
|
|
|
107 PNG file must be converted internally to a window system bitmap or
|
|
|
108 pixmap object. We describe this process by writing that when XEmacs
|
|
2953
|
109 displays the image, it @dfn{instantiates} the image instantiator
|
|
2182
|
110 into an @dfn{image instance}. Image instances are an internal object
|
|
|
111 type (similar to font instances and color instances), describing how the
|
|
|
112 image appears in a particular domain. On the other hand, image
|
|
|
113 instantiators, which are just descriptions of how the image should
|
|
|
114 appear, are represented using Lisp strings or vectors.
|
|
|
115
|
|
|
116 Furthermore the graphical realization will vary, and for some devices
|
|
2953
|
117 may not even be a bitmapped graphic. These variations may be
|
|
|
118 controlled by the program by specifying different instantiators in
|
|
2182
|
119 different locales. This is implemented with an @dfn{image specifier},
|
|
|
120 a specifier whose specifications are image instantiators.
|
|
|
121
|
|
|
122 Image specifiers are rarely if ever found by themselves. However, an
|
|
|
123 image specifier results from calling @code{glyph-image} on a glyph, or
|
|
|
124 retrieving the @code{background-pixmap} property of a face, and you can
|
|
|
125 check if some random object is an image specifier.
|
|
|
126
|
|
|
127 @defun image-specifier-p object
|
|
|
128 This function returns non-@code{nil} if @var{object} is an image specifier.
|
|
|
129 @end defun
|
|
|
130
|
|
|
131 @defun make-image-specifier spec-list
|
|
|
132 This function creates a new image specifier object and initializes it
|
|
|
133 according to @var{spec-list}. @xref{Specifiers}.
|
|
|
134 @end defun
|
|
|
135
|
|
|
136 This function exists mainly for completeness. In practice, you rarely,
|
|
|
137 if ever, need to actually create an image specifier. Instead, they are
|
|
|
138 implicitly created by the initialization of glyphs and faces, and the
|
|
|
139 specifier member of these objects cannot be changed after
|
|
|
140 initialization; you may only set the specifications it contains.
|
|
|
141
|
|
|
142 Image instantiators come in many formats: @code{xbm}, @code{xpm},
|
|
|
143 @code{gif}, @code{jpeg}, etc. These denote the format of the data
|
|
|
144 describing the image. The resulting image instances also come in many
|
|
|
145 types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
|
|
|
146 @code{pointer}, etc. This refers to the behavior of the image and the
|
|
|
147 sorts of places it can appear. (For example, a color-pixmap image has
|
|
|
148 fixed colors specified for it, while a mono-pixmap image comes in two
|
|
|
149 unspecified shades ``foreground'' and ``background'' that are determined
|
|
|
150 from the face of the glyph or surrounding text; a text image appears as
|
|
|
151 a string of text and has an unspecified foreground, background, and
|
|
|
152 font; a pointer image behaves like a mono-pixmap image but can only be
|
|
|
153 used as a mouse pointer [mono-pixmap images cannot be used as mouse
|
|
|
154 pointers]; etc.)
|
|
|
155
|
|
|
156 It is important to keep the distinction between image instantiator
|
|
|
157 format and image instance type in mind. Typically, a given image
|
|
|
158 instantiator format can result in many different image instance types.
|
|
2953
|
159 For example, @code{xpm} can be instantiated as @code{color-pixmap},
|
|
2182
|
160 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
|
|
2953
|
161 instantiated only as @code{pointer}. On the other hand, a particular image
|
|
2182
|
162 instance type can be generated by many different image instantiator
|
|
|
163 formats (e.g. @code{color-pixmap} can be generated by @code{xpm},
|
|
|
164 @code{gif}, @code{jpeg}, etc.).
|
|
|
165
|
|
|
166 @xref{Image Instances}, for a more detailed discussion of image
|
|
|
167 instance types.
|
|
|
168
|
|
|
169 An image instantiator should be a string or a vector of the form
|
|
|
170
|
|
|
171 @example
|
|
|
172 @code{[@var{format} @var{:keyword} @var{value} ...]}
|
|
|
173 @end example
|
|
|
174
|
|
|
175 i.e. a format symbol followed by zero or more alternating keyword-value
|
|
|
176 pairs.
|
|
|
177
|
|
|
178 The form of an instantiator can be checked with
|
|
|
179 @code{valid-instantiator-p} with a @var{TYPE} of @code{image},
|
|
|
180 @ref{Specifier Validation Functions}.
|
|
|
181
|
|
|
182 For a complete list of the format symbols and their usage,
|
|
|
183 @ref{Image Instantiator Formats}.
|
|
|
184
|
|
|
185 If the instantiator is a string, it will be converted into a vector by
|
|
|
186 looking it up according to the specs in the
|
|
|
187 @code{console-type-image-conversion-list} for the console type of the
|
|
|
188 domain (usually a window; sometimes a frame or device) over which the
|
|
|
189 image is being instantiated.
|
|
|
190
|
|
|
191 If the instantiator specifies data from a file, the data will be read in
|
|
|
192 at the time that the instantiator is added to the image specifier (which
|
|
|
193 may be well before the image is actually displayed), and the
|
|
|
194 instantiator will be converted into one of the inline-data forms, with
|
|
|
195 the filename retained using a @code{:file} keyword. This implies that
|
|
|
196 the file must exist when the instantiator is added to the image, but
|
|
|
197 does not need to exist at any other time (e.g. it may safely be a
|
|
|
198 temporary file).
|
|
|
199
|
|
|
200 The available keywords are given below. Note that some keywords are
|
|
|
201 generally available (for example, the @code{:data} keyword may be used
|
|
|
202 with any format except @code{nothing}), while others are only available
|
|
|
203 for one format (@code{resource-id} is unique to the
|
|
|
204 @code{mswindows-resource} format).
|
|
|
205
|
|
|
206 @table @code
|
|
|
207 @item :data
|
|
|
208 Inline image data. If available for a given format, it may be specified
|
|
|
209 directly by the program, or it may be a cache of file data previously
|
|
|
210 read. When present, it is used to instantiate the image in preference
|
|
|
211 to the file named by the @code{:file} property.
|
|
|
212
|
|
|
213 The format of inline data is image-format-specific. For example, in
|
|
|
214 pixmap formats, the value should be a string, which is interpreted as an
|
|
|
215 octet-stream representing a bitmap or pixmap. But for text formats,
|
|
|
216 it's string containing the text to be displayed, and for resource
|
|
|
217 formats, it's a string containing the name of the resource.
|
|
|
218
|
|
|
219 @item :file
|
|
|
220 Data contained in a file. The value is the name of this file. If both
|
|
|
221 @code{:data} and @code{:file} are specified, the image is created from
|
|
|
222 what is specified in @code{:data} and the string in @code{:file} becomes
|
|
|
223 the value of the @code{image-instance-file-name} function when applied
|
|
|
224 to the resulting image-instance. Note that there is nothing to stop a
|
|
|
225 program from changing either the @code{:file} or the @code{:data}
|
|
|
226 property, and there is no way to detect such mischief. This means that
|
|
|
227 the data will @emph{not} be automatically reread if you change the
|
|
|
228 @code{file} property; you must force it by removing the @code{:data}
|
|
|
229 property.
|
|
|
230 @c #### If there are ways to do this in-place, describe them.
|
|
|
231 (One way to do this is replacing the whole specification with a new
|
|
|
232 vector.) This keyword is not valid for instantiator formats
|
|
|
233 @code{nothing}, @code{string}, @code{formatted-string},
|
|
|
234 @code{cursor-font}, @code{font}, and @code{autodetect}.
|
|
|
235
|
|
|
236 @item :mask-data
|
|
|
237 Inline data for @code{xbm} and @code{xface}. This specifies a mask to
|
|
|
238 be used with the bitmap. Pixels which are not set in the mask will not
|
|
|
239 be written to the imaging device. The format is a list of width,
|
|
|
240 height, and bits, as for @code{:data}.
|
|
|
241
|
|
|
242 @item :mask-file
|
|
|
243 For @code{xbm} and @code{xface}. This specifies a file containing the
|
|
|
244 mask data. If neither a mask file nor inline mask data is given for an
|
|
|
245 XBM image, and the XBM image comes from a file, XEmacs will look for a
|
|
|
246 mask file with the same name as the image file but with @samp{Mask} or
|
|
|
247 @samp{msk} appended. For example, if you specify the XBM file
|
|
|
248 @file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
|
|
|
249 the associated mask file @file{left_ptrmsk} will automatically be picked
|
|
|
250 up.
|
|
|
251
|
|
|
252 @item :resource-id
|
|
|
253 Only for @code{mswindows-resource}. This must be either an integer
|
|
|
254 (which directly specifies a resource number) or a string. See the
|
|
|
255 description of @code{mswindows-resource} for valid strings. @xref{Image
|
|
|
256 Instantiator Formats}.
|
|
|
257
|
|
|
258 @item :foreground
|
|
|
259 @itemx :background
|
|
|
260 For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
|
|
|
261 These keywords allow you to explicitly specify foreground and background
|
|
|
262 colors. The value should be anything acceptable to
|
|
|
263 @code{make-color-instance}. This will cause an external format that
|
|
|
264 would by default be instantiated as a @code{mono-pixmap} to instead be
|
|
|
265 instantiated as a two-color color-pixmap. This can be used to override
|
|
|
266 the colors specified by a glyph's face, for example. If the image is
|
|
|
267 instantiated as a pointer, they specify its foreground and/or
|
|
|
268 background, instead of the defaults of black and white.
|
|
|
269
|
|
|
270 @item :hotspot-x
|
|
|
271 @itemx :hotspot-y
|
|
|
272 For @code{xbm} and @code{xface}. These keywords specify a hotspot if
|
|
|
273 the image is instantiated as a @code{pointer}. Note that if the XBM
|
|
|
274 image file specifies a hotspot, it will automatically be picked up if no
|
|
|
275 explicit hotspot is given.
|
|
|
276
|
|
|
277 @item :color-symbols
|
|
|
278 Only for @code{xpm}. This specifies an alist that maps strings that
|
|
|
279 specify symbolic color names to the actual color to be used for that
|
|
|
280 symbolic color (in the form of a string or a color-specifier object).
|
|
|
281 If this is not specified, the contents of @code{xpm-color-symbols} are
|
|
|
282 used to generate the alist.
|
|
|
283
|
|
|
284 @item :resource-type
|
|
|
285 Only for @code{mswindows-resource}. This must be a symbol, either
|
|
|
286 @code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
|
|
|
287 resource to be retrieved.
|
|
|
288
|
|
|
289 @item :face
|
|
|
290 For @code{inherit} and the widget formats. This specifies the face to
|
|
|
291 inherit from. For widgets this specifies the face to use for display.
|
|
|
292 It defaults to gui-element-face.
|
|
|
293
|
|
|
294 @item :selected
|
|
|
295 @itemx :active
|
|
|
296 @itemx :suffix
|
|
|
297 @itemx :keys
|
|
|
298 @itemx :style
|
|
|
299 @itemx :filter
|
|
|
300 @itemx :config
|
|
|
301 @itemx :included
|
|
|
302 @itemx :key-sequence
|
|
|
303 @itemx :accelerator
|
|
|
304 @itemx :label
|
|
|
305 @itemx :callback
|
|
|
306 These keywords, accepted as menu item specs, are also accepted by images
|
|
|
307 instantiated as @code{widget}. For their semantics, @ref{Menu Format}.
|
|
|
308 @end table
|
|
|
309
|
|
|
310
|
|
|
311 @node Image Instantiator Conversion
|
|
|
312 @subsection Image Instantiator Conversion
|
|
|
313 @cindex image instantiator conversion
|
|
|
314 @cindex conversion of image instantiators
|
|
|
315
|
|
|
316 Conversion is applied to image instantiators at the time they are added
|
|
|
317 to an image specifier or at the time they are passed to
|
|
|
318 @code{make-image-instance}.
|
|
|
319
|
|
|
320 @defun set-console-type-image-conversion-list console-type list
|
|
|
321 This function sets the image-conversion-list for consoles of the given
|
|
|
322 @var{console-type}. The image-conversion-list specifies how image
|
|
|
323 instantiators that are strings should be interpreted. Each element of
|
|
|
324 the list should be a list of two elements (a regular expression string
|
|
|
325 and a vector) or a list of three elements (the preceding two plus an
|
|
|
326 integer index into the vector). The string is converted to the vector
|
|
|
327 associated with the first matching regular expression. If a vector
|
|
|
328 index is specified, the string itself is substituted into that position
|
|
|
329 in the vector.
|
|
|
330
|
|
|
331 Note: The conversion above is applied when the image instantiator is
|
|
|
332 added to an image specifier, not when the specifier is actually
|
|
|
333 instantiated. Therefore, changing the image-conversion-list only affects
|
|
|
334 newly-added instantiators. Existing instantiators in glyphs and image
|
|
|
335 specifiers will not be affected.
|
|
|
336 @end defun
|
|
|
337
|
|
|
338 @defun console-type-image-conversion-list console-type
|
|
|
339 This function returns the image-conversion-list for consoles of the given
|
|
|
340 @var{console-type}.
|
|
|
341 @end defun
|
|
|
342
|
|
|
343
|
|
|
344 @node Image Instantiator Formats
|
|
|
345 @subsection Image Instantiator Formats
|
|
|
346 @cindex image instantiator formats
|
|
|
347
|
|
|
348 The @dfn{format} field of an image instantiator should be a symbol
|
|
|
349 denoting a valid format. Which formats are valid will depend on the
|
|
|
350 features (such as image decoding libraries) available, on platform
|
|
|
351 support (MS Windows resource IDs make no sense on other platforms), and
|
|
|
352 on the locale.
|
|
|
353
|
|
|
354 @defun valid-image-instantiator-format-p format &optional locale
|
|
|
355 This function returns non-@code{nil} if @var{format} is a valid image
|
|
|
356 instantiator format.
|
|
|
357
|
|
|
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.
|
|
|
360
|
|
|
361 Note that the return value for many formats listed above depends on
|
|
|
362 whether XEmacs was compiled with support for that format.
|
|
|
363 @end defun
|
|
|
364
|
|
|
365 @defun image-instantiator-format-list
|
|
|
366 This function returns a list of valid image-instantiator formats.
|
|
|
367 @end defun
|
|
|
368
|
|
|
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.
|
|
|
371
|
|
|
372 @table @code
|
|
|
373 @item nothing
|
|
|
374 Don't display anything; no keywords are valid for this format. Can only be
|
|
2953
|
375 instantiated as @code{nothing}.
|
|
2182
|
376
|
|
|
377 @item string
|
|
2953
|
378 Display this image as a text string. Can only be instantiated
|
|
|
379 as @code{text}, although support for instantiation as @code{mono-pixmap}
|
|
2182
|
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.
|
|
|
382
|
|
|
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.
|
|
|
388
|
|
|
389 Not currently implemented.
|
|
|
390
|
|
|
391 @item xbm
|
|
|
392 An X bitmap; available only if X support was compiled into this XEmacs.
|
|
|
393
|
|
|
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.
|
|
|
398 @c #### Check this.
|
|
|
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}.
|
|
|
402
|
|
|
403 The valid keywords and their values are
|
|
|
404 @table @code
|
|
|
405 @item :data
|
|
|
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.
|
|
|
409 @item :file
|
|
|
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.
|
|
|
413 @item :mask-data
|
|
|
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.
|
|
|
418 @item :mask-file
|
|
|
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.
|
|
|
421 @item :foreground
|
|
|
422 @itemx :background
|
|
|
423 These keywords allow you to explicitly specify foreground and background
|
|
|
424 colors. The values should be acceptable to @code{make-color-instance}.
|
|
|
425 @item :hotspot-x
|
|
|
426 @itemx :hotspot-y
|
|
|
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
|
|
|
429 XBM file.
|
|
|
430 @end table
|
|
|
431
|
|
|
432 @item xpm
|
|
|
433 An XPM pixmap; only available if XPM support was compiled into this XEmacs.
|
|
|
434
|
|
2953
|
435 Can be instantiated as @code{color-pixmap}, @code{mono-pixmap}, or
|
|
2182
|
436 @code{pointer}.
|
|
|
437
|
|
|
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 XEmacs.
|
|
|
443
|
|
|
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.
|
|
|
448
|
|
|
449 The valid keywords and their values are
|
|
|
450 @table @code
|
|
|
451 @item :data
|
|
|
452 A string interpreted as the contents of a standard XPM file.
|
|
|
453 @item :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?
|
|
|
458 @item :hotspot-x
|
|
|
459 @itemx :hotspot-y
|
|
|
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
|
|
|
462 XBM file.
|
|
|
463 @c #### Check this.
|
|
|
464 (This may not be true. The original documentation doesn't mention them
|
|
|
465 in connection with XPM, but a pointer needs a hotspot.)
|
|
|
466 @item :color-symbols
|
|
|
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.
|
|
|
473 @end table
|
|
|
474
|
|
|
475 @item xface
|
|
|
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 XEmacs.
|
|
|
478
|
|
2953
|
479 Will be instantiated as @code{mono-pixmap}, @code{color-pixmap}, or
|
|
2182
|
480 @code{pointer}, depending on the target instance type and the presence
|
|
|
481 of color keywords.
|
|
|
482
|
|
|
483 The valid keywords and their values are
|
|
|
484 @table @code
|
|
|
485 @item :data
|
|
|
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.
|
|
|
489 @item :file
|
|
|
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.
|
|
|
493 @item :mask-data
|
|
|
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.
|
|
|
498 @item :mask-file
|
|
|
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.
|
|
|
501 @item :foreground
|
|
|
502 @itemx :background
|
|
|
503 These keywords allow you to explicitly specify foreground and background
|
|
|
504 colors. The values should be acceptable to @code{make-color-instance}.
|
|
|
505 @item :hotspot-x
|
|
|
506 @itemx :hotspot-y
|
|
|
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
|
|
|
509 XBM file.
|
|
|
510 @end table
|
|
|
511
|
|
|
512 @item gif
|
|
|
513 @itemx jpeg
|
|
|
514 @itemx png
|
|
|
515 @itemx tiff
|
|
|
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 XEmacs is built, the JPEG,
|
|
|
523 PNG, and TIFF libraries will automatically be detected (in the ``usual
|
|
|
524 places'') and linked into the build.
|
|
|
525
|
|
|
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.
|
|
|
528
|
|
2953
|
529 All of these instantiators will be instantiated as @code{color-pixmap}.
|
|
2182
|
530
|
|
|
531 The valid keywords and their values are
|
|
|
532 @table @code
|
|
|
533 @item :data
|
|
|
534 A string interpreted as the contents of a file containing data in the
|
|
|
535 appropriate standard format.
|
|
|
536 @item :file
|
|
|
537 The name of a file containing standard-format data.
|
|
|
538 @end table
|
|
|
539
|
|
|
540 @item cursor-font
|
|
|
541 Most window systems provide a set of standard cursors, which in X11 is
|
|
2953
|
542 called a cursor font. Can only be instantiated as @code{pointer}. This
|
|
2182
|
543 should probably be fixed.
|
|
|
544
|
|
|
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. For MS Windows, use
|
|
|
551 @code{mswindows-resource} instantiator format, not @code{cursor-font}.
|
|
|
552 Other window systems may have different lists.
|
|
|
553
|
|
|
554 @item font
|
|
|
555 A glyph from a font; i.e. the name of a font, and glyph index into it
|
|
|
556 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
|
|
|
557 Only if X support was compiled into this XEmacs. Currently can only be
|
|
2953
|
558 instantiated as @code{pointer}. This should probably be fixed.
|
|
2182
|
559 @c #### The above description is not very helpful, so it's not obvious
|
|
|
560 @c how to instantiate a font image.
|
|
|
561
|
|
|
562 @item mswindows-resource
|
|
|
563 An MS Windows pointer resource. Specifies a resource to retrieve
|
|
|
564 directly from the system (an OEM resource) or from a file, particularly
|
|
2953
|
565 an executable file. Can be instantiated as @code{pointer} or
|
|
2182
|
566 @code{color-pixmap}.
|
|
|
567
|
|
|
568 The valid keywords and their values are
|
|
|
569
|
|
|
570 @table @code
|
|
|
571 @item :resource-type
|
|
|
572 A string naming the type (@code{cursor}, @code{bitmap}, or @code{icon})
|
|
|
573 of the resource. Required.
|
|
|
574 @item :file
|
|
|
575 A string containing the name of the file containing the resource (often
|
|
|
576 an executable). If a system resource, @code{:file} should be omitted.
|
|
|
577 @item :resource-id
|
|
|
578 A string containing the name of a resource. Required if @code{:file}
|
|
|
579 is not specified.
|
|
|
580
|
|
|
581 This must be either an integer (which directly specifies a resource
|
|
|
582 number) or a string. Valid strings are
|
|
|
583
|
|
|
584 For bitmaps:
|
|
|
585
|
|
|
586 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
|
|
|
587 "reduce", "zoom", "restore", "reduced", "zoomd",
|
|
|
588 "restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd",
|
|
|
589 "mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi",
|
|
|
590 "lfarrowi", "size", "btsize", "check", "checkboxes", and
|
|
|
591 "btncorners".
|
|
|
592
|
|
|
593 For cursors:
|
|
|
594
|
|
|
595 "normal", "ibeam", "wait", "cross", "up", "sizenwse",
|
|
|
596 "sizenesw", "sizewe", "sizens", "sizeall", and "no".
|
|
|
597
|
|
|
598 For icons:
|
|
|
599
|
|
|
600 "sample", "hand", "ques", "bang", "note", and "winlogo".
|
|
|
601 @end table
|
|
|
602
|
|
|
603 @item subwindow
|
|
2953
|
604 An embedded windowing system window. Can only be instantiated as
|
|
2182
|
605 @code{subwindow}. Not implemented.
|
|
|
606 @c #### Check status of subwindows ... I thought Andy implemented them.
|
|
|
607
|
|
|
608 @item button
|
|
|
609 A button widget; either a push button, radio button or toggle button.
|
|
2953
|
610 Can only be instantiated as @code{widget}.
|
|
2182
|
611
|
|
|
612 @item combo-box
|
|
|
613 A drop list of selectable items in a widget, for editing text.
|
|
2953
|
614 Can only be instantiated as @code{widget}.
|
|
2182
|
615
|
|
|
616 @item edit-field
|
|
2953
|
617 A text editing widget. Can only be instantiated as @code{widget}.
|
|
2182
|
618
|
|
|
619 @item label
|
|
2953
|
620 A static, text-only, widget; for displaying text. Can only be instantiated
|
|
2182
|
621 as @code{widget}.
|
|
|
622
|
|
|
623 @item layout
|
|
|
624 A widget for controlling the positioning of children underneath it.
|
|
|
625 Through the use of nested layouts, a widget hierarchy can be created
|
|
|
626 which can have the appearance of any standard dialog box or similar
|
|
|
627 arrangement; all of this is counted as one @dfn{glyph} and could appear
|
|
2953
|
628 in many of the places that expect a single glyph. Can only be instantiated
|
|
2182
|
629 as @code{widget}.
|
|
|
630
|
|
|
631 @item native-layout
|
|
|
632 The native version of a layout widget.
|
|
2953
|
633 Can only be instantiated as @code{widget}.
|
|
2182
|
634
|
|
|
635 @item progress-gauge
|
|
2953
|
636 A sliding widget, for showing progress. Can only be instantiated as
|
|
2182
|
637 @code{widget}.
|
|
|
638
|
|
|
639 @item tab-control
|
|
2953
|
640 A tab widget; a series of user selectable tabs. Can only be instantiated
|
|
2182
|
641 as @code{widget}.
|
|
|
642
|
|
2297
|
643 The required keyword is @code{:items}. Its value should be a list of
|
|
|
644 vectors, whose first element is a string, the second element is a
|
|
|
645 callback (a Lisp expression to be eval'ed), and the remaining elements
|
|
|
646 are key-value pairs. The most important keyword is @code{:selected} (a
|
|
|
647 Boolean); exactly one of the elements should have a value of @code{t}
|
|
|
648 for the @code{:selected} property. Other keywords accepted include
|
|
|
649 @code{:descriptor} (a string), @code{:face} (a symbol naming a face),
|
|
|
650 @code{:orientation} (a symbol, one of @code{top}, @code{center},
|
|
|
651 @code{bottom}, @code{left}, or @code{right}), and @code{:pixel-width}
|
|
|
652 and @code{:pixel-height} (positive integers).
|
|
|
653
|
|
|
654 (The above is incomplete and may be inaccurate.)
|
|
|
655
|
|
2182
|
656 @item tree-view
|
|
2953
|
657 A folding widget. Can only be instantiated as @code{widget}.
|
|
2182
|
658
|
|
|
659 @item scrollbar
|
|
2953
|
660 A scrollbar widget. Can only be instantiated as @code{widget}.
|
|
2182
|
661
|
|
|
662 @item autodetect
|
|
|
663 XEmacs tries to guess what format the data is in. If X support exists,
|
|
|
664 the data string will be checked to see if it names a filename. If so,
|
|
|
665 and this filename contains XBM or XPM data, the appropriate sort of
|
|
|
666 pixmap or pointer will be created. [This includes picking up any
|
|
|
667 specified hotspot or associated mask file.] Otherwise, if @code{pointer}
|
|
|
668 is one of the allowable image-instance types and the string names a
|
|
|
669 valid cursor-font name, the image will be created as a pointer.
|
|
|
670 Otherwise, the image will be displayed as text. If no X support exists,
|
|
|
671 the image will always be displayed as text.
|
|
|
672
|
|
|
673 @item inherit
|
|
|
674 Inherit from the background-pixmap property of a face. Can only be
|
|
2953
|
675 instantiated as @code{mono-pixmap}.
|
|
2182
|
676 @end table
|
|
|
677
|
|
|
678 There are two convenience variables for use with the XBM and XPM image
|
|
|
679 formats.
|
|
|
680
|
|
|
681 @defvar xpm-color-symbols
|
|
|
682 This variable holds definitions of logical color-names used when reading
|
|
|
683 XPM files. Elements of this list should be of the form
|
|
|
684 @code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name}
|
|
|
685 should be a string, which is the name of the color to define; the
|
|
|
686 @var{form-to-evaluate} should evaluate to a color specifier object, or a
|
|
|
687 string to be passed to @code{make-color-instance} (@pxref{Colors}). If
|
|
|
688 a loaded XPM file references a symbolic color called @var{color-name},
|
|
|
689 it will display as the computed color instead.
|
|
|
690
|
|
|
691 The default value of this variable defines the logical color names
|
|
|
692 @samp{"foreground"} and @samp{"background"} to be the colors of the
|
|
|
693 @code{default} face.
|
|
|
694 @end defvar
|
|
|
695
|
|
|
696 @defvar x-bitmap-file-path
|
|
|
697 A list of the directories in which X bitmap files may be found. If @code{nil},
|
|
|
698 this is initialized from the @samp{"*bitmapFilePath"} resource. This is
|
|
|
699 used by the @code{make-image-instance} function (however, note that if
|
|
|
700 the environment variable @samp{XBMLANGPATH} is set, it is consulted
|
|
|
701 first).
|
|
|
702 @end defvar
|
|
|
703
|
|
|
704
|
|
|
705 @node Image Instances
|
|
|
706 @subsection Image Instances
|
|
|
707 @cindex image instances
|
|
|
708
|
|
|
709 Image-instance objects encapsulate the way a particular image (pixmap,
|
|
|
710 etc.) is displayed on a particular device.
|
|
|
711
|
|
|
712 In most circumstances, you do not need to directly create image
|
|
|
713 instances; use a glyph instead. However, it may occasionally be useful
|
|
|
714 to explicitly create image instances, if you want more control over the
|
|
|
715 instantiation process.
|
|
|
716
|
|
|
717 @defun image-instance-p object
|
|
|
718 This function returns non-@code{nil} if @var{object} is an image instance.
|
|
|
719 @end defun
|
|
|
720
|
|
|
721 @menu
|
|
2953
|
722 * Image Instance Types:: Each image instance has a particular type.
|
|
2182
|
723 * Image Instance Functions:: Functions for working with image instances.
|
|
|
724 @end menu
|
|
|
725
|
|
|
726
|
|
|
727 @node Image Instance Types
|
|
|
728 @subsubsection Image Instance Types
|
|
|
729 @cindex image instance types
|
|
|
730
|
|
|
731 Image instances come in a number of different types. The type
|
|
|
732 of an image instance specifies the nature of the image: Whether
|
|
|
733 it is a text string, a mono pixmap, a color pixmap, etc.
|
|
|
734
|
|
|
735 The valid image instance types are
|
|
|
736
|
|
|
737 @table @code
|
|
|
738 @item nothing
|
|
|
739 Nothing is displayed.
|
|
|
740
|
|
|
741 @item text
|
|
|
742 Displayed as text. The foreground and background colors and the
|
|
|
743 font of the text are specified independent of the pixmap. Typically
|
|
|
744 these attributes will come from the face of the surrounding text,
|
|
|
745 unless a face is specified for the glyph in which the image appears.
|
|
|
746
|
|
|
747 @item mono-pixmap
|
|
|
748 Displayed as a mono pixmap (a pixmap with only two colors where the
|
|
|
749 foreground and background can be specified independent of the pixmap;
|
|
|
750 typically the pixmap assumes the foreground and background colors of
|
|
|
751 the text around it, unless a face is specified for the glyph in which
|
|
|
752 the image appears).
|
|
|
753 @item color-pixmap
|
|
|
754
|
|
|
755 Displayed as a color pixmap.
|
|
|
756
|
|
|
757 @item pointer
|
|
|
758 Used as the mouse pointer for a window.
|
|
|
759
|
|
|
760 @item subwindow
|
|
|
761 A child window that is treated as an image. This allows (e.g.)
|
|
|
762 another program to be responsible for drawing into the window.
|
|
|
763 Not currently implemented.
|
|
|
764 @c #### Check status of subwindows ... I thought Andy implemented them.
|
|
|
765
|
|
|
766 @item widget
|
|
|
767 An active GUI element implemented as a ``widget'' or ``control'' of the
|
|
|
768 underlying window system.
|
|
|
769 @end table
|
|
|
770
|
|
|
771 The following functions are used to check whether an image instance type
|
|
|
772 is valid in the running XEmacs.
|
|
|
773
|
|
|
774 @defun valid-image-instance-type-p type
|
|
|
775 This function returns non-@code{nil} if @var{type} is a valid image
|
|
|
776 instance type.
|
|
|
777 @end defun
|
|
|
778
|
|
|
779 @defun image-instance-type-list
|
|
|
780 This function returns a list of the valid image instance types.
|
|
|
781 @end defun
|
|
|
782
|
|
|
783 The following functions are used to determine the type of an image
|
|
|
784 instance.
|
|
|
785
|
|
|
786 @defun image-instance-type image-instance
|
|
|
787 Return the type of the given image instance. The return
|
|
|
788 value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
|
|
|
789 @code{color-pixmap}, @code{pointer}, @code{subwindow}, or @code{widget}.
|
|
|
790 @c #### Check status of subwindows ... I thought Andy implemented them.
|
|
|
791 @end defun
|
|
|
792
|
|
|
793 @defun text-image-instance-p object
|
|
|
794 Return non-@code{nil} if @var{object} is an image instance of type
|
|
|
795 @code{text}.
|
|
|
796 @end defun
|
|
|
797
|
|
|
798 @defun mono-pixmap-image-instance-p object
|
|
|
799 Return non-@code{nil} if @var{object} is an image instance of type
|
|
|
800 @code{mono-pixmap}.
|
|
|
801 @end defun
|
|
|
802
|
|
|
803 @defun color-pixmap-image-instance-p object
|
|
|
804 Return non-@code{nil} if @var{object} is an image instance of type
|
|
|
805 @code{color-pixmap}.
|
|
|
806 @end defun
|
|
|
807
|
|
|
808 @defun pointer-image-instance-p object
|
|
|
809 Return non-@code{nil} if @var{object} is an image instance of type
|
|
|
810 @code{pointer}.
|
|
|
811 @end defun
|
|
|
812
|
|
|
813 @defun subwindow-image-instance-p object
|
|
|
814 Return non-@code{nil} if @var{object} is an image instance of type
|
|
|
815 @code{subwindow}.
|
|
|
816 @c #### Check status of subwindows ... I thought Andy implemented them.
|
|
|
817 @end defun
|
|
|
818
|
|
|
819 @defun nothing-image-instance-p object
|
|
|
820 Return non-@code{nil} if @var{object} is an image instance of type
|
|
|
821 @code{nothing}.
|
|
|
822 @end defun
|
|
|
823
|
|
|
824 @defun widget-image-instance-p object
|
|
|
825 Return non-@code{nil} if @var{object} is an image instance of type
|
|
|
826 @code{widget}.
|
|
|
827 @end defun
|
|
|
828
|
|
|
829
|
|
|
830 @node Image Instance Functions
|
|
|
831 @subsubsection Image Instance Functions
|
|
|
832
|
|
|
833 @defun make-image-instance data &optional domain dest-types noerror
|
|
|
834 This function creates a new image-instance object.
|
|
|
835
|
|
|
836 @var{data} is an image instantiator, which describes the image
|
|
2953
|
837 (@pxref{Image Instantiators}).
|
|
2182
|
838
|
|
|
839 @var{dest-types} should be a list of allowed image instance types that
|
|
|
840 can be generated. The @var{dest-types} list is unordered. If multiple
|
|
|
841 destination types are possible for a given instantiator, the ``most
|
|
|
842 natural'' type for the instantiator's format is chosen. These are
|
|
|
843
|
|
|
844 @table @code
|
|
|
845 @item XBM
|
|
|
846 @c #### check xface
|
|
|
847 @itemx xface
|
|
|
848 @code{mono-pixmap}, then @code{color-pixmap}, then @code{pointer}.
|
|
|
849
|
|
|
850 @item XPM
|
|
|
851 @itemx GIF
|
|
|
852 @itemx JPEG
|
|
|
853 @itemx PNG
|
|
|
854 @itemx TIFF
|
|
|
855 @code{color-pixmap}, then @code{mono-pixmap}, then @code{pointer}.
|
|
|
856
|
|
|
857 @item string
|
|
|
858 @itemx formatted-string formats
|
|
|
859 @code{text}, then @code{mono-pixmap} (not currently implemented), then
|
|
|
860 @code{color-pixmap} (not currently implemented).
|
|
|
861
|
|
|
862 @item mswindows-resource
|
|
|
863 For pointer resources, @code{pointer}.
|
|
|
864
|
|
|
865 For the others, @code{color-pixmap}.
|
|
|
866 @end table
|
|
|
867
|
|
|
868 @c #### So what? This is a reference manual, list them, you lazy bastard!
|
|
|
869 The other formats can only be instantiated as one type.
|
|
|
870
|
|
|
871 If you want to control more specifically the order of the types into
|
|
|
872 which an image is instantiated, call @code{make-image-instance}
|
|
|
873 repeatedly until it succeeds, passing less and less preferred
|
|
|
874 destination types each time.
|
|
|
875
|
|
|
876 If @var{dest-types} is omitted, all possible types are allowed.
|
|
|
877
|
|
|
878 @var{domain} specifies the domain to which the image instance will be
|
|
|
879 attached. This domain is termed the @dfn{governing domain}. The type
|
|
|
880 of the governing domain depends on the image instantiator format.
|
|
|
881 (Although, more correctly, it should probably depend on the image
|
|
|
882 instance type.) For example, pixmap image instances are specific to a
|
|
|
883 device, but widget image instances are specific to a particular XEmacs
|
|
|
884 window because in order to display such a widget when two windows onto
|
|
|
885 the same buffer want to display the widget, two separate underlying
|
|
|
886 widgets must be created. (That's because a widget is actually a child
|
|
|
887 window-system window, and all window-system windows have a unique
|
|
|
888 existence on the screen.) This means that the governing domain for a
|
|
|
889 pixmap image instance will be some device (most likely, the only
|
|
|
890 existing device), whereas the governing domain for a widget image
|
|
|
891 instance will be some XEmacs window.
|
|
|
892
|
|
|
893 If you specify an overly general @var{domain} (e.g. a frame when a
|
|
|
894 window was wanted), an error is signaled. If you specify an overly
|
|
|
895 specific @var{domain} (e.g. a window when a device was wanted), the
|
|
|
896 corresponding general domain is fetched and used instead. For
|
|
|
897 @code{make-image-instance}, it makes no difference whether you specify
|
|
|
898 an overly specific domain or the properly general domain derived from
|
|
|
899 it. However, it does matter when creating an image instance by
|
|
|
900 instantiating a specifier or glyph (e.g. with
|
|
|
901 @code{glyph-image-instance}), because the more specific domain causes
|
|
|
902 spec lookup to start there and proceed to more general domains. (It
|
|
|
903 would also matter when creating an image instance with an instantiator
|
|
|
904 format of @code{inherit}, but we currently disallow this.)
|
|
|
905 @c #### We should fix that.
|
|
|
906
|
|
|
907 If omitted, @var{domain} defaults to the selected window.
|
|
|
908
|
|
|
909 @var{noerror} controls what happens when the image cannot be generated.
|
|
|
910 If @code{nil}, an error message is generated. If @code{t}, no messages
|
|
|
911 are generated and this function returns @code{nil}. If anything else, a
|
|
|
912 warning message is generated and this function returns @code{nil}.
|
|
|
913 @end defun
|
|
|
914
|
|
|
915 @defun colorize-image-instance image-instance foreground background
|
|
|
916 This function makes the image instance be displayed in the given
|
|
|
917 colors. Image instances come in two varieties: bitmaps, which are 1
|
|
|
918 bit deep which are rendered in the prevailing foreground and background
|
|
|
919 colors; and pixmaps, which are of arbitrary depth (including 1) and
|
|
|
920 which have the colors explicitly specified. This function converts a
|
|
|
921 bitmap to a pixmap. If the image instance was a pixmap already,
|
|
|
922 nothing is done (and @code{nil} is returned). Otherwise @code{t} is
|
|
|
923 returned.
|
|
|
924 @end defun
|
|
|
925
|
|
|
926 The following functions are
|
|
|
927
|
|
|
928 @defun image-instance-name image-instance
|
|
|
929 This function returns the name of the given image instance. The name is
|
|
|
930 typically taken from the @code{:file} property of the instantiator if
|
|
|
931 present, otherwise from the @code{:data} property.
|
|
|
932 @end defun
|
|
|
933
|
|
|
934 @defun image-instance-domain image-instance
|
|
|
935 Return the governing domain of the given @var{image-instance}. The
|
|
|
936 governing domain of an image instance is the domain that the image
|
|
|
937 instance is specific to. It is @emph{NOT} necessarily the domain that
|
|
|
938 was given to the call to @code{specifier-instance} that resulted in the
|
|
|
939 creation of this image instance. See @code{make-image-instance} for
|
|
|
940 more information on governing domains.
|
|
|
941 @end defun
|
|
|
942
|
|
|
943 @defun image-instance-string image-instance
|
|
|
944 This function returns the string of the given image instance. This will
|
|
|
945 only be non-@code{nil} for text image instances.
|
|
|
946 @end defun
|
|
|
947
|
|
|
948 @defun image-instance-file-name image-instance
|
|
|
949 This function returns the file name from which @var{image-instance} was
|
|
|
950 read, if known.
|
|
|
951 @end defun
|
|
|
952
|
|
|
953 @defun image-instance-mask-file-name image-instance
|
|
|
954 This function returns the file name from which @var{image-instance}'s
|
|
|
955 mask was read, if known.
|
|
|
956 @end defun
|
|
|
957
|
|
|
958 Pixmaps are considered to be three-dimensional. The height and width of
|
|
|
959 the pixel array that is displayed, and the color depth of its pixels,
|
|
|
960 are accessed with these functions.
|
|
|
961
|
|
|
962 @defun image-instance-depth image-instance
|
|
|
963 This function returns the depth of the image instance. This is 0 for a
|
|
|
964 mono pixmap, or a positive integer for a color pixmap.
|
|
|
965 @end defun
|
|
|
966
|
|
|
967 @defun image-instance-height image-instance
|
|
|
968 This function returns the height of the image instance, in pixels.
|
|
|
969 @end defun
|
|
|
970
|
|
|
971 @defun image-instance-width image-instance
|
|
|
972 This function returns the width of the image instance, in pixels.
|
|
|
973 @end defun
|
|
|
974
|
|
|
975 The hotspot is a point relative to the origin of the pixmap. When
|
|
|
976 an image is used as a mouse pointer, the hotspot is the point on the
|
|
|
977 image that sits over the location that the pointer points to. This is,
|
|
|
978 for example, the tip of the arrow or the center of the crosshairs.
|
|
|
979
|
|
|
980 These functions access the coordinates of the hotspot. They simply
|
|
|
981 return @code{nil} for a non-pointer image instance.
|
|
|
982
|
|
|
983 @defun image-instance-hotspot-x image-instance
|
|
|
984 This function returns the X coordinate of the image instance's hotspot,
|
|
|
985 if known.
|
|
|
986 @end defun
|
|
|
987
|
|
|
988 @defun image-instance-hotspot-y image-instance
|
|
|
989 This function returns the Y coordinate of the image instance's hotspot,
|
|
|
990 if known.
|
|
|
991 @end defun
|
|
|
992
|
|
|
993 Mono pixmaps and pointers may have their foreground and background
|
|
2953
|
994 colors set when instantiated. Use these functions to access color
|
|
2182
|
995 information.
|
|
|
996
|
|
|
997 @defun image-instance-foreground image-instance
|
|
|
998 This function returns the foreground color of @var{image-instance}, if
|
|
|
999 applicable. This will be a color instance or @code{nil}. (It will only
|
|
|
1000 be non-@code{nil} for colorized mono pixmaps and for pointers.)
|
|
|
1001 @end defun
|
|
|
1002
|
|
|
1003 @defun image-instance-background image-instance
|
|
|
1004 This function returns the background color of @var{image-instance}, if
|
|
|
1005 applicable. This will be a color instance or @code{nil}. (It will only
|
|
|
1006 be non-@code{nil} for colorized mono pixmaps and for pointers.)
|
|
|
1007 @end defun
|
|
|
1008
|
|
|
1009
|
|
|
1010 @node Using Glyphs
|
|
|
1011 @section Using Glyphs
|
|
|
1012
|
|
|
1013 Glyph usage is unfortunately somewhat arcane. (For discussion of
|
|
|
1014 rationale, @ref{Glyphs,,,Internals}.) Because they are not ``text,''
|
|
|
1015 they cannot be inserted directly into a buffer. Instead, they are
|
|
|
1016 values of properties of extents attached to buffers or strings, values
|
|
|
1017 of global variables such as mouse pointers, or as a component of a
|
|
|
1018 complex data structure such as a toolbar initializer. Although these
|
|
|
1019 uses could probably streamlined, each structure has its own
|
|
|
1020 requirements. Since glyphs are very flexible, it is possible to create
|
|
|
1021 applications like the @file{edit-toolbar} and @file{xpm-mode} libraries
|
|
|
1022 which display glyphs in a buffer (for reference while editing) that are
|
|
|
1023 normally used in a different context.
|
|
|
1024
|
|
|
1025 Usage of glyphs can roughly be categorized as follows:
|
|
|
1026
|
|
|
1027 @table @strong
|
|
|
1028 @item Buffer glyphs
|
|
|
1029 Glyphs that are inserted in a buffer may be used for their own sake (for
|
|
|
1030 example, image display in @file{w3}), as an accurate representation of
|
|
|
1031 text that can't be displayed in usual fonts (equation display in
|
|
|
1032 @file{preview-latex}), or as annotations (such as a marginal indication
|
|
|
1033 of a bookmark). Glyphs are attached to buffers via extents.
|
|
|
1034
|
|
|
1035 @item Redisplay glyphs
|
|
|
1036 Glyphs can be used to create XEmacs-specific ``fonts''. For example,
|
|
|
1037 the character that indicates truncation of lines is implemented as the
|
|
|
1038 @code{truncation-glyph}. It is also possible to have XEmacs display a
|
|
|
1039 certain character using a custom glyph, via display tables.
|
|
|
1040
|
|
|
1041 @item Frame glyphs
|
|
|
1042 Glyphs are used to control the appearance of various other components of
|
|
|
1043 the frame. They can be inserted in the modeline, the favicons are used
|
|
|
1044 in Web browsers. They are used to specify the labels on toolbar
|
|
|
1045 buttons. Finally, they can be inserted in the gutters. (The difference
|
|
|
1046 between a glyph inserted in a gutter and a marginal annotation is that
|
|
|
1047 the marginal annotation is tied to the text in the buffer. If the
|
|
|
1048 buffer line scrolls out of view, the marginal annotation will, as well.
|
|
|
1049 A gutter glyph does not move with the text.)
|
|
|
1050
|
|
|
1051 Unfortunately, all these uses are special cases, and have their own
|
|
|
1052 APIs, in contrast to glyphs in a buffer.
|
|
|
1053
|
|
|
1054 @item External glyphs
|
|
|
1055 External glyphs simply allow a consistent API for images. The images
|
|
|
1056 are then passed to external software such as the window system itself
|
|
|
1057 (mouse cursor shapes) and the window manager (icons to represent
|
|
|
1058 minimized windows). XEmacs has no role in managing their use.
|
|
|
1059
|
|
|
1060 @item Subwindow and widget glyphs
|
|
|
1061 These do not constitute a context of use, but rather an important class of
|
|
|
1062 glyph types. The difference between these and other glyphs is that
|
|
|
1063 while their geometry is determined by XEmacs, their behavior is managed
|
|
|
1064 separately, by internal mechanisms in the case of widgets, and
|
|
|
1065 (possibly) by another process in the case of subwindows.
|
|
|
1066 @c #### Check status of subwindows ... I thought Andy implemented them.
|
|
|
1067 @end table
|
|
|
1068
|
|
|
1069 Some simple concrete examples showing how to insert a glyph in a
|
|
|
1070 buffer are presented later. @ref{Glyph Examples}.
|
|
|
1071
|
|
|
1072 ``Creating Glyphs'' explains how to create glyphs. Creating a glyph
|
|
|
1073 using @code{make-glyph} does not specify @emph{where} the glyph will be
|
|
|
1074 used, it only specifies @emph{what} the glyph will look like. The next
|
|
|
1075 four sections explain how to embed glyphs in different display
|
|
|
1076 contexts. Finally, the last two sections explain the special
|
|
|
1077 considerations of using glyphs whose behavior is not determined by the
|
|
|
1078 code creating them, but by the glyph itself (a ``widget'' in X11 or
|
|
|
1079 ``control'' in MS Windows or Aqua), or even by a separate process.
|
|
428
|
1080
|
|
|
1081 @menu
|
|
|
1082 * Creating Glyphs:: Creating new glyphs.
|
|
2182
|
1083 * Buffer Glyphs:: Annotations are glyphs that appear in a buffer.
|
|
|
1084 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
|
|
|
1085 * Frame Glyphs:: Displaying glyphs in GUI components of the frame.
|
|
|
1086 * External Glyphs:: Icons and mouse pointers for the window system.
|
|
|
1087 * Native GUI Widgets:: Complex active elements treated as a single glyph.
|
|
|
1088 * Subwindows:: Externally-controlled subwindows in buffers.
|
|
|
1089 @c #### Check status of subwindows ... I thought Andy implemented them.
|
|
428
|
1090 @end menu
|
|
|
1091
|
|
|
1092 @node Creating Glyphs
|
|
|
1093 @subsection Creating Glyphs
|
|
|
1094
|
|
|
1095 @defun make-glyph &optional spec-list type
|
|
|
1096 This function creates a new glyph object of type @var{type}.
|
|
|
1097
|
|
2182
|
1098 The optional @var{spec-list} is used to initialize the glyph's image.
|
|
|
1099 It can be any spec-list of @dfn{image instantiator} accepted by
|
|
|
1100 @code{canonicalize-spec-list}, @ref{Adding Specifications}. An
|
|
|
1101 individual image instantiator may be a string, which is converted to a
|
|
|
1102 vector according to @code{console-type-image-conversion-list}, or a
|
|
|
1103 vector. The vector's first element specifies the @emph{external} format
|
|
|
1104 of the data, such as a string, a PNG file, or an MS Windows resource.
|
|
|
1105 This is followed by properties (keyword-value pairs) specifying such
|
|
|
1106 information as the name of a file containing an image, or pixmap data
|
|
2953
|
1107 directly. @xref{Image Instantiators}.
|
|
2182
|
1108
|
|
|
1109 The optional @var{type} specifies the type of the glyph. @var{type}
|
|
|
1110 should be one of @code{buffer} (used for glyphs in an extent, the
|
|
|
1111 modeline, the toolbar, or elsewhere in a frame), @code{pointer} (used
|
|
|
1112 for the mouse-pointer), or @code{icon} (used for a frame's icon), and
|
|
|
1113 defaults to @code{buffer}.
|
|
|
1114 @end defun
|
|
|
1115
|
|
|
1116 @var{spec-list} is the initializer for the glyph's @code{image}
|
|
|
1117 property, which is an image specifier. (Note that @dfn{image} as used
|
|
|
1118 in the context of a glyph's @code{image} property or in the terms
|
|
|
1119 @dfn{image specifier}, @dfn{image instantiator}, or @dfn{image instance}
|
|
|
1120 does not refer to what people normally think of as an image (which in
|
|
|
1121 XEmacs is called a @dfn{pixmap}), but to any graphical element---a
|
|
|
1122 pixmap, a widget, or even a block of text, when used in the places that
|
|
|
1123 call for a glyph.)
|
|
|
1124
|
|
|
1125 The most common form of @var{spec-list} is a single image instantiator.
|
|
|
1126 (@strong{Compatibility note:} in GNU Emacs 21, a string used to
|
|
|
1127 instantiate an image is interpreted as the name of an image file, which
|
|
|
1128 is searched for and instantiated.) The conversion controlled by
|
|
|
1129 @code{console-type-image-conversion-list} typically attempts to look up
|
|
|
1130 the string as a file name in XEmacs's data directory path, and if this
|
|
|
1131 fails, defaults to displaying the string as a text image instance
|
|
|
1132 (@emph{i.e.}. the string itself.
|
|
|
1133
|
|
|
1134 Fine control of a particular specification is provided by using a vector
|
|
|
1135 as the image instantiator. More complicated instantiators allow lists
|
|
|
1136 of instantiators to be specified (which are tried in order), or mappings
|
|
|
1137 from locales to lists of instantiators, @emph{etc}. @xref{Specifiers},
|
|
|
1138 for more information about specification formats.
|
|
|
1139
|
|
|
1140 As well as using @var{spec-list} to initialize the glyph, you can set
|
|
|
1141 specifications using @code{set-glyph-image}. The glyph itself is not
|
|
|
1142 actually a specifier, but rather is an object containing an image
|
|
|
1143 specifier (as well as other properties seldom set by user code).
|
|
|
1144 Therefore, you cannot set or access specifications for the glyph's image
|
|
|
1145 by directly using @code{set-specifier}, @code{specifier-instance} or the
|
|
|
1146 like on the glyph; instead use them on @code{(glyph-image @var{glyph})}
|
|
|
1147 or use the convenience functions @code{set-glyph-image},
|
|
|
1148 @code{glyph-image-instance}, and @code{glyph-image}.
|
|
428
|
1149
|
|
2182
|
1150 Glyph types reflect the fact that glyphs are used in contexts like
|
|
|
1151 pointers and window manager icons, which are defined by external
|
|
|
1152 programs such as the window system or window manager. These require
|
|
|
1153 somewhat different @emph{internal} format, which is opaque to the user.
|
|
|
1154
|
|
|
1155 It is extremely rare that you will ever have to specify a value for
|
|
|
1156 @var{type}, which should be one of @code{buffer} (used for glyphs in an
|
|
|
1157 extent, the modeline, the toolbar, or elsewhere in a buffer),
|
|
|
1158 @code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
|
|
|
1159 frame's icon), and defaults to @code{buffer}. The only cases where it
|
|
|
1160 needs to be specified is when creating icon or pointer glyphs, and in
|
|
|
1161 both cases the necessary glyphs have already been created at startup and
|
|
|
1162 are accessed through the appropriate variables,
|
|
|
1163 e.g. @code{text-pointer-glyph} (or in general, any
|
|
|
1164 @samp{*-pointer-glyph}) and @code{frame-icon-glyph}. User code should
|
|
|
1165 never need to create @code{pointer} or @code{icon} glyphs. @xref{Glyph
|
|
|
1166 Types}.
|
|
|
1167
|
|
|
1168 There are a few other glyph creation functions, normally used only
|
|
|
1169 internally or at XEmacs initialization.
|
|
|
1170
|
|
|
1171 @defun make-glyph-internal &optional type
|
|
|
1172 This function creates a new, uninitialized glyph of type @var{type}.
|
|
|
1173 @end defun
|
|
|
1174
|
|
|
1175 @defun make-pointer-glyph &optional spec-list
|
|
442
|
1176
|
|
2182
|
1177 Return a new @code{pointer-glyph} object with the specification list
|
|
|
1178 @var{spec-list}. This function is equivalent to calling
|
|
|
1179 @code{make-glyph} with a @var{type} of @code{pointer}.
|
|
|
1180 @end defun
|
|
|
1181
|
|
|
1182 @code{make-pointer-glyph} is normally used only by XEmacs initialization
|
|
|
1183 code. It is extremely unlikely that you will ever need to create a
|
|
|
1184 pointer glyph. Instead, you probably want to be calling
|
|
|
1185 @code{set-glyph-image} on an existing glyph,
|
|
|
1186 e.g. @code{text-pointer-glyph}.
|
|
|
1187
|
|
|
1188 @defun make-icon-glyph &optional spec-list
|
|
|
1189
|
|
|
1190 Return a new @code{icon-glyph} object with the specification list
|
|
|
1191 @var{spec-list}. This function is equivalent to calling
|
|
|
1192 @code{make-glyph} with a @var{type} of @code{icon}.
|
|
|
1193 @end defun
|
|
|
1194
|
|
|
1195 @code{make-icon-glyph} is normally used only by XEmacs initialization
|
|
|
1196 code. It is extremely unlikely that you will ever need to create a icon
|
|
|
1197 glyph. Instead, you probably want to be calling @code{set-glyph-image}
|
|
|
1198 on the existing glyph, @code{frame-icon-glyph}.
|
|
|
1199
|
|
|
1200
|
|
|
1201 @node Buffer Glyphs
|
|
|
1202 @subsection Buffer Glyphs
|
|
442
|
1203
|
|
|
1204 Creating a glyph using @code{make-glyph} does not specify @emph{where}
|
|
2182
|
1205 the glyph will be used, it only specifies @emph{what} the glyph will
|
|
|
1206 look like. Once you have created a glyph, you specify where it will be
|
|
|
1207 used by attaching it to an extent as a @emph{begin-glyph} or
|
|
|
1208 @emph{end-glyph}.
|
|
442
|
1209
|
|
2182
|
1210 @table @code
|
|
|
1211 @item buffer text
|
|
442
|
1212 To insert a glyph into a buffer, create an extent in the buffer and then
|
|
|
1213 use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
|
|
2182
|
1214 a glyph to be displayed at the corresponding edge of the extent. (It is
|
|
442
|
1215 common to create zero-width extents for this purpose.)
|
|
|
1216
|
|
2182
|
1217 @item margins
|
|
442
|
1218 To insert a glyph into the left or right margin of a buffer, first
|
|
|
1219 make sure the margin is visible by setting a value for the specifiers
|
|
2182
|
1220 @code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
|
|
|
1221 when using margin glyphs with layout policy @code{whitespace}.) Follow
|
|
|
1222 the same procedure above for inserting a glyph in a buffer, then
|
|
442
|
1223 set a non-default layout policy for the glyph using
|
|
|
1224 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
|
|
|
1225 Alternatively, use the high-level annotations API (see
|
|
2182
|
1226 @code{make-annotation}). (In fact, you can also use the annotations
|
|
442
|
1227 API for glyphs in a buffer, by setting a layout policy of @code{text}.)
|
|
|
1228
|
|
2182
|
1229 @end table
|
|
|
1230
|
|
|
1231
|
|
|
1232 @node Redisplay Glyphs
|
|
|
1233 @subsection Redisplay Glyphs
|
|
|
1234
|
|
|
1235 To use a glyph to control the shape of miscellaneous redisplay effects
|
|
|
1236 such as the truncation and continuation markers, set the appropriate
|
|
|
1237 existing glyph variables with @code{set-glyph-image}. See
|
|
|
1238 @code{continuation-glyph}, @code{control-arrow-glyph},
|
|
|
1239 @code{hscroll-glyph}, @code{invisible-text-glyph},
|
|
|
1240 @code{octal-escape-glyph}, and @code{truncation-glyph}. See also
|
|
|
1241 @code{overlay-arrow-string}, an odd redisplay leftover which can be set
|
|
|
1242 to a glyph you created, and will cause the glyph to be displayed on top
|
|
|
1243 of the text position specified in the marker stored in
|
|
|
1244 @code{overlay-arrow-position}.
|
|
|
1245
|
|
|
1246 To use a glyph in a display table (i.e. to control the appearance of any
|
|
|
1247 individual character), create the appropriate character glyphs and then
|
|
|
1248 set a specification for the specifier @code{current-display-table},
|
|
|
1249 which controls the appearance of characters. You can also set an
|
|
|
1250 overriding display table for use with text displayed in a particular
|
|
|
1251 face; see @code{set-face-display-table} and @code{make-display-table}.
|
|
|
1252 #### Note: Display tables do not currently support general Mule
|
|
|
1253 characters. They will be overhauled at some point to support this
|
|
|
1254 and to provide other features required under Mule. @ref{Display Tables}.
|
|
|
1255
|
|
|
1256 Glyphs are not actually used as the background pixmaps of faces, but the
|
|
|
1257 API is similar. The
|
|
|
1258 background pixmap of a face is actually an image specifier -- probably
|
|
|
1259 the only place in XEmacs where an image specifier occurs outside of a
|
|
|
1260 glyph. If you would like to use a glyph's image as a background pixmap,
|
|
|
1261 you can extract it with @code{glyph-image}, and then add it to a face.
|
|
|
1262 @xref{Face Convenience Functions}.
|
|
|
1263
|
|
|
1264 @defvr Glyph truncation-glyph
|
|
|
1265 This variable specifies what is displayed at the end of truncated lines.
|
|
|
1266 @end defvr
|
|
|
1267
|
|
|
1268 @defvr Glyph continuation-glyph
|
|
|
1269 This variable specifies what is displayed at the end of wrapped lines.
|
|
|
1270 @end defvr
|
|
|
1271
|
|
|
1272 @defvr Glyph octal-escape-glyph
|
|
|
1273 This variable specifies what to prefix character codes displayed in octal
|
|
|
1274 with.
|
|
|
1275 @end defvr
|
|
|
1276
|
|
|
1277 @defvr Glyph hscroll-glyph
|
|
|
1278 This variable specifies what to display at the beginning of horizontally
|
|
|
1279 scrolled lines.
|
|
|
1280 @end defvr
|
|
|
1281
|
|
|
1282 @defvr Glyph invisible-text-glyph
|
|
|
1283 This variable specifies what to use to indicate the presence of
|
|
|
1284 invisible text. This is the glyph that is displayed when an ellipsis is
|
|
|
1285 called for, according to @code{selective-display-ellipses} or
|
|
|
1286 @code{buffer-invisibility-spec}). Normally this is three dots (``...'').
|
|
|
1287 @end defvr
|
|
|
1288
|
|
|
1289 @defvr Glyph control-arrow-glyph
|
|
|
1290 This variable specifies what to use as an arrow for control characters.
|
|
|
1291 @end defvr
|
|
|
1292
|
|
|
1293
|
|
|
1294 @node Frame Glyphs
|
|
|
1295 @subsection Frame Glyphs
|
|
|
1296
|
|
|
1297 There are also a number of special objects whose appearance is specified
|
|
|
1298 by a glyph. Most of these a global objects that you update with
|
|
|
1299 @code{set-glyph-image}, such as mouse pointers. Frame icons, toolbar
|
|
|
1300 button icons, and the modeline are the main non-text objects which
|
|
|
1301 accept glyphs as elements.
|
|
|
1302
|
|
|
1303 @table @code
|
|
|
1304 @item modeline
|
|
2127
|
1305 A glyph may be displayed in the modeline by inserting the glyph as one
|
|
|
1306 of the elements of the modeline format. (Unfortunately you can't
|
|
|
1307 currently put a begin glyph or end glyph on one of the modeline
|
|
|
1308 extents---they're ignored.)
|
|
442
|
1309
|
|
2182
|
1310 @item toolbar
|
|
2127
|
1311 To insert a glyph into a toolbar, specify it as the icon part of a toolbar
|
|
|
1312 button, which in turn must be part of a toolbar instantiator (typically
|
|
|
1313 set on the specifier @code{default-toolbar}).
|
|
|
1314 See @code{default-toolbar} for more information. (As a convenience, you
|
|
|
1315 may use a symbol in place of the glyph list in the toolbar button
|
|
|
1316 instantiator; the symbol is evalled to get the glyph list. This
|
|
442
|
1317 facilitates both creating the toolbar instantiator and modifying
|
|
|
1318 individual glyphs in a toolbar later on. For example, you can change
|
|
|
1319 the way that the Mail toolbar button looks by modifying the value of the
|
|
|
1320 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
|
|
|
1321 and then calling @code{(set-specifier-dirty-flag default-toolbar)}.
|
|
|
1322 (#### Unfortunately this doesn't quite work the way it should; the
|
|
2127
|
1323 change will appear in new frames, but not existing ones, because once an
|
|
|
1324 image has been displayed the pixmap replaces the symbol for those domains.)
|
|
442
|
1325
|
|
2182
|
1326 @item gutter
|
|
2127
|
1327 To insert a glyph into a gutter, use
|
|
442
|
1328 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
|
|
2127
|
1329 glyph to be displayed at the corresponding edge of extent in a string,
|
|
|
1330 similar to the way you insert glyphs in a buffer. Then insert the
|
|
2182
|
1331 string into the gutter @ref{Specifying a Gutter}. Glyphs that are
|
|
|
1332 frequently used in this way are @code{tab control} and @code{progress
|
|
|
1333 bar} glyphs.
|
|
|
1334
|
|
|
1335 @end table
|
|
|
1336
|
|
|
1337
|
|
|
1338 @node External Glyphs
|
|
|
1339 @subsection External Glyphs
|
|
|
1340 @cindex frame icon
|
|
|
1341 @cindex icon, frame
|
|
|
1342 @cindex mouse cursor
|
|
|
1343 @cindex cursor (mouse)
|
|
|
1344 @cindex pointer (mouse)
|
|
|
1345 @cindex mouse pointer
|
|
442
|
1346
|
|
2182
|
1347 There are two special kinds of glyph that are not displayed by XEmacs.
|
|
|
1348 Instead, they are used to set the appearance of iconified frames and the
|
|
|
1349 mouse pointer. Because these uses are constrained by the window system,
|
|
|
1350 icons and pointers have their own special types @xref{Glyph Types}.
|
|
442
|
1351
|
|
2182
|
1352 You may use a glyph as the icon for a frame. Do not create a new glyph;
|
|
|
1353 instead, change the specifications for the existing glyph
|
|
|
1354 @code{frame-icon-glyph} with @code{set-glyph-image}. This is a unique,
|
|
|
1355 predefined object. Although the natural usage is to set specifications
|
|
|
1356 for the global locale or a frame locale, you can also arrange for a
|
|
|
1357 special icon when a frame's selected window displays a particular buffer
|
|
|
1358 by using a buffer locale.
|
|
|
1359
|
|
|
1360 The shape of the mouse pointer when over a particular section of a frame
|
|
|
1361 is controlled using various glyph variables. Since the image of a glyph
|
|
|
1362 is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
|
|
|
1363 or per-device basis.
|
|
|
1364
|
|
442
|
1365 To use a glyph as the mouse pointer, in general you do not create a new
|
|
|
1366 glyph, but rather you change the specifications of various existing
|
|
|
1367 glyphs, such as @code{text-pointer-glyph} for the pointer used over
|
|
|
1368 text, @code{modeline-pointer-glyph} for the pointer used over the
|
|
2127
|
1369 modeline, etc. Do an apropos over @samp{pointer-glyph} to find all of
|
|
|
1370 them. (Note also that you can temporarily set the mouse pointer to some
|
|
442
|
1371 specific shape by using @code{set-frame-pointer}, which takes an image
|
|
|
1372 instance, as obtained from calling @code{glyph-image-instance} on a glyph
|
|
|
1373 of type @code{pointer} -- either one of the above-mentioned variables or
|
|
|
1374 one you created yourself. (See below for what it means to create a
|
|
|
1375 glyph of type @code{pointer}.) This pointer will last only until the
|
|
|
1376 next mouse motion event is processed or certain other things happen,
|
|
|
1377 such as creating or deleting a window. (In fact, the above-mentioned
|
|
|
1378 pointer glyph variables are implemented as part of the default handler
|
|
|
1379 for mouse motion events. If you want to customize this behavior, take a
|
|
|
1380 look at @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
|
|
|
1381 really want to get low-level.)
|
|
|
1382
|
|
2182
|
1383 You should use @code{set-glyph-image} to set the following variables,
|
|
|
1384 @emph{not} @code{setq}.
|
|
|
1385
|
|
|
1386 @defvr Glyph text-pointer-glyph
|
|
|
1387 This variable specifies the shape of the mouse pointer when over text.
|
|
|
1388 @end defvr
|
|
|
1389
|
|
|
1390 @defvr Glyph nontext-pointer-glyph
|
|
|
1391 This variable specifies the shape of the mouse pointer when over a
|
|
|
1392 buffer, but not over text. If unspecified in a particular domain,
|
|
|
1393 @code{text-pointer-glyph} is used.
|
|
|
1394 @end defvr
|
|
|
1395
|
|
|
1396 @defvr Glyph modeline-pointer-glyph
|
|
|
1397 This variable specifies the shape of the mouse pointer when over the modeline.
|
|
|
1398 If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
|
|
|
1399 @end defvr
|
|
|
1400
|
|
|
1401 @defvr Glyph selection-pointer-glyph
|
|
|
1402 This variable specifies the shape of the mouse pointer when over a
|
|
|
1403 selectable text region. If unspecified in a particular domain,
|
|
|
1404 @code{text-pointer-glyph} is used.
|
|
|
1405 @end defvr
|
|
|
1406
|
|
|
1407 @defvr Glyph gc-pointer-glyph
|
|
|
1408 This variable specifies the shape of the mouse pointer when a garbage
|
|
|
1409 collection is in progress. If the selected window is on a window system
|
|
|
1410 and this glyph specifies a value (i.e. a pointer image instance) in the
|
|
|
1411 domain of the selected window, the pointer will be changed as specified
|
|
|
1412 during garbage collection. Otherwise, a message will be printed in the
|
|
|
1413 echo area, as controlled by @code{gc-message}.
|
|
|
1414 @end defvr
|
|
442
|
1415
|
|
2182
|
1416 @defvr Glyph busy-pointer-glyph
|
|
|
1417 This variable specifies the shape of the mouse pointer when XEmacs is busy.
|
|
|
1418 If unspecified in a particular domain, the pointer is not changed
|
|
|
1419 when XEmacs is busy.
|
|
|
1420 @end defvr
|
|
|
1421
|
|
|
1422 @defvr Glyph menubar-pointer-glyph
|
|
|
1423 This variable specifies the shape of the mouse pointer when over the
|
|
|
1424 menubar. If unspecified in a particular domain, the
|
|
|
1425 window-system-provided default pointer is used.
|
|
|
1426 @end defvr
|
|
442
|
1427
|
|
2182
|
1428 @defvr Glyph scrollbar-pointer-glyph
|
|
|
1429 This variable specifies the shape of the mouse pointer when over a
|
|
|
1430 scrollbar. If unspecified in a particular domain, the
|
|
|
1431 window-system-provided default pointer is used.
|
|
|
1432 @end defvr
|
|
442
|
1433
|
|
2182
|
1434 @defvr Glyph toolbar-pointer-glyph
|
|
|
1435 This variable specifies the shape of the mouse pointer when over a
|
|
|
1436 toolbar. If unspecified in a particular domain,
|
|
|
1437 @code{nontext-pointer-glyph} is used.
|
|
|
1438 @end defvr
|
|
|
1439
|
|
|
1440 Internally, these variables are implemented in
|
|
|
1441 @code{default-mouse-motion-handler}, and thus only take effect when the
|
|
|
1442 mouse moves. That function calls @code{set-frame-pointer}, which sets
|
|
|
1443 the current mouse pointer for a frame.
|
|
|
1444
|
|
|
1445 @defun set-frame-pointer frame image-instance
|
|
|
1446 This function sets the mouse pointer of @var{frame} to the given pointer
|
|
|
1447 image instance. You should not call this function directly.
|
|
|
1448 (If you do, the pointer will change again the next time the mouse moves.)
|
|
428
|
1449 @end defun
|
|
|
1450
|
|
2182
|
1451
|
|
|
1452 @node Native GUI Widgets
|
|
|
1453 @subsection Native GUI Widgets
|
|
|
1454 @cindex native widget
|
|
|
1455
|
|
|
1456 A ``native widget'' is a primitive GUI object defined either by the host
|
|
|
1457 GUI platform or an external toolkit, and accessed from Lisp as a
|
|
|
1458 ``glyph.''
|
|
|
1459
|
|
|
1460 @menu
|
|
|
1461 * Introduction to Widgets:: Native widgets provide tight integration of
|
|
|
1462 GUI features with the platform GUI.
|
|
|
1463 * Lisp API to Native Widgets:: Native widgets are glyphs.
|
|
|
1464 * Layouts:: Specifying composite widgets from Lisp.
|
|
|
1465 * Primitive Widgets:: Catalogue of available native widgets.
|
|
|
1466 @end menu
|
|
|
1467
|
|
|
1468 @node Introduction to Widgets
|
|
|
1469 @subsubsection Introduction to Native Widgets and Subwindow Glyphs
|
|
|
1470
|
|
|
1471 Traditionally Emacsen have hidden the GUI apparatus from the Lisp
|
|
|
1472 programmer, but in XEmacs 21.4 the ability to embed autonomous GUI
|
|
|
1473 objects, called @dfn{native widgets}, in text was added to Lisp. They
|
|
|
1474 are handled as @emph{glyphs}. Unlike traditional XEmacs
|
|
|
1475 glyphs such images and strings, native widgets are opaque to XEmacs, and
|
|
|
1476 must be able to redraw themselves because they are implemented as
|
|
|
1477 subwindows, not as graphics drawn by XEmacs into the text window.
|
|
|
1478
|
|
|
1479 Primitive widgets are coded in C using the underlying GUI toolkit, and
|
|
|
1480 thus are beyond the scope of the @emph{XEmacs Lisp Reference Manual}.
|
|
|
1481 However, composite widgets can be created in Lisp using ``layouts,''
|
|
|
1482 which are horizontal or vertical arrays of subwidgets. For example, the
|
|
|
1483 search dialog is formatted using layouts.
|
|
|
1484
|
|
|
1485 @node Lisp API to Native Widgets
|
|
|
1486 @subsubsection Lisp API to Native Widgets
|
|
|
1487
|
|
|
1488 Native widgets are manipulated as @emph{glyphs} (@pxref{Glyphs}). Thus
|
|
|
1489 they are created using @code{make-glyph}, with a format of one of the
|
|
|
1490 widget types and a @code{:data} property specific to the widget being
|
|
2953
|
1491 instantiated.
|
|
2182
|
1492
|
|
|
1493 However, there is a technical difference between widgets and other kinds
|
|
|
1494 of glyphs that is theoretically important. Because widgets
|
|
|
1495 are active (that is, they can respond to user input events themselves),
|
|
|
1496 it is possible for the user to become aware that two appearances of the
|
|
|
1497 ``same'' glyph are actually separate instances. For example, if a user
|
|
|
1498 changes an image glyph from red to blue, and the buffer containing the
|
|
|
1499 glyph appears in more than one window, the user will perceive all the
|
|
|
1500 appearances to change from red to blue simultaneously. However, suppose
|
|
|
1501 the glyph is a button glyph (@emph{e.g.}, as used in the Customize
|
|
|
1502 buffer for the Set, Save, and Done buttons). Then if the Customize
|
|
|
1503 buffer appears in several windows at the same time, and the user clicks
|
|
|
1504 on the button, she will only perceive the button to be depressed in the
|
|
|
1505 window where she clicked the button.
|
|
|
1506
|
|
|
1507 It seems from this example that it is unlikely to be a problem in
|
|
|
1508 practice. When the user is faced with an active widget, it seems likely
|
|
|
1509 that attention will focus on the widget being manipulated, and having
|
|
|
1510 other instances of the widget respond simultaneously might be more
|
|
|
1511 disconcerting than the actual case.
|
|
|
1512
|
|
|
1513 @node Layouts
|
|
|
1514 @subsubsection Layouts
|
|
|
1515
|
|
|
1516 An XEmacs @dfn{layout} is a one-dimensional array of glyphs. It is a
|
|
|
1517 widget for controlling the positioning of children underneath it.
|
|
|
1518 Through the use of nested layouts, a widget hierarchy can be created
|
|
|
1519 which can have the appearance of any standard dialog box or similar
|
|
|
1520 arrangement; all of this is counted as one "glyph" and could appear in
|
|
|
1521 many of the places that expect a single glyph.
|
|
|
1522
|
|
|
1523 (There are also @dfn{native layouts}, but I don't know what these are or
|
|
|
1524 how they are used.)
|
|
|
1525
|
|
|
1526 A layout descriptor is an image instantiator, @emph{i.e.}, a vector of
|
|
|
1527 the form @samp{[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]} with format
|
|
|
1528 @code{layout}, and properties
|
|
|
1529
|
|
|
1530 @c #### need defaults for these
|
|
|
1531 @table @code
|
|
|
1532 @item :orientation
|
|
|
1533 Specifies the orientation of the contained array of glyphs. The value
|
|
|
1534 must be one of the symbols @code{horizontal} or @code{vertical}.
|
|
|
1535
|
|
|
1536 @item :horizontally-justify
|
|
|
1537 Specifies the horizontal justification of the items in the array. The
|
|
|
1538 value must be one of the symbols @code{:right}, @code{:center}, or
|
|
|
1539 @code{:left}.
|
|
|
1540
|
|
|
1541 @item :vertically-justify
|
|
|
1542 Specifies the vertical justification of the items in the array. The
|
|
|
1543 value must be one of the symbols @code{:top}, @code{:center}, or
|
|
|
1544 @code{:bottom}.
|
|
|
1545
|
|
|
1546 @item :justify
|
|
|
1547 Specifies justification. #### not understood.
|
|
|
1548
|
|
|
1549 @item :border
|
|
|
1550 A glyph to place in the border. The value must be an image
|
|
|
1551 instantiator.
|
|
|
1552
|
|
|
1553 @item :items
|
|
|
1554 The glyphs controlled by the layout. The value must be a list of image
|
|
|
1555 instantiators.
|
|
|
1556 @end table
|
|
|
1557
|
|
|
1558 Here is the specification of the search dialog widget created by
|
|
|
1559 @code{make-search-dialog} in the @file{dialog-items} library, which
|
|
|
1560 makes use of recursive layouts.
|
|
|
1561
|
|
|
1562 @example
|
|
|
1563 (make-glyph
|
|
|
1564 `[layout
|
|
|
1565 :orientation horizontal
|
|
|
1566 :vertically-justify top
|
|
|
1567 :horizontally-justify center
|
|
|
1568 :border [string :data "Search"]
|
|
|
1569 :items
|
|
|
1570 ([layout :orientation vertical
|
|
|
1571 :justify top ; implies left also
|
|
|
1572 :items
|
|
|
1573 ([string :data "Search for:"]
|
|
|
1574 [button :descriptor "Match Case"
|
|
|
1575 :style toggle
|
|
|
1576 :selected (not case-fold-search)
|
|
|
1577 :callback (setq case-fold-search
|
|
|
1578 (not case-fold-search))]
|
|
|
1579 [button :descriptor "Regular Expression"
|
|
|
1580 :style toggle
|
|
|
1581 :selected search-dialog-regexp
|
|
|
1582 :callback (setq search-dialog-regexp
|
|
|
1583 (not search-dialog-regexp))]
|
|
|
1584 [button :descriptor "Forwards"
|
|
|
1585 :style radio
|
|
|
1586 :selected search-dialog-direction
|
|
|
1587 :callback (setq search-dialog-direction t)]
|
|
|
1588 [button :descriptor "Backwards"
|
|
|
1589 :style radio
|
|
|
1590 :selected (not search-dialog-direction)
|
|
|
1591 :callback (setq search-dialog-direction nil)]
|
|
|
1592 )]
|
|
|
1593 [layout :orientation vertical
|
|
|
1594 :vertically-justify top
|
|
|
1595 :horizontally-justify right
|
|
|
1596 :items
|
|
|
1597 ([edit-field :width 15 :descriptor "" :active t
|
|
|
1598 :initial-focus t]
|
|
|
1599 [button :width 10 :descriptor "Find Next"
|
|
|
1600 :callback-ex
|
|
|
1601 (lambda (image-instance event)
|
|
|
1602 (search-dialog-callback ,parent
|
|
|
1603 image-instance
|
|
|
1604 event))]
|
|
|
1605 [button :width 10 :descriptor "Cancel"
|
|
|
1606 :callback-ex
|
|
|
1607 (lambda (image-instance event)
|
|
|
1608 (isearch-dehighlight)
|
|
|
1609 (delete-frame
|
|
|
1610 (event-channel event)))])])])
|
|
|
1611 @end example
|
|
|
1612
|
|
|
1613 @node Primitive Widgets
|
|
|
1614 @subsubsection Primitive Widgets
|
|
|
1615
|
|
|
1616 @c #### the following table should be replaced with a menu of nodes
|
|
|
1617 @table @code
|
|
|
1618 @item button
|
|
|
1619 A button widget; either a push button, radio button or toggle
|
|
|
1620 button.
|
|
|
1621
|
|
|
1622 @item combo-box
|
|
|
1623 A drop list of selectable items in a widget, for editing text.
|
|
|
1624
|
|
|
1625 @item edit-field
|
|
|
1626 A text editing widget.
|
|
|
1627
|
|
|
1628 @item label
|
|
|
1629 A static, text-only, widget; for displaying text.
|
|
|
1630
|
|
|
1631 @item progress-gauge
|
|
|
1632 A sliding widget, for showing progress.
|
|
|
1633
|
|
|
1634 @item tab-control
|
|
|
1635 A tab widget; a series of user selectable tabs.
|
|
|
1636
|
|
|
1637 @item tree-view
|
|
|
1638 A folding widget.
|
|
|
1639
|
|
|
1640 @item scrollbar
|
|
|
1641 A scrollbar widget. (#### Probably not the same as the scrollbar
|
|
|
1642 controlling an Emacs window.)
|
|
|
1643 @end table
|
|
|
1644
|
|
|
1645
|
|
|
1646 @node Subwindows
|
|
|
1647 @subsection Subwindows
|
|
|
1648
|
|
|
1649 Subwindows are not currently implemented.
|
|
|
1650 @c #### Check status of subwindows ... I thought Andy implemented them.
|
|
|
1651
|
|
|
1652 @defun subwindowp object
|
|
|
1653 This function returns non-@code{nil} if @var{object} is a subwindow.
|
|
428
|
1654 @end defun
|
|
|
1655
|
|
442
|
1656
|
|
2182
|
1657 @node Manipulating Glyphs
|
|
|
1658 @section Manipulating Glyphs
|
|
428
|
1659
|
|
2182
|
1660 Each glyphs has properties that may be accessed. Most of these can
|
|
|
1661 also be set after the glyph is initialized, with the exception of the
|
|
|
1662 glyph's type. This is not a real restriction, as it is almost never
|
|
|
1663 useful to create glyphs of types other than @code{buffer}.
|
|
442
|
1664
|
|
2182
|
1665 @menu
|
|
|
1666 * Glyph Properties:: Accessing and modifying a glyph's properties.
|
|
|
1667 * Glyph Convenience Functions:: Accessing particular properties of a glyph.
|
|
|
1668 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
|
|
|
1669 * Glyph Types:: Each glyph has a particular type.
|
|
|
1670 @end menu
|
|
442
|
1671
|
|
428
|
1672
|
|
|
1673 @node Glyph Properties
|
|
|
1674 @subsection Glyph Properties
|
|
|
1675
|
|
|
1676 Each glyph has a list of properties, which control all of the aspects of
|
|
|
1677 the glyph's appearance. The following symbols have predefined meanings:
|
|
|
1678
|
|
|
1679 @table @code
|
|
|
1680 @item image
|
|
|
1681 The image used to display the glyph.
|
|
|
1682
|
|
|
1683 @item baseline
|
|
|
1684 Percent above baseline that glyph is to be displayed. Only for glyphs
|
|
|
1685 displayed inside of a buffer.
|
|
|
1686
|
|
|
1687 @item contrib-p
|
|
|
1688 Whether the glyph contributes to the height of the line it's on.
|
|
|
1689 Only for glyphs displayed inside of a buffer.
|
|
|
1690
|
|
|
1691 @item face
|
|
|
1692 Face of this glyph (@emph{not} a specifier).
|
|
|
1693 @end table
|
|
|
1694
|
|
|
1695 @defun set-glyph-property glyph property value &optional locale tag-set how-to-add
|
|
|
1696 This function changes a property of a @var{glyph}.
|
|
|
1697
|
|
|
1698 For built-in properties, the actual value of the property is a specifier
|
|
|
1699 and you cannot change this; but you can change the specifications within
|
|
2182
|
1700 the specifier, and that is what this function will do. The glyph face
|
|
|
1701 is an exception; it is a face name (a symbol) or a face object, not a
|
|
|
1702 specifier. (The face properties themselves are typically specifiers.)
|
|
|
1703 For user-defined properties, you can use this function to either change
|
|
|
1704 the actual value of the property or, if this value is a specifier,
|
|
|
1705 change the specifications within it.
|
|
428
|
1706
|
|
|
1707 If @var{property} is a built-in property, the specifications to be added
|
|
|
1708 to this property can be supplied in many different ways:
|
|
|
1709
|
|
|
1710 @itemize @bullet
|
|
|
1711 @item
|
|
|
1712 If @var{value} is a simple instantiator (e.g. a string naming a pixmap
|
|
|
1713 filename) or a list of instantiators, then the instantiator(s) will be
|
|
|
1714 added as a specification of the property for the given @var{locale}
|
|
|
1715 (which defaults to @code{global} if omitted).
|
|
|
1716
|
|
|
1717 @item
|
|
|
1718 If @var{value} is a list of specifications (each of which is a cons of a
|
|
|
1719 locale and a list of instantiators), then @var{locale} must be
|
|
|
1720 @code{nil} (it does not make sense to explicitly specify a locale in
|
|
|
1721 this case), and specifications will be added as given.
|
|
|
1722
|
|
|
1723 @item
|
|
|
1724 If @var{value} is a specifier (as would be returned by
|
|
|
1725 @code{glyph-property} if no @var{locale} argument is given), then some
|
|
|
1726 or all of the specifications in the specifier will be added to the
|
|
|
1727 property. In this case, the function is really equivalent to
|
|
|
1728 @code{copy-specifier} and @var{locale} has the same semantics (if it is
|
|
|
1729 a particular locale, the specification for the locale will be copied; if
|
|
|
1730 a locale type, specifications for all locales of that type will be
|
|
|
1731 copied; if @code{nil} or @code{all}, then all specifications will be
|
|
|
1732 copied).
|
|
|
1733 @end itemize
|
|
|
1734
|
|
|
1735 @var{how-to-add} should be either @code{nil} or one of the symbols
|
|
|
1736 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
|
|
|
1737 @code{remove-tag-set-append}, @code{remove-locale},
|
|
|
1738 @code{remove-locale-type}, or @code{remove-all}. See
|
|
|
1739 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
|
|
|
1740 of what each of these means. Most of the time, you do not need to worry
|
|
|
1741 about this argument; the default behavior usually is fine.
|
|
|
1742
|
|
|
1743 In general, it is OK to pass an instance object (e.g. as returned by
|
|
|
1744 @code{glyph-property-instance}) as an instantiator in place of an actual
|
|
|
1745 instantiator. In such a case, the instantiator used to create that
|
|
|
1746 instance object will be used (for example, if you set a font-instance
|
|
|
1747 object as the value of the @code{font} property, then the font name used
|
|
2028
|
1748 to create that object will be used instead). In some cases, however,
|
|
428
|
1749 doing this conversion does not make sense, and this will be noted in the
|
|
|
1750 documentation for particular types of instance objects.
|
|
|
1751
|
|
|
1752 If @var{property} is not a built-in property, then this function will
|
|
|
1753 simply set its value if @var{locale} is @code{nil}. However, if
|
|
|
1754 @var{locale} is given, then this function will attempt to add
|
|
|
1755 @var{value} as the instantiator for the given @var{locale}, using
|
|
|
1756 @code{add-spec-to-specifier}. If the value of the property is not a
|
|
|
1757 specifier, it will automatically be converted into a @code{generic}
|
|
|
1758 specifier.
|
|
|
1759 @end defun
|
|
|
1760
|
|
|
1761 @defun glyph-property glyph property &optional locale
|
|
|
1762 This function returns @var{glyph}'s value of the given @var{property}.
|
|
|
1763
|
|
|
1764 If @var{locale} is omitted, the @var{glyph}'s actual value for
|
|
|
1765 @var{property} will be returned. For built-in properties, this will be
|
|
|
1766 a specifier object of a type appropriate to the property (e.g. a font or
|
|
|
1767 color specifier). For other properties, this could be anything.
|
|
|
1768
|
|
|
1769 If @var{locale} is supplied, then instead of returning the actual value,
|
|
|
1770 the specification(s) for the given locale or locale type will be
|
|
|
1771 returned. This will only work if the actual value of @var{property} is
|
|
|
1772 a specifier (this will always be the case for built-in properties, but
|
|
|
1773 may or may not apply to user-defined properties). If the actual value
|
|
|
1774 of @var{property} is not a specifier, this value will simply be returned
|
|
|
1775 regardless of @var{locale}.
|
|
|
1776
|
|
|
1777 The return value will be a list of instantiators (e.g. vectors
|
|
|
1778 specifying pixmap data), or a list of specifications, each of which is a
|
|
|
1779 cons of a locale and a list of instantiators. Specifically, if
|
|
|
1780 @var{locale} is a particular locale (a buffer, window, frame, device, or
|
|
|
1781 @code{global}), a list of instantiators for that locale will be
|
|
|
1782 returned. Otherwise, if @var{locale} is a locale type (one of the
|
|
|
1783 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
|
|
|
1784 the specifications for all locales of that type will be returned.
|
|
|
1785 Finally, if @var{locale} is @code{all}, the specifications for all
|
|
|
1786 locales of all types will be returned.
|
|
|
1787
|
|
|
1788 The specifications in a specifier determine what the value of
|
|
|
1789 @var{property} will be in a particular @dfn{domain} or set of
|
|
|
1790 circumstances, which is typically a particular Emacs window along with
|
|
|
1791 the buffer it contains and the frame and device it lies within. The
|
|
|
1792 value is derived from the instantiator associated with the most specific
|
|
|
1793 locale (in the order buffer, window, frame, device, and @code{global})
|
|
|
1794 that matches the domain in question. In other words, given a domain
|
|
|
1795 (i.e. an Emacs window, usually), the specifier for @var{property} will
|
|
|
1796 first be searched for a specification whose locale is the buffer
|
|
|
1797 contained within that window; then for a specification whose locale is
|
|
|
1798 the window itself; then for a specification whose locale is the frame
|
|
|
1799 that the window is contained within; etc. The first instantiator that
|
|
|
1800 is valid for the domain (usually this means that the instantiator is
|
|
|
1801 recognized by the device [i.e. the X server or TTY device] that the
|
|
|
1802 domain is on). The function @code{glyph-property-instance} actually does
|
|
|
1803 all this, and is used to determine how to display the glyph.
|
|
|
1804 @end defun
|
|
|
1805
|
|
|
1806 @defun glyph-property-instance glyph property &optional domain default no-fallback
|
|
|
1807 This function returns the instance of @var{glyph}'s @var{property} in the
|
|
|
1808 specified @var{domain}.
|
|
|
1809
|
|
|
1810 Under most circumstances, @var{domain} will be a particular window, and
|
|
|
1811 the returned instance describes how the specified property actually is
|
|
|
1812 displayed for that window and the particular buffer in it. Note that
|
|
|
1813 this may not be the same as how the property appears when the buffer is
|
|
|
1814 displayed in a different window or frame, or how the property appears in
|
|
|
1815 the same window if you switch to another buffer in that window; and in
|
|
|
1816 those cases, the returned instance would be different.
|
|
|
1817
|
|
|
1818 The returned instance is an image-instance object, and you can query it
|
|
|
1819 using the appropriate image instance functions. For example, you could use
|
|
|
1820 @code{image-instance-depth} to find out the depth (number of color
|
|
|
1821 planes) of a pixmap displayed in a particular window. The results might
|
|
|
1822 be different from the results you would get for another window (perhaps
|
|
|
1823 the user specified a different image for the frame that window is on; or
|
|
|
1824 perhaps the same image was specified but the window is on a different X
|
|
|
1825 server, and that X server has different color capabilities from this
|
|
|
1826 one).
|
|
|
1827
|
|
|
1828 @var{domain} defaults to the selected window if omitted.
|
|
|
1829
|
|
|
1830 @var{domain} can be a frame or device, instead of a window. The value
|
|
|
1831 returned for such a domain is used in special circumstances when a
|
|
|
1832 more specific domain does not apply; for example, a frame value might be
|
|
|
1833 used for coloring a toolbar, which is conceptually attached to a frame
|
|
|
1834 rather than a particular window. The value is also useful in
|
|
|
1835 determining what the value would be for a particular window within the
|
|
|
1836 frame or device, if it is not overridden by a more specific
|
|
|
1837 specification.
|
|
|
1838
|
|
|
1839 If @var{property} does not name a built-in property, its value will
|
|
|
1840 simply be returned unless it is a specifier object, in which case it
|
|
2953
|
1841 will be instantiated using @code{specifier-instance}.
|
|
428
|
1842
|
|
|
1843 Optional arguments @var{default} and @var{no-fallback} are the same as
|
|
|
1844 in @code{specifier-instance}. @xref{Specifiers}.
|
|
|
1845 @end defun
|
|
|
1846
|
|
|
1847 @defun remove-glyph-property glyph property &optional locale tag-set exact-p
|
|
|
1848 This function removes a property from a glyph. For built-in properties,
|
|
|
1849 this is analogous to @code{remove-specifier}. @xref{Specifiers,
|
|
|
1850 remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
|
|
|
1851 and @var{exact-p} arguments.
|
|
|
1852 @end defun
|
|
|
1853
|
|
2182
|
1854
|
|
428
|
1855 @node Glyph Convenience Functions
|
|
|
1856 @subsection Glyph Convenience Functions
|
|
|
1857
|
|
|
1858 The following functions are provided for working with specific
|
|
|
1859 properties of a glyph. Note that these are exactly like calling
|
|
|
1860 the general functions described above and passing in the
|
|
|
1861 appropriate value for @var{property}.
|
|
|
1862
|
|
|
1863 Remember that if you want to determine the ``value'' of a
|
|
|
1864 specific glyph property, you probably want to use the @code{*-instance}
|
|
|
1865 functions. For example, to determine whether a glyph contributes
|
|
|
1866 to its line height, use @code{glyph-contrib-p-instance}, not
|
|
|
1867 @code{glyph-contrib-p}. (The latter will return a boolean specifier
|
|
|
1868 or a list of specifications, and you probably aren't concerned with
|
|
|
1869 these.)
|
|
|
1870
|
|
|
1871 @defun glyph-image glyph &optional locale
|
|
|
1872 This function is equivalent to calling @code{glyph-property} with
|
|
|
1873 a property of @code{image}. The return value will be an image
|
|
|
1874 specifier if @var{locale} is @code{nil} or omitted; otherwise,
|
|
|
1875 it will be a specification or list of specifications.
|
|
|
1876 @end defun
|
|
|
1877
|
|
|
1878 @defun set-glyph-image glyph spec &optional locale tag-set how-to-add
|
|
|
1879 This function is equivalent to calling @code{set-glyph-property} with
|
|
|
1880 a property of @code{image}.
|
|
|
1881 @end defun
|
|
|
1882
|
|
|
1883 @defun glyph-image-instance glyph &optional domain default no-fallback
|
|
|
1884 This function returns the instance of @var{glyph}'s image in the given
|
|
|
1885 @var{domain}, and is equivalent to calling
|
|
|
1886 @code{glyph-property-instance} with a property of @code{image}. The
|
|
|
1887 return value will be an image instance.
|
|
|
1888
|
|
|
1889 Normally @var{domain} will be a window or @code{nil} (meaning the
|
|
|
1890 selected window), and an instance object describing how the image
|
|
|
1891 appears in that particular window and buffer will be returned.
|
|
|
1892 @end defun
|
|
|
1893
|
|
|
1894 @defun glyph-contrib-p glyph &optional locale
|
|
|
1895 This function is equivalent to calling @code{glyph-property} with
|
|
|
1896 a property of @code{contrib-p}. The return value will be a boolean
|
|
|
1897 specifier if @var{locale} is @code{nil} or omitted; otherwise,
|
|
|
1898 it will be a specification or list of specifications.
|
|
|
1899 @end defun
|
|
|
1900
|
|
|
1901 @defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
|
|
|
1902 This function is equivalent to calling @code{set-glyph-property} with
|
|
|
1903 a property of @code{contrib-p}.
|
|
|
1904 @end defun
|
|
|
1905
|
|
|
1906 @defun glyph-contrib-p-instance glyph &optional domain default no-fallback
|
|
|
1907 This function returns whether the glyph contributes to its line height
|
|
|
1908 in the given @var{domain}, and is equivalent to calling
|
|
|
1909 @code{glyph-property-instance} with a property of @code{contrib-p}. The
|
|
|
1910 return value will be either @code{nil} or @code{t}. (Normally @var{domain}
|
|
|
1911 will be a window or @code{nil}, meaning the selected window.)
|
|
|
1912 @end defun
|
|
|
1913
|
|
|
1914 @defun glyph-baseline glyph &optional locale
|
|
|
1915 This function is equivalent to calling @code{glyph-property} with a
|
|
|
1916 property of @code{baseline}. The return value will be a specifier if
|
|
|
1917 @var{locale} is @code{nil} or omitted; otherwise, it will be a
|
|
|
1918 specification or list of specifications.
|
|
|
1919 @end defun
|
|
|
1920
|
|
|
1921 @defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
|
|
|
1922 This function is equivalent to calling @code{set-glyph-property} with
|
|
|
1923 a property of @code{baseline}.
|
|
|
1924 @end defun
|
|
|
1925
|
|
|
1926 @defun glyph-baseline-instance glyph &optional domain default no-fallback
|
|
|
1927 This function returns the instance of @var{glyph}'s baseline value in
|
|
|
1928 the given @var{domain}, and is equivalent to calling
|
|
|
1929 @code{glyph-property-instance} with a property of @code{baseline}. The
|
|
|
1930 return value will be an integer or @code{nil}.
|
|
|
1931
|
|
|
1932 Normally @var{domain} will be a window or @code{nil} (meaning the
|
|
|
1933 selected window), and an instance object describing the baseline value
|
|
|
1934 appears in that particular window and buffer will be returned.
|
|
|
1935 @end defun
|
|
|
1936
|
|
|
1937 @defun glyph-face glyph
|
|
|
1938 This function returns the face of @var{glyph}. (Remember, this is
|
|
|
1939 not a specifier, but a simple property.)
|
|
|
1940 @end defun
|
|
|
1941
|
|
|
1942 @defun set-glyph-face glyph face
|
|
|
1943 This function changes the face of @var{glyph} to @var{face}.
|
|
|
1944 @end defun
|
|
|
1945
|
|
2182
|
1946
|
|
428
|
1947 @node Glyph Dimensions
|
|
|
1948 @subsection Glyph Dimensions
|
|
|
1949
|
|
|
1950 @defun glyph-width glyph &optional window
|
|
|
1951 This function returns the width of @var{glyph} on @var{window}. This
|
|
|
1952 may not be exact as it does not take into account all of the context
|
|
|
1953 that redisplay will.
|
|
|
1954 @end defun
|
|
|
1955
|
|
|
1956 @defun glyph-ascent glyph &optional window
|
|
|
1957 This function returns the ascent value of @var{glyph} on @var{window}.
|
|
|
1958 This may not be exact as it does not take into account all of the
|
|
|
1959 context that redisplay will.
|
|
|
1960 @end defun
|
|
|
1961
|
|
|
1962 @defun glyph-descent glyph &optional window
|
|
|
1963 This function returns the descent value of @var{glyph} on @var{window}.
|
|
|
1964 This may not be exact as it does not take into account all of the
|
|
|
1965 context that redisplay will.
|
|
|
1966 @end defun
|
|
|
1967
|
|
|
1968 @defun glyph-height glyph &optional window
|
|
|
1969 This function returns the height of @var{glyph} on @var{window}. (This
|
|
|
1970 is equivalent to the sum of the ascent and descent values.) This may
|
|
|
1971 not be exact as it does not take into account all of the context that
|
|
|
1972 redisplay will.
|
|
|
1973 @end defun
|
|
|
1974
|
|
|
1975
|
|
|
1976 @node Glyph Types
|
|
2182
|
1977 @subsection Glyph Types
|
|
428
|
1978
|
|
|
1979 Each glyph has a particular type, which controls how the glyph's image
|
|
|
1980 is generated. Each glyph type has a corresponding list of allowable
|
|
|
1981 image instance types that can be generated. When you call
|
|
|
1982 @code{glyph-image-instance} to retrieve the image instance of a glyph,
|
|
|
1983 XEmacs does the equivalent of calling @code{make-image-instance} and
|
|
|
1984 passing in @var{dest-types} the list of allowable image instance types
|
|
|
1985 for the glyph's type.
|
|
|
1986
|
|
|
1987 @itemize @bullet
|
|
|
1988 @item
|
|
|
1989 @code{buffer} glyphs can be used as the begin-glyph or end-glyph of an
|
|
|
1990 extent, in the modeline, and in the toolbar. Their image can be
|
|
|
1991 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
|
|
|
1992 @code{text}, and @code{subwindow}.
|
|
2182
|
1993 @c #### Check status of subwindows ... I thought Andy implemented them.
|
|
428
|
1994
|
|
|
1995 @item
|
|
|
1996 @code{pointer} glyphs can be used to specify the mouse pointer. Their
|
|
|
1997 image can be instantiated as @code{pointer}.
|
|
|
1998
|
|
|
1999 @item
|
|
|
2000 @code{icon} glyphs can be used to specify the icon used when a frame is
|
|
|
2001 iconified. Their image can be instantiated as @code{mono-pixmap} and
|
|
|
2002 @code{color-pixmap}.
|
|
|
2003 @end itemize
|
|
|
2004
|
|
|
2005 @defun glyph-type glyph
|
|
|
2006 This function returns the type of the given glyph. The return value
|
|
|
2007 will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}.
|
|
|
2008 @end defun
|
|
|
2009
|
|
|
2010 @defun valid-glyph-type-p glyph-type
|
|
|
2011 Given a @var{glyph-type}, this function returns non-@code{nil} if it is
|
|
|
2012 valid.
|
|
|
2013 @end defun
|
|
|
2014
|
|
|
2015 @defun glyph-type-list
|
|
|
2016 This function returns a list of valid glyph types.
|
|
|
2017 @end defun
|
|
|
2018
|
|
|
2019 @defun buffer-glyph-p object
|
|
|
2020 This function returns non-@code{nil} if @var{object} is a glyph of type
|
|
|
2021 @code{buffer}.
|
|
|
2022 @end defun
|
|
|
2023
|
|
|
2024 @defun icon-glyph-p object
|
|
|
2025 This function returns non-@code{nil} if @var{object} is a glyph of type
|
|
|
2026 @code{icon}.
|
|
|
2027 @end defun
|
|
|
2028
|
|
|
2029 @defun pointer-glyph-p object
|
|
|
2030 This function returns non-@code{nil} if @var{object} is a glyph of type
|
|
|
2031 @code{pointer}.
|
|
|
2032 @end defun
|
|
|
2033
|
|
707
|
2034
|
|
|
2035 @node Glyph Examples
|
|
|
2036 @section Glyph Examples
|
|
|
2037
|
|
|
2038 For many applications, displaying graphics is a simple process: you
|
|
|
2039 create a glyph, and then you insert it into a buffer.
|
|
|
2040
|
|
|
2041 The easiest way to create a glyph is to use a file that contains a
|
|
|
2042 graphical image, such as a JPEG, TIFF, or PNG file:
|
|
|
2043
|
|
|
2044 @lisp
|
|
|
2045 ;; Create a glyph from a JPEG file:
|
|
|
2046 (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
|
|
|
2047 @end lisp
|
|
|
2048
|
|
|
2049 @lisp
|
|
|
2050 ;; Create a glyph from a XPM file:
|
|
|
2051 (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
|
|
|
2052 @end lisp
|
|
|
2053
|
|
|
2054 @lisp
|
|
|
2055 ;; Create a glyph from a PNG file:
|
|
|
2056 (setq foo (make-glyph [png :file "/tmp/file3.png"]))
|
|
|
2057 @end lisp
|
|
|
2058
|
|
|
2059 @lisp
|
|
|
2060 ;; Create a glyph from a TIFF file:
|
|
|
2061 (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
|
|
|
2062 @end lisp
|
|
|
2063
|
|
|
2064 The parameters passed to @code{make-glyph} are called "Image
|
|
|
2065 Specifiers", and can handle more image types than those shown above.
|
|
|
2066 You can also put the raw image data into a string (e.g., if you put the
|
|
|
2067 contents of a JPEG file into a string), and use that to create a glyph.
|
|
2953
|
2068 @xref{Image Instantiators}, for more information.
|
|
707
|
2069
|
|
|
2070 @quotation
|
|
|
2071 @strong{Caution}: In order for XEmacs to read a particular graphics file
|
|
|
2072 format, support for that format must have been compiled into XEmacs.
|
|
|
2073 It's possible, although somewhat unlikely, for XEmacs to have been
|
|
|
2074 compiled without support for any of the various graphics file formats.
|
|
|
2075 To see what graphics formats your particular version of XEmacs supports,
|
|
|
2076 use @kbd{M-x describe-installation}.
|
|
|
2077
|
|
|
2078 To programmatically query whether or not a particular file format is
|
|
|
2079 supported, you can use the @code{featurep} function, with one of:
|
|
|
2080 @code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm},
|
|
|
2081 @code{png}, or @code{xface}. For an up-to-date list, @ref{Image
|
|
2953
|
2082 Instantiators}. Example:
|
|
707
|
2083
|
|
|
2084 @example
|
|
|
2085 ;; Returns `t' if TIFF is supported:
|
|
|
2086 (featurep 'tiff)
|
|
|
2087 @end example
|
|
|
2088
|
|
|
2089 Another example is:
|
|
|
2090
|
|
|
2091 @example
|
|
|
2092 ;; Returns a list of `t' or `nil', depending on whether or not the
|
|
|
2093 ;; corresponding feature is supported:
|
|
|
2094 (mapcar #'(lambda (format-symbol) (featurep format-symbol))
|
|
|
2095 '(gif tiff jpeg xpm png))
|
|
|
2096 @end example
|
|
|
2097
|
|
|
2098 @end quotation
|
|
|
2099
|
|
|
2100 Once you have a glyph, you can then insert it into a buffer. Example:
|
|
|
2101
|
|
|
2102 @lisp
|
|
|
2103 ;; Use this function to insert a glyph at the left edge of point in the
|
|
|
2104 ;; current buffer. Any existing glyph at this location is replaced.
|
|
|
2105 (defun insert-glyph (gl)
|
|
|
2106 "Insert a glyph at the left edge of point."
|
|
1137
|
2107 (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen
|
|
707
|
2108 ;; to (hopefully) not conflict with any
|
|
|
2109 ;; other properties. Change it if
|
|
|
2110 ;; necessary.
|
|
|
2111 extent )
|
|
|
2112 ;; First, check to see if one of our extents already exists at
|
|
|
2113 ;; point. For ease-of-programming, we are creating and using our
|
|
|
2114 ;; own extents (multiple extents are allowed to exist/overlap at the
|
|
|
2115 ;; same point, and it's quite possible for other applications to
|
|
|
2116 ;; embed extents in the current buffer without your knowledge).
|
|
|
2117 ;; Basically, if an extent, with the property stored in "prop",
|
|
|
2118 ;; exists at point, we assume that it is one of ours, and we re-use
|
|
|
2119 ;; it (this is why it is important for the property stored in "prop"
|
|
|
2120 ;; to be unique, and only used by us).
|
|
|
2121 (if (not (setq extent (extent-at (point) (current-buffer) prop)))
|
|
|
2122 (progn
|
|
|
2123 ;; If an extent does not already exist, create a zero-length
|
|
|
2124 ;; extent, and give it our special property.
|
|
|
2125 (setq extent (make-extent (point) (point) (current-buffer)))
|
|
|
2126 (set-extent-property extent prop t)
|
|
|
2127 ))
|
|
|
2128 ;; Display the glyph by storing it as the extent's "begin-glyph".
|
|
|
2129 (set-extent-property extent 'begin-glyph gl)
|
|
|
2130 ))
|
|
|
2131
|
|
|
2132 ;; You can then use this function like:
|
|
|
2133 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
|
|
|
2134 ;; This will insert the glyph at point.
|
|
|
2135
|
|
|
2136 ;; Here's an example of how to insert two glyphs side-by-side, at point
|
|
|
2137 ;; (using the above code):
|
|
|
2138 (progn
|
|
|
2139 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
|
|
|
2140 ;; Create a new extent at point. We can't simply call "insert-glyph",
|
|
|
2141 ;; as "insert-glyph" will simply replace the first glyph with the
|
|
|
2142 ;; second.
|
|
|
2143 (setq extent (make-extent (point) (point) (current-buffer)))
|
|
|
2144 ;; Here, we're only setting the 'myimage property in case we need
|
|
|
2145 ;; to later identify/locate/reuse this particular extent.
|
|
|
2146 (set-extent-property extent 'myimage t)
|
|
|
2147 (set-extent-property extent 'begin-glyph
|
|
|
2148 (make-glyph [jpeg :file "/tmp/file2.jpg"]))
|
|
|
2149 )
|
|
|
2150
|
|
|
2151 @end lisp
|
|
|
2152
|
|
|
2153 Here are the gory details:
|
|
|
2154
|
|
|
2155 @itemize @bullet
|
|
|
2156
|
|
|
2157 @item
|
|
|
2158 Glyphs are displayed by attaching them to extents (see @ref{Extents}),
|
|
|
2159 either to the beginning or the end of extents.
|
|
|
2160
|
|
|
2161 Note that extents can be used for many things, and not just for
|
|
|
2162 displaying images (although, in the above example, we are creating our
|
|
|
2163 own extent for the sole purpose of displaying an image). Also, note
|
|
|
2164 that multiple extents are allowed to exist at the same position, and
|
|
|
2165 they can overlap.
|
|
|
2166
|
|
|
2167 @item
|
|
|
2168 Glyphs are often displayed inside the text area (alongside text). This
|
|
|
2169 is the default.
|
|
|
2170
|
|
|
2171 Although glyphs can also be displayed in the margins, how to do this
|
|
|
2172 will not be described here. For more information on this, see
|
|
|
2173 @ref{Annotation Basics} (look for information on "layout types") and
|
|
|
2174 @ref{Extent Properties} (look for @code{begin-glyph-layout} and
|
|
|
2175 @code{end-glyph-layout}).
|
|
|
2176
|
|
|
2177 @item
|
|
|
2178 The easiest way to insert a glyph into text is to create a zero-length
|
|
|
2179 extent at the point where you want the glyph to appear.
|
|
|
2180
|
|
|
2181 Note that zero-length extents are attached to the character to the
|
|
|
2182 right of the extent; deleting this character will also delete the extent.
|
|
|
2183
|
|
|
2184 @item
|
|
|
2185 It's often a good idea to assign a unique property to the newly-created
|
|
|
2186 extent, in case you later want to locate it, and replace any existing
|
|
|
2187 glyph with a different one (or just delete the existing one). In the
|
|
|
2188 above example, we are using "myimage" as our (hopefully) unique property
|
|
|
2189 name.
|
|
|
2190
|
|
|
2191 If you need to locate all of the extents, you'll have to use functions
|
|
|
2192 like @code{extent-list} or @code{next-extent}, or provide additional
|
|
|
2193 parameters to the @code{extent-at} function. Assigning a unique
|
|
|
2194 property to the extent makes it easy to locate your extents; for
|
|
|
2195 example, @code{extent-list} can return only those extents with a
|
|
|
2196 particular property. @xref{Finding Extents}, and @ref{Mapping Over
|
|
|
2197 Extents}, for more information.
|
|
|
2198
|
|
|
2199 @item
|
|
|
2200 Glyphs are displayed by assigning then to the @code{begin-glyph} or
|
|
|
2201 @code{end-glyph} property of the extent. For zero-length extents, it
|
|
|
2202 doesn't really matter if you assign the glyph to the @code{begin-glyph}
|
|
|
2203 or @code{end-glyph} property, as they are both at the same location;
|
|
|
2204 however, for non-zero-length extents (extents that cover one or more
|
|
|
2205 characters of text), it does matter which one you use.
|
|
|
2206
|
|
|
2207 Assigning @code{nil} to the @code{begin-glyph} or @code{end-glyph}
|
|
|
2208 property will delete any existing glyph. In this case, you may also
|
|
|
2209 want to delete the extent, assuming that the extent is used for no other
|
|
|
2210 purpose.
|
|
|
2211
|
|
|
2212 @item
|
|
|
2213 If you happen to insert two glyphs, side-by-side, note that the example
|
|
|
2214 @code{insert-glyph} function will have trouble, if it's again used at
|
|
|
2215 the same point (it can only locate one of the two extents).
|
|
|
2216 @xref{Finding Extents}, and @ref{Mapping Over Extents}, for more
|
|
|
2217 information on locating extents in a buffer.
|
|
|
2218
|
|
|
2219 @item
|
|
|
2220 Among other things, glyphs provide a way of displaying graphics
|
|
|
2221 alongside text. Note, however, that glyphs only provide a way of
|
|
|
2222 displaying graphics; glyphs are not actually part of the text, and are
|
|
|
2223 only displayed alongside the text. If you save the text in the buffer,
|
|
|
2224 the graphics are not saved. The low-level glyph code does not provide a
|
|
|
2225 way of saving graphics with the text. If you need to save graphics and
|
|
|
2226 text, you have to write your own code to do this, and this topic is
|
|
|
2227 outside the scope of this discussion.
|
|
|
2228
|
|
|
2229 @end itemize
|
