Mercurial > hg > xemacs-beta

comparison man/lispref/specifiers.texi @ 1875:ec2d1e636272

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2004-01-23 10:00:20 by stephent] specifier docs <87u12nugu7.fsf@tleepslib.sk.tsukuba.ac.jp>
author stephent
date Fri, 23 Jan 2004 10:00:34 +0000
parents 11812ec0334c
children 6ae20abf892d
comparison
equal deleted inserted replaced
1874:31c960994dba 1875:ec2d1e636272
76 Specifiers generalize both buffer- and frame-local properties. 76 Specifiers generalize both buffer- and frame-local properties.
77 Specifiers vary according to the @emph{display} context. Font-lock 77 Specifiers vary according to the @emph{display} context. Font-lock
78 keywords in a buffer will be the same no matter which window the 78 keywords in a buffer will be the same no matter which window the
79 buffer is displayed in, but windows on TTY devices will simply not be 79 buffer is displayed in, but windows on TTY devices will simply not be
80 capable of the flexibility that windows on modern GUI devices are. 80 capable of the flexibility that windows on modern GUI devices are.
81 Specifiers provide a way for the programmer to @emph{declare} that a 81 Specifiers provide a way for the programmer to @emph{declare} that an
82 emphasized text should be italic on GUI devices and inverse video on 82 emphasized text should be italic on GUI devices and inverse video on
83 TTYs. They also provide a way for the programmer to declare 83 TTYs. They also provide a way for the programmer to declare
84 fallbacks, so that a color specified as ``chartreuse'' where possible 84 fallbacks, so that a color specified as ``chartreuse'' where possible
85 can fall back to ``yellow'' on devices where only ANSI (4-bit) color 85 can fall back to ``yellow'' on devices where only ANSI (4-bit) color
86 is available. The complex calculations and device querying are 86 is available. The complex calculations and device querying are
97 The difference between @dfn{locale} and @dfn{domain} is somewhat subtle. 97 The difference between @dfn{locale} and @dfn{domain} is somewhat subtle.
98 You may think of a locale as a class of domains, which may span 98 You may think of a locale as a class of domains, which may span
99 different devices. Since the specification is abstract (a Lisp form), 99 different devices. Since the specification is abstract (a Lisp form),
100 you can state it without reference to a device. On the other hand, when 100 you can state it without reference to a device. On the other hand, when
101 you instantiate a specification, you must know the type of the device. 101 you instantiate a specification, you must know the type of the device.
102 It is useless to specify that ``blue mean italic'' on a monochrome 102 It is useless to specify that ``blue means emphasis'' on a monochrome
103 device. Thus instantiation requires specification of the device on 103 device. Thus instantiation requires specification of the device on
104 which it will be rendered. 104 which it will be rendered.
105 105
106 Thus a @dfn{specifier} allows a great deal of flexibility in 106 Thus a @dfn{specifier} allows a great deal of flexibility in
107 controlling exactly what value a property has in which circumstances. 107 controlling exactly what value a property has in which circumstances.
108 It is most commonly used for display properties, such as an image or 108 Specifiers are most commonly used for display properties, such as an image or
109 the foreground color of a face. As a simple example, you can specify 109 the foreground color of a face. As a simple example, you can specify
110 that the foreground of the default face be 110 that the foreground of the default face be
111 111
112 @itemize @bullet 112 @itemize @bullet
113 @item 113 @item
139 @cindex toolbar button, adding 139 @cindex toolbar button, adding
140 140
141 A useful specifier application is adding a button to a toolbar. XEmacs 141 A useful specifier application is adding a button to a toolbar. XEmacs
142 provides several toolbars, one along each edge of the frame. Normally 142 provides several toolbars, one along each edge of the frame. Normally
143 only one is used at a time, the default. The default toolbar is 143 only one is used at a time, the default. The default toolbar is
144 actually a specifier object which is the value of @code{default-toolbar}. 144 actually a specifier object which is the value of
145 @code{default-toolbar}. @xref{Toolbar Intro}.
145 146
146 The specification of a toolbar is simple: it is a list of buttons. 147 The specification of a toolbar is simple: it is a list of buttons.
147 Each button is a vector with four elements: an icon, a command, the 148 Each button is a vector with four elements: an icon, a command, the
148 enabled flag, and a help string. Let's retrieve the instance of the 149 enabled flag, and a help string. Let's retrieve the instance of the
149 toolbar you see in the selected frame. 150 toolbar you see in the selected frame.
680 681
681 @var{how-to-add} specifies how to combine the new specifications with 682 @var{how-to-add} specifies how to combine the new specifications with
682 the existing ones, and has the same semantics as for 683 the existing ones, and has the same semantics as for
683 @code{add-spec-to-specifier}. 684 @code{add-spec-to-specifier}.
684 685
685 In many circumstances, the higher-level function @code{set-specifier} is 686 The higher-level function @code{set-specifier} is often
686 more convenient and should be used instead. 687 more convenient because it allows abbreviations of spec-lists to be used
688 instead of the heavily nested canonical syntax. However, one should
689 take great care in using them with specifiers types which can have lists
690 as instantiators, such as toolbar specifiers and generic specifiers. In
691 those cases it's probably best to use @code{add-spec-to-specifier} or
692 @code{add-spec-list-to-specifier}.
687 @end defun 693 @end defun
688 694
689 @defspec let-specifier specifier-list &rest body 695 @defspec let-specifier specifier-list &rest body
690 This special form temporarily adds specifications to specifiers, 696 This special form temporarily adds specifications to specifiers,
691 evaluates forms in @var{body} and restores the specifiers to their 697 evaluates forms in @var{body} and restores the specifiers to their
731 can be a single instantiator or tagged instantiator (added as a global 737 can be a single instantiator or tagged instantiator (added as a global
732 specification), a list of tagged and/or untagged instantiators (added as 738 specification), a list of tagged and/or untagged instantiators (added as
733 a global specification), a cons of a locale and instantiator or locale 739 a global specification), a cons of a locale and instantiator or locale
734 and instantiator list, a list of such conses, or nearly any other 740 and instantiator list, a list of such conses, or nearly any other
735 reasonable form. More specifically, @var{value} can be anything 741 reasonable form. More specifically, @var{value} can be anything
736 accepted by @code{canonicalize-spec-list}. 742 accepted by @code{canonicalize-spec-list} (described below).
737 743
738 @var{locale}, @var{tag-set}, and @var{how-to-add} are the same as in 744 @var{locale}, @var{tag-set}, and @var{how-to-add} are the same as in
739 @code{add-spec-to-specifier}. 745 @code{add-spec-to-specifier}.
740 746
741 Note that @code{set-specifier} is exactly complementary to 747 Note that @code{set-specifier} is exactly complementary to
744 @code{specifier-specs} will return @code{nil} (meaning no specs) and 750 @code{specifier-specs} will return @code{nil} (meaning no specs) and
745 @code{set-specifier} will interpret the @code{nil} as meaning ``I'm 751 @code{set-specifier} will interpret the @code{nil} as meaning ``I'm
746 adding a global instantiator and its value is @code{nil}''), or in 752 adding a global instantiator and its value is @code{nil}''), or in
747 strange cases where there is an ambiguity between a spec-list and an 753 strange cases where there is an ambiguity between a spec-list and an
748 inst-list, etc. (The built-in specifier types are designed in such a way 754 inst-list, etc. (The built-in specifier types are designed in such a way
749 as to avoid any such ambiguities.) 755 as to avoid any such ambiguities.) For robust code,
756 @code{set-specifier} should probably be avoided for specifier types
757 which accept lists as instantiators (currently toolbar specifiers and
758 generic specifiers).
750 759
751 If you want to work with spec-lists, you should probably not use these 760 If you want to work with spec-lists, you should probably not use these
752 functions, but should use the lower-level functions 761 functions, but should use the lower-level functions
753 @code{specifier-spec-list} and @code{add-spec-list-to-specifier}. These 762 @code{specifier-spec-list} and @code{add-spec-list-to-specifier}. These
754 functions always work with fully-qualified spec-lists; thus, there is no 763 functions always work with fully-qualified spec-lists; thus, there is no
806 This function canonicalizes the given @var{spec-list} (a list of 815 This function canonicalizes the given @var{spec-list} (a list of
807 specifications). 816 specifications).
808 817
809 @var{specifier-type} specifies the type of specifier that this 818 @var{specifier-type} specifies the type of specifier that this
810 @var{spec-list} will be used for. 819 @var{spec-list} will be used for.
820
821 If @var{noerror} is @code{nil}, signal an error if the spec-list is
822 invalid; otherwise return @code{t} for an invalid spec-list. (Note that
823 this cannot be confused with a canonical spec-list.)
811 824
812 Canonicalizing means converting to the full form for a spec-list, i.e. 825 Canonicalizing means converting to the full form for a spec-list, i.e.
813 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}. 826 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}.
814 This function accepts a possibly abbreviated specification or a list of 827 This function accepts a possibly abbreviated specification or a list of
815 such things. (See @code{canonicalize-spec}.) This is the function used 828 such things. (See @code{canonicalize-spec}.) This is the function used
818 831
819 This function tries extremely hard to resolve any ambiguities, 832 This function tries extremely hard to resolve any ambiguities,
820 and the built-in specifier types (font, image, toolbar, etc.) are 833 and the built-in specifier types (font, image, toolbar, etc.) are
821 designed so that there won't be any ambiguities. 834 designed so that there won't be any ambiguities.
822 835
823 If @var{noerror} is @code{nil}, signal an error if the spec-list is 836 The canonicalization algorithm is as follows:
824 invalid; otherwise return @code{t}. 837
838 @enumerate
839 @item
840 Attempt to parse @var{spec-list} as a single, possibly abbreviated,
841 specification.
842 @item
843 If that fails, attempt to parse @var{spec-list} as a list of (abbreviated)
844 specifications.
845 @item
846 If that fails, @var{spec-list} is invalid.
847 @end enumerate
848
849 A possibly abbreviated specification @var{spec} is parsed by
850
851 @enumerate
852 @item
853 Attempt to parse @var{spec} as a possibly abbreviated inst-list.
854 @item
855 If that fails, attempt to parse @var{spec} as a cons of a locale and an
856 (abbreviated) inst-list.
857 @item
858 If that fails, @var{spec} is invalid.
859 @end enumerate
860
861 A possibly abbreviated inst-list @var{inst-list} is parsed by
862
863 @enumerate
864 @item
865 Attempt to parse @var{inst-list} as a possibly abbreviated inst-pair.
866 @item
867 If that fails, attempt to parse @var{inst-list} as a list of (abbreviated)
868 inst-pairs.
869 @item
870 If that fails, @var{inst-list} is invalid.
871 @end enumerate
872
873 A possibly abbreviated inst-pair @var{inst-pair} is parsed by
874
875 @enumerate
876 @item
877 Check if @var{inst-pair} is @code{valid-instantiator-p}.
878 @item
879 If not, check if @var{inst-pair} is a cons of something that is a tag, ie,
880 @code{valid-specifier-tag-p}, and something that is @code{valid-instantiator-p}.
881 @item
882 If not, check if @var{inst-pair} is a cons of a list of tags and something that
883 is @code{valid-instantiator-p}.
884 @item
885 Otherwise, @var{inst-pair} is invalid.
886 @end enumerate
887
888 In summary, this function generally prefers more abbreviated forms.
825 @end defun 889 @end defun
826 890
827 @node Retrieving Specifications 891 @node Retrieving Specifications
828 @section Retrieving the Specifications from a Specifier 892 @section Retrieving the Specifications from a Specifier
829 893
1033 1097
1034 The returned value is dependent on the type of specifier. For example, 1098 The returned value is dependent on the type of specifier. For example,
1035 for a font specifier (as returned by the @code{face-font} function), the 1099 for a font specifier (as returned by the @code{face-font} function), the
1036 returned value will be a font-instance object. For images, the returned 1100 returned value will be a font-instance object. For images, the returned
1037 value will be a string, pixmap, or subwindow. 1101 value will be a string, pixmap, or subwindow.
1102 @end defun
1103
1104 @defun specifier-matching-instance specifier matchspec &optional domain default no-fallback
1105 This function return an instance for @var{specifier} in @var{domain}
1106 that matches @var{matchspec}. If no instance can be generated for
1107 @var{domain}, return @var{default}.
1108
1109 This function is identical to @code{specifier-instance} except that a
1110 specification will only be considered if it matches @var{matchspec}.
1111 The definition of ``match,'' and allowed values for @var{matchspec}, are
1112 dependent on the particular type of specifier. Here are some examples:
1113
1114 @itemize
1115 @item
1116 For chartable (e.g. display table) specifiers, @var{matchspec} should be a
1117 character, and the specification (a chartable) must give a value for
1118 that character in order to be considered. This allows you to specify,
1119 @emphe.g.}, a buffer-local display table that only gives values for particular
1120 characters. All other characters are handled as if the buffer-local
1121 display table is not there. (Chartable specifiers are not yet
1122 implemented.)
1123
1124 For font specifiers, @var{matchspec} should be a list (@var{charset}
1125 . @var{second-stage-p}), and the specification (a font string) must have
1126 a registry that matches the charset's registry. (This only makes sense
1127 with Mule support.) This makes it easy to choose a font that can
1128 display a particular character. (This is what redisplay does, in fact.)
1129 @var{second-stage-p} means to ignore the font's registry and instead
1130 look at the characters in the font to see if the font can support the
1131 charset. This currently only makes sense under MS Windows.
1038 @end defun 1132 @end defun
1039 1133
1040 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default 1134 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default
1041 This function attempts to convert a particular inst-list into an 1135 This function attempts to convert a particular inst-list into an
1042 instance. This attempts to instantiate @var{inst-list} in the given 1136 instance. This attempts to instantiate @var{inst-list} in the given
1286 @code{make-image-specifier}, @code{make-face-boolean-specifier}, and 1380 @code{make-image-specifier}, @code{make-face-boolean-specifier}, and
1287 @code{make-toolbar-specifier}. 1381 @code{make-toolbar-specifier}.
1288 @end defun 1382 @end defun
1289 1383
1290 @defun make-specifier-and-init type spec-list &optional dont-canonicalize 1384 @defun make-specifier-and-init type spec-list &optional dont-canonicalize
1291 This function creates and initialize a new specifier. 1385 This function creates and initializes a new specifier.
1292 1386
1293 This is a front-end onto @code{make-specifier} that allows you to create 1387 This is a convenience API combining @code{make-specifier} and
1388 @code{set-specifier} that allows you to create
1294 a specifier and add specs to it at the same time. @var{type} specifies 1389 a specifier and add specs to it at the same time. @var{type} specifies
1295 the specifier type. @var{spec-list} supplies the specification(s) to be 1390 the specifier type. Allowed types are as for @code{make-specifier}.
1296 added to the specifier. Normally, almost any reasonable abbreviation of 1391
1297 the full spec-list form is accepted, and is converted to the full form; 1392 @var{spec-list} supplies the specification(s) to be
1298 however, if optional argument @var{dont-canonicalize} is non-@code{nil}, 1393 added to the specifier. Any abbreviation of
1299 this conversion is not performed, and the @var{spec-list} must already 1394 the full spec-list form accepted by @code{canonicalize-spec-list} may
1300 be in full form. See @code{canonicalize-spec-list}. 1395 be used.
1396 However, if the optional argument @var{dont-canonicalize} is non-@code{nil},
1397 canonicalization is not performed, and the @var{spec-list} must already
1398 be in full form.
1301 @end defun 1399 @end defun
1302 1400
1303 @defun make-integer-specifier spec-list 1401 @defun make-integer-specifier spec-list
1304 1402
1305 Return a new @code{integer} specifier object with the given 1403 Return a new @code{integer} specifier object with the given
1480 1578
1481 @defun map-specifier specifier func &optional locale maparg 1579 @defun map-specifier specifier func &optional locale maparg
1482 This function applies @var{func} to the specification(s) for 1580 This function applies @var{func} to the specification(s) for
1483 @var{locale} in @var{specifier}. 1581 @var{locale} in @var{specifier}.
1484 1582
1485 If @var{locale} is a locale, @var{func} will be called for that locale. 1583 If optional @var{locale} is a locale, @var{func} will be called for that
1584 locale.
1486 If @var{locale} is a locale type, @var{func} will be mapped over all 1585 If @var{locale} is a locale type, @var{func} will be mapped over all
1487 locales of that type. If @var{locale} is @code{nil} or the symbol 1586 locales of that type. If @var{locale} is @code{nil} or the symbol
1488 @code{all}, @var{func} will be mapped over all locales in 1587 @code{all}, @var{func} will be mapped over all locales in
1489 @var{specifier}. 1588 @var{specifier}.
1589
1590 Optional @var{ms-tag-set} and @var{ms-exact-p} are as in
1591 @code{specifier-spec-list'}.
1592 Optional @var{ms-maparg} will be passed to @var{ms-func}.
1490 1593
1491 @var{func} is called with four arguments: the @var{specifier}, the 1594 @var{func} is called with four arguments: the @var{specifier}, the
1492 locale being mapped over, the inst-list for that locale, and the 1595 locale being mapped over, the inst-list for that locale, and the
1493 optional @var{maparg}. If any invocation of @var{func} returns 1596 optional @var{maparg}. If any invocation of @var{func} returns
1494 non-@code{nil}, the mapping will stop and the returned value becomes the 1597 non-@code{nil}, the mapping will stop and the returned value becomes the