xemacs-beta: man/lispref/glyphs.texi comparison

comparison man/lispref/glyphs.texi @ 2953:c7d4a681eb2c

[xemacs-hg @ 2005-09-26 08:41:45 by ben] add specifier-instantiator and friends specifier.c: Add `specifier-instantiator' and related primitives. lispref/glyphs.texi, lispref/lispref.texi, lispref/specifiers.texi: Use "instantiation" not "instancing". Fix some places where "specifier" is used to mean "instantiator".

author	ben
date	Mon, 26 Sep 2005 08:41:57 +0000
parents	13a418960a88
children	1cecc3e9f0a0

comparison

equal deleted inserted replaced

-:861a7995b9fe
+:c7d4a681eb2c
 @node Images
 @section Images
 @menu
-* Image Specifiers::			Specifying an image's appearance.
+* Image Instantiators::			Specifying an image's appearance.
 * Image Instantiator Conversion::	Lazy realization of graphics.
 * Image Instantiator Formats::		A catalog of image descriptors.
 * Image Instances::			Classes of graphical objects.
 @end menu
-@node Image Specifiers
+@node Image Instantiators
-@subsection Image Specifiers
+@subsection Image Instantiators
-@cindex image specifiers
+@cindex image instantiators
-An image specifier is a description of the actual graphical
+An @dfn{image instantiator} is a description of the actual graphical
 realization of a glyph.  For example, a typical image description is
 @emph{the file system path to a PNG file}.  Since redisplay doesn't know
 about files, and in any case the image may need to be manipulated
 (@emph{e.g.}, a face's background pixmap must be clipped and tiled), the
 PNG file must be converted internally to a window system bitmap or
 pixmap object.  We describe this process by writing that when XEmacs
-displays the image, it @dfn{instantiates} the @dfn{image instantiator}
+displays the image, it @dfn{instantiates} the image instantiator
 into an @dfn{image instance}.  Image instances are an internal object
 type (similar to font instances and color instances), describing how the
 image appears in a particular domain.  On the other hand, image
 instantiators, which are just descriptions of how the image should
 appear, are represented using Lisp strings or vectors.
 Furthermore the graphical realization will vary, and for some devices
-may not even be a bitmapped graphic.  These variations may be controlled
+may not even be a bitmapped graphic.  These variations may be
-by the program by specifying different @dfn{image instantiators} in
+controlled by the program by specifying different instantiators in
 different locales.  This is implemented with an @dfn{image specifier},
 a specifier whose specifications are image instantiators.
 Image specifiers are rarely if ever found by themselves.  However, an
 image specifier results from calling @code{glyph-image} on a glyph, or
 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, @code{xpm} can be instanced as @code{color-pixmap},
+For example, @code{xpm} can be instantiated as @code{color-pixmap},
 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
-instanced only as @code{pointer}.  On the other hand, a particular image
+instantiated only as @code{pointer}.  On the other hand, a particular image
 instance type can be generated by many different image instantiator
 formats (e.g.  @code{color-pixmap} can be generated by @code{xpm},
 @code{gif}, @code{jpeg}, etc.).
 @xref{Image Instances}, for a more detailed discussion of image
 are usable with each, and the kinds of instances that may result.
 @table @code
 @item nothing
 Don't display anything; no keywords are valid for this format.  Can only be
-instanced as @code{nothing}.
+instantiated as @code{nothing}.
 @item string
-Display this image as a text string.  Can only be instanced
+Display this image as a text string.  Can only be instantiated
-as @code{text}, although support for instancing as @code{mono-pixmap}
+as @code{text}, although support for instantiation as @code{mono-pixmap}
 should be added.  The valid keyword is @code{:data}.  The value should
 be a string, and it is interpreted as a string of characters.
 @item formatted-string
 Display this image as a text string with replaceable fields,
 @end table
 @item xpm
 An XPM pixmap; only available if XPM support was compiled into this XEmacs.
-Can be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
+Can be instantiated as @code{color-pixmap}, @code{mono-pixmap}, or
 @code{pointer}.
 XPM is an add-on library for X that was designed to rectify the
 shortcomings of the XBM format.  Many icons and labels used in the
 XEmacs GUI are still distributed in XPM format (although we are moving
 @item xface
 An X-Face bitmap, used to encode people's faces in e-mail messages;
 only available if X-Face support was compiled into this XEmacs.
-Will be instanced as @code{mono-pixmap}, @code{color-pixmap}, or
+Will be instantiated as @code{mono-pixmap}, @code{color-pixmap}, or
 @code{pointer}, depending on the target instance type and the presence
 of color keywords.
 The valid keywords and their values are
 @table @code
 places'') and linked into the build.
 Note that PNG is the standard format for images distributed with XEmacs,
 so it is highly recommended that PNG support be built in.
-All of these instantiators will be instanced as @code{color-pixmap}.
+All of these instantiators will be instantiated as @code{color-pixmap}.
 The valid keywords and their values are
 @table @code
 @item :data
 A string interpreted as the contents of a file containing data in the
 The name of a file containing standard-format data.
 @end table
 @item cursor-font
 Most window systems provide a set of standard cursors, which in X11 is
-called a cursor font.  Can only be instanced as @code{pointer}.  This
+called a cursor font.  Can only be instantiated as @code{pointer}.  This
 should probably be fixed.
 The valid keyword is @code{:data}.  Its value should be a string
 containing one of the standard cursor-font names, such as @samp{watch}
 or @samp{right_ptr} under X.  More specifically, in the X Window System
 @item font
 A glyph from a font; i.e. the name of a font, and glyph index into it
 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
 Only if X support was compiled into this XEmacs.  Currently can only be
-instanced as @code{pointer}.  This should probably be fixed.
+instantiated as @code{pointer}.  This should probably be fixed.
 @c #### The above description is not very helpful, so it's not obvious
 @c how to instantiate a font image.
 @item 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.  Can be instanced as @code{pointer} or
+an executable file.  Can be instantiated as @code{pointer} or
 @code{color-pixmap}.
 The valid keywords and their values are
 @table @code
 "sample", "hand", "ques", "bang", "note", and "winlogo".
 @end table
 @item subwindow
-An embedded windowing system window.  Can only be instanced as
+An embedded windowing system window.  Can only be instantiated as
 @code{subwindow}.  Not implemented.
 @c #### Check status of subwindows ... I thought Andy implemented them.
 @item button
 A button widget; either a push button, radio button or toggle button.
-Can only be instanced as @code{widget}.
+Can only be instantiated as @code{widget}.
 @item combo-box
 A drop list of selectable items in a widget, for editing text.
-Can only be instanced as @code{widget}.
+Can only be instantiated as @code{widget}.
 @item edit-field
-A text editing widget.  Can only be instanced as @code{widget}.
+A text editing widget.  Can only be instantiated as @code{widget}.
 @item label
-A static, text-only, widget; for displaying text.  Can only be instanced
+A static, text-only, widget; for displaying text.  Can only be instantiated
 as @code{widget}.
 @item 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 @dfn{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.  Can only be instantiated
 as @code{widget}.
 @item native-layout
 The native version of a layout widget.
-Can only be instanced as @code{widget}.
+Can only be instantiated as @code{widget}.
 @item progress-gauge
-A sliding widget, for showing progress.  Can only be instanced as
+A sliding widget, for showing progress.  Can only be instantiated as
 @code{widget}.
 @item tab-control
-A tab widget; a series of user selectable tabs.  Can only be instanced
+A tab widget; a series of user selectable tabs.  Can only be instantiated
 as @code{widget}.
 The required keyword is @code{:items}.  Its value should be a list of
 vectors, whose first element is a string, the second element is a
 callback (a Lisp expression to be eval'ed), and the remaining elements
 and @code{:pixel-height} (positive integers).
 (The above is incomplete and may be inaccurate.)
 @item tree-view
-A folding widget.  Can only be instanced as @code{widget}.
+A folding widget.  Can only be instantiated as @code{widget}.
 @item scrollbar
-A scrollbar widget.  Can only be instanced as @code{widget}.
+A scrollbar widget.  Can only be instantiated as @code{widget}.
 @item 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
 Otherwise, the image will be displayed as text.  If no X support exists,
 the image will always be displayed as text.
 @item inherit
 Inherit from the background-pixmap property of a face.  Can only be
-instanced as @code{mono-pixmap}.
+instantiated as @code{mono-pixmap}.
 @end table
 There are two convenience variables for use with the XBM and XPM image
 formats.
 @defun image-instance-p object
 This function returns non-@code{nil} if @var{object} is an image instance.
 @end defun
 @menu
-* Image Instance Types::         Each image instances has a particular type.
+* Image Instance Types::         Each image instance has a particular type.
 * Image Instance Functions::	 Functions for working with image instances.
 @end menu
 @node Image Instance Types
 @defun make-image-instance data &optional domain dest-types noerror
 This function creates a new image-instance object.
 @var{data} is an image instantiator, which describes the image
-(@pxref{Image Specifiers}).
+(@pxref{Image Instantiators}).
 @var{dest-types} should be a list of allowed image instance types that
 can be generated.  The @var{dest-types} list is unordered.  If multiple
 destination types are possible for a given instantiator, the ``most
 natural'' type for the instantiator's format is chosen.  These are
 This function returns the Y coordinate of the image instance's hotspot,
 if known.
 @end defun
 Mono pixmaps and pointers may have their foreground and background
-colors set when instanced.  Use these functions to access color
+colors set when instantiated.  Use these functions to access color
 information.
 @defun image-instance-foreground image-instance
 This function returns the foreground color of @var{image-instance}, if
 applicable.  This will be a color instance or @code{nil}.  (It will only
 vector according to @code{console-type-image-conversion-list}, or a
 vector.  The vector's first element specifies the @emph{external} format
 of the data, such as a string, a PNG file, or an MS Windows resource.
 This is followed by properties (keyword-value pairs) specifying such
 information as the name of a file containing an image, or pixmap data
-directly.  @xref{Image Specifiers}.
+directly.  @xref{Image Instantiators}.
 The optional @var{type} specifies the type of the glyph.  @var{type}
 should be one of @code{buffer} (used for glyphs in an extent, the
 modeline, the toolbar, or elsewhere in a frame), @code{pointer} (used
 for the mouse-pointer), or @code{icon} (used for a frame's icon), and
 @subsubsection Lisp API to Native Widgets
 Native widgets are manipulated as @emph{glyphs} (@pxref{Glyphs}).  Thus
 they are created using @code{make-glyph}, with a format of one of the
 widget types and a @code{:data} property specific to the widget being
-instanced.
+instantiated.
 However, there is a technical difference between widgets and other kinds
 of glyphs that is theoretically important.  Because widgets
 are active (that is, they can respond to user input events themselves),
 it is possible for the user to become aware that two appearances of the
 frame or device, if it is not overridden by a more specific
 specification.
 If @var{property} does not name a built-in property, its value will
 simply be returned unless it is a specifier object, in which case it
-will be instanced using @code{specifier-instance}.
+will be instantiated using @code{specifier-instance}.
 Optional arguments @var{default} and @var{no-fallback} are the same as
 in @code{specifier-instance}.  @xref{Specifiers}.
 @end defun
 The parameters passed to @code{make-glyph} are called "Image
 Specifiers", and can handle more image types than those shown above.
 You can also put the raw image data into a string (e.g., if you put the
 contents of a JPEG file into a string), and use that to create a glyph.
-@xref{Image Specifiers}, for more information.
+@xref{Image Instantiators}, for more information.
 @quotation
 @strong{Caution}: In order for XEmacs to read a particular graphics file
 format, support for that format must have been compiled into XEmacs.
 It's possible, although somewhat unlikely, for XEmacs to have been
 To programmatically query whether or not a particular file format is
 supported, you can use the @code{featurep} function, with one of:
 @code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm},
 @code{png}, or @code{xface}.  For an up-to-date list, @ref{Image
-Specifiers}.  Example:
+Instantiators}.  Example:
 @example
 ;; Returns `t' if TIFF is supported:
 (featurep 'tiff)
 @end example

Mercurial > hg > xemacs-beta

comparison man/lispref/glyphs.texi @ 2953:c7d4a681eb2c