Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
+
+Image Specifiers
+----------------
+
+ An image specifier is used to describe the actual image of a glyph.
+It works like other specifiers (*note Specifiers::), in that it contains
+a number of specifications describing how the image should appear in a
+variety of circumstances. These specifications are called "image
+instantiators". When XEmacs wants to display the image, it instantiates
+the image into an "image instance". Image instances are their own
+primitive object type (similar to font instances and color instances),
+describing how the image appears in a particular domain. (On the other
+hand, image instantiators, which are just descriptions of how the image
+should appear, are represented using strings or vectors.)
+
+ - Function: image-specifier-p object
+ This function returns non-`nil' if OBJECT is an image specifier.
+ Usually, an image specifier results from calling `glyph-image' on
+ a glyph.
+
+ - Function: make-image-specifier spec-list
+ This function creates a new image specifier object and initializes
+ it according to SPEC-LIST. *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
+ 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).
+
+\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.
+
+\1f
+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.
+
+\1f
+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'.
+
+ - Function: widget-image-instance-p object
+ Return t if OBJECT is an image instance of type `widget'.
+
+\1f
+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
+ 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). 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.
+
+ 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-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: 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'.
+
+\1f
+File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
+
+Mouse Pointer
+=============
+
+ The shape of the mouse pointer when over a particular section of a
+frame is controlled using various glyph variables. Since the image of
+a glyph is a specifier, it can be controlled on a per-buffer,
+per-frame, per-window, or per-device basis.
+
+ You should use `set-glyph-image' to set the following variables,
+_not_ `setq'.
+
+ - Glyph: text-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ text.
+
+ - Glyph: nontext-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ buffer, but not over text. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
+
+ - Glyph: modeline-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the modeline. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
+
+ - Glyph: selection-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ selectable text region. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
+
+ - Glyph: gc-pointer-glyph
+ This variable specifies the shape of the mouse pointer when a
+ garbage collection is in progress. If the selected window is on a
+ window system and this glyph specifies a value (i.e. a pointer
+ image instance) in the domain of the selected window, the pointer
+ will be changed as specified during garbage collection.
+ Otherwise, a message will be printed in the echo area, as
+ controlled by `gc-message'.
+
+ - Glyph: busy-pointer-glyph
+ This variable specifies the shape of the mouse pointer when XEmacs
+ is busy. If unspecified in a particular domain, the pointer is
+ not changed when XEmacs is busy.
+
+ - Glyph: menubar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the menubar. If unspecified in a particular domain, the
+ window-system-provided default pointer is used.
+
+ - Glyph: scrollbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ scrollbar. If unspecified in a particular domain, the
+ window-system-provided default pointer is used.
+
+ - Glyph: toolbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ toolbar. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
+
+ Internally, these variables are implemented in
+`default-mouse-motion-handler', and thus only take effect when the
+mouse moves. That function calls `set-frame-pointer', which sets the
+current mouse pointer for a frame.
+
+ - Function: set-frame-pointer frame image-instance
+ This function sets the mouse pointer of FRAME to the given pointer
+ image instance. You should not call this function directly. (If
+ you do, the pointer will change again the next time the mouse
+ moves.)
+
+\1f
+File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
+
+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.
+
+\1f
+File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
+
+Subwindows
+==========
+
+ Subwindows are not currently implemented.
+
+ - Function: subwindowp object
+ This function returns non-`nil' if OBJECT is a subwindow.
+
+\1f
+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.
+
+\1f
File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
Annotation Basics
This function causes an immediate update of the cursor on the
selected frame. (This function does not exist in FSF Emacs.)
-\1f
-File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
-
-Truncation
-==========
-
- When a line of text extends beyond the right edge of a window, the
-line can either be truncated or continued on the next line. When a line
-is truncated, this is normally shown with a `\' in the rightmost column
-of the window on X displays, and with a `$' on TTY devices. When a
-line is continued or "wrapped" onto the next line, this is shown with a
-curved arrow in the rightmost column of the window (or with a `\' on
-TTY devices). The additional screen lines used to display a long text
-line are called "continuation" lines.
-
- Normally, whenever line truncation is in effect for a particular
-window, a horizontal scrollbar is displayed in that window if the
-device supports scrollbars. *Note Scrollbars::.
-
- Note that continuation is different from filling; continuation
-happens on the screen only, not in the buffer contents, and it breaks a
-line precisely at the right margin, not at a word boundary. *Note
-Filling::.
-
- - User Option: truncate-lines
- This buffer-local variable controls how XEmacs displays lines that
- extend beyond the right edge of the window. If it is non-`nil',
- then XEmacs does not display continuation lines; rather each line
- of text occupies exactly one screen line, and a backslash appears
- at the edge of any line that extends to or beyond the edge of the
- window. The default is `nil'.
-
- If the variable `truncate-partial-width-windows' is non-`nil',
- then truncation is always used for side-by-side windows (within one
- frame) regardless of the value of `truncate-lines'.
-
- - User Option: default-truncate-lines
- This variable is the default value for `truncate-lines', for
- buffers that do not have local values for it.
-
- - User Option: truncate-partial-width-windows
- This variable controls display of lines that extend beyond the
- right edge of the window, in side-by-side windows (*note Splitting
- Windows::). If it is non-`nil', these lines are truncated;
- otherwise, `truncate-lines' says what to do with them.
-
- The backslash and curved arrow used to indicate truncated or
-continued lines are only defaults, and can be changed. These images
-are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
-flexibility in how glyphs can be controlled. (This differs from FSF
-Emacs, which uses display tables to control these images.)
-
- For details, *Note Redisplay Glyphs::.
-
-\1f
-File: lispref.info, Node: The Echo Area, Next: Warnings, 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 ----------
-
- 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::.
-
-\1f
-File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
-
-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.
-
- - 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::).
-
- - 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.
-
- 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.
-
- You can do the same job by creating an extent with a `begin-glyph'
-property. *Note Extent Properties::.
-
-\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.
-
-\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)))
-
-\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.
-
- - 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'.
-
- - 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::.
-
- - 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::.
-
-\1f
-File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
-
-Display Tables
-==============
-
- 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.
-
- 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".
-
-* 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::).
-