X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-36;h=a8f035c097115352ab6756b415c46b036db76510;hb=98769b42a33fd8236341ac4175165b2dab7ceae4;hp=c9d855f7a2c5bfafa6c666c8f5d18b2691002285;hpb=e5cd8d4ed475af329be5df9627a53edd584fd3de;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-36 b/info/lispref.info-36 index c9d855f..a8f035c 100644 --- a/info/lispref.info-36 +++ b/info/lispref.info-36 @@ -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,12 +50,530 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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: 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 `t' if OBJECT is a face, else `nil'. + + - Function: copy-face old-face new-name &optional locale tag-set + exact-p 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, TAG-SET, EXACT-P 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::). + + +File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces + +Face Properties +--------------- + + You can examine and modify the properties of an existing face with +the following functions. + + The following symbols have predefined meanings: + +`foreground' + The foreground color of the face. + +`background' + The background color of the face. + +`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. + +`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. + +`reverse' + Reverse the foreground and background colors. Only used by faces + on TTY devices. + +`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: set-face-property face property value &optional locale + tag-set 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: remove-face-property face property &optional locale + tag-set exact-p + This function removes a property of a FACE. + + For built-in properties, this is analogous to `remove-specifier'. + For more information, *Note Other Specification Functions::. + + When PROPERTY is not a built-in property, this function will just + remove its value if LOCALE is `nil' or `all'. However, if LOCALE + is other than that, this function will attempt to remove VALUE as + the instantiator for the given LOCALE with `remove-specifier'. If + the value of the property is not a specifier, it will be converted + into a `generic' specifier automatically. + + - Function: face-property face property &optional locale tag-set + exact-p + 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::. + + +File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces + +Face Convenience Functions +-------------------------- + + - Command: set-face-foreground face color &optional locale tag-set + how-to-add + - Command: set-face-background face color &optional locale tag-set + 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::). + + - Command: set-face-background-pixmap face pixmap &optional locale + tag-set 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. + + - Command: set-face-font face font &optional locale tag-set 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::). + + - Command: set-face-underline-p face underline-p &optional locale + tag-set how-to-add + This function sets the underline property of face FACE. + + - Function: face-foreground face &optional locale tag-set exact-p + - Function: face-background face &optional locale tag-set exact-p + These functions return the foreground (respectively, background) + color specifier of face FACE. *Note Colors::. + + - Function: face-background-pixmap face &optional locale tag-set + exact-p + This function return the background-pixmap glyph object of face + FACE. + + - Function: face-font face &optional locale tag-set exact-p + 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. + + - 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::. + + - Function: face-background-pixmap-instance face &optional domain + This function return the background-pixmap glyph object of face + FACE. + + - Function: face-font-instance face &optional domain + This function returns the font specifier of face FACE. *Note + Fonts::. + + +File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces + +Other Face Display Functions +---------------------------- + + - Command: 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. + + - 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'. + + - 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'. + + +File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects + +Fonts +===== + + This section describes how to work with font specifier and font +instance objects, which encapsulate fonts in the window system. + +* Menu: + +* 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. + + +File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts + +Font Specifiers +--------------- + + - Function: font-specifier-p object + This predicate returns `t' if OBJECT is a font specifier, and + `nil' otherwise. + + - Function: make-font-specifier spec-list + Return a new `font' 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. *Note Specifiers::, for + more information about specifiers. + + Valid instantiators for font specifiers are: + + * A string naming a font (e.g. under X this might be + "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a + 14-point upright medium-weight Courier font). + + * A font instance (use that instance directly if the device + matches, or use the string that generated it). + + * A vector of no elements (only on TTY's; this means to set no + font at all, thus using the "natural" font of the terminal's + text). + + * A vector of one element (a face to inherit from). + + +File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts + +Font Instances +-------------- + + - Function: font-instance-p object + This predicate returns `t' if OBJECT is a font instance, and `nil' + otherwise. + + - 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. + + 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. + + +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: 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: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts Font Instance Characteristics ----------------------------- - - Function: font-instance-properties font + - Function: font-instance-properties font-instance This function returns the properties (an alist or `nil') of FONT-INSTANCE. @@ -172,7 +690,7 @@ Color Specifiers inherit from (if omitted, defaults to the same property that this face-boolean specifier is used for; if this specifier is not part of a face, the instantiator would not be valid), and - optionally a value which, if non-nil, means to invert the + optionally a value which, if non-`nil', means to invert the sense of the inherited property. @@ -429,7 +947,7 @@ Creating Glyphs pointer used over the modeline, etc. Do an apropos over `*-pointer-glyph' to find all of them. (Note also that you can temporarily set the mouse pointer to some specific shape - by using `set-frame-pointer', which takes an image instace, + by using `set-frame-pointer', which takes an image instance, as obtained from calling `glyph-image-instance' on a glyph of type `pointer' - either one of the above-mentioned variables or one you created yourself. (See below for what it means to @@ -511,312 +1029,3 @@ Creating Glyphs pointer glyph. Instead, you probably want to be calling `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'. - -File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions - -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 - -Images -====== - -* 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. -