X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-34;h=b4b7026e6a211b25549370a6fa257e083a31770f;hb=b5f26301ee1ad7dbc9ad1c22e5b8564b5161d9ad;hp=9b8b3d44f22c1518779a96a95fcd00fa57d25427;hpb=7d6edaefa00e7b7e102354283824a4f6a721b71a;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-34 b/info/lispref.info-34 index 9b8b3d4..b4b7026 100644 --- a/info/lispref.info-34 +++ b/info/lispref.info-34 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 4.0 from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,999 +50,1109 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers - -How a Specifier Is Instanced -============================ - - Instancing of a specifier in a particular window domain proceeds as -follows: - - * First, XEmacs searches for a specification whose locale is the - same as the window. If that fails, the search is repeated, - looking for a locale that is the same as the window's buffer. If - that fails, the search is repeated using the window's frame, then - using the device that frame is on. Finally, the specification - whose locale is the symbol `global' (if there is such a - specification) is considered. - - * The inst-pairs contained in the specification that was found are - considered in their order in the inst-list, looking for one whose - tag set matches the device that is derived from the window domain. - (The tag set is an unordered list of zero or more tag symbols. - For all tags that have predicates associated with them, the - predicate must match the device.) - - * If a matching tag set is found, the corresponding instantiator is - passed to the specifier's instantiation method, which is specific - to the type of the specifier. If it succeeds, the resulting - instance object is returned as the result of the instancing and - the instancing is done. Otherwise, the operation continues, - looking for another matching inst-pair in the current - specification. - - * When there are no more inst-pairs to be considered in the current - specification, the search starts over, looking for another - specification as in the first step above. - - * If all specifications are exhausted and no instance object can be - derived, the instancing fails. (Actually, this is not completely - true. Some specifier objects for built-in properties have a - "fallback" value, which is either an inst-list or another - specifier object, that is consulted if the instancing is about to - fail. If it is an inst-list, the searching proceeds using the - inst-pairs in that list. If it is a specifier, the entire - instancing starts over using that specifier instead of the given - one. Fallback values are set by the C code and cannot be - modified, except perhaps indirectly, using any Lisp functions. - The purpose of them is to supply some values to make sure that - instancing of built-in properties can't fail and to implement some - basic specifier inheritance, such as the fact that faces inherit - their properties from the `default' face.) - - It is also possible to instance a specifier over a frame domain or -device domain instead of over a window domain. The C code, for example, -instances the `top-toolbar-height' variable over a frame domain in -order to determine the height of a frame's top toolbar. Instancing over -a frame or device is similar to instancing over a window except that -specifications for locales that cannot be derived from the domain are -ignored. Specifically, instancing over a frame looks first for frame -locales, then device locales, then the `global' locale. Instancing -over a device domain looks only for device locales and the `global' -locale. +File: lispref.info, Node: Abbrev Expansion, Next: Standard Abbrev Tables, Prev: Abbrev Files, Up: Abbrevs + +Looking Up and Expanding Abbreviations +====================================== + + Abbrevs are usually expanded by commands for interactive use, +including `self-insert-command'. This section describes the +subroutines used in writing such functions, as well as the variables +they use for communication. + + - Function: abbrev-symbol abbrev &optional table + This function returns the symbol representing the abbrev named + ABBREV. The value returned is `nil' if that abbrev is not + defined. The optional second argument TABLE is the abbrev table + to look it up in. If TABLE is `nil', this function tries first + the current buffer's local abbrev table, and second the global + abbrev table. + + - Function: abbrev-expansion abbrev &optional table + This function returns the string that ABBREV would expand into (as + defined by the abbrev tables used for the current buffer). The + optional argument TABLE specifies the abbrev table to use, as in + `abbrev-symbol'. + + - Command: expand-abbrev + This command expands the abbrev before point, if any. If point + does not follow an abbrev, this command does nothing. The command + returns `t' if it did expansion, `nil' otherwise. + + - Command: abbrev-prefix-mark &optional arg + Mark current point as the beginning of an abbrev. The next call to + `expand-abbrev' will use the text from here to point (where it is + then) as the abbrev to expand, rather than using the previous word + as usual. + + - User Option: abbrev-all-caps + When this is set non-`nil', an abbrev entered entirely in upper + case is expanded using all upper case. Otherwise, an abbrev + entered entirely in upper case is expanded by capitalizing each + word of the expansion. + + - Variable: abbrev-start-location + This is the buffer position for `expand-abbrev' to use as the start + of the next abbrev to be expanded. (`nil' means use the word + before point instead.) `abbrev-start-location' is set to `nil' + each time `expand-abbrev' is called. This variable is also set by + `abbrev-prefix-mark'. + + - Variable: abbrev-start-location-buffer + The value of this variable is the buffer for which + `abbrev-start-location' has been set. Trying to expand an abbrev + in any other buffer clears `abbrev-start-location'. This variable + is set by `abbrev-prefix-mark'. + + - Variable: last-abbrev + This is the `abbrev-symbol' of the last abbrev expanded. This + information is left by `expand-abbrev' for the sake of the + `unexpand-abbrev' command. + + - Variable: last-abbrev-location + This is the location of the last abbrev expanded. This contains + information left by `expand-abbrev' for the sake of the + `unexpand-abbrev' command. + + - Variable: last-abbrev-text + This is the exact expansion text of the last abbrev expanded, + after case conversion (if any). Its value is `nil' if the abbrev + has already been unexpanded. This contains information left by + `expand-abbrev' for the sake of the `unexpand-abbrev' command. + + - Variable: pre-abbrev-expand-hook + This is a normal hook whose functions are executed, in sequence, + just before any expansion of an abbrev. *Note Hooks::. Since it + is a normal hook, the hook functions receive no arguments. + However, they can find the abbrev to be expanded by looking in the + buffer before point. + + The following sample code shows a simple use of +`pre-abbrev-expand-hook'. If the user terminates an abbrev with a +punctuation character, the hook function asks for confirmation. Thus, +this hook allows the user to decide whether to expand the abbrev, and +aborts expansion if it is not confirmed. + + (add-hook 'pre-abbrev-expand-hook 'query-if-not-space) + + ;; This is the function invoked by `pre-abbrev-expand-hook'. + + ;; If the user terminated the abbrev with a space, the function does + ;; nothing (that is, it returns so that the abbrev can expand). If the + ;; user entered some other character, this function asks whether + ;; expansion should continue. + + ;; If the user answers the prompt with `y', the function returns + ;; `nil' (because of the `not' function), but that is + ;; acceptable; the return value has no effect on expansion. + + (defun query-if-not-space () + (if (/= ?\ (preceding-char)) + (if (not (y-or-n-p "Do you want to expand this abbrev? ")) + (error "Not expanding this abbrev"))))  -File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers +File: lispref.info, Node: Standard Abbrev Tables, Prev: Abbrev Expansion, Up: Abbrevs -Specifier Types -=============== - - There are various different types of specifiers. The type of a -specifier controls what sorts of instantiators are valid, how an -instantiator is instantiated, etc. Here is a list of built-in specifier -types: - -`boolean' - The valid instantiators are the symbols `t' and `nil'. Instance - objects are the same as instantiators so no special instantiation - function is needed. - -`integer' - The valid instantiators are integers. Instance objects are the - same as instantiators so no special instantiation function is - needed. `modeline-shadow-thickness' is an example of an integer - specifier (negative thicknesses indicate that the shadow is drawn - recessed instead of raised). - -`natnum' - The valid instantiators are natnums (non-negative integers). - Instance objects are the same as instantiators so no special - instantiation function is needed. Natnum specifiers are used for - dimension variables such as `top-toolbar-height'. - -`generic' - All Lisp objects are valid instantiators. Instance objects are - the same as instantiators so no special instantiation function is - needed. - -`font' - The valid instantiators are strings describing fonts or vectors - indicating inheritance from the font of some face. Instance - objects are font-instance objects, which are specific to a - particular device. The instantiation method for font specifiers - can fail, unlike for integer, natnum, boolean, and generic - specifiers. - -`color' - The valid instantiators are strings describing colors or vectors - indicating inheritance from the foreground or background of some - face. Instance objects are color-instance objects, which are - specific to a particular device. The instantiation method for - color specifiers can fail, as for font specifiers. - -`image' - Images are perhaps the most complicated type of built-in - specifier. The valid instantiators are strings (a filename, - inline data for a pixmap, or text to be displayed in a text glyph) - or vectors describing inline data of various sorts or indicating - inheritance from the background-pixmap property of some face. - Instance objects are either strings (for text images), - image-instance objects (for pixmap images), or subwindow objects - (for subwindow images). The instantiation method for image - specifiers can fail, as for font and color specifiers. - -`face-boolean' - The valid instantiators are the symbols `t' and `nil' and vectors - indicating inheritance from a boolean property of some face. - Specifiers of this sort are used for all of the built-in boolean - properties of faces. Instance objects are either the symbol `t' - or the symbol `nil'. - -`toolbar' - The valid instantiators are toolbar descriptors, which are lists - of toolbar-button descriptors (each of which is a vector of two or - four elements). *Note Toolbar::, for more information. - - Color and font instance objects can also be used in turn as -instantiators for a new color or font instance object. Since these -instance objects are device-specific, the instantiator can be used -directly as the new instance object, but only if they are of the same -device. If the devices differ, the base color or font of the -instantiating object is effectively used instead as the instantiator. - - *Note Faces and Window-System Objects::, for more information on -fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more -information about image specifiers. *Note Toolbar::, for more -information on toolbar specifiers. - - - Function: specifier-type specifier - This function returns the type of SPECIFIER. The returned value - will be a symbol: one of `integer', `boolean', etc., as listed in - the above table. - - Functions are also provided to query whether an object is a -particular kind of specifier: - - - Function: boolean-specifier-p object - This function returns non-`nil' if OBJECT is a boolean specifier. - - - Function: integer-specifier-p object - This function returns non-`nil' if OBJECT is an integer specifier. - - - Function: natnum-specifier-p object - This function returns non-`nil' if OBJECT is a natnum specifier. - - - Function: generic-specifier-p object - This function returns non-`nil' if OBJECT is a generic specifier. - - - Function: face-boolean-specifier-p object - This function returns non-`nil' if OBJECT is a face-boolean - specifier. - - - Function: toolbar-specifier-p object - This function returns non-`nil' if OBJECT is a toolbar specifier. - - - Function: font-specifier-p object - This function returns non-`nil' if OBJECT is a font specifier. - - - Function: color-specifier-p object - This function returns non-`nil' if OBJECT is a color specifier. - - - Function: image-specifier-p object - This function returns non-`nil' if OBJECT is an image specifier. - - -File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers +Standard Abbrev Tables +====================== -Adding specifications to a Specifier -==================================== + Here we list the variables that hold the abbrev tables for the +preloaded major modes of XEmacs. - - Function: add-spec-to-specifier specifier instantiator &optional - locale tag-set how-to-add - This function adds a specification to SPECIFIER. The - specification maps from LOCALE (which should be a window, buffer, - frame, device, or the symbol `global', and defaults to `global') - to INSTANTIATOR, whose allowed values depend on the type of the - specifier. Optional argument TAG-SET limits the instantiator to - apply only to the specified tag set, which should be a list of - tags all of which must match the device being instantiated over - (tags are a device type, a device class, or tags defined with - `define-specifier-tag'). Specifying a single symbol for TAG-SET - is equivalent to specifying a one-element list containing that - symbol. Optional argument HOW-TO-ADD specifies what to do if - there are already specifications in the specifier. It should be - one of + - Variable: global-abbrev-table + This is the abbrev table for mode-independent abbrevs. The abbrevs + defined in it apply to all buffers. Each buffer may also have a + local abbrev table, whose abbrev definitions take precedence over + those in the global table. - `prepend' - Put at the beginning of the current list of instantiators for - LOCALE. + - Variable: local-abbrev-table + The value of this buffer-local variable is the (mode-specific) + abbreviation table of the current buffer. - `append' - Add to the end of the current list of instantiators for - LOCALE. - - `remove-tag-set-prepend' - This is the default. Remove any existing instantiators whose - tag set is the same as TAG-SET; then put the new instantiator - at the beginning of the current list. + - Variable: fundamental-mode-abbrev-table + This is the local abbrev table used in Fundamental mode; in other + words, it is the local abbrev table in all buffers in Fundamental + mode. - `remove-tag-set-append' - Remove any existing instantiators whose tag set is the same as - TAG-SET; then put the new instantiator at the end of the - current list. - - `remove-locale' - Remove all previous instantiators for this locale before - adding the new spec. - - `remove-locale-type' - Remove all specifications for all locales of the same type as - LOCALE (this includes LOCALE itself) before adding the new - spec. - - `remove-all' - Remove all specifications from the specifier before adding - the new spec. - - `remove-tag-set-prepend' is the default. - - You can retrieve the specifications for a particular locale or - locale type with the function `specifier-spec-list' or - `specifier-specs'. - - - Function: add-spec-list-to-specifier specifier spec-list &optional - how-to-add - This function adds a "spec-list" (a list of specifications) to - SPECIFIER. The format of a spec-list is - - `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)' - - where - - * LOCALE := a window, a buffer, a frame, a device, or `global' - - * TAG-SET := an unordered list of zero or more TAGS, each of - which is a symbol - - * TAG := a device class (*note Consoles and Devices::), a - device type, or a tag defined with `define-specifier-tag' - - * INSTANTIATOR := format determined by the type of specifier - - The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A - list of inst-pairs is called an "inst-list". The pair `(LOCALE . - INST-LIST)' is called a "specification". A spec-list, then, can - be viewed as a list of specifications. - - HOW-TO-ADD specifies how to combine the new specifications with - the existing ones, and has the same semantics as for - `add-spec-to-specifier'. - - In many circumstances, the higher-level function `set-specifier' is - more convenient and should be used instead. - - - Macro: let-specifier specifier-list &rest body - This special form temporarily adds specifications to specifiers, - evaluates forms in BODY and restores the specifiers to their - previous states. The specifiers and their temporary - specifications are listed in SPECIFIER-LIST. - - The format of SPECIFIER-LIST is - - ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...) - - SPECIFIER is the specifier to be temporarily modified. VALUE is - the instantiator to be temporarily added to specifier in LOCALE. - LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in - `add-spec-to-specifier'. - - This special form is implemented as a macro; the code resulting - from macro expansion will add specifications to specifiers using - `add-spec-to-specifier'. After forms in BODY are evaluated, the - temporary specifications are removed and old specifier spec-lists - are restored. - - LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to - `nil'. The value of the last form in BODY is returned. - - NOTE: If you want the specifier's instance to change in all - circumstances, use `(selected-window)' as the LOCALE. If LOCALE - is `nil' or omitted, it defaults to `global'. + - Variable: text-mode-abbrev-table + This is the local abbrev table used in Text mode. - The following example removes the 3D modeline effect in the - currently selected window for the duration of a second: + - Variable: c-mode-abbrev-table + This is the local abbrev table used in C mode. - (let-specifier ((modeline-shadow-thickness 0 (selected-window))) - (sit-for 1)) + - Variable: lisp-mode-abbrev-table + This is the local abbrev table used in Lisp mode and Emacs Lisp + mode. - - Function: set-specifier specifier value &optional how-to-add - This function adds some specifications to SPECIFIER. VALUE can be - a single instantiator or tagged instantiator (added as a global - specification), a list of tagged and/or untagged instantiators - (added as a global specification), a cons of a locale and - instantiator or locale and instantiator list, a list of such - conses, or nearly any other reasonable form. More specifically, - VALUE can be anything accepted by `canonicalize-spec-list'. + +File: lispref.info, Node: Extents, Next: Specifiers, Prev: Abbrevs, Up: Top - HOW-TO-ADD is the same as in `add-spec-to-specifier'. +Extents +******* - Note that `set-specifier' is exactly complementary to - `specifier-specs' except in the case where SPECIFIER has no specs - at all in it but `nil' is a valid instantiator (in that case, - `specifier-specs' will return `nil' (meaning no specs) and - `set-specifier' will interpret the `nil' as meaning "I'm adding a - global instantiator and its value is `nil'"), or in strange cases - where there is an ambiguity between a spec-list and an inst-list, - etc. (The built-in specifier types are designed in such a way as - to avoid any such ambiguities.) + An "extent" is a region of text (a start position and an end +position) that is displayed in a particular face and can have certain +other properties such as being read-only. Extents can overlap each +other. XEmacs efficiently handles buffers with large numbers of +extents in them. - If you want to work with spec-lists, you should probably not use - these functions, but should use the lower-level functions - `specifier-spec-list' and `add-spec-list-to-specifier'. These - functions always work with fully-qualified spec-lists; thus, there - is no ambiguity. + - Function: extentp object + This returns `t' if OBJECT is an extent. - - Function: canonicalize-inst-pair inst-pair specifier-type &optional - noerror - This function canonicalizes the given INST-PAIR. +* Menu: - SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST - will be used for. +* Intro to Extents:: Extents are regions over a buffer or string. +* Creating and Modifying Extents:: + Basic extent functions. +* Extent Endpoints:: Accessing and setting the bounds of an extent. +* Finding Extents:: Determining which extents are in an object. +* Mapping Over Extents:: More sophisticated functions for extent scanning. +* Extent Properties:: Extents have built-in and user-definable properties. +* Detached Extents:: Extents that are not in a buffer. +* Extent Parents:: Inheriting properties from another extent. +* Duplicable Extents:: Extents can be marked to be copied into strings. +* Extents and Events:: Extents can interact with the keyboard and mouse. +* Atomic Extents:: Treating a block of text as a single entity. - Canonicalizing means converting to the full form for an inst-pair, - i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator - is given a tag set of `nil' (the empty set), and a single tag is - converted into a tag set consisting only of that tag. + +File: lispref.info, Node: Intro to Extents, Next: Creating and Modifying Extents, Up: Extents + +Introduction to Extents +======================= + + An extent is a region of text within a buffer or string that has +certain properties associated with it. The properties of an extent +primarily affect the way the text contained in the extent is displayed. +Extents can freely overlap each other in a buffer or string. Extents +are invisible to functions that merely examine the text of a buffer or +string. + + _Please note:_ An alternative way to add properties to a buffer or +string is to use text properties. *Note Text Properties::. + + An extent is logically a Lisp object consisting of a start position, +an end position, a buffer or string to which these positions refer, and +a property list. As text is inserted into a buffer, the start and end +positions of the extent are automatically adjusted as necessary to keep +the extent referring to the same text in the buffer. If text is +inserted at the boundary of an extent, the extent's `start-open' and +`end-open' properties control whether the text is included as part of +the extent. If the text bounded by an extent is deleted, the extent +becomes "detached"; its start and end positions are no longer +meaningful, but it maintains all its other properties and can later be +reinserted into a buffer. (None of these considerations apply to +strings, because text cannot be inserted into or deleted from a string.) + + Each extent has a face or list of faces associated with it, which +controls the way in which the text bounded by the extent is displayed. +If an extent's face is `nil' or its properties are partially undefined, +the corresponding properties from the default face for the frame is +used. If two or more extents overlap, or if a list of more than one +face is specified for a particular extent, the corresponding faces are +merged to determine the text's displayed properties. Every extent has +a "priority" that determines which face takes precedence if the faces +conflict. (If two extents have the same priority, the one that comes +later in the display order takes precedence. *Note display order: +Extent Endpoints.) Higher-numbered priority values correspond to a +higher priority, and priority values can be negative. Every extent is +created with a priority of 0, but this can be changed with +`set-extent-priority'. Within a single extent with a list of faces, +faces earlier in the list have a higher priority than faces later in +the list. + + Extents can be set to respond specially to key and mouse events +within the extent. An extent's `keymap' property controls the effect of +key and mouse strokes within the extent's text, and the `mouse-face' +property controls whether the extent is highlighted when the mouse moves +over it. *Note Extents and Events::. + + An extent can optionally have a "begin-glyph" or "end-glyph" +associated with it. A begin-glyph or end-glyph is a pixmap or string +that will be displayed either at the start or end of an extent or in the +margin of the line that the start or end of the extent lies in, +depending on the extent's layout policy. Begin-glyphs and end-glyphs +are used to implement annotations, and you should use the annotation API +functions in preference to the lower-level extent functions. For more +information, *Note Annotations::. + + If an extent has its `detachable' property set, it will become +"detached" (i.e. no longer in the buffer) when all its text is deleted. +Otherwise, it will simply shrink down to zero-length and sit in the +same place in the buffer. By default, the `detachable' property is set +on newly-created extents. *Note Detached Extents::. + + If an extent has its `duplicable' property set, it will be +remembered when a string is created from text bounded by the extent. +When the string is re-inserted into a buffer, the extent will also be +re-inserted. This mechanism is used in the kill, yank, and undo +commands. *Note Duplicable Extents::. - If NOERROR is non-`nil', signal an error if the inst-pair is - invalid; otherwise return `t'. + +File: lispref.info, Node: Creating and Modifying Extents, Next: Extent Endpoints, Prev: Intro to Extents, Up: Extents - - Function: canonicalize-inst-list inst-list specifier-type &optional - noerror - This function canonicalizes the given INST-LIST (a list of - inst-pairs). - - SPECIFIER-TYPE specifies the type of specifier that this INST-LIST - will be used for. - - Canonicalizing means converting to the full form for an inst-list, - i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a - single inst-pair or any abbreviation thereof or a list of - (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.) - - If NOERROR is non-`nil', signal an error if the inst-list is - invalid; otherwise return `t'. - - - Function: canonicalize-spec spec specifier-type &optional noerror - This function canonicalizes the given SPEC (a specification). - - SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST - will be used for. - - Canonicalizing means converting to the full form for a spec, i.e. - `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a - possibly abbreviated inst-list or a cons of a locale and a - possibly abbreviated inst-list. (See `canonicalize-inst-list'.) - - If NOERROR is `nil', signal an error if the specification is - invalid; otherwise return `t'. +Creating and Modifying Extents +============================== - - Function: canonicalize-spec-list spec-list specifier-type &optional - noerror - This function canonicalizes the given SPEC-LIST (a list of - specifications). - - SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST - will be used for. - - Canonicalizing means converting to the full form for a spec-list, - i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This - function accepts a possibly abbreviated specification or a list of - such things. (See `canonicalize-spec'.) This is the function used - to convert spec-lists accepted by `set-specifier' and such into a - form suitable for `add-spec-list-to-specifier'. - - This function tries extremely hard to resolve any ambiguities, and - the built-in specifier types (font, image, toolbar, etc.) are - designed so that there won't be any ambiguities. - - If NOERROR is `nil', signal an error if the spec-list is invalid; - otherwise return `t'. + - Function: make-extent from to &optional buffer-or-string + This function makes an extent for the range [FROM, TO) in + BUFFER-OR-STRING (a buffer or string). BUFFER-OR-STRING defaults + to the current buffer. Insertions at point TO will be outside of + the extent; insertions at FROM will be inside the extent, causing + the extent to grow (*note Extent Endpoints::). This is the same + way that markers behave. The extent is initially detached if both + FROM and TO are `nil', and in this case BUFFER-OR-STRING defaults + to `nil', meaning the extent is in no buffer or string (*note + Detached Extents::). + + - Function: delete-extent extent + This function removes EXTENT from its buffer and destroys it. + This does not modify the buffer's text, only its display + properties. The extent cannot be used thereafter. To remove an + extent in such a way that it can be re-inserted later, use + `detach-extent'. *Note Detached Extents::. + + - Function: extent-object extent + This function returns the buffer or string that EXTENT is in. If + the return value is `nil', this means that the extent is detached; + however, a detached extent will not necessarily return a value of + `nil'. + + - Function: extent-live-p object + This function returns `t' if OBJECT is an extent that has not been + deleted, and `nil' otherwise.  -File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers - -Retrieving the Specifications from a Specifier -============================================== - - - Function: specifier-spec-list specifier &optional locale tag-set - exact-p - This function returns the spec-list of specifications for - SPECIFIER in LOCALE. - - If LOCALE is a particular locale (a window, buffer, frame, device, - or the symbol `global'), a spec-list consisting of the - specification for that locale will be returned. - - If LOCALE is a locale type (i.e. a symbol `window', `buffer', - `frame', or `device'), a spec-list of the specifications for all - locales of that type will be returned. - - If LOCALE is `nil' or the symbol `all', a spec-list of all - specifications in SPECIFIER will be returned. - - LOCALE can also be a list of locales, locale types, and/or `all'; - the result is as if `specifier-spec-list' were called on each - element of the list and the results concatenated together. - - Only instantiators where TAG-SET (a list of zero or more tags) is - a subset of (or possibly equal to) the instantiator's tag set are - returned. (The default value of` nil' is a subset of all tag sets, - so in this case no instantiators will be screened out.) If EXACT-P - is non-`nil', however, TAG-SET must be equal to an instantiator's - tag set for the instantiator to be returned. - - - Function: specifier-specs specifier &optional locale tag-set exact-p - This function returns the specification(s) for SPECIFIER in LOCALE. - - If LOCALE is a single locale or is a list of one element - containing a single locale, then a "short form" of the - instantiators for that locale will be returned. Otherwise, this - function is identical to `specifier-spec-list'. - - The "short form" is designed for readability and not for ease of - use in Lisp programs, and is as follows: - - 1. If there is only one instantiator, then an inst-pair (i.e. - cons of tag and instantiator) will be returned; otherwise a - list of inst-pairs will be returned. - - 2. For each inst-pair returned, if the instantiator's tag is - `any', the tag will be removed and the instantiator itself - will be returned instead of the inst-pair. - - 3. If there is only one instantiator, its value is `nil', and - its tag is `any', a one-element list containing `nil' will be - returned rather than just `nil', to distinguish this case - from there being no instantiators at all. - - - - Function: specifier-fallback specifier - This function returns the fallback value for SPECIFIER. Fallback - values are provided by the C code for certain built-in specifiers - to make sure that instancing won't fail even if all specs are - removed from the specifier, or to implement simple inheritance - behavior (e.g. this method is used to ensure that faces other than - `default' inherit their attributes from `default'). By design, - you cannot change the fallback value, and specifiers created with - `make-specifier' will never have a fallback (although a similar, - Lisp-accessible capability may be provided in the future to allow - for inheritance). - - The fallback value will be an inst-list that is instanced like any - other inst-list, a specifier of the same type as SPECIFIER - (results in inheritance), or `nil' for no fallback. - - When you instance a specifier, you can explicitly request that the - fallback not be consulted. (The C code does this, for example, when - merging faces.) See `specifier-instance'. +File: lispref.info, Node: Extent Endpoints, Next: Finding Extents, Prev: Creating and Modifying Extents, Up: Extents + +Extent Endpoints +================ + + Every extent has a start position and an end position, and logically +affects the characters between those positions. Normally the start and +end positions must both be valid positions in the extent's buffer or +string. However, both endpoints can be `nil', meaning the extent is +detached. *Note Detached Extents::. + + Whether the extent overlaps its endpoints is governed by its +`start-open' and `end-open' properties. Insertion of a character at a +closed endpoint will expand the extent to include that character; +insertion at an open endpoint will not. Similarly, functions such as +`extent-at' that scan over all extents overlapping a particular +position will include extents with a closed endpoint at that position, +but not extents with an open endpoint. + + Note that the `start-closed' and `end-closed' properties are +equivalent to `start-open' and `end-open' with the opposite sense. + + Both endpoints can be equal, in which case the extent includes no +characters but still exists in the buffer or string. Zero-length +extents are used to represent annotations (*note Annotations::) and can +be used as a more powerful form of a marker. Deletion of all the +characters in an extent may or may not result in a zero-length extent; +this depends on the `detachable' property (*note Detached Extents::). +Insertion at the position of a zero-length extent expands the extent if +both endpoints are closed; goes before the extent if it has the +`start-open' property; and goes after the extent if it has the +`end-open' property. Zero-length extents with both the `start-open' +and `end-open' properties are treated as if their starting point were +closed. Deletion of a character on a side of a zero-length extent +whose corresponding endpoint is closed causes the extent to be detached +if its `detachable' property is set; if the corresponding endpoint is +open, the extent remains in the buffer, moving as necessary. + + Extents are ordered within a buffer or string by increasing start +position, and then by decreasing end position (this is called the +"display order"). + + - Function: extent-start-position extent + This function returns the start position of EXTENT. + + - Function: extent-end-position extent + This function returns the end position of EXTENT. + + - Function: extent-length extent + This function returns the length of EXTENT in characters. If the + extent is detached, this returns `0'. If the extent is not + detached, this is equivalent to + (- (extent-end-position EXTENT) (extent-start-position EXTENT)) + + - Function: set-extent-endpoints extent start end &optional + buffer-or-string + This function sets the start and end position of EXTENT to START + and END. If both are `nil', this is equivalent to `detach-extent'. + + BUFFER-OR-STRING specifies the new buffer or string that the + extent should be in, and defaults to EXTENT's buffer or string. + (If `nil', and EXTENT is in no buffer and no string, it defaults + to the current buffer.) + + See documentation on `detach-extent' for a discussion of undo + recording.  -File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers - -Working With Specifier Tags -=========================== - - A specifier tag set is an entity that is attached to an instantiator -and can be used to restrict the scope of that instantiator to a -particular device class or device type and/or to mark instantiators -added by a particular package so that they can be later removed. - - A specifier tag set consists of a list of zero of more specifier -tags, each of which is a symbol that is recognized by XEmacs as a tag. -(The valid device types and device classes are always tags, as are any -tags defined by `define-specifier-tag'.) It is called a "tag set" (as -opposed to a list) because the order of the tags or the number of times -a particular tag occurs does not matter. - - Each tag has a predicate associated with it, which specifies whether -that tag applies to a particular device. The tags which are device -types and classes match devices of that type or class. User-defined -tags can have any predicate, or none (meaning that all devices match). -When attempting to instance a specifier, a particular instantiator is -only considered if the device of the domain being instanced over matches -all tags in the tag set attached to that instantiator. - - Most of the time, a tag set is not specified, and the instantiator -gets a null tag set, which matches all devices. - - - Function: valid-specifier-tag-p tag - This function returns non-`nil' if TAG is a valid specifier tag. - - - Function: valid-specifier-tag-set-p tag-set - This function returns non-`nil' if TAG-SET is a valid specifier - tag set. - - - Function: canonicalize-tag-set tag-set - This function canonicalizes the given tag set. Two canonicalized - tag sets can be compared with `equal' to see if they represent the - same tag set. (Specifically, canonicalizing involves sorting by - symbol name and removing duplicates.) - - - Function: device-matches-specifier-tag-set-p device tag-set - This function returns non-`nil' if DEVICE matches specifier tag - set TAG-SET. This means that DEVICE matches each tag in the tag - set. - - - Function: define-specifier-tag tag &optional predicate - This function defines a new specifier tag. If PREDICATE is - specified, it should be a function of one argument (a device) that - specifies whether the tag matches that particular device. If - PREDICATE is omitted, the tag matches all devices. - - You can redefine an existing user-defined specifier tag. However, - you cannot redefine the built-in specifier tags (the device types - and classes) or the symbols `nil', `t', `all', or `global'. - - - Function: device-matching-specifier-tag-list &optional device - This function returns a list of all specifier tags matching - DEVICE. DEVICE defaults to the selected device if omitted. - - - Function: specifier-tag-list - This function returns a list of all currently-defined specifier - tags. This includes the built-in ones (the device types and - classes). - - - Function: specifier-tag-predicate tag - This function returns the predicate for the given specifier tag. +File: lispref.info, Node: Finding Extents, Next: Mapping Over Extents, Prev: Extent Endpoints, Up: Extents + +Finding Extents +=============== + + The following functions provide a simple way of determining the +extents in a buffer or string. A number of more sophisticated +primitives for mapping over the extents in a range of a buffer or string +are also provided (*note Mapping Over Extents::). When reading through +this section, keep in mind the way that extents are ordered (*note +Extent Endpoints::). + + - Function: extent-list &optional buffer-or-string from to flags + property value + This function returns a list of the extents in BUFFER-OR-STRING. + BUFFER-OR-STRING defaults to the current buffer if omitted. FROM + and TO can be used to limit the range over which extents are + returned; if omitted, all extents in the buffer or string are + returned. + + More specifically, if a range is specified using FROM and TO, only + extents that overlap the range (i.e. begin or end inside of the + range) are included in the list. FROM and TO default to the + beginning and end of BUFFER-OR-STRING, respectively. + + FLAGS controls how end cases are treated. For a discussion of + this, and exactly what "overlap" means, see `map-extents'. + + The optional arguments PROPERTY and VALUE can be used to further + restrict which extents are returned. They have the same meaning + as for `map-extents'. + + If you want to map a function over the extents in a buffer or + string, consider using `map-extents' or `mapcar-extents' instead. + + See also the function `extents-at'. + + Functions that create extents must be prepared for the possibility +that there are other extents in the same area, created by other +functions. To deal with this, functions typically mark their own +extents by setting a particular property on them. The following +function makes it easier to locate those extents. + + - Function: extent-at pos &optional object property before at-flag + This function finds the "smallest" extent (i.e., the last one in + the display order) at (i.e., overlapping) POS in OBJECT (a buffer + or string) having PROPERTY set. OBJECT defaults to the current + buffer. PROPERTY defaults to `nil', meaning that any extent will + do. Returns `nil' if there is no matching extent at POS. If the + fourth argument BEFORE is not `nil', it must be an extent; any + returned extent will precede that extent. This feature allows + `extent-at' to be used by a loop over extents. + + AT-FLAG controls how end cases are handled (i.e. what "at" really + means), and should be one of: + + `nil' + + `after' + An extent is at POS if it covers the character after POS. + This is consistent with the way that text properties work. + + `before' + An extent is at POS if it covers the character before POS. + + `at' + An extent is at POS if it overlaps or abuts POS. This + includes all zero-length extents at POS. + + Note that in all cases, the start-openness and end-openness of the + extents considered is ignored. If you want to pay attention to + those properties, you should use `map-extents', which gives you + more control. + + The following low-level functions are provided for explicitly +traversing the extents in a buffer according to the display order. +These functions are mostly intended for debugging--in normal operation, +you should probably use `mapcar-extents' or `map-extents', or loop +using the BEFORE argument to `extent-at', rather than creating a loop +using `next-extent'. + + - Function: next-extent extent + Given an extent EXTENT, this function returns the next extent in + the buffer or string's display order. If EXTENT is a buffer or + string, this returns the first extent in the buffer or string. + + - Function: previous-extent extent + Given an extent EXTENT, this function returns the previous extent + in the buffer or string's display order. If EXTENT is a buffer or + string, this returns the last extent in the buffer or string.  -File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Example, Prev: Specifier Tag Functions, Up: Specifiers - -Functions for Instancing a Specifier -==================================== - - - Function: specifier-instance specifier &optional domain default - no-fallback - This function instantiates SPECIFIER (return its value) in DOMAIN. - If no instance can be generated for this domain, return DEFAULT. - - DOMAIN should be a window, frame, or device. Other values that - are legal as a locale (e.g. a buffer) are not valid as a domain - because they do not provide enough information to identify a - particular device (see `valid-specifier-domain-p'). DOMAIN - defaults to the selected window if omitted. - - "Instantiating" a specifier in a particular domain means - determining the specifier's "value" in that domain. This is - accomplished by searching through the specifications in the - specifier that correspond to all locales that can be derived from - the given domain, from specific to general. In most cases, the - domain is an Emacs window. In that case specifications are - searched for as follows: - - 1. A specification whose locale is the window itself; - - 2. A specification whose locale is the window's buffer; - - 3. A specification whose locale is the window's frame; - - 4. A specification whose locale is the window's frame's device; - - 5. A specification whose locale is the symbol `global'. - - If all of those fail, then the C-code-provided fallback value for - this specifier is consulted (see `specifier-fallback'). If it is - an inst-list, then this function attempts to instantiate that list - just as when a specification is located in the first five steps - above. If the fallback is a specifier, `specifier-instance' is - called recursively on this specifier and the return value used. - Note, however, that if the optional argument NO-FALLBACK is - non-`nil', the fallback value will not be consulted. - - Note that there may be more than one specification matching a - particular locale; all such specifications are considered before - looking for any specifications for more general locales. Any - particular specification that is found may be rejected because it - is tagged to a particular device class (e.g. `color') or device - type (e.g. `x') or both and the device for the given domain does - not match this, or because the specification is not valid for the - device of the given domain (e.g. the font or color name does not - exist for this particular X server). - - The returned value is dependent on the type of specifier. For - example, for a font specifier (as returned by the `face-font' - function), the returned value will be a font-instance object. For - images, the returned value will be a string, pixmap, or subwindow. - - - Function: specifier-instance-from-inst-list specifier domain - inst-list &optional default - This function attempts to convert a particular inst-list into an - instance. This attempts to instantiate INST-LIST in the given - DOMAIN, as if INST-LIST existed in a specification in SPECIFIER. - If the instantiation fails, DEFAULT is returned. In most - circumstances, you should not use this function; use - `specifier-instance' instead. +File: lispref.info, Node: Mapping Over Extents, Next: Extent Properties, Prev: Finding Extents, Up: Extents + +Mapping Over Extents +==================== + + The most basic and general function for mapping over extents is +called `map-extents'. You should read through the definition of this +function to familiarize yourself with the concepts and optional +arguments involved. However, in practice you may find it more +convenient to use the function `mapcar-extents' or to create a loop +using the `before' argument to `extent-at' (*note Finding Extents::). + + - Function: map-extents function &optional object from to maparg flags + property value + This function maps FUNCTION over the extents which overlap a + region in OBJECT. OBJECT is normally a buffer or string but could + be an extent (see below). The region is normally bounded by + [FROM, TO) (i.e. the beginning of the region is closed and the end + of the region is open), but this can be changed with the FLAGS + argument (see below for a complete discussion). + + FUNCTION is called with the arguments (extent, MAPARG). The + arguments OBJECT, FROM, TO, MAPARG, and FLAGS are all optional and + default to the current buffer, the beginning of OBJECT, the end of + OBJECT, `nil', and `nil', respectively. `map-extents' returns the + first non-`nil' result produced by FUNCTION, and no more calls to + FUNCTION are made after it returns non-`nil'. + + If OBJECT is an extent, FROM and TO default to the extent's + endpoints, and the mapping omits that extent and its predecessors. + This feature supports restarting a loop based on `map-extents'. + Note: OBJECT must be attached to a buffer or string, and the + mapping is done over that buffer or string. + + An extent overlaps the region if there is any point in the extent + that is also in the region. (For the purpose of overlap, + zero-length extents and regions are treated as closed on both ends + regardless of their endpoints' specified open/closedness.) Note + that the endpoints of an extent or region are considered to be in + that extent or region if and only if the corresponding end is + closed. For example, the extent [5,7] overlaps the region [2,5] + because 5 is in both the extent and the region. However, (5,7] + does not overlap [2,5] because 5 is not in the extent, and neither + [5,7] nor (5,7] overlaps the region [2,5) because 5 is not in the + region. + + The optional FLAGS can be a symbol or a list of one or more + symbols, modifying the behavior of `map-extents'. Allowed symbols + are: + + `end-closed' + The region's end is closed. + + `start-open' + The region's start is open. + + `all-extents-closed' + Treat all extents as closed on both ends for the purpose of + determining whether they overlap the region, irrespective of + their actual open- or closedness. + + `all-extents-open' + Treat all extents as open on both ends. + + `all-extents-closed-open' + Treat all extents as start-closed, end-open. + + `all-extents-open-closed' + Treat all extents as start-open, end-closed. + + `start-in-region' + In addition to the above conditions for extent overlap, the + extent's start position must lie within the specified region. + Note that, for this condition, open start positions are + treated as if 0.5 was added to the endpoint's value, and open + end positions are treated as if 0.5 was subtracted from the + endpoint's value. + + `end-in-region' + The extent's end position must lie within the region. + + `start-and-end-in-region' + Both the extent's start and end positions must lie within the + region. + + `start-or-end-in-region' + Either the extent's start or end position must lie within the + region. + + `negate-in-region' + The condition specified by a `*-in-region' flag must _not_ + hold for the extent to be considered. + + At most one of `all-extents-closed', `all-extents-open', + `all-extents-closed-open', and `all-extents-open-closed' may be + specified. + + At most one of `start-in-region', `end-in-region', + `start-and-end-in-region', and `start-or-end-in-region' may be + specified. + + If optional arg PROPERTY is non-`nil', only extents with that + property set on them will be visited. If optional arg VALUE is + non-`nil', only extents whose value for that property is `eq' to + VALUE will be visited. + + If you want to map over extents and accumulate a list of results, +the following function may be more convenient than `map-extents'. + + - Function: mapcar-extents function &optional predicate + buffer-or-string from to flags property value + This function applies FUNCTION to all extents which overlap a + region in BUFFER-OR-STRING. The region is delimited by FROM and + TO. FUNCTION is called with one argument, the extent. A list of + the values returned by FUNCTION is returned. An optional + PREDICATE may be used to further limit the extents over which + FUNCTION is mapped. The optional arguments FLAGS, PROPERTY, and + VALUE may also be used to control the extents passed to PREDICATE + or FUNCTION, and have the same meaning as in `map-extents'. + + - Function: map-extent-children function &optional object from to + maparg flags property value + This function is similar to `map-extents', but differs in that: + + * It only visits extents which start in the given region. + + * After visiting an extent E, it skips all other extents which + start inside E but end before E's end. + + Thus, this function may be used to walk a tree of extents in a + buffer: + (defun walk-extents (buffer &optional ignore) + (map-extent-children 'walk-extents buffer)) + + - Function: extent-in-region-p extent &optional from to flags + This function returns `t' if `map-extents' would visit EXTENT if + called with the given arguments.  -File: lispref.info, Node: Specifier Example, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers +File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents + +Properties of Extents +===================== + + Each extent has a property list associating property names with +values. Some property names have predefined meanings, and can usually +only assume particular values. Assigning other values to such a +property either cause the value to be converted into a legal value +(e.g., assigning anything but `nil' to a Boolean property will cause +the value of `t' to be assigned to the property) or will cause an +error. Property names without predefined meanings can be assigned any +value. An undefined property is equivalent to a property with a value +of `nil', or with a particular default value in the case of properties +with predefined meanings. Note that, when an extent is created, the +`end-open' and `detachable' properties are set on it. + + If an extent has a parent, all of its properties actually derive +from that parent (or from the root ancestor if the parent in turn has a +parent), and setting a property of the extent actually sets that +property on the parent. *Note Extent Parents::. + + - Function: extent-property extent property &optional default + This function returns EXTENT's value for PROPERTY, or DEFAULT if + no such property exists. + + - Function: extent-properties extent + This function returns a list of all of EXTENT's properties that do + not have the value of `nil' (or the default value, for properties + with predefined meanings). + + - Function: set-extent-property extent property value + This function sets PROPERTY to VALUE in EXTENT. (If PROPERTY has a + predefined meaning, only certain values are allowed, and some + values may be converted to others before being stored.) + + - Function: set-extent-properties extent plist + Change some properties of EXTENT. PLIST is a property list. This + is useful to change many extent properties at once. + + The following table lists the properties with predefined meanings, +along with their allowable values. + +`detached' + (Boolean) Whether the extent is detached. Setting this is the + same as calling `detach-extent'. *Note Detached Extents::. + +`destroyed' + (Boolean) Whether the extent has been deleted. Setting this is + the same as calling `delete-extent'. + +`priority' + (integer) The extent's redisplay priority. Defaults to 0. *Note + priority: Intro to Extents. This property can also be set with + `set-extent-priority' and accessed with `extent-priority'. + +`start-open' + (Boolean) Whether the start position of the extent is open, + meaning that characters inserted at that position go outside of + the extent. *Note Extent Endpoints::. + +`start-closed' + (Boolean) Same as `start-open' but with the opposite sense. + Setting this property clears `start-open' and vice-versa. + +`end-open' + (Boolean) Whether the end position of the extent is open, meaning + that characters inserted at that position go outside of the + extent. This is `t' by default. *Note Extent Endpoints::. + +`end-closed' + (Boolean) Same as `end-open' but with the opposite sense. Setting + this property clears `end-open' and vice-versa. + +`read-only' + (Boolean) Whether text within this extent will be unmodifiable. + +`face' + (face, face name, list of faces or face names, or `nil') The face + in which to display the extent's text. This property can also be + set with `set-extent-face' and accessed with `extent-face'. Note + that if a list of faces is specified, the faces are merged + together, with faces earlier in the list having priority over + faces later in the list. + +`mouse-face' + (face, face name, list of faces or face names, or `nil') The face + used to display the extent when the mouse moves over it. This + property can also be set with `set-extent-mouse-face' and accessed + with `extent-mouse-face'. Note that if a list of faces is + specified, the faces are merged together, with faces earlier in + the list having priority over faces later in the list. *Note + Extents and Events::. + +`pointer' + (pointer glyph) The glyph used as the pointer when the mouse + moves over the extent. This takes precedence over the + `text-pointer-glyph' and `nontext-pointer-glyph' variables. If + for any reason this glyph is an invalid pointer, the standard + glyphs will be used as fallbacks. *Note Mouse Pointer::. + +`detachable' + (Boolean) Whether this extent becomes detached when all of the + text it covers is deleted. This is `t' by default. *Note + Detached Extents::. + +`duplicable' + (Boolean) Whether this extent should be copied into strings, so + that kill, yank, and undo commands will restore or copy it. *Note + Duplicable Extents::. + +`unique' + (Boolean) Meaningful only in conjunction with `duplicable'. When + this is set, there may be only one instance of this extent + attached at a time. *Note Duplicable Extents::. + +`invisible' + (Boolean) If `t', text under this extent will not be displayed - + it will look as if the text is not there at all. + +`keymap' + (keymap or `nil') This keymap is consulted for mouse clicks on this + extent or keypresses made while `point' is within the extent. + *Note Extents and Events::. + +`copy-function' + This is a hook that is run when a duplicable extent is about to be + copied from a buffer to a string (or the kill ring). *Note + Duplicable Extents::. + +`paste-function' + This is a hook that is run when a duplicable extent is about to be + copied from a string (or the kill ring) into a buffer. *Note + Duplicable Extents::. + +`begin-glyph' + (glyph or `nil') This extent's begin glyph. *Note Annotations::. + +`end-glyph' + (glyph or `nil') This extent's end glyph. *Note Annotations::. + +`begin-glyph-layout' + (`text', `whitespace', `inside-margin', or `outside-margin') The + layout policy for this extent's begin glyph. Defaults to `text'. + *Note Annotations::. + +`end-glyph-layout' + (`text', `whitespace', `inside-margin', or `outside-margin') The + layout policy for this extent's end glyph. Defaults to `text'. + *Note Annotations::. + +`initial-redisplay-function' + (any funcallable object) The function to be called the first time + (a part of) the extent is redisplayed. It will be called with the + extent as its argument. + + This is used by `lazy-shot' to implement lazy font-locking. The + functionality is still experimental, and may change without further + notice. + + The following convenience functions are provided for accessing +particular properties of an extent. + + - Function: extent-face extent + This function returns the `face' property of EXTENT. This might + also return a list of face names. Do not modify this list + directly! Instead, use `set-extent-face'. + + Note that you can use `eq' to compare lists of faces as returned + by `extent-face'. In other words, if you set the face of two + different extents to two lists that are `equal' but not `eq', then + the return value of `extent-face' on the two extents will return + the identical list. + + - Function: extent-mouse-face extent + This function returns the `mouse-face' property of EXTENT. This + might also return a list of face names. Do not modify this list + directly! Instead, use `set-extent-mouse-face'. + + Note that you can use `eq' to compare lists of faces as returned + by `extent-mouse-face', just like for `extent-face'. + + - Function: extent-priority extent + This function returns the `priority' property of EXTENT. + + - Function: extent-keymap extent + This function returns the `keymap' property of EXTENT. + + - Function: extent-begin-glyph-layout extent + This function returns the `begin-glyph-layout' property of EXTENT, + i.e. the layout policy associated with the EXTENT's begin glyph. + + - Function: extent-end-glyph-layout extent + This function returns the `end-glyph-layout' property of EXTENT, + i.e. the layout policy associated with the EXTENT's end glyph. + + - Function: extent-begin-glyph extent + This function returns the `begin-glyph' property of EXTENT, i.e. + the glyph object displayed at the beginning of EXTENT. If there + is none, `nil' is returned. + + - Function: extent-end-glyph extent + This function returns the `end-glyph' property of EXTENT, i.e. the + glyph object displayed at the end of EXTENT. If there is none, + `nil' is returned. -Example of Specifier Usage -========================== + The following convenience functions are provided for setting +particular properties of an extent. + + - Function: set-extent-priority extent priority + This function sets the `priority' property of EXTENT to PRIORITY. + + - Function: set-extent-face extent face + This function sets the `face' property of EXTENT to FACE. - Now let us present an example to clarify the theoretical discussions -we have been through. In this example, we will use the general -specifier functions for clarity. Keep in mind that many types of -specifiers, and some other types of objects that are associated with -specifiers (e.g. faces), provide convenience functions making it easier -to work with objects of that type. - - Let us consider the background color of the default face. A -specifier is used to specify how that color will appear in different -domains. First, let's retrieve the specifier: - - (setq sp (face-property 'default 'background)) - => # - - (specifier-specs sp) - => ((# (nil . "forest green")) - (# (nil . "hot pink")) - (# (nil . "puke orange") - (nil . "moccasin")) - (# (nil . "magenta")) - (global ((tty) . "cyan") (nil . "white")) - ) - - Then, say we want to determine what the background color of the -default face is for the window currently displaying the buffer -`*scratch*'. We call - - (get-buffer-window "*scratch*") - => # - (window-frame (get-buffer-window "*scratch*")) - => # - (specifier-instance sp (get-buffer-window "*scratch*")) - => # - - Note that we passed a window to `specifier-instance', not a buffer. -We cannot pass a buffer because a buffer by itself does not provide -enough information. The buffer might not be displayed anywhere at all, -or could be displayed in many different frames on different devices. - - The result is arrived at like this: - - 1. First, we look for a specification matching the buffer displayed - in the window, i.e. `*scratch'. There are none, so we proceed. - - 2. Then, we look for a specification matching the window itself. - Again, there are none. - - 3. Then, we look for a specification matching the window's frame. The - specification `(# . "puke orange")' is - found. We call the instantiation method for colors, passing it the - locale we were searching over (i.e. the window, in this case) and - the instantiator (`"puke orange"'). However, the particular device - which this window is on (let's say it's an X connection) doesn't - recognize the color `"puke orange"', so the specification is - rejected. - - 4. So we continue looking for a specification matching the window's - frame. We find `(# . "moccasin")'. Again, - we call the instantiation method for colors. This time, the X - server our window is on recognizes the color `moccasin', and so the - instantiation method succeeds and returns a color instance. + - Function: set-extent-mouse-face extent face + This function sets the `mouse-face' property of EXTENT to FACE. - -File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Example, Up: Specifiers + - Function: set-extent-keymap extent keymap + This function sets the `keymap' property of EXTENT to KEYMAP. + KEYMAP must be either a keymap object, or `nil'. -Creating New Specifier Objects -============================== + - Function: set-extent-begin-glyph-layout extent layout + This function sets the `begin-glyph-layout' property of EXTENT to + LAYOUT. - - Function: make-specifier type - This function creates a new specifier. - - A specifier is an object that can be used to keep track of a - property whose value can be per-buffer, per-window, per-frame, or - per-device, and can further be restricted to a particular - device-type or device-class. Specifiers are used, for example, - for the various built-in properties of a face; this allows a face - to have different values in different frames, buffers, etc. For - more information, see `specifier-instance', `specifier-specs', and - `add-spec-to-specifier'; or, for a detailed description of - specifiers, including how they are instantiated over a particular - domain (i.e. how their value in that domain is determined), see - the chapter on specifiers in the XEmacs Lisp Reference Manual. - - TYPE specifies the particular type of specifier, and should be one - of the symbols `generic', `integer', `natnum', `boolean', `color', - `font', `image', `face-boolean', or `toolbar'. - - For more information on particular types of specifiers, see the - functions `generic-specifier-p', `integer-specifier-p', - `natnum-specifier-p', `boolean-specifier-p', `color-specifier-p', - `font-specifier-p', `image-specifier-p', - `face-boolean-specifier-p', and `toolbar-specifier-p'. - - - Function: make-specifier-and-init type spec-list &optional - dont-canonicalize - This function creates and initialize a new specifier. - - This is a front-end onto `make-specifier' that allows you to create - a specifier and add specs to it at the same time. TYPE specifies - the specifier type. SPEC-LIST supplies the specification(s) to be - added to the specifier. Normally, almost any reasonable - abbreviation of the full spec-list form is accepted, and is - converted to the full form; however, if optional argument - DONT-CANONICALIZE is non-`nil', this conversion is not performed, - and the SPEC-LIST must already be in full form. See - `canonicalize-spec-list'. + - Function: set-extent-end-glyph-layout extent layout + This function sets the `end-glyph-layout' property of EXTENT to + LAYOUT. - -File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers + - Function: set-extent-begin-glyph extent begin-glyph &optional layout + This function sets the `begin-glyph' and `glyph-layout' properties + of EXTENT to BEGIN-GLYPH and LAYOUT, respectively. (LAYOUT + defaults to `text' if not specified.) -Functions for Checking the Validity of Specifier Components -=========================================================== + - Function: set-extent-end-glyph extent end-glyph &optional layout + This function sets the `end-glyph' and `glyph-layout' properties + of EXTENT to END-GLYPH and LAYOUT, respectively. (LAYOUT defaults + to `text' if not specified.) - - Function: valid-specifier-domain-p domain - This function returns non-`nil' if DOMAIN is a valid specifier - domain. A domain is used to instance a specifier (i.e. determine - the specifier's value in that domain). Valid domains are a - window, frame, or device. (`nil' is not valid.) + - Function: set-extent-initial-redisplay-function extent function + This function sets the `initial-redisplay-function' property of the + extent to FUNCTION. - - Function: valid-specifier-locale-p locale - This function returns non-`nil' if LOCALE is a valid specifier - locale. Valid locales are a device, a frame, a window, a buffer, - and `global'. (`nil' is not valid.) + +File: lispref.info, Node: Detached Extents, Next: Extent Parents, Prev: Extent Properties, Up: Extents + +Detached Extents +================ + + A detached extent is an extent that is not attached to a buffer or +string but can be re-inserted. Detached extents have a start position +and end position of `nil'. Extents can be explicitly detached using +`detach-extent'. An extent is also detached when all of its characters +are all killed by a deletion, if its `detachable' property is set; if +this property is not set, the extent becomes a zero-length extent. +(Zero-length extents with the `detachable' property set behave +specially. *Note zero-length extents: Extent Endpoints.) + + - Function: detach-extent extent + This function detaches EXTENT from its buffer or string. If + EXTENT has the `duplicable' property, its detachment is tracked by + the undo mechanism. *Note Duplicable Extents::. + + - Function: extent-detached-p extent + This function returns `nil' if EXTENT is detached, and `t' + otherwise. + + - Function: copy-extent extent &optional object + This function makes a copy of EXTENT. It is initially detached. + Optional argument OBJECT defaults to EXTENT's object (normally a + buffer or string, but could be `nil'). + + - Function: insert-extent extent &optional start end no-hooks object + This function inserts EXTENT from START to END in OBJECT (a buffer + or string). If EXTENT is detached from a different buffer or + string, or in most cases when EXTENT is already attached, the + extent will first be copied as if with `copy-extent'. This + function operates the same as if `insert' were called on a string + whose extent data calls for EXTENT to be inserted, except that if + NO-HOOKS is non-`nil', EXTENT's `paste-function' will not be + invoked. *Note Duplicable Extents::. - - Function: valid-specifier-locale-type-p locale-type - Given a specifier LOCALE-TYPE, this function returns non-nil if it - is valid. Valid locale types are the symbols `global', `device', - `frame', `window', and `buffer'. (Note, however, that in functions - that accept either a locale or a locale type, `global' is - considered an individual locale.) + +File: lispref.info, Node: Extent Parents, Next: Duplicable Extents, Prev: Detached Extents, Up: Extents - - Function: valid-specifier-type-p specifier-type - Given a SPECIFIER-TYPE, this function returns non-`nil' if it is - valid. Valid types are `generic', `integer', `boolean', `color', - `font', `image', `face-boolean', and `toolbar'. +Extent Parents +============== - - Function: valid-specifier-tag-p tag - This function returns non-`nil' if TAG is a valid specifier tag. + An extent can have a parent extent set for it. If this is the case, +the extent derives all its properties from that extent and has no +properties of its own. The only "properties" that the extent keeps are +the buffer or string it refers to and the start and end points. (More +correctly, the extent's own properties are shadowed. If you later +change the extent to have no parent, its own properties will become +visible again.) - - Function: valid-instantiator-p instantiator specifier-type - This function returns non-`nil' if INSTANTIATOR is valid for - SPECIFIER-TYPE. + It is possible for an extent's parent to itself have a parent, and +so on. Through this, a whole tree of extents can be created, all +deriving their properties from one root extent. Note, however, that +you cannot create an inheritance loop--this is explicitly disallowed. - - Function: valid-inst-list-p inst-list type - This function returns non-`nil' if INST-LIST is valid for - specifier type TYPE. + Parent extents are used to implement the extents over the modeline. - - Function: valid-spec-list-p spec-list type - This function returns non-`nil' if SPEC-LIST is valid for - specifier type TYPE. + - Function: set-extent-parent extent parent + This function sets the parent of EXTENT to PARENT. If PARENT is + `nil', the extent is set to have no parent. - - Function: check-valid-instantiator instantiator specifier-type - This function signals an error if INSTANTIATOR is invalid for - SPECIFIER-TYPE. + - Function: extent-parent extent + This function return the parents (if any) of EXTENT, or `nil'. - - Function: check-valid-inst-list inst-list type - This function signals an error if INST-LIST is invalid for - specifier type TYPE. + - Function: extent-children extent + This function returns a list of the children (if any) of EXTENT. + The children of an extent are all those extents whose parent is + that extent. This function does not recursively trace children of + children. - - Function: check-valid-spec-list spec-list type - This function signals an error if SPEC-LIST is invalid for - specifier type TYPE. + - Function: extent-descendants extent + This function returns a list of all descendants of EXTENT, + including EXTENT. This recursively applies `extent-children' to + any children of EXTENT, until no more children can be found.  -File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers - -Other Functions for Working with Specifications in a Specifier -============================================================== - - - Function: copy-specifier specifier &optional dest locale tag-set - exact-p how-to-add - This function copies SPECIFIER to DEST, or creates a new one if - DEST is `nil'. - - If DEST is `nil' or omitted, a new specifier will be created and - the specifications copied into it. Otherwise, the specifications - will be copied into the existing specifier in DEST. - - If LOCALE is `nil' or the symbol `all', all specifications will be - copied. If LOCALE is a particular locale, the specification for - that particular locale will be copied. If LOCALE is a locale - type, the specifications for all locales of that type will be - copied. LOCALE can also be a list of locales, locale types, - and/or `all'; this is equivalent to calling `copy-specifier' for - each of the elements of the list. See `specifier-spec-list' for - more information about LOCALE. - - Only instantiators where TAG-SET (a list of zero or more tags) is - a subset of (or possibly equal to) the instantiator's tag set are - copied. (The default value of `nil' is a subset of all tag sets, - so in this case no instantiators will be screened out.) If EXACT-P - is non-`nil', however, TAG-SET must be equal to an instantiator's - tag set for the instantiator to be copied. - - Optional argument HOW-TO-ADD specifies what to do with existing - specifications in DEST. If nil, then whichever locales or locale - types are copied will first be completely erased in DEST. - Otherwise, it is the same as in `add-spec-to-specifier'. - - - Function: remove-specifier specifier &optional locale tag-set exact-p - This function removes specification(s) for SPECIFIER. - - If LOCALE is a particular locale (a buffer, window, frame, device, - or the symbol `global'), the specification for that locale will be - removed. - - If instead, LOCALE is a locale type (i.e. a symbol `buffer', - `window', `frame', or `device'), the specifications for all - locales of that type will be removed. - - If LOCALE is `nil' or the symbol `all', all specifications will be - removed. - - LOCALE can also be a list of locales, locale types, and/or `all'; - this is equivalent to calling `remove-specifier' for each of the - elements in the list. - - Only instantiators where TAG-SET (a list of zero or more tags) is - a subset of (or possibly equal to) the instantiator's tag set are - removed. (The default value of `nil' is a subset of all tag sets, - so in this case no instantiators will be screened out.) If EXACT-P - is non-`nil', however, TAG-SET must be equal to an instantiator's - tag set for the instantiator to be removed. - - - Function: map-specifier specifier func &optional locale maparg - This function applies FUNC to the specification(s) for LOCALE in - SPECIFIER. - - If LOCALE is a locale, FUNC will be called for that locale. If - LOCALE is a locale type, FUNC will be mapped over all locales of - that type. If LOCALE is `nil' or the symbol `all', FUNC will be - mapped over all locales in SPECIFIER. - - FUNC is called with four arguments: the SPECIFIER, the locale - being mapped over, the inst-list for that locale, and the optional - MAPARG. If any invocation of FUNC returns non-`nil', the mapping - will stop and the returned value becomes the value returned from - `map-specifier'. Otherwise, `map-specifier' returns `nil'. - - - Function: specifier-locale-type-from-locale locale - Given a specifier LOCALE, this function returns its type. +File: lispref.info, Node: Duplicable Extents, Next: Extents and Events, Prev: Extent Parents, Up: Extents + +Duplicable Extents +================== + + If an extent has the `duplicable' property, it will be copied into +strings, so that kill, yank, and undo commands will restore or copy it. + + Specifically: + + * When a string is created using `buffer-substring' or + `buffer-string', any duplicable extents in the region corresponding + to the string will be copied into the string (*note Buffer + Contents::). When the string is inserted into a buffer using + `insert', `insert-before-markers', `insert-buffer' or + `insert-buffer-substring', the extents in the string will be copied + back into the buffer (*note Insertion::). The extents in a string + can, of course, be retrieved explicitly using the standard extent + primitives over the string. + + * Similarly, when text is copied or cut into the kill ring, any + duplicable extents will be remembered and reinserted later when + the text is pasted back into a buffer. + + * When `concat' is called on strings, the extents in the strings are + copied into the resulting string. + + * When `substring' is called on a string, the relevant extents are + copied into the resulting string. + + * When a duplicable extent is detached by `detach-extent' or string + deletion, or inserted by `insert-extent' or string insertion, the + action is recorded by the undo mechanism so that it can be undone + later. Note that if an extent gets detached and then a later undo + causes the extent to get reinserted, the new extent will not be + `eq' to the original extent. + + * Extent motion, face changes, and attachment via `make-extent' are + not recorded by the undo mechanism. This means that extent changes + which are to be undo-able must be performed by character editing, + or by insertion and detachment of duplicable extents. + + * A duplicable extent's `copy-function' property, if non-`nil', + should be a function, and will be run when a duplicable extent is + about to be copied from a buffer to a string (or the kill ring). + It is called with three arguments: the extent and the buffer + positions within it which are being copied. If this function + returns `nil', then the extent will not be copied; otherwise it + will. + + * A duplicable extent's `paste-function' property, if non-`nil', + should be a function, and will be run when a duplicable extent is + about to be copied from a string (or the kill ring) into a buffer. + It is called with three arguments: the original extent and the + buffer positions which the copied extent will occupy. (This hook + is run after the corresponding text has already been inserted into + the buffer.) Note that the extent argument may be detached when + this function is run. If this function returns `nil', no extent + will be inserted. Otherwise, there will be an extent covering the + range in question. + + Note: if the extent to be copied is already attached to the buffer + and overlaps the new range, the extent will simply be extended and + the `paste-function' will not be called.  -File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top +File: lispref.info, Node: Extents and Events, Next: Atomic Extents, Prev: Duplicable Extents, Up: Extents + +Interaction of Extents with Keyboard and Mouse Events +===================================================== + + If an extent has the `mouse-face' property set, it will be +highlighted when the mouse passes over it. Highlighting is accomplished +by merging the extent's face with the face or faces specified by the +`mouse-face' property. The effect is as if a pseudo-extent with the +`mouse-face' face were inserted after the extent in the display order +(*note Extent Endpoints::, display order). + + - Variable: mouse-highlight-priority + This variable holds the priority to use when merging in the + highlighting pseudo-extent. The default is 1000. This is + purposely set very high so that the highlighting pseudo-extent + shows up even if there are other extents with various priorities + at the same location. + + You can also explicitly cause an extent to be highlighted. Only one +extent at a time can be highlighted in this fashion, and any other +highlighted extent will be de-highlighted. + + - Function: highlight-extent extent &optional highlight-p + This function highlights (if HIGHLIGHT-P is non-`nil') or + de-highlights (if HIGHLIGHT-P is `nil') EXTENT, if EXTENT has the + `mouse-face' property. (Nothing happens if EXTENT does not have + the `mouse-face' property.) + + - Function: force-highlight-extent extent &optional highlight-p + This function is similar to `highlight-extent' but highlights or + de-highlights the extent regardless of whether it has the + `mouse-face' property. + + If an extent has a `keymap' property, this keymap will be consulted +for mouse clicks on the extent and keypresses made while `point' is +within the extent. The behavior of mouse clicks and keystrokes not +defined in the keymap is as normal for the buffer. -Faces and Window-System Objects -******************************* + +File: lispref.info, Node: Atomic Extents, Prev: Extents and Events, Up: Extents -* Menu: +Atomic Extents +============== + + If the Lisp file `atomic-extents' is loaded, then the atomic extent +facility is available. An "atomic extent" is an extent for which +`point' cannot be positioned anywhere within it. This ensures that +when selecting text, either all or none of the extent is selected. -* Faces:: Controlling the way text looks. -* Fonts:: Controlling the typeface of text. -* Colors:: Controlling the color of text and pixmaps. + To make an extent atomic, set its `atomic' property.  -File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects - -Faces -===== - - A "face" is a named collection of graphical properties: font, -foreground color, background color, background pixmap, optional -underlining, and (on TTY devices) whether the text is to be highlighted, -dimmed, blinking, or displayed in reverse video. Faces control the -display of text on the screen. Every face has a name, which is a symbol -such as `default' or `modeline'. - - Each built-in property of a face is controlled using a specifier, -which allows it to have separate values in particular buffers, frames, -windows, and devices and to further vary according to device type (X or -TTY) and device class (color, mono, or grayscale). *Note Specifiers::, -for more information. - - The face named `default' is used for ordinary text. The face named -`modeline' is used for displaying the modeline. The face named -`highlight' is used for highlighted extents (*note Extents::). The -faces named `left-margin' and `right-margin' are used for the left and -right margin areas, respectively (*note Annotations::). The face named -`zmacs-region' is used for the highlighted region between point and -mark. +File: lispref.info, Node: Specifiers, Next: Faces and Window-System Objects, Prev: Extents, Up: Top + +Specifiers +********** + + A specifier is an object used to keep track of a property whose value +may vary depending on the particular situation (e.g. particular buffer +displayed in a particular window) that it is used in. The value of many +built-in properties, such as the font, foreground, background, and such +properties of a face and variables such as `modeline-shadow-thickness' +and `top-toolbar-height', is actually a specifier object. The +specifier object, in turn, is "instanced" in a particular situation to +yield the real value of the property in that situation. + + - Function: specifierp object + This function returns non-`nil' if OBJECT is a specifier. * Menu: -* Merging Faces:: How XEmacs decides which face to use - for a character. -* Basic Face Functions:: How to define and examine faces. -* Face Properties:: How to access and modify a face's properties. -* Face Convenience Functions:: Convenience functions for accessing - particular properties of a face. -* Other Face Display Functions:: Other functions pertaining to how a - a face appears. +* Introduction to Specifiers:: Specifiers provide a clean way for + display and other properties to vary + (under user control) in a wide variety + of contexts. +* Specifiers In-Depth:: Gory details about specifier innards. +* Specifier Instancing:: Instancing means obtaining the ``value'' of + a specifier in a particular context. +* Specifier Types:: Specifiers come in different flavors. +* Adding Specifications:: Specifications control a specifier's ``value'' + by giving conditions under which a + particular value is valid. +* Retrieving Specifications:: Querying a specifier's specifications. +* Specifier Tag Functions:: Working with specifier tags. +* Specifier Instancing Functions:: + Functions to instance a specifier. +* Specifier Example:: Making all this stuff clearer. +* Creating Specifiers:: Creating specifiers for your own use. +* Specifier Validation Functions:: + Validating the components of a specifier. +* Other Specification Functions:: + Other ways of working with specifications.  -File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces - -Merging Faces for Display -------------------------- - - Here are all the ways to specify which face to use for display of -text: - - * With defaults. Each frame has a "default face", which is used for - all text that doesn't somehow specify another face. The face named - `default' applies to the text area, while the faces `left-margin' - and `right-margin' apply to the left and right margin areas. - - * With text properties. A character may have a `face' property; if - so, it's displayed with that face. (Text properties are actually - implemented in terms of extents.) *Note Text Properties::. - - * With extents. An extent may have a `face' property, which applies - to all the text covered by the extent; in addition, if the - `highlight' property is set, the `highlight' property applies when - the mouse moves over the extent or if the extent is explicitly - highlighted. *Note Extents::. - - * With annotations. Annotations that are inserted into a buffer can - specify their own face. (Annotations are actually implemented in - terms of extents.) *Note Annotations::. - - If these various sources together specify more than one face for a -particular character, XEmacs merges the properties of the various faces -specified. Extents, text properties, and annotations all use the same -underlying representation (as extents). When multiple extents cover one -character, an extent with higher priority overrides those with lower -priority. *Note Extents::. If no extent covers a particular character, -the `default' face is used. - - If a background pixmap is specified, it determines what will be -displayed in the background of text characters. If the background -pixmap is actually a pixmap, with its colors specified, those colors are -used; if it is a bitmap, the face's foreground and background colors are -used to color it. +File: lispref.info, Node: Introduction to Specifiers, Next: Specifiers In-Depth, Up: Specifiers - -File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces - -Basic Functions for Working with Faces --------------------------------------- - - The properties a face can specify include the font, the foreground -color, the background color, the background pixmap, the underlining, -the display table, and (for TTY devices) whether the text is to be -highlighted, dimmed, blinking, or displayed in reverse video. The face -can also leave these unspecified, causing them to assume the value of -the corresponding property of the `default' face. - - Here are the basic primitives for working with faces. - - - Function: make-face name &optional doc-string temporary - This function defines and returns a new face named NAME, initially - with all properties unspecified. It does nothing if there is - already a face named NAME. Optional argument DOC-STRING specifies - an explanatory string used for descriptive purposes. If optional - argument TEMPORARY is non-`nil', the face will automatically - disappear when there are no more references to it anywhere in text - or Lisp code (otherwise, the face will continue to exist - indefinitely even if it is not used). - - - Function: face-list &optional temporary - This function returns a list of the names of all defined faces. If - TEMPORARY is `nil', only the permanent faces are included. If it - is `t', only the temporary faces are included. If it is any other - non-`nil' value both permanent and temporary are included. - - - Function: facep object - This function returns whether the given object is a face. - - - Function: copy-face old-face new-name &optional locale how-to-add - This function defines a new face named NEW-NAME which is a copy of - the existing face named OLD-FACE. If there is already a face - named NEW-NAME, then it alters the face to have the same - properties as OLD-FACE. LOCALE and HOW-TO-ADD let you copy just - parts of the old face rather than the whole face, and are as in - `copy-specifier' (*note Specifiers::). +Introduction to Specifiers +========================== + + Sometimes you may want the value of a property to vary depending on +the context the property is used in. A simple example of this in XEmacs +is buffer-local variables. For example, the variable +`modeline-format', which controls the format of the modeline, can have +different values depending on the particular buffer being edited. The +variable has a default value which most modes will use, but a +specialized package such as Calendar might change the variable so as to +tailor the modeline to its own purposes. + + Other properties (such as those that can be changed by the +`modify-frame-parameters' function, for example the color of the text +cursor) can have frame-local values, although it might also make sense +for them to have buffer-local values. In other cases, you might want +the property to vary depending on the particular window within the +frame that applies (e.g. the top or bottom window in a split frame), the +device type that that frame appears on (X or tty), etc. Perhaps you can +envision some more complicated scenario where you want a particular +value in a specified buffer, another value in all other buffers +displayed on a particular frame, another value in all other buffers +displayed in all other frames on any mono (two-color, e.g. black and +white only) displays, and a default value in all other circumstances. + + A "specifier" is a generalization of this, allowing a great deal of +flexibility in controlling exactly what value a property has in which +circumstances. It is most commonly used for display properties, such as +an image or the foreground color of a face. As a simple example, you +can specify that the foreground of the default face be + + * blue for a particular buffer + + * green for all other buffers + + As a more complicated example, you could specify that the foreground +of the default face be + + * forest green for all buffers displayed in a particular Emacs + window, or green if the X server doesn't recognize the color + `forest green' + + * blue for all buffers displayed in a particular frame + + * red for all other buffers displayed on a color device + + * white for all other buffers