-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: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
-
-Color Instances
----------------
-
- 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,
-
- (face-background-instance 'default (next-window))
- => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
-
- 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: color-instance-p object
- This function returns non-`nil' if OBJECT is a color-instance.
+File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces
-\1f
-File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
-
-Color Instance Properties
+Merging Faces for Display
-------------------------
- - Function: color-instance-name color-instance
- This function returns the name used to allocate COLOR-INSTANCE.
-
- - 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.
-
- (color-instance-rgb-components
- (face-background-instance 'default (next-window)))
- => (65535 58596 46517)
+ 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: 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: 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: 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: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
-* 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.
-
-\1f
-File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
-
-Glyph Functions
-===============
-
-* 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.
-
-\1f
-File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
-
-Creating Glyphs
+Face Properties
---------------
- - Function: make-glyph &optional spec-list type
- This function creates a new glyph object of type TYPE.
+ You can examine and modify the properties of an existing face with
+the following functions.
- 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.
+ The following symbols have predefined meanings:
- 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::.
+`foreground'
+ The foreground color of the face.
- - Function: make-glyph-internal &optional type
- This function creates a new, uninitialized glyph of type TYPE.
+`background'
+ The background color of the face.
- - Function: make-pointer-glyph &optional spec-list
- This function is equivalent to calling `make-glyph' with a TYPE of
- `pointer'.
+`font'
+ The font used to display text covered by this face.
- - Function: make-icon-glyph &optional spec-list
- This function is equivalent to calling `make-glyph' with a TYPE of
- `icon'.
+`display-table'
+ The display table of the face.
-\1f
-File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
+`background-pixmap'
+ The pixmap displayed in the background of the face. Only used by
+ faces on X devices.
-Glyph Properties
-----------------
+`underline'
+ Underline all text covered by this face.
- Each glyph has a list of properties, which control all of the
-aspects of the glyph's appearance. The following symbols have
-predefined meanings:
+`highlight'
+ Highlight all text covered by this face. Only used by faces on TTY
+ devices.
-`image'
- The image used to display the glyph.
+`dim'
+ Dim all text covered by this face. Only used by faces on TTY
+ devices.
-`baseline'
- Percent above baseline that glyph is to be displayed. Only for
- glyphs displayed inside of a buffer.
+`blinking'
+ Blink all text covered by this face. Only used by faces on TTY
+ devices.
-`contrib-p'
- Whether the glyph contributes to the height of the line it's on.
- Only for glyphs displayed inside of a buffer.
+`reverse'
+ Reverse the foreground and background colors. Only used by faces
+ on TTY devices.
-`face'
- Face of this glyph (_not_ a 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: set-glyph-property glyph property value &optional locale
+ - Function: set-face-property face property value &optional locale
tag-set how-to-add
- This function changes a property of a GLYPH.
+ 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
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
+ 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
+ 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
+ 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,
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
+ 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
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.
+ - 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.
- If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
- be returned. For built-in properties, this will be a specifier
+ - 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.
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
+ 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. vectors
- specifying pixmap data), or a list of specifications, each of
- which is a cons of a locale and a list of instantiators.
+ 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
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.
+ `face-property-instance' actually does all this, and is used to
+ determine how to display the face.
- - Function: glyph-property-instance glyph property &optional domain
+ - Function: face-property-instance face property &optional domain
default no-fallback
- This function returns the instance of GLYPH's PROPERTY in the
+ This function returns the instance of FACE's PROPERTY in the
specified DOMAIN.
Under most circumstances, DOMAIN will be a particular window, and
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).
+ 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 such a domain is used in special circumstances when a
- more specific domain does not apply; for example, a frame 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
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
+File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
-Glyph Convenience Functions
----------------------------
+Face 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
+ - Command: set-face-foreground face color &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
+ - Command: set-face-background face color &optional locale tag-set
how-to-add
- This function is equivalent to calling `set-glyph-property' with a
- property of `baseline'.
+ 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: 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'.
+ - 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.
- 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: 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: glyph-face glyph
- This function returns the face of GLYPH. (Remember, this is not a
- specifier, but a simple property.)
+ - Function: face-background-pixmap face &optional locale tag-set
+ exact-p
+ This function return the background-pixmap glyph object of face
+ FACE.
- - Function: set-glyph-face glyph face
- This function changes the face of GLYPH to 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.)
-\1f
-File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
+ *Note Fonts::.
-Glyph Dimensions
-----------------
+ - 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: 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: face-underline-p face &optional locale
+ This function returns the underline property of face FACE.
- - 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: 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: 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: face-background-pixmap-instance face &optional domain
+ This function return the background-pixmap glyph object of face
+ FACE.
- - 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.
+ - Function: face-font-instance face &optional domain
+ This function returns the font specifier of face FACE. *Note
+ Fonts::.
\1f
-File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
+File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
-Images
-======
+Other Face Display Functions
+----------------------------
-* Menu:
+ - 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.
-* 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.
+ - 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: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
+File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
-Image Specifiers
-----------------
+Fonts
+=====
- An image specifier is used to describe the actual image of a glyph.
-It works like other specifiers (*note Specifiers::), in that it contains
-a number of specifications describing how the image should appear in a
-variety of circumstances. These specifications are called "image
-instantiators". When XEmacs wants to display the image, it instantiates
-the image into an "image instance". Image instances are their own
-primitive object type (similar to font instances and color instances),
-describing how the image appears in a particular domain. (On the other
-hand, image instantiators, which are just descriptions of how the image
-should appear, are represented using strings or vectors.)
-
- - Function: image-specifier-p object
- This function returns non-`nil' if OBJECT is an image specifier.
- Usually, an image specifier results from calling `glyph-image' on
- a glyph.
-
- - Function: make-image-specifier spec-list
- This function creates a new image specifier object and initializes
- it according to SPEC-LIST. It is unlikely that you will ever want
- to do this, but this function is provided for completeness and for
- experimentation purposes. *Note Specifiers::.
-
- Image instantiators come in many formats: `xbm', `xpm', `gif',
-`jpeg', etc. This describes the format of the data describing the
-image. The resulting image instances also come in many
-types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This
-refers to the behavior of the image and the sorts of places it can
-appear. (For example, a color-pixmap image has fixed colors specified
-for it, while a mono-pixmap image comes in two unspecified shades
-"foreground" and "background" that are determined from the face of the
-glyph or surrounding text; a text image appears as a string of text and
-has an unspecified foreground, background, and font; a pointer image
-behaves like a mono-pixmap image but can only be used as a mouse
-pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
-is important to keep the distinction between image instantiator format
-and image instance type in mind. Typically, a given image instantiator
-format can result in many different image instance types (for example,
-`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
-whereas `cursor-font' can be instanced only as `pointer'), and a
-particular image instance type can be generated by many different image
-instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
-`gif', `jpeg', etc.).
-
- *Note Image Instances::, for a more detailed discussion of image
-instance types.
-
- An image instantiator should be a string or a vector of the form
-
- `[FORMAT :KEYWORD VALUE ...]'
-
- i.e. a format symbol followed by zero or more alternating
-keyword-value pairs. The "format" field should be a symbol, one of
-
-`nothing'
- Don't display anything; no keywords are valid for this. Can only
- be instanced as `nothing'.
-
-`string'
- Display this image as a text string. Can only be instanced as
- `text', although support for instancing as `mono-pixmap' should be
- added.
-
-`formatted-string'
- Display this image as a text string with replaceable fields,
- similar to a modeline format string; not currently implemented.
-
-`xbm'
- An X bitmap; only if X support was compiled into this XEmacs. Can
- be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
-
-`xpm'
- An XPM pixmap; only if XPM support was compiled into this XEmacs.
- Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
- XPM is an add-on library for X that was designed to rectify the
- shortcomings of the XBM format. Most implementations of X include
- the XPM library as a standard part. If your vendor does not, it
- is highly recommended that you download it and install it. You
- can get it from the standard XEmacs FTP site, among other places.
-
-`xface'
- An X-Face bitmap, used to encode people's faces in e-mail messages;
- only if X-Face support was compiled into this XEmacs. Can be
- instanced as `mono-pixmap', `color-pixmap', or `pointer'.
-
-`gif'
- A GIF87 or GIF89 image; only if GIF support was compiled into this
- XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
- includes GIF decoding functions as a standard part of it, so if
- you have X support, you will normally have GIF support, unless you
- explicitly disable it at configure time.
-
-`jpeg'
- A JPEG-format image; only if JPEG support was compiled into this
- XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
- libraries present on your system when XEmacs is built, XEmacs will
- automatically detect this and use them, unless you explicitly
- disable it at configure time.
-
-`png'
- A PNG/GIF24 image; only if PNG support was compiled into this
- XEmacs. Can be instanced as `color-pixmap'.
-
-`tiff'
- A TIFF-format image; only if TIFF support was compiled into this
- XEmacs.
-
-`cursor-font'
- One of the standard cursor-font names, such as `watch' or
- `right_ptr' under X. Under X, this is, more specifically, any of
- the standard cursor names from appendix B of the Xlib manual [also
- known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
- other window systems, the valid names will be specific to the type
- of window system. Can only be instanced as `pointer'.
+ This section describes how to work with font specifier and font
+instance objects, which encapsulate fonts in the window system.
-`font'
- A glyph from a font; i.e. the name of a font, and glyph index into
- it of the form `FONT fontname index [[mask-font] mask-index]'.
- Only if X support was compiled into this XEmacs. Currently can
- only be instanced as `pointer', although this should probably be
- fixed.
-
-`subwindow'
- An embedded X window; not currently implemented.
-
-`autodetect'
- XEmacs tries to guess what format the data is in. If X support
- exists, the data string will be checked to see if it names a
- filename. If so, and this filename contains XBM or XPM data, the
- appropriate sort of pixmap or pointer will be created. [This
- includes picking up any specified hotspot or associated mask
- file.] Otherwise, if `pointer' is one of the allowable
- image-instance types and the string names a valid cursor-font
- name, the image will be created as a pointer. Otherwise, the
- image will be displayed as text. If no X support exists, the
- image will always be displayed as text.
-
- The valid keywords are:
-
-`:data'
- Inline data. For most formats above, this should be a string. For
- XBM images, this should be a list of three elements: width,
- height, and a string of bit data. This keyword is not valid for
- instantiator format `nothing'.
-
-`:file'
- Data is contained in a file. The value is the name of this file.
- If both `:data' and `:file' are specified, the image is created
- from what is specified in `:data' and the string in `:file'
- becomes the value of the `image-instance-file-name' function when
- applied to the resulting image-instance. This keyword is not
- valid for instantiator formats `nothing', `string',
- `formatted-string', `cursor-font', `font', and `autodetect'.
-
-`:foreground'
-`:background'
- For `xbm', `xface', `cursor-font', and `font'. These keywords
- allow you to explicitly specify foreground and background colors.
- The argument should be anything acceptable to
- `make-color-instance'. This will cause what would be a
- `mono-pixmap' to instead be colorized as a two-color color-pixmap,
- and specifies the foreground and/or background colors for a pointer
- instead of black and white.
-
-`:mask-data'
- For `xbm' and `xface'. This specifies a mask to be used with the
- bitmap. The format is a list of width, height, and bits, like for
- `:data'.
-
-`:mask-file'
- For `xbm' and `xface'. This specifies a file containing the mask
- data. If neither a mask file nor inline mask data is given for an
- XBM image, and the XBM image comes from a file, XEmacs will look
- for a mask file with the same name as the image file but with
- `Mask' or `msk' appended. For example, if you specify the XBM file
- `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
- associated mask file `left_ptrmsk' will automatically be picked up.
-
-`:hotspot-x'
-`:hotspot-y'
- For `xbm' and `xface'. These keywords specify a hotspot if the
- image is instantiated as a `pointer'. Note that if the XBM image
- file specifies a hotspot, it will automatically be picked up if no
- explicit hotspot is given.
-
-`:color-symbols'
- Only for `xpm'. This specifies an alist that maps strings that
- specify symbolic color names to the actual color to be used for
- that symbolic color (in the form of a string or a color-specifier
- object). If this is not specified, the contents of
- `xpm-color-symbols' are used to generate the alist.
-
- If instead of a vector, the instantiator is a string, it will be
-converted into a vector by looking it up according to the specs in the
-`console-type-image-conversion-list' for the console type of the domain
-(usually a window; sometimes a frame or device) over which the image is
-being instantiated.
-
- If the instantiator specifies data from a file, the data will be
-read in at the time that the instantiator is added to the image
-specifier (which may be well before the image is actually displayed),
-and the instantiator will be converted into one of the inline-data
-forms, with the filename retained using a `:file' keyword. This
-implies that the file must exist when the instantiator is added to the
-image, but does not need to exist at any other time (e.g. it may safely
-be a temporary file).
-
- - Function: valid-image-instantiator-format-p format
- This function returns non-`nil' if FORMAT is a valid image
- instantiator format. Note that the return value for many formats
- listed above depends on whether XEmacs was compiled with support
- for that format.
-
- - Function: image-instantiator-format-list
- This function return a list of valid image-instantiator formats.
-
- - Variable: xpm-color-symbols
- This variable holds definitions of logical color-names used when
- reading XPM files. Elements of this list should be of the form
- `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
- string, which is the name of the color to define; the
- FORM-TO-EVALUATE should evaluate to a color specifier object, or a
- string to be passed to `make-color-instance' (*note Colors::). If
- a loaded XPM file references a symbolic color called COLOR-NAME,
- it will display as the computed color instead.
-
- The default value of this variable defines the logical color names
- `"foreground"' and `"background"' to be the colors of the
- `default' face.
-
- - Variable: x-bitmap-file-path
- A list of the directories in which X bitmap files may be found.
- If nil, this is initialized from the `"*bitmapFilePath"' resource.
- This is used by the `make-image-instance' function (however, note
- that if the environment variable `XBMLANGPATH' is set, it is
- consulted first).
+* 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: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
+File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
-Image Instantiator Conversion
------------------------------
+Font Specifiers
+---------------
- - Function: set-console-type-image-conversion-list console-type list
- This function sets the image-conversion-list for consoles of the
- given CONSOLE-TYPE. The image-conversion-list specifies how image
- instantiators that are strings should be interpreted. Each
- element of the list should be a list of two elements (a regular
- expression string and a vector) or a list of three elements (the
- preceding two plus an integer index into the vector). The string
- is converted to the vector associated with the first matching
- regular expression. If a vector index is specified, the string
- itself is substituted into that position in the vector.
-
- Note: The conversion above is applied when the image instantiator
- is added to an image specifier, not when the specifier is actually
- instantiated. Therefore, changing the image-conversion-list only
- affects newly-added instantiators. Existing instantiators in
- glyphs and image specifiers will not be affected.
-
- - Function: console-type-image-conversion-list console-type
- This function returns the image-conversion-list for consoles of
- the given CONSOLE-TYPE.
+ - Function: font-specifier-p object
+ This predicate returns `t' if OBJECT is a font specifier, and
+ `nil' otherwise.
-\1f
-File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
+ - 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.
-Image Instances
----------------
+ Valid instantiators for font specifiers are:
- Image-instance objects encapsulate the way a particular image
-(pixmap, etc.) is displayed on a particular device.
+ * 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).
- In most circumstances, you do not need to directly create image
-instances; use a glyph instead. However, it may occasionally be useful
-to explicitly create image instances, if you want more control over the
-instantiation process.
+ * A font instance (use that instance directly if the device
+ matches, or use the string that generated it).
- - Function: image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance.
+ * 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).
-* Menu:
+ * 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.
-* Image Instance Types:: Each image instances has a particular type.
-* Image Instance Functions:: Functions for working with image instances.
+ 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: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
+File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
-Image Instance Types
-....................
+Font Instance Names
+-------------------
- Image instances come in a number of different types. The type of an
-image instance specifies the nature of the image: Whether it is a text
-string, a mono pixmap, a color pixmap, etc.
+ - 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.
- The valid image instance types are
+ - Function: font-instance-name font-instance
+ This function returns the name used to allocate FONT-INSTANCE.
-`nothing'
- Nothing is displayed.
+ - 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).
-`text'
- Displayed as text. The foreground and background colors and the
- font of the text are specified independent of the pixmap.
- Typically these attributes will come from the face of the
- surrounding text, unless a face is specified for the glyph in
- which the image appears.
+\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.
-`mono-pixmap'
- Displayed as a mono pixmap (a pixmap with only two colors where the
- foreground and background can be specified independent of the
- pixmap; typically the pixmap assumes the foreground and background
- colors of the text around it, unless a face is specified for the
- glyph in which the image appears).
+\1f
+File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
-`color-pixmap'
- Displayed as a color pixmap.
+Font Instance Characteristics
+-----------------------------
-`pointer'
- Used as the mouse pointer for a window.
+ - Function: font-instance-properties font-instance
+ This function returns the properties (an alist or `nil') of
+ FONT-INSTANCE.
-`subwindow'
- A child window that is treated as an image. This allows (e.g.)
- another program to be responsible for drawing into the window.
- Not currently implemented.
+ - 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: valid-image-instance-type-p type
- This function returns non-`nil' if TYPE is a valid image instance
- type.
+ - 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'.
- - Function: image-instance-type-list
- This function returns a list of the valid image instance types.
+ - 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'.
- - Function: image-instance-type image-instance
- This function returns the type of the given image instance. The
- return value will be one of `nothing', `text', `mono-pixmap',
- `color-pixmap', `pointer', or `subwindow'.
+ - 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: text-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `text'.
+ - 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: mono-pixmap-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `mono-pixmap'.
+\1f
+File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
- - Function: color-pixmap-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `color-pixmap'.
+Font Convenience Functions
+--------------------------
- - Function: pointer-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `pointer'.
+ - 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: subwindow-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `subwindow'.
+ - 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: nothing-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `nothing'.
+ - 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.
\1f
-File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
-
-Image Instance Functions
-........................
-
- - Function: make-image-instance data &optional device dest-types
- no-error
- This function creates a new image-instance object.
-
- DATA is an image instantiator, which describes the image (*note
- Image Specifiers::).
-
- DEST-TYPES should be a list of allowed image instance types that
- can be generated. The DEST-TYPES list is unordered. If multiple
- destination types are possible for a given instantiator, the "most
- natural" type for the instantiator's format is chosen. (For XBM,
- the most natural types are `mono-pixmap', followed by
- `color-pixmap', followed by `pointer'. For the other normal image
- formats, the most natural types are `color-pixmap', followed by
- `mono-pixmap', followed by `pointer'. For the string and
- formatted-string formats, the most natural types are `text',
- followed by `mono-pixmap' (not currently implemented), followed by
- `color-pixmap' (not currently implemented). The other formats can
- only be instantiated as one type. (If you want to control more
- specifically the order of the types into which an image is
- instantiated, just call `make-image-instance' repeatedly until it
- succeeds, passing less and less preferred destination types each
- time.
-
- If DEST-TYPES is omitted, all possible types are allowed.
-
- NO-ERROR controls what happens when the image cannot be generated.
- If NIL, an error message is generated. If T, no messages are
- generated and this function returns NIL. If anything else, a
- warning message is generated and this function returns NIL.
-
- - Function: colorize-image-instance image-instance foreground
- background
- This function makes the image instance be displayed in the given
- colors. Image instances come in two varieties: bitmaps, which are
- 1 bit deep which are rendered in the prevailing foreground and
- background colors; and pixmaps, which are of arbitrary depth
- (including 1) and which have the colors explicitly specified.
- This function converts a bitmap to a pixmap. If the image
- instance was a pixmap already, nothing is done (and `nil' is
- returned). Otherwise `t' is returned.
-
- - Function: image-instance-name image-instance
- This function returns the name of the given image instance.
-
- - Function: image-instance-string image-instance
- This function returns the string of the given image instance.
- This will only be non-`nil' for text image instances.
-
- - Function: image-instance-file-name image-instance
- This function returns the file name from which IMAGE-INSTANCE was
- read, if known.
-
- - Function: image-instance-mask-file-name image-instance
- This function returns the file name from which IMAGE-INSTANCE's
- mask was read, if known.
-
- - Function: image-instance-depth image-instance
- This function returns the depth of the image instance. This is 0
- for a mono pixmap, or a positive integer for a color pixmap.
-
- - Function: image-instance-height image-instance
- This function returns the height of the image instance, in pixels.
-
- - Function: image-instance-width image-instance
- This function returns the width of the image instance, in pixels.
-
- - Function: image-instance-hotspot-x image-instance
- This function returns the X coordinate of the image instance's
- hotspot, if known. This is a point relative to the origin of the
- pixmap. When an image is used as a mouse pointer, the hotspot is
- the point on the image that sits over the location that the
- pointer points to. This is, for example, the tip of the arrow or
- the center of the crosshairs.
-
- This will always be `nil' for a non-pointer image instance.
-
- - Function: image-instance-hotspot-y image-instance
- This function returns the Y coordinate of the image instance's
- hotspot, if known.
-
- - Function: image-instance-foreground image-instance
- This function returns the foreground color of IMAGE-INSTANCE, if
- applicable. This will be a color instance or `nil'. (It will only
- be non-`nil' for colorized mono pixmaps and for pointers.)
-
- - Function: image-instance-background image-instance
- This function returns the background color of IMAGE-INSTANCE, if
- applicable. This will be a color instance or `nil'. (It will only
- be non-`nil' for colorized mono pixmaps and for pointers.)
+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.
\1f
-File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
+File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
-Glyph Types
-===========
+Color Specifiers
+----------------
- Each glyph has a particular type, which controls how the glyph's
-image is generated. Each glyph type has a corresponding list of
-allowable image instance types that can be generated. When you call
-`glyph-image-instance' to retrieve the image instance of a glyph,
-XEmacs does the equivalent of calling `make-image-instance' and passing
-in DEST-TYPES the list of allowable image instance types for the
-glyph's type.
+ - Function: color-specifier-p object
+ This function returns non-`nil' if OBJECT is a color specifier.
- * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
- extent, in the modeline, and in the toolbar. Their image can be
- instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
- and `subwindow'.
+ - Function: make-color-specifier spec-list
+ Return a new `color' 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
+ a detailed description of how specifiers work.
- * `pointer' glyphs can be used to specify the mouse pointer. Their
- image can be instantiated as `pointer'.
+ Valid instantiators for color specifiers are:
- * `icon' glyphs can be used to specify the icon used when a frame is
- iconified. Their image can be instantiated as `mono-pixmap' and
- `color-pixmap'.
+ * A string naming a color (e.g. under X this might be
+ "lightseagreen2" or "#F534B2").
- - Function: glyph-type glyph
- This function returns the type of the given glyph. The return
- value will be a symbol, one of `buffer', `pointer', or `icon'.
+ * A color instance (use that instance directly if the device
+ matches, or use the string that generated it).
- - Function: valid-glyph-type-p glyph-type
- Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
+ * A vector of no elements (only on TTY's; this means to set no
+ color at all, thus using the "natural" color of the
+ terminal's text).
- - Function: glyph-type-list
- This function returns a list of valid glyph types.
+ * A vector of one or two elements: a face to inherit from, and
+ optionally a symbol naming which property of that face to
+ inherit, either `foreground' or `background' (if omitted,
+ defaults to the same property that this color specifier is
+ used for; if this specifier is not part of a face, the
+ instantiator would not be valid).
- - Function: buffer-glyph-p object
- This function returns non-`nil' if OBJECT is a glyph of type
- `buffer'.
+ - Function: make-face-boolean-specifier spec-list
+ Return a new `face-boolean' 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. *Note Specifiers::, for
+ a detailed description of how specifiers work.
- - Function: icon-glyph-p object
- This function returns non-`nil' if OBJECT is a glyph of type
- `icon'.
+ Valid instantiators for face-boolean specifiers are
- - Function: pointer-glyph-p object
- This function returns non-`nil' if OBJECT is a glyph of type
- `pointer'.
+ * t or nil.
+
+ * A vector of two or three elements: a face to inherit from,
+ optionally a symbol naming the property of that face to
+ 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
+ sense of the inherited property.
-\1f
-File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
-
-Mouse Pointer
-=============
-
- The shape of the mouse pointer when over a particular section of a
-frame is controlled using various glyph variables. Since the image of
-a glyph is a specifier, it can be controlled on a per-buffer,
-per-frame, per-window, or per-device basis.
-
- You should use `set-glyph-image' to set the following variables,
-_not_ `setq'.
-
- - Glyph: text-pointer-glyph
- This variable specifies the shape of the mouse pointer when over
- text.
-
- - Glyph: nontext-pointer-glyph
- This variable specifies the shape of the mouse pointer when over a
- buffer, but not over text. If unspecified in a particular domain,
- `text-pointer-glyph' is used.
-
- - Glyph: modeline-pointer-glyph
- This variable specifies the shape of the mouse pointer when over
- the modeline. If unspecified in a particular domain,
- `nontext-pointer-glyph' is used.
-
- - Glyph: selection-pointer-glyph
- This variable specifies the shape of the mouse pointer when over a
- selectable text region. If unspecified in a particular domain,
- `text-pointer-glyph' is used.
-
- - Glyph: gc-pointer-glyph
- This variable specifies the shape of the mouse pointer when a
- garbage collection is in progress. If the selected window is on a
- window system and this glyph specifies a value (i.e. a pointer
- image instance) in the domain of the selected window, the pointer
- will be changed as specified during garbage collection.
- Otherwise, a message will be printed in the echo area, as
- controlled by `gc-message'.
-
- - Glyph: busy-pointer-glyph
- This variable specifies the shape of the mouse pointer when XEmacs
- is busy. If unspecified in a particular domain, the pointer is
- not changed when XEmacs is busy.
-
- - Glyph: menubar-pointer-glyph
- This variable specifies the shape of the mouse pointer when over
- the menubar. If unspecified in a particular domain, the
- window-system-provided default pointer is used.
-
- - Glyph: scrollbar-pointer-glyph
- This variable specifies the shape of the mouse pointer when over a
- scrollbar. If unspecified in a particular domain, the
- window-system-provided default pointer is used.
-
- - Glyph: toolbar-pointer-glyph
- This variable specifies the shape of the mouse pointer when over a
- toolbar. If unspecified in a particular domain,
- `nontext-pointer-glyph' is used.
-
- Internally, these variables are implemented in
-`default-mouse-motion-handler', and thus only take effect when the
-mouse moves. That function calls `set-frame-pointer', which sets the
-current mouse pointer for a frame.
-
- - Function: set-frame-pointer frame image-instance
- This function sets the mouse pointer of FRAME to the given pointer
- image instance. You should not call this function directly. (If
- you do, the pointer will change again the next time the mouse
- moves.)
\1f
-File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
+File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
+
+Color Instances
+---------------
+
+ 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,
-Redisplay Glyphs
-================
+ (face-background-instance 'default (next-window))
+ => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
+
+ 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.
- - Glyph: truncation-glyph
- This variable specifies what is displayed at the end of truncated
- lines.
+ - Function: color-instance-p object
+ This function returns non-`nil' if OBJECT is a color-instance.
- - Glyph: continuation-glyph
- This variable specifies what is displayed at the end of wrapped
- lines.
+\1f
+File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
- - Glyph: octal-escape-glyph
- This variable specifies what to prefix character codes displayed
- in octal with.
+Color Instance Properties
+-------------------------
- - Glyph: hscroll-glyph
- This variable specifies what to display at the beginning of
- horizontally scrolled lines.
+ - Function: color-instance-name color-instance
+ This function returns the name used to allocate COLOR-INSTANCE.
- - Glyph: invisible-text-glyph
- This variable specifies what to use to indicate the presence of
- invisible text. This is the glyph that is displayed when an
- ellipsis is called for, according to `selective-display-ellipses'
- or `buffer-invisibility-spec'). Normally this is three dots
- ("...").
+ - 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.
- - Glyph: control-arrow-glyph
- This variable specifies what to use as an arrow for control
- characters.
+ (color-instance-rgb-components
+ (face-background-instance 'default (next-window)))
+ => (65535 58596 46517)
\1f
-File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
+File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
+
+Color Convenience Functions
+---------------------------
-Subwindows
-==========
+ - 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.
- Subwindows are not currently implemented.
+ - 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.
- - Function: subwindowp object
- This function returns non-`nil' if OBJECT is a subwindow.
+ (color-rgb-components (face-background 'default (next-window)))
+ => (65535 58596 46517)
\1f
-File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
+File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
-Annotations
-***********
+Glyphs
+******
+
+ A "glyph" is an object that is used for pixmaps, widgets 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:
+
+* 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.
+
+\1f
+File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
- An "annotation" is a pixmap or string that is not part of a buffer's
-text but is displayed next to a particular location in a buffer.
-Annotations can be displayed intermixed with text, in any whitespace at
-the beginning or end of a line, or in a special area at the left or
-right side of the frame called a "margin", whose size is controllable.
-Annotations are implemented using extents (*note Extents::); but you
-can work with annotations without knowing how extents work.
+Glyph Functions
+===============
* Menu:
-* Annotation Basics:: Introduction to annotations.
-* Annotation Primitives:: Creating and deleting annotations.
-* Annotation Properties:: Retrieving and changing the characteristics
- of an annotation.
-* Margin Primitives:: Controlling the size of the margins.
-* Locating Annotations:: Looking for annotations in a buffer.
-* Annotation Hooks:: Hooks called at certain times during an
- annotation's lifetime.
+* 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.
+
+\1f
+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::.
+
+ A glyph in XEmacs does *NOT* refer to a single unit of textual
+ display (the XEmacs term for this is "rune"), but rather is an
+ object encapsulating a graphical element, such as an image or
+ widget (an element such as a button or text field; "widget" is the
+ term for this under X Windows, and it's called a "control" under
+ MS Windows). This graphical element could appear in a buffer, a
+ margin, a gutter, or a toolbar, or as a mouse pointer or an icon,
+ for example.
+
+ Creating a glyph using `make-glyph' does not specify _where_ the
+ glyph will be used, but it does specify _what_ the glyph will look
+ like. In particular, SPEC-LIST is used to specify this, and it's
+ used to initialize the glyph's `image' property, which is an image
+ specifier. (Note that "image" as used in the context of a glyph's
+ `image' property or in the terms "image specifier", "image
+ instantiator", or "image instance" does not refer to what people
+ normally think of as an image (which in XEmacs is called a
+ "pixmap"), but to any graphical element--a pixmap, a widget, or
+ even a block of text, when used in the places that call for a
+ glyph.) The format of the SPEC-LIST 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.
+
+ If you're not familiar with specifiers, you should be in order to
+ understand how glyphs work. The clearest introduction to
+ specifiers is in the Lispref manual, available under Info. (Choose
+ Help->Info->Info Contents on the menubar or type C-h i.) You can
+ also see `make-specifier' for a capsule summary. What's important
+ to keep in mind is that a specifier lets you set a different value
+ for any particular buffer, window, frame, device, or console.
+ This allows for a great deal of flexibility; in particular, only
+ one global glyph needs to exist for a particular purpose (e.g. the
+ icon used to represent an iconified frame, the mouse pointer used
+ over particular areas of a frame, etc.), and in these cases you do
+ not create your own glyph, but rather modify the existing one.
+
+ As well as using SPEC-LIST to initialize the glyph, you can set
+ specifications using `set-glyph-image'. Note that, due to a
+ possibly questionable historical design decision, a glyph itself
+ is not actually a specifier, but rather is an object containing an
+ image specifier (as well as other, seldom-used properties).
+ Therefore, you cannot set or access specifications for the glyph's
+ image by directly using `set-specifier', `specifier-instance' or
+ the like on the glyph; instead use them on `(glyph-image GLYPH)'
+ or use the convenience functions `set-glyph-image',
+ `glyph-image-instance', and `glyph-image'.
+
+ Once you have created a glyph, you specify where it will be used as
+ follows:
+
+ * To insert a glyph into a buffer, create an extent in the
+ buffer and then use `set-extent-begin-glyph' or
+ `set-extent-end-glyph' to set a glyph to be displayed at the
+ corresponding edge of the extent. (It is common to create
+ zero-width extents for this purpose.)
+
+ * To insert a glyph into the left or right margin of a buffer,
+ first make sure the margin is visible by setting a value for
+ the specifiers `left-margin-width' or `right-margin-width'.
+ (Not strictly necessary when using margin glyphs with layout
+ policy `whitespace'.) Then follow the same procedure above
+ for inserting a glyph in a buffer, and then set a non-default
+ layout policy for the glyph using
+ `set-extent-begin-glyph-layout' or
+ `set-extent-end-glyph-layout'. Alternatively, use the
+ high-level annotations API (see `make-annotation'). (In point
+ of fact, you can also use the annotations API for glyphs in a
+ buffer, by setting a layout policy of `text'.)
+
+ * To insert a glyph into the modeline, just put the glyph
+ directly as one of the modeline elements. (Unfortunately you
+ can't currently put a begin glyph or end glyph on one of the
+ modeline extents--they're ignored.)
+
+ * To insert a glyph into a toolbar, specify it as part of a
+ toolbar instantiator (typically set on the specifier
+ `default-toolbar'). See `default-toolbar' for more
+ information. (Note that it is standard practice to use a
+ symbol in place of the glyph list in the toolbar
+ instantiator; the symbol is evalled to get the glyph list.
+ This facilitates both creating the toolbar instantiator and
+ modifying individual glyphs in a toolbar later on. For
+ example, you can change the way that the Mail toolbar button
+ looks by modifying the value of the variable
+ `toolbar-mail-icon' (in general, `toolbar-*-icon') and then
+ calling `(set-specifier-dirty-flag default-toolbar)'. (####
+ Unfortunately this doesn't quite work the way it should; the
+ change will appear in new frames, but not existing ones.
+
+ * To insert a glyph into a gutter, create or modify a gutter
+ instantiator (typically set on the specifier
+ `default-gutter'). Gutter instantiators consist of strings
+ or lists of strings, so to insert a glyph, create an extent
+ over the string, and use `set-extent-begin-glyph' or
+ `set-extent-end-glyph' to set a glyph to be displayed at the
+ corresponding edge of the extent, just like for glyphs in a
+ buffer.
+
+ * To use a glyph as the icon for a frame, you do not actually
+ create a new glyph; rather, you change the specifications for
+ the existing glyph `frame-icon-glyph'. (Remember that,
+ because of the specifier nature of glyphs, you can set
+ different values for any particular buffer or frame.)
+
+ * To use a glyph as the mouse pointer, in general you do not
+ create a new glyph, but rather you change the specifications
+ of various existing glyphs, such as `text-pointer-glyph' for
+ the pointer used over text, `modeline-pointer-glyph' for the
+ 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 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
+ create a glyph of type `pointer'.) This pointer will last
+ only until the next mouse motion event is processed or
+ certain other things happen, such as creating or deleting a
+ window. (In fact, the above-mentioned pointer glyph variables
+ are implemented as part of the default handler for mouse
+ motion events. If you want to customize this behavior, take a
+ look at `mode-motion-hook', or `mouse-motion-handler' if you
+ really want to get low-level.)
+
+ * To use a glyph to control the shape of miscellaneous
+ redisplay effects such as the truncation and continuation
+ markers, set the appropriate existing glyph variables, as for
+ icons and pointers above. See `continuation-glyph',
+ `control-arrow-glyph', `hscroll-glyph',
+ `invisible-text-glyph', `octal-escape-glyph', and
+ `truncation-glyph'. See also `overlay-arrow-string', an odd
+ redisplay leftover which can be set to a glyph you created,
+ and will cause the glyph to be displayed on top of the text
+ position specified in the marker stored in
+ `overlay-arrow-position'.
+
+ * To use a glyph in a display table (i.e. to control the
+ appearance of any individual character), create the
+ appropriate character glyphs and then set a specification for
+ the specifier `current-display-table', which controls the
+ appearance of characters. You can also set an overriding
+ display table for use with text displayed in a particular
+ face; see `set-face-display-table' and `make-display-table'.
+ #### Note: Display tables do not currently support general
+ Mule characters. They will be overhauled at some point to
+ support this and to provide other features required under
+ Mule.
+
+ * To use a glyph as the background pixmap of a face: Note that
+ the background pixmap of a face is actually an image
+ specifier - probably the only place in XEmacs where an image
+ specifier occurs outside of a glyph. Similarly to how the
+ glyph's image specifier works, you don't create your own
+ image specifier, but rather add specifications to the
+ existing one (using `set-face-background-pixmap'). Note that
+ the image instance that is generated in order to actually
+ display the background pixmap is of type `mono-pixmap',
+ meaning that it's a two-color image and the foreground and
+ background of the image get filled in with the corresponding
+ colors from the face.
+
+ It is extremely rare that you will ever have to specify a value for
+ TYPE, which 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'. The only cases where it
+ needs to be specified is when creating icon or pointer glyphs, and
+ in both cases the necessary glyphs have already been created at
+ startup and are accessed through the appropriate variables, e.g.
+ `text-pointer-glyph' (or in general, `*-pointer-glyph') and
+ `frame-icon-glyph'. *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
+ Return a new `pointer-glyph' object with the specification list
+ SPEC-LIST. This function is equivalent to calling `make-glyph'
+ with a TYPE of `pointer'.
+
+ It is extremely unlikely that you will ever need to create a
+ pointer glyph. Instead, you probably want to be calling
+ `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
+
+ - Function: make-icon-glyph &optional spec-list
+ Return a new `pointer-glyph' object with the specification list
+ SPEC-LIST. This function is equivalent to calling `make-glyph'
+ with a TYPE of `icon'.
+
+ It is extremely unlikely that you will ever need to create a
+ pointer glyph. Instead, you probably want to be calling
+ `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
projects / chise / xemacs-chise.git / blobdiff