-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
Foundation instead of in the original English.
\1f
+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.
+
+\1f
+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::).
+
+\1f
+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::.
+
+\1f
+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::.
+
+\1f
+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'.
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
+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).
+
+\1f
+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.
+
+\1f
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.
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.
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
pointer glyph. Instead, you probably want to be calling
`set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.
-
projects / chise / xemacs-chise.git / blobdiff