Mercurial > hg > xemacs-beta
diff 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 |
line wrap: on
line diff
--- a/man/lispref/glyphs.texi Mon Sep 26 08:29:31 2005 +0000 +++ b/man/lispref/glyphs.texi Mon Sep 26 08:41:57 2005 +0000 @@ -88,25 +88,25 @@ @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 -@subsection Image Specifiers -@cindex image specifiers +@node Image Instantiators +@subsection Image Instantiators +@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 @@ -114,8 +114,8 @@ 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 -by the program by specifying different @dfn{image instantiators} in +may not even be a bitmapped graphic. These variations may be +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. @@ -156,9 +156,9 @@ 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.). @@ -372,11 +372,11 @@ @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 -as @code{text}, although support for instancing as @code{mono-pixmap} +Display this image as a text string. Can only be instantiated +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. @@ -432,7 +432,7 @@ @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 @@ -476,7 +476,7 @@ 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. @@ -526,7 +526,7 @@ 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 @@ -539,7 +539,7 @@ @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 @@ -555,14 +555,14 @@ 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 @@ -601,23 +601,23 @@ @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 @@ -625,19 +625,19 @@ 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 @@ -654,10 +654,10 @@ (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, @@ -672,7 +672,7 @@ @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 @@ -719,7 +719,7 @@ @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 @@ -834,7 +834,7 @@ 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 @@ -991,7 +991,7 @@ @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 @@ -1104,7 +1104,7 @@ 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 @@ -1488,7 +1488,7 @@ 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 @@ -1838,7 +1838,7 @@ 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}. @@ -2065,7 +2065,7 @@ 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 @@ -2079,7 +2079,7 @@ 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: