Mercurial > hg > xemacs-beta

comparison man/lispref/specifiers.texi @ 3674:f200f93c0b69

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2006-11-11 16:05:31 by aidan] Update some documentation, comments; add some entries to etc/NEWS.
author aidan
date Sat, 11 Nov 2006 16:05:39 +0000
parents c7d4a681eb2c
children 755ae5b97edb
comparison
equal deleted inserted replaced
3673:887d4be44334 3674:f200f93c0b69
8 @chapter Specifiers 8 @chapter Specifiers
9 @cindex specifier 9 @cindex specifier
10 10
11 A specifier is an object used to keep track of a property whose value 11 A specifier is an object used to keep track of a property whose value
12 should vary according to @emph{display context}, a window, a frame, or 12 should vary according to @emph{display context}, a window, a frame, or
13 device. The value of many built-in properties, such as the font, 13 device, or a Mule character set. The value of many built-in properties,
14 foreground, background, and such properties of a face and variables 14 such as the font, foreground, background, and such properties of a face
15 such as @code{modeline-shadow-thickness} and 15 and variables such as @code{modeline-shadow-thickness} and
16 @code{top-toolbar-height}, is actually a specifier object. The 16 @code{top-toolbar-height}, is actually a specifier object. The
17 specifier object, in turn, is ``instantiated'' in a particular situation 17 specifier object, in turn, is ``instantiated'' in a particular situation
18 to yield the real value of the property in the current context. 18 to yield the real value of the property in the current context.
19 19
20 @defun specifierp object 20 @defun specifierp object
211 (specifier-instance (face-font 'default)) 211 (specifier-instance (face-font 'default))
212 #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b> 212 #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b>
213 @end example 213 @end example
214 214
215 In this case, @code{specifier-instance} returns an opaque object; 215 In this case, @code{specifier-instance} returns an opaque object;
216 programs can't work on it, they can only pass it around. Worse, in some 216 Lisp programs can't work on it, they can only pass it around. Worse, in some
217 environments the instantiation will fail, resulting in a different value 217 environments the instantiation will fail, resulting in a different value
218 (when another instantiation succeeds), or worse yet, an error, if all 218 (when another instantiation succeeds), or worse yet, an error, if all
219 attempts to instantiate the specifier fail. @code{specifier-instance} is 219 attempts to instantiate the specifier fail. @code{specifier-instance} is
220 context-dependent, even for the exact same specification. 220 context-dependent, even for the exact same specification.
221 @code{specifier-specs} is deterministic, and only depends on the 221 @code{specifier-specs} is deterministic, and only depends on the
359 @dfn{tag set} (an unordered list of zero or more symbols, or @dfn{tags}) 359 @dfn{tag set} (an unordered list of zero or more symbols, or @dfn{tags})
360 and an @dfn{instantiator} (the allowed form of this varies depending on 360 and an @dfn{instantiator} (the allowed form of this varies depending on
361 the type of specifier). In a given specification, there may be more 361 the type of specifier). In a given specification, there may be more
362 than one inst-pair with the same tag set; this is unlike for locales. 362 than one inst-pair with the same tag set; this is unlike for locales.
363 363
364 The tag set is used to restrict the sorts of devices over which the 364 The tag set is used to restrict the sorts of devices and character sets
365 instantiator is valid and to uniquely identify instantiators added by a 365 over which the instantiator is valid and to uniquely identify
366 particular application, so that different applications can work on the 366 instantiators added by a particular application, so that different
367 same specifier and not interfere with each other. Each tag can have a 367 applications can work on the same specifier and not interfere with each
368 @dfn{predicate} associated with it, which is a function of one argument 368 other.
369 (a device) that specifies whether the tag matches that particular 369
370 device. (If a tag does not have a predicate, it matches all devices.) 370 Each tag can have a @dfn{device-predicate} associated with it, which is
371 All tags in a tag set must match a device for the associated inst-pair 371 a function of one argument (a device) that specifies whether the tag
372 to be instantiable over that device. (A null tag set is perfectly 372 matches that particular device. (If a tag does not have a predicate, it
373 valid, and trivially matches all devices.) 373 matches all devices.) All tags in a tag set must match a device for the
374 374 associated inst-pair to be instantiable over that device. (A null tag
375 The valid device types (normally @code{x}, @code{tty}, @code{stream}, 375 set is perfectly valid, and trivially matches all devices.)
376 @code{mswindows}, @code{msprinter}, and possibly @code{carbon}) and 376
377 device classes (normally @code{color}, @code{grayscale}, and 377 Each tag can also have a @dfn{charset-predicate} associated with it;
378 @code{mono}) can always be used as tags, and match devices of the 378 this is a function that takes one charset argument, and specifies
379 associated type or class (@pxref{Consoles and Devices}). User-defined 379 whether that tag matches that particular charset. When instantiating a
380 tags may be defined, with an optional predicate specified. An 380 face over a given domain with a given charset, the
381 application can create its own tag, use it to mark all its 381 @code{charset-predicate} attribute of a tag is consulted@footnote{Not
382 instantiators, and be fairly confident that it will not interfere with 382 quite the case; the result of the functions are pre-calculated and
383 other applications that modify the same specifier---Functions that add 383 cached whenever @code{define-specifier-tag} or @code{make-charset} is
384 a specification to a specifier usually only overwrite existing 384 called.} to decide whether this inst-pair matches the charset. If the
385 inst-pairs with the same tag set as was given, and a particular tag or 385 @code{charset-predicate} function of a tag is unspecified, that tag
386 tag set can be specified when removing instantiators. 386 defaults to matching all charsets.
387
388 When @code{charset-predicate}s are being taken into account, the
389 matching process becomes two-stage. The first stage pays attention to
390 the charset predicates and the device predicates; only if there is no
391 match does the second stage take place, in which charset predicates are
392 ignored, and only the device predicates are relevant.
393
394 The valid device types in a build (normally @code{x}, @code{tty},
395 @code{stream}, @code{mswindows}, @code{msprinter}, and possibly
396 @code{carbon}) and device classes (normally @code{color},
397 @code{grayscale}, and @code{mono}) can always be used as tags, and match
398 devices of the associated type or class (@pxref{Consoles and Devices}).
399 There are also built-in tags related to font instantiation and
400 translation to Unicode; they are identical to the symbols used with
401 @code{specifier-matching-instance}, see the documentation of that
402 function for their names.
403
404 User-defined tags may be defined, with optional device and charset
405 predicates specified. An application can create its own tag, use it to
406 mark all its instantiators, and be fairly confident that it will not
407 interfere with other applications that modify the same
408 specifier---functions that add a specification to a specifier usually
409 only overwrite existing inst-pairs with the same tag set as was given,
410 and a particular tag or tag set can be specified when removing
411 instantiators.
387 412
388 When a specifier is instantiated in a domain, both the locale and the tag 413 When a specifier is instantiated in a domain, both the locale and the tag
389 set can be viewed as specifying necessary conditions that must apply in 414 set can be viewed as specifying necessary conditions that must apply in
390 that domain for an instantiator to be considered as a possible result of 415 that domain for an instantiator to be considered as a possible result of
391 the instantiation. More specific locales always override more general 416 the instantiation. More specific locales always override more general
1139 valid device types and device classes are always tags, as are any tags 1164 valid device types and device classes are always tags, as are any tags
1140 defined by @code{define-specifier-tag}.) It is called a ``tag set'' (as 1165 defined by @code{define-specifier-tag}.) It is called a ``tag set'' (as
1141 opposed to a list) because the order of the tags or the number of times 1166 opposed to a list) because the order of the tags or the number of times
1142 a particular tag occurs does not matter. 1167 a particular tag occurs does not matter.
1143 1168
1144 Each tag has a predicate associated with it, which specifies whether 1169 Each tag has a device predicate associated with it, which specifies whether
1145 that tag applies to a particular device. The tags which are device 1170 that tag applies to a particular device. The tags which are device
1146 types and classes match devices of that type or class. User-defined 1171 types and classes match devices of that type or class. User-defined
1147 tags can have any predicate, or none (meaning that all devices match). 1172 tags can have any device predicate, or none (meaning that all devices match).
1148 When attempting to instantiate a specifier, a particular instantiator is 1173 When attempting to instantiate a specifier, a particular instantiator is
1149 only considered if the device of the domain being instantiated over matches 1174 only considered if the device of the domain being instantiated over matches
1150 all tags in the tag set attached to that instantiator. 1175 all tags in the tag set attached to that instantiator.
1151 1176
1177 Each tag can also have a charset predicate, specifying whether that tag
1178 applies to a particular charset. There are a few tags with predefined
1179 charset predicates created to allow sensible fallbacks in the face
1180 code---see the output of @code{(specifier-fallback (face-font
1181 'default))} for these.
1182
1152 Most of the time, a tag set is not specified, and the instantiator gets 1183 Most of the time, a tag set is not specified, and the instantiator gets
1153 a null tag set, which matches all devices. 1184 a null tag set, which matches all devices and all character sets (when
1185 possible; fonts with an inappropriate repertoire will not match, for
1186 example).
1154 1187
1155 @defun valid-specifier-tag-p tag 1188 @defun valid-specifier-tag-p tag
1156 This function returns non-@code{nil} if @var{tag} is a valid specifier 1189 This function returns non-@code{nil} if @var{tag} is a valid specifier
1157 tag. 1190 tag.
1158 @end defun 1191 @end defun
1173 This function returns non-@code{nil} if @var{device} matches specifier 1206 This function returns non-@code{nil} if @var{device} matches specifier
1174 tag set @var{tag-set}. This means that @var{device} matches each tag in 1207 tag set @var{tag-set}. This means that @var{device} matches each tag in
1175 the tag set. 1208 the tag set.
1176 @end defun 1209 @end defun
1177 1210
1178 @defun define-specifier-tag tag &optional predicate 1211 @defun define-specifier-tag tag &optional device-predicate charset-predicate
1179 This function defines a new specifier tag. If @var{predicate} is 1212 This function defines a new specifier tag. If @var{device-predicate} is
1180 specified, it should be a function of one argument (a device) that 1213 specified, it should be a function of one argument (a device) that
1181 specifies whether the tag matches that particular device. If 1214 specifies whether the tag matches that particular device. If
1182 @var{predicate} is omitted, the tag matches all devices. 1215 @var{device-predicate} is omitted, the tag matches all devices.
1216
1217 If @var{charset-predicate} is specified, it should be a function taking
1218 one character set argument that specifies whether the tag matches that
1219 particular character set.
1183 1220
1184 You can redefine an existing user-defined specifier tag. However, you 1221 You can redefine an existing user-defined specifier tag. However, you
1185 cannot redefine the built-in specifier tags (the device types and 1222 cannot redefine the built-in specifier tags (the device types and
1186 classes) or the symbols @code{nil}, @code{t}, @code{all}, or 1223 classes) or the symbols @code{nil}, @code{t}, @code{all}, or
1187 @code{global}. 1224 @code{global}.
1195 @defun specifier-tag-list 1232 @defun specifier-tag-list
1196 This function returns a list of all currently-defined specifier tags. 1233 This function returns a list of all currently-defined specifier tags.
1197 This includes the built-in ones (the device types and classes). 1234 This includes the built-in ones (the device types and classes).
1198 @end defun 1235 @end defun
1199 1236
1200 @defun specifier-tag-predicate tag 1237 @defun specifier-tag-device-predicate tag
1201 This function returns the predicate for the given specifier tag. 1238 This function returns the device predicate for the given specifier tag.
1239 @end defun
1240
1241 @defun specifier-tag-charset-predicate tag
1242 This function returns the charset predicate for the given specifier tag.
1202 @end defun 1243 @end defun
1203 1244
1204 @node Specifier Instantiation Functions 1245 @node Specifier Instantiation Functions
1205 @section Functions for Instantiating a Specifier 1246 @section Functions for Instantiating a Specifier
1206 1247
1278 characters. All other characters are handled as if the buffer-local 1319 characters. All other characters are handled as if the buffer-local
1279 display table is not there. (Chartable specifiers are not yet 1320 display table is not there. (Chartable specifiers are not yet
1280 implemented.) 1321 implemented.)
1281 @item 1322 @item
1282 For font specifiers, @var{matchspec} should be a list (@var{charset} 1323 For font specifiers, @var{matchspec} should be a list (@var{charset}
1283 . @var{second-stage-p}), and the specification (a font string) must have 1324 . @var{stage}). On X11 the specification (a font string) should, for
1284 a registry that matches the charset's registry. (This only makes sense 1325 clarity, have a registry that matches the charset's registry, but the
1285 with Mule support.) This makes it easy to choose a font that can 1326 redisplay code will specify the XLFD CHARSET_REGISTRY and
1286 display a particular character. (This is what redisplay does, in fact.) 1327 CHARSET_ENCODING fields itself. This makes minimal sense without Mule
1287 @var{second-stage-p} means to ignore the font's registry and instead 1328 support. @var{stage} can be one of the symbols @code{'initial} and
1288 look at the characters in the font to see if the font can support the 1329 @code{'final}; on X11, @code{'initial} means ``search for fonts using
1289 charset. This currently only makes sense under MS Windows. 1330 the charset registry of this charset'' and @code{'final} means ``search
1331 for fonts using `iso10646-1' as their charset registries, with the
1332 expectation that characters will be translated to Unicode at
1333 redisplay.'' Their meanings are similar on MS Windows, with the
1334 difference that the actual repertoire of the font is checked when
1335 deciding if a matchspec with @code{'final} matches.
1336
1337 For example, the following code emulates what redisplay does when
1338 deciding what font to use for ethiopic with the default face (ignoring,
1339 for the moment, fallbacks):
1340 @example
1341 (or
1342 (specifier-matching-instance (face-font 'default)
1343 (cons 'ethiopic 'initial))
1344 (specifier-matching-instance (face-font 'default)
1345 (cons 'ethiopic 'final)))
1346 @end example
1290 @end itemize 1347 @end itemize
1291 @end defun 1348 @end defun
1292 1349
1293 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default 1350 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default
1294 This function attempts to convert a particular inst-list into an 1351 This function attempts to convert a particular inst-list into an