|
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
|
|
442
|
10 A @dfn{glyph} is an object that is used for pixmaps, widgets and
|
|
|
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
|
|
|
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 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.
|
|
707
|
39 * Glyph Examples:: Examples of how to work with glyphs.
|
|
428
|
40 @end menu
|
|
|
41
|
|
|
42 @node Glyph Functions
|
|
|
43 @section Glyph Functions
|
|
|
44
|
|
|
45 @menu
|
|
|
46 * Creating Glyphs:: Creating new glyphs.
|
|
|
47 * Glyph Properties:: Accessing and modifying a glyph's properties.
|
|
|
48 * Glyph Convenience Functions::
|
|
|
49 Convenience functions for accessing particular
|
|
|
50 properties of a glyph.
|
|
|
51 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
|
|
|
52 @end menu
|
|
|
53
|
|
|
54 @node Creating Glyphs
|
|
|
55 @subsection Creating Glyphs
|
|
|
56
|
|
|
57 @defun make-glyph &optional spec-list type
|
|
|
58 This function creates a new glyph object of type @var{type}.
|
|
|
59
|
|
|
60 @var{spec-list} is used to initialize the glyph's image. It is
|
|
|
61 typically an image instantiator (a string or a vector; @ref{Image
|
|
|
62 Specifiers}), but can also be a list of such instantiators (each one in
|
|
|
63 turn is tried until an image is successfully produced), a cons of a
|
|
|
64 locale (frame, buffer, etc.) and an instantiator, a list of such conses,
|
|
|
65 or any other form accepted by @code{canonicalize-spec-list}.
|
|
|
66 @xref{Specifiers}, for more information about specifiers.
|
|
|
67
|
|
|
68 @var{type} specifies the type of the glyph, which specifies in which
|
|
|
69 contexts the glyph can be used, and controls the allowable image types
|
|
|
70 into which the glyph's image can be instantiated. @var{type} should be
|
|
|
71 one of @code{buffer} (used for glyphs in an extent, the modeline, the
|
|
|
72 toolbar, or elsewhere in a buffer), @code{pointer} (used for the
|
|
|
73 mouse-pointer), or @code{icon} (used for a frame's icon), and defaults
|
|
|
74 to @code{buffer}. @xref{Glyph Types}.
|
|
442
|
75
|
|
|
76 A glyph in XEmacs does @strong{NOT} refer to a single unit of textual
|
|
|
77 display (the XEmacs term for this is @dfn{rune}), but rather is an
|
|
|
78 object encapsulating a graphical element, such as an image or widget (an
|
|
|
79 element such as a button or text field; @dfn{widget} is the term for
|
|
|
80 this under X Windows, and it's called a @dfn{control} under MS Windows).
|
|
|
81 This graphical element could appear in a buffer, a margin, a gutter, or
|
|
|
82 a toolbar, or as a mouse pointer or an icon, for example.
|
|
|
83
|
|
|
84 Creating a glyph using @code{make-glyph} does not specify @emph{where}
|
|
|
85 the glyph will be used, but it does specify @emph{what} the glyph will
|
|
444
|
86 look like. In particular, @var{spec-list} is used to specify this, and it's
|
|
442
|
87 used to initialize the glyph's @code{image} property, which is an image
|
|
|
88 specifier. (Note that @dfn{image} as used in the context of a glyph's
|
|
|
89 @code{image} property or in the terms @dfn{image specifier}, @dfn{image
|
|
|
90 instantiator}, or @dfn{image instance} does not refer to what people
|
|
|
91 normally think of as an image (which in XEmacs is called a
|
|
|
92 @dfn{pixmap}), but to any graphical element---a pixmap, a widget, or
|
|
|
93 even a block of text, when used in the places that call for a glyph.)
|
|
444
|
94 The format of the @var{spec-list} is typically an image instantiator (a string
|
|
442
|
95 or a vector; @ref{Image Specifiers}), but can also be a list of such
|
|
|
96 instantiators (each one in turn is tried until an image is successfully
|
|
|
97 produced), a cons of a locale (frame, buffer, etc.) and an
|
|
|
98 instantiator, a list of such conses, or any other form accepted by
|
|
|
99 @code{canonicalize-spec-list}. @xref{Specifiers}, for more information
|
|
|
100 about specifiers.
|
|
|
101
|
|
|
102 If you're not familiar with specifiers, you should be in order to
|
|
|
103 understand how glyphs work. The clearest introduction to specifiers
|
|
|
104 is in the Lispref manual, available under Info. (Choose
|
|
|
105 Help->Info->Info Contents on the menubar or type C-h i.) You can
|
|
|
106 also see @code{make-specifier} for a capsule summary. What's important to
|
|
|
107 keep in mind is that a specifier lets you set a different value for
|
|
|
108 any particular buffer, window, frame, device, or console. This allows
|
|
|
109 for a great deal of flexibility; in particular, only one global glyph
|
|
|
110 needs to exist for a particular purpose (e.g. the icon used to represent
|
|
|
111 an iconified frame, the mouse pointer used over particular areas of a
|
|
|
112 frame, etc.), and in these cases you do not create your own glyph, but
|
|
|
113 rather modify the existing one.
|
|
|
114
|
|
|
115 As well as using @var{spec-list} to initialize the glyph, you can set
|
|
|
116 specifications using @code{set-glyph-image}. Note that, due to a
|
|
|
117 possibly questionable historical design decision, a glyph itself is not
|
|
|
118 actually a specifier, but rather is an object containing an image
|
|
|
119 specifier (as well as other, seldom-used properties). Therefore, you
|
|
|
120 cannot set or access specifications for the glyph's image by directly
|
|
|
121 using @code{set-specifier}, @code{specifier-instance} or the like on the
|
|
|
122 glyph; instead use them on @code{(glyph-image @var{glyph})} or use the
|
|
|
123 convenience functions @code{set-glyph-image},
|
|
|
124 @code{glyph-image-instance}, and @code{glyph-image}.
|
|
|
125
|
|
|
126 Once you have created a glyph, you specify where it will be used as
|
|
|
127 follows:
|
|
|
128
|
|
|
129 @itemize @bullet
|
|
|
130 @item
|
|
|
131 To insert a glyph into a buffer, create an extent in the buffer and then
|
|
|
132 use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
|
|
|
133 a glyph to be displayed at the corresponding edge of the extent. (It is
|
|
|
134 common to create zero-width extents for this purpose.)
|
|
|
135
|
|
|
136 @item
|
|
|
137 To insert a glyph into the left or right margin of a buffer, first
|
|
|
138 make sure the margin is visible by setting a value for the specifiers
|
|
|
139 @code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
|
|
|
140 when using margin glyphs with layout policy @code{whitespace}.) Then follow
|
|
|
141 the same procedure above for inserting a glyph in a buffer, and then
|
|
|
142 set a non-default layout policy for the glyph using
|
|
|
143 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
|
|
|
144 Alternatively, use the high-level annotations API (see
|
|
|
145 @code{make-annotation}). (In point of fact, you can also use the annotations
|
|
|
146 API for glyphs in a buffer, by setting a layout policy of @code{text}.)
|
|
|
147
|
|
|
148 @item
|
|
|
149 To insert a glyph into the modeline, just put the glyph directly as one
|
|
|
150 of the modeline elements. (Unfortunately you can't currently put a begin
|
|
|
151 glyph or end glyph on one of the modeline extents---they're ignored.)
|
|
|
152
|
|
|
153 @item
|
|
|
154 To insert a glyph into a toolbar, specify it as part of a toolbar
|
|
|
155 instantiator (typically set on the specifier @code{default-toolbar}).
|
|
|
156 See @code{default-toolbar} for more information. (Note that it is
|
|
|
157 standard practice to use a symbol in place of the glyph list in the
|
|
|
158 toolbar instantiator; the symbol is evalled to get the glyph list. This
|
|
|
159 facilitates both creating the toolbar instantiator and modifying
|
|
|
160 individual glyphs in a toolbar later on. For example, you can change
|
|
|
161 the way that the Mail toolbar button looks by modifying the value of the
|
|
|
162 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
|
|
|
163 and then calling @code{(set-specifier-dirty-flag default-toolbar)}.
|
|
|
164 (#### Unfortunately this doesn't quite work the way it should; the
|
|
|
165 change will appear in new frames, but not existing ones.
|
|
|
166
|
|
|
167 @item
|
|
|
168 To insert a glyph into a gutter, create or modify a gutter instantiator
|
|
|
169 (typically set on the specifier @code{default-gutter}). Gutter
|
|
|
170 instantiators consist of strings or lists of strings, so to insert a
|
|
|
171 glyph, create an extent over the string, and use
|
|
|
172 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
|
|
|
173 glyph to be displayed at the corresponding edge of the extent, just like
|
|
|
174 for glyphs in a buffer.
|
|
|
175
|
|
|
176 @item
|
|
|
177 To use a glyph as the icon for a frame, you do not actually create a new
|
|
|
178 glyph; rather, you change the specifications for the existing glyph
|
|
|
179 @code{frame-icon-glyph}. (Remember that, because of the specifier nature
|
|
|
180 of glyphs, you can set different values for any particular buffer or
|
|
|
181 frame.)
|
|
|
182
|
|
|
183 @item
|
|
|
184 To use a glyph as the mouse pointer, in general you do not create a new
|
|
|
185 glyph, but rather you change the specifications of various existing
|
|
|
186 glyphs, such as @code{text-pointer-glyph} for the pointer used over
|
|
|
187 text, @code{modeline-pointer-glyph} for the pointer used over the
|
|
|
188 modeline, etc. Do an apropos over @code{*-pointer-glyph} to find all of
|
|
|
189 them. (Note also that you can temporarily set the mouse pointer to some
|
|
|
190 specific shape by using @code{set-frame-pointer}, which takes an image
|
|
|
191 instance, as obtained from calling @code{glyph-image-instance} on a glyph
|
|
|
192 of type @code{pointer} -- either one of the above-mentioned variables or
|
|
|
193 one you created yourself. (See below for what it means to create a
|
|
|
194 glyph of type @code{pointer}.) This pointer will last only until the
|
|
|
195 next mouse motion event is processed or certain other things happen,
|
|
|
196 such as creating or deleting a window. (In fact, the above-mentioned
|
|
|
197 pointer glyph variables are implemented as part of the default handler
|
|
|
198 for mouse motion events. If you want to customize this behavior, take a
|
|
|
199 look at @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
|
|
|
200 really want to get low-level.)
|
|
|
201
|
|
|
202 @item
|
|
|
203 To use a glyph to control the shape of miscellaneous redisplay effects
|
|
|
204 such as the truncation and continuation markers, set the appropriate
|
|
|
205 existing glyph variables, as for icons and pointers above. See
|
|
|
206 @code{continuation-glyph}, @code{control-arrow-glyph},
|
|
|
207 @code{hscroll-glyph}, @code{invisible-text-glyph},
|
|
|
208 @code{octal-escape-glyph}, and @code{truncation-glyph}. See also
|
|
|
209 @code{overlay-arrow-string}, an odd redisplay leftover which can be set
|
|
|
210 to a glyph you created, and will cause the glyph to be displayed on top
|
|
|
211 of the text position specified in the marker stored in
|
|
|
212 @code{overlay-arrow-position}.
|
|
|
213
|
|
|
214 @item
|
|
|
215 To use a glyph in a display table (i.e. to control the appearance of any
|
|
|
216 individual character), create the appropriate character glyphs and then
|
|
|
217 set a specification for the specifier @code{current-display-table},
|
|
|
218 which controls the appearance of characters. You can also set an
|
|
|
219 overriding display table for use with text displayed in a particular
|
|
|
220 face; see @code{set-face-display-table} and @code{make-display-table}.
|
|
|
221 #### Note: Display tables do not currently support general Mule
|
|
|
222 characters. They will be overhauled at some point to support this
|
|
|
223 and to provide other features required under Mule.
|
|
|
224
|
|
|
225 @item
|
|
|
226 To use a glyph as the background pixmap of a face: Note that the
|
|
|
227 background pixmap of a face is actually an image specifier -- probably
|
|
|
228 the only place in XEmacs where an image specifier occurs outside of a
|
|
1137
|
229 glyph. Similarly to how the glyph's image specifier works, you don't
|
|
442
|
230 create your own image specifier, but rather add specifications to the
|
|
1137
|
231 existing one (using @code{set-face-background-pixmap-file} or
|
|
|
232 @code{set-face-background-pixmap}). Note that the image instance that is
|
|
|
233 generated in order to actually display the background pixmap is of type
|
|
|
234 @code{mono-pixmap}, meaning that it's a two-color image and the
|
|
|
235 foreground and background of the image get filled in with the
|
|
|
236 corresponding colors from the face.
|
|
442
|
237 @end itemize
|
|
|
238
|
|
|
239 It is extremely rare that you will ever have to specify a value for
|
|
444
|
240 @var{type}, which should be one of @code{buffer} (used for glyphs in an
|
|
442
|
241 extent, the modeline, the toolbar, or elsewhere in a buffer),
|
|
|
242 @code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
|
|
|
243 frame's icon), and defaults to @code{buffer}. The only cases where it
|
|
|
244 needs to be specified is when creating icon or pointer glyphs, and in
|
|
|
245 both cases the necessary glyphs have already been created at startup and
|
|
|
246 are accessed through the appropriate variables,
|
|
|
247 e.g. @code{text-pointer-glyph} (or in general, @code{*-pointer-glyph})
|
|
|
248 and @code{frame-icon-glyph}. @xref{Glyph Types}.
|
|
428
|
249 @end defun
|
|
|
250
|
|
|
251 @defun make-glyph-internal &optional type
|
|
|
252 This function creates a new, uninitialized glyph of type @var{type}.
|
|
|
253 @end defun
|
|
|
254
|
|
|
255 @defun make-pointer-glyph &optional spec-list
|
|
442
|
256
|
|
|
257 Return a new @code{pointer-glyph} object with the specification list
|
|
|
258 @var{spec-list}. This function is equivalent to calling
|
|
|
259 @code{make-glyph} with a @var{type} of @code{pointer}.
|
|
|
260
|
|
|
261 It is extremely unlikely that you will ever need to create a pointer
|
|
|
262 glyph. Instead, you probably want to be calling @code{set-glyph-image}
|
|
|
263 on an existing glyph, e.g. @code{text-pointer-glyph}.
|
|
428
|
264 @end defun
|
|
|
265
|
|
|
266 @defun make-icon-glyph &optional spec-list
|
|
442
|
267
|
|
|
268 Return a new @code{pointer-glyph} object with the specification list
|
|
|
269 @var{spec-list}. This function is equivalent to calling
|
|
|
270 @code{make-glyph} with a @var{type} of @code{icon}.
|
|
|
271
|
|
|
272 It is extremely unlikely that you will ever need to create a pointer
|
|
|
273 glyph. Instead, you probably want to be calling @code{set-glyph-image}
|
|
|
274 on an existing glyph, e.g. @code{text-pointer-glyph}.
|
|
428
|
275 @end defun
|
|
|
276
|
|
|
277 @node Glyph Properties
|
|
|
278 @subsection Glyph Properties
|
|
|
279
|
|
|
280 Each glyph has a list of properties, which control all of the aspects of
|
|
|
281 the glyph's appearance. The following symbols have predefined meanings:
|
|
|
282
|
|
|
283 @table @code
|
|
|
284 @item image
|
|
|
285 The image used to display the glyph.
|
|
|
286
|
|
|
287 @item baseline
|
|
|
288 Percent above baseline that glyph is to be displayed. Only for glyphs
|
|
|
289 displayed inside of a buffer.
|
|
|
290
|
|
|
291 @item contrib-p
|
|
|
292 Whether the glyph contributes to the height of the line it's on.
|
|
|
293 Only for glyphs displayed inside of a buffer.
|
|
|
294
|
|
|
295 @item face
|
|
|
296 Face of this glyph (@emph{not} a specifier).
|
|
|
297 @end table
|
|
|
298
|
|
|
299 @defun set-glyph-property glyph property value &optional locale tag-set how-to-add
|
|
|
300 This function changes a property of a @var{glyph}.
|
|
|
301
|
|
|
302 For built-in properties, the actual value of the property is a specifier
|
|
|
303 and you cannot change this; but you can change the specifications within
|
|
|
304 the specifier, and that is what this function will do. For user-defined
|
|
|
305 properties, you can use this function to either change the actual value
|
|
|
306 of the property or, if this value is a specifier, change the
|
|
|
307 specifications within it.
|
|
|
308
|
|
|
309 If @var{property} is a built-in property, the specifications to be added
|
|
|
310 to this property can be supplied in many different ways:
|
|
|
311
|
|
|
312 @itemize @bullet
|
|
|
313 @item
|
|
|
314 If @var{value} is a simple instantiator (e.g. a string naming a pixmap
|
|
|
315 filename) or a list of instantiators, then the instantiator(s) will be
|
|
|
316 added as a specification of the property for the given @var{locale}
|
|
|
317 (which defaults to @code{global} if omitted).
|
|
|
318
|
|
|
319 @item
|
|
|
320 If @var{value} is a list of specifications (each of which is a cons of a
|
|
|
321 locale and a list of instantiators), then @var{locale} must be
|
|
|
322 @code{nil} (it does not make sense to explicitly specify a locale in
|
|
|
323 this case), and specifications will be added as given.
|
|
|
324
|
|
|
325 @item
|
|
|
326 If @var{value} is a specifier (as would be returned by
|
|
|
327 @code{glyph-property} if no @var{locale} argument is given), then some
|
|
|
328 or all of the specifications in the specifier will be added to the
|
|
|
329 property. In this case, the function is really equivalent to
|
|
|
330 @code{copy-specifier} and @var{locale} has the same semantics (if it is
|
|
|
331 a particular locale, the specification for the locale will be copied; if
|
|
|
332 a locale type, specifications for all locales of that type will be
|
|
|
333 copied; if @code{nil} or @code{all}, then all specifications will be
|
|
|
334 copied).
|
|
|
335 @end itemize
|
|
|
336
|
|
|
337 @var{how-to-add} should be either @code{nil} or one of the symbols
|
|
|
338 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
|
|
|
339 @code{remove-tag-set-append}, @code{remove-locale},
|
|
|
340 @code{remove-locale-type}, or @code{remove-all}. See
|
|
|
341 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
|
|
|
342 of what each of these means. Most of the time, you do not need to worry
|
|
|
343 about this argument; the default behavior usually is fine.
|
|
|
344
|
|
|
345 In general, it is OK to pass an instance object (e.g. as returned by
|
|
|
346 @code{glyph-property-instance}) as an instantiator in place of an actual
|
|
|
347 instantiator. In such a case, the instantiator used to create that
|
|
|
348 instance object will be used (for example, if you set a font-instance
|
|
|
349 object as the value of the @code{font} property, then the font name used
|
|
|
350 to create that object will be used instead). If some cases, however,
|
|
|
351 doing this conversion does not make sense, and this will be noted in the
|
|
|
352 documentation for particular types of instance objects.
|
|
|
353
|
|
|
354 If @var{property} is not a built-in property, then this function will
|
|
|
355 simply set its value if @var{locale} is @code{nil}. However, if
|
|
|
356 @var{locale} is given, then this function will attempt to add
|
|
|
357 @var{value} as the instantiator for the given @var{locale}, using
|
|
|
358 @code{add-spec-to-specifier}. If the value of the property is not a
|
|
|
359 specifier, it will automatically be converted into a @code{generic}
|
|
|
360 specifier.
|
|
|
361 @end defun
|
|
|
362
|
|
|
363 @defun glyph-property glyph property &optional locale
|
|
|
364 This function returns @var{glyph}'s value of the given @var{property}.
|
|
|
365
|
|
|
366 If @var{locale} is omitted, the @var{glyph}'s actual value for
|
|
|
367 @var{property} will be returned. For built-in properties, this will be
|
|
|
368 a specifier object of a type appropriate to the property (e.g. a font or
|
|
|
369 color specifier). For other properties, this could be anything.
|
|
|
370
|
|
|
371 If @var{locale} is supplied, then instead of returning the actual value,
|
|
|
372 the specification(s) for the given locale or locale type will be
|
|
|
373 returned. This will only work if the actual value of @var{property} is
|
|
|
374 a specifier (this will always be the case for built-in properties, but
|
|
|
375 may or may not apply to user-defined properties). If the actual value
|
|
|
376 of @var{property} is not a specifier, this value will simply be returned
|
|
|
377 regardless of @var{locale}.
|
|
|
378
|
|
|
379 The return value will be a list of instantiators (e.g. vectors
|
|
|
380 specifying pixmap data), or a list of specifications, each of which is a
|
|
|
381 cons of a locale and a list of instantiators. Specifically, if
|
|
|
382 @var{locale} is a particular locale (a buffer, window, frame, device, or
|
|
|
383 @code{global}), a list of instantiators for that locale will be
|
|
|
384 returned. Otherwise, if @var{locale} is a locale type (one of the
|
|
|
385 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
|
|
|
386 the specifications for all locales of that type will be returned.
|
|
|
387 Finally, if @var{locale} is @code{all}, the specifications for all
|
|
|
388 locales of all types will be returned.
|
|
|
389
|
|
|
390 The specifications in a specifier determine what the value of
|
|
|
391 @var{property} will be in a particular @dfn{domain} or set of
|
|
|
392 circumstances, which is typically a particular Emacs window along with
|
|
|
393 the buffer it contains and the frame and device it lies within. The
|
|
|
394 value is derived from the instantiator associated with the most specific
|
|
|
395 locale (in the order buffer, window, frame, device, and @code{global})
|
|
|
396 that matches the domain in question. In other words, given a domain
|
|
|
397 (i.e. an Emacs window, usually), the specifier for @var{property} will
|
|
|
398 first be searched for a specification whose locale is the buffer
|
|
|
399 contained within that window; then for a specification whose locale is
|
|
|
400 the window itself; then for a specification whose locale is the frame
|
|
|
401 that the window is contained within; etc. The first instantiator that
|
|
|
402 is valid for the domain (usually this means that the instantiator is
|
|
|
403 recognized by the device [i.e. the X server or TTY device] that the
|
|
|
404 domain is on). The function @code{glyph-property-instance} actually does
|
|
|
405 all this, and is used to determine how to display the glyph.
|
|
|
406 @end defun
|
|
|
407
|
|
|
408 @defun glyph-property-instance glyph property &optional domain default no-fallback
|
|
|
409 This function returns the instance of @var{glyph}'s @var{property} in the
|
|
|
410 specified @var{domain}.
|
|
|
411
|
|
|
412 Under most circumstances, @var{domain} will be a particular window, and
|
|
|
413 the returned instance describes how the specified property actually is
|
|
|
414 displayed for that window and the particular buffer in it. Note that
|
|
|
415 this may not be the same as how the property appears when the buffer is
|
|
|
416 displayed in a different window or frame, or how the property appears in
|
|
|
417 the same window if you switch to another buffer in that window; and in
|
|
|
418 those cases, the returned instance would be different.
|
|
|
419
|
|
|
420 The returned instance is an image-instance object, and you can query it
|
|
|
421 using the appropriate image instance functions. For example, you could use
|
|
|
422 @code{image-instance-depth} to find out the depth (number of color
|
|
|
423 planes) of a pixmap displayed in a particular window. The results might
|
|
|
424 be different from the results you would get for another window (perhaps
|
|
|
425 the user specified a different image for the frame that window is on; or
|
|
|
426 perhaps the same image was specified but the window is on a different X
|
|
|
427 server, and that X server has different color capabilities from this
|
|
|
428 one).
|
|
|
429
|
|
|
430 @var{domain} defaults to the selected window if omitted.
|
|
|
431
|
|
|
432 @var{domain} can be a frame or device, instead of a window. The value
|
|
|
433 returned for such a domain is used in special circumstances when a
|
|
|
434 more specific domain does not apply; for example, a frame value might be
|
|
|
435 used for coloring a toolbar, which is conceptually attached to a frame
|
|
|
436 rather than a particular window. The value is also useful in
|
|
|
437 determining what the value would be for a particular window within the
|
|
|
438 frame or device, if it is not overridden by a more specific
|
|
|
439 specification.
|
|
|
440
|
|
|
441 If @var{property} does not name a built-in property, its value will
|
|
|
442 simply be returned unless it is a specifier object, in which case it
|
|
|
443 will be instanced using @code{specifier-instance}.
|
|
|
444
|
|
|
445 Optional arguments @var{default} and @var{no-fallback} are the same as
|
|
|
446 in @code{specifier-instance}. @xref{Specifiers}.
|
|
|
447 @end defun
|
|
|
448
|
|
|
449 @defun remove-glyph-property glyph property &optional locale tag-set exact-p
|
|
|
450 This function removes a property from a glyph. For built-in properties,
|
|
|
451 this is analogous to @code{remove-specifier}. @xref{Specifiers,
|
|
|
452 remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
|
|
|
453 and @var{exact-p} arguments.
|
|
|
454 @end defun
|
|
|
455
|
|
|
456 @node Glyph Convenience Functions
|
|
|
457 @subsection Glyph Convenience Functions
|
|
|
458
|
|
|
459 The following functions are provided for working with specific
|
|
|
460 properties of a glyph. Note that these are exactly like calling
|
|
|
461 the general functions described above and passing in the
|
|
|
462 appropriate value for @var{property}.
|
|
|
463
|
|
|
464 Remember that if you want to determine the ``value'' of a
|
|
|
465 specific glyph property, you probably want to use the @code{*-instance}
|
|
|
466 functions. For example, to determine whether a glyph contributes
|
|
|
467 to its line height, use @code{glyph-contrib-p-instance}, not
|
|
|
468 @code{glyph-contrib-p}. (The latter will return a boolean specifier
|
|
|
469 or a list of specifications, and you probably aren't concerned with
|
|
|
470 these.)
|
|
|
471
|
|
|
472 @defun glyph-image glyph &optional locale
|
|
|
473 This function is equivalent to calling @code{glyph-property} with
|
|
|
474 a property of @code{image}. The return value will be an image
|
|
|
475 specifier if @var{locale} is @code{nil} or omitted; otherwise,
|
|
|
476 it will be a specification or list of specifications.
|
|
|
477 @end defun
|
|
|
478
|
|
|
479 @defun set-glyph-image glyph spec &optional locale tag-set how-to-add
|
|
|
480 This function is equivalent to calling @code{set-glyph-property} with
|
|
|
481 a property of @code{image}.
|
|
|
482 @end defun
|
|
|
483
|
|
|
484 @defun glyph-image-instance glyph &optional domain default no-fallback
|
|
|
485 This function returns the instance of @var{glyph}'s image in the given
|
|
|
486 @var{domain}, and is equivalent to calling
|
|
|
487 @code{glyph-property-instance} with a property of @code{image}. The
|
|
|
488 return value will be an image instance.
|
|
|
489
|
|
|
490 Normally @var{domain} will be a window or @code{nil} (meaning the
|
|
|
491 selected window), and an instance object describing how the image
|
|
|
492 appears in that particular window and buffer will be returned.
|
|
|
493 @end defun
|
|
|
494
|
|
|
495 @defun glyph-contrib-p glyph &optional locale
|
|
|
496 This function is equivalent to calling @code{glyph-property} with
|
|
|
497 a property of @code{contrib-p}. The return value will be a boolean
|
|
|
498 specifier if @var{locale} is @code{nil} or omitted; otherwise,
|
|
|
499 it will be a specification or list of specifications.
|
|
|
500 @end defun
|
|
|
501
|
|
|
502 @defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
|
|
|
503 This function is equivalent to calling @code{set-glyph-property} with
|
|
|
504 a property of @code{contrib-p}.
|
|
|
505 @end defun
|
|
|
506
|
|
|
507 @defun glyph-contrib-p-instance glyph &optional domain default no-fallback
|
|
|
508 This function returns whether the glyph contributes to its line height
|
|
|
509 in the given @var{domain}, and is equivalent to calling
|
|
|
510 @code{glyph-property-instance} with a property of @code{contrib-p}. The
|
|
|
511 return value will be either @code{nil} or @code{t}. (Normally @var{domain}
|
|
|
512 will be a window or @code{nil}, meaning the selected window.)
|
|
|
513 @end defun
|
|
|
514
|
|
|
515 @defun glyph-baseline glyph &optional locale
|
|
|
516 This function is equivalent to calling @code{glyph-property} with a
|
|
|
517 property of @code{baseline}. The return value will be a specifier if
|
|
|
518 @var{locale} is @code{nil} or omitted; otherwise, it will be a
|
|
|
519 specification or list of specifications.
|
|
|
520 @end defun
|
|
|
521
|
|
|
522 @defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
|
|
|
523 This function is equivalent to calling @code{set-glyph-property} with
|
|
|
524 a property of @code{baseline}.
|
|
|
525 @end defun
|
|
|
526
|
|
|
527 @defun glyph-baseline-instance glyph &optional domain default no-fallback
|
|
|
528 This function returns the instance of @var{glyph}'s baseline value in
|
|
|
529 the given @var{domain}, and is equivalent to calling
|
|
|
530 @code{glyph-property-instance} with a property of @code{baseline}. The
|
|
|
531 return value will be an integer or @code{nil}.
|
|
|
532
|
|
|
533 Normally @var{domain} will be a window or @code{nil} (meaning the
|
|
|
534 selected window), and an instance object describing the baseline value
|
|
|
535 appears in that particular window and buffer will be returned.
|
|
|
536 @end defun
|
|
|
537
|
|
|
538 @defun glyph-face glyph
|
|
|
539 This function returns the face of @var{glyph}. (Remember, this is
|
|
|
540 not a specifier, but a simple property.)
|
|
|
541 @end defun
|
|
|
542
|
|
|
543 @defun set-glyph-face glyph face
|
|
|
544 This function changes the face of @var{glyph} to @var{face}.
|
|
|
545 @end defun
|
|
|
546
|
|
|
547 @node Glyph Dimensions
|
|
|
548 @subsection Glyph Dimensions
|
|
|
549
|
|
|
550 @defun glyph-width glyph &optional window
|
|
|
551 This function returns the width of @var{glyph} on @var{window}. This
|
|
|
552 may not be exact as it does not take into account all of the context
|
|
|
553 that redisplay will.
|
|
|
554 @end defun
|
|
|
555
|
|
|
556 @defun glyph-ascent glyph &optional window
|
|
|
557 This function returns the ascent value of @var{glyph} on @var{window}.
|
|
|
558 This may not be exact as it does not take into account all of the
|
|
|
559 context that redisplay will.
|
|
|
560 @end defun
|
|
|
561
|
|
|
562 @defun glyph-descent glyph &optional window
|
|
|
563 This function returns the descent value of @var{glyph} on @var{window}.
|
|
|
564 This may not be exact as it does not take into account all of the
|
|
|
565 context that redisplay will.
|
|
|
566 @end defun
|
|
|
567
|
|
|
568 @defun glyph-height glyph &optional window
|
|
|
569 This function returns the height of @var{glyph} on @var{window}. (This
|
|
|
570 is equivalent to the sum of the ascent and descent values.) This may
|
|
|
571 not be exact as it does not take into account all of the context that
|
|
|
572 redisplay will.
|
|
|
573 @end defun
|
|
|
574
|
|
|
575 @node Images
|
|
|
576 @section Images
|
|
|
577
|
|
|
578 @menu
|
|
|
579 * Image Specifiers:: Specifying how an image will appear.
|
|
|
580 * Image Instantiator Conversion::
|
|
|
581 Conversion is applied to image instantiators
|
|
|
582 at the time they are added to an
|
|
|
583 image specifier or at the time they
|
|
|
584 are passed to @code{make-image-instance}.
|
|
|
585 * Image Instances:: What an image specifier gets instanced as.
|
|
|
586 @end menu
|
|
|
587
|
|
|
588 @node Image Specifiers
|
|
|
589 @subsection Image Specifiers
|
|
|
590 @cindex image specifiers
|
|
|
591
|
|
|
592 An image specifier is used to describe the actual image of a glyph.
|
|
|
593 It works like other specifiers (@pxref{Specifiers}), in that it contains
|
|
|
594 a number of specifications describing how the image should appear in a
|
|
|
595 variety of circumstances. These specifications are called @dfn{image
|
|
|
596 instantiators}. When XEmacs wants to display the image, it instantiates
|
|
|
597 the image into an @dfn{image instance}. Image instances are their own
|
|
|
598 primitive object type (similar to font instances and color instances),
|
|
|
599 describing how the image appears in a particular domain. (On the other
|
|
|
600 hand, image instantiators, which are just descriptions of how the image
|
|
|
601 should appear, are represented using strings or vectors.)
|
|
|
602
|
|
|
603 @defun image-specifier-p object
|
|
|
604 This function returns non-@code{nil} if @var{object} is an image specifier.
|
|
|
605 Usually, an image specifier results from calling @code{glyph-image} on
|
|
|
606 a glyph.
|
|
|
607 @end defun
|
|
|
608
|
|
|
609 @defun make-image-specifier spec-list
|
|
442
|
610 This function creates a new image specifier object and initializes it
|
|
|
611 according to @var{spec-list}. @xref{Specifiers}.
|
|
|
612
|
|
|
613 Note that, in practice, you rarely, if ever, need to actually create an
|
|
|
614 image specifier! (This function exists mainly for completeness.) Pretty
|
|
|
615 much the only use for image specifiers is to control how glyphs are
|
|
|
616 displayed, and the image specifier associated with a glyph (the
|
|
|
617 @code{image} property of a glyph) is created automatically when a glyph
|
|
|
618 is created and need not (and cannot, for that matter) ever be changed
|
|
|
619 (@pxref{Glyphs}). In fact, the design decision to create a separate
|
|
|
620 image specifier type, rather than make glyphs themselves be specifiers,
|
|
|
621 is debatable---the other properties of glyphs are rarely used and could
|
|
|
622 conceivably have been incorporated into the glyph's instantiator. The
|
|
|
623 rarely used glyph types (buffer, pointer, icon) could also have been
|
|
|
624 incorporated into the instantiator.
|
|
428
|
625 @end defun
|
|
|
626
|
|
|
627 Image instantiators come in many formats: @code{xbm}, @code{xpm},
|
|
|
628 @code{gif}, @code{jpeg}, etc. This describes the format of the data
|
|
|
629 describing the image. The resulting image instances also come in many
|
|
440
|
630 types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
|
|
428
|
631 @code{pointer}, etc. This refers to the behavior of the image and the
|
|
|
632 sorts of places it can appear. (For example, a color-pixmap image has
|
|
|
633 fixed colors specified for it, while a mono-pixmap image comes in two
|
|
|
634 unspecified shades ``foreground'' and ``background'' that are determined
|
|
|
635 from the face of the glyph or surrounding text; a text image appears as
|
|
|
636 a string of text and has an unspecified foreground, background, and
|
|
|
637 font; a pointer image behaves like a mono-pixmap image but can only be
|
|
|
638 used as a mouse pointer [mono-pixmap images cannot be used as mouse
|
|
|
639 pointers]; etc.) It is important to keep the distinction between image
|
|
|
640 instantiator format and image instance type in mind. Typically, a given
|
|
|
641 image instantiator format can result in many different image instance
|
|
|
642 types (for example, @code{xpm} can be instanced as @code{color-pixmap},
|
|
|
643 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
|
|
|
644 instanced only as @code{pointer}), and a particular image instance type
|
|
|
645 can be generated by many different image instantiator formats (e.g.
|
|
|
646 @code{color-pixmap} can be generated by @code{xpm}, @code{gif},
|
|
|
647 @code{jpeg}, etc.).
|
|
|
648
|
|
|
649 @xref{Image Instances}, for a more detailed discussion of image
|
|
|
650 instance types.
|
|
|
651
|
|
|
652 An image instantiator should be a string or a vector of the form
|
|
|
653
|
|
|
654 @example
|
|
|
655 @code{[@var{format} @var{:keyword} @var{value} ...]}
|
|
|
656 @end example
|
|
|
657
|
|
|
658 i.e. a format symbol followed by zero or more alternating keyword-value
|
|
|
659 pairs. The @dfn{format} field should be a symbol, one of
|
|
|
660
|
|
|
661 @table @code
|
|
|
662 @item nothing
|
|
442
|
663 Don't display anything; no keywords are valid for this. Can only be
|
|
|
664 instanced as @code{nothing}.
|
|
428
|
665 @item string
|
|
442
|
666 Display this image as a text string. Can only be instanced
|
|
428
|
667 as @code{text}, although support for instancing as @code{mono-pixmap}
|
|
442
|
668 should be added.
|
|
428
|
669 @item formatted-string
|
|
442
|
670 Display this image as a text string with replaceable fields,
|
|
|
671 similar to a modeline format string; not currently implemented.
|
|
428
|
672 @item xbm
|
|
442
|
673 An X bitmap; only if X support was compiled into this XEmacs. Can be
|
|
428
|
674 instanced as @code{mono-pixmap}, @code{color-pixmap}, or
|
|
442
|
675 @code{pointer}.
|
|
428
|
676 @item xpm
|
|
442
|
677 An XPM pixmap; only if XPM support was compiled into this XEmacs. Can
|
|
428
|
678 be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
|
|
|
679 @code{pointer}. XPM is an add-on library for X that was designed to
|
|
|
680 rectify the shortcomings of the XBM format. Most implementations of X
|
|
|
681 include the XPM library as a standard part. If your vendor does not, it
|
|
|
682 is highly recommended that you download it and install it. You can get
|
|
442
|
683 it from the standard XEmacs FTP site, among other places.
|
|
428
|
684 @item xface
|
|
442
|
685 An X-Face bitmap, used to encode people's faces in e-mail messages;
|
|
428
|
686 only if X-Face support was compiled into this XEmacs. Can be instanced
|
|
442
|
687 as @code{mono-pixmap}, @code{color-pixmap}, or @code{pointer}.
|
|
428
|
688 @item gif
|
|
442
|
689 A GIF87 or GIF89 image; only if GIF support was compiled into this
|
|
428
|
690 XEmacs. Can be instanced as @code{color-pixmap}. Note that XEmacs
|
|
|
691 includes GIF decoding functions as a standard part of it, so if you have
|
|
|
692 X support, you will normally have GIF support, unless you explicitly
|
|
442
|
693 disable it at configure time.
|
|
428
|
694 @item jpeg
|
|
442
|
695 A JPEG-format image; only if JPEG support was compiled into this
|
|
428
|
696 XEmacs. Can be instanced as @code{color-pixmap}. If you have the JPEG
|
|
|
697 libraries present on your system when XEmacs is built, XEmacs will
|
|
|
698 automatically detect this and use them, unless you explicitly disable it
|
|
442
|
699 at configure time.
|
|
428
|
700 @item png
|
|
442
|
701 A PNG/GIF24 image; only if PNG support was compiled into this XEmacs.
|
|
|
702 Can be instanced as @code{color-pixmap}.
|
|
428
|
703 @item tiff
|
|
442
|
704 A TIFF-format image; only if TIFF support was compiled into this XEmacs.
|
|
428
|
705 @item cursor-font
|
|
442
|
706 One of the standard cursor-font names, such as @samp{watch} or
|
|
428
|
707 @samp{right_ptr} under X. Under X, this is, more specifically, any of
|
|
|
708 the standard cursor names from appendix B of the Xlib manual [also known
|
|
|
709 as the file @file{<X11/cursorfont.h>}] minus the @samp{XC_} prefix. On
|
|
|
710 other window systems, the valid names will be specific to the type of
|
|
442
|
711 window system. Can only be instanced as @code{pointer}.
|
|
428
|
712 @item font
|
|
442
|
713 A glyph from a font; i.e. the name of a font, and glyph index into it
|
|
428
|
714 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
|
|
|
715 Only if X support was compiled into this XEmacs. Currently can only be
|
|
442
|
716 instanced as @code{pointer}, although this should probably be fixed.
|
|
|
717 @item mswindows-resource
|
|
|
718 An MS Windows pointer resource. Specifies a resource to retrieve
|
|
|
719 directly from the system (an OEM resource) or from a file, particularly
|
|
|
720 an executable file. If the resource is to be retrieved from a file, use
|
|
|
721 :file and optionally :resource-id. Otherwise use :resource-id. Always
|
|
|
722 specify :resource-type to specify the type (cursor, bitmap or icon) of
|
|
|
723 the resource. Possible values for :resource-id are listed below. Can
|
|
|
724 be instanced as @code{pointer} or @code{color-pixmap}.
|
|
428
|
725 @item subwindow
|
|
442
|
726 An embedded windowing system window. Can only be instanced as
|
|
|
727 @code{subwindow}.
|
|
|
728 @item button
|
|
|
729 A button widget; either a push button, radio button or toggle button.
|
|
|
730 Can only be instanced as @code{widget}.
|
|
|
731 @item combo-box
|
|
|
732 A drop list of selectable items in a widget, for editing text.
|
|
|
733 Can only be instanced as @code{widget}.
|
|
|
734 @item edit-field
|
|
|
735 A text editing widget. Can only be instanced as @code{widget}.
|
|
|
736 @item label
|
|
|
737 A static, text-only, widget; for displaying text. Can only be instanced
|
|
|
738 as @code{widget}.
|
|
|
739 @item layout
|
|
|
740 A widget for controlling the positioning of children underneath it.
|
|
|
741 Through the use of nested layouts, a widget hierarchy can be created
|
|
|
742 which can have the appearance of any standard dialog box or similar
|
|
|
743 arrangement; all of this is counted as one @dfn{glyph} and could appear
|
|
|
744 in many of the places that expect a single glyph. Can only be instanced
|
|
|
745 as @code{widget}.
|
|
|
746 @item native-layout
|
|
|
747 @c #### Document me better!
|
|
|
748 The native version of a layout widget.
|
|
|
749 Can only be instanced as @code{widget}.
|
|
|
750 @item progress-gauge
|
|
|
751 A sliding widget, for showing progress. Can only be instanced as
|
|
|
752 @code{widget}.
|
|
|
753 @item tab-control
|
|
|
754 A tab widget; a series of user selectable tabs. Can only be instanced
|
|
|
755 as @code{widget}.
|
|
|
756 @item tree-view
|
|
|
757 A folding widget. Can only be instanced as @code{widget}.
|
|
|
758 @item scrollbar
|
|
|
759 A scrollbar widget. Can only be instanced as @code{widget}.
|
|
428
|
760 @item autodetect
|
|
442
|
761 XEmacs tries to guess what format the data is in. If X support exists,
|
|
428
|
762 the data string will be checked to see if it names a filename. If so,
|
|
|
763 and this filename contains XBM or XPM data, the appropriate sort of
|
|
|
764 pixmap or pointer will be created. [This includes picking up any
|
|
|
765 specified hotspot or associated mask file.] Otherwise, if @code{pointer}
|
|
|
766 is one of the allowable image-instance types and the string names a
|
|
|
767 valid cursor-font name, the image will be created as a pointer.
|
|
|
768 Otherwise, the image will be displayed as text. If no X support exists,
|
|
442
|
769 the image will always be displayed as text.
|
|
|
770 @item inherit
|
|
|
771 Inherit from the background-pixmap property of a face. Can only be
|
|
|
772 instanced as @code{mono-pixmap}.
|
|
428
|
773 @end table
|
|
|
774
|
|
|
775 The valid keywords are:
|
|
|
776
|
|
|
777 @table @code
|
|
|
778 @item :data
|
|
442
|
779 Inline data. For most formats above, this should be a string. For
|
|
428
|
780 XBM images, this should be a list of three elements: width, height, and
|
|
|
781 a string of bit data. This keyword is not valid for instantiator
|
|
442
|
782 format @code{nothing}.
|
|
428
|
783
|
|
|
784 @item :file
|
|
442
|
785 Data is contained in a file. The value is the name of this file. If
|
|
428
|
786 both @code{:data} and @code{:file} are specified, the image is created
|
|
|
787 from what is specified in @code{:data} and the string in @code{:file}
|
|
|
788 becomes the value of the @code{image-instance-file-name} function when
|
|
|
789 applied to the resulting image-instance. This keyword is not valid for
|
|
|
790 instantiator formats @code{nothing}, @code{string},
|
|
|
791 @code{formatted-string}, @code{cursor-font}, @code{font}, and
|
|
442
|
792 @code{autodetect}.
|
|
428
|
793
|
|
|
794 @item :foreground
|
|
|
795 @itemx :background
|
|
442
|
796 For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
|
|
428
|
797 These keywords allow you to explicitly specify foreground and background
|
|
|
798 colors. The argument should be anything acceptable to
|
|
|
799 @code{make-color-instance}. This will cause what would be a
|
|
|
800 @code{mono-pixmap} to instead be colorized as a two-color color-pixmap,
|
|
|
801 and specifies the foreground and/or background colors for a pointer
|
|
442
|
802 instead of black and white.
|
|
428
|
803
|
|
|
804 @item :mask-data
|
|
442
|
805 For @code{xbm} and @code{xface}. This specifies a mask to be used with the
|
|
428
|
806 bitmap. The format is a list of width, height, and bits, like for
|
|
442
|
807 @code{:data}.
|
|
428
|
808
|
|
|
809 @item :mask-file
|
|
442
|
810 For @code{xbm} and @code{xface}. This specifies a file containing the
|
|
428
|
811 mask data. If neither a mask file nor inline mask data is given for an
|
|
|
812 XBM image, and the XBM image comes from a file, XEmacs will look for a
|
|
|
813 mask file with the same name as the image file but with @samp{Mask} or
|
|
|
814 @samp{msk} appended. For example, if you specify the XBM file
|
|
|
815 @file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
|
|
|
816 the associated mask file @file{left_ptrmsk} will automatically be picked
|
|
442
|
817 up.
|
|
428
|
818
|
|
|
819 @item :hotspot-x
|
|
|
820 @itemx :hotspot-y
|
|
442
|
821 For @code{xbm} and @code{xface}. These keywords specify a hotspot if
|
|
428
|
822 the image is instantiated as a @code{pointer}. Note that if the XBM
|
|
|
823 image file specifies a hotspot, it will automatically be picked up if no
|
|
442
|
824 explicit hotspot is given.
|
|
428
|
825
|
|
|
826 @item :color-symbols
|
|
442
|
827 Only for @code{xpm}. This specifies an alist that maps strings that
|
|
428
|
828 specify symbolic color names to the actual color to be used for that
|
|
|
829 symbolic color (in the form of a string or a color-specifier object).
|
|
|
830 If this is not specified, the contents of @code{xpm-color-symbols} are
|
|
442
|
831 used to generate the alist.
|
|
|
832 @item :resource-id
|
|
|
833 Only for @code{mswindows-resource}. This must be either an integer
|
|
|
834 (which directly specifies a resource number) or a string. Valid strings
|
|
|
835 are
|
|
|
836
|
|
|
837 For bitmaps:
|
|
|
838
|
|
|
839 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
|
|
|
840 "reduce", "zoom", "restore", "reduced", "zoomd",
|
|
|
841 "restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd",
|
|
|
842 "mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi",
|
|
|
843 "lfarrowi", "size", "btsize", "check", "checkboxes", and
|
|
|
844 "btncorners".
|
|
|
845
|
|
|
846 For cursors:
|
|
|
847
|
|
|
848 "normal", "ibeam", "wait", "cross", "up", "sizenwse",
|
|
|
849 "sizenesw", "sizewe", "sizens", "sizeall", and "no".
|
|
|
850
|
|
|
851 For icons:
|
|
|
852
|
|
|
853 "sample", "hand", "ques", "bang", "note", and "winlogo".
|
|
|
854 @item :resource-type
|
|
|
855 Only for @code{mswindows-resource}. This must be a symbol, either
|
|
|
856 @code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
|
|
|
857 resource to be retrieved.
|
|
|
858 @item :face
|
|
|
859 Only for @code{inherit}. This specifies the face to inherit from. For
|
|
|
860 widgets this also specifies the face to use for display. It defaults to
|
|
|
861 gui-element-face.
|
|
428
|
862 @end table
|
|
|
863
|
|
442
|
864 Keywords accepted as menu item specs are also accepted by widgets.
|
|
|
865 These are @code{:selected}, @code{:active}, @code{:suffix},
|
|
|
866 @code{:keys}, @code{:style}, @code{:filter}, @code{:config},
|
|
|
867 @code{:included}, @code{:key-sequence}, @code{:accelerator},
|
|
|
868 @code{:label} and @code{:callback}.
|
|
|
869
|
|
428
|
870 If instead of a vector, the instantiator is a string, it will be
|
|
|
871 converted into a vector by looking it up according to the specs in the
|
|
|
872 @code{console-type-image-conversion-list} for the console type of
|
|
|
873 the domain (usually a window; sometimes a frame or device) over which
|
|
|
874 the image is being instantiated.
|
|
|
875
|
|
|
876 If the instantiator specifies data from a file, the data will be read in
|
|
|
877 at the time that the instantiator is added to the image specifier (which
|
|
|
878 may be well before the image is actually displayed), and the
|
|
|
879 instantiator will be converted into one of the inline-data forms, with
|
|
|
880 the filename retained using a @code{:file} keyword. This implies that
|
|
|
881 the file must exist when the instantiator is added to the image, but
|
|
|
882 does not need to exist at any other time (e.g. it may safely be a
|
|
|
883 temporary file).
|
|
|
884
|
|
444
|
885 @defun valid-image-instantiator-format-p format &optional locale
|
|
428
|
886 This function returns non-@code{nil} if @var{format} is a valid image
|
|
444
|
887 instantiator format.
|
|
|
888
|
|
|
889 If @var{locale} is non-@code{nil} then the format is checked in that locale.
|
|
|
890 If @var{locale} is @code{nil} the current console is used.
|
|
|
891
|
|
|
892 Note that the return value for many formats listed above depends on
|
|
|
893 whether XEmacs was compiled with support for that format.
|
|
428
|
894 @end defun
|
|
|
895
|
|
|
896 @defun image-instantiator-format-list
|
|
|
897 This function return a list of valid image-instantiator formats.
|
|
|
898 @end defun
|
|
|
899
|
|
|
900 @defvar xpm-color-symbols
|
|
|
901 This variable holds definitions of logical color-names used when reading
|
|
|
902 XPM files. Elements of this list should be of the form
|
|
|
903 @code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name}
|
|
|
904 should be a string, which is the name of the color to define; the
|
|
|
905 @var{form-to-evaluate} should evaluate to a color specifier object, or a
|
|
|
906 string to be passed to @code{make-color-instance} (@pxref{Colors}). If
|
|
|
907 a loaded XPM file references a symbolic color called @var{color-name},
|
|
|
908 it will display as the computed color instead.
|
|
|
909
|
|
|
910 The default value of this variable defines the logical color names
|
|
|
911 @samp{"foreground"} and @samp{"background"} to be the colors of the
|
|
|
912 @code{default} face.
|
|
|
913 @end defvar
|
|
|
914
|
|
|
915 @defvar x-bitmap-file-path
|
|
444
|
916 A list of the directories in which X bitmap files may be found. If @code{nil},
|
|
428
|
917 this is initialized from the @samp{"*bitmapFilePath"} resource. This is
|
|
|
918 used by the @code{make-image-instance} function (however, note that if
|
|
|
919 the environment variable @samp{XBMLANGPATH} is set, it is consulted
|
|
|
920 first).
|
|
|
921 @end defvar
|
|
|
922
|
|
|
923 @node Image Instantiator Conversion
|
|
|
924 @subsection Image Instantiator Conversion
|
|
|
925 @cindex image instantiator conversion
|
|
|
926 @cindex conversion of image instantiators
|
|
|
927
|
|
|
928 @defun set-console-type-image-conversion-list console-type list
|
|
|
929 This function sets the image-conversion-list for consoles of the given
|
|
|
930 @var{console-type}. The image-conversion-list specifies how image
|
|
|
931 instantiators that are strings should be interpreted. Each element of
|
|
|
932 the list should be a list of two elements (a regular expression string
|
|
|
933 and a vector) or a list of three elements (the preceding two plus an
|
|
|
934 integer index into the vector). The string is converted to the vector
|
|
|
935 associated with the first matching regular expression. If a vector
|
|
|
936 index is specified, the string itself is substituted into that position
|
|
|
937 in the vector.
|
|
|
938
|
|
|
939 Note: The conversion above is applied when the image instantiator is
|
|
|
940 added to an image specifier, not when the specifier is actually
|
|
|
941 instantiated. Therefore, changing the image-conversion-list only affects
|
|
|
942 newly-added instantiators. Existing instantiators in glyphs and image
|
|
|
943 specifiers will not be affected.
|
|
|
944 @end defun
|
|
|
945
|
|
|
946 @defun console-type-image-conversion-list console-type
|
|
|
947 This function returns the image-conversion-list for consoles of the given
|
|
|
948 @var{console-type}.
|
|
|
949 @end defun
|
|
|
950
|
|
|
951 @node Image Instances
|
|
|
952 @subsection Image Instances
|
|
|
953 @cindex image instances
|
|
|
954
|
|
|
955 Image-instance objects encapsulate the way a particular image (pixmap,
|
|
|
956 etc.) is displayed on a particular device.
|
|
|
957
|
|
|
958 In most circumstances, you do not need to directly create image
|
|
|
959 instances; use a glyph instead. However, it may occasionally be useful
|
|
|
960 to explicitly create image instances, if you want more control over the
|
|
|
961 instantiation process.
|
|
|
962
|
|
|
963 @defun image-instance-p object
|
|
|
964 This function returns non-@code{nil} if @var{object} is an image instance.
|
|
|
965 @end defun
|
|
|
966
|
|
|
967 @menu
|
|
|
968 * Image Instance Types:: Each image instances has a particular type.
|
|
|
969 * Image Instance Functions:: Functions for working with image instances.
|
|
|
970 @end menu
|
|
|
971
|
|
|
972 @node Image Instance Types
|
|
|
973 @subsubsection Image Instance Types
|
|
|
974 @cindex image instance types
|
|
|
975
|
|
|
976 Image instances come in a number of different types. The type
|
|
|
977 of an image instance specifies the nature of the image: Whether
|
|
|
978 it is a text string, a mono pixmap, a color pixmap, etc.
|
|
|
979
|
|
|
980 The valid image instance types are
|
|
|
981
|
|
|
982 @table @code
|
|
|
983 @item nothing
|
|
|
984 Nothing is displayed.
|
|
|
985
|
|
|
986 @item text
|
|
|
987 Displayed as text. The foreground and background colors and the
|
|
|
988 font of the text are specified independent of the pixmap. Typically
|
|
|
989 these attributes will come from the face of the surrounding text,
|
|
|
990 unless a face is specified for the glyph in which the image appears.
|
|
|
991
|
|
|
992 @item mono-pixmap
|
|
|
993 Displayed as a mono pixmap (a pixmap with only two colors where the
|
|
|
994 foreground and background can be specified independent of the pixmap;
|
|
|
995 typically the pixmap assumes the foreground and background colors of
|
|
|
996 the text around it, unless a face is specified for the glyph in which
|
|
|
997 the image appears).
|
|
|
998 @item color-pixmap
|
|
|
999
|
|
|
1000 Displayed as a color pixmap.
|
|
|
1001
|
|
|
1002 @item pointer
|
|
|
1003 Used as the mouse pointer for a window.
|
|
|
1004
|
|
|
1005 @item subwindow
|
|
|
1006 A child window that is treated as an image. This allows (e.g.)
|
|
|
1007 another program to be responsible for drawing into the window.
|
|
|
1008 Not currently implemented.
|
|
|
1009 @end table
|
|
|
1010
|
|
|
1011 @defun valid-image-instance-type-p type
|
|
|
1012 This function returns non-@code{nil} if @var{type} is a valid image
|
|
|
1013 instance type.
|
|
|
1014 @end defun
|
|
|
1015
|
|
|
1016 @defun image-instance-type-list
|
|
|
1017 This function returns a list of the valid image instance types.
|
|
|
1018 @end defun
|
|
|
1019
|
|
|
1020 @defun image-instance-type image-instance
|
|
|
1021 This function returns the type of the given image instance. The return
|
|
|
1022 value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
|
|
|
1023 @code{color-pixmap}, @code{pointer}, or @code{subwindow}.
|
|
|
1024 @end defun
|
|
|
1025
|
|
|
1026 @defun text-image-instance-p object
|
|
|
1027 This function returns non-@code{nil} if @var{object} is an image
|
|
|
1028 instance of type @code{text}.
|
|
|
1029 @end defun
|
|
|
1030
|
|
|
1031 @defun mono-pixmap-image-instance-p object
|
|
|
1032 This function returns non-@code{nil} if @var{object} is an image
|
|
|
1033 instance of type @code{mono-pixmap}.
|
|
|
1034 @end defun
|
|
|
1035
|
|
|
1036 @defun color-pixmap-image-instance-p object
|
|
|
1037 This function returns non-@code{nil} if @var{object} is an image
|
|
|
1038 instance of type @code{color-pixmap}.
|
|
|
1039 @end defun
|
|
|
1040
|
|
|
1041 @defun pointer-image-instance-p object
|
|
|
1042 This function returns non-@code{nil} if @var{object} is an image
|
|
|
1043 instance of type @code{pointer}.
|
|
|
1044 @end defun
|
|
|
1045
|
|
|
1046 @defun subwindow-image-instance-p object
|
|
|
1047 This function returns non-@code{nil} if @var{object} is an image
|
|
|
1048 instance of type @code{subwindow}.
|
|
|
1049 @end defun
|
|
|
1050
|
|
|
1051 @defun nothing-image-instance-p object
|
|
|
1052 This function returns non-@code{nil} if @var{object} is an image
|
|
|
1053 instance of type @code{nothing}.
|
|
|
1054 @end defun
|
|
|
1055
|
|
442
|
1056 @defun widget-image-instance-p object
|
|
444
|
1057 Return @code{t} if @var{object} is an image instance of type @code{widget}.
|
|
442
|
1058 @end defun
|
|
|
1059
|
|
428
|
1060 @node Image Instance Functions
|
|
|
1061 @subsubsection Image Instance Functions
|
|
|
1062
|
|
444
|
1063 @defun make-image-instance data &optional domain dest-types noerror
|
|
428
|
1064 This function creates a new image-instance object.
|
|
|
1065
|
|
|
1066 @var{data} is an image instantiator, which describes the image
|
|
|
1067 (@pxref{Image Specifiers}).
|
|
|
1068
|
|
|
1069 @var{dest-types} should be a list of allowed image instance types that
|
|
|
1070 can be generated. The @var{dest-types} list is unordered. If multiple
|
|
|
1071 destination types are possible for a given instantiator, the ``most
|
|
|
1072 natural'' type for the instantiator's format is chosen. (For XBM, the
|
|
|
1073 most natural types are @code{mono-pixmap}, followed by
|
|
|
1074 @code{color-pixmap}, followed by @code{pointer}. For the other normal
|
|
|
1075 image formats, the most natural types are @code{color-pixmap}, followed
|
|
|
1076 by @code{mono-pixmap}, followed by @code{pointer}. For the string and
|
|
|
1077 formatted-string formats, the most natural types are @code{text},
|
|
|
1078 followed by @code{mono-pixmap} (not currently implemented), followed by
|
|
442
|
1079 @code{color-pixmap} (not currently implemented). For MS Windows
|
|
|
1080 resources, the most natural type for pointer resources is
|
|
|
1081 @code{pointer}, and for the others it's @code{color-pixmap}. The other
|
|
|
1082 formats can only be instantiated as one type. (If you want to control
|
|
|
1083 more specifically the order of the types into which an image is
|
|
|
1084 instantiated, just call @code{make-image-instance} repeatedly until it
|
|
|
1085 succeeds, passing less and less preferred destination types each time.
|
|
428
|
1086
|
|
|
1087 If @var{dest-types} is omitted, all possible types are allowed.
|
|
|
1088
|
|
442
|
1089 @var{domain} specifies the domain to which the image instance will be
|
|
|
1090 attached. This domain is termed the @dfn{governing domain}. The type
|
|
|
1091 of the governing domain depends on the image instantiator
|
|
|
1092 format. (Although, more correctly, it should probably depend on the
|
|
|
1093 image instance type.) For example, pixmap image instances are specific
|
|
|
1094 to a device, but widget image instances are specific to a particular
|
|
|
1095 XEmacs window because in order to display such a widget when two windows
|
|
|
1096 onto the same buffer want to display the widget, two separate underlying
|
|
|
1097 widgets must be created. (That's because a widget is actually a child
|
|
|
1098 window-system window, and all window-system windows have a unique
|
|
|
1099 existence on the screen.) This means that the governing domain for a
|
|
|
1100 pixmap image instance will be some device (most likely, the only
|
|
|
1101 existing device), whereas the governing domain for a widget image
|
|
|
1102 instance will be some XEmacs window.
|
|
|
1103
|
|
|
1104 If you specify an overly general @var{domain} (e.g. a frame when a
|
|
|
1105 window was wanted), an error is signaled. If you specify an overly
|
|
|
1106 specific @var{domain} (e.g. a window when a device was wanted), the
|
|
|
1107 corresponding general domain is fetched and used instead. For
|
|
|
1108 @code{make-image-instance}, it makes no difference whether you specify
|
|
|
1109 an overly specific domain or the properly general domain derived from
|
|
|
1110 it. However, it does matter when creating an image instance by
|
|
|
1111 instantiating a specifier or glyph (e.g. with
|
|
|
1112 @code{glyph-image-instance}), because the more specific domain causes
|
|
|
1113 spec lookup to start there and proceed to more general domains. (It
|
|
|
1114 would also matter when creating an image instance with an instantiator
|
|
|
1115 format of @code{inherit}, but we currently disallow this. #### We should
|
|
|
1116 fix this.)
|
|
|
1117 n
|
|
|
1118 If omitted, @var{domain} defaults to the selected window.
|
|
|
1119
|
|
444
|
1120 @var{noerror} controls what happens when the image cannot be generated.
|
|
|
1121 If @code{nil}, an error message is generated. If @code{t}, no messages
|
|
|
1122 are generated and this function returns @code{nil}. If anything else, a
|
|
|
1123 warning message is generated and this function returns @code{nil}.
|
|
428
|
1124 @end defun
|
|
|
1125
|
|
|
1126 @defun colorize-image-instance image-instance foreground background
|
|
|
1127 This function makes the image instance be displayed in the given
|
|
|
1128 colors. Image instances come in two varieties: bitmaps, which are 1
|
|
|
1129 bit deep which are rendered in the prevailing foreground and background
|
|
|
1130 colors; and pixmaps, which are of arbitrary depth (including 1) and
|
|
|
1131 which have the colors explicitly specified. This function converts a
|
|
|
1132 bitmap to a pixmap. If the image instance was a pixmap already,
|
|
|
1133 nothing is done (and @code{nil} is returned). Otherwise @code{t} is
|
|
|
1134 returned.
|
|
|
1135 @end defun
|
|
|
1136
|
|
|
1137 @defun image-instance-name image-instance
|
|
|
1138 This function returns the name of the given image instance.
|
|
|
1139 @end defun
|
|
|
1140
|
|
442
|
1141 @defun image-instance-domain image-instance
|
|
|
1142
|
|
|
1143 Return the governing domain of the given @var{image-instance}. The
|
|
|
1144 governing domain of an image instance is the domain that the image
|
|
|
1145 instance is specific to. It is @emph{NOT} necessarily the domain that
|
|
|
1146 was given to the call to @code{specifier-instance} that resulted in the
|
|
|
1147 creation of this image instance. See @code{make-image-instance} for
|
|
|
1148 more information on governing domains.
|
|
|
1149 @end defun
|
|
|
1150
|
|
|
1151
|
|
428
|
1152 @defun image-instance-string image-instance
|
|
|
1153 This function returns the string of the given image instance. This will
|
|
|
1154 only be non-@code{nil} for text image instances.
|
|
|
1155 @end defun
|
|
|
1156
|
|
|
1157 @defun image-instance-file-name image-instance
|
|
|
1158 This function returns the file name from which @var{image-instance} was
|
|
|
1159 read, if known.
|
|
|
1160 @end defun
|
|
|
1161
|
|
|
1162 @defun image-instance-mask-file-name image-instance
|
|
|
1163 This function returns the file name from which @var{image-instance}'s
|
|
|
1164 mask was read, if known.
|
|
|
1165 @end defun
|
|
|
1166
|
|
|
1167 @defun image-instance-depth image-instance
|
|
|
1168 This function returns the depth of the image instance. This is 0 for a
|
|
|
1169 mono pixmap, or a positive integer for a color pixmap.
|
|
|
1170 @end defun
|
|
|
1171
|
|
|
1172 @defun image-instance-height image-instance
|
|
|
1173 This function returns the height of the image instance, in pixels.
|
|
|
1174 @end defun
|
|
|
1175
|
|
|
1176 @defun image-instance-width image-instance
|
|
|
1177 This function returns the width of the image instance, in pixels.
|
|
|
1178 @end defun
|
|
|
1179
|
|
|
1180 @defun image-instance-hotspot-x image-instance
|
|
|
1181 This function returns the X coordinate of the image instance's hotspot,
|
|
|
1182 if known. This is a point relative to the origin of the pixmap. When
|
|
|
1183 an image is used as a mouse pointer, the hotspot is the point on the
|
|
|
1184 image that sits over the location that the pointer points to. This is,
|
|
|
1185 for example, the tip of the arrow or the center of the crosshairs.
|
|
|
1186
|
|
|
1187 This will always be @code{nil} for a non-pointer image instance.
|
|
|
1188 @end defun
|
|
|
1189
|
|
|
1190 @defun image-instance-hotspot-y image-instance
|
|
|
1191 This function returns the Y coordinate of the image instance's hotspot,
|
|
|
1192 if known.
|
|
|
1193 @end defun
|
|
|
1194
|
|
|
1195 @defun image-instance-foreground image-instance
|
|
|
1196 This function returns the foreground color of @var{image-instance}, if
|
|
|
1197 applicable. This will be a color instance or @code{nil}. (It will only
|
|
|
1198 be non-@code{nil} for colorized mono pixmaps and for pointers.)
|
|
|
1199 @end defun
|
|
|
1200
|
|
|
1201 @defun image-instance-background image-instance
|
|
|
1202 This function returns the background color of @var{image-instance}, if
|
|
|
1203 applicable. This will be a color instance or @code{nil}. (It will only
|
|
|
1204 be non-@code{nil} for colorized mono pixmaps and for pointers.)
|
|
|
1205 @end defun
|
|
|
1206
|
|
|
1207
|
|
|
1208 @node Glyph Types
|
|
|
1209 @section Glyph Types
|
|
|
1210
|
|
|
1211 Each glyph has a particular type, which controls how the glyph's image
|
|
|
1212 is generated. Each glyph type has a corresponding list of allowable
|
|
|
1213 image instance types that can be generated. When you call
|
|
|
1214 @code{glyph-image-instance} to retrieve the image instance of a glyph,
|
|
|
1215 XEmacs does the equivalent of calling @code{make-image-instance} and
|
|
|
1216 passing in @var{dest-types} the list of allowable image instance types
|
|
|
1217 for the glyph's type.
|
|
|
1218
|
|
|
1219 @itemize @bullet
|
|
|
1220 @item
|
|
|
1221 @code{buffer} glyphs can be used as the begin-glyph or end-glyph of an
|
|
|
1222 extent, in the modeline, and in the toolbar. Their image can be
|
|
|
1223 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
|
|
|
1224 @code{text}, and @code{subwindow}.
|
|
|
1225
|
|
|
1226 @item
|
|
|
1227 @code{pointer} glyphs can be used to specify the mouse pointer. Their
|
|
|
1228 image can be instantiated as @code{pointer}.
|
|
|
1229
|
|
|
1230 @item
|
|
|
1231 @code{icon} glyphs can be used to specify the icon used when a frame is
|
|
|
1232 iconified. Their image can be instantiated as @code{mono-pixmap} and
|
|
|
1233 @code{color-pixmap}.
|
|
|
1234 @end itemize
|
|
|
1235
|
|
|
1236 @defun glyph-type glyph
|
|
|
1237 This function returns the type of the given glyph. The return value
|
|
|
1238 will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}.
|
|
|
1239 @end defun
|
|
|
1240
|
|
|
1241 @defun valid-glyph-type-p glyph-type
|
|
|
1242 Given a @var{glyph-type}, this function returns non-@code{nil} if it is
|
|
|
1243 valid.
|
|
|
1244 @end defun
|
|
|
1245
|
|
|
1246 @defun glyph-type-list
|
|
|
1247 This function returns a list of valid glyph types.
|
|
|
1248 @end defun
|
|
|
1249
|
|
|
1250 @defun buffer-glyph-p object
|
|
|
1251 This function returns non-@code{nil} if @var{object} is a glyph of type
|
|
|
1252 @code{buffer}.
|
|
|
1253 @end defun
|
|
|
1254
|
|
|
1255 @defun icon-glyph-p object
|
|
|
1256 This function returns non-@code{nil} if @var{object} is a glyph of type
|
|
|
1257 @code{icon}.
|
|
|
1258 @end defun
|
|
|
1259
|
|
|
1260 @defun pointer-glyph-p object
|
|
|
1261 This function returns non-@code{nil} if @var{object} is a glyph of type
|
|
|
1262 @code{pointer}.
|
|
|
1263 @end defun
|
|
|
1264
|
|
|
1265 @node Mouse Pointer
|
|
|
1266 @section Mouse Pointer
|
|
|
1267 @cindex mouse cursor
|
|
|
1268 @cindex cursor (mouse)
|
|
|
1269 @cindex pointer (mouse)
|
|
|
1270 @cindex mouse pointer
|
|
|
1271
|
|
|
1272 The shape of the mouse pointer when over a particular section of a frame
|
|
|
1273 is controlled using various glyph variables. Since the image of a glyph
|
|
|
1274 is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
|
|
|
1275 or per-device basis.
|
|
|
1276
|
|
|
1277 You should use @code{set-glyph-image} to set the following variables,
|
|
|
1278 @emph{not} @code{setq}.
|
|
|
1279
|
|
|
1280 @defvr Glyph text-pointer-glyph
|
|
|
1281 This variable specifies the shape of the mouse pointer when over text.
|
|
|
1282 @end defvr
|
|
|
1283
|
|
|
1284 @defvr Glyph nontext-pointer-glyph
|
|
|
1285 This variable specifies the shape of the mouse pointer when over a
|
|
|
1286 buffer, but not over text. If unspecified in a particular domain,
|
|
|
1287 @code{text-pointer-glyph} is used.
|
|
|
1288 @end defvr
|
|
|
1289
|
|
|
1290 @defvr Glyph modeline-pointer-glyph
|
|
|
1291 This variable specifies the shape of the mouse pointer when over the modeline.
|
|
|
1292 If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
|
|
|
1293 @end defvr
|
|
|
1294
|
|
|
1295 @defvr Glyph selection-pointer-glyph
|
|
|
1296 This variable specifies the shape of the mouse pointer when over a
|
|
|
1297 selectable text region. If unspecified in a particular domain,
|
|
|
1298 @code{text-pointer-glyph} is used.
|
|
|
1299 @end defvr
|
|
|
1300
|
|
|
1301 @defvr Glyph gc-pointer-glyph
|
|
|
1302 This variable specifies the shape of the mouse pointer when a garbage
|
|
|
1303 collection is in progress. If the selected window is on a window system
|
|
|
1304 and this glyph specifies a value (i.e. a pointer image instance) in the
|
|
|
1305 domain of the selected window, the pointer will be changed as specified
|
|
|
1306 during garbage collection. Otherwise, a message will be printed in the
|
|
|
1307 echo area, as controlled by @code{gc-message}.
|
|
|
1308 @end defvr
|
|
|
1309
|
|
|
1310 @defvr Glyph busy-pointer-glyph
|
|
|
1311 This variable specifies the shape of the mouse pointer when XEmacs is busy.
|
|
|
1312 If unspecified in a particular domain, the pointer is not changed
|
|
|
1313 when XEmacs is busy.
|
|
|
1314 @end defvr
|
|
|
1315
|
|
|
1316 @defvr Glyph menubar-pointer-glyph
|
|
|
1317 This variable specifies the shape of the mouse pointer when over the
|
|
|
1318 menubar. If unspecified in a particular domain, the
|
|
|
1319 window-system-provided default pointer is used.
|
|
|
1320 @end defvr
|
|
|
1321
|
|
|
1322 @defvr Glyph scrollbar-pointer-glyph
|
|
|
1323 This variable specifies the shape of the mouse pointer when over a
|
|
|
1324 scrollbar. If unspecified in a particular domain, the
|
|
|
1325 window-system-provided default pointer is used.
|
|
|
1326 @end defvr
|
|
|
1327
|
|
|
1328 @defvr Glyph toolbar-pointer-glyph
|
|
|
1329 This variable specifies the shape of the mouse pointer when over a
|
|
|
1330 toolbar. If unspecified in a particular domain,
|
|
|
1331 @code{nontext-pointer-glyph} is used.
|
|
|
1332 @end defvr
|
|
|
1333
|
|
|
1334 Internally, these variables are implemented in
|
|
|
1335 @code{default-mouse-motion-handler}, and thus only take effect when the
|
|
|
1336 mouse moves. That function calls @code{set-frame-pointer}, which sets
|
|
|
1337 the current mouse pointer for a frame.
|
|
|
1338
|
|
|
1339 @defun set-frame-pointer frame image-instance
|
|
|
1340 This function sets the mouse pointer of @var{frame} to the given pointer
|
|
|
1341 image instance. You should not call this function directly.
|
|
|
1342 (If you do, the pointer will change again the next time the mouse moves.)
|
|
|
1343 @end defun
|
|
|
1344
|
|
|
1345 @node Redisplay Glyphs
|
|
|
1346 @section Redisplay Glyphs
|
|
|
1347
|
|
|
1348 @defvr Glyph truncation-glyph
|
|
|
1349 This variable specifies what is displayed at the end of truncated lines.
|
|
|
1350 @end defvr
|
|
|
1351
|
|
|
1352 @defvr Glyph continuation-glyph
|
|
|
1353 This variable specifies what is displayed at the end of wrapped lines.
|
|
|
1354 @end defvr
|
|
|
1355
|
|
|
1356 @defvr Glyph octal-escape-glyph
|
|
|
1357 This variable specifies what to prefix character codes displayed in octal
|
|
|
1358 with.
|
|
|
1359 @end defvr
|
|
|
1360
|
|
|
1361 @defvr Glyph hscroll-glyph
|
|
|
1362 This variable specifies what to display at the beginning of horizontally
|
|
|
1363 scrolled lines.
|
|
|
1364 @end defvr
|
|
|
1365
|
|
|
1366 @defvr Glyph invisible-text-glyph
|
|
|
1367 This variable specifies what to use to indicate the presence of
|
|
|
1368 invisible text. This is the glyph that is displayed when an ellipsis is
|
|
|
1369 called for, according to @code{selective-display-ellipses} or
|
|
|
1370 @code{buffer-invisibility-spec}). Normally this is three dots (``...'').
|
|
|
1371 @end defvr
|
|
|
1372
|
|
|
1373 @defvr Glyph control-arrow-glyph
|
|
|
1374 This variable specifies what to use as an arrow for control characters.
|
|
|
1375 @end defvr
|
|
|
1376
|
|
|
1377 @node Subwindows
|
|
|
1378 @section Subwindows
|
|
|
1379
|
|
|
1380 Subwindows are not currently implemented.
|
|
|
1381
|
|
|
1382 @defun subwindowp object
|
|
|
1383 This function returns non-@code{nil} if @var{object} is a subwindow.
|
|
|
1384 @end defun
|
|
707
|
1385
|
|
|
1386 @node Glyph Examples
|
|
|
1387 @section Glyph Examples
|
|
|
1388
|
|
|
1389 For many applications, displaying graphics is a simple process: you
|
|
|
1390 create a glyph, and then you insert it into a buffer.
|
|
|
1391
|
|
|
1392 The easiest way to create a glyph is to use a file that contains a
|
|
|
1393 graphical image, such as a JPEG, TIFF, or PNG file:
|
|
|
1394
|
|
|
1395 @lisp
|
|
|
1396 ;; Create a glyph from a JPEG file:
|
|
|
1397 (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
|
|
|
1398 @end lisp
|
|
|
1399
|
|
|
1400 @lisp
|
|
|
1401 ;; Create a glyph from a XPM file:
|
|
|
1402 (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
|
|
|
1403 @end lisp
|
|
|
1404
|
|
|
1405 @lisp
|
|
|
1406 ;; Create a glyph from a PNG file:
|
|
|
1407 (setq foo (make-glyph [png :file "/tmp/file3.png"]))
|
|
|
1408 @end lisp
|
|
|
1409
|
|
|
1410 @lisp
|
|
|
1411 ;; Create a glyph from a TIFF file:
|
|
|
1412 (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
|
|
|
1413 @end lisp
|
|
|
1414
|
|
|
1415 The parameters passed to @code{make-glyph} are called "Image
|
|
|
1416 Specifiers", and can handle more image types than those shown above.
|
|
|
1417 You can also put the raw image data into a string (e.g., if you put the
|
|
|
1418 contents of a JPEG file into a string), and use that to create a glyph.
|
|
|
1419 @xref{Image Specifiers}, for more information.
|
|
|
1420
|
|
|
1421 @quotation
|
|
|
1422 @strong{Caution}: In order for XEmacs to read a particular graphics file
|
|
|
1423 format, support for that format must have been compiled into XEmacs.
|
|
|
1424 It's possible, although somewhat unlikely, for XEmacs to have been
|
|
|
1425 compiled without support for any of the various graphics file formats.
|
|
|
1426 To see what graphics formats your particular version of XEmacs supports,
|
|
|
1427 use @kbd{M-x describe-installation}.
|
|
|
1428
|
|
|
1429 To programmatically query whether or not a particular file format is
|
|
|
1430 supported, you can use the @code{featurep} function, with one of:
|
|
|
1431 @code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm},
|
|
|
1432 @code{png}, or @code{xface}. For an up-to-date list, @ref{Image
|
|
|
1433 Specifiers}. Example:
|
|
|
1434
|
|
|
1435 @example
|
|
|
1436 ;; Returns `t' if TIFF is supported:
|
|
|
1437 (featurep 'tiff)
|
|
|
1438 @end example
|
|
|
1439
|
|
|
1440 Another example is:
|
|
|
1441
|
|
|
1442 @example
|
|
|
1443 ;; Returns a list of `t' or `nil', depending on whether or not the
|
|
|
1444 ;; corresponding feature is supported:
|
|
|
1445 (mapcar #'(lambda (format-symbol) (featurep format-symbol))
|
|
|
1446 '(gif tiff jpeg xpm png))
|
|
|
1447 @end example
|
|
|
1448
|
|
|
1449 @end quotation
|
|
|
1450
|
|
|
1451 Once you have a glyph, you can then insert it into a buffer. Example:
|
|
|
1452
|
|
|
1453 @lisp
|
|
|
1454 ;; Use this function to insert a glyph at the left edge of point in the
|
|
|
1455 ;; current buffer. Any existing glyph at this location is replaced.
|
|
|
1456 (defun insert-glyph (gl)
|
|
|
1457 "Insert a glyph at the left edge of point."
|
|
1137
|
1458 (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen
|
|
707
|
1459 ;; to (hopefully) not conflict with any
|
|
|
1460 ;; other properties. Change it if
|
|
|
1461 ;; necessary.
|
|
|
1462 extent )
|
|
|
1463 ;; First, check to see if one of our extents already exists at
|
|
|
1464 ;; point. For ease-of-programming, we are creating and using our
|
|
|
1465 ;; own extents (multiple extents are allowed to exist/overlap at the
|
|
|
1466 ;; same point, and it's quite possible for other applications to
|
|
|
1467 ;; embed extents in the current buffer without your knowledge).
|
|
|
1468 ;; Basically, if an extent, with the property stored in "prop",
|
|
|
1469 ;; exists at point, we assume that it is one of ours, and we re-use
|
|
|
1470 ;; it (this is why it is important for the property stored in "prop"
|
|
|
1471 ;; to be unique, and only used by us).
|
|
|
1472 (if (not (setq extent (extent-at (point) (current-buffer) prop)))
|
|
|
1473 (progn
|
|
|
1474 ;; If an extent does not already exist, create a zero-length
|
|
|
1475 ;; extent, and give it our special property.
|
|
|
1476 (setq extent (make-extent (point) (point) (current-buffer)))
|
|
|
1477 (set-extent-property extent prop t)
|
|
|
1478 ))
|
|
|
1479 ;; Display the glyph by storing it as the extent's "begin-glyph".
|
|
|
1480 (set-extent-property extent 'begin-glyph gl)
|
|
|
1481 ))
|
|
|
1482
|
|
|
1483 ;; You can then use this function like:
|
|
|
1484 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
|
|
|
1485 ;; This will insert the glyph at point.
|
|
|
1486
|
|
|
1487 ;; Here's an example of how to insert two glyphs side-by-side, at point
|
|
|
1488 ;; (using the above code):
|
|
|
1489 (progn
|
|
|
1490 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
|
|
|
1491 ;; Create a new extent at point. We can't simply call "insert-glyph",
|
|
|
1492 ;; as "insert-glyph" will simply replace the first glyph with the
|
|
|
1493 ;; second.
|
|
|
1494 (setq extent (make-extent (point) (point) (current-buffer)))
|
|
|
1495 ;; Here, we're only setting the 'myimage property in case we need
|
|
|
1496 ;; to later identify/locate/reuse this particular extent.
|
|
|
1497 (set-extent-property extent 'myimage t)
|
|
|
1498 (set-extent-property extent 'begin-glyph
|
|
|
1499 (make-glyph [jpeg :file "/tmp/file2.jpg"]))
|
|
|
1500 )
|
|
|
1501
|
|
|
1502 @end lisp
|
|
|
1503
|
|
|
1504 Here are the gory details:
|
|
|
1505
|
|
|
1506 @itemize @bullet
|
|
|
1507
|
|
|
1508 @item
|
|
|
1509 Glyphs are displayed by attaching them to extents (see @ref{Extents}),
|
|
|
1510 either to the beginning or the end of extents.
|
|
|
1511
|
|
|
1512 Note that extents can be used for many things, and not just for
|
|
|
1513 displaying images (although, in the above example, we are creating our
|
|
|
1514 own extent for the sole purpose of displaying an image). Also, note
|
|
|
1515 that multiple extents are allowed to exist at the same position, and
|
|
|
1516 they can overlap.
|
|
|
1517
|
|
|
1518 @item
|
|
|
1519 Glyphs are often displayed inside the text area (alongside text). This
|
|
|
1520 is the default.
|
|
|
1521
|
|
|
1522 Although glyphs can also be displayed in the margins, how to do this
|
|
|
1523 will not be described here. For more information on this, see
|
|
|
1524 @ref{Annotation Basics} (look for information on "layout types") and
|
|
|
1525 @ref{Extent Properties} (look for @code{begin-glyph-layout} and
|
|
|
1526 @code{end-glyph-layout}).
|
|
|
1527
|
|
|
1528 @item
|
|
|
1529 The easiest way to insert a glyph into text is to create a zero-length
|
|
|
1530 extent at the point where you want the glyph to appear.
|
|
|
1531
|
|
|
1532 Note that zero-length extents are attached to the character to the
|
|
|
1533 right of the extent; deleting this character will also delete the extent.
|
|
|
1534
|
|
|
1535 @item
|
|
|
1536 It's often a good idea to assign a unique property to the newly-created
|
|
|
1537 extent, in case you later want to locate it, and replace any existing
|
|
|
1538 glyph with a different one (or just delete the existing one). In the
|
|
|
1539 above example, we are using "myimage" as our (hopefully) unique property
|
|
|
1540 name.
|
|
|
1541
|
|
|
1542 If you need to locate all of the extents, you'll have to use functions
|
|
|
1543 like @code{extent-list} or @code{next-extent}, or provide additional
|
|
|
1544 parameters to the @code{extent-at} function. Assigning a unique
|
|
|
1545 property to the extent makes it easy to locate your extents; for
|
|
|
1546 example, @code{extent-list} can return only those extents with a
|
|
|
1547 particular property. @xref{Finding Extents}, and @ref{Mapping Over
|
|
|
1548 Extents}, for more information.
|
|
|
1549
|
|
|
1550 @item
|
|
|
1551 Glyphs are displayed by assigning then to the @code{begin-glyph} or
|
|
|
1552 @code{end-glyph} property of the extent. For zero-length extents, it
|
|
|
1553 doesn't really matter if you assign the glyph to the @code{begin-glyph}
|
|
|
1554 or @code{end-glyph} property, as they are both at the same location;
|
|
|
1555 however, for non-zero-length extents (extents that cover one or more
|
|
|
1556 characters of text), it does matter which one you use.
|
|
|
1557
|
|
|
1558 Assigning @code{nil} to the @code{begin-glyph} or @code{end-glyph}
|
|
|
1559 property will delete any existing glyph. In this case, you may also
|
|
|
1560 want to delete the extent, assuming that the extent is used for no other
|
|
|
1561 purpose.
|
|
|
1562
|
|
|
1563 @item
|
|
|
1564 If you happen to insert two glyphs, side-by-side, note that the example
|
|
|
1565 @code{insert-glyph} function will have trouble, if it's again used at
|
|
|
1566 the same point (it can only locate one of the two extents).
|
|
|
1567 @xref{Finding Extents}, and @ref{Mapping Over Extents}, for more
|
|
|
1568 information on locating extents in a buffer.
|
|
|
1569
|
|
|
1570 @item
|
|
|
1571 Among other things, glyphs provide a way of displaying graphics
|
|
|
1572 alongside text. Note, however, that glyphs only provide a way of
|
|
|
1573 displaying graphics; glyphs are not actually part of the text, and are
|
|
|
1574 only displayed alongside the text. If you save the text in the buffer,
|
|
|
1575 the graphics are not saved. The low-level glyph code does not provide a
|
|
|
1576 way of saving graphics with the text. If you need to save graphics and
|
|
|
1577 text, you have to write your own code to do this, and this topic is
|
|
|
1578 outside the scope of this discussion.
|
|
|
1579
|
|
|
1580 @end itemize
|
