+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\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
- HOW-TO-ADD
- This function changes a property of a FACE.
-
- For built-in properties, the actual value of the property is a
- specifier and you cannot change this; but you can change the
- specifications within the specifier, and that is what this
- function will do. For user-defined properties, you can use this
- function to either change the actual value of the property or, if
- this value is a specifier, change the specifications within it.
-
- If PROPERTY is a built-in property, the specifications to be added
- to this property can be supplied in many different ways:
-
- If VALUE is a simple instantiator (e.g. a string naming a
- font or color) or a list of instantiators, then the
- instantiator(s) will be added as a specification of the
- property for the given LOCALE (which defaults to `global' if
- omitted).
-
- If VALUE is a list of specifications (each of which is a cons
- of a locale and a list of instantiators), then LOCALE must be
- `nil' (it does not make sense to explicitly specify a locale
- in this case), and specifications will be added as given.
-
- If VALUE is a specifier (as would be returned by
- `face-property' if no LOCALE argument is given), then some or
- all of the specifications in the specifier will be added to
- the property. In this case, the function is really
- equivalent to `copy-specifier' and LOCALE has the same
- semantics (if it is a particular locale, the specification
- for the locale will be copied; if a locale type,
- specifications for all locales of that type will be copied;
- if `nil' or `all', then all specifications will be copied).
-
- HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
- `append', `remove-tag-set-prepend', `remove-tag-set-append',
- `remove-locale', `remove-locale-type', or `remove-all'. See
- `copy-specifier' and `add-spec-to-specifier' for a description of
- what each of these means. Most of the time, you do not need to
- worry about this argument; the default behavior usually is fine.
-
- In general, it is OK to pass an instance object (e.g. as returned
- by `face-property-instance') as an instantiator in place of an
- actual instantiator. In such a case, the instantiator used to
- create that instance object will be used (for example, if you set
- a font-instance object as the value of the `font' property, then
- the font name used to create that object will be used instead).
- If some cases, however, doing this conversion does not make sense,
- and this will be noted in the documentation for particular types
- of instance objects.
-
- If PROPERTY is not a built-in property, then this function will
- simply set its value if LOCALE is `nil'. However, if LOCALE is
- given, then this function will attempt to add VALUE as the
- instantiator for the given LOCALE, using `add-spec-to-specifier'.
- If the value of the property is not a specifier, it will
- automatically be converted into a `generic' specifier.
-
- - Function: face-property FACE PROPERTY &optional LOCALE
- This function returns FACE's value of the given PROPERTY.
-
- If LOCALE is omitted, the FACE's actual value for PROPERTY will be
- returned. For built-in properties, this will be a specifier
- object of a type appropriate to the property (e.g. a font or color
- specifier). For other properties, this could be anything.
-
- If LOCALE is supplied, then instead of returning the actual value,
- the specification(s) for the given locale or locale type will be
- returned. This will only work if the actual value of PROPERTY is
- a specifier (this will always be the case for built-in properties,
- but not or not may apply to user-defined properties). If the
- actual value of PROPERTY is not a specifier, this value will
- simply be returned regardless of LOCALE.
-
- The return value will be a list of instantiators (e.g. strings
- specifying a font or color name), or a list of specifications,
- each of which is a cons of a locale and a list of instantiators.
- Specifically, if LOCALE is a particular locale (a buffer, window,
- frame, device, or `global'), a list of instantiators for that
- locale will be returned. Otherwise, if LOCALE is a locale type
- (one of the symbols `buffer', `window', `frame', or `device'), the
- specifications for all locales of that type will be returned.
- Finally, if LOCALE is `all', the specifications for all locales of
- all types will be returned.
-
- The specifications in a specifier determine what the value of
- PROPERTY will be in a particular "domain" or set of circumstances,
- which is typically a particular Emacs window along with the buffer
- it contains and the frame and device it lies within. The value is
- derived from the instantiator associated with the most specific
- locale (in the order buffer, window, frame, device, and `global')
- that matches the domain in question. In other words, given a
- domain (i.e. an Emacs window, usually), the specifier for PROPERTY
- will first be searched for a specification whose locale is the
- buffer contained within that window; then for a specification
- whose locale is the window itself; then for a specification whose
- locale is the frame that the window is contained within; etc. The
- first instantiator that is valid for the domain (usually this
- means that the instantiator is recognized by the device [i.e. the
- X server or TTY device] that the domain is on). The function
- `face-property-instance' actually does all this, and is used to
- determine how to display the face.
-
- - Function: face-property-instance FACE PROPERTY &optional DOMAIN
- DEFAULT NO-FALLBACK
- This function returns the instance of FACE's PROPERTY in the
- specified DOMAIN.
-
- Under most circumstances, DOMAIN will be a particular window, and
- the returned instance describes how the specified property
- actually is displayed for that window and the particular buffer in
- it. Note that this may not be the same as how the property
- appears when the buffer is displayed in a different window or
- frame, or how the property appears in the same window if you
- switch to another buffer in that window; and in those cases, the
- returned instance would be different.
-
- The returned instance will typically be a color-instance,
- font-instance, or pixmap-instance object, and you can query it
- using the appropriate object-specific functions. For example, you
- could use `color-instance-rgb-components' to find out the RGB
- (red, green, and blue) components of how the `background' property
- of the `highlight' face is displayed in a particular window. The
- results might be different from the results you would get for
- another window (perhaps the user specified a different color for
- the frame that window is on; or perhaps the same color was
- specified but the window is on a different X server, and that X
- server has different RGB values for the color from this one).
-
- DOMAIN defaults to the selected window if omitted.
-
- DOMAIN can be a frame or device, instead of a window. The value
- returned for a such a domain is used in special circumstances when
- a more specific domain does not apply; for example, a frame value
- might be used for coloring a toolbar, which is conceptually
- attached to a frame rather than a particular window. The value is
- also useful in determining what the value would be for a
- particular window within the frame or device, if it is not
- overridden by a more specific specification.
-
- If PROPERTY does not name a built-in property, its value will
- simply be returned unless it is a specifier object, in which case
- it will be instanced using `specifier-instance'.
-
- Optional arguments DEFAULT and NO-FALLBACK are the same as in
- `specifier-instance'. *Note Specifiers::.
-
-\1f
-File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
-
-Face Convenience Functions
---------------------------
-
- - Function: set-face-foreground FACE COLOR &optional LOCALE TAG
- HOW-TO-ADD
- - Function: set-face-background FACE COLOR &optional LOCALE TAG
- HOW-TO-ADD
- These functions set the foreground (respectively, background)
- color of face FACE to COLOR. The argument COLOR should be a
- string (the name of a color) or a color object as returned by
- `make-color' (*note Colors::.).
-
- - Function: set-face-background-pixmap FACE PIXMAP &optional LOCALE
- TAG HOW-TO-ADD
- This function sets the background pixmap of face FACE to PIXMAP.
- The argument PIXMAP should be a string (the name of a bitmap or
- pixmap file; the directories listed in the variable
- `x-bitmap-file-path' will be searched) or a glyph object as
- returned by `make-glyph' (*note Glyphs::.). The argument may also
- be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
- are the size in pixels, and DATA is a string, containing the raw
- bits of the bitmap.
-
- - Function: set-face-font FACE FONT &optional LOCALE TAG HOW-TO-ADD
- This function sets the font of face FACE. The argument FONT
- should be a string or a font object as returned by `make-font'
- (*note Fonts::.).
-
- - Function: set-face-underline-p FACE UNDERLINE-P &optional LOCALE TAG
- HOW-TO-ADD
- This function sets the underline property of face FACE.
-
- - Function: face-foreground FACE &optional LOCALE
- - Function: face-background FACE &optional LOCALE
- These functions return the foreground (respectively, background)
- color specifier of face FACE. *Note Colors::.
-
- - Function: face-background-pixmap FACE &optional LOCALE
- This function return the background-pixmap glyph object of face
- FACE.
-
- - Function: face-font FACE &optional LOCALE
- This function returns the font specifier of face FACE. (Note:
- This is not the same as the function `face-font' in FSF Emacs.)
- *Note Fonts::.
-
- - Function: face-font-name FACE &optional DOMAIN
- This function returns the name of the font of face FACE, or `nil'
- if it is unspecified. This is basically equivalent to `(font-name
- (face-font FACE) DOMAIN)' except that it does not cause an error
- if FACE's font is `nil'. (This function is named `face-font' in
- FSF Emacs.)
-
- - Function: face-underline-p FACE &optional LOCALE
- This function returns the underline property of face FACE.
-
- - 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
-----------------------------
-
- - Function: invert-face FACE &optional LOCALE
- Swap the foreground and background colors of face FACE. If the
- face doesn't specify both foreground and background, then its
- foreground and background are set to the default background and
- foreground.
-
- - 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.
-
-\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
- This function returns the properties (an alist or `nil') of
- FONT-INSTANCE.
-
- - Function: x-make-font-bold FONT &optional DEVICE
- Given an X font specification, this attempts to make a "bold" font.
- If it fails, it returns `nil'.
-
- - Function: x-make-font-unbold FONT &optional DEVICE
- Given an X font specification, this attempts to make a non-bold
- font. If it fails, it returns `nil'.
-
- - 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: x-make-font-unitalic FONT &optional DEVICE
- Given an X font specification, this attempts to make a non-italic
- font. If it fails, it returns `nil'.
-
- - Function: x-make-font-bold-italic FONT &optional DEVICE
- Given an X font specification, this attempts to make a
- "bold-italic" font. If it fails, it returns `nil'.
-
-\1f
-File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
-
-Font Convenience Functions
---------------------------
-
- - Function: font-name FONT &optional DOMAIN
- This function returns the name of the FONT in the specified
- DOMAIN, if any. FONT should be a font specifier object and DOMAIN
- is normally a window and defaults to the selected window if
- omitted. This is equivalent to using `specifier-instance' and
- applying `font-instance-name' to the result.
-
- - Function: font-truename FONT &optional DOMAIN
- This function returns the truename of the FONT in the specified
- DOMAIN, if any. FONT should be a font specifier object and DOMAIN
- is normally a window and defaults to the selected window if
- omitted. This is equivalent to using `specifier-instance' and
- applying `font-instance-truename' to the result.
-
- - Function: font-properties FONT &optional DOMAIN
- This function returns the properties of the FONT in the specified
- DOMAIN, if any. FONT should be a font specifier object and DOMAIN
- is normally a window and defaults to the selected window if
- omitted. This is equivalent to using `specifier-instance' and
- applying `font-instance-properties' to the result.
-
-\1f
-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: Color Specifiers, Next: Color Instances, Up: Colors
-
-Color Specifiers
-----------------
-
- - Function: color-specifier-p OBJECT
- This function returns non-`nil' if OBJECT is a color specifier.
-
-\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.
-
-\1f
-File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
-
-Color Instance Properties
--------------------------
-
- - 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)
-
-\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)
-
-\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:
-
-* 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
----------------
-
- - Function: make-glyph &optional SPEC-LIST TYPE
- This function creates a new glyph object of type TYPE.
-
- SPEC-LIST is used to initialize the glyph's image. It is
- typically an image instantiator (a string or a vector; *Note Image
- Specifiers::), but can also be a list of such instantiators (each
- one in turn is tried until an image is successfully produced), a
- cons of a locale (frame, buffer, etc.) and an instantiator, a list
- of such conses, or any other form accepted by
- `canonicalize-spec-list'. *Note Specifiers::, for more
- information about specifiers.
-
- TYPE specifies the type of the glyph, which specifies in which
- contexts the glyph can be used, and controls the allowable image
- types into which the glyph's image can be instantiated. TYPE
- should be one of `buffer' (used for glyphs in an extent, the
- modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
- for the mouse-pointer), or `icon' (used for a frame's icon), and
- defaults to `buffer'. *Note Glyph Types::.
-
- - Function: make-glyph-internal &optional TYPE
- This function creates a new, uninitialized glyph of type TYPE.
-
- - Function: make-pointer-glyph &optional SPEC-LIST
- This function is equivalent to calling `make-glyph' with a TYPE of
- `pointer'.
-
- - Function: make-icon-glyph &optional SPEC-LIST
- This function is equivalent to calling `make-glyph' with a TYPE of
- `icon'.
-
-\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.1 / blobdiff