Foundation instead of in the original English.
\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: 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: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
+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.
-Annotation Primitives
-=====================
+\1f
+File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
- - 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.
+Glyph Dimensions
+----------------
- 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.
+ - 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.
- The newly created annotation is returned.
+ - 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: delete-annotation annotation
- This function removes ANNOTATION from its buffer. This does not
- modify the buffer text.
+ - 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: annotationp annotation
- This function returns `t' if ANNOTATION is an annotation, `nil'
- otherwise.
+ - 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: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
+File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
-Annotation Properties
-=====================
+Images
+======
- - Function: annotation-glyph annotation
- This function returns the glyph object used to display ANNOTATION.
+* Menu:
- - 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.
+* Image Specifiers:: Specifying how an image will appear.
+* Image Instantiator Conversion::
+ Conversion is applied to image instantiators
+ at the time they are added to an
+ image specifier or at the time they
+ are passed to `make-image-instance'.
+* Image Instances:: What an image specifier gets instanced as.
- - Function: annotation-down-glyph annotation
- This function returns the glyph used to display ANNOTATION when
- the left mouse button is depressed on the annotation.
+\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. *Note Specifiers::.
+
+ Note that, in practice, you rarely, if ever, need to actually
+ create an image specifier! (This function exists mainly for
+ completeness.) Pretty much the only use for image specifiers is to
+ control how glyphs are displayed, and the image specifier
+ associated with a glyph (the `image' property of a glyph) is
+ created automatically when a glyph is created and need not (and
+ cannot, for that matter) ever be changed (*note Glyphs::). In
+ fact, the design decision to create a separate image specifier
+ type, rather than make glyphs themselves be specifiers, is
+ debatable--the other properties of glyphs are rarely used and could
+ conceivably have been incorporated into the glyph's instantiator.
+ The rarely used glyph types (buffer, pointer, icon) could also
+ have been incorporated into the instantiator.
+
+ Image instantiators come in many formats: `xbm', `xpm', `gif',
+`jpeg', etc. This describes the format of the data describing the
+image. The resulting image instances also come in many
+types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This
+refers to the behavior of the image and the sorts of places it can
+appear. (For example, a color-pixmap image has fixed colors specified
+for it, while a mono-pixmap image comes in two unspecified shades
+"foreground" and "background" that are determined from the face of the
+glyph or surrounding text; a text image appears as a string of text and
+has an unspecified foreground, background, and font; a pointer image
+behaves like a mono-pixmap image but can only be used as a mouse
+pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
+is important to keep the distinction between image instantiator format
+and image instance type in mind. Typically, a given image instantiator
+format can result in many different image instance types (for example,
+`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
+whereas `cursor-font' can be instanced only as `pointer'), and a
+particular image instance type can be generated by many different image
+instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
+`gif', `jpeg', etc.).
+
+ *Note Image Instances::, for a more detailed discussion of image
+instance types.
+
+ An image instantiator should be a string or a vector of the form
+
+ `[FORMAT :KEYWORD VALUE ...]'
+
+ i.e. a format symbol followed by zero or more alternating
+keyword-value pairs. The "format" field should be a symbol, one of
+
+`nothing'
+ Don't display anything; no keywords are valid for this. Can only
+ be instanced as `nothing'.
+
+`string'
+ Display this image as a text string. Can only be instanced as
+ `text', although support for instancing as `mono-pixmap' should be
+ added.
+
+`formatted-string'
+ Display this image as a text string with replaceable fields,
+ similar to a modeline format string; not currently implemented.
+
+`xbm'
+ An X bitmap; only if X support was compiled into this XEmacs. Can
+ be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+
+`xpm'
+ An XPM pixmap; only if XPM support was compiled into this XEmacs.
+ Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
+ XPM is an add-on library for X that was designed to rectify the
+ shortcomings of the XBM format. Most implementations of X include
+ the XPM library as a standard part. If your vendor does not, it
+ is highly recommended that you download it and install it. You
+ can get it from the standard XEmacs FTP site, among other places.
+
+`xface'
+ An X-Face bitmap, used to encode people's faces in e-mail messages;
+ only if X-Face support was compiled into this XEmacs. Can be
+ instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+
+`gif'
+ A GIF87 or GIF89 image; only if GIF support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
+ includes GIF decoding functions as a standard part of it, so if
+ you have X support, you will normally have GIF support, unless you
+ explicitly disable it at configure time.
+
+`jpeg'
+ A JPEG-format image; only if JPEG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
+ libraries present on your system when XEmacs is built, XEmacs will
+ automatically detect this and use them, unless you explicitly
+ disable it at configure time.
+
+`png'
+ A PNG/GIF24 image; only if PNG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'.
+
+`tiff'
+ A TIFF-format image; only if TIFF support was compiled into this
+ XEmacs.
+
+`cursor-font'
+ One of the standard cursor-font names, such as `watch' or
+ `right_ptr' under X. Under X, this is, more specifically, any of
+ the standard cursor names from appendix B of the Xlib manual [also
+ known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
+ other window systems, the valid names will be specific to the type
+ of window system. Can only be instanced as `pointer'.
+
+`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.
+
+`mswindows-resource'
+ An MS Windows pointer resource. Specifies a resource to retrieve
+ directly from the system (an OEM resource) or from a file,
+ particularly an executable file. If the resource is to be
+ retrieved from a file, use :file and optionally :resource-id.
+ Otherwise use :resource-id. Always specify :resource-type to
+ specify the type (cursor, bitmap or icon) of the resource.
+ Possible values for :resource-id are listed below. Can be
+ instanced as `pointer' or `color-pixmap'.
+
+`subwindow'
+ An embedded windowing system window. Can only be instanced as
+ `subwindow'.
+
+`button'
+ A button widget; either a push button, radio button or toggle
+ button. Can only be instanced as `widget'.
+
+`combo-box'
+ A drop list of selectable items in a widget, for editing text.
+ Can only be instanced as `widget'.
+
+`edit-field'
+ A text editing widget. Can only be instanced as `widget'.
+
+`label'
+ A static, text-only, widget; for displaying text. Can only be
+ instanced as `widget'.
+
+`layout'
+ A widget for controlling the positioning of children underneath it.
+ Through the use of nested layouts, a widget hierarchy can be
+ created which can have the appearance of any standard dialog box
+ or similar arrangement; all of this is counted as one "glyph" and
+ could appear in many of the places that expect a single glyph.
+ Can only be instanced as `widget'.
+
+`native-layout'
+ The native version of a layout widget. Can only be instanced as
+ `widget'.
+
+`progress-gauge'
+ A sliding widget, for showing progress. Can only be instanced as
+ `widget'.
+
+`tab-control'
+ A tab widget; a series of user selectable tabs. Can only be
+ instanced as `widget'.
+
+`tree-view'
+ A folding widget. Can only be instanced as `widget'.
+
+`scrollbar'
+ A scrollbar widget. Can only be instanced as `widget'.
+
+`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.
+
+`inherit'
+ Inherit from the background-pixmap property of a face. Can only be
+ instanced as `mono-pixmap'.
+
+ 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.
+
+`:resource-id'
+ Only for `mswindows-resource'. This must be either an integer
+ (which directly specifies a resource number) or a string. Valid
+ strings are
+
+ For bitmaps:
+
+ "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce",
+ "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd",
+ "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo",
+ "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize",
+ "check", "checkboxes", and "btncorners".
+
+ For cursors:
+
+ "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw",
+ "sizewe", "sizens", "sizeall", and "no".
+
+ For icons:
+
+ "sample", "hand", "ques", "bang", "note", and "winlogo".
+
+`:resource-type'
+ Only for `mswindows-resource'. This must be a symbol, either
+ `cursor', `icon', or `bitmap', specifying the type of resource to
+ be retrieved.
+
+`:face'
+ Only for `inherit'. This specifies the face to inherit from. For
+ widgets this also specifies the face to use for display. It
+ defaults to gui-element-face.
+
+ Keywords accepted as menu item specs are also accepted by widgets.
+These are `:selected', `:active', `:suffix', `:keys', `:style',
+`:filter', `:config', `:included', `:key-sequence', `:accelerator',
+`:label' and `:callback'.
+
+ 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 &optional locale
+ This function returns non-`nil' if FORMAT is a valid image
+ instantiator format.
+
+ If LOCALE is non-`nil' then the format is checked in that locale.
+ If LOCALE is `nil' the current console is used.
+
+ 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).
- - 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.
+\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.
- - Function: annotation-face annotation
- This function returns the face associated with ANNOTATION.
+\1f
+File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
- - Function: set-annotation-face annotation face
- This function sets the face associated with ANNOTATION to FACE.
+Image Instances
+---------------
- - Function: annotation-layout annotation
- This function returns the layout policy of ANNOTATION.
+ Image-instance objects encapsulate the way a particular image
+(pixmap, etc.) is displayed on a particular device.
- - Function: set-annotation-layout annotation layout
- This function sets the layout policy of ANNOTATION to LAYOUT.
+ 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.
- - 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: image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance.
- - Function: annotation-data annotation
- This function returns the data associated with ANNOTATION.
+* Menu:
- - Function: set-annotation-data annotation data
- This function sets the data field of ANNOTATION to DATA. DATA is
- returned.
+* Image Instance Types:: Each image instances has a particular type.
+* Image Instance Functions:: Functions for working with image instances.
- - Function: annotation-action annotation
- This function returns the action associated with ANNOTATION.
+\1f
+File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
- - Function: set-annotation-action annotation action
- This function sets the action field of ANNOTATION to ACTION.
- ACTION is returned..
+Image Instance Types
+....................
- - Function: annotation-menu annotation
- This function returns the menu associated with ANNOTATION.
+ Image instances come in a number of different types. The type of an
+image instance specifies the nature of the image: Whether it is a text
+string, a mono pixmap, a color pixmap, etc.
- - Function: 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.
+ The valid image instance types are
- - Function: annotation-visible annotation
- This function returns `t' if there is enough available space to
- display ANNOTATION, `nil' otherwise.
+`nothing'
+ Nothing is displayed.
- - Function: annotation-width annotation
- This function returns the width of ANNOTATION in pixels.
+`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: hide-annotation annotation
- This function removes ANNOTATION's glyph, making it invisible.
+`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).
- - Function: reveal-annotation annotation
- This function restores ANNOTATION's glyph, making it visible.
+`color-pixmap'
+ Displayed as a color pixmap.
-\1f
-File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
+`pointer'
+ Used as the mouse pointer for a window.
-Locating Annotations
-====================
+`subwindow'
+ A child window that is treated as an image. This allows (e.g.)
+ another program to be responsible for drawing into the window.
+ Not currently implemented.
- - Function: annotations-in-region start end buffer
- This function returns a list of all annotations in BUFFER which
- are between START and END inclusively.
+ - Function: valid-image-instance-type-p type
+ This function returns non-`nil' if TYPE is a valid image instance
+ type.
- - 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: image-instance-type-list
+ This function returns a list of the valid image instance types.
- - 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: image-instance-type image-instance
+ This function returns the type of the given image instance. The
+ return value will be one of `nothing', `text', `mono-pixmap',
+ `color-pixmap', `pointer', or `subwindow'.
- - Function: all-annotations
- This function returns a list of all annotations in all buffers in
- existence.
+ - Function: text-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `text'.
-\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.
+ - Function: mono-pixmap-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `mono-pixmap'.
-\1f
-File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
+ - Function: color-pixmap-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `color-pixmap'.
-Annotation Hooks
-================
+ - Function: pointer-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `pointer'.
- The following three hooks are provided for use with the marginal
-annotations:
+ - Function: subwindow-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `subwindow'.
-`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: nothing-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `nothing'.
-`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.
+ - Function: widget-image-instance-p object
+ Return `t' if OBJECT is an image instance of type `widget'.
\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.
-
-* 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.
+File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
+
+Image Instance Functions
+........................
+
+ - Function: make-image-instance data &optional domain dest-types
+ noerror
+ 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). For MS Windows
+ resources, the most natural type for pointer resources is
+ `pointer', and for the others it's `color-pixmap'. 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.
+
+ DOMAIN specifies the domain to which the image instance will be
+ attached. This domain is termed the "governing domain". The type
+ of the governing domain depends on the image instantiator format.
+ (Although, more correctly, it should probably depend on the image
+ instance type.) For example, pixmap image instances are specific
+ to a device, but widget image instances are specific to a
+ particular XEmacs window because in order to display such a widget
+ when two windows onto the same buffer want to display the widget,
+ two separate underlying widgets must be created. (That's because a
+ widget is actually a child window-system window, and all
+ window-system windows have a unique existence on the screen.) This
+ means that the governing domain for a pixmap image instance will
+ be some device (most likely, the only existing device), whereas
+ the governing domain for a widget image instance will be some
+ XEmacs window.
+
+ If you specify an overly general DOMAIN (e.g. a frame when a
+ window was wanted), an error is signaled. If you specify an overly
+ specific DOMAIN (e.g. a window when a device was wanted), the
+ corresponding general domain is fetched and used instead. For
+ `make-image-instance', it makes no difference whether you specify
+ an overly specific domain or the properly general domain derived
+ from it. However, it does matter when creating an image instance
+ by instantiating a specifier or glyph (e.g. with
+ `glyph-image-instance'), because the more specific domain causes
+ spec lookup to start there and proceed to more general domains. (It
+ would also matter when creating an image instance with an
+ instantiator format of `inherit', but we currently disallow this.
+ #### We should fix this.) n If omitted, DOMAIN defaults to the
+ selected window.
+
+ NOERROR 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-domain image-instance
+ Return the governing domain of the given IMAGE-INSTANCE. The
+ governing domain of an image instance is the domain that the image
+ instance is specific to. It is _NOT_ necessarily the domain that
+ was given to the call to `specifier-instance' that resulted in the
+ creation of this image instance. See `make-image-instance' for
+ more information on governing domains.
+
+ - 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.)
\1f
-File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
-
-Refreshing the Screen
-=====================
+File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
- The function `redraw-frame' redisplays the entire contents of a
-given frame. *Note Frames::.
+Glyph Types
+===========
- - Function: redraw-frame frame
- This function clears and redisplays frame FRAME.
+ 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.
- Even more powerful is `redraw-display':
+ * `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'.
- - 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.
+ * `pointer' glyphs can be used to specify the mouse pointer. Their
+ image can be instantiated as `pointer'.
- 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.
+ * `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'.
- 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::.
+ - 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'.
- - 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.
+ - Function: valid-glyph-type-p glyph-type
+ Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
- 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::.
+ - Function: glyph-type-list
+ This function returns a list of valid glyph types.
- - 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.)
+ - Function: buffer-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `buffer'.
-\1f
-File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
-
-Truncation
-==========
+ - Function: icon-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `icon'.
- 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: pointer-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `pointer'.
\1f
-File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
+File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
-The Echo Area
+Mouse Pointer
=============
- The "echo area" is used for displaying messages made with the
-`message' primitive, and for echoing keystrokes. It is not the same as
-the minibuffer, despite the fact that the minibuffer appears (when
-active) in the same place on the screen as the echo area. The `XEmacs
-Reference Manual' specifies the rules for resolving conflicts between
-the echo area and the minibuffer for use of that screen space (*note
-The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo
-area; see *Note Errors::.
-
- You can write output in the echo area by using the Lisp printing
-functions with `t' as the stream (*note Output Functions::), or as
-follows:
-
- - Function: message string &rest arguments
- This function displays a one-line message in the echo area. The
- argument STRING is similar to a C language `printf' control
- string. See `format' in *Note String Conversion::, for the details
- on the conversion specifications. `message' returns the
- constructed string.
-
- In batch mode, `message' prints the message text on the standard
- error stream, followed by a newline.
-
- If STRING is `nil', `message' clears the echo area. If the
- minibuffer is active, this brings the minibuffer contents back onto
- the screen immediately.
-
- (message "Minibuffer depth is %d."
- (minibuffer-depth))
- -| Minibuffer depth is 0.
- => "Minibuffer depth is 0."
-
- ---------- Echo Area ----------
- Minibuffer depth is 0.
- ---------- Echo Area ----------
-
- In addition to only displaying a message, XEmacs allows you to
-"label" your messages, giving you fine-grained control of their
-display. Message label is a symbol denoting the message type. Some
-standard labels are:
-
- * `message'--default label used by the `message' function;
-
- * `error'--default label used for reporting errors;
-
- * `progress'--progress indicators like `Converting... 45%' (not
- logged by default);
-
- * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
- default);
-
- * `command'--helper command messages like `Mark set' (not logged by
- default);
-
- * `no-log'--messages that should never be logged
-
- Several messages may be stacked in the echo area at once. Lisp
-programs may access these messages, or remove them as appropriate, via
-the message stack.
-
- - Function: display-message label message &optional frame stdout-p
- This function displays MESSAGE (a string) labeled as LABEL, as
- described above.
-
- The FRAME argument specifies the frame to whose minibuffer the
- message should be printed. This is currently unimplemented. The
- STDOUT-P argument is used internally.
-
- (display-message 'command "Mark set")
-
- - Function: lmessage label string &rest arguments
- This function displays a message STRING with label LABEL. It is
- similar to `message' in that it accepts a `printf'-like strings
- and any number of arguments.
-
- ;; Display a command message.
- (lmessage 'command "Comment column set to %d" comment-column)
-
- ;; Display a progress message.
- (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
-
- ;; Display a message that should not be logged.
- (lmessage 'no-log "Done")
-
- - Function: clear-message &optional label frame stdout-p no-restore
- This function remove any message with the given LABEL from the
- message-stack, erasing it from the echo area if it's currently
- displayed there.
-
- If a message remains at the head of the message-stack and
- NO-RESTORE is `nil', it will be displayed. The string which
- remains in the echo area will be returned, or `nil' if the
- message-stack is now empty. If LABEL is nil, the entire
- message-stack is cleared.
-
- ;; Show a message, wait for 2 seconds, and restore old minibuffer
- ;; contents.
- (message "A message")
- -| A message
- => "A Message"
- (lmessage 'my-label "Newsflash! Newsflash!")
- -| Newsflash! Newsflash!
- => "Newsflash! Newsflash!"
- (sit-for 2)
- (clear-message 'my-label)
- -| A message
- => "A message"
-
- Unless you need the return value or you need to specify a label,
- you should just use `(message nil)'.
-
- - Function: current-message &optional frame
- This function returns the current message in the echo area, or
- `nil'. The FRAME argument is currently unused.
-
- Some of the messages displayed in the echo area are also recorded in
-the ` *Message-Log*' buffer. Exactly which messages will be recorded
-can be tuned using the following variables.
-
- - User Option: log-message-max-size
- This variable specifies the maximum size of the ` *Message-log*'
- buffer.
-
- - Variable: log-message-ignore-labels
- This variable specifies the labels whose messages will not be
- logged. It should be a list of symbols.
-
- - Variable: log-message-ignore-regexps
- This variable specifies the regular expressions matching messages
- that will not be logged. It should be a list of regular
- expressions.
-
- Normally, packages that generate messages that might need to be
- ignored should label them with `progress', `prompt', or `no-log',
- so they can be filtered by `log-message-ignore-labels'.
-
- - Variable: echo-keystrokes
- This variable determines how much time should elapse before command
- characters echo. Its value must be a number, which specifies the
- number of seconds to wait before echoing. If the user types a
- prefix key (such as `C-x') and then delays this many seconds
- before continuing, the prefix key is echoed in the echo area. Any
- subsequent characters in the same command will be echoed as well.
-
- If the value is zero, then command input is not echoed.
-
- - Variable: cursor-in-echo-area
- This variable controls where the cursor appears when a message is
- displayed in the echo area. If it is non-`nil', then the cursor
- appears at the end of the message. Otherwise, the cursor appears
- at point--not in the echo area at all.
-
- The value is normally `nil'; Lisp programs bind it to `t' for
- brief periods of time.
-
-\1f
-File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
-
-Warnings
-========
-
- XEmacs contains a facility for unified display of various warnings.
-Unlike errors, warnings are displayed in the situations when XEmacs
-encounters a problem that is recoverable, but which should be fixed for
-safe future operation.
-
- For example, warnings are printed by the startup code when it
-encounters problems with X keysyms, when there is an error in `.emacs',
-and in other problematic situations. Unlike messages, warnings are
-displayed in a separate buffer, and include an explanatory message that
-may span across several lines. Here is an example of how a warning is
-displayed:
-
- (1) (initialization/error) An error has occurred while loading ~/.emacs:
-
- Symbol's value as variable is void: bogus-variable
-
- To ensure normal operation, you should investigate the cause of the error
- in your initialization file and remove it. Use the `-debug-init' option
- to XEmacs to view a complete error backtrace.
-
- Each warning has a "class" and a "priority level". The class is a
-symbol describing what sort of warning this is, such as
-`initialization', `resource' or `key-mapping'.
-
- The warning priority level specifies how important the warning is.
-The recognized warning levels, in increased order of priority, are:
-`debug', `info', `notice', `warning', `error', `critical', `alert' and
-`emergency'.
-
- - Function: display-warning class message &optional level
- This function displays a warning message MESSAGE (a string).
- CLASS should be a warning class symbol, as described above, or a
- list of such symbols. LEVEL describes the warning priority level.
- If unspecified, it default to `warning'.
-
- (display-warning 'resource
- "Bad resource specification encountered:
- something like
-
- Emacs*foo: bar
-
- You should replace the * with a . in order to get proper behavior when
- you use the specifier and/or `set-face-*' functions.")
-
- ---------- Warning buffer ----------
- (1) (resource/warning) Bad resource specification encountered:
- something like
-
- Emacs*foo: bar
-
- You should replace the * with a . in order to get proper behavior when
- you use the specifier and/or `set-face-*' functions.
- ---------- Warning buffer ----------
-
- - Function: lwarn class level message &rest args
- This function displays a formatted labeled warning message. As
- above, CLASS should be the warning class symbol, or a list of such
- symbols, and LEVEL should specify the warning priority level
- (`warning' by default).
-
- Unlike in `display-warning', MESSAGE may be a formatted message,
- which will be, together with the rest of the arguments, passed to
- `format'.
-
- (lwarn 'message-log 'warning
- "Error caught in `remove-message-hook': %s"
- (error-message-string e))
-
- - Variable: log-warning-minimum-level
- This variable specifies the minimum level of warnings that should
- be generated. Warnings with level lower than defined by this
- variable are completely ignored, as if they never happened.
-
- - Variable: display-warning-minimum-level
- This variable specifies the minimum level of warnings that should
- be displayed. Unlike `log-warning-minimum-level', setting this
- function does not suppress warnings entirely--they are still
- generated in the `*Warnings*' buffer, only they are not displayed
- by default.
-
- - Variable: log-warning-suppressed-classes
- This variable specifies a list of classes that should not be
- logged or displayed. If any of the class symbols associated with
- a warning is the same as any of the symbols listed here, the
- warning will be completely ignored, as it they never happened.
-
- - Variable: display-warning-suppressed-classes
- This variable specifies a list of classes that should not be
- logged or displayed. If any of the class symbols associated with
- a warning is the same as any of the symbols listed here, the
- warning will not be displayed. The warning will still logged in
- the *Warnings* buffer (unless also contained in
- `log-warning-suppressed-classes'), but the buffer will not be
- automatically popped up.
-
-\1f
-File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
-
-Invisible Text
-==============
-
- You can make characters "invisible", so that they do not appear on
-the screen, with the `invisible' property. This can be either a text
-property or a property of an overlay.
-
- In the simplest case, any non-`nil' `invisible' property makes a
-character invisible. This is the default case--if you don't alter the
-default value of `buffer-invisibility-spec', this is how the
-`invisibility' property works. This feature is much like selective
-display (*note Selective Display::), but more general and cleaner.
-
- More generally, you can use the variable `buffer-invisibility-spec'
-to control which values of the `invisible' property make text
-invisible. This permits you to classify the text into different subsets
-in advance, by giving them different `invisible' values, and
-subsequently make various subsets visible or invisible by changing the
-value of `buffer-invisibility-spec'.
-
- Controlling visibility with `buffer-invisibility-spec' is especially
-useful in a program to display the list of entries in a data base. It
-permits the implementation of convenient filtering commands to view
-just a part of the entries in the data base. Setting this variable is
-very fast, much faster than scanning all the text in the buffer looking
-for properties to change.
-
- - Variable: buffer-invisibility-spec
- This variable specifies which kinds of `invisible' properties
- actually make a character invisible.
-
- `t'
- A character is invisible if its `invisible' property is
- non-`nil'. This is the default.
-
- a list
- Each element of the list makes certain characters invisible.
- Ultimately, a character is invisible if any of the elements
- of this list applies to it. The list can have two kinds of
- elements:
-
- `ATOM'
- A character is invisible if its `invisible' property
- value is ATOM or if it is a list with ATOM as a member.
-
- `(ATOM . t)'
- A character is invisible if its `invisible' property
- value is ATOM or if it is a list with ATOM as a member.
- Moreover, if this character is at the end of a line and
- is followed by a visible newline, it displays an
- ellipsis.
-
- Ordinarily, commands that operate on text or move point do not care
-whether the text is invisible. However, the user-level line motion
-commands explicitly ignore invisible newlines.
-
-\1f
-File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
-
-Selective Display
-=================
-
- "Selective display" is a pair of features that hide certain lines on
-the screen.
-
- The first variant, explicit selective display, is designed for use in
-a Lisp program. The program controls which lines are hidden by altering
-the text. Outline mode has traditionally used this variant. It has
-been partially replaced by the invisible text feature (*note Invisible
-Text::); there is a new version of Outline mode which uses that instead.
-
- In the second variant, the choice of lines to hide is made
-automatically based on indentation. This variant is designed to be a
-user-level feature.
-
- The way you control explicit selective display is by replacing a
-newline (control-j) with a carriage return (control-m). The text that
-was formerly a line following that newline is now invisible. Strictly
-speaking, it is temporarily no longer a line at all, since only newlines
-can separate lines; it is now part of the previous line.
-
- Selective display does not directly affect editing commands. For
-example, `C-f' (`forward-char') moves point unhesitatingly into
-invisible text. However, the replacement of newline characters with
-carriage return characters affects some editing commands. For example,
-`next-line' skips invisible lines, since it searches only for newlines.
-Modes that use selective display can also define commands that take
-account of the newlines, or that make parts of the text visible or
-invisible.
-
- When you write a selectively displayed buffer into a file, all the
-control-m's are output as newlines. This means that when you next read
-in the file, it looks OK, with nothing invisible. The selective display
-effect is seen only within XEmacs.
-
- - Variable: selective-display
- This buffer-local variable enables selective display. This means
- that lines, or portions of lines, may be made invisible.
-
- * If the value of `selective-display' is `t', then any portion
- of a line that follows a control-m is not displayed.
-
- * If the value of `selective-display' is a positive integer,
- then lines that start with more than that many columns of
- indentation are not displayed.
-
- When some portion of a buffer is invisible, the vertical movement
- commands operate as if that portion did not exist, allowing a
- single `next-line' command to skip any number of invisible lines.
- However, character movement commands (such as `forward-char') do
- not skip the invisible portion, and it is possible (if tricky) to
- insert or delete text in an invisible portion.
-
- In the examples below, we show the _display appearance_ of the
- buffer `foo', which changes with the value of `selective-display'.
- The _contents_ of the buffer do not change.
-
- (setq selective-display nil)
- => nil
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column
- 3n this column
- 3n this column
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- (setq selective-display 2)
- => 2
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- - Variable: selective-display-ellipses
- If this buffer-local variable is non-`nil', then XEmacs displays
- `...' at the end of a line that is followed by invisible text.
- This example is a continuation of the previous one.
-
- (setq selective-display-ellipses t)
- => t
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column ...
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- You can use a display table to substitute other text for the
- ellipsis (`...'). *Note Display Tables::.
+ The shape of the mouse pointer when over a particular section of a
+frame is controlled using various glyph variables. Since the image of
+a glyph is a specifier, it can be controlled on a per-buffer,
+per-frame, per-window, or per-device basis.
+
+ You should use `set-glyph-image' to set the following variables,
+_not_ `setq'.
+
+ - Glyph: text-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ text.
+
+ - Glyph: nontext-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ buffer, but not over text. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
+
+ - Glyph: modeline-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the modeline. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
+
+ - Glyph: selection-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ selectable text region. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
+
+ - Glyph: gc-pointer-glyph
+ This variable specifies the shape of the mouse pointer when a
+ garbage collection is in progress. If the selected window is on a
+ window system and this glyph specifies a value (i.e. a pointer
+ image instance) in the domain of the selected window, the pointer
+ will be changed as specified during garbage collection.
+ Otherwise, a message will be printed in the echo area, as
+ controlled by `gc-message'.
+
+ - Glyph: busy-pointer-glyph
+ This variable specifies the shape of the mouse pointer when XEmacs
+ is busy. If unspecified in a particular domain, the pointer is
+ not changed when XEmacs is busy.
+
+ - Glyph: menubar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the menubar. If unspecified in a particular domain, the
+ window-system-provided default pointer is used.
+
+ - Glyph: scrollbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ scrollbar. If unspecified in a particular domain, the
+ window-system-provided default pointer is used.
+
+ - Glyph: toolbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ toolbar. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
+
+ Internally, these variables are implemented in
+`default-mouse-motion-handler', and thus only take effect when the
+mouse moves. That function calls `set-frame-pointer', which sets the
+current mouse pointer for a frame.
+
+ - Function: set-frame-pointer frame image-instance
+ This function sets the mouse pointer of FRAME to the given pointer
+ image instance. You should not call this function directly. (If
+ you do, the pointer will change again the next time the mouse
+ moves.)
\1f
-File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
+File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
-The Overlay Arrow
-=================
-
- The "overlay arrow" is useful for directing the user's attention to
-a particular line in a buffer. For example, in the modes used for
-interface to debuggers, the overlay arrow indicates the line of code
-about to be executed.
+Redisplay Glyphs
+================
- - Variable: overlay-arrow-string
- This variable holds the string to display to call attention to a
- particular line, or `nil' if the arrow feature is not in use.
- Despite its name, the value of this variable can be either a string
- or a glyph (*note Glyphs::).
+ - Glyph: truncation-glyph
+ This variable specifies what is displayed at the end of truncated
+ lines.
- - Variable: overlay-arrow-position
- This variable holds a marker that indicates where to display the
- overlay arrow. It should point at the beginning of a line. The
- arrow text appears at the beginning of that line, overlaying any
- text that would otherwise appear. Since the arrow is usually
- short, and the line usually begins with indentation, normally
- nothing significant is overwritten.
+ - Glyph: continuation-glyph
+ This variable specifies what is displayed at the end of wrapped
+ lines.
- The overlay string is displayed only in the buffer that this marker
- points into. Thus, only one buffer can have an overlay arrow at
- any given time.
+ - Glyph: octal-escape-glyph
+ This variable specifies what to prefix character codes displayed
+ in octal with.
- You can do the same job by creating an extent with a `begin-glyph'
-property. *Note Extent Properties::.
+ - Glyph: hscroll-glyph
+ This variable specifies what to display at the beginning of
+ horizontally scrolled lines.
-\1f
-File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
-
-Temporary Displays
-==================
-
- Temporary displays are used by commands to put output into a buffer
-and then present it to the user for perusal rather than for editing.
-Many of the help commands use this feature.
-
- - Special Form: with-output-to-temp-buffer buffer-name forms...
- This function executes FORMS while arranging to insert any output
- they print into the buffer named BUFFER-NAME. The buffer is then
- shown in some window for viewing, displayed but not selected.
-
- The string BUFFER-NAME specifies the temporary buffer, which need
- not already exist. The argument must be a string, not a buffer.
- The buffer is erased initially (with no questions asked), and it is
- marked as unmodified after `with-output-to-temp-buffer' exits.
-
- `with-output-to-temp-buffer' binds `standard-output' to the
- temporary buffer, then it evaluates the forms in FORMS. Output
- using the Lisp output functions within FORMS goes by default to
- that buffer (but screen display and messages in the echo area,
- although they are "output" in the general sense of the word, are
- not affected). *Note Output Functions::.
-
- The value of the last form in FORMS is returned.
-
- ---------- Buffer: foo ----------
- This is the contents of foo.
- ---------- Buffer: foo ----------
-
- (with-output-to-temp-buffer "foo"
- (print 20)
- (print standard-output))
- => #<buffer foo>
-
- ---------- Buffer: foo ----------
- 20
-
- #<buffer foo>
-
- ---------- Buffer: foo ----------
-
- - Variable: temp-buffer-show-function
- If this variable is non-`nil', `with-output-to-temp-buffer' calls
- it as a function to do the job of displaying a help buffer. The
- function gets one argument, which is the buffer it should display.
-
- In Emacs versions 18 and earlier, this variable was called
- `temp-buffer-show-hook'.
-
- - Function: momentary-string-display string position &optional char
- message
- This function momentarily displays STRING in the current buffer at
- POSITION. It has no effect on the undo list or on the buffer's
- modification status.
-
- The momentary display remains until the next input event. If the
- next input event is CHAR, `momentary-string-display' ignores it
- and returns. Otherwise, that event remains buffered for
- subsequent use as input. Thus, typing CHAR will simply remove the
- string from the display, while typing (say) `C-f' will remove the
- string from the display and later (presumably) move point forward.
- The argument CHAR is a space by default.
-
- The return value of `momentary-string-display' is not meaningful.
-
- You can do the same job in a more general way by creating an extent
- with a begin-glyph property. *Note Extent Properties::.
-
- If MESSAGE is non-`nil', it is displayed in the echo area while
- STRING is displayed in the buffer. If it is `nil', a default
- message says to type CHAR to continue.
-
- In this example, point is initially located at the beginning of the
- second line:
-
- ---------- Buffer: foo ----------
- This is the contents of foo.
- -!-Second line.
- ---------- Buffer: foo ----------
-
- (momentary-string-display
- "**** Important Message! ****"
- (point) ?\r
- "Type RET when done reading")
- => t
-
- ---------- Buffer: foo ----------
- This is the contents of foo.
- **** Important Message! ****Second line.
- ---------- Buffer: foo ----------
-
- ---------- Echo Area ----------
- Type RET when done reading
- ---------- Echo Area ----------
-
- This function works by actually changing the text in the buffer.
- As a result, if you later undo in this buffer, you will see the
- message come and go.
+ - 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
+ ("...").
-\1f
-File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
-
-Blinking Parentheses
-====================
-
- This section describes the mechanism by which XEmacs shows a matching
-open parenthesis when the user inserts a close parenthesis.
-
- - Variable: blink-paren-function
- The value of this variable should be a function (of no arguments)
- to be called whenever a character with close parenthesis syntax is
- inserted. The value of `blink-paren-function' may be `nil', in
- which case nothing is done.
-
- *Please note:* This variable was named `blink-paren-hook' in
- older Emacs versions, but since it is not called with the
- standard convention for hooks, it was renamed to
- `blink-paren-function' in version 19.
-
- - Variable: blink-matching-paren
- If this variable is `nil', then `blink-matching-open' does nothing.
-
- - Variable: blink-matching-paren-distance
- This variable specifies the maximum distance to scan for a matching
- parenthesis before giving up.
-
- - Variable: blink-matching-paren-delay
- This variable specifies the number of seconds for the cursor to
- remain at the matching parenthesis. A fraction of a second often
- gives good results, but the default is 1, which works on all
- systems.
-
- - Function: blink-matching-open
- This function is the default value of `blink-paren-function'. It
- assumes that point follows a character with close parenthesis
- syntax and moves the cursor momentarily to the matching opening
- character. If that character is not already on the screen, it
- displays the character's context in the echo area. To avoid long
- delays, this function does not search farther than
- `blink-matching-paren-distance' characters.
-
- Here is an example of calling this function explicitly.
-
- (defun interactive-blink-matching-open ()
- "Indicate momentarily the start of sexp before point."
- (interactive)
- (let ((blink-matching-paren-distance
- (buffer-size))
- (blink-matching-paren t))
- (blink-matching-open)))
+ - Glyph: control-arrow-glyph
+ This variable specifies what to use as an arrow for control
+ characters.
\1f
-File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
-
-Usual Display Conventions
-=========================
-
- The usual display conventions define how to display each character
-code. You can override these conventions by setting up a display table
-(*note Display Tables::). Here are the usual display conventions:
-
- * Character codes 32 through 126 map to glyph codes 32 through 126.
- Normally this means they display as themselves.
-
- * Character code 9 is a horizontal tab. It displays as whitespace
- up to a position determined by `tab-width'.
-
- * Character code 10 is a newline.
-
- * All other codes in the range 0 through 31, and code 127, display
- in one of two ways according to the value of `ctl-arrow'. If it is
- non-`nil', these codes map to sequences of two glyphs, where the
- first glyph is the ASCII code for `^'. (A display table can
- specify a glyph to use instead of `^'.) Otherwise, these codes map
- just like the codes in the range 128 to 255.
-
- * Character codes 128 through 255 map to sequences of four glyphs,
- where the first glyph is the ASCII code for `\', and the others are
- digit characters representing the code in octal. (A display table
- can specify a glyph to use instead of `\'.)
-
- The usual display conventions apply even when there is a display
-table, for any character whose entry in the active display table is
-`nil'. Thus, when you set up a display table, you need only specify
-the characters for which you want unusual behavior.
-
- These variables affect the way certain characters are displayed on
-the screen. Since they change the number of columns the characters
-occupy, they also affect the indentation functions.
+File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
- - User Option: ctl-arrow
- This buffer-local variable controls how control characters are
- displayed. If it is non-`nil', they are displayed as a caret
- followed by the character: `^A'. If it is `nil', they are
- displayed as a backslash followed by three octal digits: `\001'.
+Subwindows
+==========
- - Variable: default-ctl-arrow
- The value of this variable is the default value for `ctl-arrow' in
- buffers that do not override it. *Note Default Value::.
+ Subwindows are not currently implemented.
- - User Option: tab-width
- The value of this variable is the spacing between tab stops used
- for displaying tab characters in Emacs buffers. The default is 8.
- Note that this feature is completely independent from the
- user-settable tab stops used by the command `tab-to-tab-stop'.
- *Note Indent Tabs::.
+ - Function: subwindowp object
+ This function returns non-`nil' if OBJECT is a subwindow.
\1f
-File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
-
-Display Tables
-==============
+File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
- You can use the "display table" feature to control how all 256
-possible character codes display on the screen. This is useful for
-displaying European languages that have letters not in the ASCII
-character set.
+Annotations
+***********
- The display table maps each character code into a sequence of
-"runes", each rune being an image that takes up one character position
-on the screen. You can also define how to display each rune on your
-terminal, using the "rune table".
+ 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.
* Menu:
-* Display Table Format:: What a display table consists of.
-* Active Display Table:: How XEmacs selects a display table to use.
-* Character Descriptors:: Format of an individual element of a
- display table.
-
-\1f
-File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
-
-Display Table Format
---------------------
-
- A display table is an array of 256 elements. (In FSF Emacs, a display
-table is 262 elements. The six extra elements specify the truncation
-and continuation glyphs, etc. This method is very kludgey, and in
-XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
-used. *Note Truncation::.)
-
- - Function: make-display-table
- This creates and returns a display table. The table initially has
- `nil' in all elements.
-
- The 256 elements correspond to character codes; the Nth element says
-how to display the character code N. The value should be `nil', a
-string, a glyph, or a vector of strings and glyphs (*note Character
-Descriptors::). If an element is `nil', it says to display that
-character according to the usual display conventions (*note Usual
-Display::).
-
- If you use the display table to change the display of newline
-characters, the whole buffer will be displayed as one long "line."
-
- For example, here is how to construct a display table that mimics the
-effect of setting `ctl-arrow' to a non-`nil' value:
-
- (setq disptab (make-display-table))
- (let ((i 0))
- (while (< i 32)
- (or (= i ?\t) (= i ?\n)
- (aset disptab i (concat "^" (char-to-string (+ i 64)))))
- (setq i (1+ i)))
- (aset disptab 127 "^?"))
-
-\1f
-File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
-
-Active Display Table
---------------------
-
- The active display table is controlled by the variable
-`current-display-table'. This is a specifier, which means that you can
-specify separate values for it in individual buffers, windows, frames,
-and devices, as well as a global value. It also means that you cannot
-set this variable using `setq'; use `set-specifier' instead. *Note
-Specifiers::. (FSF Emacs uses `window-display-table',
-`buffer-display-table', `standard-display-table', etc. to control the
-display table. However, specifiers are a cleaner and more powerful way
-of doing the same thing. FSF Emacs also uses a different format for
-the contents of a display table, using additional indirection to a
-"glyph table" and such. Note that "glyph" has a different meaning in
-XEmacs.)
-
- Individual faces can also specify an overriding display table; this
-is set using `set-face-display-table'. *Note Faces::.
-
- If no display table can be determined for a particular window, then
-XEmacs uses the usual display conventions. *Note Usual Display::.
-
-\1f
-File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
-
-Character Descriptors
----------------------
-
- Each element of the display-table vector describes how to display a
-particular character and is called a "character descriptor". A
-character descriptor can be:
-
-a string
- Display this particular string wherever the character is to be
- displayed.
-
-a glyph
- Display this particular glyph wherever the character is to be
- displayed.
-
-a vector
- The vector may contain strings and/or glyphs. Display the
- elements of the vector one after another wherever the character is
- to be displayed.
-
-`nil'
- Display according to the standard interpretation (*note Usual
- Display::).
+* 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.