X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-37;h=d4e9b21c01847de0cfe19b1f30f6b2f60a55a228;hb=dbfc38b11cb852dc18107ed3822f6efb13630a8b;hp=7a64c762e9bbbd0ceea2d55b8a2ecaf0bc51102f;hpb=f52a96980ed9280f8f906a20d4b899dc0b027644;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-37 b/info/lispref.info-37 index 7a64c76..d4e9b21 100644 --- a/info/lispref.info-37 +++ b/info/lispref.info-37 @@ -50,6 +50,809 @@ 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. *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 `'] 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). + + +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'. + + - Function: widget-image-instance-p object + Return t if OBJECT is an image instance of type `widget'. + + +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.) + + +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 @@ -410,834 +1213,3 @@ occur if there is input pending. *Note Command Loop::. 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: 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. - - -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. - - -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. - - -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::. - - -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::. - - -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 ---------- - 20 - - # - - ---------- 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. - - -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))) - - -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::. - - -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. - - -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 "^?")) - - -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::. - - -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::). -