xemacs-beta: lisp/glyphs.el comparison

comparison lisp/glyphs.el @ 2607:f8db302d6298

[xemacs-hg @ 2005-02-22 23:38:49 by ben] Update glyph documentation glyphs.el: 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.

author	ben
date	Tue, 22 Feb 2005 23:38:50 +0000
parents	1ccc32a20af4
children	fd1acd2f457a

comparison

equal deleted inserted replaced

-:76568bec0cdb
+:f8db302d6298
 ;;; 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@cs.uiuc.edu>, Ben Wing <ben@xemacs.org>
 ;; Maintainer: XEmacs Development Team
 ;; Keywords: extensions, internal, dumped
 SPEC-LIST can be a list of specifications (each of which is a cons of a
 locale and a list of instantiators), a single instantiator, or a list
 of instantiators.  See `make-specifier' for more information about
 specifiers.
-An image specifier is used for images (pixmaps, widgets and the like).
+The main purpose of this doc string is to describe the possible formats for
-It is used to describe the actual image in a glyph.  It is instanced
+image instantiators, as given as an argument to `make-glyph' or
-as an image-instance.  Note that \"image\" as used in XEmacs does not
+`set-glyph-image'.
-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.
 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
-'nothing
+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'
 Don't display anything; no keywords are valid for this.
-Can only be instanced as `nothing'.
+[] (nothing)
-'string
+`string'
-Display this image as a text string.  Can only be instanced
+Display this image as a text string.  Support for instantiating as
-as `text', although support for instancing as `mono-pixmap'
+`mono-pixmap' and `color-pixmap' should probably be added.
-and `color-pixmap' should be added.
+[:data] (text)
-'formatted-string
+`formatted-string'
-Display this image as a text string, with replaceable fields;
+Display this image as a text string, with replaceable fields.
-not currently implemented. (It is, instead, equivalent to `string'.)
+Not currently implemented -- it's treated like `string'.
-'xbm
+[:data] (text)
-An X bitmap; only if X or MS Windows support was compiled into this
+`gif'
-XEmacs.  Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+A GIF87 or GIF89 image; only if GIF support was compiled into this
-'xpm
+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.
+[:data, :file] (color-pixmap, pointer)
+`png'
+A PNG image; only if PNG support was compiled into this XEmacs.
+[:data, :file] (color-pixmap, pointer)
+`tiff'
+A TIFF image; only if TIFF support was compiled into this XEmacs.
+[:data, :file] (color-pixmap, pointer)
+`bmp'
+A MS Windows BMP image; only if MS Windows support was compiled into
+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.
-Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
+[:data, :file, :color-symbols] (mono-pixmap, color-pixmap, pointer)
-'xface
+`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
+only if X-Face support was compiled into this XEmacs.
-instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+[:data, :file, :foreground, :background, :mask-data, :mask-file,
-'gif
+:hotspot-x, :hotspot-y] (mono-pixmap, color-pixmap, pointer)
-A GIF87 or GIF89 image; only if GIF support was compiled into this
+`cursor-font'
-XEmacs.  NOTE: only the first frame of animated gifs will be displayed.
+X and GTK only.  One of the standard cursor-font names, such as \"watch\"
-Can be instanced as `color-pixmap'.
+or \"right_ptr\" under X.  Under X, this is, more specifically, any
-'jpeg
-A JPEG image; only if JPEG support was compiled into this XEmacs.
-Can be instanced as `color-pixmap'.
-'png
-A PNG image; only if PNG support was compiled into this XEmacs.
-Can be instanced as `color-pixmap'.
-'tiff
-A TIFF image; only if TIFF support was compiled into this XEmacs.
-Can be instanced as `color-pixmap'.
-'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
 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'.
+type of window system.
-'mswindows-resource
+[: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
+the resource.  Possible values for :resource-id are listed below.
-be instanced as `pointer' or `color-pixmap'.
+[:file, :resource-type, :resource-id] (pointer, color-pixmap)
-'font
+`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
+[:data, :foreground, :background] (pointer)
-An embedded windowing system window.  Can only be instanced as
+`subwindow'
-`subwindow'.
+An embedded windowing system window.
-'button
+[:pixel-width, :pixel-height] (subwindow)
+`button'
 A button widget; either a push button, radio button or toggle button.
-Can only be instanced as `widget'.
+[WIDGET-KEYWORDS, GUI-KEYWORDS, :image] (widget)
-'combo-box
+`combo-box'
 A drop list of selectable items in a widget, for editing text.
-Can only be instanced as `widget'.
+[GUI-KEYWORDS, :width, :height, :pixel-width, :face, :items] (widget)
-'edit-field
+`edit-field'
-A text editing widget.  Can only be instanced as `widget'.
+A text editing widget.
-'label
+[WIDGET-KEYWORDS, GUI-KEYWORDS] (widget)
-A static, text-only, widget; for displaying text.  Can only be instanced
+`label'
-as `widget'.
+A static, text-only, widget; for displaying text.
-'layout
+[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
+in many of the places that expect a single glyph.
-as `widget'.
+[WIDGET-KEYWORDS, GUI-KEYWORDS, :orientation, :justify, :vertically-justify,
-'native-layout
+: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'.
+[WIDGET-KEYWORDS, GUI-KEYWORDS] (widget)
-'progress-gauge
+`progress-gauge'
-A sliding widget, for showing progress.  Can only be instanced as
+A sliding widget, for showing progress.
-`widget'.
+[WIDGET-KEYWORDS, GUI-KEYWORDS, :value] (widget)
-'tab-control
+`tab-control'
-A tab widget; a series of user selectable tabs.  Can only be instanced
+A tab widget; a series of user selectable tabs.
-as `widget'.
+[WIDGET-KEYWORDS, GUI-KEYWORDS, :orientation, :items] (widget)
-'tree-view
+`tree-view'
-A folding widget.  Can only be instanced as `widget'.
+A folding widget.
-'scrollbar
+[WIDGET-KEYWORDS, GUI-KEYWORDS, :items] (widget)
-A scrollbar widget.  Can only be instanced as `widget'.
+`scrollbar'
-'autodetect
+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
 sort of pixmap or pointer will be created. [This includes picking up
 any specified hotspot or associated mask file.] Otherwise, if `pointer'
 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
+exists, the image will always be displayed as text.
-`mono-pixmap', `color-pixmap', `pointer', or `text'.
+[:data] (mono-pixmap, color-pixmap, pointer, text)
-'inherit
+`inherit'
-Inherit from the background-pixmap property of a face.  Can only be
+Inherit from the background-pixmap property of a face.
-instanced as `mono-pixmap'.
+[:face] (mono-pixmap)
 The valid keywords are:
 :data
 Inline data.  For most formats above, this should be a string.  For
 \"restored\", \"uparrowd\", \"dnarrowd\", \"rgarrowd\", \"lfarrowd\",
 \"mnarrow\", \"combo\", \"uparrowi\", \"dnarrowi\", \"rgarrowi\",
 \"lfarrowi\", \"size\", \"btsize\", \"check\", \"checkboxes\", and
 \"btncorners\".
--- For cursors:
+-- For pointers:
 \"normal\", \"ibeam\", \"wait\", \"cross\", \"up\", \"sizenwse\",
 \"sizenesw\", \"sizewe\", \"sizens\", \"sizeall\", and \"no\".
 -- For icons:
 \"sample\", \"hand\", \"ques\", \"bang\", \"note\", and \"winlogo\".
 :resource-type
-Only for `mswindows-resource'.  This must be a symbol, either `cursor',
+Only for `mswindows-resource'.  This must be a symbol, either `cursor'
-`icon', or `bitmap', specifying the type of resource to be retrieved.
+(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
-Keywords accepted as menu item specs are also accepted by widgets.
+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.
+\[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
 the domain (usually a window; sometimes a frame or device) over which
 instantiator will be converted into one of the inline-data forms, with
 the filename retained using a :file keyword.  This implies that the
 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
 (defconst built-in-glyph-specifiers
 The return value will be a list of instantiators (e.g. strings
 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
+the symbols `buffer', `window', `frame', `device', `device-class', or
-'device-type), the specifications for all locales of that type will
+`device-type'), the specifications for all locales of that type will
-be returned.  Finally, if LOCALE is 'all, the specifications for all
+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
 PROPERTY will be in a particular \"domain\" or set of circumstances,
 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
 within that window; then for a specification whose locale is the window
 itself; then for a specification whose locale is the frame that the
 (check-argument-type 'glyphp glyph)
 (let ((specifier (get glyph property)))
 ;; 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))
 		  ;; make sure the nil returned from `get' wasn't
 		  ;; actually the value of the property
 this property can be supplied in many different ways:
 -- 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
 case), and specifications will be added as given.
 -- If VALUE is a specifier (as would be returned by `glyph-property'
 specifications in the specifier will be added to the property.
 In this case, the function is really equivalent to
 `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,
+HOW-TO-ADD should be either nil or one of the symbols `prepend',
-'append, 'remove-tag-set-prepend, 'remove-tag-set-append, 'remove-locale,
+`append', `remove-tag-set-prepend', `remove-tag-set-append', `remove-locale',
-'remove-locale-type, or 'remove-all.  See `copy-specifier' and
+`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.
 In general, it is OK to pass an instance object (e.g. as returned
 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
 the documentation for particular types of instance objects.
 If PROPERTY is not a built-in property, then this function will
 simply set its value if LOCALE is nil.  However, if LOCALE is
 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:
 image		The image used to display the glyph.
 (defun glyph-image (glyph &optional locale)
 "Return the image of GLYPH in LOCALE, or nil if it is unspecified.
 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 'image locale))
 a list of (possibly tagged) instantiators, an alist of specifications
 (each mapping a locale to an instantiator list), or an image 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 "image"))
 (set-glyph-property glyph 'image spec locale tag-set how-to-add))
 (defun glyph-contrib-p (glyph &optional locale)
 "Return whether GLYPH contributes to its line height.
 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."
 (glyph-property-instance glyph 'contrib-p domain default no-fallback))
 SPEC should be an instantiator (t or nil), a list of (possibly
 tagged) instantiators, an alist of specifications (each mapping a
 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"))
 (set-glyph-property glyph 'contrib-p spec locale tag-set how-to-add))
 (defun glyph-baseline (glyph &optional locale)
 "Return the baseline of GLYPH in LOCALE, or nil if it is unspecified.
 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 'baseline locale))
 baseline of the line the glyph is on] or nil), a list of (possibly
 tagged) instantiators, an alist of specifications (each mapping a
 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"))
 (set-glyph-property glyph 'baseline spec locale tag-set how-to-add))
 `image' property or in the terms \"image specifier\", \"image
 instantiator\", or \"image instance\" does not refer to what people
 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
+SPEC-LIST is typically an image instantiator, describing the source for the
-of the valid image instantiators), but can also be a list of such
+image data.  This is either a vector of the form [FORMAT :KEYWORD DATA ...],
-instantiators (each one in turn is tried until an image is
+for example
-successfully produced), a cons of a locale (frame, buffer, etc.)  and
-an instantiator, a list of such conses, or any other form accepted by
+[jpeg :file \"/user/john/images/myimage.jpg\"]
-`canonicalize-spec-list'.
+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
 is in the Lispref manual, available under Info. (Choose
 Help->Info->Info Contents on the menubar or type \\[info].) You can
 individual glyphs in a toolbar later on.  For example, you can
 change the way that the Mail toolbar button looks by modifying the
 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
 consist of strings or lists of strings, so to insert a glyph, create an
 extent over the string, and use `set-extent-begin-glyph' or
 any individual character), create the appropriate character glyphs
 and then set a specification for the specifier `current-display-table',
 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
 the only place in XEmacs where an image specifier occurs outside of
 a glyph.  Similarly to how the glyph's image specifier works, you
 (if (null value)
 	(remove-specifier harg 'global)
 (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
 old 'set-value 'dontusethis-old-pointer-shape-handler new))

Mercurial > hg > xemacs-beta

comparison lisp/glyphs.el @ 2607:f8db302d6298