[COMMIT] add specifier-instantiator and friends

NOTE: This patch has been committed. This is needed by changes coming up. src/ChangeLog addition: 2005-09-26 Ben Wing <ben(a)xemacs.org&gt; * specifier.c: * specifier.c (Fvalid_specifier_type_p): * specifier.c (Fvalid_specifier_locale_p): * specifier.c (Fvalid_specifier_domain_p): * specifier.c (Fvalid_specifier_locale_type_p): * specifier.c (Fdefine_specifier_tag): * specifier.c (specifier_get_external_inst_list): * specifier.c (Fspecifier_specs): * specifier.c (Fspecifier_fallback): * specifier.c (specifier_instance_from_inst_list): * specifier.c (CHECK_INSTANCE_ENTRY): * specifier.c (specifier_instance_1): * specifier.c (specifier_instance): * specifier.c (specifier_matching_foo): * specifier.c (Fspecifier_instance): * specifier.c (Fspecifier_instantiator): * specifier.c (Fspecifier_matching_instance): * specifier.c (specifier_matching_foo_from_inst_list): * specifier.c (syms_of_specifier): Add `specifier-instantiator' and related primitives. man/ChangeLog addition: 2005-09-26 Ben Wing <ben(a)xemacs.org&gt; * lispref/glyphs.texi (Images): * lispref/glyphs.texi (Image Instantiators): * lispref/glyphs.texi (Image Instantiator Formats): * lispref/glyphs.texi (Image Instances): * lispref/glyphs.texi (Image Instance Functions): * lispref/glyphs.texi (Creating Glyphs): * lispref/glyphs.texi (Lisp API to Native Widgets): * lispref/glyphs.texi (Glyph Properties): * lispref/glyphs.texi (Glyph Examples): * lispref/lispref.texi (Top): * lispref/specifiers.texi (Specifiers): * lispref/specifiers.texi (Introduction to Specifiers): * lispref/specifiers.texi (Simple Specifier Usage): * lispref/specifiers.texi (Specifiers In-Depth): * lispref/specifiers.texi (Specifier Instantiation): * lispref/specifiers.texi (Retrieving Specifications): * lispref/specifiers.texi (Specifier Tag Functions): * lispref/specifiers.texi (Specifier Validation Functions): Use "instantiation" not "instancing". Fix some places where "specifier" is used to mean "instantiator". build source patch: Diff command: bash -ci "cvs-diff --show-c-function -no-changelog " Files affected: man/lispref/specifiers.texi man/lispref/lispref.texi man/lispref/glyphs.texi src/specifier.c Mon Sep 26 03:34:35 CDT 2005 Index: src/specifier.c =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/src/specifier.c,v retrieving revision 1.40 diff -u -p -r1.40 specifier.c --- src/specifier.c 2005/04/08 23:11:32 1.40 +++ src/specifier.c 2005/09/26 08:34:52 ＠＠ -1,6 +1,6 ＠＠ /* Specifier implementation Copyright (C) 1994, 1995 Board of Trustees, University of Illinois. - Copyright (C) 1995, 1996, 2002 Ben Wing. + Copyright (C) 1995, 1996, 2002, 2005 Ben Wing. Copyright (C) 1995 Sun Microsystems, Inc. This file is part of XEmacs. ＠＠ -23,9 +23,8 ＠＠ Boston, MA 02111-1307, USA. */ /* Synched up with: Not in FSF. */ /* Design by Ben Wing; - Original version by Chuck Thompson; - rewritten by Ben Wing; - Magic specifiers by Kirill Katsnelson; + Written by Ben Wing based on prototype for 19.12 by Chuck Thompson. + Magic specifiers by Kirill Katsnelson. */ #include <config.h> ＠＠ -460,8 +459,8 ＠＠ valid_specifier_type_p (Lisp_Object type DEFUN ("valid-specifier-type-p", Fvalid_specifier_type_p, 1, 1, 0, /* Given a SPECIFIER-TYPE, return non-nil if it is valid. -Valid types are 'generic, 'integer, 'boolean, 'color, 'font, 'image, -'face-boolean, and 'toolbar. +Valid types are `generic', `integer', `boolean', `color', `font', `image', +`face-boolean', and `toolbar'. */ (specifier_type)) { ＠＠ -578,8 +577,11 ＠＠ lower-level functions `add-spec-to-speci `add-spec-list-to-specifier'. You can also temporarily bind a setting to a specifier using `let-specifier'. To retrieve settings, use `specifier-specs', or its lower-level counterpart -`specifier-spec-list'. To determine the actual value, use -`specifier-instance'. +`specifier-spec-list'. + +To determine the actual value (i.e. the instance) in a particular domain, use +`specifier-instance'. To determine the corresponding setting that yielded +the value (i.e. the instantiator), use `specifier-instantiator'. For more information, see `set-specifier', `specifier-instance', `specifier-specs', and `add-spec-to-specifier'; or, for a detailed ＠＠ -588,9 +590,9 ＠＠ process works, see the chapter on specif Reference Manual. TYPE specifies the particular type of specifier, and should be one of -the symbols 'generic, 'integer, 'natnum, 'boolean, 'color, 'font, -'image, 'face-boolean, 'display-table, 'gutter, 'gutter-size, -'gutter-visible or 'toolbar. +the symbols `generic', `integer', `natnum', `boolean', `color', `font', +`image', `face-boolean', `display-table', `gutter', `gutter-size', +`gutter-visible' or `toolbar'. For more information on particular types of specifiers, see the functions `make-generic-specifier', `make-integer-specifier', ＠＠ -637,7 +639,7 ＠＠ Return the type of SPECIFIER. DEFUN ("valid-specifier-locale-p", Fvalid_specifier_locale_p, 1, 1, 0, /* Return t if LOCALE is a valid specifier locale. -Valid locales are devices, frames, windows, buffers, and 'global. +Valid locales are devices, frames, windows, buffers, and `global'. \(nil is not valid.) */ (locale)) ＠＠ -655,7 +657,7 ＠＠ Valid locales are devices, frames, windo DEFUN ("valid-specifier-domain-p", Fvalid_specifier_domain_p, 1, 1, 0, /* Return t if DOMAIN is a valid specifier domain. -A domain is used to instance a specifier (i.e. determine the specifier's +A domain is used to instantiate a specifier (i.e. determine the specifier's value in that domain). Valid domains are image instances, windows, frames, and devices. \(nil is not valid.) image instances are pseudo-domains since instantiation will actually occur in the window the image instance itself is ＠＠ -675,9 +677,9 ＠＠ instantiated in. DEFUN ("valid-specifier-locale-type-p", Fvalid_specifier_locale_type_p, 1, 1, 0, /* Given a specifier LOCALE-TYPE, return non-nil if it is valid. -Valid locale types are 'global, 'device, 'frame, 'window, and 'buffer. +Valid locale types are `global', `device', `frame', `window', and `buffer'. \(Note, however, that in functions that accept either a locale or a locale -type, 'global is considered an individual locale.) +type, `global' is considered an individual locale.) */ (locale_type)) { ＠＠ -828,8 +830,8 ＠＠ Each tag has a predicate associated with that tag applies to a particular device. The tags which are device types and classes match devices of that type or class. User-defined tags can have any predicate, or none (meaning that all devices match). When -attempting to instance a specifier, a particular instantiator is only -considered if the device of the domain being instanced over matches +attempting to instantiate a specifier, a particular instantiator is only +considered if the device of the domain being instantiated over matches all tags in the tag set attached to that instantiator. Most of the time, a tag set is not specified, and the instantiator ＠＠ -976,7 +978,7 ＠＠ device. If PREDICATE is omitted, the ta You can redefine an existing user-defined specifier tag. However, you cannot redefine the built-in specifier tags (the device types -and classes) or the symbols nil, t, 'all, or 'global. +and classes) or the symbols nil, t, `all', or `global'. */ (tag, predicate)) { ＠＠ -990,7 +992,7 ＠＠ and classes) or the symbols nil, t, 'all /* Try to prevent common instantiators and locales from being redefined, to reduce ambiguity */ if (NILP (tag) || EQ (tag, Qt) || EQ (tag, Qall) || EQ (tag, Qglobal)) - invalid_change ("Cannot define nil, t, 'all, or 'global", tag); + invalid_change ("Cannot define nil, t, `all', or `global'", tag); assoc = assq_no_quit (tag, Vuser_defined_tags); if (NILP (assoc)) { ＠＠ -1476,7 +1478,7 ＠＠ specifier_get_external_inst_list (Lisp_O type); if (!inst_list || NILP (*inst_list)) { - /* nil for *inst_list should only occur in 'global */ + /* nil for *inst_list should only occur in `global' */ assert (!inst_list || EQ (locale, Qglobal)); return Qnil; } ＠＠ -1834,12 +1836,12 ＠＠ specifier_copy_locale_type (Lisp_Object /* map MAPFUN over the locales in SPECIFIER that are given in LOCALE. CLOSURE is passed unchanged to MAPFUN. LOCALE can be one of - -- nil (same as 'all) - -- a single locale, locale type, or 'all - -- a list of locales, locale types, and/or 'all + -- nil (same as `all') + -- a single locale, locale type, or `all' + -- a list of locales, locale types, and/or `all' - MAPFUN is called for each locale and locale type given; for 'all, - it is called for the locale 'global and for the four possible + MAPFUN is called for each locale and locale type given; for `all', + it is called for the locale `global' and for the four possible locale types. In each invocation, either LOCALE will be a locale and LOCALE_TYPE will be the locale type of this locale, or LOCALE will be nil and LOCALE_TYPE will be a locale type. ＠＠ -1920,7 +1922,7 ＠＠ map_specifier (Lisp_Object specifier, Li DEFUN ("add-spec-to-specifier", Fadd_spec_to_specifier, 2, 5, 0, /* Add a specification to SPECIFIER. The specification maps from LOCALE (which should be a window, buffer, -frame, device, or 'global, and defaults to 'global) to INSTANTIATOR, +frame, device, or `global', and defaults to `global') to INSTANTIATOR, whose allowed values depend on the type of the specifier. Optional argument TAG-SET limits the instantiator to apply only to the specified tag set, which should be a list of tags all of which must match the ＠＠ -1931,26 +1933,26 ＠＠ containing that symbol. Optional argume do if there are already specifications in the specifier. It should be one of - 'prepend Put at the beginning of the current list of + `prepend' Put at the beginning of the current list of instantiators for LOCALE. - 'append Add to the end of the current list of + `append' Add to the end of the current list of instantiators for LOCALE. - 'remove-tag-set-prepend (this is the default) + `remove-tag-set-prepend' (this is the default) Remove any existing instantiators whose tag set is the same as TAG-SET; then put the new instantiator at the beginning of the current list. ("Same tag set" means that they contain the same elements. The order may be different.) - 'remove-tag-set-append + `remove-tag-set-append' Remove any existing instantiators whose tag set is the same as TAG-SET; then put the new instantiator at the end of the current list. - 'remove-locale Remove all previous instantiators for this locale + `remove-locale' Remove all previous instantiators for this locale before adding the new spec. - 'remove-locale-type Remove all specifications for all locales of the + `remove-locale-type' Remove all specifications for all locales of the same type as LOCALE (this includes LOCALE itself) before adding the new spec. - 'remove-all Remove all specifications from the specifier + `remove-all' Remove all specifications from the specifier before adding the new spec. You can retrieve the specifications for a particular locale or locale type ＠＠ -1989,7 +1991,7 ＠＠ The format of SPEC-LIST is ((LOCALE (TAG-SET . INSTANTIATOR) ...) ...) where - LOCALE := a window, a buffer, a frame, a device, or 'global + LOCALE := a window, a buffer, a frame, a device, or `global' TAG-SET := an unordered list of zero or more TAGS, each of which is a symbol TAG := a device class (see `valid-device-class-p'), a device type ＠＠ -2105,17 +2107,17 ＠＠ DEFUN ("specifier-spec-list", Fspecifier Return the spec-list of specifications for SPECIFIER in LOCALE. If LOCALE is a particular locale (a buffer, window, frame, device, -or 'global), a spec-list consisting of the specification for that +or `global'), a spec-list consisting of the specification for that locale will be returned. -If LOCALE is a locale type (i.e. 'buffer, 'window, 'frame, or 'device), +If LOCALE is a locale type (i.e. `buffer', `window', `frame', or `device'), a spec-list of the specifications for all locales of that type will be returned. -If LOCALE is nil or 'all, a spec-list of all specifications in SPECIFIER +If LOCALE is nil or `all', a spec-list of all specifications in SPECIFIER will be returned. -LOCALE can also be a list of locales, locale types, and/or 'all; the +LOCALE can also be a list of locales, locale types, and/or `all'; the result is as if `specifier-spec-list' were called on each element of the list and the results concatenated together. ＠＠ -2155,11 +2157,11 ＠＠ in Lisp programs, and is as follows: 1. If there is only one instantiator, then an inst-pair (i.e. cons of tag and instantiator) will be returned; otherwise a list of inst-pairs will be returned. -2. For each inst-pair returned, if the instantiator's tag is 'any, +2. For each inst-pair returned, if the instantiator's tag is `any', the tag will be removed and the instantiator itself will be returned instead of the inst-pair. 3. If there is only one instantiator, its value is nil, and its tag is - 'any, a one-element list containing nil will be returned rather + `any', a one-element list containing nil will be returned rather than just nil, to distinguish this case from there being no instantiators at all. */ ＠＠ -2205,15 +2207,15 ＠＠ DEFUN ("remove-specifier", Fremove_speci Remove specification(s) for SPECIFIER. If LOCALE is a particular locale (a window, buffer, frame, device, -or 'global), the specification for that locale will be removed. +or `global'), the specification for that locale will be removed. -If instead, LOCALE is a locale type (i.e. 'window, 'buffer, 'frame, -or 'device), the specifications for all locales of that type will be +If instead, LOCALE is a locale type (i.e. `window', `buffer', `frame', +or `device'), the specifications for all locales of that type will be removed. -If LOCALE is nil or 'all, all specifications will be removed. +If LOCALE is nil or `all', all specifications will be removed. -LOCALE can also be a list of locales, locale types, and/or 'all; this +LOCALE can also be a list of locales, locale types, and/or `all'; this is equivalent to calling `remove-specifier' for each of the elements in the list. ＠＠ -2284,11 +2286,11 ＠＠ If DEST is nil or omitted, a new specifi specifications copied into it. Otherwise, the specifications will be copied into the existing specifier in DEST. -If LOCALE is nil or 'all, all specifications will be copied. If LOCALE +If LOCALE is nil or `all', all specifications will be copied. If LOCALE is a particular locale, the specification for that particular locale will be copied. If LOCALE is a locale type, the specifications for all locales of that type will be copied. LOCALE can also be a list of locales, -locale types, and/or 'all; this is equivalent to calling `copy-specifier' +locale types, and/or `all'; this is equivalent to calling `copy-specifier' for each of the elements of the list. See `specifier-spec-list' for more information about LOCALE. ＠＠ -2339,7 +2341,7 ＠＠ the same as in `add-spec-to-specifier'.  /************************************************************************/ -/* Instancing */ +/* Instantiation */ /************************************************************************/ static Lisp_Object ＠＠ -2440,20 +2442,20 ＠＠ set_specifier_fallback (Lisp_Object spec DEFUN ("specifier-fallback", Fspecifier_fallback, 1, 1, 0, /* Return the fallback value for SPECIFIER. Fallback values are provided by the C code for certain built-in -specifiers to make sure that instancing won't fail even if all +specifiers to make sure that instantiation won't fail even if all specs are removed from the specifier, or to implement simple inheritance behavior (e.g. this method is used to ensure that -faces other than 'default inherit their attributes from 'default). +faces other than `default' inherit their attributes from `default'). By design, you cannot change the fallback value, and specifiers created with `make-specifier' will never have a fallback (although a similar, Lisp-accessible capability may be provided in the future to allow for inheritance). -The fallback value will be an inst-list that is instanced like +The fallback value will be an inst-list that is instantiated like any other inst-list, a specifier of the same type as SPECIFIER \(results in inheritance), or nil for no fallback. -When you instance a specifier, you can explicitly request that the +When you instantiate a specifier, you can explicitly request that the fallback not be consulted. (The C code does this, for example, when merging faces.) See `specifier-instance'. */ ＠＠ -2469,7 +2471,8 ＠＠ specifier_instance_from_inst_list (Lisp_ Lisp_Object domain, Lisp_Object inst_list, Error_Behavior errb, int no_quit, - Lisp_Object depth) + Lisp_Object depth, + Lisp_Object *instantiator) { /* This function can GC */ Lisp_Specifier *sp; ＠＠ -2498,7 +2501,9 ＠＠ specifier_instance_from_inst_list (Lisp_ if (device_matches_specifier_tag_set_p (device, tag_set)) { Lisp_Object val = XCDR (tagged_inst); + Lisp_Object the_instantiator = val; + if (HAS_SPECMETH_P (sp, instantiate)) val = call_with_suspended_errors ((lisp_fn_t) RAW_SPECMETH (sp, instantiate), ＠＠ -2509,6 +2514,8 ＠＠ specifier_instance_from_inst_list (Lisp_ { unbind_to (count); UNGCPRO; + if (instantiator) + *instantiator = the_instantiator; return val; } } ＠＠ -2532,7 +2539,8 ＠＠ specifier_instance_from_inst_list (Lisp_ Lisp_Object CIE_val = \ specifier_instance_from_inst_list (specifier, matchspec, \ domain, *CIE_inst_list, \ - errb, no_quit, depth); \ + errb, no_quit, depth, \ + instantiator); \ if (!UNBOUNDP (CIE_val)) \ return CIE_val; \ } \ ＠＠ -2544,10 +2552,12 ＠＠ specifier_instance_from_inst_list (Lisp_ as we can determine. In practice, when called from redisplay the arg will usually be a window and occasionally a frame. If triggered by a user call, who knows what it will usually be. */ -Lisp_Object -specifier_instance (Lisp_Object specifier, Lisp_Object matchspec, - Lisp_Object domain, Error_Behavior errb, int no_quit, - int no_fallback, Lisp_Object depth) + +static Lisp_Object +specifier_instance_1 (Lisp_Object specifier, Lisp_Object matchspec, + Lisp_Object domain, Error_Behavior errb, int no_quit, + int no_fallback, Lisp_Object depth, + Lisp_Object *instantiator) { Lisp_Object buffer = Qnil; Lisp_Object window = Qnil; ＠＠ -2555,6 +2565,9 ＠＠ specifier_instance (Lisp_Object specifie Lisp_Object device = Qnil; Lisp_Specifier *sp = XSPECIFIER (specifier); + if (instantiator) + *instantiator = Qunbound; + /* Attempt to determine buffer, window, frame, and device from the domain. */ /* #### get image instances out of domains! */ ＠＠ -2639,29 +2652,92 ＠＠ specifier_instance (Lisp_Object specifie assert (CONSP (sp->fallback)); return specifier_instance_from_inst_list (specifier, matchspec, domain, sp->fallback, errb, no_quit, - depth); + depth, instantiator); } #undef CHECK_INSTANCE_ENTRY Lisp_Object +specifier_instance (Lisp_Object specifier, Lisp_Object matchspec, + Lisp_Object domain, Error_Behavior errb, int no_quit, + int no_fallback, Lisp_Object depth) +{ + return specifier_instance_1 (specifier, matchspec, domain, errb, + no_quit, no_fallback, depth, NULL); +} + +Lisp_Object specifier_instance_no_quit (Lisp_Object specifier, Lisp_Object matchspec, Lisp_Object domain, Error_Behavior errb, int no_fallback, Lisp_Object depth) +{ + return specifier_instance_1 (specifier, matchspec, domain, errb, + 1, no_fallback, depth, NULL); +} + +static Lisp_Object +specifier_matching_foo (Lisp_Object specifier, + Lisp_Object matchspec, + Lisp_Object domain, + Lisp_Object default_, + Lisp_Object no_fallback, + int want_instantiator) { - return specifier_instance (specifier, matchspec, domain, errb, - 1, no_fallback, depth); + Lisp_Object instance, instantiator; + + CHECK_SPECIFIER (specifier); + if (!UNBOUNDP (matchspec)) + check_valid_specifier_matchspec (matchspec, + XSPECIFIER (specifier)->methods, + ERROR_ME); + domain = decode_domain (domain); + + instance = specifier_instance_1 (specifier, matchspec, domain, ERROR_ME, + 0, !NILP (no_fallback), Qzero, + &instantiator); + return UNBOUNDP (instance) ? default_ : want_instantiator ? instantiator : + instance; } DEFUN ("specifier-instance", Fspecifier_instance, 1, 4, 0, /* Instantiate SPECIFIER (return its value) in DOMAIN. If no instance can be generated for this domain, return DEFAULT. -DOMAIN should be a window, frame, or device. Other values that are legal +DOMAIN is nearly always a window (defaulting to the selected window if +omitted), but can be a window, frame, or device. Other values that are legal as a locale (e.g. a buffer) are not valid as a domain because they do not provide enough information to identify a particular device (see -`valid-specifier-domain-p'). DOMAIN defaults to the selected window -if omitted. +`valid-specifier-domain-p'). Window domains are used internally in nearly +all circumstances when computing specifier instances of display properties. +Frame domains are used in a few circumstances (such as when computing the +geometry of a frame based on properties such as the toolbar widths), and +device domains are rarely if ever used internally. + +This function looks through the specifications in SPECIFIER that correspond +to DOMAIN, from most specific (specifications for DOMAIN itself) to most +general (global specifications), for matching instantiators, and attempts +to compute an instance value for each instantiator found. The first +successfully computed value is returned. The corresponding instantiator +can be returned using `specifier-instantiator'. + +A specifier is a generalized object for controlling the value of a property -- +typically, but not necessarily, a display-related property -- that can vary +over particular buffers, frames, device types, etc. + +A fundamental distinction must be made between the specification of a +property's value, and the resulting value itself. This distinction is +clearest in the case of an image -- the specification describes the source +of the image (for example, a file of JPEG data), and the resulting value +encapsulates a window-system object describing the image as displayed on a +particular device (for example, a particular X display). The specification +might also be an instruction of the form "use the background pixmap of the +`modeline' face". A similar mapping exists between color strings and +color-instance objects, and font strings and font-instance objects. In +some cases, the specification and the resulting value are of the same type, +but the distinction is still logically made. +The specification of a value is called an instantiator, and the resulting +value the instance. + "Instantiating" a specifier in a particular domain means determining the specifier's "value" in that domain. This is accomplished by searching through the specifications in the specifier that correspond ＠＠ -2673,7 +2749,7 ＠＠ specifications are searched for as follo 2. A specification whose locale is the window's buffer; 3. A specification whose locale is the window's frame; 4. A specification whose locale is the window's frame's device; -5. A specification whose locale is 'global. +5. A specification whose locale is `global'. If all of those fail, then the C-code-provided fallback value for this specifier is consulted (see `specifier-fallback'). If it is ＠＠ -2701,20 +2777,32 ＠＠ trying to debug why particular instantia The returned value is dependent on the type of specifier. For example, for a font specifier (as returned by the `face-font' function), the returned value will be a font-instance object. For glyphs, the returned value -will be a string, pixmap, or subwindow. +will be an image-instance object. See also `specifier-matching-instance'. */ (specifier, domain, default_, no_fallback)) { - Lisp_Object instance; + return specifier_matching_foo (specifier, Qunbound, domain, default_, + no_fallback, 0); +} - CHECK_SPECIFIER (specifier); - domain = decode_domain (domain); +DEFUN ("specifier-instantiator", Fspecifier_instantiator, 1, 4, 0, /* +Return instantiator that would be used to instantiate SPECIFIER in DOMAIN. +If no instance can be generated for this domain, return DEFAULT. + +DOMAIN should be a window, frame, or device. Other values that are legal +as a locale (e.g. a buffer) are not valid as a domain because they do not +provide enough information to identify a particular device (see +`valid-specifier-domain-p'). DOMAIN defaults to the selected window +if omitted. - instance = specifier_instance (specifier, Qunbound, domain, ERROR_ME, 0, - !NILP (no_fallback), Qzero); - return UNBOUNDP (instance) ? default_ : instance; +See `specifier-instance' for more information about the instantiation process. +*/ + (specifier, domain, default_, no_fallback)) +{ + return specifier_matching_foo (specifier, Qunbound, domain, default_, + no_fallback, 1); } DEFUN ("specifier-matching-instance", Fspecifier_matching_instance, 2, 5, 0, /* ＠＠ -2745,46 +2833,86 ＠＠ dependent on the particular type of spec */ (specifier, matchspec, domain, default_, no_fallback)) { - Lisp_Object instance; + return specifier_matching_foo (specifier, matchspec, domain, default_, + no_fallback, 0); +} - CHECK_SPECIFIER (specifier); - check_valid_specifier_matchspec (matchspec, XSPECIFIER (specifier)->methods, - ERROR_ME); - domain = decode_domain (domain); +DEFUN ("specifier-matching-instantiator", Fspecifier_matching_instantiator, + 2, 5, 0, /* +Return instantiator for instance of SPECIFIER in DOMAIN that matches MATCHSPEC. +If no instance can be generated for this domain, return DEFAULT. - instance = specifier_instance (specifier, matchspec, domain, ERROR_ME, - 0, !NILP (no_fallback), Qzero); - return UNBOUNDP (instance) ? default_ : instance; +This function is identical to `specifier-matching-instance' but returns +the instantiator used to generate the instance, rather than the actual +instance. +*/ + (specifier, matchspec, domain, default_, no_fallback)) +{ + return specifier_matching_foo (specifier, matchspec, domain, default_, + no_fallback, 1); } -DEFUN ("specifier-instance-from-inst-list", Fspecifier_instance_from_inst_list, - 3, 4, 0, /* -Attempt to convert a particular inst-list into an instance. -This attempts to instantiate INST-LIST in the given DOMAIN, -as if INST-LIST existed in a specification in SPECIFIER. If -the instantiation fails, DEFAULT is returned. In most circumstances, -you should not use this function; use `specifier-instance' instead. -*/ - (specifier, domain, inst_list, default_)) +static Lisp_Object +specifier_matching_foo_from_inst_list (Lisp_Object specifier, + Lisp_Object matchspec, + Lisp_Object domain, + Lisp_Object inst_list, + Lisp_Object default_, + int want_instantiator) { Lisp_Object val = Qunbound; Lisp_Specifier *sp = XSPECIFIER (specifier); struct gcpro gcpro1; Lisp_Object built_up_list = Qnil; + Lisp_Object instantiator; CHECK_SPECIFIER (specifier); + if (!UNBOUNDP (matchspec)) + check_valid_specifier_matchspec (matchspec, + XSPECIFIER (specifier)->methods, + ERROR_ME); check_valid_domain (domain); check_valid_inst_list (inst_list, sp->methods, ERROR_ME); GCPRO1 (built_up_list); built_up_list = build_up_processed_list (specifier, domain, inst_list); if (!NILP (built_up_list)) - val = specifier_instance_from_inst_list (specifier, Qunbound, domain, + val = specifier_instance_from_inst_list (specifier, matchspec, domain, built_up_list, ERROR_ME, - 0, Qzero); + 0, Qzero, &instantiator); UNGCPRO; - return UNBOUNDP (val) ? default_ : val; + return UNBOUNDP (val) ? default_ : want_instantiator ? instantiator : val; + +} + +DEFUN ("specifier-instance-from-inst-list", Fspecifier_instance_from_inst_list, + 3, 4, 0, /* +Attempt to convert a particular inst-list into an instance. +This attempts to instantiate INST-LIST in the given DOMAIN, +as if INST-LIST existed in a specification in SPECIFIER. If +the instantiation fails, DEFAULT is returned. In most circumstances, +you should not use this function; use `specifier-instance' instead. +*/ + (specifier, domain, inst_list, default_)) +{ + return specifier_matching_foo_from_inst_list (specifier, Qunbound, + domain, inst_list, default_, + 0); } +DEFUN ("specifier-instantiator-from-inst-list", Fspecifier_instantiator_from_inst_list, + 3, 4, 0, /* +Attempt to convert an inst-list into an instance; return instantiator. +This is identical to `specifier-instance-from-inst-list' but returns +the instantiator used to generate the instance, rather than the instance +itself. +*/ + (specifier, domain, inst_list, default_)) +{ + return specifier_matching_foo_from_inst_list (specifier, Qunbound, + domain, inst_list, default_, + 1); +} + DEFUN ("specifier-matching-instance-from-inst-list", Fspecifier_matching_instance_from_inst_list, 4, 5, 0, /* ＠＠ -2800,24 +2928,24 ＠＠ works. */ (specifier, matchspec, domain, inst_list, default_)) { - Lisp_Object val = Qunbound; - Lisp_Specifier *sp = XSPECIFIER (specifier); - struct gcpro gcpro1; - Lisp_Object built_up_list = Qnil; + return specifier_matching_foo_from_inst_list (specifier, matchspec, + domain, inst_list, default_, + 0); +} - CHECK_SPECIFIER (specifier); - check_valid_specifier_matchspec (matchspec, XSPECIFIER (specifier)->methods, - ERROR_ME); - check_valid_domain (domain); - check_valid_inst_list (inst_list, sp->methods, ERROR_ME); - GCPRO1 (built_up_list); - built_up_list = build_up_processed_list (specifier, domain, inst_list); - if (!NILP (built_up_list)) - val = specifier_instance_from_inst_list (specifier, matchspec, domain, - built_up_list, ERROR_ME, - 0, Qzero); - UNGCPRO; - return UNBOUNDP (val) ? default_ : val; +DEFUN ("specifier-matching-instantiator-from-inst-list", + Fspecifier_matching_instantiator_from_inst_list, + 4, 5, 0, /* +Attempt to convert an inst-list into an instance; return instantiator. +This is identical to `specifier-matching-instance-from-inst-list' but returns +the instantiator used to generate the instance, rather than the instance +itself. +*/ + (specifier, matchspec, domain, inst_list, default_)) +{ + return specifier_matching_foo_from_inst_list (specifier, matchspec, + domain, inst_list, default_, + 1); }  ＠＠ -3058,10 +3186,10 ＠＠ DEFINE_SPECIFIER_TYPE (generic); "instance computed from it is likewise any kind of Lisp object. The\n" "SPECIFIER-DATA should be an alist of methods governing how the specifier\n" "works. All methods are optional, and reasonable default methods will be\n" -"provided. Currently there are two defined methods: 'instantiate and\n" -"'validate.\n" +"provided. Currently there are two defined methods: `instantiate' and\n" +"`validate'.\n" "\n" -"'instantiate specifies how to do the instantiation; if omitted, the\n" +"`instantiate' specifies how to do the instantiation; if omitted, the\n" "instantiator itself is simply returned as the instance. The method\n" "should be a function that accepts three parameters (a specifier, the\n" "instantiator that matched the domain being instantiated over, and that\n" ＠＠ -3073,7 +3201,7 ＠＠ DEFINE_SPECIFIER_TYPE (generic); "the locale corresponding to the passed instantiator could be the window's\n" "buffer or frame).\n" "\n" -"'validate specifies whether a given instantiator is valid; if omitted,\n" +"`validate' specifies whether a given instantiator is valid; if omitted,\n" "all instantiators are considered valid. It should be a function of\n" "two arguments: an instantiator and a flag CAN-SIGNAL-ERROR. If this\n" "flag is false, the function must simply return t or nil indicating\n" ＠＠ -3271,9 +3399,13 ＠＠ syms_of_specifier (void) DEFSUBR (Fvalid_specifier_matchspec_p); DEFSUBR (Fspecifier_fallback); DEFSUBR (Fspecifier_instance); + DEFSUBR (Fspecifier_instantiator); DEFSUBR (Fspecifier_matching_instance); + DEFSUBR (Fspecifier_matching_instantiator); DEFSUBR (Fspecifier_instance_from_inst_list); + DEFSUBR (Fspecifier_instantiator_from_inst_list); DEFSUBR (Fspecifier_matching_instance_from_inst_list); + DEFSUBR (Fspecifier_matching_instantiator_from_inst_list); DEFSUBR (Fset_specifier_dirty_flag); DEFSUBR (Fgeneric_specifier_p); cvs server: Diffing . cvs server: Diffing man cvs server: Diffing man/lispref Index: man/lispref/glyphs.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/glyphs.texi,v retrieving revision 1.9 diff -u -p -r1.9 glyphs.texi --- man/lispref/glyphs.texi 2004/09/22 02:06:27 1.9 +++ man/lispref/glyphs.texi 2005/09/26 08:34:55 ＠＠ -88,25 +88,25 ＠＠ more information about specifier locales ＠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 ＠＠ instantiators, which are just descriptio 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 ＠＠ 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.). ＠＠ -372,11 +372,11 ＠＠ are usable with each, and the kinds of i ＠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 ＠＠ XBM file. ＠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 ＠＠ used to generate the alist. 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 ＠＠ 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 ＠＠ -539,7 +539,7 ＠＠ The name of a file containing standard-f ＠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 ＠＠ Other window systems may have different 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 ＠＠ For icons: ＠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 ＠＠ A widget for controlling the positioning 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 ＠＠ and ＠code{:pixel-height} (positive integ (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 ＠＠ the image will always be displayed as te ＠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 ＠＠ This function returns non-＠code{nil} if ＠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 ＠＠ Return non-＠code{nil} if ＠var{object} is 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 ＠＠ 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 ＠＠ -1104,7 +1104,7 ＠＠ vector. The vector's first element spec 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 ＠＠ search dialog is formatted using layouts 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 ＠＠ 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}. ＠＠ -2065,7 +2065,7 ＠＠ The parameters passed to ＠code{make-glyp 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 ＠＠ To programmatically query whether or not 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: Index: man/lispref/lispref.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/lispref.texi,v retrieving revision 1.22 diff -u -p -r1.22 lispref.texi --- man/lispref/lispref.texi 2005/06/19 20:49:47 1.22 +++ man/lispref/lispref.texi 2005/09/26 08:34:56 ＠＠ -941,15 +941,15 ＠＠ Specifiers (under user control) in a wide variety of contexts. * Specifiers In-Depth:: Gory details about specifier innards. -* Specifier Instancing:: Instancing means obtaining the ``value'' of +* Specifier Instantiation:: Instantiation means obtaining the ``value'' of a specifier in a particular context. * Specifier Types:: Specifiers come in different flavors. * Adding Specifications:: Specifications control a specifier's ``value'' by giving conditions under which a particular value is valid. * Retrieving Specifications:: Querying a specifier's specifications. -* Specifier Instancing Functions:: - Functions to instance a specifier. +* Specifier Instantiation Functions:: + Functions to instantiate a specifier. * Specifier Examples:: Making all this stuff clearer. * Creating Specifiers:: Creating specifiers for your own use. * Specifier Validation Functions:: ＠＠ -977,21 +977,21 ＠＠ Faces Fonts * Font Specifiers:: Specifying how a font will appear. -* Font Instances:: What a font specifier gets instanced as. +* Font Instances:: What a font specifier gets instantiated as. * Font Instance Names:: The name of a font instance. * Font Instance Size:: The size of a font instance. * Font Instance Characteristics:: Display characteristics of font instances. * Font Convenience Functions:: Convenience functions that automatically - instance and retrieve the properties + instantiate and retrieve the properties of a font specifier. Colors * Color Specifiers:: Specifying how a color will appear. -* Color Instances:: What a color specifier gets instanced as. +* Color Instances:: What a color specifier gets instantiated as. * Color Instance Properties:: Properties of color instances. * Color Convenience Functions:: Convenience functions that automatically - instance and retrieve the properties + instantiate and retrieve the properties of a color specifier. Glyphs ＠＠ -1004,22 +1004,14 ＠＠ Glyphs Images -* 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. Image Instances -* Image Instance Types:: Each image instances has a particular type. -* Image Instance Functions:: Functions for working with image instances. - -Using Glyphs - - -Image Instances - -* 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. Using Glyphs Index: man/lispref/specifiers.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/specifiers.texi,v retrieving revision 1.14 diff -u -p -r1.14 specifiers.texi --- man/lispref/specifiers.texi 2004/06/18 07:18:40 1.14 +++ man/lispref/specifiers.texi 2005/09/26 08:34:56 ＠＠ -14,7 +14,7 ＠＠ device. The value of many built-in prop foreground, background, and such properties of a face and variables such as ＠code{modeline-shadow-thickness} and ＠code{top-toolbar-height}, is actually a specifier object. The -specifier object, in turn, is ``instanced'' in a particular situation +specifier object, in turn, is ``instantiated'' in a particular situation to yield the real value of the property in the current context. ＠defun specifierp object ＠＠ -28,7 +28,7 ＠＠ This function returns non-＠code{nil} if of contexts. * Simple Specifier Usage:: Getting started with specifiers. * Specifiers In-Depth:: Gory details about specifier innards. -* Specifier Instancing:: Instancing means obtaining the ``value'' of +* Specifier Instantiation:: Instantiation means obtaining the ``value'' of a specifier in a particular context. * Specifier Types:: Specifiers come in different flavors. * Adding Specifications:: Specifications control a specifier's ``value'' ＠＠ -36,8 +36,8 ＠＠ This function returns non-＠code{nil} if particular value is valid. * Retrieving Specifications:: Querying a specifier's specifications. * Specifier Tag Functions:: Working with specifier tags. -* Specifier Instancing Functions:: - Functions to instance a specifier. +* Specifier Instantiation Functions:: + Functions to instantiate a specifier. * Specifier Examples:: Making all this stuff clearer. * Creating Specifiers:: Creating specifiers for your own use. * Specifier Validation Functions:: ＠＠ -89,12 +89,12 ＠＠ is available. The complex calculations transparent to both user and programmer. You ask for what you want; it's up to XEmacs to provide it, or a reasonable approximation. -We call such a declaration a ＠dfn{specification}. A ＠dfn{specification} -applies in a particular ＠dfn{locale}, which is a window, buffer, frame, -device, or the global locale. The value part of the specification is -called an ＠dfn{instantiator}. The process of determining the value in a -particular context, or ＠dfn{domain}, is called ＠dfn{instantiation} or -＠dfn{instancing}. A domain is a window, frame, or device. +We call such a declaration a ＠dfn{specification}. A +＠dfn{specification} applies in a particular ＠dfn{locale}, which is a +window, buffer, frame, device, or the global locale. The value part +of the specification is called an ＠dfn{instantiator}. The process of +determining the value in a particular context, or ＠dfn{domain}, is +called ＠dfn{instantiation}. A domain is a window, frame, or device. The difference between ＠dfn{locale} and ＠dfn{domain} is somewhat subtle. You may think of a locale as a class of domains, which may span ＠＠ -199,8 +199,8 ＠＠ a program manipulates specifications, cl desirable. In the case of the toolbar descriptor, it turns out that these are the -same: the instancing process is trivial. However, many specifications -have non-trivial instancing. Compare the results of the following forms +same: the instantiation process is trivial. However, many specifications +have non-trivial instantiation. Compare the results of the following forms on my system. (The ＠samp{(cdr (first ...))} form is due to my use of Mule. On non-Mule XEmacsen, just use ＠code{specifier-specs}.) ＠＠ -216,16 +216,16 ＠＠ In this case, ＠code{specifier-instance} programs can't work on it, they can only pass it around. Worse, in some environments the instantiation will fail, resulting in a different value (when another instantiation succeeds), or worse yet, an error, if all -attempts to instance the specifier fail. ＠code{specifier-instance} is +attempts to instantiate the specifier fail. ＠code{specifier-instance} is context-dependent, even for the exact same specification. ＠code{specifier-specs} is deterministic, and only depends on the specifications. Note that in the toolbar-changing code we operate in the global locale. This means that narrower locales, if they have specifications, will -shadow our changes. (Specifier instancing does not merge +shadow our changes. (Specifier instantiation does not merge specifications. It selects the "highest-priority successful -specification" and instances that.) +specification" and instantiates that.) In fact, in our example, it seems pretty likely that different buffers ＠emph{should} have different buttons. (The icon can be the same, but ＠＠ -283,7 +283,7 ＠＠ Specifications}, for documentation of ＠c ＠cindex domain (in a specifier) ＠cindex locale (in a specifier) ＠cindex instantiator (in a specifier) -＠cindex instancing (in a specifier) +＠cindex instantiation (in a specifier) ＠cindex instance (in a specifier) ＠cindex inst-list (in a specifier) ＠cindex inst-pair (in a specifier) ＠＠ -293,7 +293,7 ＠＠ Specifications}, for documentation of ＠c ＠cindex specifier, domain ＠cindex specifier, locale ＠cindex specifier, instantiator -＠cindex specifier, instancing +＠cindex specifier, instantiation ＠cindex specifier, instance ＠cindex specifier, inst-list ＠cindex specifier, inst-pair ＠＠ -335,11 +335,11 ＠＠ particular situation?'' This involves lo to see which ones apply to this particular situation, and perhaps preferring one over another if more than one applies. In specifier terminology, a ``particular situation'' is called a ＠dfn{domain}, and -determining its value in a particular domain is called ＠dfn{instancing}. +determining its value in a particular domain is called ＠dfn{instantiation}. Most of the time, a domain is identified by a particular window. For example, if the redisplay engine is drawing text in the default face in a particular window, it retrieves the specifier for the foreground color -of the default face and ＠dfn{instances} it in the domain given by that +of the default face and ＠dfn{instantiates} it in the domain given by that window; in other words, it asks the specifier, ``What is your value in this window?''. ＠＠ -372,28 +372,28 ＠＠ All tags in a tag set must match a devic to be instantiable over that device. (A null tag set is perfectly valid, and trivially matches all devices.) -＠c #### don't we have more device types now, gtk, ms-windows, mac-carbon? -The valid device types (normally ＠code{x}, ＠code{tty}, and -＠code{stream}) and device classes (normally ＠code{color}, -＠code{grayscale}, and ＠code{mono}) can always be used as tags, and match -devices of the associated type or class (＠pxref{Consoles and Devices}). -User-defined tags may be defined, with an optional predicate specified. -An application can create its own tag, use it to mark all its +The valid device types (normally ＠code{x}, ＠code{tty}, ＠code{stream}, +＠code{mswindows}, ＠code{msprinter}, and possibly ＠code{carbon}) and +device classes (normally ＠code{color}, ＠code{grayscale}, and +＠code{mono}) can always be used as tags, and match devices of the +associated type or class (＠pxref{Consoles and Devices}). User-defined +tags may be defined, with an optional predicate specified. An +application can create its own tag, use it to mark all its instantiators, and be fairly confident that it will not interfere with other applications that modify the same specifier---Functions that add a specification to a specifier usually only overwrite existing inst-pairs with the same tag set as was given, and a particular tag or tag set can be specified when removing instantiators. -When a specifier is instanced in a domain, both the locale and the tag +When a specifier is instantiated in a domain, both the locale and the tag set can be viewed as specifying necessary conditions that must apply in that domain for an instantiator to be considered as a possible result of -the instancing. More specific locales always override more general +the instantiation. More specific locales always override more general locales (thus, there is no particular ordering of the specifications in a specifier); however, the tag sets are simply considered in the order that the inst-pairs occur in the specification's inst-list. -Note also that the actual object that results from the instancing +Note also that the actual object that results from the instantiation (called an ＠dfn{instance object}) may not be the same as the instantiator from which it was derived. For some specifier types (such as integer specifiers and boolean specifiers), the instantiator will be returned ＠＠ -410,12 +410,12 ＠＠ device, etc. Furthermore, this conversi might fail---a font or color might not exist on a particular device, for example. -＠node Specifier Instancing -＠section How a Specifier Is Instanced +＠node Specifier Instantiation +＠section How a Specifier Is Instantiated ＠cindex fallback (in a specifier) ＠cindex specifier, fallback -Instancing of a specifier in a particular window domain proceeds as +Instantiation of a specifier in a particular window domain proceeds as follows: ＠itemize ＠bullet ＠＠ -437,7 +437,7 ＠＠ match the device.) If a matching tag set is found, the corresponding instantiator is passed to the specifier's instantiation method, which is specific to the type of the specifier. If it succeeds, the resulting instance object is -returned as the result of the instancing and the instancing is done. +returned as the result of the instantiation and the instantiation is done. Otherwise, the operation continues, looking for another matching inst-pair in the current specification. ＠item ＠＠ -446,36 +446,36 ＠＠ specification, the search starts over, l as in the first step above. ＠item If all specifications are exhausted and no instance object can be -derived, the instancing fails. (Actually, this is not completely true. +derived, the instantiation fails. (Actually, this is not completely true. Some specifier objects for built-in properties have a ＠dfn{fallback} value, which is either an inst-list or another specifier object, that is -consulted if the instancing is about to fail. If it is an inst-list, +consulted if the instantiation is about to fail. If it is an inst-list, the searching proceeds using the inst-pairs in that list. If it is a -specifier, the entire instancing starts over using that specifier +specifier, the entire instantiation starts over using that specifier instead of the given one. Fallback values are set by the C code and cannot be modified, except perhaps indirectly, using any Lisp functions. The purpose of them is to supply some values to make sure that -instancing of built-in properties can't fail and to implement some basic +instantiation of built-in properties can't fail and to implement some basic specifier inheritance, such as the fact that faces inherit their properties from the ＠code{default} face.) ＠end itemize -It is also possible to instance a specifier over a frame domain or +It is also possible to instantiate a specifier over a frame domain or device domain instead of over a window domain. The C code, for example, -instances the ＠code{top-toolbar-height} variable over a frame domain in -order to determine the height of a frame's top toolbar. Instancing over -a frame or device is similar to instancing over a window except that +instantiates the ＠code{top-toolbar-height} variable over a frame domain in +order to determine the height of a frame's top toolbar. Instantiation over +a frame or device is similar to instantiation over a window except that specifications for locales that cannot be derived from the domain are -ignored. Specifically, instancing over a frame looks first for frame -locales, then device locales, then the ＠code{global} locale. Instancing +ignored. Specifically, instantiation over a frame looks first for frame +locales, then device locales, then the ＠code{global} locale. Instantiation over a device domain looks only for device locales and the ＠code{global} locale. -Note that specifiers are instanced on ＠emph{every} redisplay. (This is +Note that specifiers are instantiated on ＠emph{every} redisplay. (This is the concept; of course the implementation keeps track of changes and -doesn't reinstance unchanged specifiers.) That means that changes in +doesn't reinstantiate unchanged specifiers.) That means that changes in specifiers controlling appearance are reflected immediately in the UI. -Also, since specifiers are instanced completely, removing a +Also, since specifiers are instantiated completely, removing a specification can be just as effective as adding one. ＠emph{E.g.}, Giacomo Boffi wanted a modeline that indicates whether the ＠＠ -1109,7 +1109,7 ＠＠ no instantiators at all. ＠defun specifier-fallback specifier This function returns the fallback value for ＠var{specifier}. Fallback values are provided by the C code for certain built-in specifiers to -make sure that instancing won't fail even if all specs are removed from +make sure that instantiation won't fail even if all specs are removed from the specifier, or to implement simple inheritance behavior (e.g. this method is used to ensure that faces other than ＠code{default} inherit their attributes from ＠code{default}). By design, you cannot change the ＠＠ -1117,11 +1117,11 ＠＠ fallback value, and specifiers created w never have a fallback (although a similar, Lisp-accessible capability may be provided in the future to allow for inheritance). -The fallback value will be an inst-list that is instanced like +The fallback value will be an inst-list that is instantiated like any other inst-list, a specifier of the same type as ＠var{specifier} (results in inheritance), or ＠code{nil} for no fallback. -When you instance a specifier, you can explicitly request that the +When you instantiate a specifier, you can explicitly request that the fallback not be consulted. (The C code does this, for example, when merging faces.) See ＠code{specifier-instance}. ＠end defun ＠＠ -1145,8 +1145,8 ＠＠ Each tag has a predicate associated with that tag applies to a particular device. The tags which are device types and classes match devices of that type or class. User-defined tags can have any predicate, or none (meaning that all devices match). -When attempting to instance a specifier, a particular instantiator is -only considered if the device of the domain being instanced over matches +When attempting to instantiate a specifier, a particular instantiator is +only considered if the device of the domain being instantiated over matches all tags in the tag set attached to that instantiator. Most of the time, a tag set is not specified, and the instantiator gets ＠＠ -1201,8 +1201,8 ＠＠ This includes the built-in ones (the dev This function returns the predicate for the given specifier tag. ＠end defun -＠node Specifier Instancing Functions -＠section Functions for Instancing a Specifier +＠node Specifier Instantiation Functions +＠section Functions for Instantiating a Specifier ＠defun specifier-instance specifier &optional domain default no-fallback This function instantiates ＠var{specifier} (returns its value) in ＠＠ -1605,7 +1605,7 ＠＠ Display Table}). ＠defun valid-specifier-domain-p domain This function returns non-＠code{nil} if ＠var{domain} is a valid -specifier domain. A domain is used to instance a specifier +specifier domain. A domain is used to instantiate a specifier (i.e. determine the specifier's value in that domain). Valid domains are a window, frame, or device. (＠code{nil} is not valid.) ＠end defun