1 ;;; glyphs.el --- Lisp interface to C glyphs
3 ;; Copyright (C) 1994, 1997 Free Software Foundation, Inc.
4 ;; Copyright (C) 1995, 1996, 2000 Ben Wing.
6 ;; Author: Chuck Thompson <cthomp@cs.uiuc.edu>, Ben Wing <ben@xemacs.org>
7 ;; Maintainer: XEmacs Development Team
8 ;; Keywords: extensions, internal, dumped
10 ;; This file is part of XEmacs.
12 ;; XEmacs is free software; you can redistribute it and/or modify it
13 ;; under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation; either version 2, or (at your option)
17 ;; XEmacs is distributed in the hope that it will be useful, but
18 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 ;; General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with XEmacs; see the file COPYING. If not, write to the
24 ;; Free Software Foundation, 59 Temple Place - Suite 330,
25 ;; Boston, MA 02111-1307, USA.
27 ;;; Synched up with: Not in FSF.
31 ;; Prototype created 1995 by Chuck Thompson.
32 ;; Completely rewritten by Ben Wing, 1995.
33 ;; Various cleanups (esp. doc strings) by Ben Wing, May 2000.
37 ;; This file is dumped with XEmacs.
41 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; image specifiers
43 (defun make-image-specifier (spec-list)
44 "Return a new `image' specifier object with the specification list SPEC-LIST.
45 SPEC-LIST can be a list of specifications (each of which is a cons of a
46 locale and a list of instantiators), a single instantiator, or a list
47 of instantiators. See `make-specifier' for more information about
50 An image specifier is used for images (pixmaps, widgets and the like).
51 It is used to describe the actual image in a glyph. It is instanced
52 as an image-instance. Note that \"image\" as used in XEmacs does not
53 actually refer to what the term \"image\" normally means (a picture,
54 e.g. in .GIF or .JPG format, and called a \"pixmap\" in XEmacs), but
55 includes all types of graphical elements, including pixmaps, widgets
56 \(buttons, sliders, text fields, etc.) and even strings of text.
58 Note that, in practice, you rarely, if ever, need to actually create
59 an image specifier! (The function `make-image-specifier' exists mainly
60 for completeness.) Pretty much the only use for image specifiers is to
61 control how glyphs are displayed, and the image specifier associated
62 with a glyph (the `image' property of a glyph) is created
63 automatically when a glyph is created (see `make-glyph') and need not
64 \(and cannot, for that matter) ever be changed. In fact, the design
65 decision to create a separate image specifier type, rather than make
66 glyphs themselves be specifiers, is debatable -- the other properties
67 of glyphs are rarely used and could conceivably have been incorporated
68 into the glyph's instantiator. The rarely used glyph types (buffer,
69 pointer, icon) could also have been incorporated into the instantiator.
71 Image instantiators come in many formats: `xbm', `xpm', `gif', `jpeg',
72 etc. This describes the format of the data describing the image. The
73 resulting image instances also come in many types -- `mono-pixmap',
74 `color-pixmap', `text', `pointer', etc. This refers to the behavior of
75 the image and the sorts of places it can appear. (For example, a
76 color-pixmap image has fixed colors specified for it, while a
77 mono-pixmap image comes in two unspecified shades \"foreground\" and
78 \"background\" that are determined from the face of the glyph or
79 surrounding text; a text image appears as a string of text and has an
80 unspecified foreground, background, and font; a pointer image behaves
81 like a mono-pixmap image but can only be used as a mouse pointer
82 \[mono-pixmap images cannot be used as mouse pointers]; etc.) It is
83 important to keep the distinction between image instantiator format and
84 image instance type in mind. Typically, a given image instantiator
85 format can result in many different image instance types (for example,
86 `xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
87 whereas `cursor-font' can be instanced only as `pointer'), and a
88 particular image instance type can be generated by many different
89 image instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
92 See `make-image-instance' for a more detailed discussion of image
95 An image instantiator should be a string or a vector of the form
97 [FORMAT :KEYWORD VALUE ...]
99 i.e. a format symbol followed by zero or more alternating keyword-value
100 pairs. FORMAT should be one of
103 Don't display anything; no keywords are valid for this.
104 Can only be instanced as `nothing'.
106 Display this image as a text string. Can only be instanced
107 as `text', although support for instancing as `mono-pixmap'
108 and `color-pixmap' should be added.
110 Display this image as a text string, with replaceable fields;
111 not currently implemented. (It is, instead, equivalent to `string'.)
113 An X bitmap; only if X or MS Windows support was compiled into this
114 XEmacs. Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
116 An XPM pixmap; only if XPM support was compiled into this XEmacs.
117 Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
119 An X-Face bitmap, used to encode people's faces in e-mail messages;
120 only if X-Face support was compiled into this XEmacs. Can be
121 instanced as `mono-pixmap', `color-pixmap', or `pointer'.
123 A GIF87 or GIF89 image; only if GIF support was compiled into this
124 XEmacs. NOTE: only the first frame of animated gifs will be displayed.
125 Can be instanced as `color-pixmap'.
127 A JPEG image; only if JPEG support was compiled into this XEmacs.
128 Can be instanced as `color-pixmap'.
130 A PNG image; only if PNG support was compiled into this XEmacs.
131 Can be instanced as `color-pixmap'.
133 A TIFF image; only if TIFF support was compiled into this XEmacs.
134 Can be instanced as `color-pixmap'.
136 A MS Windows BMP image; only if MS Windows support was compiled into
137 this XEmacs. Can be instanced as `color-pixmap'.
139 One of the standard cursor-font names, such as \"watch\" or
140 \"right_ptr\" under X. Under X, this is, more specifically, any
141 of the standard cursor names from appendix B of the Xlib manual
142 [also known as the file <X11/cursorfont.h>] minus the XC_ prefix.
143 On other window systems, the valid names will be specific to the
144 type of window system. Can only be instanced as `pointer'.
146 An MS Windows pointer resource. Specifies a resource to retrieve
147 directly from the system (an OEM resource) or from a file, particularly
148 an executable file. If the resource is to be retrieved from a file, use
149 :file and optionally :resource-id. Otherwise use :resource-id. Always
150 specify :resource-type to specify the type (cursor, bitmap or icon) of
151 the resource. Possible values for :resource-id are listed below. Can
152 be instanced as `pointer' or `color-pixmap'.
154 A glyph from a font; i.e. the name of a font, and glyph index into it
155 of the form \"FONT fontname index [[mask-font] mask-index]\".
156 Currently can only be instanced as `pointer', although this should
159 An embedded windowing system window. Can only be instanced as
162 A button widget; either a push button, radio button or toggle button.
163 Can only be instanced as `widget'.
165 A drop list of selectable items in a widget, for editing text.
166 Can only be instanced as `widget'.
168 A text editing widget. Can only be instanced as `widget'.
170 A static, text-only, widget; for displaying text. Can only be instanced
173 A widget for controlling the positioning of children underneath it.
174 Through the use of nested layouts, a widget hierarchy can be created
175 which can have the appearance of any standard dialog box or similar
176 arrangement; all of this is counted as one \"glyph\" and could appear
177 in many of the places that expect a single glyph. Can only be instanced
180 The native version of a layout widget. #### Document me better!
181 Can only be instanced as `widget'.
183 A sliding widget, for showing progress. Can only be instanced as
186 A tab widget; a series of user selectable tabs. Can only be instanced
189 A folding widget. Can only be instanced as `widget'.
191 A scrollbar widget. Can only be instanced as `widget'.
193 XEmacs tries to guess what format the data is in. If X support
194 exists, the data string will be checked to see if it names a filename.
195 If so, and this filename contains XBM or XPM data, the appropriate
196 sort of pixmap or pointer will be created. [This includes picking up
197 any specified hotspot or associated mask file.] Otherwise, if `pointer'
198 is one of the allowable image-instance types and the string names a
199 valid cursor-font name, the image will be created as a pointer.
200 Otherwise, the image will be displayed as text. If no X support
201 exists, the image will always be displayed as text. Can be instanced as
202 `mono-pixmap', `color-pixmap', `pointer', or `text'.
204 Inherit from the background-pixmap property of a face. Can only be
205 instanced as `mono-pixmap'.
207 The valid keywords are:
210 Inline data. For most formats above, this should be a string. For
211 XBM images, this should be a list of three elements: width, height, and
212 a string of bit data. This keyword is valid for all of the bitmap/pixmap
213 formats, as well as `string', `formatted-string', `font', `cursor-font',
216 Data is contained in a file. The value is the name of this file.
217 If both :data and :file are specified, the image is created from
218 what is specified in :data and the string in :file becomes the
219 value of the `image-instance-file-name' function when applied to
220 the resulting image-instance. This keyword is valid for all of the
221 bitmap/pixmap formats as well as `mswindows-resource'.
224 For `xbm', `xface', `cursor-font', `widget' and `font'. These keywords
225 allow you to explicitly specify foreground and background colors.
226 The argument should be anything acceptable to `make-color-instance'.
227 This will cause what would be a `mono-pixmap' to instead be colorized
228 as a two-color color-pixmap, and specifies the foreground and/or
229 background colors for a pointer instead of black and white.
231 For `xbm' and `xface'. This specifies a mask to be used with the
232 bitmap. The format is a list of width, height, and bits, like for
235 For `xbm' and `xface'. This specifies a file containing the mask data.
236 If neither a mask file nor inline mask data is given for an XBM image,
237 and the XBM image comes from a file, XEmacs will look for a mask file
238 with the same name as the image file but with \"Mask\" or \"msk\"
239 appended. For example, if you specify the XBM file \"left_ptr\"
240 [usually located in \"/usr/include/X11/bitmaps\"], the associated
241 mask file \"left_ptrmsk\" will automatically be picked up.
244 For `xbm' and `xface'. These keywords specify a hotspot if the image
245 is instantiated as a `pointer'. Note that if the XBM image file
246 specifies a hotspot, it will automatically be picked up if no
247 explicit hotspot is given.
249 Only for `xpm'. This specifies an alist that maps strings
250 that specify symbolic color names to the actual color to be used
251 for that symbolic color (in the form of a string or a color-specifier
252 object). If this is not specified, the contents of `xpm-color-symbols'
253 are used to generate the alist.
255 Only for `mswindows-resource'. This must be either an integer (which
256 directly specifies a resource number) or a string. Valid strings are
260 \"close\", \"uparrow\", \"dnarrow\", \"rgarrow\", \"lfarrow\",
261 \"reduce\", \"zoom\", \"restore\", \"reduced\", \"zoomd\",
262 \"restored\", \"uparrowd\", \"dnarrowd\", \"rgarrowd\", \"lfarrowd\",
263 \"mnarrow\", \"combo\", \"uparrowi\", \"dnarrowi\", \"rgarrowi\",
264 \"lfarrowi\", \"size\", \"btsize\", \"check\", \"checkboxes\", and
269 \"normal\", \"ibeam\", \"wait\", \"cross\", \"up\", \"sizenwse\",
270 \"sizenesw\", \"sizewe\", \"sizens\", \"sizeall\", and \"no\".
274 \"sample\", \"hand\", \"ques\", \"bang\", \"note\", and \"winlogo\".
276 Only for `mswindows-resource'. This must be a symbol, either `cursor',
277 `icon', or `bitmap', specifying the type of resource to be retrieved.
279 Only for `inherit'. This specifies the face to inherit from.
280 For widgets this also specifies the face to use for display. It defaults
283 Keywords accepted as menu item specs are also accepted by widgets.
284 These are `:selected', `:active', `:suffix', `:keys', `:style',
285 `:filter', `:config', `:included', `:key-sequence', `:accelerator',
286 `:label' and `:callback'.
288 If instead of a vector, the instantiator is a string, it will be
289 converted into a vector by looking it up according to the specs in the
290 `console-type-image-conversion-list' (q.v.) for the console type of
291 the domain (usually a window; sometimes a frame or device) over which
292 the image is being instantiated.
294 If the instantiator specifies data from a file, the data will be read
295 in at the time that the instantiator is added to the image (which may
296 be well before when the image is actually displayed), and the
297 instantiator will be converted into one of the inline-data forms, with
298 the filename retained using a :file keyword. This implies that the
299 file must exist when the instantiator is added to the image, but does
300 not need to exist at any other time (e.g. it may safely be a temporary
303 (make-specifier-and-init 'image spec-list))
305 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; glyphs
307 (defconst built-in-glyph-specifiers
308 '(image contrib-p baseline)
309 "A list of the built-in glyph properties that are specifiers.")
311 (defun glyph-property (glyph property &optional locale)
312 "Return GLYPH's value of PROPERTY in LOCALE.
314 If LOCALE is omitted, the GLYPH's actual value for PROPERTY will be
315 returned. For built-in properties, this will be a specifier object
316 of a type appropriate to the property (e.g. a font or color
317 specifier). For other properties, this could be anything.
319 If LOCALE is supplied, then instead of returning the actual value,
320 the specification(s) for the given locale or locale type will
321 be returned. This will only work if the actual value of
322 PROPERTY is a specifier (this will always be the case for built-in
323 properties, but not or not may apply to user-defined properties).
324 If the actual value of PROPERTY is not a specifier, this value
325 will simply be returned regardless of LOCALE.
327 The return value will be a list of instantiators (e.g. strings
328 specifying a font or color name), or a list of specifications, each
329 of which is a cons of a locale and a list of instantiators.
330 Specifically, if LOCALE is a particular locale (a buffer, window,
331 frame, device, or 'global), a list of instantiators for that locale
332 will be returned. Otherwise, if LOCALE is a locale type (one of
333 the symbols 'buffer, 'window, 'frame, 'device, 'device-class, or
334 'device-type), the specifications for all locales of that type will
335 be returned. Finally, if LOCALE is 'all, the specifications for all
336 locales of all types will be returned.
338 The specifications in a specifier determine what the value of
339 PROPERTY will be in a particular \"domain\" or set of circumstances,
340 which is typically a particular Emacs window along with the buffer
341 it contains and the frame and device it lies within. The value
342 is derived from the instantiator associated with the most specific
343 locale (in the order buffer, window, frame, device, and 'global)
344 that matches the domain in question. In other words, given a domain
345 (i.e. an Emacs window, usually), the specifier for PROPERTY will first
346 be searched for a specification whose locale is the buffer contained
347 within that window; then for a specification whose locale is the window
348 itself; then for a specification whose locale is the frame that the
349 window is contained within; etc. The first instantiator that is
350 valid for the domain (usually this means that the instantiator is
351 recognized by the device [i.e. the X server or TTY device] that the
352 domain is on. The function `glyph-property-instance' actually does
353 all this, and is used to determine how to display the glyph.
355 See `set-glyph-property' for the built-in property-names."
356 (check-argument-type 'glyphp glyph)
357 (let ((value (get glyph property)))
359 (or (memq property built-in-glyph-specifiers)
361 (setq value (specifier-specs value locale)))
364 (defun convert-glyph-property-into-specifier (glyph property)
365 "Convert PROPERTY on GLYPH into a specifier, if it's not already."
366 (check-argument-type 'glyphp glyph)
367 (let ((specifier (get glyph property)))
368 ;; if a user-property does not have a specifier but a
369 ;; locale was specified, put a specifier there.
370 ;; If there was already a value there, convert it to a
371 ;; specifier with the value as its 'global instantiator.
372 (if (not (specifierp specifier))
373 (let ((new-specifier (make-specifier 'generic)))
374 (if (or (not (null specifier))
375 ;; make sure the nil returned from `get' wasn't
376 ;; actually the value of the property
377 (null (get glyph property t)))
378 (add-spec-to-specifier new-specifier specifier))
379 (setq specifier new-specifier)
380 (put glyph property specifier)))))
382 (defun glyph-property-instance (glyph property
383 &optional domain default no-fallback)
384 "Return the instance of GLYPH's PROPERTY in the specified DOMAIN.
386 Under most circumstances, DOMAIN will be a particular window,
387 and the returned instance describes how the specified property
388 actually is displayed for that window and the particular buffer
389 in it. Note that this may not be the same as how the property
390 appears when the buffer is displayed in a different window or
391 frame, or how the property appears in the same window if you
392 switch to another buffer in that window; and in those cases,
393 the returned instance would be different.
395 DOMAIN defaults to the selected window if omitted.
397 DOMAIN can be a frame or device, instead of a window. The value
398 returned for a such a domain is used in special circumstances
399 when a more specific domain does not apply; for example, a frame
400 value might be used for coloring a toolbar, which is conceptually
401 attached to a frame rather than a particular window. The value
402 is also useful in determining what the value would be for a
403 particular window within the frame or device, if it is not
404 overridden by a more specific specification.
406 If PROPERTY does not name a built-in property, its value will
407 simply be returned unless it is a specifier object, in which case
408 it will be instanced using `specifier-instance'.
410 Optional arguments DEFAULT and NO-FALLBACK are the same as in
411 `specifier-instance'."
412 (check-argument-type 'glyphp glyph)
413 (let ((value (get glyph property)))
414 (if (specifierp value)
415 (setq value (specifier-instance value domain default no-fallback)))
418 (defun set-glyph-property (glyph property value &optional locale tag-set
420 "Change a property of a GLYPH.
422 NOTE: If you want to remove a property from a glyph, use
423 `remove-glyph-property' rather than attempting to set a value of nil
426 For built-in properties, the actual value of the property is a
427 specifier and you cannot change this; but you can change the
428 specifications within the specifier, and that is what this function
429 will do. For user-defined properties, you can use this function
430 to either change the actual value of the property or, if this value
431 is a specifier, change the specifications within it.
433 If PROPERTY is a built-in property, the specifications to be added to
434 this property can be supplied in many different ways:
436 -- If VALUE is a simple instantiator (e.g. a string naming a font or
437 color) or a list of instantiators, then the instantiator(s) will
438 be added as a specification of the property for the given LOCALE
439 (which defaults to 'global if omitted).
440 -- If VALUE is a list of specifications (each of which is a cons of
441 a locale and a list of instantiators), then LOCALE must be nil
442 (it does not make sense to explicitly specify a locale in this
443 case), and specifications will be added as given.
444 -- If VALUE is a specifier (as would be returned by `glyph-property'
445 if no LOCALE argument is given), then some or all of the
446 specifications in the specifier will be added to the property.
447 In this case, the function is really equivalent to
448 `copy-specifier' and LOCALE has the same semantics (if it is
449 a particular locale, the specification for the locale will be
450 copied; if a locale type, specifications for all locales of
451 that type will be copied; if nil or 'all, then all
452 specifications will be copied).
454 HOW-TO-ADD should be either nil or one of the symbols 'prepend,
455 'append, 'remove-tag-set-prepend, 'remove-tag-set-append, 'remove-locale,
456 'remove-locale-type, or 'remove-all. See `copy-specifier' and
457 `add-spec-to-specifier' for a description of what each of
458 these means. Most of the time, you do not need to worry about
459 this argument; the default behavior usually is fine.
461 In general, it is OK to pass an instance object (e.g. as returned
462 by `glyph-property-instance') as an instantiator in place of
463 an actual instantiator. In such a case, the instantiator used
464 to create that instance object will be used (for example, if
465 you set a font-instance object as the value of the 'font
466 property, then the font name used to create that object will
467 be used instead). If some cases, however, doing this
468 conversion does not make sense, and this will be noted in
469 the documentation for particular types of instance objects.
471 If PROPERTY is not a built-in property, then this function will
472 simply set its value if LOCALE is nil. However, if LOCALE is
473 given, then this function will attempt to add VALUE as the
474 instantiator for the given LOCALE, using `add-spec-to-specifier'.
475 If the value of the property is not a specifier, it will
476 automatically be converted into a 'generic specifier.
479 The following symbols have predefined meanings:
481 image The image used to display the glyph.
483 baseline Percent above baseline that glyph is to be
486 contrib-p Whether the glyph contributes to the
487 height of the line it's on.
489 face Face of this glyph (*not* a specifier)."
490 (check-argument-type 'glyphp glyph)
491 (if (memq property built-in-glyph-specifiers)
492 (set-specifier (get glyph property) value locale tag-set how-to-add)
494 ;; This section adds user defined properties.
496 (put glyph property value)
497 (convert-glyph-property-into-specifier glyph property)
498 (add-spec-to-specifier (get glyph property) value locale tag-set
502 (defun remove-glyph-property (glyph property &optional locale tag-set exact-p)
503 "Remove a property from a glyph.
504 For built-in properties, this is analogous to `remove-specifier'.
505 See `remove-specifier' for the meaning of the LOCALE, TAG-SET, and EXACT-P
507 (or locale (setq locale 'all))
508 (if (memq property built-in-glyph-specifiers)
509 (remove-specifier (glyph-property glyph property) locale tag-set exact-p)
511 (remprop glyph property)
512 (convert-glyph-property-into-specifier glyph property)
513 (remove-specifier (glyph-property glyph property) locale tag-set
516 (defun glyph-face (glyph)
517 "Return the face of GLYPH."
518 (glyph-property glyph 'face))
520 (defun set-glyph-face (glyph face)
521 "Change the face of GLYPH to FACE."
522 ; (interactive (glyph-interactive "face"))
523 (set-glyph-property glyph 'face face))
525 (defun glyph-image (glyph &optional locale)
526 "Return the image of GLYPH in LOCALE, or nil if it is unspecified.
528 LOCALE may be a locale (the instantiators for that particular locale
529 will be returned), a locale type (the specifications for all locales
530 of that type will be returned), 'all (all specifications will be
531 returned), or nil (the actual specifier object will be returned).
533 See `glyph-property' for more information."
534 (glyph-property glyph 'image locale))
536 (defun glyph-image-instance (glyph &optional domain default no-fallback)
537 "Return the instance of GLYPH's image in DOMAIN.
539 Normally DOMAIN will be a window or nil (meaning the selected window),
540 and an instance object describing how the image appears in that
541 particular window and buffer will be returned.
543 See `glyph-property-instance' for more information."
544 (glyph-property-instance glyph 'image domain default no-fallback))
546 (defun glyph-image-property (glyph prop &optional domain default no-fallback)
547 "Return property PROP of the instance of GLYPH's image in DOMAIN.
549 Normally DOMAIN will be a window or nil (meaning the selected window).
550 The value returned is dependent on the image instance type."
551 (image-instance-property
552 (glyph-image-instance glyph domain default no-fallback) prop))
554 (defun set-glyph-image (glyph spec &optional locale tag-set how-to-add)
555 "Change the image of GLYPH in LOCALE.
557 SPEC should be an instantiator (a string or vector; see
558 `make-image-specifier' for a description of possible values here),
559 a list of (possibly tagged) instantiators, an alist of specifications
560 (each mapping a locale to an instantiator list), or an image specifier
563 If SPEC is an alist, LOCALE must be omitted. If SPEC is a
564 specifier object, LOCALE can be a locale, a locale type, 'all,
565 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
566 specifies the locale under which the specified instantiator(s)
567 will be added, and defaults to 'global.
569 See `set-glyph-property' for more information."
570 ; (interactive (glyph-interactive "image"))
571 (set-glyph-property glyph 'image spec locale tag-set how-to-add))
573 (defun glyph-contrib-p (glyph &optional locale)
574 "Return whether GLYPH contributes to its line height.
576 LOCALE may be a locale (the instantiators for that particular locale
577 will be returned), a locale type (the specifications for all locales
578 of that type will be returned), 'all (all specifications will be
579 returned), or nil (the actual specifier object will be returned).
581 See `glyph-property' for more information."
582 (glyph-property glyph 'contrib-p locale))
584 (defun glyph-contrib-p-instance (glyph &optional domain default no-fallback)
585 "Return the instance of GLYPH's 'contrib-p property in DOMAIN.
587 Normally DOMAIN will be a window or nil (meaning the selected window),
588 and an instance object describing what the 'contrib-p property is in
589 that particular window and buffer will be returned.
591 See `glyph-property-instance' for more information."
592 (glyph-property-instance glyph 'contrib-p domain default no-fallback))
594 (defun set-glyph-contrib-p (glyph spec &optional locale tag-set how-to-add)
595 "Change the contrib-p property of GLYPH in LOCALE.
597 SPEC should be an instantiator (t or nil), a list of (possibly
598 tagged) instantiators, an alist of specifications (each mapping a
599 locale to an instantiator list), or a boolean specifier object.
601 If SPEC is an alist, LOCALE must be omitted. If SPEC is a
602 specifier object, LOCALE can be a locale, a locale type, 'all,
603 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
604 specifies the locale under which the specified instantiator(s)
605 will be added, and defaults to 'global.
607 See `set-glyph-property' for more information."
608 ; (interactive (glyph-interactive "contrib-p"))
609 (set-glyph-property glyph 'contrib-p spec locale tag-set how-to-add))
611 (defun glyph-baseline (glyph &optional locale)
612 "Return the baseline of GLYPH in LOCALE, or nil if it is unspecified.
614 LOCALE may be a locale (the instantiators for that particular locale
615 will be returned), a locale type (the specifications for all locales
616 of that type will be returned), 'all (all specifications will be
617 returned), or nil (the actual specifier object will be returned).
619 See `glyph-property' for more information."
620 (glyph-property glyph 'baseline locale))
622 (defun glyph-baseline-instance (glyph &optional domain default no-fallback)
623 "Return the instance of GLYPH's baseline in DOMAIN.
625 Normally DOMAIN will be a window or nil (meaning the selected window),
626 and an integer or nil (specifying the baseline in that particular
627 window and buffer) will be returned.
629 See `glyph-property-instance' for more information."
630 (glyph-property-instance glyph 'baseline domain default no-fallback))
632 (defun set-glyph-baseline (glyph spec &optional locale tag-set how-to-add)
633 "Change the baseline of GLYPH to SPEC in LOCALE.
635 SPEC should be an instantiator (an integer [a percentage above the
636 baseline of the line the glyph is on] or nil), a list of (possibly
637 tagged) instantiators, an alist of specifications (each mapping a
638 locale to an instantiator list), or a generic specifier object.
640 If SPEC is an alist, LOCALE must be omitted. If SPEC is a
641 specifier object, LOCALE can be a locale, a locale type, 'all,
642 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
643 specifies the locale under which the specified instantiator(s)
644 will be added, and defaults to 'global.
646 See `set-glyph-property' for more information."
647 ; (interactive (glyph-interactive "baseline"))
648 (set-glyph-property glyph 'baseline spec locale tag-set how-to-add))
650 (defun make-glyph (&optional spec-list type)
651 "Create a new glyph of type TYPE.
653 A glyph in XEmacs does NOT refer to a single unit of textual display (the
654 XEmacs term for this is \"rune\"), but rather is an object encapsulating
655 a graphical element, such as an image or widget (an element such as a
656 button or text field; \"widget\" is the term for this under X Windows,
657 and it's called a \"control\" under MS Windows). This graphical element
658 could appear in a buffer, a margin, a gutter, or a toolbar, or as a mouse
659 pointer or an icon, for example.
661 Creating a glyph using `make-glyph' does not specify *where* the glyph
662 will be used, but it does specify *what* the glyph will look like. In
663 particular, SPEC-LIST is used to specify this, and it's used to
664 initialize the glyph's `image' property, which is an image
665 specifier. (Note that \"image\" as used in the context of a glyph's
666 `image' property or in the terms \"image specifier\", \"image
667 instantiator\", or \"image instance\" does not refer to what people
668 normally think of as an image (which in XEmacs is called a
669 \"pixmap\"), but to any graphical element -- a pixmap, a widget, or
670 even a block of text, when used in the places that call for a glyph.)
671 The format of the SPEC-LIST is typically an image instantiator (a
672 string or a vector; see `make-image-specifier' for a detailed description
673 of the valid image instantiators), but can also be a list of such
674 instantiators (each one in turn is tried until an image is
675 successfully produced), a cons of a locale (frame, buffer, etc.) and
676 an instantiator, a list of such conses, or any other form accepted by
677 `canonicalize-spec-list'.
679 If you're not familiar with specifiers, you should be in order to
680 understand how glyphs work. The clearest introduction to specifiers
681 is in the Lispref manual, available under Info. (Choose
682 Help->Info->Info Contents on the menubar or type \\[info].) You can
683 also see `make-specifier' for a capsule summary. What's important to
684 keep in mind is that a specifier lets you set a different value for
685 any particular buffer, window, frame, device, or console. This allows
686 for a great deal of flexibility; in particular, only one global glyph
687 needs to exist for a particular purpose (e.g. the icon used to represent
688 an iconified frame, the mouse pointer used over particular areas of a
689 frame, etc.), and in these cases you do not create your own glyph, but
690 rather modify the existing one.
692 As well as using SPEC-LIST to initialize the glyph, you can set
693 specifications using `set-glyph-image'. Note that, due to a possibly
694 questionable historical design decision, a glyph itself is not
695 actually a specifier, but rather is an object containing an image
696 specifier (as well as other, seldom-used properties). Therefore, you
697 cannot set or access specifications for the glyph's image by directly
698 using `set-specifier', `specifier-instance' or the like on the glyph;
699 instead use them on `(glyph-image GLYPH)' or use the convenience
700 functions `set-glyph-image', `glyph-image-instance', and
703 Once you have created a glyph, you specify where it will be used as follows:
705 -- To insert a glyph into a buffer, create an extent in the buffer and then
706 use `set-extent-begin-glyph' or `set-extent-end-glyph' to set a glyph
707 to be displayed at the corresponding edge of the extent. (It is common
708 to create zero-width extents for this purpose.)
710 -- To insert a glyph into the left or right margin of a buffer, first
711 make sure the margin is visible by setting a value for the specifiers
712 `left-margin-width' or `right-margin-width'. (Not strictly necessary
713 when using margin glyphs with layout policy `whitespace'.) Then follow
714 the same procedure above for inserting a glyph in a buffer, and then
715 set a non-default layout policy for the glyph using
716 `set-extent-begin-glyph-layout' or `set-extent-end-glyph-layout'.
717 Alternatively, use the high-level annotations API (see
718 `make-annotation'). (In point of fact, you can also use the annotations
719 API for glyphs in a buffer, by setting a layout policy of `text'.)
721 -- To insert a glyph into the modeline, just put the glyph directly as
722 one of the modeline elements. (Unfortunately you can't currently
723 put a begin glyph or end glyph on one of the modeline extents --
726 -- To insert a glyph into a toolbar, specify it as part of a toolbar
727 instantiator (typically set on the specifier `default-toolbar').
728 See `default-toolbar' for more information. (Note that it is standard
729 practice to use a symbol in place of the glyph list in the toolbar
730 instantiator; the symbol is evalled to get the glyph list. This
731 facilitates both creating the toolbar instantiator and modifying
732 individual glyphs in a toolbar later on. For example, you can
733 change the way that the Mail toolbar button looks by modifying the
734 value of the variable `toolbar-mail-icon' (in general, `toolbar-*-icon')
735 and then calling `(set-specifier-dirty-flag default-toolbar)'.
736 (#### Unfortunately this doesn't quite work the way it should; the
737 change will appear in new frames, but not existing ones.
739 -- To insert a glyph into a gutter, create or modify a gutter instantiator
740 (typically set on the specifier `default-gutter'). Gutter instantiators
741 consist of strings or lists of strings, so to insert a glyph, create an
742 extent over the string, and use `set-extent-begin-glyph' or
743 `set-extent-end-glyph' to set a glyph to be displayed at the corresponding
744 edge of the extent, just like for glyphs in a buffer.
746 -- To use a glyph as the icon for a frame, you do not actually create a new
747 glyph; rather, you change the specifications for the existing glyph
748 `frame-icon-glyph'. (Remember that, because of the specifier nature of
749 glyphs, you can set different values for any particular buffer or frame.)
751 -- To use a glyph as the mouse pointer, in general you do not create a
752 new glyph, but rather you change the specifications of various existing
753 glyphs, such as `text-pointer-glyph' for the pointer used over text,
754 `modeline-pointer-glyph' for the pointer used over the modeline, etc.
755 Do an apropos over `*-pointer-glyph' to find all of them. (Note also
756 that you can temporarily set the mouse pointer to some specific shape
757 by using `set-frame-pointer', which takes an image instance, as obtained
758 from calling `glyph-image-instance' on a glyph of type `pointer' --
759 either one of the above-mentioned variables or one you created yourself.
760 (See below for what it means to create a glyph of type `pointer'.)
761 This pointer will last only until the next mouse motion event is
762 processed or certain other things happen, such as creating or deleting
763 a window. (In fact, the above-mentioned pointer glyph variables are
764 implemented as part of the default handler for mouse motion events.
765 If you want to customize this behavior, take a look at `mode-motion-hook',
766 or `mouse-motion-handler' if you really want to get low-level.)
768 -- To use a glyph to control the shape of miscellaneous redisplay effects
769 such as the truncation and continuation markers, set the appropriate
770 existing glyph variables, as for icons and pointers above. See
771 `continuation-glyph', `control-arrow-glyph', `hscroll-glyph',
772 `invisible-text-glyph', `octal-escape-glyph', and `truncation-glyph'.
773 See also `overlay-arrow-string', an odd redisplay leftover which can
774 be set to a glyph you created, and will cause the glyph to be displayed
775 on top of the text position specified in the marker stored in
776 `overlay-arrow-position'.
778 -- To use a glyph in a display table (i.e. to control the appearance of
779 any individual character), create the appropriate character glyphs
780 and then set a specification for the specifier `current-display-table',
781 which controls the appearance of characters. You can also set an
782 overriding display table for use with text displayed in a particular
783 face; see `set-face-display-table' and `make-display-table'.
784 #### Note: Display tables do not currently support general Mule
785 characters. They will be overhauled at some point to support this
786 and to provide other features required under Mule.
788 -- To use a glyph as the background pixmap of a face: Note that the
789 background pixmap of a face is actually an image specifier -- probably
790 the only place in XEmacs where an image specifier occurs outside of
791 a glyph. Similarly to how the glyph's image specifier works, you
792 don't create your own image specifier, but rather add specifications
793 to the existing one (using `set-face-background-pixmap'). Note that
794 the image instance that is generated in order to actually display the
795 background pixmap is of type `mono-pixmap', meaning that it's a two-color
796 image and the foreground and background of the image get filled in with
797 the corresponding colors from the face.
799 It is extremely rare that you will ever have to specify a value for TYPE,
800 which should be one of `buffer' (used for glyphs in an extent, the modeline,
801 the toolbar, or elsewhere in a buffer), `pointer' (used for the mouse-pointer),
802 or `icon' (used for a frame's icon), and defaults to `buffer'. The only cases
803 where it needs to be specified is when creating icon or pointer glyphs, and
804 in both cases the necessary glyphs have already been created at startup and
805 are accessed through the appropriate variables, e.g. `text-pointer-glyph'
806 (or in general, `*-pointer-glyph') and `frame-icon-glyph'."
807 (let ((glyph (make-glyph-internal type)))
808 (and spec-list (set-glyph-image glyph spec-list))
811 (defun buffer-glyph-p (object)
812 "Return t if OBJECT is a glyph of type `buffer'."
813 (and (glyphp object) (eq 'buffer (glyph-type object))))
815 (defun pointer-glyph-p (object)
816 "Return t if OBJECT is a glyph of type `pointer'."
817 (and (glyphp object) (eq 'pointer (glyph-type object))))
819 (defun icon-glyph-p (object)
820 "Return t if OBJECT is a glyph of type `icon'."
821 (and (glyphp object) (eq 'icon (glyph-type object))))
823 (defun make-pointer-glyph (&optional spec-list)
824 "Return a new `pointer-glyph' object with the specification list SPEC-LIST.
825 This is equivalent to calling `make-glyph', specifying a type of `pointer'.
826 See `make-glyph' for more information.
828 It is extremely unlikely that you will ever need to create a pointer glyph.
829 Instead, you probably want to be calling `set-glyph-image' on an existing
830 glyph, e.g. `text-pointer-glyph'."
831 (make-glyph spec-list 'pointer))
833 (defun make-icon-glyph (&optional spec-list)
834 "Return a new `icon-glyph' object with the specification list SPEC-LIST.
835 This is equivalent to calling `make-glyph', specifying a type of `icon'.
836 See `make-glyph' for more information.
838 It is extremely unlikely that you will ever need to create a icon glyph.
839 Instead, you probably want to be calling `set-glyph-image' on
841 (make-glyph spec-list 'icon))
843 (defun nothing-image-instance-p (object)
844 "Return t if OBJECT is an image instance of type `nothing'."
845 (and (image-instance-p object) (eq 'nothing (image-instance-type object))))
847 (defun text-image-instance-p (object)
848 "Return t if OBJECT is an image instance of type `text'."
849 (and (image-instance-p object) (eq 'text (image-instance-type object))))
851 (defun mono-pixmap-image-instance-p (object)
852 "Return t if OBJECT is an image instance of type `mono-pixmap'."
853 (and (image-instance-p object) (eq 'mono-pixmap
854 (image-instance-type object))))
856 (defun color-pixmap-image-instance-p (object)
857 "Return t if OBJECT is an image instance of type `color-pixmap'."
858 (and (image-instance-p object) (eq 'color-pixmap
859 (image-instance-type object))))
861 (defun pointer-image-instance-p (object)
862 "Return t if OBJECT is an image instance of type `pointer'."
863 (and (image-instance-p object) (eq 'pointer (image-instance-type object))))
865 (defun widget-image-instance-p (object)
866 "Return t if OBJECT is an image instance of type `widget'."
867 (and (image-instance-p object) (eq 'widget (image-instance-type object))))
869 (defun subwindow-image-instance-p (object)
870 "Return t if OBJECT is an image instance of type `subwindow'."
871 (and (image-instance-p object) (eq 'subwindow (image-instance-type object))))
873 ;;;;;;;;;; the built-in glyphs
875 (defvar text-pointer-glyph (make-pointer-glyph)
876 "*The shape of the mouse-pointer when over text.
877 This is a glyph; use `set-glyph-image' to change it.")
878 (set-glyph-face text-pointer-glyph 'pointer)
880 (defvar nontext-pointer-glyph (make-pointer-glyph)
881 "*The shape of the mouse-pointer when over a buffer, but not over text.
882 This is a glyph; use `set-glyph-image' to change it.
883 If unspecified in a particular domain, `text-pointer-glyph' is used.")
884 (set-glyph-face nontext-pointer-glyph 'pointer)
886 (defvar modeline-pointer-glyph (make-pointer-glyph)
887 "*The shape of the mouse-pointer when over the modeline.
888 This is a glyph; use `set-glyph-image' to change it.
889 If unspecified in a particular domain, `nontext-pointer-glyph' is used.")
890 (set-glyph-face modeline-pointer-glyph 'pointer)
892 (defvar selection-pointer-glyph (make-pointer-glyph)
893 "*The shape of the mouse-pointer when over a selectable text region.
894 This is a glyph; use `set-glyph-image' to change it.
895 If unspecified in a particular domain, `text-pointer-glyph' is used.")
896 (set-glyph-face selection-pointer-glyph 'pointer)
898 (defvar busy-pointer-glyph (make-pointer-glyph)
899 "*The shape of the mouse-pointer when XEmacs is busy.
900 This is a glyph; use `set-glyph-image' to change it.
901 If unspecified in a particular domain, the pointer is not changed
902 when XEmacs is busy.")
903 (set-glyph-face busy-pointer-glyph 'pointer)
905 (defvar toolbar-pointer-glyph (make-pointer-glyph)
906 "*The shape of the mouse-pointer when over a toolbar.
907 This is a glyph; use `set-glyph-image' to change it.
908 If unspecified in a particular domain, `nontext-pointer-glyph' is used.")
909 (set-glyph-face toolbar-pointer-glyph 'pointer)
911 (defvar divider-pointer-glyph (make-pointer-glyph)
912 "*The shape of the mouse-pointer when over a window divider.
913 This is a glyph; use `set-glyph-image' to change it.
914 If unspecified in a particular domain, `nontext-pointer-glyph' is used.")
915 (set-glyph-face divider-pointer-glyph 'pointer)
917 ;; The following three are in C.
918 (if (featurep 'menubar)
919 (set-glyph-face menubar-pointer-glyph 'pointer))
920 (if (featurep 'scrollbar)
921 (set-glyph-face scrollbar-pointer-glyph 'pointer))
922 (set-glyph-face gc-pointer-glyph 'pointer)
924 ;; Now add the magic access/set behavior.
926 (defun dontusethis-set-value-glyph-handler (sym args fun harg handler)
927 (error "Use `set-glyph-image' to set `%s'" sym))
928 (defun dontusethis-make-unbound-glyph-handler (sym args fun harg handler)
929 (error "Can't `makunbound' `%s'" sym))
930 (defun dontusethis-make-local-glyph-handler (sym args fun harg handler)
931 (error "Use `set-glyph-image' to make local values for `%s'" sym))
933 (defun define-constant-glyph (sym)
934 (dontusethis-set-symbol-value-handler
936 'dontusethis-set-value-glyph-handler)
937 (dontusethis-set-symbol-value-handler
939 'dontusethis-make-unbound-glyph-handler)
940 (dontusethis-set-symbol-value-handler
942 'dontusethis-make-local-glyph-handler)
943 ;; Make frame properties magically work with glyph variables.
944 (put sym 'const-glyph-variable t))
946 (define-constant-glyph 'text-pointer-glyph)
947 (define-constant-glyph 'nontext-pointer-glyph)
948 (define-constant-glyph 'modeline-pointer-glyph)
949 (define-constant-glyph 'selection-pointer-glyph)
950 (define-constant-glyph 'busy-pointer-glyph)
951 (define-constant-glyph 'gc-pointer-glyph)
952 (define-constant-glyph 'divider-pointer-glyph)
953 (define-constant-glyph 'toolbar-pointer-glyph)
954 (define-constant-glyph 'menubar-pointer-glyph)
955 (define-constant-glyph 'scrollbar-pointer-glyph)
957 (define-constant-glyph 'octal-escape-glyph)
958 (define-constant-glyph 'control-arrow-glyph)
959 (define-constant-glyph 'invisible-text-glyph)
960 (define-constant-glyph 'hscroll-glyph)
961 (define-constant-glyph 'truncation-glyph)
962 (define-constant-glyph 'continuation-glyph)
964 (define-constant-glyph 'frame-icon-glyph)
966 ;; backwards compatibility garbage
968 (defun dontusethis-old-pointer-shape-handler (sym args fun harg handler)
969 (let ((value (car args)))
971 (remove-specifier harg 'global)
972 (set-glyph-image (symbol-value harg) value))))
974 ;; It might or might not be garbage, but it's rude. Make these
975 ;; 'compatible instead of 'obsolete. -slb
976 (defun define-obsolete-pointer-glyph (old new)
977 (define-compatible-variable-alias old new)
978 (dontusethis-set-symbol-value-handler
979 old 'set-value 'dontusethis-old-pointer-shape-handler new))
981 ;;; (defvar x-pointer-shape nil)
982 (define-obsolete-pointer-glyph 'x-pointer-shape 'text-pointer-glyph)
984 ;;; (defvar x-nontext-pointer-shape nil)
985 (define-obsolete-pointer-glyph 'x-nontext-pointer-shape 'nontext-pointer-glyph)
987 ;;; (defvar x-mode-pointer-shape nil)
988 (define-obsolete-pointer-glyph 'x-mode-pointer-shape 'modeline-pointer-glyph)
990 ;;; (defvar x-selection-pointer-shape nil)
991 (define-obsolete-pointer-glyph 'x-selection-pointer-shape
992 'selection-pointer-glyph)
994 ;;; (defvar x-busy-pointer-shape nil)
995 (define-obsolete-pointer-glyph 'x-busy-pointer-shape 'busy-pointer-glyph)
997 ;;; (defvar x-gc-pointer-shape nil)
998 (define-obsolete-pointer-glyph 'x-gc-pointer-shape 'gc-pointer-glyph)
1000 ;;; (defvar x-toolbar-pointer-shape nil)
1001 (define-obsolete-pointer-glyph 'x-toolbar-pointer-shape 'toolbar-pointer-glyph)
1004 (defalias 'subwindow-xid 'image-instance-subwindow-id)
1005 (defalias 'subwindow-width 'image-instance-width)
1006 (defalias 'subwindow-height 'image-instance-height)
1007 ;;;;;;;;;; initialization
1009 (defun init-glyphs ()
1010 ;; initialize default image types
1012 (set-console-type-image-conversion-list 'x
1013 `(,@(if (featurep 'xpm) '(("\\.xpm\\'" [xpm :file nil] 2)))
1014 ("\\.xbm\\'" [xbm :file nil] 2)
1015 ,@(if (featurep 'xpm) '(("\\`/\\* XPM \\*/" [xpm :data nil] 2)))
1016 ,@(if (featurep 'xface) '(("\\`X-Face:" [xface :data nil] 2)))
1017 ,@(if (featurep 'gif) '(("\\.gif\\'" [gif :file nil] 2)
1018 ("\\`GIF8[79]" [gif :data nil] 2)))
1019 ,@(if (featurep 'jpeg) '(("\\.jpe?g\\'" [jpeg :file nil] 2)))
1020 ;; all of the JFIF-format JPEG's that I've seen begin with
1021 ;; the following. I have no idea if this is standard.
1022 ,@(if (featurep 'jpeg) '(("\\`\377\330\377\340\000\020JFIF"
1023 [jpeg :data nil] 2)))
1024 ,@(if (featurep 'png) '(("\\.png\\'" [png :file nil] 2)))
1025 ,@(if (featurep 'png) '(("\\`\211PNG" [png :data nil] 2)))
1026 ("" [string :data nil] 2)
1028 ;; #### this should really be formatted-string, not string but we
1029 ;; don't have it implemented yet
1031 ;; #define could also mean a bitmap as well as a version 1 XPM. Who
1032 ;; cares. We don't want the file contents getting converted to a
1033 ;; string in either case which is why the entry is there.
1036 (set-console-type-image-conversion-list
1038 '(("^#define" [string :data "[xpm]"])
1039 ("\\`X-Face:" [string :data "[xface]"])
1040 ("\\`/\\* XPM \\*/" [string :data "[xpm]"])
1041 ("\\`GIF87" [string :data "[gif]"])
1042 ("\\`\377\330\340\000\020JFIF" [string :data "[jpeg]"])
1043 ("" [string :data nil] 2)
1044 ;; this last one is here for pointers and icons and such --
1045 ;; strings are not allowed so they will be ignored.
1048 ;; finish initializing truncation glyph -- created internally
1049 ;; because it has a built-in bitmap
1050 (set-glyph-image truncation-glyph "$" 'global 'tty)
1052 ;; finish initializing continuation glyph -- created internally
1053 ;; because it has a built-in bitmap
1054 (set-glyph-image continuation-glyph "\\" 'global 'tty)
1056 ;; finish initializing hscroll glyph -- created internally
1057 ;; because it has a built-in bitmap
1058 (set-glyph-image hscroll-glyph "$" 'global 'tty)))
1060 (set-glyph-image octal-escape-glyph "\\")
1061 (set-glyph-image control-arrow-glyph "^")
1062 (set-glyph-image invisible-text-glyph " ...")
1063 ;; (set-glyph-image hscroll-glyph "$")
1065 (let ((face (make-face 'border-glyph
1066 "Truncation and continuation glyphs face")))
1067 (set-glyph-face continuation-glyph face)
1068 (set-glyph-face truncation-glyph face)
1069 (set-glyph-face hscroll-glyph face))
1071 ;; finish initializing xemacs logo -- created internally because it
1072 ;; has a built-in bitmap
1074 (set-glyph-image xemacs-logo
1076 (if emacs-beta-version
1080 (cond ((featurep 'xpm)
1081 (set-glyph-image frame-icon-glyph
1082 (concat "../etc/" "xemacs-icon.xpm")
1085 (set-glyph-image frame-icon-glyph
1086 (concat "../etc/" "xemacs-icon2.xbm")
1090 (set-glyph-image xemacs-logo
1091 "XEmacs <insert spiffy graphic logo here>"
1097 ;;; glyphs.el ends here.