11:44 p.m.
NOTE: This patch has been committed.
This is an attempt to update the documentation in glyphs.el to correspond
to what David has asked for.
BTW I notice that Stephen has independently done something similar (in fact
more extensive, probably) to the stuff in the Lisp manual -- luckily we
didn't both choose the same places at the same time!
Stephen -- I'd suggest incorporating some of these updates into the Lisp
manual, if possible.
Also, there's one thing that should be updated for 21.4: In the process of
updating the docs I discovered that GIF, JPEG, PNG and TIFF can be used as
mouse pointers under Windows but not under X or GTK. So I went and fixed
this under 21.5 -- to be committed soon. 21.4 won't have this, so maybe it
should document this limitation.
lisp/ChangeLog addition:
2005-02-21 Ben Wing <ben(a)xemacs.org>
* glyphs.el:
* glyphs.el (make-image-specifier):
* glyphs.el (glyph-property):
* glyphs.el (convert-glyph-property-into-specifier):
* glyphs.el (set-glyph-property):
* glyphs.el (glyph-image):
* glyphs.el (set-glyph-image):
* glyphs.el (glyph-contrib-p):
* glyphs.el (glyph-contrib-p-instance):
* glyphs.el (set-glyph-contrib-p):
* glyphs.el (glyph-baseline):
* glyphs.el (set-glyph-baseline):
* glyphs.el (make-glyph):
Update documentation of `make-glyph' and `make-image-specifier'
to more clearly document image instantiators and describe how
errors are handled in make-glyph. Also fix symbol references in
doc strings to use `symbol' format, not 'symbol.
build source patch:
Diff command: bash -ci "cvs-diff --show-c-function -no-changelog "
Files affected: lisp/glyphs.el
Index: lisp/glyphs.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/glyphs.el,v
retrieving revision 1.7
diff -u -p -r1.7 glyphs.el
--- lisp/glyphs.el 2001/04/12 18:21:21 1.7
+++ lisp/glyphs.el 2005/02/22 04:58:49
＠＠ -1,7 +1,7 ＠＠
;;; glyphs.el --- Lisp interface to C glyphs
;; Copyright (C) 1994, 1997 Free Software Foundation, Inc.
-;; Copyright (C) 1995, 1996, 2000 Ben Wing.
+;; Copyright (C) 1995, 1996, 2000, 2005 Ben Wing.
;; Author: Chuck Thompson <cthomp(a)cs.uiuc.edu>, Ben Wing <ben(a)xemacs.org>
;; Maintainer: XEmacs Development Team
＠＠ -47,149 +47,129 ＠＠ locale and a list of instantiators), a s
of instantiators. See `make-specifier' for more information about
specifiers.
-An image specifier is used for images (pixmaps, widgets and the like).
-It is used to describe the actual image in a glyph. It is instanced
-as an image-instance. Note that \"image\" as used in XEmacs does not
-actually refer to what the term \"image\" normally means (a picture,
-e.g. in .GIF or .JPG format, and called a \"pixmap\" in XEmacs), but
-includes all types of graphical elements, including pixmaps, widgets
-\(buttons, sliders, text fields, etc.) and even strings of text.
-
-Note that, in practice, you rarely, if ever, need to actually create
-an image specifier! (The function `make-image-specifier' exists mainly
-for completeness.) Pretty much the only use for image specifiers is to
-control how glyphs are displayed, and the image specifier associated
-with a glyph (the `image' property of a glyph) is created
-automatically when a glyph is created (see `make-glyph') and need not
-\(and cannot, for that matter) ever be changed. In fact, the design
-decision to create a separate image specifier type, rather than make
-glyphs themselves be specifiers, is debatable -- the other properties
-of glyphs are rarely used and could conceivably have been incorporated
-into the glyph's instantiator. The rarely used glyph types (buffer,
-pointer, icon) could also have been incorporated into the instantiator.
-
-Image instantiators come in many formats: `xbm', `xpm', `gif', `jpeg',
-etc. This describes the format of the data describing the image. The
-resulting image instances also come in many types -- `mono-pixmap',
-`color-pixmap', `text', `pointer', etc. This refers to the behavior of
-the image and the sorts of places it can appear. (For example, a
-color-pixmap image has fixed colors specified for it, while a
-mono-pixmap image comes in two unspecified shades \"foreground\" and
-\"background\" that are determined from the face of the glyph or
-surrounding text; a text image appears as a string of text and has an
-unspecified foreground, background, and font; a pointer image behaves
-like a mono-pixmap image but can only be used as a mouse pointer
-\[mono-pixmap images cannot be used as mouse pointers]; etc.) It is
-important to keep the distinction between image instantiator format and
-image instance type in mind. Typically, a given image instantiator
-format can result in many different image instance types (for example,
-`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
-whereas `cursor-font' can be instanced only as `pointer'), and a
-particular image instance type can be generated by many different
-image instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
-`gif', `jpeg', etc.).
-
-See `make-image-instance' for a more detailed discussion of image
-instance types.
+The main purpose of this doc string is to describe the possible formats for
+image instantiators, as given as an argument to `make-glyph' or
+`set-glyph-image'.
An image instantiator should be a string or a vector of the form
[FORMAT :KEYWORD VALUE ...]
i.e. a format symbol followed by zero or more alternating keyword-value
-pairs. FORMAT should be one of
+pairs. The vector form of an image instantiator explicitly specifies the
+format of the image and other relevant properties. The string form
+specifies only a filename or gives inline data of an unspecified format,
+and XEmacs must guess the actual format. Once it has done this, it
+internally converts the instantiator into the vector format. This is
+described in more detail below.
+
+Following is a list of the possible values for FORMAT. After each
+description, the allowable keywords for the format are listed in brackets,
+followed by the possible image instance types that can be generated from
+this format. (Image instance types will be discussed below.)
-'nothing
+`nothing'
Don't display anything; no keywords are valid for this.
- Can only be instanced as `nothing'.
-'string
- Display this image as a text string. Can only be instanced
- as `text', although support for instancing as `mono-pixmap'
- and `color-pixmap' should be added.
-'formatted-string
- Display this image as a text string, with replaceable fields;
- not currently implemented. (It is, instead, equivalent to `string'.)
-'xbm
- An X bitmap; only if X or MS Windows support was compiled into this
- XEmacs. Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
-'xpm
- An XPM pixmap; only if XPM support was compiled into this XEmacs.
- Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
-'xface
- An X-Face bitmap, used to encode people's faces in e-mail messages;
- only if X-Face support was compiled into this XEmacs. Can be
- instanced as `mono-pixmap', `color-pixmap', or `pointer'.
-'gif
+ [] (nothing)
+`string'
+ Display this image as a text string. Support for instantiating as
+ `mono-pixmap' and `color-pixmap' should probably be added.
+ [:data] (text)
+`formatted-string'
+ Display this image as a text string, with replaceable fields.
+ Not currently implemented -- it's treated like `string'.
+ [:data] (text)
+`gif'
A GIF87 or GIF89 image; only if GIF support was compiled into this
- XEmacs. NOTE: only the first frame of animated gifs will be displayed.
- Can be instanced as `color-pixmap'.
-'jpeg
+ XEmacs. NOTE: Only the first frame of animated gifs will be displayed.
+ [:data, :file] (color-pixmap, pointer)
+`jpeg'
A JPEG image; only if JPEG support was compiled into this XEmacs.
- Can be instanced as `color-pixmap'.
-'png
+ [:data, :file] (color-pixmap, pointer)
+`png'
A PNG image; only if PNG support was compiled into this XEmacs.
- Can be instanced as `color-pixmap'.
-'tiff
+ [:data, :file] (color-pixmap, pointer)
+`tiff'
A TIFF image; only if TIFF support was compiled into this XEmacs.
- Can be instanced as `color-pixmap'.
-'bmp
+ [:data, :file] (color-pixmap, pointer)
+`bmp'
A MS Windows BMP image; only if MS Windows support was compiled into
- this XEmacs. Can be instanced as `color-pixmap'.
-'cursor-font
- One of the standard cursor-font names, such as \"watch\" or
- \"right_ptr\" under X. Under X, this is, more specifically, any
+ this XEmacs.
+ [:data, :file] (color-pixmap, pointer)
+`xbm'
+ An X bitmap; exists if any window-system support was compiled into this
+ XEmacs.
+ [:data, :file, :foreground, :background, :mask-data, :mask-file,
+:hotspot-x, :hotspot-y] (mono-pixmap, color-pixmap, pointer)
+`xpm'
+ An XPM pixmap; only if XPM support was compiled into this XEmacs.
+ [:data, :file, :color-symbols] (mono-pixmap, color-pixmap, pointer)
+`xface'
+ An X-Face bitmap, used to encode people's faces in e-mail messages;
+ only if X-Face support was compiled into this XEmacs.
+ [:data, :file, :foreground, :background, :mask-data, :mask-file,
+:hotspot-x, :hotspot-y] (mono-pixmap, color-pixmap, pointer)
+`cursor-font'
+ X and GTK only. One of the standard cursor-font names, such as \"watch\"
+ or \"right_ptr\" under X. Under X, this is, more specifically, any
of the standard cursor names from appendix B of the Xlib manual
[also known as the file <X11/cursorfont.h>] minus the XC_ prefix.
On other window systems, the valid names will be specific to the
- type of window system. Can only be instanced as `pointer'.
-'mswindows-resource
+ type of window system.
+ [:data, :foreground, :background] (pointer)
+`mswindows-resource'
An MS Windows pointer resource. Specifies a resource to retrieve
directly from the system (an OEM resource) or from a file, particularly
an executable file. If the resource is to be retrieved from a file, use
:file and optionally :resource-id. Otherwise use :resource-id. Always
specify :resource-type to specify the type (cursor, bitmap or icon) of
- the resource. Possible values for :resource-id are listed below. Can
- be instanced as `pointer' or `color-pixmap'.
-'font
+ the resource. Possible values for :resource-id are listed below.
+ [:file, :resource-type, :resource-id] (pointer, color-pixmap)
+`font'
A glyph from a font; i.e. the name of a font, and glyph index into it
of the form \"FONT fontname index [[mask-font] mask-index]\".
- Currently can only be instanced as `pointer', although this should
+ Currently can only be instantiated as `pointer', although this should
probably be fixed.
-'subwindow
- An embedded windowing system window. Can only be instanced as
- `subwindow'.
-'button
+ [:data, :foreground, :background] (pointer)
+`subwindow'
+ An embedded windowing system window.
+ [:pixel-width, :pixel-height] (subwindow)
+`button'
A button widget; either a push button, radio button or toggle button.
- Can only be instanced as `widget'.
-'combo-box
+ [WIDGET-KEYWORDS, GUI-KEYWORDS, :image] (widget)
+`combo-box'
A drop list of selectable items in a widget, for editing text.
- Can only be instanced as `widget'.
-'edit-field
- A text editing widget. Can only be instanced as `widget'.
-'label
- A static, text-only, widget; for displaying text. Can only be instanced
- as `widget'.
-'layout
+ [GUI-KEYWORDS, :width, :height, :pixel-width, :face, :items] (widget)
+`edit-field'
+ A text editing widget.
+ [WIDGET-KEYWORDS, GUI-KEYWORDS] (widget)
+`label'
+ A static, text-only, widget; for displaying text.
+ [WIDGET-KEYWORDS, :descriptor] (widget)
+`layout'
A widget for controlling the positioning of children underneath it.
Through the use of nested layouts, a widget hierarchy can be created
which can have the appearance of any standard dialog box or similar
arrangement; all of this is counted as one \"glyph\" and could appear
- in many of the places that expect a single glyph. Can only be instanced
- as `widget'.
-'native-layout
+ in many of the places that expect a single glyph.
+ [WIDGET-KEYWORDS, GUI-KEYWORDS, :orientation, :justify, :vertically-justify,
+:horizontally-justify, :border, :margin-width, :items] (widget)
+`native-layout'
The native version of a layout widget. #### Document me better!
- Can only be instanced as `widget'.
-'progress-gauge
- A sliding widget, for showing progress. Can only be instanced as
- `widget'.
-'tab-control
- A tab widget; a series of user selectable tabs. Can only be instanced
- as `widget'.
-'tree-view
- A folding widget. Can only be instanced as `widget'.
-'scrollbar
- A scrollbar widget. Can only be instanced as `widget'.
-'autodetect
+ [WIDGET-KEYWORDS, GUI-KEYWORDS] (widget)
+`progress-gauge'
+ A sliding widget, for showing progress.
+ [WIDGET-KEYWORDS, GUI-KEYWORDS, :value] (widget)
+`tab-control'
+ A tab widget; a series of user selectable tabs.
+ [WIDGET-KEYWORDS, GUI-KEYWORDS, :orientation, :items] (widget)
+`tree-view'
+ A folding widget.
+ [WIDGET-KEYWORDS, GUI-KEYWORDS, :items] (widget)
+`scrollbar'
+ A scrollbar widget.
+ [GUI-KEYWORDS, :pixel-width, :face, :items] (widget)
+`autodetect'
XEmacs tries to guess what format the data is in. If X support
exists, the data string will be checked to see if it names a filename.
If so, and this filename contains XBM or XPM data, the appropriate
＠＠ -198,11 +178,11 ＠＠ pairs. FORMAT should be one of
is one of the allowable image-instance types and the string names a
valid cursor-font name, the image will be created as a pointer.
Otherwise, the image will be displayed as text. If no X support
- exists, the image will always be displayed as text. Can be instanced as
- `mono-pixmap', `color-pixmap', `pointer', or `text'.
-'inherit
- Inherit from the background-pixmap property of a face. Can only be
- instanced as `mono-pixmap'.
+ exists, the image will always be displayed as text.
+ [:data] (mono-pixmap, color-pixmap, pointer, text)
+`inherit'
+ Inherit from the background-pixmap property of a face.
+ [:face] (mono-pixmap)
The valid keywords are:
＠＠ -264,7 +244,7 ＠＠ The valid keywords are:
\"lfarrowi\", \"size\", \"btsize\", \"check\",
\"checkboxes\", and
\"btncorners\".
- -- For cursors:
+ -- For pointers:
\"normal\", \"ibeam\", \"wait\", \"cross\",
\"up\", \"sizenwse\",
\"sizenesw\", \"sizewe\", \"sizens\",
\"sizeall\", and \"no\".
＠＠ -273,18 +253,28 ＠＠ The valid keywords are:
\"sample\", \"hand\", \"ques\", \"bang\",
\"note\", and \"winlogo\".
:resource-type
- Only for `mswindows-resource'. This must be a symbol, either `cursor',
- `icon', or `bitmap', specifying the type of resource to be retrieved.
+ Only for `mswindows-resource'. This must be a symbol, either `cursor'
+ (i.e. pointer), `icon', or `bitmap', specifying the type of resource to
+ be retrieved.
:face
Only for `inherit'. This specifies the face to inherit from.
For widgets this also specifies the face to use for display. It defaults
to gui-element-face.
+:pixel-width, :pixel-height
+ Width and height of element, in pixels. For `subwindow', the values
+ must be integers. For widgets, the values can be integers or
+ expressions that evaluate to integers.
-Keywords accepted as menu item specs are also accepted by widgets.
+\[WIDGET-KEYWORDS] stands for the standard keywords accepted by widgets:
These are `:selected', `:active', `:suffix', `:keys', `:style',
`:filter', `:config', `:included', `:key-sequence', `:accelerator',
-`:label' and `:callback'.
+`:label', `:callback', `:initial-focus', and `:descriptor'.
+#### Document me.
+\[GUI-KEYWORDS] stands for keywords accepted by many widgets.
+These are `:width', `:height', `:pixel-width', `:pixel-height', and
`:face'.
+#### Document me.
+
If instead of a vector, the instantiator is a string, it will be
converted into a vector by looking it up according to the specs in the
`console-type-image-conversion-list' (q.v.) for the console type of
＠＠ -299,7 +289,148 ＠＠ the filename retained using a :file keyw
file must exist when the instantiator is added to the image, but does
not need to exist at any other time (e.g. it may safely be a temporary
file).
-"
+
+NOTE: In practice, you rarely, if ever, need to actually
+create an image specifier! (The function `make-image-specifier' exists
+mainly for completeness.) Pretty much the only use for image specifiers is
+to control how glyphs are displayed, and the image specifier associated
+with a glyph (the `image' property of a glyph) is created automatically
+when a glyph is created (see `make-glyph') and need not \(and cannot, for
+that matter) ever be changed. In fact, the design decision to create a
+separate image specifier type, rather than make glyphs themselves be
+specifiers, is debatable -- the other properties of glyphs are rarely used
+and could conceivably have been incorporated into the glyph's instantiator.
+The rarely used glyph types (buffer, pointer, icon) could also have been
+incorporated into the instantiator.
+
+An image specifier is used for images (pixmaps, widgets and the like). It
+is used to describe the actual image in a glyph. It is instantiated \(see
+`specifier-instance') as an image-instance. Note that \"image\" as used
in
+XEmacs does not actually refer to what the term \"image\" normally means (a
+picture, e.g. in .GIF or .JPG format, and called a \"pixmap\" in XEmacs),
+but includes all types of graphical elements, including pixmaps, widgets
+\(buttons, sliders, text fields, etc.) and even strings of text.
+
+There is an important distinction to be made between image instantiators
+and image instances, and \"image instantiator formats\" and \"image
+instance types\", analogous to the distinction between source and
+destination. An image instantiator describes the source data for an image.
+An image instance encapsulates the resulting window-system object used to
+display the image. Image instantiator formats are the formats of the
+source: This includes familiar and less-familiar graphics formats such as
+`gif', `jpeg', `png' and `xpm'; widget types such as `button',
`edit-field'
+and `combo-box'; and other beasts such as `string' (plain text, which could
+potentially behave like text when placed in a buffer, such as wrapping),
+`font' (a single character from a particular font, specified by the index
+into the font), etc. Image instance types are the (destination) types of
+the resulting image instance. Different image instance types correspond to
+fundamentally different appearance and behaviors for the resulting image,
+specifically:
+
+-- `color-pixmap' (a color image);
+-- `mono-pixmap' (a \"monochrome\" image, technically a two-color image
+ that comes in two unspecified shades \"foreground\" and
\"background\",
+ determined from the face [see `make-face'] of the glyph or surrounding
+ text);
+-- `text' (a string of text appearing somewhere in a buffer's text or
+ margins, which has an unspecified foreground, background, and font
+ derived from the surrounding text or other external property and which
+ behaves in many respects like an image but can wrap across the end of a
+ line to the beginning of the next);
+-- `pointer' (the mouse pointer for a window; this is a combination of a
+ rectangular pixmap image, a monochrome mask that specifies the
+ transparency of the image [i.e. in which places the underlying screen
+ image can show through, and how much of it], and a \"hotspot\" that
+ indicates which pixel in the pointer's image is considered the actual
+ pointer location -- for example, this will be located near the tip of
+ an arrow, in the middle of a crosshairs, somewhere along an i-beam, etc.);
+-- `widget' (a window-system object or \"widget\" that interacts with the
+ user, such as a button, edit-field or combo-box);
+-- `subwindow' (a rectangular area that another program can draw into);
+-- `nothing' (no display).
+
+There is not a one-to-one mapping between source (image instantiator)
+formats and destination (image instance) types. For example, the source
+format `xpm' can generate the image instance types `color-pixmap',
+`mono-pixmap', or `pointer', and the image instance type `color-pixmap' can
+be generated by any of `gif', `jpeg', `png', `tiff', `xpm', `xbm'
and
+`xface'.
+
+In general, the user or programmer specifies the image instantiator format,
+while the appropriate image instance type is determined automatically by
+XEmacs from the image instantiator format, from the data in the
+instantiator and from the particular situation the image (and the glyph
+that holds it) is being used in. (However, it's possible to explicitly
+create image instances and control their types; see `make-image-instance'.)
+For example, a glyph used to specify the shape of a mouse pointer can only
+result in `pointer'-type image instances, and a glyph used for an icon can
+only result in `color-pixmap' image instances. A glyph used in a buffer
+can potentially result in any image instance type except for `pointer', but
+particular instantiator formats have only a limited set of image instance
+types they will support. Here is an example of how the image instance type
+for an `xpm' instantiator (which can potentially support `color-pixmap',
+`mono-pixmap', or `pointer') is determined:
+
+1. If the glyph is being used for a mouse pointer (hence its `glyph-type'
+ is `pointer'), it can be instantiated only a `pointer'-type image instance.
+2. If the glyph is being used for an icon (hence its `glyph-type' is `icon'),
+ it can be instantiated only a `color-pixmap'-type image instance.
+3. Otherwise, the glyph is being used somewhere inside a frame (`glyph-type'
+ of `buffer') and any image instance type except `pointer' can be
+ supported. In this case, this means `color-pixmap' or `mono-pixmap'.
+ Which one will result depends on the particular data being processed,
+ since XPM images can specify whether they are color or mono.
+
+Note again that \"mono\" does *NOT* simply mean \"an image with two
+colors\". The latter image has two prespecified colors, e.g. red and blue
+or black and white, and will always appear with those colors, no matter
+what the context. A mono image has two *unspecified* colors, symbolically
+named \"foreground\" and \"background\", and the actual values for
those
+colors depends on context. A mono pixmap displayed among text will take
+its foreground and background from that of the text and hence blend in
+nicely; a two-color color pixmap won't do that.
+
+Note also that `color-pixmap' image instances can be generated from the
+supported pixmap formats that are inherently mono (i.e. `xbm' and `xface')
+by specifying :foreground and :background values.
+
+A table of the various image instantiator formats and the possible
+destination (image instance) types that can be generated from them is as
+follows:
+
+
+ color-pixmap mono-pixmap text pointer widget subwindow noth.
+-------------------------------------------------------------------------------
+nothing +
+string +
+formatted-string +
+xbm + + +
+xpm + + +
+xface + + +
+gif + +
+jpeg + +
+png + +
+tiff + +
+bmp + +
+cursor-font +
+mswindows-resource + +
+font +
+subwindow +
+button +
+combo-box +
+edit-field +
+label +
+layout +
+native-layout +
+progress-gauge +
+tab-control +
+tree-view +
+scrollbar +
+autodetect + + + +
+inherit +
+
+See `make-image-instance' for a more detailed discussion of image
+instance types."
(make-specifier-and-init 'image spec-list))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; glyphs
＠＠ -328,11 +459,11 ＠＠ The return value will be a list of insta
specifying a font or color name), or a list of specifications, each
of which is a cons of a locale and a list of instantiators.
Specifically, if LOCALE is a particular locale (a buffer, window,
- frame, device, or 'global), a list of instantiators for that locale
+ frame, device, or `global'), a list of instantiators for that locale
will be returned. Otherwise, if LOCALE is a locale type (one of
- the symbols 'buffer, 'window, 'frame, 'device, 'device-class, or
- 'device-type), the specifications for all locales of that type will
- be returned. Finally, if LOCALE is 'all, the specifications for all
+ the symbols `buffer', `window', `frame', `device', `device-class',
or
+ `device-type'), the specifications for all locales of that type will
+ be returned. Finally, if LOCALE is `all', the specifications for all
locales of all types will be returned.
The specifications in a specifier determine what the value of
＠＠ -340,7 +471,7 ＠＠ The specifications in a specifier determ
which is typically a particular Emacs window along with the buffer
it contains and the frame and device it lies within. The value
is derived from the instantiator associated with the most specific
- locale (in the order buffer, window, frame, device, and 'global)
+ locale (in the order buffer, window, frame, device, and `global')
that matches the domain in question. In other words, given a domain
(i.e. an Emacs window, usually), the specifier for PROPERTY will first
be searched for a specification whose locale is the buffer contained
＠＠ -368,7 +499,7 ＠＠ See `set-glyph-property' for the built-i
;; if a user-property does not have a specifier but a
;; locale was specified, put a specifier there.
;; If there was already a value there, convert it to a
- ;; specifier with the value as its 'global instantiator.
+ ;; specifier with the value as its `global' instantiator.
(if (not (specifierp specifier))
(let ((new-specifier (make-specifier 'generic)))
(if (or (not (null specifier))
＠＠ -436,7 +567,7 ＠＠ If PROPERTY is a built-in property, the
-- If VALUE is a simple instantiator (e.g. a string naming a font or
color) or a list of instantiators, then the instantiator(s) will
be added as a specification of the property for the given LOCALE
- (which defaults to 'global if omitted).
+ (which defaults to `global' if omitted).
-- If VALUE is a list of specifications (each of which is a cons of
a locale and a list of instantiators), then LOCALE must be nil
(it does not make sense to explicitly specify a locale in this
＠＠ -448,12 +579,12 ＠＠ If PROPERTY is a built-in property, the
`copy-specifier' and LOCALE has the same semantics (if it is
a particular locale, the specification for the locale will be
copied; if a locale type, specifications for all locales of
- that type will be copied; if nil or 'all, then all
+ that type will be copied; if nil or `all', then all
specifications will be copied).
-HOW-TO-ADD should be either nil or one of the symbols 'prepend,
- 'append, 'remove-tag-set-prepend, 'remove-tag-set-append,
'remove-locale,
- 'remove-locale-type, or 'remove-all. See `copy-specifier' and
+HOW-TO-ADD should be either nil or one of the symbols `prepend',
+ `append', `remove-tag-set-prepend', `remove-tag-set-append',
`remove-locale',
+ `remove-locale-type', or `remove-all.' See `copy-specifier' and
`add-spec-to-specifier' for a description of what each of
these means. Most of the time, you do not need to worry about
this argument; the default behavior usually is fine.
＠＠ -462,7 +593,7 ＠＠ In general, it is OK to pass an instance
by `glyph-property-instance') as an instantiator in place of
an actual instantiator. In such a case, the instantiator used
to create that instance object will be used (for example, if
- you set a font-instance object as the value of the 'font
+ you set a font-instance object as the value of the `font'
property, then the font name used to create that object will
be used instead). If some cases, however, doing this
conversion does not make sense, and this will be noted in
＠＠ -473,7 +604,7 ＠＠ If PROPERTY is not a built-in property,
given, then this function will attempt to add VALUE as the
instantiator for the given LOCALE, using `add-spec-to-specifier'.
If the value of the property is not a specifier, it will
- automatically be converted into a 'generic specifier.
+ automatically be converted into a `generic' specifier.
The following symbols have predefined meanings:
＠＠ -527,7 +658,7 ＠＠ See `remove-specifier' for the meaning o
LOCALE may be a locale (the instantiators for that particular locale
will be returned), a locale type (the specifications for all locales
- of that type will be returned), 'all (all specifications will be
+ of that type will be returned), `all' (all specifications will be
returned), or nil (the actual specifier object will be returned).
See `glyph-property' for more information."
＠＠ -561,10 +692,10 ＠＠ SPEC should be an instantiator (a string
object.
If SPEC is an alist, LOCALE must be omitted. If SPEC is a
- specifier object, LOCALE can be a locale, a locale type, 'all,
+ specifier object, LOCALE can be a locale, a locale type, `all',
or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
specifies the locale under which the specified instantiator(s)
- will be added, and defaults to 'global.
+ will be added, and defaults to `global.'
See `set-glyph-property' for more information."
; (interactive (glyph-interactive "image"))
＠＠ -575,17 +706,17 ＠＠ See `set-glyph-property' for more inform
LOCALE may be a locale (the instantiators for that particular locale
will be returned), a locale type (the specifications for all locales
- of that type will be returned), 'all (all specifications will be
+ of that type will be returned), `all' (all specifications will be
returned), or nil (the actual specifier object will be returned).
See `glyph-property' for more information."
(glyph-property glyph 'contrib-p locale))
(defun glyph-contrib-p-instance (glyph &optional domain default no-fallback)
- "Return the instance of GLYPH's 'contrib-p property in DOMAIN.
+ "Return the instance of GLYPH's `contrib-p' property in DOMAIN.
Normally DOMAIN will be a window or nil (meaning the selected window),
- and an instance object describing what the 'contrib-p property is in
+ and an instance object describing what the `contrib-p' property is in
that particular window and buffer will be returned.
See `glyph-property-instance' for more information."
＠＠ -599,10 +730,10 ＠＠ SPEC should be an instantiator (t or nil
locale to an instantiator list), or a boolean specifier object.
If SPEC is an alist, LOCALE must be omitted. If SPEC is a
- specifier object, LOCALE can be a locale, a locale type, 'all,
+ specifier object, LOCALE can be a locale, a locale type, `all',
or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
specifies the locale under which the specified instantiator(s)
- will be added, and defaults to 'global.
+ will be added, and defaults to `global.'
See `set-glyph-property' for more information."
; (interactive (glyph-interactive "contrib-p"))
＠＠ -613,7 +744,7 ＠＠ See `set-glyph-property' for more inform
LOCALE may be a locale (the instantiators for that particular locale
will be returned), a locale type (the specifications for all locales
- of that type will be returned), 'all (all specifications will be
+ of that type will be returned), `all' (all specifications will be
returned), or nil (the actual specifier object will be returned).
See `glyph-property' for more information."
＠＠ -638,10 +769,10 ＠＠ SPEC should be an instantiator (an integ
locale to an instantiator list), or a generic specifier object.
If SPEC is an alist, LOCALE must be omitted. If SPEC is a
- specifier object, LOCALE can be a locale, a locale type, 'all,
+ specifier object, LOCALE can be a locale, a locale type, `all',
or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
specifies the locale under which the specified instantiator(s)
- will be added, and defaults to 'global.
+ will be added, and defaults to `global.'
See `set-glyph-property' for more information."
; (interactive (glyph-interactive "baseline"))
＠＠ -668,13 +799,46 ＠＠ instantiator\", or \"image instance\" do
normally think of as an image (which in XEmacs is called a
\"pixmap\"), but to any graphical element -- a pixmap, a widget, or
even a block of text, when used in the places that call for a glyph.)
-The format of the SPEC-LIST is typically an image instantiator (a
-string or a vector; see `make-image-specifier' for a detailed description
-of the valid image instantiators), but can also be a list of such
-instantiators (each one in turn is tried until an image is
-successfully produced), a cons of a locale (frame, buffer, etc.) and
-an instantiator, a list of such conses, or any other form accepted by
-`canonicalize-spec-list'.
+
+SPEC-LIST is typically an image instantiator, describing the source for the
+image data. This is either a vector of the form [FORMAT :KEYWORD DATA ...],
+for example
+
+ [jpeg :file \"/user/john/images/myimage.jpg\"]
+
+or
+
+ [xbm :data \"/* XPM */\nstatic char * copy[] = {\n...\"]
+
+or it is a string, either giving a file name or directly specifying inline
+data. See `make-image-specifier' for a detailed description of valid image
+instantiators. If the instantiator is a string, XEmacs will convert it
+into vector form by trying to guess whether a file name or inline data is
+intended, and what kind of data is inline or in the file. Usually it does
+a pretty good job. See `console-type-image-conversion-list' for details of
+how this works.
+
+If the instantiator specifies data from a file, the data will be read in
+when `make-glyph' is called and substituted inline into the instantiator,
+using the :data keyword. This means that the file must exist when the
+glyph is created, but does not need to exist afterwards (e.g. it may safely
+be a temporary file).
+
+When errors occur in the process of reading image data from a file
+\(e.g. the file does not exist or the data is of the wrong format or
+corrupted), no Lisp error will currently be signalled. Instead, the
+instantiator is skipped and warnings will be issued at level `debug'. \(A
+glyph with no instantiators in it cannot be displayed.) Normally, such
+warnings are ignored entirely, but you can change this by setting
+`log-warning-minimum-level'. This is useful if you're trying to debug why
+particular instantiators are not being processed. (#### We should probably
+provide a way of getting errors in such circumstances, or even make this
+the default behavior.)
+
+Technically, SPEC-LIST can also be a list of image instantiators (each one
+in turn is tried until an image is successfully produced), a cons of a
+locale (frame, buffer, etc.) and an instantiator, a list of such conses,
+or any other form accepted by `canonicalize-spec-list'.
If you're not familiar with specifiers, you should be in order to
understand how glyphs work. The clearest introduction to specifiers
＠＠ -734,7 +898,7 ＠＠ Once you have created a glyph, you speci
value of the variable `toolbar-mail-icon' (in general, `toolbar-*-icon')
and then calling `(set-specifier-dirty-flag default-toolbar)'.
(#### Unfortunately this doesn't quite work the way it should; the
- change will appear in new frames, but not existing ones.
+ change will appear in new frames, but not existing ones.)
-- To insert a glyph into a gutter, create or modify a gutter instantiator
(typically set on the specifier `default-gutter'). Gutter instantiators
＠＠ -781,9 +945,6 ＠＠ Once you have created a glyph, you speci
which controls the appearance of characters. You can also set an
overriding display table for use with text displayed in a particular
face; see `set-face-display-table' and `make-display-table'.
- #### Note: Display tables do not currently support general Mule
- characters. They will be overhauled at some point to support this
- and to provide other features required under Mule.
-- To use a glyph as the background pixmap of a face: Note that the
background pixmap of a face is actually an image specifier -- probably
＠＠ -972,7 +1133,7 ＠＠ If unspecified in a particular domain, `
(set-glyph-image (symbol-value harg) value))))
;; It might or might not be garbage, but it's rude. Make these
-;; 'compatible instead of 'obsolete. -slb
+;; `compatible' instead of `obsolete.' -slb
(defun define-obsolete-pointer-glyph (old new)
(define-compatible-variable-alias old new)
(dontusethis-set-symbol-value-handler