This is Info file ../../info/lispref.info, produced by Makeinfo version 1.68 from the input file lispref.texi. Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995, 1996 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images Image Specifiers ---------------- An image specifier is used to describe the actual image of a glyph. It works like other specifiers (*note Specifiers::.), in that it contains a number of specifications describing how the image should appear in a variety of circumstances. These specifications are called "image instantiators". When XEmacs wants to display the image, it instantiates the image into an "image instance". Image instances are their own primitive object type (similar to font instances and color instances), describing how the image appears in a particular domain. (On the other hand, image instantiators, which are just descriptions of how the image should appear, are represented using strings or vectors.) - Function: image-specifier-p OBJECT This function returns non-`nil' if OBJECT is an image specifier. Usually, an image specifier results from calling `glyph-image' on a glyph. - Function: make-image-specifier SPEC-LIST This function creates a new image specifier object and initializes it according to SPEC-LIST. It is unlikely that you will ever want to do this, but this function is provided for completeness and for experimentation purposes. *Note Specifiers::. Image instantiators come in many formats: `xbm', `xpm', `gif', `jpeg', etc. This describes the format of the data describing the image. The resulting image instances also come in many types - `mono-pixmap', `color-pixmap', `text', `pointer', etc. This refers to the behavior of the image and the sorts of places it can appear. (For example, a color-pixmap image has fixed colors specified for it, while a mono-pixmap image comes in two unspecified shades "foreground" and "background" that are determined from the face of the glyph or surrounding text; a text image appears as a string of text and has an unspecified foreground, background, and font; a pointer image behaves like a mono-pixmap image but can only be used as a mouse pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It is important to keep the distinction between image instantiator format and image instance type in mind. Typically, a given image instantiator format can result in many different image instance types (for example, `xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer'; whereas `cursor-font' can be instanced only as `pointer'), and a particular image instance type can be generated by many different image instantiator formats (e.g. `color-pixmap' can be generated by `xpm', `gif', `jpeg', etc.). *Note Image Instances:: for a more detailed discussion of image instance types. An image instantiator should be a string or a vector of the form `[FORMAT :KEYWORD VALUE ...]' i.e. a format symbol followed by zero or more alternating keyword-value pairs. The "format" field should be a symbol, one of `nothing' (Don't display anything; no keywords are valid for this. Can only be instanced as `nothing'.) `string' (Display this image as a text string. Can only be instanced as `text', although support for instancing as `mono-pixmap' should be added.) `formatted-string' (Display this image as a text string with replaceable fields, similar to a modeline format string; not currently implemented.) `xbm' (An X bitmap; only if X support was compiled into this XEmacs. Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.) `xpm' (An XPM pixmap; only if XPM support was compiled into this XEmacs. Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'. XPM is an add-on library for X that was designed to rectify the shortcomings of the XBM format. Most implementations of X include the XPM library as a standard part. If your vendor does not, it is highly recommended that you download it and install it. You can get it from the standard XEmacs FTP site, among other places.) `xface' (An X-Face bitmap, used to encode people's faces in e-mail messages; only if X-Face support was compiled into this XEmacs. Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.) `gif' (A GIF87 or GIF89 image; only if GIF support was compiled into this XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs includes GIF decoding functions as a standard part of it, so if you have X support, you will normally have GIF support, unless you explicitly disable it at configure time.) `jpeg' (A JPEG-format image; only if JPEG support was compiled into this XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG libraries present on your system when XEmacs is built, XEmacs will automatically detect this and use them, unless you explicitly disable it at configure time.) `png' (A PNG/GIF24 image; only if PNG support was compiled into this XEmacs. Can be instanced as `color-pixmap'.) `tiff' (A TIFF-format image; only if TIFF support was compiled into this XEmacs. Not currently implemented.) `cursor-font' (One of the standard cursor-font names, such as `watch' or `right_ptr' under X. Under X, this is, more specifically, any of the standard cursor names from appendix B of the Xlib manual [also known as the file `'] minus the `XC_' prefix. On other window systems, the valid names will be specific to the type of window system. Can only be instanced as `pointer'.) `font' (A glyph from a font; i.e. the name of a font, and glyph index into it of the form `FONT fontname index [[mask-font] mask-index]'. Only if X support was compiled into this XEmacs. Currently can only be instanced as `pointer', although this should probably be fixed.) `subwindow' (An embedded X window; not currently implemented.) `autodetect' (XEmacs tries to guess what format the data is in. If X support exists, the data string will be checked to see if it names a filename. If so, and this filename contains XBM or XPM data, the appropriate sort of pixmap or pointer will be created. [This includes picking up any specified hotspot or associated mask file.] Otherwise, if `pointer' is one of the allowable image-instance types and the string names a valid cursor-font name, the image will be created as a pointer. Otherwise, the image will be displayed as text. If no X support exists, the image will always be displayed as text.) The valid keywords are: `:data' (Inline data. For most formats above, this should be a string. For XBM images, this should be a list of three elements: width, height, and a string of bit data. This keyword is not valid for instantiator format `nothing'.) `:file' (Data is contained in a file. The value is the name of this file. If both `:data' and `:file' are specified, the image is created from what is specified in `:data' and the string in `:file' becomes the value of the `image-instance-file-name' function when applied to the resulting image-instance. This keyword is not valid for instantiator formats `nothing', `string', `formatted-string', `cursor-font', `font', and `autodetect'.) `:foreground' `:background' (For `xbm', `xface', `cursor-font', and `font'. These keywords allow you to explicitly specify foreground and background colors. The argument should be anything acceptable to `make-color-instance'. This will cause what would be a `mono-pixmap' to instead be colorized as a two-color color-pixmap, and specifies the foreground and/or background colors for a pointer instead of black and white.) `:mask-data' (For `xbm' and `xface'. This specifies a mask to be used with the bitmap. The format is a list of width, height, and bits, like for `:data'.) `:mask-file' (For `xbm' and `xface'. This specifies a file containing the mask data. If neither a mask file nor inline mask data is given for an XBM image, and the XBM image comes from a file, XEmacs will look for a mask file with the same name as the image file but with `Mask' or `msk' appended. For example, if you specify the XBM file `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the associated mask file `left_ptrmsk' will automatically be picked up.) `:hotspot-x' `:hotspot-y' (For `xbm' and `xface'. These keywords specify a hotspot if the image is instantiated as a `pointer'. Note that if the XBM image file specifies a hotspot, it will automatically be picked up if no explicit hotspot is given.) `:color-symbols' (Only for `xpm'. This specifies an alist that maps strings that specify symbolic color names to the actual color to be used for that symbolic color (in the form of a string or a color-specifier object). If this is not specified, the contents of `xpm-color-symbols' are used to generate the alist.) If instead of a vector, the instantiator is a string, it will be converted into a vector by looking it up according to the specs in the `console-type-image-conversion-list' for the console type of the domain (usually a window; sometimes a frame or device) over which the image is being instantiated. If the instantiator specifies data from a file, the data will be read in at the time that the instantiator is added to the image specifier (which may be well before the image is actually displayed), and the instantiator will be converted into one of the inline-data forms, with the filename retained using a `:file' keyword. This implies that the file must exist when the instantiator is added to the image, but does not need to exist at any other time (e.g. it may safely be a temporary file). - Function: valid-image-instantiator-format-p FORMAT This function returns non-`nil' if FORMAT is a valid image instantiator format. Note that the return value for many formats listed above depends on whether XEmacs was compiled with support for that format. - Function: image-instantiator-format-list This function return a list of valid image-instantiator formats. - Variable: xpm-color-symbols This variable holds definitions of logical color-names used when reading XPM files. Elements of this list should be of the form `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a string, which is the name of the color to define; the FORM-TO-EVALUATE should evaluate to a color specifier object, or a string to be passed to `make-color-instance' (*note Colors::.). If a loaded XPM file references a symbolic color called COLOR-NAME, it will display as the computed color instead. The default value of this variable defines the logical color names `"foreground"' and `"background"' to be the colors of the `default' face. - Variable: x-bitmap-file-path A list of the directories in which X bitmap files may be found. If nil, this is initialized from the `"*bitmapFilePath"' resource. This is used by the `make-image-instance' function (however, note that if the environment variable `XBMLANGPATH' is set, it is consulted first).  File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images Image Instantiator Conversion ----------------------------- - Function: set-console-type-image-conversion-list CONSOLE-TYPE LIST This function sets the image-conversion-list for consoles of the given CONSOLE-TYPE. The image-conversion-list specifies how image instantiators that are strings should be interpreted. Each element of the list should be a list of two elements (a regular expression string and a vector) or a list of three elements (the preceding two plus an integer index into the vector). The string is converted to the vector associated with the first matching regular expression. If a vector index is specified, the string itself is substituted into that position in the vector. Note: The conversion above is applied when the image instantiator is added to an image specifier, not when the specifier is actually instantiated. Therefore, changing the image-conversion-list only affects newly-added instantiators. Existing instantiators in glyphs and image specifiers will not be affected. - Function: console-type-image-conversion-list CONSOLE-TYPE This function returns the image-conversion-list for consoles of the given CONSOLE-TYPE.  File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images Image Instances --------------- Image-instance objects encapsulate the way a particular image (pixmap, etc.) is displayed on a particular device. 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: image-instance-p OBJECT This function returns non-`nil' if OBJECT is an image instance. * Menu: * Image Instance Types:: Each image instances has a particular type. * Image Instance Functions:: Functions for working with image instances.  File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances Image Instance Types .................... 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. The valid image instance types are `nothing' Nothing is displayed. `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. `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). `color-pixmap' Displayed as a color pixmap. `pointer' Used as the mouse pointer for a window. `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: valid-image-instance-type-p TYPE This function returns non-`nil' if TYPE is a valid image instance type. - Function: image-instance-type-list This function returns a list of the valid image instance types. - 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: text-image-instance-p OBJECT This function returns non-`nil' if OBJECT is an image instance of type `text'. - Function: mono-pixmap-image-instance-p OBJECT This function returns non-`nil' if OBJECT is an image instance of type `mono-pixmap'. - Function: color-pixmap-image-instance-p OBJECT This function returns non-`nil' if OBJECT is an image instance of type `color-pixmap'. - Function: pointer-image-instance-p OBJECT This function returns non-`nil' if OBJECT is an image instance of type `pointer'. - Function: subwindow-image-instance-p OBJECT This function returns non-`nil' if OBJECT is an image instance of type `subwindow'. - Function: nothing-image-instance-p OBJECT This function returns non-`nil' if OBJECT is an image instance of type `nothing'.  File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances Image Instance Functions ........................ - Function: make-image-instance DATA &optional DEVICE DEST-TYPES NO-ERROR This function creates a new image-instance object. DATA is an image instantiator, which describes the image (*note Image Specifiers::.). DEST-TYPES should be a list of allowed image instance types that can be generated. The DEST-TYPES list is unordered. If multiple destination types are possible for a given instantiator, the "most natural" type for the instantiator's format is chosen. (For XBM, the most natural types are `mono-pixmap', followed by `color-pixmap', followed by `pointer'. For the other normal image formats, the most natural types are `color-pixmap', followed by `mono-pixmap', followed by `pointer'. For the string and formatted-string formats, the most natural types are `text', followed by `mono-pixmap' (not currently implemented), followed by `color-pixmap' (not currently implemented). The other formats can only be instantiated as one type. (If you want to control more specifically the order of the types into which an image is instantiated, just call `make-image-instance' repeatedly until it succeeds, passing less and less preferred destination types each time. If DEST-TYPES is omitted, all possible types are allowed. NO-ERROR controls what happens when the image cannot be generated. If NIL, an error message is generated. If T, no messages are generated and this function returns NIL. If anything else, a warning message is generated and this function returns NIL. - Function: colorize-image-instance IMAGE-INSTANCE FOREGROUND BACKGROUND This function makes the image instance be displayed in the given colors. Image instances come in two varieties: bitmaps, which are 1 bit deep which are rendered in the prevailing foreground and background colors; and pixmaps, which are of arbitrary depth (including 1) and which have the colors explicitly specified. This function converts a bitmap to a pixmap. If the image instance was a pixmap already, nothing is done (and `nil' is returned). Otherwise `t' is returned. - Function: image-instance-name IMAGE-INSTANCE This function returns the name of the given image instance. - Function: image-instance-string IMAGE-INSTANCE This function returns the string of the given image instance. This will only be non-`nil' for text image instances. - Function: image-instance-file-name IMAGE-INSTANCE This function returns the file name from which IMAGE-INSTANCE was read, if known. - Function: image-instance-mask-file-name IMAGE-INSTANCE This function returns the file name from which IMAGE-INSTANCE's mask was read, if known. - Function: image-instance-depth IMAGE-INSTANCE This function returns the depth of the image instance. This is 0 for a mono pixmap, or a positive integer for a color pixmap. - Function: image-instance-height IMAGE-INSTANCE This function returns the height of the image instance, in pixels. - Function: image-instance-width IMAGE-INSTANCE This function returns the width of the image instance, in pixels. - Function: image-instance-hotspot-x IMAGE-INSTANCE This function returns the X coordinate of the image instance's hotspot, if known. This is a point relative to the origin of the pixmap. When an image is used as a mouse pointer, the hotspot is the point on the image that sits over the location that the pointer points to. This is, for example, the tip of the arrow or the center of the crosshairs. This will always be `nil' for a non-pointer image instance. - Function: image-instance-hotspot-y IMAGE-INSTANCE This function returns the Y coordinate of the image instance's hotspot, if known. - Function: image-instance-foreground IMAGE-INSTANCE This function returns the foreground color of IMAGE-INSTANCE, if applicable. This will be a color instance or `nil'. (It will only be non-`nil' for colorized mono pixmaps and for pointers.) - Function: image-instance-background IMAGE-INSTANCE This function returns the background color of IMAGE-INSTANCE, if applicable. This will be a color instance or `nil'. (It will only be non-`nil' for colorized mono pixmaps and for pointers.)  File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs Glyph Types =========== Each glyph has a particular type, which controls how the glyph's image is generated. Each glyph type has a corresponding list of allowable image instance types that can be generated. When you call `glyph-image-instance' to retrieve the image instance of a glyph, XEmacs does the equivalent of calling `make-image-instance' and passing in DEST-TYPES the list of allowable image instance types for the glyph's type. * `buffer' glyphs can be used as the begin-glyph or end-glyph of an extent, in the modeline, and in the toolbar. Their image can be instantiated as `nothing', `mono-pixmap', `color-pixmap', `text', and `subwindow'. * `pointer' glyphs can be used to specify the mouse pointer. Their image can be instantiated as `pointer'. * `icon' glyphs can be used to specify the icon used when a frame is iconified. Their image can be instantiated as `mono-pixmap' and `color-pixmap'. - Function: 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'. - Function: valid-glyph-type-p GLYPH-TYPE Given a GLYPH-TYPE, this function returns non-`nil' if it is valid. - Function: glyph-type-list This function returns a list of valid glyph types. - Function: buffer-glyph-p OBJECT This function returns non-`nil' if OBJECT is a glyph of type `buffer'. - Function: icon-glyph-p OBJECT This function returns non-`nil' if OBJECT is a glyph of type `icon'. - Function: pointer-glyph-p OBJECT This function returns non-`nil' if OBJECT is a glyph of type `pointer'.  File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs Mouse Pointer ============= The shape of the mouse pointer when over a particular section of a frame is controlled using various glyph variables. Since the image of a glyph is a specifier, it can be controlled on a per-buffer, per-frame, per-window, or per-device basis. You should use `set-glyph-image' to set the following variables, *not* `setq'. - Glyph: text-pointer-glyph This variable specifies the shape of the mouse pointer when over text. - Glyph: nontext-pointer-glyph This variable specifies the shape of the mouse pointer when over a buffer, but not over text. If unspecified in a particular domain, `text-pointer-glyph' is used. - Glyph: modeline-pointer-glyph This variable specifies the shape of the mouse pointer when over the modeline. If unspecified in a particular domain, `nontext-pointer-glyph' is used. - Glyph: selection-pointer-glyph This variable specifies the shape of the mouse pointer when over a selectable text region. If unspecified in a particular domain, `text-pointer-glyph' is used. - Glyph: gc-pointer-glyph This variable specifies the shape of the mouse pointer when a garbage collection is in progress. If the selected window is on a window system and this glyph specifies a value (i.e. a pointer image instance) in the domain of the selected window, the pointer will be changed as specified during garbage collection. Otherwise, a message will be printed in the echo area, as controlled by `gc-message'. - Glyph: busy-pointer-glyph This variable specifies the shape of the mouse pointer when XEmacs is busy. If unspecified in a particular domain, the pointer is not changed when XEmacs is busy. - Glyph: menubar-pointer-glyph This variable specifies the shape of the mouse pointer when over the menubar. If unspecified in a particular domain, the window-system-provided default pointer is used. - Glyph: scrollbar-pointer-glyph This variable specifies the shape of the mouse pointer when over a scrollbar. If unspecified in a particular domain, the window-system-provided default pointer is used. - Glyph: toolbar-pointer-glyph This variable specifies the shape of the mouse pointer when over a toolbar. If unspecified in a particular domain, `nontext-pointer-glyph' is used. Internally, these variables are implemented in `default-mouse-motion-handler', and thus only take effect when the mouse moves. That function calls `set-frame-pointer', which sets the current mouse pointer for a frame. - Function: set-frame-pointer FRAME IMAGE-INSTANCE This function sets the mouse pointer of FRAME to the given pointer image instance. You should not call this function directly. (If you do, the pointer will change again the next time the mouse moves.)  File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs Redisplay Glyphs ================ - Glyph: truncation-glyph This variable specifies what is displayed at the end of truncated lines. - Glyph: continuation-glyph This variable specifies what is displayed at the end of wrapped lines. - Glyph: octal-escape-glyph This variable specifies what to prefix character codes displayed in octal with. - Glyph: hscroll-glyph This variable specifies what to display at the beginning of horizontally scrolled lines. - 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 ("..."). - Glyph: control-arrow-glyph This variable specifies what to use as an arrow for control characters.  File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs Subwindows ========== Subwindows are not currently implemented. - Function: subwindowp OBJECT This function returns non-`nil' if OBJECT is a subwindow.  File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top Annotations *********** 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: * 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.  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: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations Annotation Primitives ===================== - Function: make-annotation GLYPH &optional POSITION LAYOUT BUFFER WITH-EVENT D-GLYPH RIGHTP This function creates a marginal annotation at position POS in BUFFER. The annotation is displayed using GLYPH, which should be a glyph object or a string, and is positioned using layout policy LAYOUT. If POS is `nil', point is used. If LAYOUT is `nil', `whitespace' is used. If BUFFER is `nil', the current buffer is used. If WITH-EVENT is non-`nil', then when an annotation is activated, the triggering event is passed as the second arg to the annotation function. If D-GLYPH is non-`nil' then it is used as the glyph that will be displayed when button1 is down. If RIGHTP is non-`nil' then the glyph will be displayed on the right side of the buffer instead of the left. The newly created annotation is returned. - Function: delete-annotation ANNOTATION This function removes ANNOTATION from its buffer. This does not modify the buffer text. - Function: annotationp ANNOTATION This function returns `t' if ANNOTATION is an annotation, `nil' otherwise.  File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations Annotation Properties ===================== - Function: annotation-glyph ANNOTATION This function returns the glyph object used to display ANNOTATION. - Function: set-annotation-glyph ANNOTATION GLYPH &optional LAYOUT SIDE This function sets the glyph of ANNOTATION to GLYPH, which should be a glyph object. If LAYOUT is non-`nil', set the layout policy of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the side of the buffer at which the annotation is displayed to the given side. The new value of `annotation-glyph' is returned. - Function: annotation-down-glyph ANNOTATION This function returns the glyph used to display ANNOTATION when the left mouse button is depressed on the annotation. - 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. - Function: annotation-face ANNOTATION This function returns the face associated with ANNOTATION. - Function: set-annotation-face ANNOTATION FACE This function sets the face associated with ANNOTATION to FACE. - Function: annotation-layout ANNOTATION This function returns the layout policy of ANNOTATION. - Function: set-annotation-layout ANNOTATION LAYOUT This function sets the layout policy of ANNOTATION to LAYOUT. - 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: annotation-data ANNOTATION This function returns the data associated with ANNOTATION. - Function: set-annotation-data ANNOTATION DATA This function sets the data field of ANNOTATION to DATA. DATA is returned. - Function: annotation-action ANNOTATION This function returns the action associated with ANNOTATION. - Function: set-annotation-action ANNOTATION ACTION This function sets the action field of ANNOTATION to ACTION. ACTION is returned.. - Function: annotation-menu ANNOTATION This function returns the menu associated with ANNOTATION. - 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. - Function: annotation-visible ANNOTATION This function returns `t' if there is enough available space to display ANNOTATION, `nil' otherwise. - Function: annotation-width ANNOTATION This function returns the width of ANNOTATION in pixels. - Function: hide-annotation ANNOTATION This function removes ANNOTATION's glyph, making it invisible. - Function: reveal-annotation ANNOTATION This function restores ANNOTATION's glyph, making it visible.  File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations Locating Annotations ==================== - 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: 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: annotation-list &optional BUFFER This function returns a list of all annotations in BUFFER. If BUFFER is `nil', the current buffer is used. - Function: all-annotations This function returns a list of all annotations in all buffers in existence.  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.  File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations Annotation Hooks ================ The following three hooks are provided for use with the marginal annotations: `before-delete-annotation-hook' This hook is called immediately before an annotation is destroyed. It is passed a single argument, the annotation being destroyed. `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.  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. * 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: Refresh Screen, Next: Truncation, Up: Display Refreshing the Screen ===================== The function `redraw-frame' redisplays the entire contents of a given frame. *Note Frames::. - Function: redraw-frame FRAME This function clears and redisplays frame FRAME. Even more powerful is `redraw-display': - Command: redraw-display &optional DEVICE This function redraws all frames on DEVICE marked as having their image garbled. DEVICE defaults to the selected device. If DEVICE is `t', all devices will have their frames checked. Processing user input takes absolute priority over redisplay. If you call these functions when input is available, they do nothing immediately, but a full redisplay does happen eventually--after all the input has been processed. Normally, suspending and resuming XEmacs also refreshes the screen. Some terminal emulators record separate contents for display-oriented programs such as XEmacs and for ordinary sequential display. If you are using such a terminal, you might want to inhibit the redisplay on resumption. *Note Suspending XEmacs::. - 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. 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::. - Command: force-redisplay This function causes an immediate update of the display in all circumstances, whether or not input is pending. (This function does not exist in FSF Emacs.) - 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.)  File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display Truncation ========== When a line of text extends beyond the right edge of a window, the line can either be truncated or continued on the next line. When a line is truncated, this is normally shown with a `\' in the rightmost column of the window on X displays, and with a `$' on TTY devices. When a line is continued or "wrapped" onto the next line, this is shown with a curved arrow in the rightmost column of the window (or with a `\' on TTY devices). The additional screen lines used to display a long text line are called "continuation" lines. Normally, whenever line truncation is in effect for a particular window, a horizontal scrollbar is displayed in that window if the device supports scrollbars. *Note Scrollbars::. Note that continuation is different from filling; continuation happens on the screen only, not in the buffer contents, and it breaks a line precisely at the right margin, not at a word boundary. *Note Filling::. - User Option: truncate-lines This buffer-local variable controls how XEmacs displays lines that extend beyond the right edge of the window. If it is non-`nil', then XEmacs does not display continuation lines; rather each line of text occupies exactly one screen line, and a backslash appears at the edge of any line that extends to or beyond the edge of the window. The default is `nil'. If the variable `truncate-partial-width-windows' is non-`nil', then truncation is always used for side-by-side windows (within one frame) regardless of the value of `truncate-lines'. - User Option: default-truncate-lines This variable is the default value for `truncate-lines', for buffers that do not have local values for it. - User Option: truncate-partial-width-windows This variable controls display of lines that extend beyond the right edge of the window, in side-by-side windows (*note Splitting Windows::.). If it is non-`nil', these lines are truncated; otherwise, `truncate-lines' says what to do with them. The backslash and curved arrow used to indicate truncated or continued lines are only defaults, and can be changed. These images are actually glyphs (*note Glyphs::.). XEmacs provides a great deal of flexibility in how glyphs can be controlled. (This differs from FSF Emacs, which uses display tables to control these images.) For details, *Note Redisplay Glyphs::.  File: lispref.info, Node: The Echo Area, Next: Invisible Text, Prev: Truncation, Up: Display The Echo Area ============= 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 ---------- Some of the messages displayed in the echo area are also recorded in the ` *Message-Log*' buffer. - User Option: log-message-max-size This variable specifies the maximum size of `* Message-Log*' buffer. - Variable: echo-keystrokes This variable determines how much time should elapse before command characters echo. Its value must be an integer, 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.