-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
-
-Image Specifiers
-----------------
-
- 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. Not currently implemented.)
-
-`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'.)
-
-`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).
+File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces
+
+Merging Faces for Display
+-------------------------
+
+ Here are all the ways to specify which face to use for display of
+text:
+
+ * With defaults. Each frame has a "default face", which is used for
+ all text that doesn't somehow specify another face. The face named
+ `default' applies to the text area, while the faces `left-margin'
+ and `right-margin' apply to the left and right margin areas.
+
+ * With text properties. A character may have a `face' property; if
+ so, it's displayed with that face. (Text properties are actually
+ implemented in terms of extents.) *Note Text Properties::.
+
+ * With extents. An extent may have a `face' property, which applies
+ to all the text covered by the extent; in addition, if the
+ `highlight' property is set, the `highlight' property applies when
+ the mouse moves over the extent or if the extent is explicitly
+ highlighted. *Note Extents::.
+
+ * With annotations. Annotations that are inserted into a buffer can
+ specify their own face. (Annotations are actually implemented in
+ terms of extents.) *Note Annotations::.
+
+ If these various sources together specify more than one face for a
+particular character, XEmacs merges the properties of the various faces
+specified. Extents, text properties, and annotations all use the same
+underlying representation (as extents). When multiple extents cover one
+character, an extent with higher priority overrides those with lower
+priority. *Note Extents::. If no extent covers a particular character,
+the `default' face is used.
+
+ If a background pixmap is specified, it determines what will be
+displayed in the background of text characters. If the background
+pixmap is actually a pixmap, with its colors specified, those colors are
+used; if it is a bitmap, the face's foreground and background colors are
+used to color it.
\1f
-File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
-
-Image Instantiator Conversion
------------------------------
-
- - 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.
+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: Image Instances, Prev: Image Instantiator Conversion, Up: Images
+File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
-Image Instances
+Face Properties
---------------
- Image-instance objects encapsulate the way a particular image
-(pixmap, etc.) is displayed on a particular device.
+ You can examine and modify the properties of an existing face with
+the following functions.
- 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.
+ The following symbols have predefined meanings:
- - Function: image-instance-p OBJECT
- This function returns non-`nil' if OBJECT is an image instance.
+`foreground'
+ The foreground color of the face.
-* Menu:
+`background'
+ The background color of the face.
-* Image Instance Types:: Each image instances has a particular type.
-* Image Instance Functions:: Functions for working with image instances.
+`font'
+ The font used to display text covered by this face.
+
+`display-table'
+ The display table of the face.
+
+`background-pixmap'
+ The pixmap displayed in the background of the face. Only used by
+ faces on X devices.
+
+`underline'
+ Underline all text covered by this face.
+
+`highlight'
+ Highlight all text covered by this face. Only used by faces on TTY
+ devices.
+
+`dim'
+ Dim all text covered by this face. Only used by faces on TTY
+ devices.
+
+`blinking'
+ Blink all text covered by this face. Only used by faces on TTY
+ devices.
+
+`reverse'
+ Reverse the foreground and background colors. Only used by faces
+ on TTY devices.
+
+`doc-string'
+ Description of what the face's normal use is. NOTE: This is not a
+ specifier, unlike all the other built-in properties, and cannot
+ contain locale-specific values.
+
+ - Function: set-face-property face property value &optional locale
+ tag-set how-to-add
+ This function changes a property of a FACE.
+
+ For built-in properties, the actual value of the property is a
+ specifier and you cannot change this; but you can change the
+ specifications within the specifier, and that is what this
+ function will do. For user-defined properties, you can use this
+ function to either change the actual value of the property or, if
+ this value is a specifier, change the specifications within it.
+
+ If PROPERTY is a built-in property, the specifications to be added
+ to this property can be supplied in many different ways:
+
+ If VALUE is a simple instantiator (e.g. a string naming a
+ font or color) or a list of instantiators, then the
+ instantiator(s) will be added as a specification of the
+ property for the given LOCALE (which defaults to `global' if
+ omitted).
+
+ If VALUE is a list of specifications (each of which is a cons
+ of a locale and a list of instantiators), then LOCALE must be
+ `nil' (it does not make sense to explicitly specify a locale
+ in this case), and specifications will be added as given.
+
+ If VALUE is a specifier (as would be returned by
+ `face-property' if no LOCALE argument is given), then some or
+ all of the specifications in the specifier will be added to
+ the property. In this case, the function is really
+ equivalent to `copy-specifier' and LOCALE has the same
+ semantics (if it is a particular locale, the specification
+ for the locale will be copied; if a locale type,
+ specifications for all locales of that type will be copied;
+ if `nil' or `all', then all specifications will be copied).
+
+ HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
+ `append', `remove-tag-set-prepend', `remove-tag-set-append',
+ `remove-locale', `remove-locale-type', or `remove-all'. See
+ `copy-specifier' and `add-spec-to-specifier' for a description of
+ what each of these means. Most of the time, you do not need to
+ worry about this argument; the default behavior usually is fine.
+
+ In general, it is OK to pass an instance object (e.g. as returned
+ by `face-property-instance') as an instantiator in place of an
+ actual instantiator. In such a case, the instantiator used to
+ create that instance object will be used (for example, if you set
+ a font-instance object as the value of the `font' property, then
+ the font name used to create that object will be used instead).
+ If some cases, however, doing this conversion does not make sense,
+ and this will be noted in the documentation for particular types
+ of instance objects.
+
+ If PROPERTY is not a built-in property, then this function will
+ simply set its value if LOCALE is `nil'. However, if LOCALE is
+ given, then this function will attempt to add VALUE as the
+ instantiator for the given LOCALE, using `add-spec-to-specifier'.
+ If the value of the property is not a specifier, it will
+ automatically be converted into a `generic' specifier.
+
+ - Function: remove-face-property face property &optional locale
+ tag-set exact-p
+ This function removes a property of a FACE.
+
+ For built-in properties, this is analogous to `remove-specifier'.
+ For more information, *Note Other Specification Functions::.
+
+ When PROPERTY is not a built-in property, this function will just
+ remove its value if LOCALE is `nil' or `all'. However, if LOCALE
+ is other than that, this function will attempt to remove VALUE as
+ the instantiator for the given LOCALE with `remove-specifier'. If
+ the value of the property is not a specifier, it will be converted
+ into a `generic' specifier automatically.
+
+ - Function: face-property face property &optional locale tag-set
+ exact-p
+ This function returns FACE's value of the given PROPERTY.
+
+ If LOCALE is omitted, the FACE's actual value for PROPERTY will be
+ returned. For built-in properties, this will be a specifier
+ object of a type appropriate to the property (e.g. a font or color
+ specifier). For other properties, this could be anything.
+
+ If LOCALE is supplied, then instead of returning the actual value,
+ the specification(s) for the given locale or locale type will be
+ returned. This will only work if the actual value of PROPERTY is
+ a specifier (this will always be the case for built-in properties,
+ but not or not may apply to user-defined properties). If the
+ actual value of PROPERTY is not a specifier, this value will
+ simply be returned regardless of LOCALE.
+
+ The return value will be a list of instantiators (e.g. strings
+ specifying a font or color name), or a list of specifications,
+ each of which is a cons of a locale and a list of instantiators.
+ Specifically, if LOCALE is a particular locale (a buffer, window,
+ frame, device, or `global'), a list of instantiators for that
+ locale will be returned. Otherwise, if LOCALE is a locale type
+ (one of the symbols `buffer', `window', `frame', or `device'), the
+ specifications for all locales of that type will be returned.
+ Finally, if LOCALE is `all', the specifications for all locales of
+ all types will be returned.
+
+ The specifications in a specifier determine what the value of
+ PROPERTY will be in a particular "domain" or set of circumstances,
+ which is typically a particular Emacs window along with the buffer
+ it contains and the frame and device it lies within. The value is
+ derived from the instantiator associated with the most specific
+ locale (in the order buffer, window, frame, device, and `global')
+ that matches the domain in question. In other words, given a
+ domain (i.e. an Emacs window, usually), the specifier for PROPERTY
+ will first be searched for a specification whose locale is the
+ buffer contained within that window; then for a specification
+ whose locale is the window itself; then for a specification whose
+ locale is the frame that the window is contained within; etc. The
+ first instantiator that is valid for the domain (usually this
+ means that the instantiator is recognized by the device [i.e. the
+ X server or TTY device] that the domain is on). The function
+ `face-property-instance' actually does all this, and is used to
+ determine how to display the face.
+
+ - Function: face-property-instance face property &optional domain
+ default no-fallback
+ This function returns the instance of FACE's PROPERTY in the
+ specified DOMAIN.
+
+ Under most circumstances, DOMAIN will be a particular window, and
+ the returned instance describes how the specified property
+ actually is displayed for that window and the particular buffer in
+ it. Note that this may not be the same as how the property
+ appears when the buffer is displayed in a different window or
+ frame, or how the property appears in the same window if you
+ switch to another buffer in that window; and in those cases, the
+ returned instance would be different.
+
+ The returned instance will typically be a color-instance,
+ font-instance, or pixmap-instance object, and you can query it
+ using the appropriate object-specific functions. For example, you
+ could use `color-instance-rgb-components' to find out the RGB
+ (red, green, and blue) components of how the `background' property
+ of the `highlight' face is displayed in a particular window. The
+ results might be different from the results you would get for
+ another window (perhaps the user specified a different color for
+ the frame that window is on; or perhaps the same color was
+ specified but the window is on a different X server, and that X
+ server has different RGB values for the color from this one).
+
+ DOMAIN defaults to the selected window if omitted.
+
+ DOMAIN can be a frame or device, instead of a window. The value
+ returned for a such a domain is used in special circumstances when
+ a more specific domain does not apply; for example, a frame value
+ might be used for coloring a toolbar, which is conceptually
+ attached to a frame rather than a particular window. The value is
+ also useful in determining what the value would be for a
+ particular window within the frame or device, if it is not
+ overridden by a more specific specification.
+
+ If PROPERTY does not name a built-in property, its value will
+ simply be returned unless it is a specifier object, in which case
+ it will be instanced using `specifier-instance'.
+
+ Optional arguments DEFAULT and NO-FALLBACK are the same as in
+ `specifier-instance'. *Note Specifiers::.
\1f
-File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
+File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
+
+Face Convenience Functions
+--------------------------
+
+ - Command: set-face-foreground face color &optional locale tag-set
+ how-to-add
+ - Command: set-face-background face color &optional locale tag-set
+ how-to-add
+ These functions set the foreground (respectively, background)
+ color of face FACE to COLOR. The argument COLOR should be a
+ string (the name of a color) or a color object as returned by
+ `make-color' (*note Colors::).
+
+ - Command: set-face-background-pixmap face pixmap &optional locale
+ tag-set how-to-add
+ This function sets the background pixmap of face FACE to PIXMAP.
+ The argument PIXMAP should be a string (the name of a bitmap or
+ pixmap file; the directories listed in the variable
+ `x-bitmap-file-path' will be searched) or a glyph object as
+ returned by `make-glyph' (*note Glyphs::). The argument may also
+ be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
+ are the size in pixels, and DATA is a string, containing the raw
+ bits of the bitmap.
+
+ - Command: set-face-font face font &optional locale tag-set how-to-add
+ This function sets the font of face FACE. The argument FONT
+ should be a string or a font object as returned by `make-font'
+ (*note Fonts::).
+
+ - Command: set-face-underline-p face underline-p &optional locale
+ tag-set how-to-add
+ This function sets the underline property of face FACE.
+
+ - Function: face-foreground face &optional locale tag-set exact-p
+ - Function: face-background face &optional locale tag-set exact-p
+ These functions return the foreground (respectively, background)
+ color specifier of face FACE. *Note Colors::.
+
+ - Function: face-background-pixmap face &optional locale tag-set
+ exact-p
+ This function return the background-pixmap glyph object of face
+ FACE.
+
+ - Function: face-font face &optional locale tag-set exact-p
+ This function returns the font specifier of face FACE. (Note:
+ This is not the same as the function `face-font' in FSF Emacs.)
+
+ *Note Fonts::.
+
+ - Function: face-font-name face &optional domain
+ This function returns the name of the font of face FACE, or `nil'
+ if it is unspecified. This is basically equivalent to `(font-name
+ (face-font FACE) DOMAIN)' except that it does not cause an error
+ if FACE's font is `nil'. (This function is named `face-font' in
+ FSF Emacs.)
+
+ - Function: face-underline-p face &optional locale
+ This function returns the underline property of face FACE.
+
+ - Function: face-foreground-instance face &optional domain
+ - Function: face-background-instance face &optional domain
+ These functions return the foreground (respectively, background)
+ color specifier of face FACE. *Note Colors::.
+
+ - Function: face-background-pixmap-instance face &optional domain
+ This function return the background-pixmap glyph object of face
+ FACE.
+
+ - Function: face-font-instance face &optional domain
+ This function returns the font specifier of face FACE. *Note
+ Fonts::.
-Image Instance Types
-....................
+\1f
+File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
- 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.
+Other Face Display Functions
+----------------------------
- The valid image instance types are
+ - 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.
-`nothing'
- Nothing is displayed.
+ - 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'.
-`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.
+ - 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'.
-`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: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
-`color-pixmap'
- Displayed as a color pixmap.
+Fonts
+=====
-`pointer'
- Used as the mouse pointer for a window.
+ This section describes how to work with font specifier and font
+instance objects, which encapsulate fonts in the window system.
-`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.
+* Menu:
- - Function: valid-image-instance-type-p TYPE
- This function returns non-`nil' if TYPE is a valid image instance
- type.
+* 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.
- - Function: image-instance-type-list
- This function returns a list of the valid image instance types.
+\1f
+File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
- - 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'.
+Font Specifiers
+---------------
- - Function: text-image-instance-p OBJECT
- This function returns non-`nil' if OBJECT is an image instance of
- type `text'.
+ - Function: font-specifier-p object
+ This predicate returns `t' if OBJECT is a font specifier, and
+ `nil' otherwise.
- - Function: mono-pixmap-image-instance-p OBJECT
- This function returns non-`nil' if OBJECT is an image instance of
- type `mono-pixmap'.
+ - 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.
- - Function: color-pixmap-image-instance-p OBJECT
- This function returns non-`nil' if OBJECT is an image instance of
- type `color-pixmap'.
+ Valid instantiators for font specifiers are:
- - Function: pointer-image-instance-p OBJECT
- This function returns non-`nil' if OBJECT is an image instance of
- type `pointer'.
+ * 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).
- - Function: subwindow-image-instance-p OBJECT
- This function returns non-`nil' if OBJECT is an image instance of
- type `subwindow'.
+ * A font instance (use that instance directly if the device
+ matches, or use the string that generated it).
- - Function: nothing-image-instance-p OBJECT
- This function returns non-`nil' if OBJECT is an image instance of
- type `nothing'.
+ * 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).
-\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.)
+ * A vector of one element (a face to inherit from).
\1f
-File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
+File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
-Glyph Types
-===========
+Font Instances
+--------------
- 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.
-
- * `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'.
-
- * `pointer' glyphs can be used to specify the mouse pointer. Their
- image can be instantiated as `pointer'.
+ - Function: font-instance-p object
+ This predicate returns `t' if OBJECT is a font instance, and `nil'
+ otherwise.
- * `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'.
+ - 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.
- - 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'.
+ The returned object is a normal, first-class lisp object. The way
+ you "deallocate" the font is the way you deallocate any other lisp
+ object: you drop all pointers to it and allow it to be garbage
+ collected. When these objects are GCed, the underlying X data is
+ deallocated as well.
- - Function: valid-glyph-type-p GLYPH-TYPE
- Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
+\1f
+File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
- - Function: glyph-type-list
- This function returns a list of valid glyph types.
+Font Instance Names
+-------------------
- - Function: buffer-glyph-p OBJECT
- This function returns non-`nil' if OBJECT is a glyph of type
- `buffer'.
+ - 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: icon-glyph-p OBJECT
- This function returns non-`nil' if OBJECT is a glyph of type
- `icon'.
+ - Function: font-instance-name font-instance
+ This function returns the name used to allocate FONT-INSTANCE.
- - Function: pointer-glyph-p OBJECT
- This function returns non-`nil' if OBJECT is a glyph of type
- `pointer'.
+ - 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: 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.)
+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: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
+File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
-Redisplay Glyphs
-================
+Font Instance Characteristics
+-----------------------------
- - Glyph: truncation-glyph
- This variable specifies what is displayed at the end of truncated
- lines.
+ - Function: font-instance-properties font-instance
+ This function returns the properties (an alist or `nil') of
+ FONT-INSTANCE.
- - Glyph: continuation-glyph
- This variable specifies what is displayed at the end of wrapped
- lines.
+ - 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'.
- - Glyph: octal-escape-glyph
- This variable specifies what to prefix character codes displayed
- in octal with.
+ - 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'.
- - Glyph: hscroll-glyph
- This variable specifies what to display at the beginning of
- horizontally scrolled lines.
+ - 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'.
- - 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: 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'.
- - Glyph: control-arrow-glyph
- This variable specifies what to use as an arrow for control
- characters.
+ - 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: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
-
-Subwindows
-==========
-
- Subwindows are not currently implemented.
-
- - Function: subwindowp OBJECT
- This function returns non-`nil' if OBJECT is a subwindow.
+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: Annotations, Next: Display, Prev: Glyphs, Up: Top
-
-Annotations
-***********
+File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
- 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.
+Colors
+======
* 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.
+* 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: Annotation Basics, Next: Annotation Primitives, Up: Annotations
-
-Annotation Basics
-=================
-
- Marginal annotations are notes associated with a particular location
-in a buffer. They may be displayed in a margin created on the
-left-hand or right-hand side of the frame, in any whitespace at the
-beginning or end of a line, or inside of the text itself. Every
-annotation may have an associated action to be performed when the
-annotation is selected. The term "annotation" is used to refer to an
-individual note. The term "margin" is generically used to refer to the
-whitespace before the first character on a line or after the last
-character on a line.
-
- Each annotation has the following characteristics:
-GLYPH
- This is a glyph object and is used as the displayed representation
- of the annotation.
-
-DOWN-GLYPH
- If given, this glyph is used as the displayed representation of
- the annotation when the mouse is pressed down over the annotation.
-
-FACE
- The face with which to display the glyph.
-
-SIDE
- Which side of the text (left or right) the annotation is displayed
- at.
-
-ACTION
- If non-`nil', this field must contain a function capable of being
- the first argument to `funcall'. This function is normally
- evaluated with a single argument, the value of the DATA field,
- each time the annotation is selected. However, if the WITH-EVENT
- parameter to `make-annotation' is non-`nil', the function is
- called with two arguments. The first argument is the same as
- before, and the second argument is the event (a button-up event,
- usually) that activated the annotation.
-
-DATA
- Not used internally. This field can contain any E-Lisp object.
- It is passed as the first argument to ACTION described above.
-
-MENU
- A menu displayed when the right mouse button is pressed over the
- annotation.
-
- The margin is divided into "outside" and "inside". The outside
-margin is space on the left or right side of the frame which normal text
-cannot be displayed in. The inside margin is that space between the
-leftmost or rightmost point at which text can be displayed and where the
-first or last character actually is.
-
- There are four different "layout types" which affect the exact
-location an annotation appears.
-
-`outside-margin'
- The annotation is placed in the outside margin area. as close as
- possible to the edge of the frame. If the outside margin is not
- wide enough for an annotation to fit, it is not displayed.
-
-`inside-margin'
- The annotation is placed in the inside margin area, as close as
- possible to the edge of the frame. If the inside margin is not
- wide enough for the annotation to fit, it will be displayed using
- any available outside margin space if and only if the specifier
- `use-left-overflow' or `use-right-overflow' (depending on which
- side the annotation appears in) is non-`nil'.
-
-`whitespace'
- The annotation is placed in the inside margin area, as close as
- possible to the first or last non-whitespace character on a line.
- If the inside margin is not wide enough for the annotation to fit,
- it will be displayed if and only if the specifier
- `use-left-overflow' or `use-right-overflow' (depending on which
- side the annotation appears in) is non-`nil'.
-
-`text'
- The annotation is placed at the position it is inserted. It will
- create enough space for itself inside of the text area. It does
- not take up a place in the logical buffer, only in the display of
- the buffer.
-
- The current layout policy is that all `whitespace' annotations are
-displayed first. Next, all `inside-margin' annotations are displayed
-using any remaining space. Finally as many `outside-margin'
-annotations are displayed as possible. The `text' annotations will
-always display as they create their own space to display in.
+File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
-\1f
-File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
-
-Annotation Primitives
-=====================
-
- - Function: make-annotation GLYPH &optional POSITION LAYOUT BUFFER
- WITH-EVENT D-GLYPH RIGHTP
- This function creates a marginal annotation at position POS in
- BUFFER. The annotation is displayed using GLYPH, which should be
- a glyph object or a string, and is positioned using layout policy
- LAYOUT. If POS is `nil', point is used. If LAYOUT is `nil',
- `whitespace' is used. If BUFFER is `nil', the current buffer is
- used.
-
- If WITH-EVENT is non-`nil', then when an annotation is activated,
- the triggering event is passed as the second arg to the annotation
- function. If D-GLYPH is non-`nil' then it is used as the glyph
- that will be displayed when button1 is down. If RIGHTP is
- non-`nil' then the glyph will be displayed on the right side of
- the buffer instead of the left.
-
- The newly created annotation is returned.
-
- - Function: delete-annotation ANNOTATION
- This function removes ANNOTATION from its buffer. This does not
- modify the buffer text.
-
- - Function: annotationp ANNOTATION
- This function returns `t' if ANNOTATION is an annotation, `nil'
- otherwise.
-
-\1f
-File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
-
-Annotation Properties
-=====================
-
- - Function: annotation-glyph ANNOTATION
- This function returns the glyph object used to display ANNOTATION.
+Color Specifiers
+----------------
- - Function: set-annotation-glyph ANNOTATION GLYPH &optional LAYOUT SIDE
- This function sets the glyph of ANNOTATION to GLYPH, which should
- be a glyph object. If LAYOUT is non-`nil', set the layout policy
- of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
- side of the buffer at which the annotation is displayed to the
- given side. The new value of `annotation-glyph' is returned.
+ - Function: color-specifier-p object
+ This function returns non-`nil' if OBJECT is a color specifier.
- - Function: annotation-down-glyph ANNOTATION
- This function returns the glyph used to display ANNOTATION when
- the left mouse button is depressed on the annotation.
+ - 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.
- - Function: set-annotation-down-glyph ANNOTATION GLYPH
- This function returns the glyph used to display ANNOTATION when
- the left mouse button is depressed on the annotation to GLYPH,
- which should be a glyph object.
+ Valid instantiators for color specifiers are:
- - Function: annotation-face ANNOTATION
- This function returns the face associated with ANNOTATION.
+ * A string naming a color (e.g. under X this might be
+ "lightseagreen2" or "#F534B2").
- - Function: set-annotation-face ANNOTATION FACE
- This function sets the face associated with ANNOTATION to FACE.
+ * A color instance (use that instance directly if the device
+ matches, or use the string that generated it).
- - Function: annotation-layout ANNOTATION
- This function returns the layout policy of ANNOTATION.
+ * 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: set-annotation-layout ANNOTATION LAYOUT
- This function sets the layout policy of ANNOTATION to LAYOUT.
+ * 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: annotation-side ANNOTATION
- This function returns the side of the buffer that ANNOTATION is
- displayed on. Return value is a symbol, either `left' or `right'.
+ - 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: annotation-data ANNOTATION
- This function returns the data associated with ANNOTATION.
+ Valid instantiators for face-boolean specifiers are
- - Function: set-annotation-data ANNOTATION DATA
- This function sets the data field of ANNOTATION to DATA. DATA is
- returned.
+ * t or nil.
- - Function: annotation-action ANNOTATION
- This function returns the action associated with ANNOTATION.
+ * 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.
- - Function: set-annotation-action ANNOTATION ACTION
- This function sets the action field of ANNOTATION to ACTION.
- ACTION is returned..
- - Function: annotation-menu ANNOTATION
- This function returns the menu associated with ANNOTATION.
+\1f
+File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
- - Function: set-annotation-menu ANNOTATION MENU
- This function sets the menu associated with ANNOTATION to MENU.
- This menu will be displayed when the right mouse button is pressed
- over the annotation.
+Color Instances
+---------------
- - Function: annotation-visible ANNOTATION
- This function returns `t' if there is enough available space to
- display ANNOTATION, `nil' otherwise.
+ A "color-instance object" is an object describing the way a color
+specifier is instanced in a particular domain. Functions such as
+`face-background-instance' return a color-instance object. For example,
- - Function: annotation-width ANNOTATION
- This function returns the width of ANNOTATION in pixels.
+ (face-background-instance 'default (next-window))
+ => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
- - Function: hide-annotation ANNOTATION
- This function removes ANNOTATION's glyph, making it invisible.
+ 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: reveal-annotation ANNOTATION
- This function restores ANNOTATION's glyph, making it visible.
+ - Function: color-instance-p object
+ This function returns non-`nil' if OBJECT is a color-instance.
\1f
-File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
+File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
-Locating Annotations
-====================
+Color Instance Properties
+-------------------------
- - Function: annotations-in-region START END BUFFER
- This function returns a list of all annotations in BUFFER which
- are between START and END inclusively.
+ - Function: color-instance-name color-instance
+ This function returns the name used to allocate COLOR-INSTANCE.
- - Function: annotations-at &optional POSITION BUFFER
- This function returns a list of all annotations at POSITION in
- BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
- the current buffer is used.
+ - Function: color-instance-rgb-components color-instance
+ This function returns a three element list containing the red,
+ green, and blue color components of COLOR-INSTANCE.
- - Function: annotation-list &optional BUFFER
- This function returns a list of all annotations in BUFFER. If
- BUFFER is `nil', the current buffer is used.
-
- - Function: all-annotations
- This function returns a list of all annotations in all buffers in
- existence.
-
-\1f
-File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
-
-Margin Primitives
-=================
-
- The margin widths are controllable on a buffer-local, window-local,
-frame-local, device-local, or device-type-local basis through the use
-of specifiers. *Note Specifiers::.
-
- - Specifier: left-margin-width
- This is a specifier variable controlling the width of the left
- outside margin, in characters. Use `set-specifier' to change its
- value.
-
- - Specifier: right-margin-width
- This is a specifier variable controlling the width of the right
- outside margin, in characters. Use `set-specifier' to change its
- value.
-
- - Specifier: use-left-overflow
- If non-`nil', use the left outside margin as extra whitespace when
- displaying `whitespace' and `inside-margin' annotations. Defaults
- to `nil'. This is a specifier variable; use `set-specifier' to
- change its value.
-
- - Specifier: use-right-overflow
- If non-`nil', use the right outside margin as extra whitespace when
- displaying `whitespace' and `inside-margin' annotations. Defaults
- to `nil'. This is a specifier variable; use `set-specifier' to
- change its value.
-
- - Function: window-left-margin-pixel-width &optional WINDOW
- This function returns the width in pixels of the left outside
- margin of WINDOW. If WINDOW is `nil', the selected window is
- assumed.
-
- - Function: window-right-margin-pixel-width &optional WINDOW
- This function returns the width in pixels of the right outside
- margin of WINDOW. If WINDOW is `nil', the selected window is
- assumed.
-
- The margin colors are controlled by the faces `left-margin' and
-`right-margin'. These can be set using the X resources
-`Emacs.left-margin.background' and `Emacs.left-margin.foreground';
-likewise for the right margin.
+ (color-instance-rgb-components
+ (face-background-instance 'default (next-window)))
+ => (65535 58596 46517)
\1f
-File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
+File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
-Annotation Hooks
-================
+Color Convenience Functions
+---------------------------
- The following three hooks are provided for use with the marginal
-annotations:
+ - 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.
-`before-delete-annotation-hook'
- This hook is called immediately before an annotation is destroyed.
- It is passed a single argument, the annotation being destroyed.
+ - 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.
-`after-delete-annotation-hook'
- This normal hook is called immediately after an annotation is
- destroyed.
-
-`make-annotation-hook'
- This hook is called immediately after an annotation is created.
- It is passed a single argument, the newly created annotation.
+ (color-rgb-components (face-background 'default (next-window)))
+ => (65535 58596 46517)
\1f
-File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
-
-Emacs Display
-*************
-
- This chapter describes a number of other features related to the
-display that XEmacs presents to the user.
+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, 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:
-* Refresh Screen:: Clearing the screen and redrawing everything on it.
-* Truncation:: Folding or wrapping long text lines.
-* The Echo Area:: Where messages are displayed.
-* Warnings:: Display of Warnings.
-* Invisible Text:: Hiding part of the buffer text.
-* Selective Display:: Hiding part of the buffer text (the old way).
-* Overlay Arrow:: Display of an arrow to indicate position.
-* Temporary Displays:: Displays that go away automatically.
-* Blinking:: How XEmacs shows the matching open parenthesis.
-* Usual Display:: The usual conventions for displaying nonprinting chars.
-* Display Tables:: How to specify other conventions.
-* Beeping:: Audible signal to the user.
+* 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: Refresh Screen, Next: Truncation, Up: Display
-
-Refreshing the Screen
-=====================
-
- The function `redraw-frame' redisplays the entire contents of a
-given frame. *Note Frames::.
-
- - Function: redraw-frame FRAME
- This function clears and redisplays frame FRAME.
+File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
- Even more powerful is `redraw-display':
+Glyph Functions
+===============
- - Command: redraw-display &optional DEVICE
- This function redraws all frames on DEVICE marked as having their
- image garbled. DEVICE defaults to the selected device. If DEVICE
- is `t', all devices will have their frames checked.
-
- Processing user input takes absolute priority over redisplay. If you
-call these functions when input is available, they do nothing
-immediately, but a full redisplay does happen eventually--after all the
-input has been processed.
-
- Normally, suspending and resuming XEmacs also refreshes the screen.
-Some terminal emulators record separate contents for display-oriented
-programs such as XEmacs and for ordinary sequential display. If you are
-using such a terminal, you might want to inhibit the redisplay on
-resumption. *Note Suspending XEmacs::.
+* Menu:
- - Variable: no-redraw-on-reenter
- This variable controls whether XEmacs redraws the entire screen
- after it has been suspended and resumed. Non-`nil' means yes,
- `nil' means no.
+* 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.
- The above functions do not actually cause the display to be updated;
-rather, they clear out the internal display records that XEmacs
-maintains, so that the next time the display is updated it will be
-redrawn from scratch. Normally this occurs the next time that
-`next-event' or `sit-for' is called; however, a display update will not
-occur if there is input pending. *Note Command Loop::.
+\1f
+File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
- - Function: force-cursor-redisplay
- This function causes an immediate update of the cursor on the
- selected frame. (This function does not exist in FSF Emacs.)
+Creating Glyphs
+---------------
-\1f
-File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
-
-Truncation
-==========
-
- When a line of text extends beyond the right edge of a window, the
-line can either be truncated or continued on the next line. When a line
-is truncated, this is normally shown with a `\' in the rightmost column
-of the window on X displays, and with a `$' on TTY devices. When a
-line is continued or "wrapped" onto the next line, this is shown with a
-curved arrow in the rightmost column of the window (or with a `\' on
-TTY devices). The additional screen lines used to display a long text
-line are called "continuation" lines.
-
- Normally, whenever line truncation is in effect for a particular
-window, a horizontal scrollbar is displayed in that window if the
-device supports scrollbars. *Note Scrollbars::.
-
- Note that continuation is different from filling; continuation
-happens on the screen only, not in the buffer contents, and it breaks a
-line precisely at the right margin, not at a word boundary. *Note
-Filling::.
-
- - User Option: truncate-lines
- This buffer-local variable controls how XEmacs displays lines that
- extend beyond the right edge of the window. If it is non-`nil',
- then XEmacs does not display continuation lines; rather each line
- of text occupies exactly one screen line, and a backslash appears
- at the edge of any line that extends to or beyond the edge of the
- window. The default is `nil'.
-
- If the variable `truncate-partial-width-windows' is non-`nil',
- then truncation is always used for side-by-side windows (within one
- frame) regardless of the value of `truncate-lines'.
-
- - User Option: default-truncate-lines
- This variable is the default value for `truncate-lines', for
- buffers that do not have local values for it.
-
- - User Option: truncate-partial-width-windows
- This variable controls display of lines that extend beyond the
- right edge of the window, in side-by-side windows (*note Splitting
- Windows::.). If it is non-`nil', these lines are truncated;
- otherwise, `truncate-lines' says what to do with them.
-
- The backslash and curved arrow used to indicate truncated or
-continued lines are only defaults, and can be changed. These images
-are actually glyphs (*note Glyphs::.). XEmacs provides a great deal of
-flexibility in how glyphs can be controlled. (This differs from FSF
-Emacs, which uses display tables to control these images.)
-
- For details, *Note Redisplay 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