|
0
|
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
|
|
|
10 A @dfn{glyph} is an object that is used for pixmaps and images of all
|
|
|
11 sorts, as well as for things that ``act'' like pixmaps, such as
|
|
|
12 non-textual strings (@dfn{annotations}) displayed in a buffer or in the
|
|
|
13 margins. It is used in begin-glyphs and end-glyphs attached to extents,
|
|
|
14 marginal and textual annotations, overlay arrows (@code{overlay-arrow-*}
|
|
|
15 variables), toolbar buttons, mouse pointers, frame icons, truncation and
|
|
|
16 continuation markers, and the like. (Basically, any place there is an
|
|
|
17 image or something that acts like an image, there will be a glyph object
|
|
|
18 representing it.)
|
|
|
19
|
|
|
20 The actual image that is displayed (as opposed to its position or
|
|
|
21 clipping) is defined by an @dfn{image specifier} object contained
|
|
|
22 within the glyph. The separation between an image specifier object
|
|
|
23 and a glyph object is made because the glyph includes other properties
|
|
|
24 than just the actual image: e.g. the face it is displayed in (for text
|
|
|
25 images), the alignment of the image (when it is in a buffer), etc.
|
|
|
26
|
|
|
27 @defun glyphp object
|
|
|
28 This function returns @code{t} if @var{object} is a glyph.
|
|
|
29 @end defun
|
|
|
30
|
|
|
31 @menu
|
|
|
32 * Glyph Functions:: Functions for working with glyphs.
|
|
|
33 * Images:: Graphical images displayed in a frame.
|
|
|
34 * Glyph Types:: Each glyph has a particular type.
|
|
|
35 * Mouse Pointer:: Controlling the mouse pointer.
|
|
|
36 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
|
|
|
37 * Subwindows:: Inserting an externally-controlled subwindow
|
|
|
38 into a buffer.
|
|
|
39 @end menu
|
|
|
40
|
|
|
41 @node Glyph Functions
|
|
|
42 @section Glyph Functions
|
|
|
43
|
|
|
44 @menu
|
|
|
45 * Creating Glyphs:: Creating new glyphs.
|
|
|
46 * Glyph Properties:: Accessing and modifying a glyph's properties.
|
|
|
47 * Glyph Convenience Functions::
|
|
|
48 Convenience functions for accessing particular
|
|
|
49 properties of a glyph.
|
|
|
50 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
|
|
|
51 @end menu
|
|
|
52
|
|
|
53 @node Creating Glyphs
|
|
|
54 @subsection Creating Glyphs
|
|
|
55
|
|
|
56 @defun make-glyph &optional spec-list type
|
|
|
57 This function creates a new glyph object of type @var{type}.
|
|
|
58
|
|
|
59 @var{spec-list} is used to initialize the glyph's image. It is
|
|
|
60 typically an image instantiator (a string or a vector; @ref{Image
|
|
|
61 Specifiers}), but can also be a list of such instantiators (each one in
|
|
|
62 turn is tried until an image is successfully produced), a cons of a
|
|
|
63 locale (frame, buffer, etc.) and an instantiator, a list of such conses,
|
|
|
64 or any other form accepted by @code{canonicalize-spec-list}.
|
|
394
|
65 @xref{Specifiers}, for more information about specifiers.
|
|
0
|
66
|
|
|
67 @var{type} specifies the type of the glyph, which specifies in which
|
|
|
68 contexts the glyph can be used, and controls the allowable image types
|
|
|
69 into which the glyph's image can be instantiated. @var{type} should be
|
|
|
70 one of @code{buffer} (used for glyphs in an extent, the modeline, the
|
|
|
71 toolbar, or elsewhere in a buffer), @code{pointer} (used for the
|
|
|
72 mouse-pointer), or @code{icon} (used for a frame's icon), and defaults
|
|
|
73 to @code{buffer}. @xref{Glyph Types}.
|
|
|
74 @end defun
|
|
|
75
|
|
|
76 @defun make-glyph-internal &optional type
|
|
2
|
77 This function creates a new, uninitialized glyph of type @var{type}.
|
|
0
|
78 @end defun
|
|
|
79
|
|
|
80 @defun make-pointer-glyph &optional spec-list
|
|
|
81 This function is equivalent to calling @code{make-glyph} with a
|
|
|
82 @var{type} of @code{pointer}.
|
|
|
83 @end defun
|
|
|
84
|
|
|
85 @defun make-icon-glyph &optional spec-list
|
|
|
86 This function is equivalent to calling @code{make-glyph} with a
|
|
|
87 @var{type} of @code{icon}.
|
|
|
88 @end defun
|
|
|
89
|
|
|
90 @node Glyph Properties
|
|
|
91 @subsection Glyph Properties
|
|
|
92
|
|
|
93 Each glyph has a list of properties, which control all of the aspects of
|
|
|
94 the glyph's appearance. The following symbols have predefined meanings:
|
|
|
95
|
|
|
96 @table @code
|
|
|
97 @item image
|
|
|
98 The image used to display the glyph.
|
|
|
99
|
|
|
100 @item baseline
|
|
|
101 Percent above baseline that glyph is to be displayed. Only for glyphs
|
|
|
102 displayed inside of a buffer.
|
|
|
103
|
|
|
104 @item contrib-p
|
|
|
105 Whether the glyph contributes to the height of the line it's on.
|
|
|
106 Only for glyphs displayed inside of a buffer.
|
|
|
107
|
|
|
108 @item face
|
|
|
109 Face of this glyph (@emph{not} a specifier).
|
|
|
110 @end table
|
|
|
111
|
|
|
112 @defun set-glyph-property glyph property value &optional locale tag-set how-to-add
|
|
|
113 This function changes a property of a @var{glyph}.
|
|
|
114
|
|
|
115 For built-in properties, the actual value of the property is a specifier
|
|
|
116 and you cannot change this; but you can change the specifications within
|
|
|
117 the specifier, and that is what this function will do. For user-defined
|
|
|
118 properties, you can use this function to either change the actual value
|
|
|
119 of the property or, if this value is a specifier, change the
|
|
|
120 specifications within it.
|
|
|
121
|
|
|
122 If @var{property} is a built-in property, the specifications to be added
|
|
|
123 to this property can be supplied in many different ways:
|
|
|
124
|
|
|
125 @itemize @bullet
|
|
|
126 @item
|
|
|
127 If @var{value} is a simple instantiator (e.g. a string naming a pixmap
|
|
|
128 filename) or a list of instantiators, then the instantiator(s) will be
|
|
|
129 added as a specification of the property for the given @var{locale}
|
|
|
130 (which defaults to @code{global} if omitted).
|
|
|
131
|
|
|
132 @item
|
|
|
133 If @var{value} is a list of specifications (each of which is a cons of a
|
|
|
134 locale and a list of instantiators), then @var{locale} must be
|
|
|
135 @code{nil} (it does not make sense to explicitly specify a locale in
|
|
|
136 this case), and specifications will be added as given.
|
|
|
137
|
|
|
138 @item
|
|
|
139 If @var{value} is a specifier (as would be returned by
|
|
|
140 @code{glyph-property} if no @var{locale} argument is given), then some
|
|
|
141 or all of the specifications in the specifier will be added to the
|
|
|
142 property. In this case, the function is really equivalent to
|
|
|
143 @code{copy-specifier} and @var{locale} has the same semantics (if it is
|
|
|
144 a particular locale, the specification for the locale will be copied; if
|
|
|
145 a locale type, specifications for all locales of that type will be
|
|
|
146 copied; if @code{nil} or @code{all}, then all specifications will be
|
|
|
147 copied).
|
|
|
148 @end itemize
|
|
|
149
|
|
|
150 @var{how-to-add} should be either @code{nil} or one of the symbols
|
|
|
151 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
|
|
|
152 @code{remove-tag-set-append}, @code{remove-locale},
|
|
|
153 @code{remove-locale-type}, or @code{remove-all}. See
|
|
|
154 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
|
|
|
155 of what each of these means. Most of the time, you do not need to worry
|
|
|
156 about this argument; the default behavior usually is fine.
|
|
|
157
|
|
|
158 In general, it is OK to pass an instance object (e.g. as returned by
|
|
|
159 @code{glyph-property-instance}) as an instantiator in place of an actual
|
|
|
160 instantiator. In such a case, the instantiator used to create that
|
|
|
161 instance object will be used (for example, if you set a font-instance
|
|
|
162 object as the value of the @code{font} property, then the font name used
|
|
|
163 to create that object will be used instead). If some cases, however,
|
|
|
164 doing this conversion does not make sense, and this will be noted in the
|
|
|
165 documentation for particular types of instance objects.
|
|
|
166
|
|
|
167 If @var{property} is not a built-in property, then this function will
|
|
|
168 simply set its value if @var{locale} is @code{nil}. However, if
|
|
|
169 @var{locale} is given, then this function will attempt to add
|
|
|
170 @var{value} as the instantiator for the given @var{locale}, using
|
|
|
171 @code{add-spec-to-specifier}. If the value of the property is not a
|
|
|
172 specifier, it will automatically be converted into a @code{generic}
|
|
|
173 specifier.
|
|
|
174 @end defun
|
|
|
175
|
|
|
176 @defun glyph-property glyph property &optional locale
|
|
|
177 This function returns @var{glyph}'s value of the given @var{property}.
|
|
|
178
|
|
|
179 If @var{locale} is omitted, the @var{glyph}'s actual value for
|
|
|
180 @var{property} will be returned. For built-in properties, this will be
|
|
|
181 a specifier object of a type appropriate to the property (e.g. a font or
|
|
|
182 color specifier). For other properties, this could be anything.
|
|
|
183
|
|
|
184 If @var{locale} is supplied, then instead of returning the actual value,
|
|
|
185 the specification(s) for the given locale or locale type will be
|
|
|
186 returned. This will only work if the actual value of @var{property} is
|
|
|
187 a specifier (this will always be the case for built-in properties, but
|
|
2
|
188 may or may not apply to user-defined properties). If the actual value
|
|
0
|
189 of @var{property} is not a specifier, this value will simply be returned
|
|
|
190 regardless of @var{locale}.
|
|
|
191
|
|
|
192 The return value will be a list of instantiators (e.g. vectors
|
|
|
193 specifying pixmap data), or a list of specifications, each of which is a
|
|
|
194 cons of a locale and a list of instantiators. Specifically, if
|
|
|
195 @var{locale} is a particular locale (a buffer, window, frame, device, or
|
|
|
196 @code{global}), a list of instantiators for that locale will be
|
|
|
197 returned. Otherwise, if @var{locale} is a locale type (one of the
|
|
|
198 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
|
|
|
199 the specifications for all locales of that type will be returned.
|
|
|
200 Finally, if @var{locale} is @code{all}, the specifications for all
|
|
|
201 locales of all types will be returned.
|
|
|
202
|
|
|
203 The specifications in a specifier determine what the value of
|
|
|
204 @var{property} will be in a particular @dfn{domain} or set of
|
|
|
205 circumstances, which is typically a particular Emacs window along with
|
|
|
206 the buffer it contains and the frame and device it lies within. The
|
|
|
207 value is derived from the instantiator associated with the most specific
|
|
|
208 locale (in the order buffer, window, frame, device, and @code{global})
|
|
|
209 that matches the domain in question. In other words, given a domain
|
|
|
210 (i.e. an Emacs window, usually), the specifier for @var{property} will
|
|
|
211 first be searched for a specification whose locale is the buffer
|
|
|
212 contained within that window; then for a specification whose locale is
|
|
|
213 the window itself; then for a specification whose locale is the frame
|
|
|
214 that the window is contained within; etc. The first instantiator that
|
|
|
215 is valid for the domain (usually this means that the instantiator is
|
|
|
216 recognized by the device [i.e. the X server or TTY device] that the
|
|
|
217 domain is on). The function @code{glyph-property-instance} actually does
|
|
|
218 all this, and is used to determine how to display the glyph.
|
|
|
219 @end defun
|
|
|
220
|
|
|
221 @defun glyph-property-instance glyph property &optional domain default no-fallback
|
|
|
222 This function returns the instance of @var{glyph}'s @var{property} in the
|
|
|
223 specified @var{domain}.
|
|
|
224
|
|
|
225 Under most circumstances, @var{domain} will be a particular window, and
|
|
|
226 the returned instance describes how the specified property actually is
|
|
|
227 displayed for that window and the particular buffer in it. Note that
|
|
|
228 this may not be the same as how the property appears when the buffer is
|
|
|
229 displayed in a different window or frame, or how the property appears in
|
|
|
230 the same window if you switch to another buffer in that window; and in
|
|
|
231 those cases, the returned instance would be different.
|
|
|
232
|
|
|
233 The returned instance is an image-instance object, and you can query it
|
|
|
234 using the appropriate image instance functions. For example, you could use
|
|
|
235 @code{image-instance-depth} to find out the depth (number of color
|
|
|
236 planes) of a pixmap displayed in a particular window. The results might
|
|
|
237 be different from the results you would get for another window (perhaps
|
|
|
238 the user specified a different image for the frame that window is on; or
|
|
|
239 perhaps the same image was specified but the window is on a different X
|
|
|
240 server, and that X server has different color capabilities from this
|
|
|
241 one).
|
|
|
242
|
|
|
243 @var{domain} defaults to the selected window if omitted.
|
|
|
244
|
|
|
245 @var{domain} can be a frame or device, instead of a window. The value
|
|
2
|
246 returned for such a domain is used in special circumstances when a
|
|
0
|
247 more specific domain does not apply; for example, a frame value might be
|
|
|
248 used for coloring a toolbar, which is conceptually attached to a frame
|
|
|
249 rather than a particular window. The value is also useful in
|
|
|
250 determining what the value would be for a particular window within the
|
|
|
251 frame or device, if it is not overridden by a more specific
|
|
|
252 specification.
|
|
|
253
|
|
|
254 If @var{property} does not name a built-in property, its value will
|
|
|
255 simply be returned unless it is a specifier object, in which case it
|
|
|
256 will be instanced using @code{specifier-instance}.
|
|
|
257
|
|
|
258 Optional arguments @var{default} and @var{no-fallback} are the same as
|
|
|
259 in @code{specifier-instance}. @xref{Specifiers}.
|
|
|
260 @end defun
|
|
|
261
|
|
|
262 @defun remove-glyph-property glyph property &optional locale tag-set exact-p
|
|
|
263 This function removes a property from a glyph. For built-in properties,
|
|
|
264 this is analogous to @code{remove-specifier}. @xref{Specifiers,
|
|
|
265 remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
|
|
|
266 and @var{exact-p} arguments.
|
|
|
267 @end defun
|
|
|
268
|
|
|
269 @node Glyph Convenience Functions
|
|
|
270 @subsection Glyph Convenience Functions
|
|
|
271
|
|
|
272 The following functions are provided for working with specific
|
|
|
273 properties of a glyph. Note that these are exactly like calling
|
|
|
274 the general functions described above and passing in the
|
|
|
275 appropriate value for @var{property}.
|
|
|
276
|
|
|
277 Remember that if you want to determine the ``value'' of a
|
|
|
278 specific glyph property, you probably want to use the @code{*-instance}
|
|
|
279 functions. For example, to determine whether a glyph contributes
|
|
|
280 to its line height, use @code{glyph-contrib-p-instance}, not
|
|
|
281 @code{glyph-contrib-p}. (The latter will return a boolean specifier
|
|
|
282 or a list of specifications, and you probably aren't concerned with
|
|
|
283 these.)
|
|
|
284
|
|
|
285 @defun glyph-image glyph &optional locale
|
|
|
286 This function is equivalent to calling @code{glyph-property} with
|
|
|
287 a property of @code{image}. The return value will be an image
|
|
|
288 specifier if @var{locale} is @code{nil} or omitted; otherwise,
|
|
|
289 it will be a specification or list of specifications.
|
|
|
290 @end defun
|
|
|
291
|
|
|
292 @defun set-glyph-image glyph spec &optional locale tag-set how-to-add
|
|
|
293 This function is equivalent to calling @code{set-glyph-property} with
|
|
|
294 a property of @code{image}.
|
|
|
295 @end defun
|
|
|
296
|
|
|
297 @defun glyph-image-instance glyph &optional domain default no-fallback
|
|
|
298 This function returns the instance of @var{glyph}'s image in the given
|
|
|
299 @var{domain}, and is equivalent to calling
|
|
|
300 @code{glyph-property-instance} with a property of @code{image}. The
|
|
|
301 return value will be an image instance.
|
|
|
302
|
|
|
303 Normally @var{domain} will be a window or @code{nil} (meaning the
|
|
|
304 selected window), and an instance object describing how the image
|
|
|
305 appears in that particular window and buffer will be returned.
|
|
|
306 @end defun
|
|
|
307
|
|
|
308 @defun glyph-contrib-p glyph &optional locale
|
|
|
309 This function is equivalent to calling @code{glyph-property} with
|
|
|
310 a property of @code{contrib-p}. The return value will be a boolean
|
|
|
311 specifier if @var{locale} is @code{nil} or omitted; otherwise,
|
|
|
312 it will be a specification or list of specifications.
|
|
|
313 @end defun
|
|
|
314
|
|
|
315 @defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
|
|
|
316 This function is equivalent to calling @code{set-glyph-property} with
|
|
|
317 a property of @code{contrib-p}.
|
|
|
318 @end defun
|
|
|
319
|
|
|
320 @defun glyph-contrib-p-instance glyph &optional domain default no-fallback
|
|
|
321 This function returns whether the glyph contributes to its line height
|
|
|
322 in the given @var{domain}, and is equivalent to calling
|
|
|
323 @code{glyph-property-instance} with a property of @code{contrib-p}. The
|
|
|
324 return value will be either @code{nil} or @code{t}. (Normally @var{domain}
|
|
|
325 will be a window or @code{nil}, meaning the selected window.)
|
|
|
326 @end defun
|
|
|
327
|
|
|
328 @defun glyph-baseline glyph &optional locale
|
|
|
329 This function is equivalent to calling @code{glyph-property} with a
|
|
|
330 property of @code{baseline}. The return value will be a specifier if
|
|
|
331 @var{locale} is @code{nil} or omitted; otherwise, it will be a
|
|
|
332 specification or list of specifications.
|
|
|
333 @end defun
|
|
|
334
|
|
|
335 @defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
|
|
|
336 This function is equivalent to calling @code{set-glyph-property} with
|
|
|
337 a property of @code{baseline}.
|
|
|
338 @end defun
|
|
|
339
|
|
|
340 @defun glyph-baseline-instance glyph &optional domain default no-fallback
|
|
|
341 This function returns the instance of @var{glyph}'s baseline value in
|
|
|
342 the given @var{domain}, and is equivalent to calling
|
|
|
343 @code{glyph-property-instance} with a property of @code{baseline}. The
|
|
|
344 return value will be an integer or @code{nil}.
|
|
|
345
|
|
|
346 Normally @var{domain} will be a window or @code{nil} (meaning the
|
|
|
347 selected window), and an instance object describing the baseline value
|
|
|
348 appears in that particular window and buffer will be returned.
|
|
|
349 @end defun
|
|
|
350
|
|
|
351 @defun glyph-face glyph
|
|
|
352 This function returns the face of @var{glyph}. (Remember, this is
|
|
|
353 not a specifier, but a simple property.)
|
|
|
354 @end defun
|
|
|
355
|
|
|
356 @defun set-glyph-face glyph face
|
|
|
357 This function changes the face of @var{glyph} to @var{face}.
|
|
|
358 @end defun
|
|
|
359
|
|
|
360 @node Glyph Dimensions
|
|
|
361 @subsection Glyph Dimensions
|
|
|
362
|
|
|
363 @defun glyph-width glyph &optional window
|
|
|
364 This function returns the width of @var{glyph} on @var{window}. This
|
|
|
365 may not be exact as it does not take into account all of the context
|
|
|
366 that redisplay will.
|
|
|
367 @end defun
|
|
|
368
|
|
|
369 @defun glyph-ascent glyph &optional window
|
|
|
370 This function returns the ascent value of @var{glyph} on @var{window}.
|
|
|
371 This may not be exact as it does not take into account all of the
|
|
|
372 context that redisplay will.
|
|
|
373 @end defun
|
|
|
374
|
|
|
375 @defun glyph-descent glyph &optional window
|
|
|
376 This function returns the descent value of @var{glyph} on @var{window}.
|
|
|
377 This may not be exact as it does not take into account all of the
|
|
|
378 context that redisplay will.
|
|
|
379 @end defun
|
|
|
380
|
|
|
381 @defun glyph-height glyph &optional window
|
|
|
382 This function returns the height of @var{glyph} on @var{window}. (This
|
|
|
383 is equivalent to the sum of the ascent and descent values.) This may
|
|
|
384 not be exact as it does not take into account all of the context that
|
|
|
385 redisplay will.
|
|
|
386 @end defun
|
|
|
387
|
|
|
388 @node Images
|
|
|
389 @section Images
|
|
|
390
|
|
|
391 @menu
|
|
|
392 * Image Specifiers:: Specifying how an image will appear.
|
|
|
393 * Image Instantiator Conversion::
|
|
|
394 Conversion is applied to image instantiators
|
|
|
395 at the time they are added to an
|
|
|
396 image specifier or at the time they
|
|
|
397 are passed to @code{make-image-instance}.
|
|
|
398 * Image Instances:: What an image specifier gets instanced as.
|
|
|
399 @end menu
|
|
|
400
|
|
|
401 @node Image Specifiers
|
|
|
402 @subsection Image Specifiers
|
|
|
403 @cindex image specifiers
|
|
|
404
|
|
|
405 An image specifier is used to describe the actual image of a glyph.
|
|
|
406 It works like other specifiers (@pxref{Specifiers}), in that it contains
|
|
|
407 a number of specifications describing how the image should appear in a
|
|
|
408 variety of circumstances. These specifications are called @dfn{image
|
|
|
409 instantiators}. When XEmacs wants to display the image, it instantiates
|
|
|
410 the image into an @dfn{image instance}. Image instances are their own
|
|
|
411 primitive object type (similar to font instances and color instances),
|
|
|
412 describing how the image appears in a particular domain. (On the other
|
|
|
413 hand, image instantiators, which are just descriptions of how the image
|
|
|
414 should appear, are represented using strings or vectors.)
|
|
|
415
|
|
|
416 @defun image-specifier-p object
|
|
|
417 This function returns non-@code{nil} if @var{object} is an image specifier.
|
|
|
418 Usually, an image specifier results from calling @code{glyph-image} on
|
|
|
419 a glyph.
|
|
|
420 @end defun
|
|
|
421
|
|
|
422 @defun make-image-specifier spec-list
|
|
|
423 This function creates a new image specifier object and initializes
|
|
|
424 it according to @var{spec-list}. It is unlikely that you will ever
|
|
|
425 want to do this, but this function is provided for completeness and
|
|
|
426 for experimentation purposes. @xref{Specifiers}.
|
|
|
427 @end defun
|
|
|
428
|
|
|
429 Image instantiators come in many formats: @code{xbm}, @code{xpm},
|
|
|
430 @code{gif}, @code{jpeg}, etc. This describes the format of the data
|
|
|
431 describing the image. The resulting image instances also come in many
|
|
398
|
432 types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
|
|
0
|
433 @code{pointer}, etc. This refers to the behavior of the image and the
|
|
|
434 sorts of places it can appear. (For example, a color-pixmap image has
|
|
|
435 fixed colors specified for it, while a mono-pixmap image comes in two
|
|
|
436 unspecified shades ``foreground'' and ``background'' that are determined
|
|
|
437 from the face of the glyph or surrounding text; a text image appears as
|
|
|
438 a string of text and has an unspecified foreground, background, and
|
|
|
439 font; a pointer image behaves like a mono-pixmap image but can only be
|
|
|
440 used as a mouse pointer [mono-pixmap images cannot be used as mouse
|
|
|
441 pointers]; etc.) It is important to keep the distinction between image
|
|
|
442 instantiator format and image instance type in mind. Typically, a given
|
|
|
443 image instantiator format can result in many different image instance
|
|
|
444 types (for example, @code{xpm} can be instanced as @code{color-pixmap},
|
|
|
445 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
|
|
|
446 instanced only as @code{pointer}), and a particular image instance type
|
|
|
447 can be generated by many different image instantiator formats (e.g.
|
|
|
448 @code{color-pixmap} can be generated by @code{xpm}, @code{gif},
|
|
|
449 @code{jpeg}, etc.).
|
|
|
450
|
|
394
|
451 @xref{Image Instances}, for a more detailed discussion of image
|
|
0
|
452 instance types.
|
|
|
453
|
|
|
454 An image instantiator should be a string or a vector of the form
|
|
|
455
|
|
|
456 @example
|
|
|
457 @code{[@var{format} @var{:keyword} @var{value} ...]}
|
|
|
458 @end example
|
|
|
459
|
|
|
460 i.e. a format symbol followed by zero or more alternating keyword-value
|
|
|
461 pairs. The @dfn{format} field should be a symbol, one of
|
|
|
462
|
|
|
463 @table @code
|
|
|
464 @item nothing
|
|
404
|
465 Don't display anything; no keywords are valid for this. Can only be
|
|
|
466 instanced as @code{nothing}.
|
|
0
|
467 @item string
|
|
404
|
468 Display this image as a text string. Can only be instanced
|
|
0
|
469 as @code{text}, although support for instancing as @code{mono-pixmap}
|
|
404
|
470 should be added.
|
|
0
|
471 @item formatted-string
|
|
404
|
472 Display this image as a text string with replaceable fields,
|
|
|
473 similar to a modeline format string; not currently implemented.
|
|
0
|
474 @item xbm
|
|
404
|
475 An X bitmap; only if X support was compiled into this XEmacs. Can be
|
|
0
|
476 instanced as @code{mono-pixmap}, @code{color-pixmap}, or
|
|
404
|
477 @code{pointer}.
|
|
0
|
478 @item xpm
|
|
404
|
479 An XPM pixmap; only if XPM support was compiled into this XEmacs. Can
|
|
0
|
480 be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
|
|
|
481 @code{pointer}. XPM is an add-on library for X that was designed to
|
|
|
482 rectify the shortcomings of the XBM format. Most implementations of X
|
|
|
483 include the XPM library as a standard part. If your vendor does not, it
|
|
|
484 is highly recommended that you download it and install it. You can get
|
|
404
|
485 it from the standard XEmacs FTP site, among other places.
|
|
0
|
486 @item xface
|
|
404
|
487 An X-Face bitmap, used to encode people's faces in e-mail messages;
|
|
0
|
488 only if X-Face support was compiled into this XEmacs. Can be instanced
|
|
404
|
489 as @code{mono-pixmap}, @code{color-pixmap}, or @code{pointer}.
|
|
0
|
490 @item gif
|
|
404
|
491 A GIF87 or GIF89 image; only if GIF support was compiled into this
|
|
0
|
492 XEmacs. Can be instanced as @code{color-pixmap}. Note that XEmacs
|
|
|
493 includes GIF decoding functions as a standard part of it, so if you have
|
|
|
494 X support, you will normally have GIF support, unless you explicitly
|
|
404
|
495 disable it at configure time.
|
|
0
|
496 @item jpeg
|
|
404
|
497 A JPEG-format image; only if JPEG support was compiled into this
|
|
0
|
498 XEmacs. Can be instanced as @code{color-pixmap}. If you have the JPEG
|
|
2
|
499 libraries present on your system when XEmacs is built, XEmacs will
|
|
|
500 automatically detect this and use them, unless you explicitly disable it
|
|
404
|
501 at configure time.
|
|
0
|
502 @item png
|
|
404
|
503 A PNG/GIF24 image; only if PNG support was compiled into this XEmacs.
|
|
|
504 Can be instanced as @code{color-pixmap}.
|
|
0
|
505 @item tiff
|
|
404
|
506 A TIFF-format image; only if TIFF support was compiled into this XEmacs.
|
|
0
|
507 @item cursor-font
|
|
404
|
508 One of the standard cursor-font names, such as @samp{watch} or
|
|
0
|
509 @samp{right_ptr} under X. Under X, this is, more specifically, any of
|
|
|
510 the standard cursor names from appendix B of the Xlib manual [also known
|
|
|
511 as the file @file{<X11/cursorfont.h>}] minus the @samp{XC_} prefix. On
|
|
|
512 other window systems, the valid names will be specific to the type of
|
|
404
|
513 window system. Can only be instanced as @code{pointer}.
|
|
0
|
514 @item font
|
|
404
|
515 A glyph from a font; i.e. the name of a font, and glyph index into it
|
|
0
|
516 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
|
|
|
517 Only if X support was compiled into this XEmacs. Currently can only be
|
|
404
|
518 instanced as @code{pointer}, although this should probably be fixed.
|
|
0
|
519 @item subwindow
|
|
404
|
520 An embedded X window; not currently implemented.
|
|
0
|
521 @item autodetect
|
|
404
|
522 XEmacs tries to guess what format the data is in. If X support exists,
|
|
0
|
523 the data string will be checked to see if it names a filename. If so,
|
|
|
524 and this filename contains XBM or XPM data, the appropriate sort of
|
|
|
525 pixmap or pointer will be created. [This includes picking up any
|
|
|
526 specified hotspot or associated mask file.] Otherwise, if @code{pointer}
|
|
|
527 is one of the allowable image-instance types and the string names a
|
|
|
528 valid cursor-font name, the image will be created as a pointer.
|
|
|
529 Otherwise, the image will be displayed as text. If no X support exists,
|
|
404
|
530 the image will always be displayed as text.
|
|
0
|
531 @end table
|
|
|
532
|
|
|
533 The valid keywords are:
|
|
|
534
|
|
|
535 @table @code
|
|
|
536 @item :data
|
|
404
|
537 Inline data. For most formats above, this should be a string. For
|
|
0
|
538 XBM images, this should be a list of three elements: width, height, and
|
|
|
539 a string of bit data. This keyword is not valid for instantiator
|
|
404
|
540 format @code{nothing}.
|
|
0
|
541
|
|
|
542 @item :file
|
|
404
|
543 Data is contained in a file. The value is the name of this file. If
|
|
0
|
544 both @code{:data} and @code{:file} are specified, the image is created
|
|
|
545 from what is specified in @code{:data} and the string in @code{:file}
|
|
|
546 becomes the value of the @code{image-instance-file-name} function when
|
|
|
547 applied to the resulting image-instance. This keyword is not valid for
|
|
|
548 instantiator formats @code{nothing}, @code{string},
|
|
|
549 @code{formatted-string}, @code{cursor-font}, @code{font}, and
|
|
404
|
550 @code{autodetect}.
|
|
0
|
551
|
|
|
552 @item :foreground
|
|
|
553 @itemx :background
|
|
404
|
554 For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
|
|
0
|
555 These keywords allow you to explicitly specify foreground and background
|
|
|
556 colors. The argument should be anything acceptable to
|
|
|
557 @code{make-color-instance}. This will cause what would be a
|
|
|
558 @code{mono-pixmap} to instead be colorized as a two-color color-pixmap,
|
|
|
559 and specifies the foreground and/or background colors for a pointer
|
|
404
|
560 instead of black and white.
|
|
0
|
561
|
|
|
562 @item :mask-data
|
|
404
|
563 For @code{xbm} and @code{xface}. This specifies a mask to be used with the
|
|
0
|
564 bitmap. The format is a list of width, height, and bits, like for
|
|
404
|
565 @code{:data}.
|
|
0
|
566
|
|
|
567 @item :mask-file
|
|
404
|
568 For @code{xbm} and @code{xface}. This specifies a file containing the
|
|
0
|
569 mask data. If neither a mask file nor inline mask data is given for an
|
|
|
570 XBM image, and the XBM image comes from a file, XEmacs will look for a
|
|
|
571 mask file with the same name as the image file but with @samp{Mask} or
|
|
|
572 @samp{msk} appended. For example, if you specify the XBM file
|
|
|
573 @file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
|
|
|
574 the associated mask file @file{left_ptrmsk} will automatically be picked
|
|
404
|
575 up.
|
|
0
|
576
|
|
|
577 @item :hotspot-x
|
|
|
578 @itemx :hotspot-y
|
|
404
|
579 For @code{xbm} and @code{xface}. These keywords specify a hotspot if
|
|
0
|
580 the image is instantiated as a @code{pointer}. Note that if the XBM
|
|
|
581 image file specifies a hotspot, it will automatically be picked up if no
|
|
404
|
582 explicit hotspot is given.
|
|
0
|
583
|
|
|
584 @item :color-symbols
|
|
404
|
585 Only for @code{xpm}. This specifies an alist that maps strings that
|
|
0
|
586 specify symbolic color names to the actual color to be used for that
|
|
|
587 symbolic color (in the form of a string or a color-specifier object).
|
|
|
588 If this is not specified, the contents of @code{xpm-color-symbols} are
|
|
404
|
589 used to generate the alist.
|
|
0
|
590 @end table
|
|
|
591
|
|
|
592 If instead of a vector, the instantiator is a string, it will be
|
|
|
593 converted into a vector by looking it up according to the specs in the
|
|
|
594 @code{console-type-image-conversion-list} for the console type of
|
|
|
595 the domain (usually a window; sometimes a frame or device) over which
|
|
|
596 the image is being instantiated.
|
|
|
597
|
|
|
598 If the instantiator specifies data from a file, the data will be read in
|
|
2
|
599 at the time that the instantiator is added to the image specifier (which
|
|
|
600 may be well before the image is actually displayed), and the
|
|
|
601 instantiator will be converted into one of the inline-data forms, with
|
|
|
602 the filename retained using a @code{:file} keyword. This implies that
|
|
|
603 the file must exist when the instantiator is added to the image, but
|
|
|
604 does not need to exist at any other time (e.g. it may safely be a
|
|
|
605 temporary file).
|
|
0
|
606
|
|
|
607 @defun valid-image-instantiator-format-p format
|
|
|
608 This function returns non-@code{nil} if @var{format} is a valid image
|
|
|
609 instantiator format. Note that the return value for many formats listed
|
|
|
610 above depends on whether XEmacs was compiled with support for that format.
|
|
|
611 @end defun
|
|
|
612
|
|
|
613 @defun image-instantiator-format-list
|
|
|
614 This function return a list of valid image-instantiator formats.
|
|
|
615 @end defun
|
|
|
616
|
|
|
617 @defvar xpm-color-symbols
|
|
|
618 This variable holds definitions of logical color-names used when reading
|
|
|
619 XPM files. Elements of this list should be of the form
|
|
|
620 @code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name}
|
|
|
621 should be a string, which is the name of the color to define; the
|
|
|
622 @var{form-to-evaluate} should evaluate to a color specifier object, or a
|
|
|
623 string to be passed to @code{make-color-instance} (@pxref{Colors}). If
|
|
|
624 a loaded XPM file references a symbolic color called @var{color-name},
|
|
|
625 it will display as the computed color instead.
|
|
|
626
|
|
|
627 The default value of this variable defines the logical color names
|
|
|
628 @samp{"foreground"} and @samp{"background"} to be the colors of the
|
|
|
629 @code{default} face.
|
|
|
630 @end defvar
|
|
|
631
|
|
|
632 @defvar x-bitmap-file-path
|
|
|
633 A list of the directories in which X bitmap files may be found. If nil,
|
|
|
634 this is initialized from the @samp{"*bitmapFilePath"} resource. This is
|
|
|
635 used by the @code{make-image-instance} function (however, note that if
|
|
|
636 the environment variable @samp{XBMLANGPATH} is set, it is consulted
|
|
|
637 first).
|
|
|
638 @end defvar
|
|
|
639
|
|
|
640 @node Image Instantiator Conversion
|
|
|
641 @subsection Image Instantiator Conversion
|
|
|
642 @cindex image instantiator conversion
|
|
|
643 @cindex conversion of image instantiators
|
|
|
644
|
|
|
645 @defun set-console-type-image-conversion-list console-type list
|
|
|
646 This function sets the image-conversion-list for consoles of the given
|
|
|
647 @var{console-type}. The image-conversion-list specifies how image
|
|
|
648 instantiators that are strings should be interpreted. Each element of
|
|
|
649 the list should be a list of two elements (a regular expression string
|
|
|
650 and a vector) or a list of three elements (the preceding two plus an
|
|
|
651 integer index into the vector). The string is converted to the vector
|
|
|
652 associated with the first matching regular expression. If a vector
|
|
|
653 index is specified, the string itself is substituted into that position
|
|
|
654 in the vector.
|
|
|
655
|
|
|
656 Note: The conversion above is applied when the image instantiator is
|
|
|
657 added to an image specifier, not when the specifier is actually
|
|
|
658 instantiated. Therefore, changing the image-conversion-list only affects
|
|
|
659 newly-added instantiators. Existing instantiators in glyphs and image
|
|
|
660 specifiers will not be affected.
|
|
|
661 @end defun
|
|
|
662
|
|
|
663 @defun console-type-image-conversion-list console-type
|
|
|
664 This function returns the image-conversion-list for consoles of the given
|
|
|
665 @var{console-type}.
|
|
|
666 @end defun
|
|
|
667
|
|
|
668 @node Image Instances
|
|
|
669 @subsection Image Instances
|
|
|
670 @cindex image instances
|
|
|
671
|
|
|
672 Image-instance objects encapsulate the way a particular image (pixmap,
|
|
|
673 etc.) is displayed on a particular device.
|
|
|
674
|
|
|
675 In most circumstances, you do not need to directly create image
|
|
|
676 instances; use a glyph instead. However, it may occasionally be useful
|
|
|
677 to explicitly create image instances, if you want more control over the
|
|
|
678 instantiation process.
|
|
|
679
|
|
|
680 @defun image-instance-p object
|
|
|
681 This function returns non-@code{nil} if @var{object} is an image instance.
|
|
|
682 @end defun
|
|
|
683
|
|
|
684 @menu
|
|
|
685 * Image Instance Types:: Each image instances has a particular type.
|
|
|
686 * Image Instance Functions:: Functions for working with image instances.
|
|
|
687 @end menu
|
|
|
688
|
|
|
689 @node Image Instance Types
|
|
|
690 @subsubsection Image Instance Types
|
|
|
691 @cindex image instance types
|
|
|
692
|
|
|
693 Image instances come in a number of different types. The type
|
|
|
694 of an image instance specifies the nature of the image: Whether
|
|
|
695 it is a text string, a mono pixmap, a color pixmap, etc.
|
|
|
696
|
|
|
697 The valid image instance types are
|
|
|
698
|
|
|
699 @table @code
|
|
|
700 @item nothing
|
|
|
701 Nothing is displayed.
|
|
|
702
|
|
|
703 @item text
|
|
|
704 Displayed as text. The foreground and background colors and the
|
|
|
705 font of the text are specified independent of the pixmap. Typically
|
|
|
706 these attributes will come from the face of the surrounding text,
|
|
|
707 unless a face is specified for the glyph in which the image appears.
|
|
|
708
|
|
|
709 @item mono-pixmap
|
|
|
710 Displayed as a mono pixmap (a pixmap with only two colors where the
|
|
|
711 foreground and background can be specified independent of the pixmap;
|
|
|
712 typically the pixmap assumes the foreground and background colors of
|
|
|
713 the text around it, unless a face is specified for the glyph in which
|
|
|
714 the image appears).
|
|
|
715 @item color-pixmap
|
|
|
716
|
|
|
717 Displayed as a color pixmap.
|
|
|
718
|
|
|
719 @item pointer
|
|
|
720 Used as the mouse pointer for a window.
|
|
|
721
|
|
|
722 @item subwindow
|
|
|
723 A child window that is treated as an image. This allows (e.g.)
|
|
|
724 another program to be responsible for drawing into the window.
|
|
|
725 Not currently implemented.
|
|
|
726 @end table
|
|
|
727
|
|
|
728 @defun valid-image-instance-type-p type
|
|
|
729 This function returns non-@code{nil} if @var{type} is a valid image
|
|
|
730 instance type.
|
|
|
731 @end defun
|
|
|
732
|
|
|
733 @defun image-instance-type-list
|
|
|
734 This function returns a list of the valid image instance types.
|
|
|
735 @end defun
|
|
|
736
|
|
|
737 @defun image-instance-type image-instance
|
|
|
738 This function returns the type of the given image instance. The return
|
|
|
739 value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
|
|
|
740 @code{color-pixmap}, @code{pointer}, or @code{subwindow}.
|
|
|
741 @end defun
|
|
|
742
|
|
|
743 @defun text-image-instance-p object
|
|
|
744 This function returns non-@code{nil} if @var{object} is an image
|
|
|
745 instance of type @code{text}.
|
|
|
746 @end defun
|
|
|
747
|
|
|
748 @defun mono-pixmap-image-instance-p object
|
|
|
749 This function returns non-@code{nil} if @var{object} is an image
|
|
|
750 instance of type @code{mono-pixmap}.
|
|
|
751 @end defun
|
|
|
752
|
|
|
753 @defun color-pixmap-image-instance-p object
|
|
|
754 This function returns non-@code{nil} if @var{object} is an image
|
|
|
755 instance of type @code{color-pixmap}.
|
|
|
756 @end defun
|
|
|
757
|
|
|
758 @defun pointer-image-instance-p object
|
|
|
759 This function returns non-@code{nil} if @var{object} is an image
|
|
|
760 instance of type @code{pointer}.
|
|
|
761 @end defun
|
|
|
762
|
|
|
763 @defun subwindow-image-instance-p object
|
|
|
764 This function returns non-@code{nil} if @var{object} is an image
|
|
|
765 instance of type @code{subwindow}.
|
|
|
766 @end defun
|
|
|
767
|
|
|
768 @defun nothing-image-instance-p object
|
|
|
769 This function returns non-@code{nil} if @var{object} is an image
|
|
|
770 instance of type @code{nothing}.
|
|
|
771 @end defun
|
|
|
772
|
|
|
773 @node Image Instance Functions
|
|
|
774 @subsubsection Image Instance Functions
|
|
|
775
|
|
|
776 @defun make-image-instance data &optional device dest-types no-error
|
|
|
777 This function creates a new image-instance object.
|
|
|
778
|
|
|
779 @var{data} is an image instantiator, which describes the image
|
|
|
780 (@pxref{Image Specifiers}).
|
|
|
781
|
|
|
782 @var{dest-types} should be a list of allowed image instance types that
|
|
|
783 can be generated. The @var{dest-types} list is unordered. If multiple
|
|
|
784 destination types are possible for a given instantiator, the ``most
|
|
|
785 natural'' type for the instantiator's format is chosen. (For XBM, the
|
|
|
786 most natural types are @code{mono-pixmap}, followed by
|
|
|
787 @code{color-pixmap}, followed by @code{pointer}. For the other normal
|
|
|
788 image formats, the most natural types are @code{color-pixmap}, followed
|
|
|
789 by @code{mono-pixmap}, followed by @code{pointer}. For the string and
|
|
|
790 formatted-string formats, the most natural types are @code{text},
|
|
|
791 followed by @code{mono-pixmap} (not currently implemented), followed by
|
|
|
792 @code{color-pixmap} (not currently implemented). The other formats can
|
|
|
793 only be instantiated as one type. (If you want to control more
|
|
|
794 specifically the order of the types into which an image is instantiated,
|
|
|
795 just call @code{make-image-instance} repeatedly until it succeeds,
|
|
|
796 passing less and less preferred destination types each time.
|
|
|
797
|
|
|
798 If @var{dest-types} is omitted, all possible types are allowed.
|
|
|
799
|
|
|
800 @var{no-error} controls what happens when the image cannot be generated.
|
|
|
801 If @var{nil}, an error message is generated. If @var{t}, no messages
|
|
|
802 are generated and this function returns @var{nil}. If anything else, a
|
|
|
803 warning message is generated and this function returns @var{nil}.
|
|
|
804 @end defun
|
|
|
805
|
|
|
806 @defun colorize-image-instance image-instance foreground background
|
|
|
807 This function makes the image instance be displayed in the given
|
|
|
808 colors. Image instances come in two varieties: bitmaps, which are 1
|
|
|
809 bit deep which are rendered in the prevailing foreground and background
|
|
|
810 colors; and pixmaps, which are of arbitrary depth (including 1) and
|
|
|
811 which have the colors explicitly specified. This function converts a
|
|
|
812 bitmap to a pixmap. If the image instance was a pixmap already,
|
|
|
813 nothing is done (and @code{nil} is returned). Otherwise @code{t} is
|
|
|
814 returned.
|
|
|
815 @end defun
|
|
|
816
|
|
|
817 @defun image-instance-name image-instance
|
|
|
818 This function returns the name of the given image instance.
|
|
|
819 @end defun
|
|
|
820
|
|
|
821 @defun image-instance-string image-instance
|
|
|
822 This function returns the string of the given image instance. This will
|
|
|
823 only be non-@code{nil} for text image instances.
|
|
|
824 @end defun
|
|
|
825
|
|
|
826 @defun image-instance-file-name image-instance
|
|
|
827 This function returns the file name from which @var{image-instance} was
|
|
|
828 read, if known.
|
|
|
829 @end defun
|
|
|
830
|
|
|
831 @defun image-instance-mask-file-name image-instance
|
|
|
832 This function returns the file name from which @var{image-instance}'s
|
|
|
833 mask was read, if known.
|
|
|
834 @end defun
|
|
|
835
|
|
|
836 @defun image-instance-depth image-instance
|
|
|
837 This function returns the depth of the image instance. This is 0 for a
|
|
|
838 mono pixmap, or a positive integer for a color pixmap.
|
|
|
839 @end defun
|
|
|
840
|
|
|
841 @defun image-instance-height image-instance
|
|
|
842 This function returns the height of the image instance, in pixels.
|
|
|
843 @end defun
|
|
|
844
|
|
|
845 @defun image-instance-width image-instance
|
|
|
846 This function returns the width of the image instance, in pixels.
|
|
|
847 @end defun
|
|
|
848
|
|
|
849 @defun image-instance-hotspot-x image-instance
|
|
|
850 This function returns the X coordinate of the image instance's hotspot,
|
|
|
851 if known. This is a point relative to the origin of the pixmap. When
|
|
|
852 an image is used as a mouse pointer, the hotspot is the point on the
|
|
|
853 image that sits over the location that the pointer points to. This is,
|
|
|
854 for example, the tip of the arrow or the center of the crosshairs.
|
|
|
855
|
|
|
856 This will always be @code{nil} for a non-pointer image instance.
|
|
|
857 @end defun
|
|
|
858
|
|
|
859 @defun image-instance-hotspot-y image-instance
|
|
|
860 This function returns the Y coordinate of the image instance's hotspot,
|
|
|
861 if known.
|
|
|
862 @end defun
|
|
|
863
|
|
|
864 @defun image-instance-foreground image-instance
|
|
|
865 This function returns the foreground color of @var{image-instance}, if
|
|
|
866 applicable. This will be a color instance or @code{nil}. (It will only
|
|
|
867 be non-@code{nil} for colorized mono pixmaps and for pointers.)
|
|
|
868 @end defun
|
|
|
869
|
|
|
870 @defun image-instance-background image-instance
|
|
|
871 This function returns the background color of @var{image-instance}, if
|
|
|
872 applicable. This will be a color instance or @code{nil}. (It will only
|
|
|
873 be non-@code{nil} for colorized mono pixmaps and for pointers.)
|
|
|
874 @end defun
|
|
|
875
|
|
|
876
|
|
|
877 @node Glyph Types
|
|
|
878 @section Glyph Types
|
|
|
879
|
|
|
880 Each glyph has a particular type, which controls how the glyph's image
|
|
|
881 is generated. Each glyph type has a corresponding list of allowable
|
|
|
882 image instance types that can be generated. When you call
|
|
|
883 @code{glyph-image-instance} to retrieve the image instance of a glyph,
|
|
|
884 XEmacs does the equivalent of calling @code{make-image-instance} and
|
|
|
885 passing in @var{dest-types} the list of allowable image instance types
|
|
|
886 for the glyph's type.
|
|
|
887
|
|
|
888 @itemize @bullet
|
|
|
889 @item
|
|
|
890 @code{buffer} glyphs can be used as the begin-glyph or end-glyph of an
|
|
|
891 extent, in the modeline, and in the toolbar. Their image can be
|
|
|
892 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
|
|
|
893 @code{text}, and @code{subwindow}.
|
|
|
894
|
|
|
895 @item
|
|
|
896 @code{pointer} glyphs can be used to specify the mouse pointer. Their
|
|
|
897 image can be instantiated as @code{pointer}.
|
|
|
898
|
|
|
899 @item
|
|
|
900 @code{icon} glyphs can be used to specify the icon used when a frame is
|
|
|
901 iconified. Their image can be instantiated as @code{mono-pixmap} and
|
|
|
902 @code{color-pixmap}.
|
|
|
903 @end itemize
|
|
|
904
|
|
|
905 @defun glyph-type glyph
|
|
|
906 This function returns the type of the given glyph. The return value
|
|
|
907 will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}.
|
|
|
908 @end defun
|
|
|
909
|
|
|
910 @defun valid-glyph-type-p glyph-type
|
|
|
911 Given a @var{glyph-type}, this function returns non-@code{nil} if it is
|
|
|
912 valid.
|
|
|
913 @end defun
|
|
|
914
|
|
|
915 @defun glyph-type-list
|
|
|
916 This function returns a list of valid glyph types.
|
|
|
917 @end defun
|
|
|
918
|
|
|
919 @defun buffer-glyph-p object
|
|
|
920 This function returns non-@code{nil} if @var{object} is a glyph of type
|
|
|
921 @code{buffer}.
|
|
|
922 @end defun
|
|
|
923
|
|
|
924 @defun icon-glyph-p object
|
|
|
925 This function returns non-@code{nil} if @var{object} is a glyph of type
|
|
|
926 @code{icon}.
|
|
|
927 @end defun
|
|
|
928
|
|
|
929 @defun pointer-glyph-p object
|
|
|
930 This function returns non-@code{nil} if @var{object} is a glyph of type
|
|
|
931 @code{pointer}.
|
|
|
932 @end defun
|
|
|
933
|
|
|
934 @node Mouse Pointer
|
|
|
935 @section Mouse Pointer
|
|
|
936 @cindex mouse cursor
|
|
|
937 @cindex cursor (mouse)
|
|
|
938 @cindex pointer (mouse)
|
|
|
939 @cindex mouse pointer
|
|
|
940
|
|
|
941 The shape of the mouse pointer when over a particular section of a frame
|
|
|
942 is controlled using various glyph variables. Since the image of a glyph
|
|
|
943 is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
|
|
|
944 or per-device basis.
|
|
|
945
|
|
|
946 You should use @code{set-glyph-image} to set the following variables,
|
|
|
947 @emph{not} @code{setq}.
|
|
|
948
|
|
|
949 @defvr Glyph text-pointer-glyph
|
|
|
950 This variable specifies the shape of the mouse pointer when over text.
|
|
|
951 @end defvr
|
|
|
952
|
|
|
953 @defvr Glyph nontext-pointer-glyph
|
|
|
954 This variable specifies the shape of the mouse pointer when over a
|
|
|
955 buffer, but not over text. If unspecified in a particular domain,
|
|
|
956 @code{text-pointer-glyph} is used.
|
|
|
957 @end defvr
|
|
|
958
|
|
|
959 @defvr Glyph modeline-pointer-glyph
|
|
|
960 This variable specifies the shape of the mouse pointer when over the modeline.
|
|
|
961 If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
|
|
|
962 @end defvr
|
|
|
963
|
|
|
964 @defvr Glyph selection-pointer-glyph
|
|
|
965 This variable specifies the shape of the mouse pointer when over a
|
|
|
966 selectable text region. If unspecified in a particular domain,
|
|
|
967 @code{text-pointer-glyph} is used.
|
|
|
968 @end defvr
|
|
|
969
|
|
|
970 @defvr Glyph gc-pointer-glyph
|
|
|
971 This variable specifies the shape of the mouse pointer when a garbage
|
|
|
972 collection is in progress. If the selected window is on a window system
|
|
|
973 and this glyph specifies a value (i.e. a pointer image instance) in the
|
|
|
974 domain of the selected window, the pointer will be changed as specified
|
|
|
975 during garbage collection. Otherwise, a message will be printed in the
|
|
|
976 echo area, as controlled by @code{gc-message}.
|
|
|
977 @end defvr
|
|
|
978
|
|
|
979 @defvr Glyph busy-pointer-glyph
|
|
|
980 This variable specifies the shape of the mouse pointer when XEmacs is busy.
|
|
|
981 If unspecified in a particular domain, the pointer is not changed
|
|
|
982 when XEmacs is busy.
|
|
|
983 @end defvr
|
|
|
984
|
|
|
985 @defvr Glyph menubar-pointer-glyph
|
|
|
986 This variable specifies the shape of the mouse pointer when over the
|
|
|
987 menubar. If unspecified in a particular domain, the
|
|
|
988 window-system-provided default pointer is used.
|
|
|
989 @end defvr
|
|
|
990
|
|
|
991 @defvr Glyph scrollbar-pointer-glyph
|
|
|
992 This variable specifies the shape of the mouse pointer when over a
|
|
|
993 scrollbar. If unspecified in a particular domain, the
|
|
|
994 window-system-provided default pointer is used.
|
|
|
995 @end defvr
|
|
|
996
|
|
|
997 @defvr Glyph toolbar-pointer-glyph
|
|
|
998 This variable specifies the shape of the mouse pointer when over a
|
|
|
999 toolbar. If unspecified in a particular domain,
|
|
|
1000 @code{nontext-pointer-glyph} is used.
|
|
|
1001 @end defvr
|
|
|
1002
|
|
|
1003 Internally, these variables are implemented in
|
|
|
1004 @code{default-mouse-motion-handler}, and thus only take effect when the
|
|
|
1005 mouse moves. That function calls @code{set-frame-pointer}, which sets
|
|
|
1006 the current mouse pointer for a frame.
|
|
|
1007
|
|
|
1008 @defun set-frame-pointer frame image-instance
|
|
|
1009 This function sets the mouse pointer of @var{frame} to the given pointer
|
|
|
1010 image instance. You should not call this function directly.
|
|
2
|
1011 (If you do, the pointer will change again the next time the mouse moves.)
|
|
0
|
1012 @end defun
|
|
|
1013
|
|
|
1014 @node Redisplay Glyphs
|
|
|
1015 @section Redisplay Glyphs
|
|
|
1016
|
|
|
1017 @defvr Glyph truncation-glyph
|
|
|
1018 This variable specifies what is displayed at the end of truncated lines.
|
|
|
1019 @end defvr
|
|
|
1020
|
|
|
1021 @defvr Glyph continuation-glyph
|
|
|
1022 This variable specifies what is displayed at the end of wrapped lines.
|
|
|
1023 @end defvr
|
|
|
1024
|
|
|
1025 @defvr Glyph octal-escape-glyph
|
|
|
1026 This variable specifies what to prefix character codes displayed in octal
|
|
|
1027 with.
|
|
|
1028 @end defvr
|
|
|
1029
|
|
|
1030 @defvr Glyph hscroll-glyph
|
|
|
1031 This variable specifies what to display at the beginning of horizontally
|
|
|
1032 scrolled lines.
|
|
|
1033 @end defvr
|
|
|
1034
|
|
|
1035 @defvr Glyph invisible-text-glyph
|
|
|
1036 This variable specifies what to use to indicate the presence of
|
|
|
1037 invisible text. This is the glyph that is displayed when an ellipsis is
|
|
|
1038 called for, according to @code{selective-display-ellipses} or
|
|
|
1039 @code{buffer-invisibility-spec}). Normally this is three dots (``...'').
|
|
|
1040 @end defvr
|
|
|
1041
|
|
|
1042 @defvr Glyph control-arrow-glyph
|
|
|
1043 This variable specifies what to use as an arrow for control characters.
|
|
|
1044 @end defvr
|
|
|
1045
|
|
|
1046 @node Subwindows
|
|
|
1047 @section Subwindows
|
|
|
1048
|
|
|
1049 Subwindows are not currently implemented.
|
|
|
1050
|
|
|
1051 @defun subwindowp object
|
|
|
1052 This function returns non-@code{nil} if @var{object} is a subwindow.
|
|
|
1053 @end defun
|
