Mercurial > hg > xemacs-beta
annotate man/lispref/specifiers.texi @ 5353:38e24b8be4ea
Improve the lexical scoping in #'block, #'return-from.
lisp/ChangeLog addition:
2011-02-07 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el:
* bytecomp.el (byte-compile-initial-macro-environment):
Shadow `block', `return-from' here, we implement them differently
when byte-compiling.
* bytecomp.el (byte-compile-active-blocks): New.
* bytecomp.el (byte-compile-block-1): New.
* bytecomp.el (byte-compile-return-from-1): New.
* bytecomp.el (return-from-1): New.
* bytecomp.el (block-1): New.
These are two aliases that exist to have their own associated
byte-compile functions, which functions implement `block' and
`return-from'.
* cl-extra.el (cl-macroexpand-all):
Fix a bug here when macros in the environment have been compiled.
* cl-macs.el (block):
* cl-macs.el (return):
* cl-macs.el (return-from):
Be more careful about lexical scope in these macros.
* cl.el:
* cl.el ('cl-block-wrapper): Removed.
* cl.el ('cl-block-throw): Removed.
These aren't needed in code generated by this XEmacs. They
shouldn't be needed in code generated by XEmacs 21.4, but if it
turns out the packages do need them, we can put them back.
2011-01-30 Mike Sperber <mike@xemacs.org>
* font-lock.el (font-lock-fontify-pending-extents): Don't fail if
`font-lock-mode' is unset, which can happen in the middle of
`revert-buffer'.
2011-01-23 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (delete):
* cl-macs.el (delq):
* cl-macs.el (remove):
* cl-macs.el (remq):
Don't use the compiler macro if these functions were given the
wrong number of arguments, as happens in lisp-tests.el.
* cl-seq.el (remove, remq): Removed.
I added these to subr.el, and forgot to remove them from here.
2011-01-22 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-setq, byte-compile-set):
Remove kludge allowing keywords' values to be set, all the code
that does that is gone.
* cl-compat.el (elt-satisfies-test-p):
* faces.el (set-face-parent):
* faces.el (face-doc-string):
* gtk-font-menu.el:
* gtk-font-menu.el (gtk-reset-device-font-menus):
* msw-font-menu.el:
* msw-font-menu.el (mswindows-reset-device-font-menus):
* package-get.el (package-get-installedp):
* select.el (select-convert-from-image-data):
* sound.el:
* sound.el (load-sound-file):
* x-font-menu.el (x-reset-device-font-menus-core):
Don't quote keywords, they're self-quoting, and the
win from backward-compatibility is sufficiently small now that the
style problem overrides it.
2011-01-22 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (block, return-from): Require that NAME be a symbol
in these macros, as always documented in the #'block docstring and
as required by Common Lisp.
* descr-text.el (unidata-initialize-unihan-database):
Correct the use of non-symbols in #'block and #'return-from in
this function.
2011-01-15 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (concatenate): Accept more complicated TYPEs in this
function, handing the sequences over to #'coerce if we don't
understand them here.
* cl-macs.el (inline): Don't proclaim #'concatenate as inline, its
compiler macro is more useful than doing that.
2011-01-11 Aidan Kehoe <kehoea@parhasard.net>
* subr.el (delete, delq, remove, remq): Move #'remove, #'remq
here, they don't belong in cl-seq.el; move #'delete, #'delq here
from fns.c, implement them in terms of #'delete*, allowing support
for sequences generally.
* update-elc.el (do-autoload-commands): Use #'delete*, not #'delq
here, now the latter's no longer dumped.
* cl-macs.el (delete, delq): Add compiler macros transforming
#'delete and #'delq to #'delete* calls.
2011-01-10 Aidan Kehoe <kehoea@parhasard.net>
* dialog.el (make-dialog-box): Correct a misplaced parenthesis
here, thank you Mats Lidell in 87zkr9gqrh.fsf@mail.contactor.se !
2011-01-02 Aidan Kehoe <kehoea@parhasard.net>
* dialog.el (make-dialog-box):
* list-mode.el (display-completion-list):
These functions used to use cl-parsing-keywords; change them to
use defun* instead, fixing the build. (Not sure what led to me
not including this change in d1b17a33450b!)
2011-01-02 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (define-star-compiler-macros):
Make sure the form has ITEM and LIST specified before attempting
to change to calls with explicit tests; necessary for some tests
in lisp-tests.el to compile correctly.
(stable-union, stable-intersection): Add compiler macros for these
functions, in the same way we do for most of the other functions
in cl-seq.el.
2011-01-01 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (dolist, dotimes, do-symbols, macrolet)
(symbol-macrolet):
Define these macros with defmacro* instead of parsing the argument
list by hand, for the sake of style and readability; use backquote
where appropriate, instead of calling #'list and and friends, for
the same reason.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* x-misc.el (device-x-display):
Provide this function, documented in the Lispref for years, but
not existing previously. Thank you Julian Bradfield, thank you
Jeff Mincy.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* cl-seq.el:
Move the heavy lifting from this file to C. Dump the
cl-parsing-keywords macro, but don't use defun* for the functions
we define that do take keywords, dynamic scope lossage makes that
not practical.
* subr.el (sort, fillarray): Move these aliases here.
(map-plist): #'nsublis is now built-in, but at this point #'eql
isn't necessarily available as a test; use #'eq.
* obsolete.el (cl-delete-duplicates): Make this available for old
compiler macros and old code.
(memql): Document that this is equivalent to #'member*, and worse.
* cl.el (adjoin, subst): Removed. These are in C.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* simple.el (assoc-ignore-case): Remove a duplicate definition of
this function (it's already in subr.el).
* iso8859-1.el (char-width):
On non-Mule, make this function equivalent to that produced by
(constantly 1), but preserve its docstring.
* subr.el (subst-char-in-string): Define this in terms of
#'substitute, #'nsubstitute.
(string-width): Define this using #'reduce and #'char-width.
(char-width): Give this a simpler definition, it makes far more
sense to check for mule at load time and redefine, as we do in
iso8859-1.el.
(store-substring): Implement this in terms of #'replace, now
#'replace is cheap.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* update-elc.el (lisp-files-needed-for-byte-compilation)
(lisp-files-needing-early-byte-compilation):
cl-macs belongs in the former, not the latter, it is as
fundamental as bytecomp.el.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* cl.el:
Provde the Common Lisp program-error, type-error as error
symbols. This doesn't nearly go far enough for anyone using the
Common Lisp errors.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (delete-duplicates):
If the form has an incorrect number of arguments, don't attempt a
compiler macroexpansion.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (cl-safe-expr-p):
Forms that start with the symbol lambda are also safe.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (= < > <= >=):
For these functions' compiler macros, the optimisation is safe
even if the first and the last arguments have side effects, since
they're only used the once.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (inline-side-effect-free-compiler-macros):
Unroll a loop here at macro-expansion time, so these compiler
macros are compiled. Use #'eql instead of #'eq in a couple of
places for better style.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (notany, notevery): Avoid some dynamic scope
stupidity with local variable names in these functions, when they
weren't prefixed with cl-; go into some more detail in the doc
strings.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (side-effect-free-fns): #'remove, #'remq are
free of side-effects.
(side-effect-and-error-free-fns):
Drop dot, dot-marker from the list.
2010-11-17 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (coerce):
In the argument list, name the first argument OBJECT, not X; the
former name was always used in the doc string and is clearer.
Handle vector type specifications which include the length of the
target sequence, error if there's a mismatch.
* cl-macs.el (cl-make-type-test): Handle type specifications
starting with the symbol 'eql.
2010-11-14 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (eql): Don't remove the byte-compile property of this
symbol. That was necessary to override a bug in bytecomp.el where
#'eql was confused with #'eq, which bug we no longer have.
If neither expression is constant, don't attempt to handle the
expression in this compiler macro, leave it to byte-compile-eql,
which produces better code anyway.
* bytecomp.el (eq): #'eql is not the function associated with the
byte-eq byte code.
(byte-compile-eql): Add an explicit compile method for this
function, for cases where the cl-macs compiler macro hasn't
reduced it to #'eq or #'equal.
2010-10-25 Aidan Kehoe <kehoea@parhasard.net>
Add compiler macros and compilation sanity-checking for various
functions that take keywords.
* byte-optimize.el (side-effect-free-fns): #'symbol-value is
side-effect free and not error free.
* bytecomp.el (byte-compile-normal-call): Check keyword argument
lists for sanity; store information about the positions where
keyword arguments start using the new byte-compile-keyword-start
property.
* cl-macs.el (cl-const-expr-val): Take a new optional argument,
cl-not-constant, defaulting to nil, in this function; return it if
the expression is not constant.
(cl-non-fixnum-number-p): Make this into a separate function, we
want to pass it to #'every.
(eql): Use it.
(define-star-compiler-macros): Use the same code to generate the
member*, assoc* and rassoc* compiler macros; special-case some
code in #'add-to-list in subr.el.
(remove, remq): Add compiler macros for these two functions, in
preparation for #'remove being in C.
(define-foo-if-compiler-macros): Transform (remove-if-not ...) calls to
(remove ... :if-not) at compile time, which will be a real win
once the latter is in C.
(define-substitute-if-compiler-macros)
(define-subst-if-compiler-macros): Similarly for these functions.
(delete-duplicates): Change this compiler macro to use
#'plists-equal; if we don't have information about the type of
SEQUENCE at compile time, don't bother attempting to inline the
call, the function will be in C soon enough.
(equalp): Remove an old commented-out compiler macro for this, if
we want to see it it's in version control.
(subst-char-in-string): Transform this to a call to nsubstitute or
nsubstitute, if that is appropriate.
* cl.el (ldiff): Don't call setf here, this makes for a load-time
dependency problem in cl-macs.el
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* term/vt100.el:
Refer to XEmacs, not GNU Emacs, in permissions.
* term/bg-mouse.el:
* term/sup-mouse.el:
Put copyright notice in canonical "Copyright DATE AUTHOR" form.
Refer to XEmacs, not GNU Emacs, in permissions.
* site-load.el:
Add permission boilerplate.
* mule/canna-leim.el:
* alist.el:
Refer to XEmacs, not APEL/this program, in permissions.
* mule/canna-leim.el:
Remove my copyright, I've assigned it to the FSF.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* gtk.el:
* gtk-widget-accessors.el:
* gtk-package.el:
* gtk-marshal.el:
* gtk-compose.el:
* gnome.el:
Add copyright notice based on internal evidence.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* easymenu.el: Add reference to COPYING to permission notice.
* gutter.el:
* gutter-items.el:
* menubar-items.el:
Fix typo "Xmacs" in permissions notice.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* auto-save.el:
* font.el:
* fontconfig.el:
* mule/kinsoku.el:
Add "part of XEmacs" text to permission notice.
2010-10-14 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (side-effect-free-fns):
* cl-macs.el (remf, getf):
* cl-extra.el (tailp, cl-set-getf, cl-do-remf):
* cl.el (ldiff, endp):
Tighten up Common Lisp compatibility for #'ldiff, #'endp, #'tailp;
add circularity checking for the first two.
#'cl-set-getf and #'cl-do-remf were Lisp implementations of
#'plist-put and #'plist-remprop; change the names to aliases,
changes the macros that use them to using #'plist-put and
#'plist-remprop directly.
2010-10-12 Aidan Kehoe <kehoea@parhasard.net>
* abbrev.el (fundamental-mode-abbrev-table, global-abbrev-table):
Create both these abbrev tables using the usual
#'define-abbrev-table calls, rather than attempting to
special-case them.
* cl-extra.el: Force cl-macs to be loaded here, if cl-extra.el is
being loaded interpreted. Previously other, later files would
redundantly call (load "cl-macs") when interpreted, it's more
reasonable to do it here, once.
* cmdloop.el (read-quoted-char-radix): Use defcustom here, we
don't have any dump-order dependencies that would prevent that.
* custom.el (eval-when-compile): Don't load cl-macs when
interpreted or when byte-compiling, rely on cl-extra.el in the
former case and the appropriate entry in bytecomp-load-hook in the
latter. Get rid of custom-declare-variable-list, we have no
dump-time dependencies that would require it.
* faces.el (eval-when-compile): Don't load cl-macs when
interpreted or when byte-compiling.
* packages.el: Remove some inaccurate comments.
* post-gc.el (cleanup-simple-finalizers): Use #'delete-if-not
here, now the order of preloaded-file-list has been changed to
make it available.
* subr.el (custom-declare-variable-list): Remove. No need for it.
Also remove a stub define-abbrev-table from this file, given the
current order of preloaded-file-list there's no need for it.
2010-10-10 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-constp) Forms quoted with FUNCTION are
also constant.
(byte-compile-initial-macro-environment): In #'the, if FORM is
constant and does not match TYPE, warn at byte-compile time.
2010-10-10 Aidan Kehoe <kehoea@parhasard.net>
* backquote.el (bq-vector-contents, bq-list*): Remove; the former
is equivalent to (append VECTOR nil), the latter to (list* ...).
(bq-process-2): Use (append VECTOR nil) instead of using
#'bq-vector-contents to convert to a list.
(bq-process-1): Now we use list* instead of bq-list
* subr.el (list*): Moved from cl.el, since it is now required to
be available the first time a backquoted form is encountered.
* cl.el (list*): Move to subr.el.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* test-harness.el (Check-Message):
Add an omitted comma here, thank you the buildbot.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* hash-table.el (hash-table-key-list, hash-table-value-list)
(hash-table-key-value-alist, hash-table-key-value-plist):
Remove some useless #'nreverse calls in these files; our hash
tables have no order, it's not helpful to pretend they do.
* behavior.el (read-behavior):
Do the same in this file, in some code evidently copied from
hash-table.el.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* info.el (Info-insert-dir):
* format.el (format-deannotate-region):
* files.el (cd, save-buffers-kill-emacs):
Use #'some, #'every and related functions for applying boolean
operations to lists, instead of rolling our own ones that cons and
don't short-circuit.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-initial-macro-environment):
* cl-macs.el (the):
Rephrase the docstring, make its implementation when compiling
files a little nicer.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* descr-text.el (unidata-initialize-unicodedata-database)
(unidata-initialize-unihan-database, describe-char-unicode-data)
(describe-char-unicode-data):
Wrap calls to the database functions with (with-fboundp ...),
avoiding byte compile warnings on builds without support for the
database functions.
(describe-char): (reduce #'max ...), not (apply #'max ...), no
need to cons needlessly.
(describe-char): Remove a redundant lambda wrapping
#'extent-properties.
(describe-char-unicode-data): Call #'nsubst when replacing "" with
nil in the result of #'split-string, instead of consing inside
mapcar.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* x-faces.el (x-available-font-sizes):
* specifier.el (let-specifier):
* package-ui.el (pui-add-required-packages):
* msw-faces.el (mswindows-available-font-sizes):
* modeline.el (modeline-minor-mode-menu):
* minibuf.el (minibuf-directory-files):
Replace the O2N (delq nil (mapcar (lambda (W) (and X Y)) Z)) with
the ON (mapcan (lambda (W) (and X (list Y))) Z) in these files.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (= < > <= >=):
When these functions are handed more than two arguments, and those
arguments have no side effects, transform to a series of two
argument calls, avoiding funcall in the byte-compiled code.
* mule/mule-cmds.el (finish-set-language-environment):
Take advantage of this change in a function called 256 times at
startup.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-function-form, byte-compile-quote)
(byte-compile-quote-form):
Warn at compile time, and error at runtime, if a (quote ...) or a
(function ...) form attempts to quote more than one object.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (byte-optimize-apply): Transform (apply 'nconc
(mapcar ...)) to (mapcan ...); warn about use of the first idiom.
* update-elc.el (do-autoload-commands):
* packages.el (packages-find-package-library-path):
* frame.el (frame-list):
* extents.el (extent-descendants):
* etags.el (buffer-tag-table-files):
* dumped-lisp.el (preloaded-file-list):
* device.el (device-list):
* bytecomp-runtime.el (proclaim-inline, proclaim-notinline)
Use #'mapcan, not (apply #'nconc (mapcar ...) in all these files.
* bytecomp-runtime.el (eval-when-compile, eval-and-compile):
In passing, mention that these macros also evaluate the body when
interpreted.
tests/ChangeLog addition:
2011-02-07 Aidan Kehoe <kehoea@parhasard.net>
* automated/lisp-tests.el:
Test lexical scope for `block', `return-from'; add a
Known-Bug-Expect-Failure for a contorted example that fails when
byte-compiled.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Mon, 07 Feb 2011 12:01:24 +0000 |
| parents | 755ae5b97edb |
| children | 62b9ef1ed4ac |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 3 @c Copyright (C) 1995, 1996 Ben Wing. | |
| 1882 | 4 @c Copyright (C) 2002, 2004 Free Software Foundation, Inc. |
| 428 | 5 @c See the file lispref.texi for copying conditions. |
| 6 @setfilename ../../info/specifiers.info | |
| 7 @node Specifiers, Faces and Window-System Objects, Extents, top | |
| 8 @chapter Specifiers | |
| 9 @cindex specifier | |
| 10 | |
| 11 A specifier is an object used to keep track of a property whose value | |
| 1135 | 12 should vary according to @emph{display context}, a window, a frame, or |
| 3674 | 13 device, or a Mule character set. The value of many built-in properties, |
| 14 such as the font, foreground, background, and such properties of a face | |
| 15 and variables such as @code{modeline-shadow-thickness} and | |
| 1135 | 16 @code{top-toolbar-height}, is actually a specifier object. The |
| 2953 | 17 specifier object, in turn, is ``instantiated'' in a particular situation |
| 1135 | 18 to yield the real value of the property in the current context. |
| 428 | 19 |
| 20 @defun specifierp object | |
| 21 This function returns non-@code{nil} if @var{object} is a specifier. | |
| 22 @end defun | |
| 23 | |
| 24 @menu | |
| 440 | 25 * Introduction to Specifiers:: Specifiers provide a clean way for |
| 26 display and other properties to vary | |
| 27 (under user control) in a wide variety | |
| 28 of contexts. | |
| 1135 | 29 * Simple Specifier Usage:: Getting started with specifiers. |
| 440 | 30 * Specifiers In-Depth:: Gory details about specifier innards. |
| 2953 | 31 * Specifier Instantiation:: Instantiation means obtaining the ``value'' of |
| 440 | 32 a specifier in a particular context. |
| 33 * Specifier Types:: Specifiers come in different flavors. | |
| 34 * Adding Specifications:: Specifications control a specifier's ``value'' | |
| 35 by giving conditions under which a | |
| 36 particular value is valid. | |
| 37 * Retrieving Specifications:: Querying a specifier's specifications. | |
| 38 * Specifier Tag Functions:: Working with specifier tags. | |
| 2953 | 39 * Specifier Instantiation Functions:: |
| 40 Functions to instantiate a specifier. | |
| 1869 | 41 * Specifier Examples:: Making all this stuff clearer. |
| 440 | 42 * Creating Specifiers:: Creating specifiers for your own use. |
| 428 | 43 * Specifier Validation Functions:: |
| 440 | 44 Validating the components of a specifier. |
| 428 | 45 * Other Specification Functions:: |
| 440 | 46 Other ways of working with specifications. |
| 2028 | 47 * Specifier Compatibility Notes:: |
| 48 Backward compatibility and GNU Emacs. | |
| 428 | 49 @end menu |
| 50 | |
| 51 @node Introduction to Specifiers | |
| 52 @section Introduction to Specifiers | |
| 53 | |
| 1135 | 54 Perhaps the most useful way to explain specifiers is via an analogy. |
| 55 Emacs Lisp programmers are used to @emph{buffer-local variables} | |
| 1138 | 56 @ref{Buffer-Local Variables}. For example, the variable |
| 428 | 57 @code{modeline-format}, which controls the format of the modeline, can |
| 58 have different values depending on the particular buffer being edited. | |
| 59 The variable has a default value which most modes will use, but a | |
| 1138 | 60 specialized package such as Calendar might change the variable so as to |
| 61 tailor the modeline to its own purposes. Other variables are perhaps | |
| 62 best thought of as ``mode local,'' such as font-lock keywords, but they | |
| 63 are implemented as buffer locals. | |
| 428 | 64 |
| 65 Other properties (such as those that can be changed by the | |
| 66 @code{modify-frame-parameters} function, for example the color of the | |
| 67 text cursor) can have frame-local values, although it might also make | |
| 68 sense for them to have buffer-local values. In other cases, you might | |
| 69 want the property to vary depending on the particular window within the | |
| 70 frame that applies (e.g. the top or bottom window in a split frame), the | |
| 71 device type that that frame appears on (X or tty), etc. Perhaps you can | |
| 72 envision some more complicated scenario where you want a particular | |
| 73 value in a specified buffer, another value in all other buffers | |
| 74 displayed on a particular frame, another value in all other buffers | |
| 75 displayed in all other frames on any mono (two-color, e.g. black and | |
| 76 white only) displays, and a default value in all other circumstances. | |
| 77 | |
| 1135 | 78 Specifiers generalize both buffer- and frame-local properties. |
| 79 Specifiers vary according to the @emph{display} context. Font-lock | |
| 80 keywords in a buffer will be the same no matter which window the | |
| 81 buffer is displayed in, but windows on TTY devices will simply not be | |
| 82 capable of the flexibility that windows on modern GUI devices are. | |
| 1875 | 83 Specifiers provide a way for the programmer to @emph{declare} that an |
| 1135 | 84 emphasized text should be italic on GUI devices and inverse video on |
| 85 TTYs. They also provide a way for the programmer to declare | |
| 86 fallbacks, so that a color specified as ``chartreuse'' where possible | |
| 87 can fall back to ``yellow'' on devices where only ANSI (4-bit) color | |
| 88 is available. The complex calculations and device querying are | |
| 89 transparent to both user and programmer. You ask for what you want; | |
| 90 it's up to XEmacs to provide it, or a reasonable approximation. | |
| 91 | |
| 2953 | 92 We call such a declaration a @dfn{specification}. A |
| 93 @dfn{specification} applies in a particular @dfn{locale}, which is a | |
| 94 window, buffer, frame, device, or the global locale. The value part | |
| 95 of the specification is called an @dfn{instantiator}. The process of | |
| 96 determining the value in a particular context, or @dfn{domain}, is | |
| 97 called @dfn{instantiation}. A domain is a window, frame, or device. | |
| 1135 | 98 |
| 99 The difference between @dfn{locale} and @dfn{domain} is somewhat subtle. | |
| 100 You may think of a locale as a class of domains, which may span | |
| 101 different devices. Since the specification is abstract (a Lisp form), | |
| 102 you can state it without reference to a device. On the other hand, when | |
| 103 you instantiate a specification, you must know the type of the device. | |
| 1875 | 104 It is useless to specify that ``blue means emphasis'' on a monochrome |
| 1135 | 105 device. Thus instantiation requires specification of the device on |
| 106 which it will be rendered. | |
| 107 | |
| 108 Thus a @dfn{specifier} allows a great deal of flexibility in | |
| 109 controlling exactly what value a property has in which circumstances. | |
| 1875 | 110 Specifiers are most commonly used for display properties, such as an image or |
| 1135 | 111 the foreground color of a face. As a simple example, you can specify |
| 112 that the foreground of the default face be | |
| 428 | 113 |
| 114 @itemize @bullet | |
| 115 @item | |
| 116 blue for a particular buffer | |
| 117 @item | |
| 118 green for all other buffers | |
| 119 @end itemize | |
| 120 | |
| 121 As a more complicated example, you could specify that the foreground of | |
| 122 the default face be | |
| 123 | |
| 124 @itemize @bullet | |
| 125 @item | |
| 126 forest green for all buffers displayed in a particular Emacs window, or | |
| 127 green if the X server doesn't recognize the color @samp{forest green} | |
| 128 @item | |
| 129 blue for all buffers displayed in a particular frame | |
| 130 @item | |
| 131 red for all other buffers displayed on a color device | |
| 132 @item | |
| 133 white for all other buffers | |
| 134 @end itemize | |
| 135 | |
| 1135 | 136 @node Simple Specifier Usage |
| 137 @section Simple Specifier Usage | |
| 138 @cindex specifier examples | |
| 139 @cindex examples, specifier | |
| 140 @cindex adding a button to a toolbar | |
| 141 @cindex toolbar button, adding | |
| 142 | |
| 143 A useful specifier application is adding a button to a toolbar. XEmacs | |
| 144 provides several toolbars, one along each edge of the frame. Normally | |
| 145 only one is used at a time, the default. The default toolbar is | |
| 1875 | 146 actually a specifier object which is the value of |
| 147 @code{default-toolbar}. @xref{Toolbar Intro}. | |
| 1135 | 148 |
| 149 The specification of a toolbar is simple: it is a list of buttons. | |
| 150 Each button is a vector with four elements: an icon, a command, the | |
| 151 enabled flag, and a help string. Let's retrieve the instance of the | |
| 152 toolbar you see in the selected frame. | |
| 153 | |
| 154 @example | |
| 155 (specifier-instance default-toolbar) | |
| 156 @end example | |
| 157 | |
| 158 The value returned is, as promised, a list of vectors. Now let's build | |
| 159 up a button, and add it to the toolbar. Our button will invoke the last | |
| 160 defined keyboard macro. This is an alternative to | |
| 161 @code{name-last-kbd-macro} for creating a persistent macro, rather than | |
| 162 an alias for @kbd{C-x e}. | |
| 163 | |
| 164 A toolbar button icon can be quite sophisticated, with different images | |
| 165 for button up, button down, and disabled states, and a similar set with | |
| 166 captions. We'll use a very simple icon, but we have to jump through a | |
| 167 few non-obvious hoops designed to support the sophisticated applications. | |
| 168 The rest of the button descriptor is straightforward. | |
| 169 | |
| 170 @example | |
| 171 (setq toolbar-my-kbd-macro-button | |
| 172 `[ (list (make-glyph "MyKbdMac")) | |
| 173 (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro)) | |
| 174 t | |
| 175 "Execute a previously defined keyboard macro." ]) | |
| 176 | |
| 177 (set-specifier default-toolbar | |
| 178 (cons toolbar-my-kbd-macro-button | |
| 179 (specifier-specs default-toolbar 'global)) | |
| 180 'global) | |
| 181 @end example | |
| 182 | |
| 183 To remove the button, just substitute the function @code{delete} for the | |
| 184 @code{cons} above. | |
| 185 | |
| 186 What is the difference between @code{specifier-instance}, which we used | |
| 187 in the example of retrieving the toolbar descriptor, and | |
| 188 @code{specifier-specs}, which was used in the toolbar manipulating code? | |
| 189 @code{specifier-specs} retrieves a copy of the instantiator, which is | |
| 190 abstract and does not depend on context. @code{specifier-instance}, on | |
| 191 the other hand, actually instantiates the specification, and returns the | |
| 192 result for the given context. Another way to express this is: | |
| 193 @code{specifier-specs} takes a @emph{locale} as an argument, while | |
| 194 @code{specifier-instance} takes a @emph{domain}. The reason for | |
| 195 providing @code{specifier-instance} is that sometimes you wish to see | |
| 196 the object that XEmacs will actually use. @code{specifier-specs}, on | |
| 197 the other hand, shows you what the programmer (or user) requested. When | |
| 198 a program manipulates specifications, clearly it's the latter that is | |
| 199 desirable. | |
| 200 | |
| 201 In the case of the toolbar descriptor, it turns out that these are the | |
| 2953 | 202 same: the instantiation process is trivial. However, many specifications |
| 203 have non-trivial instantiation. Compare the results of the following forms | |
| 1135 | 204 on my system. (The @samp{(cdr (first ...))} form is due to my use of |
| 205 Mule. On non-Mule XEmacsen, just use @code{specifier-specs}.) | |
| 206 | |
| 207 @example | |
| 208 (cdr (first (specifier-specs (face-font 'default) 'global))) | |
| 209 => "-*--14-*jisx0208*-0" | |
| 210 | |
| 211 (specifier-instance (face-font 'default)) | |
| 212 #<font-instance "-*--14-*jisx0208*-0" on #<x-device on ":0.0" 0x970> 0xe0028b 0x176b> | |
| 213 @end example | |
| 214 | |
| 215 In this case, @code{specifier-instance} returns an opaque object; | |
| 3674 | 216 Lisp programs can't work on it, they can only pass it around. Worse, in some |
| 1135 | 217 environments the instantiation will fail, resulting in a different value |
| 218 (when another instantiation succeeds), or worse yet, an error, if all | |
| 2953 | 219 attempts to instantiate the specifier fail. @code{specifier-instance} is |
| 1135 | 220 context-dependent, even for the exact same specification. |
| 221 @code{specifier-specs} is deterministic, and only depends on the | |
| 222 specifications. | |
| 223 | |
| 224 Note that in the toolbar-changing code we operate in the global locale. | |
| 225 This means that narrower locales, if they have specifications, will | |
| 2953 | 226 shadow our changes. (Specifier instantiation does not merge |
| 1135 | 227 specifications. It selects the "highest-priority successful |
| 2953 | 228 specification" and instantiates that.) |
| 1135 | 229 |
| 230 In fact, in our example, it seems pretty likely that different buffers | |
| 231 @emph{should} have different buttons. (The icon can be the same, but | |
| 232 the keyboard macro you create in a Dired buffer is highly unlikely to be | |
| 233 useful in a LaTeX buffer!) Here's one way to implement this: | |
| 234 | |
| 235 @example | |
| 236 (setq toolbar-my-kbd-macro-button | |
| 237 `[ (list (make-glyph "MyKbdMac")) | |
| 238 (lambda () (interactive) (execute-kbd-macro ,last-kbd-macro)) | |
| 239 t | |
| 240 "Execute a previously defined keyboard macro." ]) | |
| 241 | |
| 242 (set-specifier default-toolbar | |
| 243 (cons toolbar-my-kbd-macro-button | |
| 244 (cond ((specifier-specs default-toolbar | |
| 245 (current-buffer))) | |
| 246 ((specifier-specs default-toolbar | |
| 247 'global))) | |
| 248 (current-buffer)) | |
| 249 @end example | |
| 250 | |
| 251 Finally, a cautionary note: the use of @code{specifier-specs} in the | |
| 252 code above is for expository purposes. Don't use it in production code. | |
| 253 In fact, the @code{set-specifier} form above is likely to fail | |
| 254 occasionally, because you can add many specifications for the same | |
| 255 locale. | |
| 256 | |
| 257 In these cases, @code{specifier-specs} will return a list. A further | |
| 258 refinement is that a specification may be associated with a set of | |
| 259 @dfn{specifier tags}. If the list of specifier tags is non-nil, then | |
| 260 @code{specifier-specs} will return a cons of the tag set and the | |
| 261 instantiator. Evidently @code{specifier-specs} is a bit unreliable. | |
| 262 (For toolbars, the code above should work 99% of the time, because | |
| 263 toolbars are rarely changed. Since instantiation is trivial, multiple | |
| 264 specs are not useful---the first one always succeeds.) | |
| 265 | |
| 266 In fact, @code{specifier-specs} is intended to be used to display specs | |
| 1138 | 267 to humans with a minimum of clutter. The robust way to access |
| 268 specifications is via @code{specifier-spec-list}. @xref{Adding | |
| 269 Specifications}, for the definition of @dfn{spec-list}. @xref{Retrieving | |
| 270 Specifications}, for documentation of @code{specifier-specs} and | |
| 271 @code{specifier-spec-list}. To get the desired effect, replace the form | |
| 272 @code{(specifier-spec default-toolbar 'global)} with | |
| 1135 | 273 |
| 274 @example | |
| 275 (cdr (second (first (specifier-spec-list default-toolbar 'global)))) | |
| 276 @end example | |
| 277 | |
| 278 (It should be obvious why the example uses the lazy unreliable method!) | |
| 279 | |
| 428 | 280 @node Specifiers In-Depth |
| 281 @section In-Depth Overview of a Specifier | |
| 282 @cindex specification (in a specifier) | |
| 283 @cindex domain (in a specifier) | |
| 284 @cindex locale (in a specifier) | |
| 285 @cindex instantiator (in a specifier) | |
| 2953 | 286 @cindex instantiation (in a specifier) |
| 428 | 287 @cindex instance (in a specifier) |
| 288 @cindex inst-list (in a specifier) | |
| 289 @cindex inst-pair (in a specifier) | |
| 290 @cindex tag (in a specifier) | |
| 291 @cindex tag set (in a specifier) | |
| 292 @cindex specifier, specification | |
| 293 @cindex specifier, domain | |
| 294 @cindex specifier, locale | |
| 295 @cindex specifier, instantiator | |
| 2953 | 296 @cindex specifier, instantiation |
| 428 | 297 @cindex specifier, instance |
| 298 @cindex specifier, inst-list | |
| 299 @cindex specifier, inst-pair | |
| 300 @cindex specifier, tag | |
| 301 @cindex specifier, tag set | |
| 302 | |
| 1135 | 303 Having variables vary according the editing context is very useful, and |
| 304 the buffer is the natural ``atomic'' unit of editing context. In a GUI | |
| 305 environment, it can be similarly useful to have variables whose values | |
| 306 vary according to display context. The atomic unit of display context | |
| 307 is the Emacs window. Buffers are cleanly grouped by modes, but windows | |
| 308 are not so easily pigeonholed. On the one hand, a window displays a | |
| 309 buffer, and thus one possible hierarchy is window, buffer, mode. On the | |
| 310 other, a window is a component of a frame. This generates the window, | |
| 311 frame, device hierarchy. Finally, there are objects such as toolbars | |
| 312 whose properties are described by specifiers. These do not fit | |
| 313 naturally into either hierarchy. This problem is as yet not cleanly | |
| 314 solved. | |
| 315 | |
| 316 Another potential source of conceptual confusion is the instantiation | |
| 317 process. Instantiating a buffer-local variable is simple: at any given | |
| 318 point in time there is a current buffer, and its local values are used | |
| 319 and set whenever the variable is accessed, unless the programmer goes to | |
| 320 some special effort (uses @code{default-value} and @code{set-default}. | |
| 321 However, a specifier object encapsulates a set of @dfn{specifications}, | |
| 322 each of which says what its value should be if a particular condition | |
| 323 applies. Several such conditions might apply simultaneously in a given | |
| 324 window. | |
| 325 | |
| 428 | 326 For example, one specification might be ``The value should be |
| 327 darkseagreen2 on X devices'' another might be ``The value should be blue | |
| 1135 | 328 in the *Help* buffer''. So what do we do for "the *Help* buffer on an X |
| 329 device"? The answer is simple: give each type of locale a priority and | |
| 330 check them in priority order, returning the first instantiator that | |
| 331 successfully instantiates a value. | |
| 332 | |
| 428 | 333 Given a specifier, a logical question is ``What is its value in a |
| 334 particular situation?'' This involves looking through the specifications | |
| 335 to see which ones apply to this particular situation, and perhaps | |
| 336 preferring one over another if more than one applies. In specifier | |
| 337 terminology, a ``particular situation'' is called a @dfn{domain}, and | |
| 2953 | 338 determining its value in a particular domain is called @dfn{instantiation}. |
| 428 | 339 Most of the time, a domain is identified by a particular window. For |
| 340 example, if the redisplay engine is drawing text in the default face in | |
| 341 a particular window, it retrieves the specifier for the foreground color | |
| 2953 | 342 of the default face and @dfn{instantiates} it in the domain given by that |
| 428 | 343 window; in other words, it asks the specifier, ``What is your value in |
| 344 this window?''. | |
| 345 | |
| 1135 | 346 Note that the redisplay example is in a sense canonical. That is, |
| 347 specifiers are designed to present a uniform and @emph{efficient} API | |
| 348 to redisplay. It is the efficiency constraint that motivates the | |
| 349 introduction of specifier tags, and many restrictions on access (for | |
| 350 example, a buffer is not a domain, and you cannot instantiate a | |
| 351 specifier over a buffer). | |
| 352 | |
| 428 | 353 More specifically, a specifier contains a set of @dfn{specifications}, |
| 354 each of which associates a @dfn{locale} (a window object, a buffer | |
| 355 object, a frame object, a device object, or the symbol @code{global}) | |
| 356 with an @dfn{inst-list}, which is a list of one or more | |
| 357 @dfn{inst-pairs}. (For each possible locale, there can be at most one | |
| 358 specification containing that locale.) Each inst-pair is a cons of a | |
| 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 | |
| 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. | |
| 363 | |
| 3674 | 364 The tag set is used to restrict the sorts of devices and character sets |
| 365 over which the instantiator is valid and to uniquely identify | |
| 366 instantiators added by a particular application, so that different | |
| 367 applications can work on the same specifier and not interfere with each | |
| 368 other. | |
| 369 | |
| 370 Each tag can have a @dfn{device-predicate} associated with it, which is | |
| 371 a function of one argument (a device) that specifies whether the tag | |
| 372 matches that particular device. (If a tag does not have a predicate, it | |
| 373 matches all devices.) All tags in a tag set must match a device for the | |
| 374 associated inst-pair to be instantiable over that device. (A null tag | |
| 375 set is perfectly valid, and trivially matches all devices.) | |
| 376 | |
| 377 Each tag can also have a @dfn{charset-predicate} associated with it; | |
| 378 this is a function that takes one charset argument, and specifies | |
| 379 whether that tag matches that particular charset. When instantiating a | |
| 380 face over a given domain with a given charset, the | |
| 381 @code{charset-predicate} attribute of a tag is consulted@footnote{Not | |
| 382 quite the case; the result of the functions are pre-calculated and | |
| 383 cached whenever @code{define-specifier-tag} or @code{make-charset} is | |
| 384 called.} to decide whether this inst-pair matches the charset. If the | |
| 385 @code{charset-predicate} function of a tag is unspecified, that tag | |
| 386 defaults to matching all charsets. | |
| 428 | 387 |
| 3674 | 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. | |
| 428 | 412 |
| 2953 | 413 When a specifier is instantiated in a domain, both the locale and the tag |
| 428 | 414 set can be viewed as specifying necessary conditions that must apply in |
| 415 that domain for an instantiator to be considered as a possible result of | |
| 2953 | 416 the instantiation. More specific locales always override more general |
| 428 | 417 locales (thus, there is no particular ordering of the specifications in |
| 418 a specifier); however, the tag sets are simply considered in the order | |
| 419 that the inst-pairs occur in the specification's inst-list. | |
| 420 | |
| 2953 | 421 Note also that the actual object that results from the instantiation |
| 428 | 422 (called an @dfn{instance object}) may not be the same as the instantiator |
| 423 from which it was derived. For some specifier types (such as integer | |
| 424 specifiers and boolean specifiers), the instantiator will be returned | |
| 425 directly as the instance object. For other types, however, this | |
| 426 is not the case. For example, for font specifiers, the instantiator | |
| 427 is a font-description string and the instance object is a font-instance | |
| 428 object, which describes how the font is displayed on a particular device. | |
| 429 A font-instance object encapsulates such things as the actual font name | |
| 430 used to display the font on that device (a font-description string | |
| 431 under X is usually a wildcard specification that may resolve to | |
| 432 different font names, with possibly different foundries, widths, etc., | |
| 433 on different devices), the extra properties of that font on that | |
| 434 device, etc. Furthermore, this conversion (called @dfn{instantiation}) | |
| 440 | 435 might fail---a font or color might not exist on a particular device, |
| 428 | 436 for example. |
| 437 | |
| 2953 | 438 @node Specifier Instantiation |
| 439 @section How a Specifier Is Instantiated | |
| 428 | 440 @cindex fallback (in a specifier) |
| 441 @cindex specifier, fallback | |
| 442 | |
| 2953 | 443 Instantiation of a specifier in a particular window domain proceeds as |
| 428 | 444 follows: |
| 445 | |
| 446 @itemize @bullet | |
| 447 @item | |
| 448 First, XEmacs searches for a specification whose locale is the same as | |
| 449 the window. If that fails, the search is repeated, looking for a locale | |
| 450 that is the same as the window's buffer. If that fails, the search is | |
| 451 repeated using the window's frame, then using the device that frame is | |
| 452 on. Finally, the specification whose locale is the symbol @code{global} | |
| 453 (if there is such a specification) is considered. | |
| 454 @item | |
| 455 The inst-pairs contained in the specification that was found are | |
| 456 considered in their order in the inst-list, looking for one whose tag | |
| 457 set matches the device that is derived from the window domain. (The | |
| 458 tag set is an unordered list of zero or more tag symbols. For all | |
| 459 tags that have predicates associated with them, the predicate must | |
| 460 match the device.) | |
| 461 @item | |
| 462 If a matching tag set is found, the corresponding instantiator is passed | |
| 463 to the specifier's instantiation method, which is specific to the type | |
| 464 of the specifier. If it succeeds, the resulting instance object is | |
| 2953 | 465 returned as the result of the instantiation and the instantiation is done. |
| 428 | 466 Otherwise, the operation continues, looking for another matching |
| 467 inst-pair in the current specification. | |
| 468 @item | |
| 469 When there are no more inst-pairs to be considered in the current | |
| 470 specification, the search starts over, looking for another specification | |
| 471 as in the first step above. | |
| 472 @item | |
| 473 If all specifications are exhausted and no instance object can be | |
| 2953 | 474 derived, the instantiation fails. (Actually, this is not completely true. |
| 428 | 475 Some specifier objects for built-in properties have a @dfn{fallback} |
| 476 value, which is either an inst-list or another specifier object, that is | |
| 2953 | 477 consulted if the instantiation is about to fail. If it is an inst-list, |
| 428 | 478 the searching proceeds using the inst-pairs in that list. If it is a |
| 2953 | 479 specifier, the entire instantiation starts over using that specifier |
| 428 | 480 instead of the given one. Fallback values are set by the C code and |
| 481 cannot be modified, except perhaps indirectly, using any Lisp functions. | |
| 482 The purpose of them is to supply some values to make sure that | |
| 2953 | 483 instantiation of built-in properties can't fail and to implement some basic |
| 428 | 484 specifier inheritance, such as the fact that faces inherit their |
| 485 properties from the @code{default} face.) | |
| 486 @end itemize | |
| 487 | |
| 2953 | 488 It is also possible to instantiate a specifier over a frame domain or |
| 428 | 489 device domain instead of over a window domain. The C code, for example, |
| 2953 | 490 instantiates the @code{top-toolbar-height} variable over a frame domain in |
| 491 order to determine the height of a frame's top toolbar. Instantiation over | |
| 492 a frame or device is similar to instantiation over a window except that | |
| 428 | 493 specifications for locales that cannot be derived from the domain are |
| 2953 | 494 ignored. Specifically, instantiation over a frame looks first for frame |
| 495 locales, then device locales, then the @code{global} locale. Instantiation | |
| 428 | 496 over a device domain looks only for device locales and the @code{global} |
| 497 locale. | |
| 498 | |
| 2953 | 499 Note that specifiers are instantiated on @emph{every} redisplay. (This is |
| 2141 | 500 the concept; of course the implementation keeps track of changes and |
| 2953 | 501 doesn't reinstantiate unchanged specifiers.) That means that changes in |
| 2141 | 502 specifiers controlling appearance are reflected immediately in the UI. |
| 2953 | 503 Also, since specifiers are instantiated completely, removing a |
| 2141 | 504 specification can be just as effective as adding one. |
| 505 | |
| 506 @emph{E.g.}, Giacomo Boffi wanted a modeline that indicates whether the | |
| 507 frame containing it is selected or not. The first proposed implementation | |
| 508 is natural in a world of ``local'' variables. The later implementations | |
| 509 apply the power of specifiers. | |
| 510 | |
| 511 (The copyright notice and permission statement below apply to the code in | |
| 512 example format, up to the ``@code{;;; end of neon-modeline.el}'' | |
| 513 comment.) | |
| 514 | |
| 515 @example | |
| 516 ;;; neon-modeline.el | |
| 517 | |
| 518 ;; Copyright (c) 2004 Stephen J. Turnbull <stephen@@xemacs.org> | |
| 519 | |
| 520 ;; Based on a suggestion by Giacomo Boffi | |
| 521 | |
| 522 ;; This code may be used and redistributed under the GNU GPL, v.2 or any | |
| 523 ;; later version as published by the FSF, or under the license used for | |
| 524 ;; XEmacs Texinfo manuals, at your option. | |
| 525 @end example | |
| 526 | |
| 527 A few customizations: | |
| 528 | |
| 529 @example | |
| 530 ;; Placate the specifier and Customize gods. | |
| 531 | |
| 532 (unless (valid-specifier-tag-p 'modeline-background) | |
| 533 (define-specifier-tag 'modeline-background)) | |
| 534 | |
| 535 (defgroup lisp-demos nil "Demos for Lisp programming techniques.") | |
| 536 | |
| 537 (defgroup neon-modeline nil "Neon modeline identifies selected frame." | |
| 538 :group 'lisp-demos) | |
| 539 | |
| 540 (defcustom neon-modeline-selected-background "LemonChiffon" | |
| 541 "Background color for modeline in selected frames." | |
| 542 :type 'color | |
| 543 :group 'neon-modeline) | |
| 544 | |
| 545 (defcustom neon-modeline-deselected-background "Wheat" | |
| 546 "Background color for modeline in unselected frames." | |
| 547 :type 'color | |
| 548 :group 'neon-modeline) | |
| 549 | |
| 550 @end example | |
| 551 | |
| 552 Our first try uses three functions, a setup and two hook functions. | |
| 553 Separate hooks are defined for entry into a frame and exit from it. | |
| 554 Since we're using hooks, it's a fairly natural approach: we operate on | |
| 555 the background on each event corresponding to an appearance change we | |
| 556 want to make. This doesn't depend on the specifier API, ``frame-local'' | |
| 557 variables would serve as well. | |
| 558 | |
| 559 @example | |
| 560 (defun select-modeline () | |
| 561 (set-face-background 'modeline neon-modeline-selected-background | |
| 562 (selected-frame))) | |
| 563 | |
| 564 (defun deselect-modeline () | |
| 565 (set-face-background 'modeline neon-modeline-deselected-background | |
| 566 (selected-frame))) | |
| 567 @end example | |
| 568 | |
| 569 Note that the initialization removes no specifications, and therefore is | |
| 570 not idempotent. Cruft will accumulate in the specifier if the | |
| 571 @samp{-setup} function is called repeatedly. This shouldn't cause a | |
| 572 performance problem; specifiers are quite efficient for their purpose. | |
| 573 But it's ugly, and wastes a small amount of space. | |
| 574 | |
| 575 @example | |
| 576 (defun neon-modeline-setup () | |
| 577 (interactive) | |
| 578 (set-face-background 'modeline neon-modeline-deselected-background) | |
| 579 ;; Add the distinguished background on pointer entry to the frame; | |
| 580 (add-hook 'select-frame-hook 'select-modeline) | |
| 581 ;; restore the ordinary background on pointer exit from the frame. | |
| 582 (add-hook 'deselect-frame-hook 'deselect-modeline) | |
| 583 @end example | |
| 584 | |
| 585 This approach causes a decided flicker on Boffi's platform, because the | |
| 586 two hook functions are executed in response to separate GUI events. | |
| 587 | |
| 588 The following code should be an improvement. First, the hook function. | |
| 589 | |
| 590 @example | |
| 591 (defun neon-modeline-reselect () | |
| 592 (set-face-background 'modeline neon-modeline-deselected-background | |
| 593 (selected-frame) '(modeline-background) | |
| 594 'remove-locale-type)) | |
| 595 @end example | |
| 596 | |
| 597 Only one event triggers the configuration change, which should reduce | |
| 598 flicker. Because this is implemented as a specifier, we can use the | |
| 599 specifier API to reset all frame-local specifications (the | |
| 600 @code{remove-locale-type} argument). This leaves the @code{global} | |
| 601 specification alone, but removes all existing frame-local | |
| 602 specifications. Then it adds the selected-frame background | |
| 603 specification for the newly selected frame. @emph{I.e.}, this | |
| 604 effectively implements a ``move specification from frame to frame'' | |
| 605 operation. | |
| 606 | |
| 607 Why does it give the desired result? By ensuring that only one frame | |
| 608 has the selected-frame modeline background. Frame-local specifications | |
| 609 have precedence over global ones, so when the modeline background is | |
| 610 instantiated in the selected frame, it matches the specification set up | |
| 611 for it and gets the right color. On the other hand, in any other frame, | |
| 612 it does not match the selected frame, so it falls through the | |
| 613 frame-local specifications and picks up the global specification. Again | |
| 614 we get the desired color, in this case for unselected frames. | |
| 615 | |
| 616 Here the @code{modeline-background} tag is simply good practice | |
| 617 (identifying an application's specifications allows it to avoid | |
| 618 interfering with other applications, and other well-behaved applications | |
| 619 and Customize should not munge specifications with our tag on them). | |
| 620 However, an alternative implementation of this functionality would be | |
| 621 | |
| 622 @example | |
| 623 (defun neon-modeline-reselect-2 () | |
| 624 (set-face-background 'modeline neon-modeline-deselected-background | |
| 625 (selected-frame) '(modeline-background) | |
| 626 'remove-tag-set-prepend)) | |
| 627 @end example | |
| 628 | |
| 629 @code{neon-modeline-reselect} may be a preferable implementation here, if we | |
| 630 really want only one frame to have a local specification. The | |
| 631 @code{neon-modeline-reselect-2} style would be useful if we had groups of | |
| 632 frames which have @emph{different} modeline backgrounds when deselected. | |
| 633 | |
| 634 Here's the initialization function, with different semantics from above. | |
| 635 Note that it is destructive, unless the user saves off the state of the | |
| 636 modeline face before invoking the function. This is only a problem if | |
| 637 you remove specifications and expect the older ones to persist. In this | |
| 638 example it should not be an issue. We use the customizations defined | |
| 639 above. | |
| 640 | |
| 641 @example | |
| 642 (defun neon-modeline-modified-setup () | |
| 643 (interactive) | |
| 644 (set-face-background 'modeline neon-modeline-selected-background | |
| 645 'global nil 'remove-all) | |
| 646 (add-hook 'select-frame-hook 'neon-modeline-reselect) | |
| 647 | |
| 648 ;;; end of neon-modeline.el | |
| 649 @end example | |
| 650 | |
| 651 Note the use of @code{'remove-all} to clear out stale specifications. | |
| 652 Thus it will be idempotent. | |
| 653 | |
| 654 | |
| 428 | 655 @node Specifier Types |
| 656 @section Specifier Types | |
| 657 | |
| 658 There are various different types of specifiers. The type of a | |
| 659 specifier controls what sorts of instantiators are valid, how an | |
| 660 instantiator is instantiated, etc. Here is a list of built-in specifier | |
| 661 types: | |
| 662 | |
| 663 @table @code | |
| 664 @item boolean | |
| 665 The valid instantiators are the symbols @code{t} and @code{nil}. | |
| 666 Instance objects are the same as instantiators so no special | |
| 667 instantiation function is needed. | |
| 668 | |
| 669 @item integer | |
| 670 The valid instantiators are integers. Instance objects are the same as | |
| 671 instantiators so no special instantiation function is needed. | |
| 672 @code{modeline-shadow-thickness} is an example of an integer specifier | |
| 673 (negative thicknesses indicate that the shadow is drawn recessed instead | |
| 674 of raised). | |
| 675 | |
| 676 @item natnum | |
| 677 The valid instantiators are natnums (non-negative integers). Instance | |
| 678 objects are the same as instantiators so no special instantiation | |
| 679 function is needed. Natnum specifiers are used for dimension variables | |
| 680 such as @code{top-toolbar-height}. | |
| 681 | |
| 682 @item generic | |
| 683 All Lisp objects are valid instantiators. Instance objects are the same | |
| 684 as instantiators so no special instantiation function is needed. | |
| 685 | |
| 686 @item font | |
| 687 The valid instantiators are strings describing fonts or vectors | |
| 688 indicating inheritance from the font of some face. Instance objects are | |
| 689 font-instance objects, which are specific to a particular device. The | |
| 690 instantiation method for font specifiers can fail, unlike for integer, | |
| 691 natnum, boolean, and generic specifiers. | |
| 692 | |
| 693 @item color | |
| 694 The valid instantiators are strings describing colors or vectors | |
| 695 indicating inheritance from the foreground or background of some face. | |
| 696 Instance objects are color-instance objects, which are specific to a | |
| 697 particular device. The instantiation method for color specifiers can fail, | |
| 698 as for font specifiers. | |
| 699 | |
| 700 @item image | |
| 701 Images are perhaps the most complicated type of built-in specifier. The | |
| 702 valid instantiators are strings (a filename, inline data for a pixmap, | |
| 703 or text to be displayed in a text glyph) or vectors describing inline | |
| 704 data of various sorts or indicating inheritance from the | |
| 705 background-pixmap property of some face. Instance objects are either | |
| 706 strings (for text images), image-instance objects (for pixmap images), | |
| 707 or subwindow objects (for subwindow images). The instantiation method | |
| 708 for image specifiers can fail, as for font and color specifiers. | |
| 709 | |
| 710 @item face-boolean | |
| 711 The valid instantiators are the symbols @code{t} and @code{nil} and | |
| 712 vectors indicating inheritance from a boolean property of some face. | |
| 713 Specifiers of this sort are used for all of the built-in boolean | |
| 714 properties of faces. Instance objects are either the symbol @code{t} | |
| 715 or the symbol @code{nil}. | |
| 716 | |
| 717 @item toolbar | |
| 718 The valid instantiators are toolbar descriptors, which are lists | |
| 719 of toolbar-button descriptors (each of which is a vector of two | |
| 720 or four elements). @xref{Toolbar}, for more information. | |
| 721 @end table | |
| 722 | |
| 723 Color and font instance objects can also be used in turn as | |
| 724 instantiators for a new color or font instance object. Since these | |
| 725 instance objects are device-specific, the instantiator can be used | |
| 726 directly as the new instance object, but only if they are of the same | |
| 727 device. If the devices differ, the base color or font of the | |
| 728 instantiating object is effectively used instead as the instantiator. | |
| 729 | |
| 730 @xref{Faces and Window-System Objects}, for more information on fonts, | |
| 731 colors, and face-boolean specifiers. @xref{Glyphs}, for more information | |
| 732 about image specifiers. @xref{Toolbar}, for more information on toolbar | |
| 733 specifiers. | |
| 734 | |
| 735 @defun specifier-type specifier | |
| 736 This function returns the type of @var{specifier}. The returned value | |
| 737 will be a symbol: one of @code{integer}, @code{boolean}, etc., as | |
| 738 listed in the above table. | |
| 739 @end defun | |
| 740 | |
| 741 Functions are also provided to query whether an object is a particular | |
| 742 kind of specifier: | |
| 743 | |
| 744 @defun boolean-specifier-p object | |
| 745 This function returns non-@code{nil} if @var{object} is a boolean | |
| 746 specifier. | |
| 747 @end defun | |
| 748 | |
| 749 @defun integer-specifier-p object | |
| 750 This function returns non-@code{nil} if @var{object} is an integer | |
| 751 specifier. | |
| 752 @end defun | |
| 753 | |
| 754 @defun natnum-specifier-p object | |
| 755 This function returns non-@code{nil} if @var{object} is a natnum | |
| 756 specifier. | |
| 757 @end defun | |
| 758 | |
| 759 @defun generic-specifier-p object | |
| 760 This function returns non-@code{nil} if @var{object} is a generic | |
| 761 specifier. | |
| 762 @end defun | |
| 763 | |
| 764 @defun face-boolean-specifier-p object | |
| 765 This function returns non-@code{nil} if @var{object} is a face-boolean | |
| 766 specifier. | |
| 767 @end defun | |
| 768 | |
| 769 @defun toolbar-specifier-p object | |
| 770 This function returns non-@code{nil} if @var{object} is a toolbar | |
| 771 specifier. | |
| 772 @end defun | |
| 773 | |
| 774 @defun font-specifier-p object | |
| 775 This function returns non-@code{nil} if @var{object} is a font | |
| 776 specifier. | |
| 777 @end defun | |
| 778 | |
| 779 @defun color-specifier-p object | |
| 780 This function returns non-@code{nil} if @var{object} is a color | |
| 781 specifier. | |
| 782 @end defun | |
| 783 | |
| 784 @defun image-specifier-p object | |
| 785 This function returns non-@code{nil} if @var{object} is an image | |
| 786 specifier. | |
| 787 @end defun | |
| 788 | |
| 789 @node Adding Specifications | |
| 790 @section Adding specifications to a Specifier | |
| 791 | |
| 792 @defun add-spec-to-specifier specifier instantiator &optional locale tag-set how-to-add | |
| 793 This function adds a specification to @var{specifier}. The | |
| 794 specification maps from @var{locale} (which should be a window, buffer, | |
| 795 frame, device, or the symbol @code{global}, and defaults to | |
| 796 @code{global}) to @var{instantiator}, whose allowed values depend on the | |
| 797 type of the specifier. Optional argument @var{tag-set} limits the | |
| 798 instantiator to apply only to the specified tag set, which should be a | |
| 799 list of tags all of which must match the device being instantiated over | |
| 800 (tags are a device type, a device class, or tags defined with | |
| 801 @code{define-specifier-tag}). Specifying a single symbol for | |
| 802 @var{tag-set} is equivalent to specifying a one-element list containing | |
| 803 that symbol. Optional argument @var{how-to-add} specifies what to do if | |
| 804 there are already specifications in the specifier. It should be one of | |
| 805 | |
| 806 @table @code | |
| 807 @item prepend | |
| 808 Put at the beginning of the current list of instantiators for @var{locale}. | |
| 809 @item append | |
| 810 Add to the end of the current list of instantiators for @var{locale}. | |
| 811 @item remove-tag-set-prepend | |
| 812 This is the default. Remove any existing instantiators whose tag set is | |
| 813 the same as @var{tag-set}; then put the new instantiator at the | |
| 814 beginning of the current list. | |
| 815 @item remove-tag-set-append | |
| 816 Remove any existing instantiators whose tag set is the same as | |
| 817 @var{tag-set}; then put the new instantiator at the end of the current | |
| 818 list. | |
| 819 @item remove-locale | |
| 820 Remove all previous instantiators for this locale before adding the new | |
| 821 spec. | |
| 822 @item remove-locale-type | |
| 823 Remove all specifications for all locales of the same type as | |
| 824 @var{locale} (this includes @var{locale} itself) before adding the new | |
| 825 spec. | |
| 826 @item remove-all | |
| 827 Remove all specifications from the specifier before adding the new spec. | |
| 828 @end table | |
| 829 | |
| 830 @code{remove-tag-set-prepend} is the default. | |
| 831 | |
| 832 You can retrieve the specifications for a particular locale or locale type | |
| 833 with the function @code{specifier-spec-list} or @code{specifier-specs}. | |
| 834 @end defun | |
| 835 | |
| 836 @defun add-spec-list-to-specifier specifier spec-list &optional how-to-add | |
| 837 This function adds a @dfn{spec-list} (a list of specifications) to | |
| 838 @var{specifier}. The format of a spec-list is | |
| 839 | |
| 840 @example | |
| 841 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)} | |
| 842 @end example | |
| 843 | |
| 844 where | |
| 845 | |
| 846 @itemize @bullet | |
| 847 @item | |
| 848 @var{locale} := a window, a buffer, a frame, a device, or @code{global} | |
| 849 @item | |
| 850 @var{tag-set} := an unordered list of zero or more @var{tags}, each of | |
| 851 which is a symbol | |
| 852 @item | |
| 853 @var{tag} := a device class (@pxref{Consoles and Devices}), a device type, | |
| 854 or a tag defined with @code{define-specifier-tag} | |
| 855 @item | |
| 856 @var{instantiator} := format determined by the type of specifier | |
| 857 @end itemize | |
| 858 | |
| 859 The pair @code{(@var{tag-set} . @var{instantiator})} is called an | |
| 860 @dfn{inst-pair}. A list of inst-pairs is called an @dfn{inst-list}. | |
| 861 The pair @code{(@var{locale} . @var{inst-list})} is called a | |
| 862 @dfn{specification}. A spec-list, then, can be viewed as a list of | |
| 863 specifications. | |
| 864 | |
| 865 @var{how-to-add} specifies how to combine the new specifications with | |
| 866 the existing ones, and has the same semantics as for | |
| 867 @code{add-spec-to-specifier}. | |
| 868 | |
| 1875 | 869 The higher-level function @code{set-specifier} is often |
| 870 more convenient because it allows abbreviations of spec-lists to be used | |
| 871 instead of the heavily nested canonical syntax. However, one should | |
| 872 take great care in using them with specifiers types which can have lists | |
| 873 as instantiators, such as toolbar specifiers and generic specifiers. In | |
| 874 those cases it's probably best to use @code{add-spec-to-specifier} or | |
| 875 @code{add-spec-list-to-specifier}. | |
| 428 | 876 @end defun |
| 877 | |
| 444 | 878 @defspec let-specifier specifier-list &rest body |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3674
diff
changeset
|
879 This macro temporarily adds specifications to specifiers, |
| 428 | 880 evaluates forms in @var{body} and restores the specifiers to their |
| 881 previous states. The specifiers and their temporary specifications are | |
| 882 listed in @var{specifier-list}. | |
| 883 | |
| 884 The format of @var{specifier-list} is | |
| 885 | |
| 886 @example | |
| 887 ((@var{specifier} @var{value} &optional @var{locale} @var{tag-set} @var{how-to-add}) ...) | |
| 888 @end example | |
| 889 | |
| 890 @var{specifier} is the specifier to be temporarily modified. | |
| 891 @var{value} is the instantiator to be temporarily added to specifier in | |
| 892 @var{locale}. @var{locale}, @var{tag-set} and @var{how-to-add} have the | |
| 893 same meaning as in @code{add-spec-to-specifier}. | |
| 894 | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3674
diff
changeset
|
895 The code resulting from macro expansion will add specifications to |
|
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3674
diff
changeset
|
896 specifiers using @code{add-spec-to-specifier}. After forms in |
|
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3674
diff
changeset
|
897 @var{body} are evaluated, the temporary specifications are removed and |
|
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
3674
diff
changeset
|
898 old specifier spec-lists are restored. |
| 428 | 899 |
| 900 @var{locale}, @var{tag-set} and @var{how-to-add} may be omitted, and | |
| 901 default to @code{nil}. The value of the last form in @var{body} is | |
| 902 returned. | |
| 903 | |
| 904 NOTE: If you want the specifier's instance to change in all | |
| 905 circumstances, use @code{(selected-window)} as the @var{locale}. If | |
| 906 @var{locale} is @code{nil} or omitted, it defaults to @code{global}. | |
| 907 | |
| 908 The following example removes the 3D modeline effect in the currently | |
| 909 selected window for the duration of a second: | |
| 910 | |
| 911 @example | |
| 912 (let-specifier ((modeline-shadow-thickness 0 (selected-window))) | |
| 913 (sit-for 1)) | |
| 914 @end example | |
| 444 | 915 @end defspec |
| 428 | 916 |
| 444 | 917 @defun set-specifier specifier value &optional locale tag-set how-to-add |
| 428 | 918 This function adds some specifications to @var{specifier}. @var{value} |
| 919 can be a single instantiator or tagged instantiator (added as a global | |
| 920 specification), a list of tagged and/or untagged instantiators (added as | |
| 921 a global specification), a cons of a locale and instantiator or locale | |
| 922 and instantiator list, a list of such conses, or nearly any other | |
| 923 reasonable form. More specifically, @var{value} can be anything | |
| 1875 | 924 accepted by @code{canonicalize-spec-list} (described below). |
| 428 | 925 |
| 444 | 926 @var{locale}, @var{tag-set}, and @var{how-to-add} are the same as in |
| 927 @code{add-spec-to-specifier}. | |
| 428 | 928 |
| 929 Note that @code{set-specifier} is exactly complementary to | |
| 930 @code{specifier-specs} except in the case where @var{specifier} has no | |
| 931 specs at all in it but @code{nil} is a valid instantiator (in that case, | |
| 932 @code{specifier-specs} will return @code{nil} (meaning no specs) and | |
| 933 @code{set-specifier} will interpret the @code{nil} as meaning ``I'm | |
| 934 adding a global instantiator and its value is @code{nil}''), or in | |
| 935 strange cases where there is an ambiguity between a spec-list and an | |
| 936 inst-list, etc. (The built-in specifier types are designed in such a way | |
| 1875 | 937 as to avoid any such ambiguities.) For robust code, |
| 938 @code{set-specifier} should probably be avoided for specifier types | |
| 939 which accept lists as instantiators (currently toolbar specifiers and | |
| 940 generic specifiers). | |
| 428 | 941 |
| 942 If you want to work with spec-lists, you should probably not use these | |
| 943 functions, but should use the lower-level functions | |
| 944 @code{specifier-spec-list} and @code{add-spec-list-to-specifier}. These | |
| 945 functions always work with fully-qualified spec-lists; thus, there is no | |
| 946 ambiguity. | |
| 947 @end defun | |
| 948 | |
| 949 @defun canonicalize-inst-pair inst-pair specifier-type &optional noerror | |
| 950 This function canonicalizes the given @var{inst-pair}. | |
| 951 | |
| 952 @var{specifier-type} specifies the type of specifier that this | |
| 953 @var{spec-list} will be used for. | |
| 954 | |
| 955 Canonicalizing means converting to the full form for an inst-pair, i.e. | |
| 956 @code{(@var{tag-set} . @var{instantiator})}. A single, untagged | |
| 957 instantiator is given a tag set of @code{nil} (the empty set), and a | |
| 958 single tag is converted into a tag set consisting only of that tag. | |
| 959 | |
| 960 If @var{noerror} is non-@code{nil}, signal an error if the inst-pair is | |
| 961 invalid; otherwise return @code{t}. | |
| 962 @end defun | |
| 963 | |
| 964 @defun canonicalize-inst-list inst-list specifier-type &optional noerror | |
| 965 This function canonicalizes the given @var{inst-list} (a list of | |
| 966 inst-pairs). | |
| 967 | |
| 968 @var{specifier-type} specifies the type of specifier that this @var{inst-list} | |
| 969 will be used for. | |
| 970 | |
| 971 Canonicalizing means converting to the full form for an inst-list, i.e. | |
| 972 @code{((@var{tag-set} . @var{instantiator}) ...)}. This function | |
| 973 accepts a single inst-pair or any abbreviation thereof or a list of | |
| 974 (possibly abbreviated) inst-pairs. (See @code{canonicalize-inst-pair}.) | |
| 975 | |
| 976 If @var{noerror} is non-@code{nil}, signal an error if the inst-list is | |
| 977 invalid; otherwise return @code{t}. | |
| 978 @end defun | |
| 979 | |
| 980 @defun canonicalize-spec spec specifier-type &optional noerror | |
| 981 This function canonicalizes the given @var{spec} (a specification). | |
| 982 | |
| 983 @var{specifier-type} specifies the type of specifier that this | |
| 984 @var{spec-list} will be used for. | |
| 985 | |
| 986 Canonicalizing means converting to the full form for a spec, i.e. | |
| 987 @code{(@var{locale} (@var{tag-set} . @var{instantiator}) ...)}. This | |
| 988 function accepts a possibly abbreviated inst-list or a cons of a locale | |
| 989 and a possibly abbreviated inst-list. (See | |
| 990 @code{canonicalize-inst-list}.) | |
| 991 | |
| 992 If @var{noerror} is @code{nil}, signal an error if the specification is | |
| 993 invalid; otherwise return @code{t}. | |
| 994 @end defun | |
| 995 | |
| 996 @defun canonicalize-spec-list spec-list specifier-type &optional noerror | |
| 997 This function canonicalizes the given @var{spec-list} (a list of | |
| 998 specifications). | |
| 999 | |
| 1000 @var{specifier-type} specifies the type of specifier that this | |
| 1001 @var{spec-list} will be used for. | |
| 1002 | |
| 1875 | 1003 If @var{noerror} is @code{nil}, signal an error if the spec-list is |
| 1004 invalid; otherwise return @code{t} for an invalid spec-list. (Note that | |
| 1005 this cannot be confused with a canonical spec-list.) | |
| 1006 | |
| 428 | 1007 Canonicalizing means converting to the full form for a spec-list, i.e. |
| 1008 @code{((@var{locale} (@var{tag-set} . @var{instantiator}) ...) ...)}. | |
| 1009 This function accepts a possibly abbreviated specification or a list of | |
| 1010 such things. (See @code{canonicalize-spec}.) This is the function used | |
| 1011 to convert spec-lists accepted by @code{set-specifier} and such into a | |
| 1012 form suitable for @code{add-spec-list-to-specifier}. | |
| 1013 | |
| 1014 This function tries extremely hard to resolve any ambiguities, | |
| 1015 and the built-in specifier types (font, image, toolbar, etc.) are | |
| 1016 designed so that there won't be any ambiguities. | |
| 1017 | |
| 1875 | 1018 The canonicalization algorithm is as follows: |
| 1019 | |
| 1020 @enumerate | |
| 1021 @item | |
| 1022 Attempt to parse @var{spec-list} as a single, possibly abbreviated, | |
| 1023 specification. | |
| 1024 @item | |
| 1025 If that fails, attempt to parse @var{spec-list} as a list of (abbreviated) | |
| 1026 specifications. | |
| 1027 @item | |
| 1028 If that fails, @var{spec-list} is invalid. | |
| 1029 @end enumerate | |
| 1030 | |
| 1031 A possibly abbreviated specification @var{spec} is parsed by | |
| 1032 | |
| 1033 @enumerate | |
| 1034 @item | |
| 1035 Attempt to parse @var{spec} as a possibly abbreviated inst-list. | |
| 1036 @item | |
| 1037 If that fails, attempt to parse @var{spec} as a cons of a locale and an | |
| 1038 (abbreviated) inst-list. | |
| 1039 @item | |
| 1040 If that fails, @var{spec} is invalid. | |
| 1041 @end enumerate | |
| 1042 | |
| 1043 A possibly abbreviated inst-list @var{inst-list} is parsed by | |
| 1044 | |
| 1045 @enumerate | |
| 1046 @item | |
| 1047 Attempt to parse @var{inst-list} as a possibly abbreviated inst-pair. | |
| 1048 @item | |
| 1049 If that fails, attempt to parse @var{inst-list} as a list of (abbreviated) | |
| 1050 inst-pairs. | |
| 1051 @item | |
| 1052 If that fails, @var{inst-list} is invalid. | |
| 1053 @end enumerate | |
| 1054 | |
| 1055 A possibly abbreviated inst-pair @var{inst-pair} is parsed by | |
| 1056 | |
| 1057 @enumerate | |
| 1058 @item | |
| 1059 Check if @var{inst-pair} is @code{valid-instantiator-p}. | |
| 1060 @item | |
| 1061 If not, check if @var{inst-pair} is a cons of something that is a tag, ie, | |
| 1062 @code{valid-specifier-tag-p}, and something that is @code{valid-instantiator-p}. | |
| 1063 @item | |
| 1064 If not, check if @var{inst-pair} is a cons of a list of tags and something that | |
| 1065 is @code{valid-instantiator-p}. | |
| 1066 @item | |
| 1067 Otherwise, @var{inst-pair} is invalid. | |
| 1068 @end enumerate | |
| 1069 | |
| 1070 In summary, this function generally prefers more abbreviated forms. | |
| 428 | 1071 @end defun |
| 1072 | |
| 1073 @node Retrieving Specifications | |
| 1074 @section Retrieving the Specifications from a Specifier | |
| 1075 | |
| 1076 @defun specifier-spec-list specifier &optional locale tag-set exact-p | |
| 1077 This function returns the spec-list of specifications for | |
| 1078 @var{specifier} in @var{locale}. | |
| 1079 | |
| 1080 If @var{locale} is a particular locale (a window, buffer, frame, device, | |
| 1081 or the symbol @code{global}), a spec-list consisting of the | |
| 1082 specification for that locale will be returned. | |
| 1083 | |
| 444 | 1084 If @var{locale} is a locale type (i.e. one of the symbols @code{window}, |
| 428 | 1085 @code{buffer}, @code{frame}, or @code{device}), a spec-list of the |
| 1086 specifications for all locales of that type will be returned. | |
| 1087 | |
| 1088 If @var{locale} is @code{nil} or the symbol @code{all}, a spec-list of | |
| 1089 all specifications in @var{specifier} will be returned. | |
| 1090 | |
| 1091 @var{locale} can also be a list of locales, locale types, and/or | |
| 1092 @code{all}; the result is as if @code{specifier-spec-list} were called | |
| 1093 on each element of the list and the results concatenated together. | |
| 1094 | |
| 1095 Only instantiators where @var{tag-set} (a list of zero or more tags) is | |
| 1096 a subset of (or possibly equal to) the instantiator's tag set are | |
| 444 | 1097 returned. (The default value of @code{nil} is a subset of all tag sets, |
| 428 | 1098 so in this case no instantiators will be screened out.) If @var{exact-p} |
| 1099 is non-@code{nil}, however, @var{tag-set} must be equal to an | |
| 1100 instantiator's tag set for the instantiator to be returned. | |
| 1101 @end defun | |
| 1102 | |
| 1103 @defun specifier-specs specifier &optional locale tag-set exact-p | |
| 1104 This function returns the specification(s) for @var{specifier} in | |
| 1105 @var{locale}. | |
| 1106 | |
| 1107 If @var{locale} is a single locale or is a list of one element | |
| 1108 containing a single locale, then a ``short form'' of the instantiators | |
| 1109 for that locale will be returned. Otherwise, this function is identical | |
| 1110 to @code{specifier-spec-list}. | |
| 1111 | |
| 1112 The ``short form'' is designed for readability and not for ease of use | |
| 1113 in Lisp programs, and is as follows: | |
| 1114 | |
| 1115 @enumerate | |
| 1116 @item | |
| 1117 If there is only one instantiator, then an inst-pair (i.e. cons of tag | |
| 1118 and instantiator) will be returned; otherwise a list of inst-pairs will | |
| 1119 be returned. | |
| 1120 @item | |
| 1121 For each inst-pair returned, if the instantiator's tag is @code{any}, | |
| 1122 the tag will be removed and the instantiator itself will be returned | |
| 1123 instead of the inst-pair. | |
| 1124 @item | |
| 1125 If there is only one instantiator, its value is @code{nil}, and its tag | |
| 1126 is @code{any}, a one-element list containing @code{nil} will be returned | |
| 1127 rather than just @code{nil}, to distinguish this case from there being | |
| 1128 no instantiators at all. | |
| 1129 @end enumerate | |
| 1130 | |
| 1131 @end defun | |
| 1132 | |
| 1133 @defun specifier-fallback specifier | |
| 1134 This function returns the fallback value for @var{specifier}. Fallback | |
| 1135 values are provided by the C code for certain built-in specifiers to | |
| 2953 | 1136 make sure that instantiation won't fail even if all specs are removed from |
| 428 | 1137 the specifier, or to implement simple inheritance behavior (e.g. this |
| 1138 method is used to ensure that faces other than @code{default} inherit | |
| 1139 their attributes from @code{default}). By design, you cannot change the | |
| 1140 fallback value, and specifiers created with @code{make-specifier} will | |
| 1141 never have a fallback (although a similar, Lisp-accessible capability | |
| 1142 may be provided in the future to allow for inheritance). | |
| 1143 | |
| 2953 | 1144 The fallback value will be an inst-list that is instantiated like |
| 428 | 1145 any other inst-list, a specifier of the same type as @var{specifier} |
| 1146 (results in inheritance), or @code{nil} for no fallback. | |
| 1147 | |
| 2953 | 1148 When you instantiate a specifier, you can explicitly request that the |
| 428 | 1149 fallback not be consulted. (The C code does this, for example, when |
| 1150 merging faces.) See @code{specifier-instance}. | |
| 1151 @end defun | |
| 1152 | |
| 1153 @node Specifier Tag Functions | |
| 1154 @section Working With Specifier Tags | |
| 1155 | |
| 1156 A specifier tag set is an entity that is attached to an instantiator | |
| 1157 and can be used to restrict the scope of that instantiator to a | |
| 1158 particular device class or device type and/or to mark instantiators | |
| 1159 added by a particular package so that they can be later removed. | |
| 1160 | |
| 442 | 1161 A specifier tag set consists of a list of zero or more specifier tags, |
| 428 | 1162 each of which is a symbol that is recognized by XEmacs as a tag. (The |
| 1163 valid device types and device classes are always tags, as are any tags | |
| 1164 defined by @code{define-specifier-tag}.) It is called a ``tag set'' (as | |
| 1165 opposed to a list) because the order of the tags or the number of times | |
| 1166 a particular tag occurs does not matter. | |
| 1167 | |
| 3674 | 1168 Each tag has a device predicate associated with it, which specifies whether |
| 428 | 1169 that tag applies to a particular device. The tags which are device |
| 1170 types and classes match devices of that type or class. User-defined | |
| 3674 | 1171 tags can have any device predicate, or none (meaning that all devices match). |
| 2953 | 1172 When attempting to instantiate a specifier, a particular instantiator is |
| 1173 only considered if the device of the domain being instantiated over matches | |
| 428 | 1174 all tags in the tag set attached to that instantiator. |
| 1175 | |
| 3674 | 1176 Each tag can also have a charset predicate, specifying whether that tag |
| 1177 applies to a particular charset. There are a few tags with predefined | |
| 1178 charset predicates created to allow sensible fallbacks in the face | |
| 1179 code---see the output of @code{(specifier-fallback (face-font | |
| 1180 'default))} for these. | |
| 1181 | |
| 428 | 1182 Most of the time, a tag set is not specified, and the instantiator gets |
| 3674 | 1183 a null tag set, which matches all devices and all character sets (when |
| 1184 possible; fonts with an inappropriate repertoire will not match, for | |
| 1185 example). | |
| 428 | 1186 |
| 1187 @defun valid-specifier-tag-p tag | |
| 1188 This function returns non-@code{nil} if @var{tag} is a valid specifier | |
| 1189 tag. | |
| 1190 @end defun | |
| 1191 | |
| 1192 @defun valid-specifier-tag-set-p tag-set | |
| 1193 This function returns non-@code{nil} if @var{tag-set} is a valid | |
| 1194 specifier tag set. | |
| 1195 @end defun | |
| 1196 | |
| 1197 @defun canonicalize-tag-set tag-set | |
| 1198 This function canonicalizes the given tag set. Two canonicalized tag | |
| 1199 sets can be compared with @code{equal} to see if they represent the same | |
| 1200 tag set. (Specifically, canonicalizing involves sorting by symbol name | |
| 1201 and removing duplicates.) | |
| 1202 @end defun | |
| 1203 | |
| 1204 @defun device-matches-specifier-tag-set-p device tag-set | |
| 1205 This function returns non-@code{nil} if @var{device} matches specifier | |
| 1206 tag set @var{tag-set}. This means that @var{device} matches each tag in | |
| 1207 the tag set. | |
| 1208 @end defun | |
| 1209 | |
| 3674 | 1210 @defun define-specifier-tag tag &optional device-predicate charset-predicate |
| 1211 This function defines a new specifier tag. If @var{device-predicate} is | |
| 428 | 1212 specified, it should be a function of one argument (a device) that |
| 1213 specifies whether the tag matches that particular device. If | |
| 3674 | 1214 @var{device-predicate} is omitted, the tag matches all devices. |
| 1215 | |
| 1216 If @var{charset-predicate} is specified, it should be a function taking | |
| 1217 one character set argument that specifies whether the tag matches that | |
| 1218 particular character set. | |
| 428 | 1219 |
| 1220 You can redefine an existing user-defined specifier tag. However, you | |
| 1221 cannot redefine the built-in specifier tags (the device types and | |
| 1222 classes) or the symbols @code{nil}, @code{t}, @code{all}, or | |
| 1223 @code{global}. | |
| 1224 @end defun | |
| 1225 | |
| 1226 @defun device-matching-specifier-tag-list &optional device | |
| 1227 This function returns a list of all specifier tags matching | |
| 1228 @var{device}. @var{device} defaults to the selected device if omitted. | |
| 1229 @end defun | |
| 1230 | |
| 1231 @defun specifier-tag-list | |
| 1232 This function returns a list of all currently-defined specifier tags. | |
| 1233 This includes the built-in ones (the device types and classes). | |
| 1234 @end defun | |
| 1235 | |
| 3674 | 1236 @defun specifier-tag-device-predicate tag |
| 1237 This function returns the device predicate for the given specifier tag. | |
| 1238 @end defun | |
| 1239 | |
| 1240 @defun specifier-tag-charset-predicate tag | |
| 1241 This function returns the charset predicate for the given specifier tag. | |
| 428 | 1242 @end defun |
| 1243 | |
| 2953 | 1244 @node Specifier Instantiation Functions |
| 1245 @section Functions for Instantiating a Specifier | |
| 428 | 1246 |
| 1247 @defun specifier-instance specifier &optional domain default no-fallback | |
| 1882 | 1248 This function instantiates @var{specifier} (returns its value) in |
| 428 | 1249 @var{domain}. If no instance can be generated for this domain, return |
| 1250 @var{default}. | |
| 1251 | |
| 1252 @var{domain} should be a window, frame, or device. Other values that | |
| 1253 are legal as a locale (e.g. a buffer) are not valid as a domain because | |
| 1254 they do not provide enough information to identify a particular device | |
| 1255 (see @code{valid-specifier-domain-p}). @var{domain} defaults to the | |
| 1256 selected window if omitted. | |
| 1257 | |
| 1258 @dfn{Instantiating} a specifier in a particular domain means determining | |
| 1259 the specifier's ``value'' in that domain. This is accomplished by | |
| 1260 searching through the specifications in the specifier that correspond to | |
| 1261 all locales that can be derived from the given domain, from specific to | |
| 1262 general. In most cases, the domain is an Emacs window. In that case | |
| 1263 specifications are searched for as follows: | |
| 1264 | |
| 1265 @enumerate | |
| 1266 @item | |
| 1267 A specification whose locale is the window itself; | |
| 1268 @item | |
| 1269 A specification whose locale is the window's buffer; | |
| 1270 @item | |
| 1271 A specification whose locale is the window's frame; | |
| 1272 @item | |
| 1273 A specification whose locale is the window's frame's device; | |
| 1274 @item | |
| 1275 A specification whose locale is the symbol @code{global}. | |
| 1276 @end enumerate | |
| 1277 | |
| 1278 If all of those fail, then the C-code-provided fallback value for this | |
| 1279 specifier is consulted (see @code{specifier-fallback}). If it is an | |
| 1280 inst-list, then this function attempts to instantiate that list just as | |
| 1281 when a specification is located in the first five steps above. If the | |
| 1282 fallback is a specifier, @code{specifier-instance} is called recursively | |
| 1283 on this specifier and the return value used. Note, however, that if the | |
| 1284 optional argument @var{no-fallback} is non-@code{nil}, the fallback | |
| 1285 value will not be consulted. | |
| 1286 | |
| 1287 Note that there may be more than one specification matching a particular | |
| 1288 locale; all such specifications are considered before looking for any | |
| 1289 specifications for more general locales. Any particular specification | |
| 1290 that is found may be rejected because it is tagged to a particular | |
| 1291 device class (e.g. @code{color}) or device type (e.g. @code{x}) or both | |
| 1292 and the device for the given domain does not match this, or because the | |
| 1293 specification is not valid for the device of the given domain (e.g. the | |
| 1294 font or color name does not exist for this particular X server). | |
| 1295 | |
| 1296 The returned value is dependent on the type of specifier. For example, | |
| 1297 for a font specifier (as returned by the @code{face-font} function), the | |
| 1298 returned value will be a font-instance object. For images, the returned | |
| 1299 value will be a string, pixmap, or subwindow. | |
| 1300 @end defun | |
| 1301 | |
| 1875 | 1302 @defun specifier-matching-instance specifier matchspec &optional domain default no-fallback |
| 1882 | 1303 This function returns an instance for @var{specifier} in @var{domain} |
| 1875 | 1304 that matches @var{matchspec}. If no instance can be generated for |
| 2028 | 1305 @var{domain}, return @var{default}. @xref{Specifier Compatibility Notes}. |
| 1875 | 1306 |
| 1307 This function is identical to @code{specifier-instance} except that a | |
| 1308 specification will only be considered if it matches @var{matchspec}. | |
| 1309 The definition of ``match,'' and allowed values for @var{matchspec}, are | |
| 1310 dependent on the particular type of specifier. Here are some examples: | |
| 1311 | |
| 1312 @itemize | |
| 1313 @item | |
| 1314 For chartable (e.g. display table) specifiers, @var{matchspec} should be a | |
| 1315 character, and the specification (a chartable) must give a value for | |
| 1316 that character in order to be considered. This allows you to specify, | |
| 1877 | 1317 @emph{e.g.}, a buffer-local display table that only gives values for particular |
| 1875 | 1318 characters. All other characters are handled as if the buffer-local |
| 1319 display table is not there. (Chartable specifiers are not yet | |
| 1320 implemented.) | |
| 1877 | 1321 @item |
| 1875 | 1322 For font specifiers, @var{matchspec} should be a list (@var{charset} |
| 3674 | 1323 . @var{stage}). On X11 the specification (a font string) should, for |
| 1324 clarity, have a registry that matches the charset's registry, but the | |
| 1325 redisplay code will specify the XLFD CHARSET_REGISTRY and | |
| 1326 CHARSET_ENCODING fields itself. This makes minimal sense without Mule | |
| 1327 support. @var{stage} can be one of the symbols @code{'initial} and | |
| 1328 @code{'final}; on X11, @code{'initial} means ``search for fonts using | |
| 1329 the charset registry of this charset'' and @code{'final} means ``search | |
| 1330 for fonts using `iso10646-1' as their charset registries, with the | |
| 1331 expectation that characters will be translated to Unicode at | |
| 1332 redisplay.'' Their meanings are similar on MS Windows, with the | |
| 1333 difference that the actual repertoire of the font is checked when | |
| 1334 deciding if a matchspec with @code{'final} matches. | |
| 1335 | |
| 1336 For example, the following code emulates what redisplay does when | |
| 1337 deciding what font to use for ethiopic with the default face (ignoring, | |
| 1338 for the moment, fallbacks): | |
| 1339 @example | |
| 1340 (or | |
| 1341 (specifier-matching-instance (face-font 'default) | |
| 1342 (cons 'ethiopic 'initial)) | |
| 1343 (specifier-matching-instance (face-font 'default) | |
| 1344 (cons 'ethiopic 'final))) | |
| 1345 @end example | |
| 1878 | 1346 @end itemize |
| 1875 | 1347 @end defun |
| 1348 | |
| 428 | 1349 @defun specifier-instance-from-inst-list specifier domain inst-list &optional default |
| 1350 This function attempts to convert a particular inst-list into an | |
| 1351 instance. This attempts to instantiate @var{inst-list} in the given | |
| 1352 @var{domain}, as if @var{inst-list} existed in a specification in | |
| 1353 @var{specifier}. If the instantiation fails, @var{default} is returned. | |
| 1354 In most circumstances, you should not use this function; use | |
| 1355 @code{specifier-instance} instead. | |
| 1356 @end defun | |
| 1357 | |
| 1869 | 1358 @node Specifier Examples |
| 1359 @section Examples of Specifier Usage | |
| 428 | 1360 |
| 1361 Now let us present an example to clarify the theoretical discussions we | |
| 1362 have been through. In this example, we will use the general specifier | |
| 1363 functions for clarity. Keep in mind that many types of specifiers, and | |
| 1364 some other types of objects that are associated with specifiers | |
| 1365 (e.g. faces), provide convenience functions making it easier to work | |
| 1366 with objects of that type. | |
| 1367 | |
| 1368 Let us consider the background color of the default face. A specifier | |
| 1369 is used to specify how that color will appear in different domains. | |
| 1370 First, let's retrieve the specifier: | |
| 1371 | |
| 1372 @example | |
| 1373 (setq sp (face-property 'default 'background)) | |
| 1374 @result{} #<color-specifier 0x3da> | |
| 1375 @end example | |
| 1376 | |
| 1377 @example | |
| 1378 (specifier-specs sp) | |
| 1379 @result{} ((#<buffer "device.c"> (nil . "forest green")) | |
| 1380 (#<window on "Makefile" 0x8a2b> (nil . "hot pink")) | |
| 1381 (#<x-frame "emacs" 0x4ac> (nil . "puke orange") | |
| 440 | 1382 (nil . "moccasin")) |
| 428 | 1383 (#<x-frame "VM" 0x4ac> (nil . "magenta")) |
| 440 | 1384 (global ((tty) . "cyan") (nil . "white")) |
| 428 | 1385 ) |
| 1386 @end example | |
| 1387 | |
| 1388 Then, say we want to determine what the background color of the default | |
| 1389 face is for the window currently displaying the buffer @samp{*scratch*}. | |
| 1390 We call | |
| 1391 | |
| 1392 @example | |
| 1393 (get-buffer-window "*scratch*") | |
| 1394 @result{} #<window on "*scratch*" 0x4ad> | |
| 1395 (window-frame (get-buffer-window "*scratch*")) | |
| 1396 @result{} #<x-frame "emacs" 0x4ac> | |
| 1397 (specifier-instance sp (get-buffer-window "*scratch*")) | |
| 1398 @result{} #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309> | |
| 1399 @end example | |
| 1400 | |
| 1401 Note that we passed a window to @code{specifier-instance}, not a buffer. | |
| 1402 We cannot pass a buffer because a buffer by itself does not provide enough | |
| 1403 information. The buffer might not be displayed anywhere at all, or | |
| 1404 could be displayed in many different frames on different devices. | |
| 1405 | |
| 1406 The result is arrived at like this: | |
| 1407 | |
| 1408 @enumerate | |
| 1409 @item | |
| 1410 First, we look for a specification matching the buffer displayed in the | |
| 440 | 1411 window, i.e. @samp{*scratch*}. There are none, so we proceed. |
| 428 | 1412 @item |
| 1413 Then, we look for a specification matching the window itself. Again, there | |
| 1414 are none. | |
| 1415 @item | |
| 1416 Then, we look for a specification matching the window's frame. The | |
| 1417 specification @code{(#<x-frame "emacs" 0x4ac> . "puke orange")} is | |
| 1418 found. We call the instantiation method for colors, passing it the | |
| 1419 locale we were searching over (i.e. the window, in this case) and the | |
| 1420 instantiator (@samp{"puke orange"}). However, the particular device | |
| 1421 which this window is on (let's say it's an X connection) doesn't | |
| 1422 recognize the color @samp{"puke orange"}, so the specification is | |
| 1423 rejected. | |
| 1424 @item | |
| 1425 So we continue looking for a specification matching the window's frame. | |
| 1426 We find @samp{(#<x-frame "emacs" 0x4ac> . "moccasin")}. Again, we | |
| 1427 call the instantiation method for colors. This time, the X server | |
| 1428 our window is on recognizes the color @samp{moccasin}, and so the | |
| 1429 instantiation method succeeds and returns a color instance. | |
| 1430 @end enumerate | |
| 1431 | |
| 1869 | 1432 Here's another example, which implements something like GNU Emacs's |
| 1433 ``frame-local'' variables. | |
| 1434 | |
| 1435 @example | |
| 1436 ;; Implementation | |
| 1437 | |
| 1438 ;; There are probably better ways to write this macro | |
| 1439 ;; Heaven help you if VAR is a buffer-local; you will become very | |
| 1440 ;; confused. Probably should error on that. | |
| 1441 (defmacro define-frame-local-variable (var) | |
| 1442 "Make the unbound symbol VAR become a frame-local variable." | |
| 1443 (let ((val (if (boundp var) (symbol-value var) nil))) | |
| 1444 `(progn | |
| 1445 (setq ,var (make-specifier 'generic)) | |
| 1446 (add-spec-to-specifier ,var ',val 'global)))) | |
| 1447 | |
| 1448 ;; I'm not real happy about this terminology, how can `setq' be a defun? | |
| 1449 ;; But `frame-set' would have people writing "(frame-set 'foo value)". | |
| 1450 (defun frame-setq (var value &optional frame) | |
| 1451 "Set the local value of VAR to VALUE in FRAME. | |
| 1452 | |
| 1453 FRAME defaults to the selected frame." | |
| 1454 (and frame (not (framep frame)) | |
| 1455 (error 'invalid-argument "FRAME must be a frame", frame)) | |
| 1456 (add-spec-to-specifier var value (or frame (selected-frame)))) | |
| 1457 | |
| 1458 (defun frame-value (var &optional frame) | |
| 1459 "Get the local value of VAR in FRAME. | |
| 1460 | |
| 1461 FRAME defaults to the selected frame." | |
| 1462 (and frame (not (framep frame)) | |
| 1463 (error 'invalid-argument "FRAME must be a frame", frame)) | |
| 1464 ;; this is not just a map from frames to values; it also falls back | |
| 1465 ;; to the global value | |
| 1466 (specifier-instance var (or frame (selected-frame)))) | |
| 1467 | |
| 1468 ;; for completeness | |
| 1469 (defun frame-set-default (var value) | |
| 1470 "Set the default value of frame-local variable VAR to VALUE." | |
| 1471 (add-spec-to-specifier var value 'global)) | |
| 1472 | |
| 1473 (defun frame-get-default (var) | |
| 1474 "Get the default value of frame-local variable VAR." | |
| 1475 (car (specifier-specs var 'global))) | |
| 1476 @end example | |
| 1477 | |
| 1478 Now you can execute the above definitions (eg, with @code{eval-last-sexp}) | |
| 1479 and switch to @file{*scratch*} to play. Things will work differently if | |
| 1480 you already have a variable named @code{foo}. | |
| 1481 | |
| 1482 @example | |
| 1483 ;; Usage | |
| 1484 | |
| 1485 foo | |
| 1486 @error{} Symbol's value as variable is void: foo | |
| 1487 | |
| 1488 (define-frame-local-variable foo) | |
| 1489 @result{} nil | |
| 1490 | |
| 1491 ;; the value of foo is a specifier, which is an opaque object; | |
| 1492 ;; you must use accessor functions to get values | |
| 1493 | |
| 1494 foo | |
| 1495 @result{} #<generic-specifier global=(nil) 0x4f5cb> | |
| 1496 | |
| 1497 ;; since no frame-local value is set, the global value (which is the | |
| 1498 ;; constant `nil') is returned | |
| 1499 (frame-value foo) | |
| 1500 @result{} nil | |
| 1501 | |
| 1502 ;; get the default explicitly | |
| 1503 (frame-get-default foo) | |
| 1504 @result{} nil | |
| 1505 | |
| 1506 ;; get the whole specification list | |
| 1507 (specifier-specs foo 'global) | |
| 1508 @result{} (nil) | |
| 1509 | |
| 1510 ;; give foo a frame-local value | |
| 1511 | |
| 1512 (frame-setq foo 'bar) | |
| 1513 @result{} nil | |
| 1514 | |
| 1515 ;; access foo in several ways | |
| 1516 | |
| 1517 ;; Note that the print function for this kind of specifier only | |
| 1518 ;; gives you the global setting. To get the full list of specs for | |
| 1519 ;; debugging or study purposes, you must use specifier-specs or | |
| 1520 ;; specifier-spec-list. | |
| 1521 foo | |
| 1522 @result{} #<generic-specifier global=(nil) 0x4f5cb> | |
| 1523 | |
| 1524 ;; get the whole specification list | |
| 1525 (specifier-specs foo) | |
| 1526 @result{} ((#<x-frame "Message" 0x1bd66> (nil . bar)) (global (nil))) | |
| 1527 | |
| 1528 ;; get the frame-local value | |
| 1529 (frame-value foo) | |
| 1530 @result{} bar | |
| 1531 | |
| 1532 ;; get the default explicitly | |
| 1533 (frame-get-default foo) | |
| 1534 @result{} nil | |
| 1535 | |
| 1536 ;; Switch to another frame and evaluate: | |
| 1537 ;; C-x 5 o M-: (frame-setq foo 'baz) RET M-: (frame-value foo) RET | |
| 1538 @result{} baz | |
| 1539 | |
| 1540 ;; Switch back. | |
| 1541 ;; C-x 5 o | |
| 1542 (specifier-specs foo) | |
| 1543 @result{} ((#<x-frame "emacs" 0x28ec> (nil . baz)) | |
| 1544 (#<x-frame "Message" 0x1bd66> (nil . bar)) | |
| 1545 (global (nil))) | |
| 1546 | |
| 1547 (frame-value foo) | |
| 1548 @result{} bar | |
| 1549 | |
| 1550 (frame-get-default foo) | |
| 1551 @result{} nil | |
| 1552 @end example | |
| 1553 | |
| 1554 Note that since specifiers generalize both frame-local and buffer-local | |
| 1555 variables in a sensible way, XEmacs is not likely to put a high priority | |
| 2028 | 1556 on implementing frame-local variables @ref{Specifier Compatibility Notes}. |
| 1869 | 1557 |
| 1558 | |
| 428 | 1559 @node Creating Specifiers |
| 1560 @section Creating New Specifier Objects | |
| 1561 | |
| 1562 @defun make-specifier type | |
| 1563 This function creates a new specifier. | |
| 1564 | |
| 1565 A specifier is an object that can be used to keep track of a property | |
| 1566 whose value can be per-buffer, per-window, per-frame, or per-device, | |
| 1567 and can further be restricted to a particular device-type or device-class. | |
| 1568 Specifiers are used, for example, for the various built-in properties of a | |
| 1569 face; this allows a face to have different values in different frames, | |
| 444 | 1570 buffers, etc. For more information, see @code{specifier-instance}, |
| 1571 @code{specifier-specs}, and @code{add-spec-to-specifier}; or, for a detailed | |
| 428 | 1572 description of specifiers, including how they are instantiated over a |
| 1573 particular domain (i.e. how their value in that domain is determined), | |
| 1574 see the chapter on specifiers in the XEmacs Lisp Reference Manual. | |
| 1575 | |
| 1576 @var{type} specifies the particular type of specifier, and should be one | |
| 1577 of the symbols @code{generic}, @code{integer}, @code{natnum}, | |
| 1578 @code{boolean}, @code{color}, @code{font}, @code{image}, | |
| 1579 @code{face-boolean}, or @code{toolbar}. | |
| 1580 | |
| 1581 For more information on particular types of specifiers, see the | |
| 442 | 1582 functions @code{make-generic-specifier}, @code{make-integer-specifier}, |
| 1583 @code{make-natnum-specifier}, @code{make-boolean-specifier}, | |
| 1584 @code{make-color-specifier}, @code{make-font-specifier}, | |
| 1585 @code{make-image-specifier}, @code{make-face-boolean-specifier}, and | |
| 1586 @code{make-toolbar-specifier}. | |
| 428 | 1587 @end defun |
| 1588 | |
| 1589 @defun make-specifier-and-init type spec-list &optional dont-canonicalize | |
| 1875 | 1590 This function creates and initializes a new specifier. |
| 428 | 1591 |
| 1875 | 1592 This is a convenience API combining @code{make-specifier} and |
| 1593 @code{set-specifier} that allows you to create | |
| 428 | 1594 a specifier and add specs to it at the same time. @var{type} specifies |
| 1875 | 1595 the specifier type. Allowed types are as for @code{make-specifier}. |
| 1596 | |
| 1597 @var{spec-list} supplies the specification(s) to be | |
| 1598 added to the specifier. Any abbreviation of | |
| 1599 the full spec-list form accepted by @code{canonicalize-spec-list} may | |
| 1600 be used. | |
| 1601 However, if the optional argument @var{dont-canonicalize} is non-@code{nil}, | |
| 1602 canonicalization is not performed, and the @var{spec-list} must already | |
| 1603 be in full form. | |
| 428 | 1604 @end defun |
| 1605 | |
| 442 | 1606 @defun make-integer-specifier spec-list |
| 1607 | |
| 1608 Return a new @code{integer} specifier object with the given | |
| 1609 specification list. @var{spec-list} can be a list of specifications | |
| 1610 (each of which is a cons of a locale and a list of instantiators), a | |
| 1611 single instantiator, or a list of instantiators. | |
| 1612 | |
| 1613 Valid instantiators for integer specifiers are integers. | |
| 1614 @end defun | |
| 1615 | |
| 1616 @defun make-boolean-specifier spec-list | |
| 1617 | |
| 1618 Return a new @code{boolean} specifier object with the given | |
| 1619 specification list. @var{spec-list} can be a list of specifications | |
| 1620 (each of which is a cons of a locale and a list of instantiators), a | |
| 1621 single instantiator, or a list of instantiators. | |
| 1622 | |
| 1623 Valid instantiators for boolean specifiers are @code{t} and @code{nil}. | |
| 1624 @end defun | |
| 1625 | |
| 1626 @defun make-natnum-specifier spec-list | |
| 1627 | |
| 1628 Return a new @code{natnum} specifier object with the given specification | |
| 1629 list. @var{spec-list} can be a list of specifications (each of which is | |
| 1630 a cons of a locale and a list of instantiators), a single instantiator, | |
| 1631 or a list of instantiators. | |
| 1632 | |
| 1633 Valid instantiators for natnum specifiers are non-negative integers. | |
| 1634 @end defun | |
| 1635 | |
| 1636 @defun make-generic-specifier spec-list | |
| 1637 | |
| 1638 Return a new @code{generic} specifier object with the given | |
| 1639 specification list. @var{spec-list} can be a list of specifications | |
| 1640 (each of which is a cons of a locale and a list of instantiators), a | |
| 1641 single instantiator, or a list of instantiators. | |
| 1642 | |
| 1643 Valid instantiators for generic specifiers are all Lisp values. They | |
| 1644 are returned back unchanged when a specifier is instantiated. | |
| 1645 @end defun | |
| 1646 | |
| 1647 @defun make-display-table-specifier spec-list | |
| 1648 | |
| 1649 Return a new @code{display-table} specifier object with the given spec | |
| 1650 list. @var{spec-list} can be a list of specifications (each of which is | |
| 1651 a cons of a locale and a list of instantiators), a single instantiator, | |
| 1652 or a list of instantiators. | |
| 1653 | |
| 1654 Valid instantiators for display-table specifiers are described in detail | |
| 1655 in the doc string for @code{current-display-table} (@pxref{Active | |
| 1656 Display Table}). | |
| 1657 @end defun | |
| 1658 | |
| 428 | 1659 @node Specifier Validation Functions |
| 1660 @section Functions for Checking the Validity of Specifier Components | |
| 1661 | |
| 1662 @defun valid-specifier-domain-p domain | |
| 1663 This function returns non-@code{nil} if @var{domain} is a valid | |
| 2953 | 1664 specifier domain. A domain is used to instantiate a specifier |
| 428 | 1665 (i.e. determine the specifier's value in that domain). Valid domains |
| 1666 are a window, frame, or device. (@code{nil} is not valid.) | |
| 1667 @end defun | |
| 1668 | |
| 1669 @defun valid-specifier-locale-p locale | |
| 1670 This function returns non-@code{nil} if @var{locale} is a valid | |
| 1671 specifier locale. Valid locales are a device, a frame, a window, a | |
| 1672 buffer, and @code{global}. (@code{nil} is not valid.) | |
| 1673 @end defun | |
| 1674 | |
| 1675 @defun valid-specifier-locale-type-p locale-type | |
| 444 | 1676 Given a specifier @var{locale-type}, this function returns non-@code{nil} if it |
| 428 | 1677 is valid. Valid locale types are the symbols @code{global}, |
| 1678 @code{device}, @code{frame}, @code{window}, and @code{buffer}. (Note, | |
| 1679 however, that in functions that accept either a locale or a locale type, | |
| 1680 @code{global} is considered an individual locale.) | |
| 1681 @end defun | |
| 1682 | |
| 1683 @defun valid-specifier-type-p specifier-type | |
| 1684 Given a @var{specifier-type}, this function returns non-@code{nil} if it | |
| 1685 is valid. Valid types are @code{generic}, @code{integer}, | |
| 1686 @code{boolean}, @code{color}, @code{font}, @code{image}, | |
| 1687 @code{face-boolean}, and @code{toolbar}. | |
| 1688 @end defun | |
| 1689 | |
| 1690 @defun valid-specifier-tag-p tag | |
| 1691 This function returns non-@code{nil} if @var{tag} is a valid specifier | |
| 1692 tag. | |
| 1693 @end defun | |
| 1694 | |
| 1695 @defun valid-instantiator-p instantiator specifier-type | |
| 1696 This function returns non-@code{nil} if @var{instantiator} is valid for | |
| 1697 @var{specifier-type}. | |
| 1698 @end defun | |
| 1699 | |
| 1700 @defun valid-inst-list-p inst-list type | |
| 1701 This function returns non-@code{nil} if @var{inst-list} is valid for | |
| 1702 specifier type @var{type}. | |
| 1703 @end defun | |
| 1704 | |
| 1705 @defun valid-spec-list-p spec-list type | |
| 1706 This function returns non-@code{nil} if @var{spec-list} is valid for | |
| 1707 specifier type @var{type}. | |
| 1708 @end defun | |
| 1709 | |
| 1710 @defun check-valid-instantiator instantiator specifier-type | |
| 1711 This function signals an error if @var{instantiator} is invalid for | |
| 1712 @var{specifier-type}. | |
| 1713 @end defun | |
| 1714 | |
| 1715 @defun check-valid-inst-list inst-list type | |
| 1716 This function signals an error if @var{inst-list} is invalid for | |
| 1717 specifier type @var{type}. | |
| 1718 @end defun | |
| 1719 | |
| 1720 @defun check-valid-spec-list spec-list type | |
| 1721 This function signals an error if @var{spec-list} is invalid for | |
| 1722 specifier type @var{type}. | |
| 1723 @end defun | |
| 1724 | |
| 1725 @node Other Specification Functions | |
| 1726 @section Other Functions for Working with Specifications in a Specifier | |
| 1727 | |
| 1728 @defun copy-specifier specifier &optional dest locale tag-set exact-p how-to-add | |
| 1729 This function copies @var{specifier} to @var{dest}, or creates a new one | |
| 1730 if @var{dest} is @code{nil}. | |
| 1731 | |
| 1732 If @var{dest} is @code{nil} or omitted, a new specifier will be created | |
| 1733 and the specifications copied into it. Otherwise, the specifications | |
| 1734 will be copied into the existing specifier in @var{dest}. | |
| 1735 | |
| 1736 If @var{locale} is @code{nil} or the symbol @code{all}, all | |
| 1737 specifications will be copied. If @var{locale} is a particular locale, | |
| 1738 the specification for that particular locale will be copied. If | |
| 1739 @var{locale} is a locale type, the specifications for all locales of | |
| 1740 that type will be copied. @var{locale} can also be a list of locales, | |
| 1741 locale types, and/or @code{all}; this is equivalent to calling | |
| 1742 @code{copy-specifier} for each of the elements of the list. See | |
| 1743 @code{specifier-spec-list} for more information about @var{locale}. | |
| 1744 | |
| 1745 Only instantiators where @var{tag-set} (a list of zero or more tags) is | |
| 1746 a subset of (or possibly equal to) the instantiator's tag set are | |
| 1747 copied. (The default value of @code{nil} is a subset of all tag sets, | |
| 1748 so in this case no instantiators will be screened out.) If @var{exact-p} | |
| 1749 is non-@code{nil}, however, @var{tag-set} must be equal to an | |
| 1750 instantiator's tag set for the instantiator to be copied. | |
| 1751 | |
| 1752 Optional argument @var{how-to-add} specifies what to do with existing | |
| 444 | 1753 specifications in @var{dest}. If @code{nil}, then whichever locales or locale |
| 428 | 1754 types are copied will first be completely erased in @var{dest}. |
| 1755 Otherwise, it is the same as in @code{add-spec-to-specifier}. | |
| 1756 @end defun | |
| 1757 | |
| 1758 @defun remove-specifier specifier &optional locale tag-set exact-p | |
| 1759 This function removes specification(s) for @var{specifier}. | |
| 1760 | |
| 1761 If @var{locale} is a particular locale (a buffer, window, frame, device, | |
| 1762 or the symbol @code{global}), the specification for that locale will be | |
| 1763 removed. | |
| 1764 | |
| 1765 If instead, @var{locale} is a locale type (i.e. a symbol @code{buffer}, | |
| 1766 @code{window}, @code{frame}, or @code{device}), the specifications for | |
| 1767 all locales of that type will be removed. | |
| 1768 | |
| 1769 If @var{locale} is @code{nil} or the symbol @code{all}, all | |
| 1770 specifications will be removed. | |
| 1771 | |
| 1772 @var{locale} can also be a list of locales, locale types, and/or | |
| 1773 @code{all}; this is equivalent to calling @code{remove-specifier} for | |
| 1774 each of the elements in the list. | |
| 1775 | |
| 1776 Only instantiators where @var{tag-set} (a list of zero or more tags) is | |
| 1777 a subset of (or possibly equal to) the instantiator's tag set are | |
| 1778 removed. (The default value of @code{nil} is a subset of all tag sets, | |
| 1779 so in this case no instantiators will be screened out.) If @var{exact-p} | |
| 1780 is non-@code{nil}, however, @var{tag-set} must be equal to an | |
| 1781 instantiator's tag set for the instantiator to be removed. | |
| 1782 @end defun | |
| 1783 | |
| 1784 @defun map-specifier specifier func &optional locale maparg | |
| 1785 This function applies @var{func} to the specification(s) for | |
| 1786 @var{locale} in @var{specifier}. | |
| 1787 | |
| 1875 | 1788 If optional @var{locale} is a locale, @var{func} will be called for that |
| 1789 locale. | |
| 428 | 1790 If @var{locale} is a locale type, @var{func} will be mapped over all |
| 1791 locales of that type. If @var{locale} is @code{nil} or the symbol | |
| 1792 @code{all}, @var{func} will be mapped over all locales in | |
| 1793 @var{specifier}. | |
| 1794 | |
| 1875 | 1795 Optional @var{ms-tag-set} and @var{ms-exact-p} are as in |
| 1796 @code{specifier-spec-list'}. | |
| 1797 Optional @var{ms-maparg} will be passed to @var{ms-func}. | |
| 1798 | |
| 428 | 1799 @var{func} is called with four arguments: the @var{specifier}, the |
| 1800 locale being mapped over, the inst-list for that locale, and the | |
| 1801 optional @var{maparg}. If any invocation of @var{func} returns | |
| 1802 non-@code{nil}, the mapping will stop and the returned value becomes the | |
| 1803 value returned from @code{map-specifier}. Otherwise, | |
| 1804 @code{map-specifier} returns @code{nil}. | |
| 1805 @end defun | |
| 1806 | |
| 1807 @defun specifier-locale-type-from-locale locale | |
| 1808 Given a specifier @var{locale}, this function returns its type. | |
| 1809 @end defun | |
| 2028 | 1810 |
| 1811 @node Specifier Compatibility Notes | |
| 1812 @section Specifier Compatibility Notes | |
| 1813 | |
| 1814 This node describes compatibility issues in the use of specifiers known | |
| 1815 as of 2004-01-22. | |
| 1816 @c I considered basing the main text on 21.4, but then future | |
| 1817 @c maintenance of this documentation would be a pain. | |
| 1818 The main text refers to XEmacs 21.5.16. | |
| 1819 | |
| 1820 Effort will be made to describe changes in the API or semantics between | |
| 1821 XEmacs versions accurately. Any inaccuracy or missing information about | |
| 1822 backward and forward compatibility is a bug, and we greatly appreciate | |
| 1823 your reports, whether you can provide a patch or not. | |
| 1824 | |
| 1825 A change is reported as @dfn{changed} when we believe that the new or | |
| 1826 changed API will cause old code to malfunction. When old code is | |
| 1827 believed to be upward compatible with the changed API, the change is | |
| 1828 reported as @dfn{added}. | |
| 1829 | |
| 1830 We would like to also describe compatibility with GNU Emacs, but this is | |
| 1831 not so high a priority. Inaccuracies or omissions will be addressed at | |
| 1832 the priority of a feature request, and as such processing will be | |
| 1833 greatly expedited if you can provide a patch. | |
| 1834 @c #### xref here to bug reporting and patch submissions | |
| 1835 | |
| 1836 @c #### write and xref a file on compatibility policy | |
| 1837 | |
| 1838 @subsection Compatibility with GNU Emacs | |
| 1839 | |
| 1840 Specifiers are not used in GNU Emacs. If your program depends on | |
| 1841 specifers, you will probably have to rewrite the functionality | |
| 1842 completely for GNU Emacs. If you wish to maximize portability, you | |
| 1843 should plan to encapsulate use of specifiers. | |
| 1844 | |
| 1845 GNU Emacs provides two features for context-sensitive variables, | |
| 1846 buffer-local variables and frame-local variables. XEmacs implements | |
| 1847 buffer-local variables 100%-compatibly with GNU Emacs. If buffer-local | |
| 1848 variables will server your purpose and portability is a major concern, | |
| 1849 consider using them instead of specifiers. | |
| 1850 | |
| 1851 XEmacs does not implement frame-local variables at all. In this case | |
| 1852 specifiers must be used to provide equivalent functionality. | |
| 1853 | |
| 1854 It is not clear whether XEmacs will provide this feature in the future. | |
| 1855 @c Thanks to Jerry James for the following explanation. He is not | |
| 1856 @c responsible for its use here, Stephen Turnbull is. | |
| 1857 In fact, some core XEmacs developers think that both frame-local | |
| 1858 variables and buffer-local variables are evil, because the declaration | |
| 1859 is both global and invisible. That is, you cannot tell whether a | |
| 1860 variable is ``normal,'' buffer-local, or frame-local just by looking at | |
| 1861 it. So if you have namespace management problems, and some other Lisp | |
| 1862 package happens to use a variable name that you already declared frame- | |
| 1863 or buffer-local, weird stuff happens, and it is extremely hard to track | |
| 1864 down. | |
| 1865 @c #### Direct comments to xemacs-design? | |
| 1866 | |
| 1867 @subsection Backwards Compatibility with XEmacs 21.4 | |
| 1868 | |
| 1869 Sorry, I'm unwilling to find out exactly when these changes were made. | |
| 1870 | |
| 1871 Changed by 21.5.16: the second argument of | |
| 1872 @code{specifier-matching-instance} is now a cons of a charset and a | |
| 1873 boolean value. Previously it was a charset or a symbol (a name of a | |
| 1874 charset). It was not documented in Info. | |
| 1875 | |
| 1876 Changed by 21.5.16: the specifier-specific error symbols | |
| 1877 @code{specifier_syntax_error}, @code{specifier_argument_error}, and | |
| 1878 @code{specifier_change_error} were removed. (This probably only | |
| 1879 affected internal code.) | |
| 1880 | |
| 1881 Added by 21.5.16: @code{map-specifier} got two new arguments, | |
| 1882 @code{ms-tag-set} and @code{ms-exact-p}. | |
| 1883 | |
| 1884 Added by 21.5.16: when skipping instantiators, XEmacs warns at level | |
| 1885 `debug'. | |
| 1886 | |
| 1887 Added by 21.5.16: new convenience APIs: | |
| 1888 @code{instance-to-instantiator}, | |
| 1889 @code{device-type-matches-spec}, | |
| 1890 @code{add-tag-to-inst-list}, | |
| 1891 @code{derive-domain-from-locale}, | |
| 1892 @code{derive-device-type-from-tag-set}, | |
| 1893 @code{derive-device-type-from-locale-and-tag-set}, and | |
| 1894 @code{derive-specifier-specs-from-locale}. |