X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=info%2Flispref.info-35;h=caf9facd089b6d041a6a7721b7ca1f7e933d185e;hb=2779fcb5d524d6b7de5a6ef9ebfd6662433a4a07;hp=6c3b144b93d89874fd95f20dec114df9dc388386;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-35 b/info/lispref.info-35 index 6c3b144..caf9fac 100644 --- a/info/lispref.info-35 +++ b/info/lispref.info-35 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 3.12s from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,933 +50,1046 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces +File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers + +In-Depth Overview of a Specifier +================================ + + A specifier object encapsulates a set of "specifications", each of +which says what its value should be if a particular condition applies. +For example, one specification might be "The value should be +darkseagreen2 on X devices" another might be "The value should be blue +in the *Help* buffer". In specifier terminology, these conditions are +called "locales" and the values are called "instantiators". Given a +specifier, a logical question is "What is its value in a particular +situation?" This involves looking through the specifications to see +which ones apply to this particular situation, and perhaps preferring +one over another if more than one applies. In specifier terminology, a +"particular situation" is called a "domain", and determining its value +in a particular domain is called "instancing". Most of the time, a +domain is identified by a particular window. For example, if the +redisplay engine is drawing text in the default face in a particular +window, it retrieves the specifier for the foreground color of the +default face and "instances" it in the domain given by that window; in +other words, it asks the specifier, "What is your value in this +window?". + + More specifically, a specifier contains a set of "specifications", +each of which associates a "locale" (a window object, a buffer object, +a frame object, a device object, or the symbol `global') with an +"inst-list", which is a list of one or more "inst-pairs". (For each +possible locale, there can be at most one specification containing that +locale.) Each inst-pair is a cons of a "tag set" (an unordered list of +zero or more symbols, or "tags") and an "instantiator" (the allowed +form of this varies depending on the type of specifier). In a given +specification, there may be more than one inst-pair with the same tag +set; this is unlike for locales. + + The tag set is used to restrict the sorts of devices over which the +instantiator is valid and to uniquely identify instantiators added by a +particular application, so that different applications can work on the +same specifier and not interfere with each other. Each tag can have a +"predicate" associated with it, which is a function of one argument (a +device) that specifies whether the tag matches that particular device. +(If a tag does not have a predicate, it matches all devices.) All tags +in a tag set must match a device for the associated inst-pair to be +instantiable over that device. (A null tag set is perfectly valid.) + + The valid device types (normally `x', `tty', and `stream') and +device classes (normally `color', `grayscale', and `mono') can always +be used as tags, and match devices of the associated type or class +(*note Consoles and Devices::). User-defined tags may be defined, with +an optional predicate specified. An application can create its own +tag, use it to mark all its instantiators, and be fairly confident that +it will not interfere with other applications that modify the same +specifier--Functions that add a specification to a specifier usually +only overwrite existing inst-pairs with the same tag set as was given, +and a particular tag or tag set can be specified when removing +instantiators. + + When a specifier is instanced in a domain, both the locale and the +tag set can be viewed as specifying necessary conditions that must +apply in that domain for an instantiator to be considered as a possible +result of the instancing. More specific locales always override more +general locales (thus, there is no particular ordering of the +specifications in a specifier); however, the tag sets are simply +considered in the order that the inst-pairs occur in the +specification's inst-list. + + Note also that the actual object that results from the instancing +(called an "instance object") may not be the same as the instantiator +from which it was derived. For some specifier types (such as integer +specifiers and boolean specifiers), the instantiator will be returned +directly as the instance object. For other types, however, this is not +the case. For example, for font specifiers, the instantiator is a +font-description string and the instance object is a font-instance +object, which describes how the font is displayed on a particular +device. A font-instance object encapsulates such things as the actual +font name used to display the font on that device (a font-description +string under X is usually a wildcard specification that may resolve to +different font names, with possibly different foundries, widths, etc., +on different devices), the extra properties of that font on that +device, etc. Furthermore, this conversion (called "instantiation") +might fail--a font or color might not exist on a particular device, for +example. -Face Properties ---------------- - - You can examine and modify the properties of an existing face with -the following functions. + +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. - The following symbols have predefined meanings: + +File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers -`foreground' - The foreground color of the face. +Specifier Types +=============== -`background' - The background color of the face. + 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 font used to display text covered by this face. - -`display-table' - The display table of the face. - -`background-pixmap' - The pixmap displayed in the background of the face. Only used by - faces on X devices. + 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. -`underline' - Underline all text covered by this face. - -`highlight' - Highlight all text covered by this face. Only used by faces on TTY - devices. - -`dim' - Dim all text covered by this face. Only used by faces on TTY - devices. - -`blinking' - Blink all text covered by this face. Only used by faces on TTY - devices. +`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. -`reverse' - Reverse the foreground and background colors. Only used by faces - on TTY devices. + - Function: font-specifier-p object + This function returns non-`nil' if OBJECT is a font specifier. -`doc-string' - Description of what the face's normal use is. NOTE: This is not a - specifier, unlike all the other built-in properties, and cannot - contain locale-specific values. + - Function: color-specifier-p object + This function returns non-`nil' if OBJECT is a color specifier. - - Function: set-face-property face property value &optional locale tag - how-to-add - This function changes a property of a FACE. - - For built-in properties, the actual value of the property is a - specifier and you cannot change this; but you can change the - specifications within the specifier, and that is what this - function will do. For user-defined properties, you can use this - function to either change the actual value of the property or, if - this value is a specifier, change the specifications within it. - - If PROPERTY is a built-in property, the specifications to be added - to this property can be supplied in many different ways: - - If VALUE is a simple instantiator (e.g. a string naming a - font or color) or a list of instantiators, then the - instantiator(s) will be added as a specification of the - property for the given LOCALE (which defaults to `global' if - omitted). - - If VALUE is a list of specifications (each of which is a cons - of a locale and a list of instantiators), then LOCALE must be - `nil' (it does not make sense to explicitly specify a locale - in this case), and specifications will be added as given. - - If VALUE is a specifier (as would be returned by - `face-property' if no LOCALE argument is given), then some or - all of the specifications in the specifier will be added to - the property. In this case, the function is really - equivalent to `copy-specifier' and LOCALE has the same - semantics (if it is a particular locale, the specification - for the locale will be copied; if a locale type, - specifications for all locales of that type will be copied; - if `nil' or `all', then all specifications will be copied). - - HOW-TO-ADD should be either `nil' or one of the symbols `prepend', - `append', `remove-tag-set-prepend', `remove-tag-set-append', - `remove-locale', `remove-locale-type', or `remove-all'. See - `copy-specifier' and `add-spec-to-specifier' for a description of - what each of these means. Most of the time, you do not need to - worry about this argument; the default behavior usually is fine. - - In general, it is OK to pass an instance object (e.g. as returned - by `face-property-instance') as an instantiator in place of an - actual instantiator. In such a case, the instantiator used to - create that instance object will be used (for example, if you set - a font-instance object as the value of the `font' property, then - the font name used to create that object will be used instead). - If some cases, however, doing this conversion does not make sense, - and this will be noted in the documentation for particular types - of instance objects. - - If PROPERTY is not a built-in property, then this function will - simply set its value if LOCALE is `nil'. However, if LOCALE is - given, then this function will attempt to add VALUE as the - instantiator for the given LOCALE, using `add-spec-to-specifier'. - If the value of the property is not a specifier, it will - automatically be converted into a `generic' specifier. - - - Function: face-property face property &optional locale - This function returns FACE's value of the given PROPERTY. - - If LOCALE is omitted, the FACE's actual value for PROPERTY will be - returned. For built-in properties, this will be a specifier - object of a type appropriate to the property (e.g. a font or color - specifier). For other properties, this could be anything. - - If LOCALE is supplied, then instead of returning the actual value, - the specification(s) for the given locale or locale type will be - returned. This will only work if the actual value of PROPERTY is - a specifier (this will always be the case for built-in properties, - but not or not may apply to user-defined properties). If the - actual value of PROPERTY is not a specifier, this value will - simply be returned regardless of LOCALE. - - The return value will be a list of instantiators (e.g. strings - specifying a font or color name), or a list of specifications, - each of which is a cons of a locale and a list of instantiators. - Specifically, if LOCALE is a particular locale (a buffer, window, - frame, device, or `global'), a list of instantiators for that - locale will be returned. Otherwise, if LOCALE is a locale type - (one of the symbols `buffer', `window', `frame', or `device'), the - specifications for all locales of that type will be returned. - Finally, if LOCALE is `all', the specifications for all locales of - all types will be returned. - - The specifications in a specifier determine what the value of - PROPERTY will be in a particular "domain" or set of circumstances, - which is typically a particular Emacs window along with the buffer - it contains and the frame and device it lies within. The value is - derived from the instantiator associated with the most specific - locale (in the order buffer, window, frame, device, and `global') - that matches the domain in question. In other words, given a - domain (i.e. an Emacs window, usually), the specifier for PROPERTY - will first be searched for a specification whose locale is the - buffer contained within that window; then for a specification - whose locale is the window itself; then for a specification whose - locale is the frame that the window is contained within; etc. The - first instantiator that is valid for the domain (usually this - means that the instantiator is recognized by the device [i.e. the - X server or TTY device] that the domain is on). The function - `face-property-instance' actually does all this, and is used to - determine how to display the face. - - - Function: face-property-instance face property &optional domain - default no-fallback - This function returns the instance of FACE's PROPERTY in the - specified DOMAIN. - - Under most circumstances, DOMAIN will be a particular window, and - the returned instance describes how the specified property - actually is displayed for that window and the particular buffer in - it. Note that this may not be the same as how the property - appears when the buffer is displayed in a different window or - frame, or how the property appears in the same window if you - switch to another buffer in that window; and in those cases, the - returned instance would be different. - - The returned instance will typically be a color-instance, - font-instance, or pixmap-instance object, and you can query it - using the appropriate object-specific functions. For example, you - could use `color-instance-rgb-components' to find out the RGB - (red, green, and blue) components of how the `background' property - of the `highlight' face is displayed in a particular window. The - results might be different from the results you would get for - another window (perhaps the user specified a different color for - the frame that window is on; or perhaps the same color was - specified but the window is on a different X server, and that X - server has different RGB values for the color from this one). - - DOMAIN defaults to the selected window if omitted. - - DOMAIN can be a frame or device, instead of a window. The value - returned for a such a domain is used in special circumstances when - a more specific domain does not apply; for example, a frame value - might be used for coloring a toolbar, which is conceptually - attached to a frame rather than a particular window. The value is - also useful in determining what the value would be for a - particular window within the frame or device, if it is not - overridden by a more specific specification. - - If PROPERTY does not name a built-in property, its value will - simply be returned unless it is a specifier object, in which case - it will be instanced using `specifier-instance'. - - Optional arguments DEFAULT and NO-FALLBACK are the same as in - `specifier-instance'. *Note Specifiers::. + - Function: image-specifier-p object + This function returns non-`nil' if OBJECT is an image specifier.  -File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces - -Face Convenience Functions --------------------------- - - - Function: set-face-foreground face color &optional locale tag - how-to-add - - Function: set-face-background face color &optional locale tag - how-to-add - These functions set the foreground (respectively, background) - color of face FACE to COLOR. The argument COLOR should be a - string (the name of a color) or a color object as returned by - `make-color' (*note Colors::). - - - Function: set-face-background-pixmap face pixmap &optional locale - tag how-to-add - This function sets the background pixmap of face FACE to PIXMAP. - The argument PIXMAP should be a string (the name of a bitmap or - pixmap file; the directories listed in the variable - `x-bitmap-file-path' will be searched) or a glyph object as - returned by `make-glyph' (*note Glyphs::). The argument may also - be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT - are the size in pixels, and DATA is a string, containing the raw - bits of the bitmap. - - - Function: set-face-font face font &optional locale tag how-to-add - This function sets the font of face FACE. The argument FONT - should be a string or a font object as returned by `make-font' - (*note Fonts::). - - - Function: set-face-underline-p face underline-p &optional locale tag +File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers + +Adding specifications to a Specifier +==================================== + + - 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 + + `prepend' + Put at the beginning of the current list of instantiators for + LOCALE. + + `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. + + `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 sets the underline property of face FACE. - - - Function: face-foreground face &optional locale - - Function: face-background face &optional locale - These functions return the foreground (respectively, background) - color specifier of face FACE. *Note Colors::. - - - Function: face-background-pixmap face &optional locale - This function return the background-pixmap glyph object of face - FACE. - - - Function: face-font face &optional locale - This function returns the font specifier of face FACE. (Note: - This is not the same as the function `face-font' in FSF Emacs.) - *Note Fonts::. - - - Function: face-font-name face &optional domain - This function returns the name of the font of face FACE, or `nil' - if it is unspecified. This is basically equivalent to `(font-name - (face-font FACE) DOMAIN)' except that it does not cause an error - if FACE's font is `nil'. (This function is named `face-font' in - FSF Emacs.) - - - Function: face-underline-p face &optional locale - This function returns the underline property of face FACE. + This function adds a "spec-list" (a list of specifications) to + SPECIFIER. The format of a spec-list is - - Function: face-foreground-instance face &optional domain - - Function: face-background-instance face &optional domain - These functions return the foreground (respectively, background) - color specifier of face FACE. *Note Colors::. + `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)' - - Function: face-background-pixmap-instance face &optional domain - This function return the background-pixmap glyph object of face - FACE. + where - - Function: face-font-instance face &optional domain - This function returns the font specifier of face FACE. *Note - Fonts::. + * LOCALE := a window, a buffer, a frame, a device, or `global' - -File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces - -Other Face Display Functions ----------------------------- - - - Function: invert-face face &optional locale - Swap the foreground and background colors of face FACE. If the - face doesn't specify both foreground and background, then its - foreground and background are set to the default background and - foreground. + * TAG-SET := an unordered list of zero or more TAGS, each of + which is a symbol - - Function: face-equal face1 face2 &optional domain - This returns `t' if the faces FACE1 and FACE2 will display in the - same way. DOMAIN is as in `face-property-instance'. + * TAG := a device class (*note Consoles and Devices::), a + device type, or a tag defined with `define-specifier-tag' - - Function: face-differs-from-default-p face &optional domain - This returns `t' if the face FACE displays differently from the - default face. DOMAIN is as in `face-property-instance'. + * INSTANTIATOR := format determined by the type of specifier - -File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects + 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. -Fonts -===== + 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'. - This section describes how to work with font specifier and font -instance objects, which encapsulate fonts in the window system. + In many circumstances, the higher-level function `set-specifier' is + more convenient and should be used instead. -* Menu: + - Special Form: 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. -* Font Specifiers:: Specifying how a font will appear. -* Font Instances:: What a font specifier gets instanced as. -* Font Instance Names:: The name of a font instance. -* Font Instance Size:: The size of a font instance. -* Font Instance Characteristics:: Display characteristics of font instances. -* Font Convenience Functions:: Convenience functions that automatically - instance and retrieve the properties - of a font specifier. + The format of SPECIFIER-LIST is - -File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts + ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...) -Font Specifiers ---------------- + 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'. - - Function: font-specifier-p object - This predicate returns `t' if OBJECT is a font specifier, and - `nil' otherwise. + 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. - -File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts + LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to + `nil'. The value of the last form in BODY is returned. -Font Instances --------------- + 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'. - - Function: font-instance-p object - This predicate returns `t' if OBJECT is a font instance, and `nil' - otherwise. + The following example removes the 3D modeline effect in the + currently selected window for the duration of a second: - - Function: make-font-instance name &optional device noerror - This function creates a new font-instance object of the specified - name. DEVICE specifies the device this object applies to and - defaults to the selected device. An error is signalled if the - font is unknown or cannot be allocated; however, if NOERROR is - non-`nil', `nil' is simply returned in this case. + (let-specifier ((modeline-shadow-thickness 0 (selected-window))) + (sit-for 1)) - The returned object is a normal, first-class lisp object. The way - you "deallocate" the font is the way you deallocate any other lisp - object: you drop all pointers to it and allow it to be garbage - collected. When these objects are GCed, the underlying X data is - deallocated as well. + - Function: set-specifier specifier value &optional locale tag-set + 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'. + + LOCALE, TAG-SET, and HOW-TO-ADD are the same as in + `add-spec-to-specifier'. + + 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.) + + 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: canonicalize-inst-pair inst-pair specifier-type &optional + noerror + This function canonicalizes the given INST-PAIR. + + SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST + will be used for. + + 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. + + If NOERROR is non-`nil', signal an error if the inst-pair is + invalid; otherwise return `t'. + + - 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'. + + - 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'.  -File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts - -Font Instance Names -------------------- - - - Function: list-fonts pattern &optional device - This function returns a list of font names matching the given - pattern. DEVICE specifies which device to search for names, and - defaults to the currently selected device. - - - Function: font-instance-name font-instance - This function returns the name used to allocate FONT-INSTANCE. - - - Function: font-instance-truename font-instance - This function returns the canonical name of the given font - instance. Font names are patterns which may match any number of - fonts, of which the first found is used. This returns an - unambiguous name for that font (but not necessarily its only - unambiguous name). +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. one of the symbols `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: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts - -Font Instance Size ------------------- - - - Function: x-font-size font - This function returns the nominal size of the given font. This is - done by parsing its name, so it's likely to lose. X fonts can be - specified (by the user) in either pixels or 10ths of points, and - this returns the first one it finds, so you have to decide which - units the returned value is measured in yourself ... - - - Function: x-find-larger-font font &optional device - This function loads a new, slightly larger version of the given - font (or font name). Returns the font if it succeeds, `nil' - otherwise. If scalable fonts are available, this returns a font - which is 1 point larger. Otherwise, it returns the next larger - version of this font that is defined. - - - Function: x-find-smaller-font font &optional device - This function loads a new, slightly smaller version of the given - font (or font name). Returns the font if it succeeds, `nil' - otherwise. If scalable fonts are available, this returns a font - which is 1 point smaller. Otherwise, it returns the next smaller - version of this font that is defined. +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 or 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: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts - -Font Instance Characteristics ------------------------------ - - - Function: font-instance-properties font - This function returns the properties (an alist or `nil') of - FONT-INSTANCE. - - - Function: x-make-font-bold font &optional device - Given an X font specification, this attempts to make a "bold" font. - If it fails, it returns `nil'. - - - Function: x-make-font-unbold font &optional device - Given an X font specification, this attempts to make a non-bold - font. If it fails, it returns `nil'. +File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Example, Prev: Specifier Tag Functions, Up: Specifiers - - Function: x-make-font-italic font &optional device - Given an X font specification, this attempts to make an "italic" - font. If it fails, it returns `nil'. +Functions for Instancing a Specifier +==================================== - - Function: x-make-font-unitalic font &optional device - Given an X font specification, this attempts to make a non-italic - font. If it fails, it returns `nil'. - - - Function: x-make-font-bold-italic font &optional device - Given an X font specification, this attempts to make a - "bold-italic" font. If it fails, it returns `nil'. + - 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: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts - -Font Convenience Functions --------------------------- - - - Function: font-name font &optional domain - This function returns the name of the FONT in the specified - DOMAIN, if any. FONT should be a font specifier object and DOMAIN - is normally a window and defaults to the selected window if - omitted. This is equivalent to using `specifier-instance' and - applying `font-instance-name' to the result. - - - Function: font-truename font &optional domain - This function returns the truename of the FONT in the specified - DOMAIN, if any. FONT should be a font specifier object and DOMAIN - is normally a window and defaults to the selected window if - omitted. This is equivalent to using `specifier-instance' and - applying `font-instance-truename' to the result. - - - Function: font-properties font &optional domain - This function returns the properties of the FONT in the specified - DOMAIN, if any. FONT should be a font specifier object and DOMAIN - is normally a window and defaults to the selected window if - omitted. This is equivalent to using `specifier-instance' and - applying `font-instance-properties' to the result. +File: lispref.info, Node: Specifier Example, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers + +Example of Specifier Usage +========================== + + 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.  -File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects - -Colors -====== - -* Menu: - -* Color Specifiers:: Specifying how a color will appear. -* Color Instances:: What a color specifier gets instanced as. -* Color Instance Properties:: Properties of color instances. -* Color Convenience Functions:: Convenience functions that automatically - instance and retrieve the properties - of a color specifier. +File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Example, Up: Specifiers + +Creating New Specifier Objects +============================== + + - 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 `make-generic-specifier', `make-integer-specifier', + `make-natnum-specifier', `make-boolean-specifier', + `make-color-specifier', `make-font-specifier', + `make-image-specifier', `make-face-boolean-specifier', and + `make-toolbar-specifier'. + + - 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: make-integer-specifier spec-list + Return a new `integer' specifier object with the given + specification list. SPEC-LIST can be a list of specifications + (each of which is a cons of a locale and a list of instantiators), + a single instantiator, or a list of instantiators. + + Valid instantiators for integer specifiers are integers. + + - Function: make-boolean-specifier spec-list + Return a new `boolean' specifier object with the given + specification list. SPEC-LIST can be a list of specifications + (each of which is a cons of a locale and a list of instantiators), + a single instantiator, or a list of instantiators. + + Valid instantiators for boolean specifiers are `t' and `nil'. + + - Function: make-natnum-specifier spec-list + Return a new `natnum' specifier object with the given specification + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. + + Valid instantiators for natnum specifiers are non-negative + integers. + + - Function: make-generic-specifier spec-list + Return a new `generic' specifier object with the given + specification list. SPEC-LIST can be a list of specifications + (each of which is a cons of a locale and a list of instantiators), + a single instantiator, or a list of instantiators. + + Valid instantiators for generic specifiers are all Lisp values. + They are returned back unchanged when a specifier is instantiated. + + - Function: make-display-table-specifier spec-list + Return a new `display-table' specifier object with the given spec + list. SPEC-LIST can be a list of specifications (each of which is + a cons of a locale and a list of instantiators), a single + instantiator, or a list of instantiators. + + Valid instantiators for display-table specifiers are described in + detail in the doc string for `current-display-table' (*note Active + Display Table::).  -File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors - -Color Specifiers ----------------- +File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers - - Function: color-specifier-p object - This function returns non-`nil' if OBJECT is a color specifier. +Functions for Checking the Validity of Specifier Components +=========================================================== - -File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors + - 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.) -Color Instances ---------------- + - 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.) - A "color-instance object" is an object describing the way a color -specifier is instanced in a particular domain. Functions such as -`face-background-instance' return a color-instance object. For example, + - 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.) - (face-background-instance 'default (next-window)) - => # + - 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'. - The color-instance object returned describes the way the background -color of the `default' face is displayed in the next window after the -selected one. + - Function: valid-specifier-tag-p tag + This function returns non-`nil' if TAG is a valid specifier tag. - - Function: color-instance-p object - This function returns non-`nil' if OBJECT is a color-instance. + - Function: valid-instantiator-p instantiator specifier-type + This function returns non-`nil' if INSTANTIATOR is valid for + SPECIFIER-TYPE. - -File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors + - Function: valid-inst-list-p inst-list type + This function returns non-`nil' if INST-LIST is valid for + specifier type TYPE. -Color Instance Properties -------------------------- + - Function: valid-spec-list-p spec-list type + This function returns non-`nil' if SPEC-LIST is valid for + specifier type TYPE. - - Function: color-instance-name color-instance - This function returns the name used to allocate COLOR-INSTANCE. + - Function: check-valid-instantiator instantiator specifier-type + This function signals an error if INSTANTIATOR is invalid for + SPECIFIER-TYPE. - - Function: color-instance-rgb-components color-instance - This function returns a three element list containing the red, - green, and blue color components of COLOR-INSTANCE. + - Function: check-valid-inst-list inst-list type + This function signals an error if INST-LIST is invalid for + specifier type TYPE. - (color-instance-rgb-components - (face-background-instance 'default (next-window))) - => (65535 58596 46517) + - Function: check-valid-spec-list spec-list type + This function signals an error if SPEC-LIST is invalid for + specifier type TYPE.  -File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors - -Color Convenience Functions ---------------------------- - - - Function: color-name color &optional domain - This function returns the name of the COLOR in the specified - DOMAIN, if any. COLOR should be a color specifier object and - DOMAIN is normally a window and defaults to the selected window if - omitted. This is equivalent to using `specifier-instance' and - applying `color-instance-name' to the result. - - - Function: color-rgb-components color &optional domain - This function returns the RGB components of the COLOR in the - specified DOMAIN, if any. COLOR should be a color specifier - object and DOMAIN is normally a window and defaults to the - selected window if omitted. This is equivalent to using - `specifier-instance' and applying `color-instance-rgb-components' - to the result. - - (color-rgb-components (face-background 'default (next-window))) - => (65535 58596 46517) +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: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top - -Glyphs -****** - - A "glyph" is an object that is used for pixmaps and images of all -sorts, as well as for things that "act" like pixmaps, such as -non-textual strings ("annotations") displayed in a buffer or in the -margins. It is used in begin-glyphs and end-glyphs attached to extents, -marginal and textual annotations, overlay arrows (`overlay-arrow-*' -variables), toolbar buttons, mouse pointers, frame icons, truncation and -continuation markers, and the like. (Basically, any place there is an -image or something that acts like an image, there will be a glyph object -representing it.) - - The actual image that is displayed (as opposed to its position or -clipping) is defined by an "image specifier" object contained within -the glyph. The separation between an image specifier object and a -glyph object is made because the glyph includes other properties than -just the actual image: e.g. the face it is displayed in (for text -images), the alignment of the image (when it is in a buffer), etc. - - - Function: glyphp object - This function returns `t' if OBJECT is a glyph. - -* Menu: +File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top -* Glyph Functions:: Functions for working with glyphs. -* Images:: Graphical images displayed in a frame. -* Glyph Types:: Each glyph has a particular type. -* Mouse Pointer:: Controlling the mouse pointer. -* Redisplay Glyphs:: Glyphs controlling various redisplay functions. -* Subwindows:: Inserting an externally-controlled subwindow - into a buffer. - - -File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs - -Glyph Functions -=============== +Faces and Window-System Objects +******************************* * Menu: -* Creating Glyphs:: Creating new glyphs. -* Glyph Properties:: Accessing and modifying a glyph's properties. -* Glyph Convenience Functions:: - Convenience functions for accessing particular - properties of a glyph. -* Glyph Dimensions:: Determining the height, width, etc. of a glyph. - - -File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions - -Creating Glyphs ---------------- - - - Function: make-glyph &optional spec-list type - This function creates a new glyph object of type TYPE. - - SPEC-LIST is used to initialize the glyph's image. It is - typically an image instantiator (a string or a vector; *Note Image - Specifiers::), but can also be a list of such instantiators (each - one in turn is tried until an image is successfully produced), a - cons of a locale (frame, buffer, etc.) and an instantiator, a list - of such conses, or any other form accepted by - `canonicalize-spec-list'. *Note Specifiers::, for more - information about specifiers. - - TYPE specifies the type of the glyph, which specifies in which - contexts the glyph can be used, and controls the allowable image - types into which the glyph's image can be instantiated. TYPE - should be one of `buffer' (used for glyphs in an extent, the - modeline, the toolbar, or elsewhere in a buffer), `pointer' (used - for the mouse-pointer), or `icon' (used for a frame's icon), and - defaults to `buffer'. *Note Glyph Types::. - - - Function: make-glyph-internal &optional type - This function creates a new, uninitialized glyph of type TYPE. - - - Function: make-pointer-glyph &optional spec-list - This function is equivalent to calling `make-glyph' with a TYPE of - `pointer'. - - - Function: make-icon-glyph &optional spec-list - This function is equivalent to calling `make-glyph' with a TYPE of - `icon'. +* Faces:: Controlling the way text looks. +* Fonts:: Controlling the typeface of text. +* Colors:: Controlling the color of text and pixmaps.  -File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions +File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects -Glyph Properties ----------------- - - Each glyph has a list of properties, which control all of the -aspects of the glyph's appearance. The following symbols have -predefined meanings: - -`image' - The image used to display the glyph. - -`baseline' - Percent above baseline that glyph is to be displayed. Only for - glyphs displayed inside of a buffer. - -`contrib-p' - Whether the glyph contributes to the height of the line it's on. - Only for glyphs displayed inside of a buffer. - -`face' - Face of this glyph (_not_ a specifier). - - - Function: set-glyph-property glyph property value &optional locale - tag-set how-to-add - This function changes a property of a GLYPH. - - For built-in properties, the actual value of the property is a - specifier and you cannot change this; but you can change the - specifications within the specifier, and that is what this - function will do. For user-defined properties, you can use this - function to either change the actual value of the property or, if - this value is a specifier, change the specifications within it. - - If PROPERTY is a built-in property, the specifications to be added - to this property can be supplied in many different ways: - - * If VALUE is a simple instantiator (e.g. a string naming a - pixmap filename) or a list of instantiators, then the - instantiator(s) will be added as a specification of the - property for the given LOCALE (which defaults to `global' if - omitted). - - * If VALUE is a list of specifications (each of which is a cons - of a locale and a list of instantiators), then LOCALE must be - `nil' (it does not make sense to explicitly specify a locale - in this case), and specifications will be added as given. - - * If VALUE is a specifier (as would be returned by - `glyph-property' if no LOCALE argument is given), then some - or all of the specifications in the specifier will be added - to the property. In this case, the function is really - equivalent to `copy-specifier' and LOCALE has the same - semantics (if it is a particular locale, the specification - for the locale will be copied; if a locale type, - specifications for all locales of that type will be copied; - if `nil' or `all', then all specifications will be copied). - - HOW-TO-ADD should be either `nil' or one of the symbols `prepend', - `append', `remove-tag-set-prepend', `remove-tag-set-append', - `remove-locale', `remove-locale-type', or `remove-all'. See - `copy-specifier' and `add-spec-to-specifier' for a description of - what each of these means. Most of the time, you do not need to - worry about this argument; the default behavior usually is fine. - - In general, it is OK to pass an instance object (e.g. as returned - by `glyph-property-instance') as an instantiator in place of an - actual instantiator. In such a case, the instantiator used to - create that instance object will be used (for example, if you set - a font-instance object as the value of the `font' property, then - the font name used to create that object will be used instead). - If some cases, however, doing this conversion does not make sense, - and this will be noted in the documentation for particular types - of instance objects. - - If PROPERTY is not a built-in property, then this function will - simply set its value if LOCALE is `nil'. However, if LOCALE is - given, then this function will attempt to add VALUE as the - instantiator for the given LOCALE, using `add-spec-to-specifier'. - If the value of the property is not a specifier, it will - automatically be converted into a `generic' specifier. - - - Function: glyph-property glyph property &optional locale - This function returns GLYPH's value of the given PROPERTY. - - If LOCALE is omitted, the GLYPH's actual value for PROPERTY will - be returned. For built-in properties, this will be a specifier - object of a type appropriate to the property (e.g. a font or color - specifier). For other properties, this could be anything. - - If LOCALE is supplied, then instead of returning the actual value, - the specification(s) for the given locale or locale type will be - returned. This will only work if the actual value of PROPERTY is - a specifier (this will always be the case for built-in properties, - but may or may not apply to user-defined properties). If the - actual value of PROPERTY is not a specifier, this value will - simply be returned regardless of LOCALE. - - The return value will be a list of instantiators (e.g. vectors - specifying pixmap data), or a list of specifications, each of - which is a cons of a locale and a list of instantiators. - Specifically, if LOCALE is a particular locale (a buffer, window, - frame, device, or `global'), a list of instantiators for that - locale will be returned. Otherwise, if LOCALE is a locale type - (one of the symbols `buffer', `window', `frame', or `device'), the - specifications for all locales of that type will be returned. - Finally, if LOCALE is `all', the specifications for all locales of - all types will be returned. - - The specifications in a specifier determine what the value of - PROPERTY will be in a particular "domain" or set of circumstances, - which is typically a particular Emacs window along with the buffer - it contains and the frame and device it lies within. The value is - derived from the instantiator associated with the most specific - locale (in the order buffer, window, frame, device, and `global') - that matches the domain in question. In other words, given a - domain (i.e. an Emacs window, usually), the specifier for PROPERTY - will first be searched for a specification whose locale is the - buffer contained within that window; then for a specification - whose locale is the window itself; then for a specification whose - locale is the frame that the window is contained within; etc. The - first instantiator that is valid for the domain (usually this - means that the instantiator is recognized by the device [i.e. the - X server or TTY device] that the domain is on). The function - `glyph-property-instance' actually does all this, and is used to - determine how to display the glyph. - - - Function: glyph-property-instance glyph property &optional domain - default no-fallback - This function returns the instance of GLYPH's PROPERTY in the - specified DOMAIN. - - Under most circumstances, DOMAIN will be a particular window, and - the returned instance describes how the specified property - actually is displayed for that window and the particular buffer in - it. Note that this may not be the same as how the property - appears when the buffer is displayed in a different window or - frame, or how the property appears in the same window if you - switch to another buffer in that window; and in those cases, the - returned instance would be different. - - The returned instance is an image-instance object, and you can - query it using the appropriate image instance functions. For - example, you could use `image-instance-depth' to find out the - depth (number of color planes) of a pixmap displayed in a - particular window. The results might be different from the - results you would get for another window (perhaps the user - specified a different image for the frame that window is on; or - perhaps the same image was specified but the window is on a - different X server, and that X server has different color - capabilities from this one). - - DOMAIN defaults to the selected window if omitted. - - DOMAIN can be a frame or device, instead of a window. The value - returned for such a domain is used in special circumstances when a - more specific domain does not apply; for example, a frame value - might be used for coloring a toolbar, which is conceptually - attached to a frame rather than a particular window. The value is - also useful in determining what the value would be for a - particular window within the frame or device, if it is not - overridden by a more specific specification. - - If PROPERTY does not name a built-in property, its value will - simply be returned unless it is a specifier object, in which case - it will be instanced using `specifier-instance'. - - Optional arguments DEFAULT and NO-FALLBACK are the same as in - `specifier-instance'. *Note Specifiers::. - - - Function: remove-glyph-property glyph property &optional locale - tag-set exact-p - This function removes a property from a glyph. For built-in - properties, this is analogous to `remove-specifier'. *Note - remove-specifier-p: Specifiers, for the meaning of the LOCALE, - TAG-SET, and EXACT-P arguments. - - -File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions - -Glyph Convenience Functions ---------------------------- - - The following functions are provided for working with specific -properties of a glyph. Note that these are exactly like calling the -general functions described above and passing in the appropriate value -for PROPERTY. - - Remember that if you want to determine the "value" of a specific -glyph property, you probably want to use the `*-instance' functions. -For example, to determine whether a glyph contributes to its line -height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The -latter will return a boolean specifier or a list of specifications, and -you probably aren't concerned with these.) - - - Function: glyph-image glyph &optional locale - This function is equivalent to calling `glyph-property' with a - property of `image'. The return value will be an image specifier - if LOCALE is `nil' or omitted; otherwise, it will be a - specification or list of specifications. - - - Function: set-glyph-image glyph spec &optional locale tag-set - how-to-add - This function is equivalent to calling `set-glyph-property' with a - property of `image'. - - - Function: glyph-image-instance glyph &optional domain default - no-fallback - This function returns the instance of GLYPH's image in the given - DOMAIN, and is equivalent to calling `glyph-property-instance' - with a property of `image'. The return value will be an image - instance. - - Normally DOMAIN will be a window or `nil' (meaning the selected - window), and an instance object describing how the image appears - in that particular window and buffer will be returned. - - - Function: glyph-contrib-p glyph &optional locale - This function is equivalent to calling `glyph-property' with a - property of `contrib-p'. The return value will be a boolean - specifier if LOCALE is `nil' or omitted; otherwise, it will be a - specification or list of specifications. - - - Function: set-glyph-contrib-p glyph spec &optional locale tag-set - how-to-add - This function is equivalent to calling `set-glyph-property' with a - property of `contrib-p'. - - - Function: glyph-contrib-p-instance glyph &optional domain default - no-fallback - This function returns whether the glyph contributes to its line - height in the given DOMAIN, and is equivalent to calling - `glyph-property-instance' with a property of `contrib-p'. The - return value will be either `nil' or `t'. (Normally DOMAIN will be - a window or `nil', meaning the selected window.) - - - Function: glyph-baseline glyph &optional locale - This function is equivalent to calling `glyph-property' with a - property of `baseline'. The return value will be a specifier if - LOCALE is `nil' or omitted; otherwise, it will be a specification - or list of specifications. - - - Function: set-glyph-baseline glyph spec &optional locale tag-set - how-to-add - This function is equivalent to calling `set-glyph-property' with a - property of `baseline'. - - - Function: glyph-baseline-instance glyph &optional domain default - no-fallback - This function returns the instance of GLYPH's baseline value in - the given DOMAIN, and is equivalent to calling - `glyph-property-instance' with a property of `baseline'. The - return value will be an integer or `nil'. - - Normally DOMAIN will be a window or `nil' (meaning the selected - window), and an instance object describing the baseline value - appears in that particular window and buffer will be returned. - - - Function: glyph-face glyph - This function returns the face of GLYPH. (Remember, this is not a - specifier, but a simple property.) - - - Function: set-glyph-face glyph face - This function changes the face of GLYPH to FACE. - - -File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions - -Glyph Dimensions ----------------- - - - Function: glyph-width glyph &optional window - This function returns the width of GLYPH on WINDOW. This may not - be exact as it does not take into account all of the context that - redisplay will. - - - Function: glyph-ascent glyph &optional window - This function returns the ascent value of GLYPH on WINDOW. This - may not be exact as it does not take into account all of the - context that redisplay will. - - - Function: glyph-descent glyph &optional window - This function returns the descent value of GLYPH on WINDOW. This - may not be exact as it does not take into account all of the - context that redisplay will. - - - Function: glyph-height glyph &optional window - This function returns the height of GLYPH on WINDOW. (This is - equivalent to the sum of the ascent and descent values.) This may - not be exact as it does not take into account all of the context - that redisplay will. - - -File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs +Faces +===== -Images -====== + 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. * Menu: -* Image Specifiers:: Specifying how an image will appear. -* Image Instantiator Conversion:: - Conversion is applied to image instantiators - at the time they are added to an - image specifier or at the time they - are passed to `make-image-instance'. -* Image Instances:: What an image specifier gets instanced as. +* 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.