X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-37;h=d4e9b21c01847de0cfe19b1f30f6b2f60a55a228;hb=dbfc38b11cb852dc18107ed3822f6efb13630a8b;hp=50538a1023f169ad31341e7d04f2297479ba422b;hpb=82da33b61c3e2dd2937db17b75b2838188793053;p=chise%2Fxemacs-chise.git- diff --git a/info/lispref.info-37 b/info/lispref.info-37 index 50538a1..d4e9b21 100644 --- a/info/lispref.info-37 +++ b/info/lispref.info-37 @@ -1,5 +1,5 @@ -This is Info file ../info/lispref.info, produced by Makeinfo version -1.68 from the input file lispref/lispref.texi. +This is ../info/lispref.info, produced by makeinfo version 4.0 from +lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -50,1233 +50,1166 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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: 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: 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: 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: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display +File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images -Selective Display -================= +Image Instances +--------------- - "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::. + Image-instance objects encapsulate the way a particular image +(pixmap, etc.) is displayed on a particular device. - -File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display + In most circumstances, you do not need to directly create image +instances; use a glyph instead. However, it may occasionally be useful +to explicitly create image instances, if you want more control over the +instantiation process. -The Overlay Arrow -================= + - Function: image-instance-p object + This function returns non-`nil' if OBJECT is an image instance. - 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. +* Menu: - You can do the same job by creating an extent with a `begin-glyph' -property. *Note Extent Properties::. +* Image Instance Types:: Each image instances has a particular type. +* Image Instance Functions:: Functions for working with image instances.  -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: Image Instance Types, Next: Image Instance Functions, Up: Image Instances - -File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display +Image Instance Types +.................... -Blinking Parentheses -==================== + 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. - 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))) + The valid image instance types are - -File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display +`nothing' + Nothing is displayed. -Usual Display Conventions -========================= +`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. - 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: +`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). - * Character codes 32 through 126 map to glyph codes 32 through 126. - Normally this means they display as themselves. +`color-pixmap' + Displayed as a color pixmap. - * Character code 9 is a horizontal tab. It displays as whitespace - up to a position determined by `tab-width'. +`pointer' + Used as the mouse pointer for a window. - * Character code 10 is a newline. +`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. - * 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. + - Function: valid-image-instance-type-p type + This function returns non-`nil' if TYPE is a valid image instance + type. - * 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 `\'.) + - Function: image-instance-type-list + This function returns a list of the valid image instance types. - 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. + - 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'. - 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. + - Function: text-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `text'. - - 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'. + - Function: mono-pixmap-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `mono-pixmap'. - - 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::. + - Function: color-pixmap-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `color-pixmap'. - - User Option: tab-width - The value of this variable is the spacing between tab stops used - for displaying tab characters in Emacs buffers. The default is 8. - Note that this feature is completely independent from the - user-settable tab stops used by the command `tab-to-tab-stop'. - *Note Indent Tabs::. + - Function: pointer-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `pointer'. - -File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display - -Display Tables -============== + - Function: subwindow-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `subwindow'. - 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. + - Function: nothing-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `nothing'. - 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. + - Function: widget-image-instance-p object + Return t if OBJECT is an image instance of type `widget'.  -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: 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: 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: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs - -File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables +Glyph Types +=========== -Character Descriptors ---------------------- + 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. - 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: + * `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'. -a string - Display this particular string wherever the character is to be - displayed. + * `pointer' glyphs can be used to specify the mouse pointer. Their + image can be instantiated as `pointer'. -a glyph - Display this particular glyph wherever the character is to be - displayed. + * `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'. -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. + - 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'. -`nil' - Display according to the standard interpretation (*note Usual - Display::.). + - Function: valid-glyph-type-p glyph-type + Given a GLYPH-TYPE, this function returns non-`nil' if it is valid. - -File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display + - Function: glyph-type-list + This function returns a list of valid glyph types. -Beeping -======= + - Function: buffer-glyph-p object + This function returns non-`nil' if OBJECT is a glyph of type + `buffer'. - You can make XEmacs ring a bell, play a sound, or blink the screen to -attract the user's attention. Be conservative about how often you do -this; frequent bells can become irritating. Also be careful not to use -beeping alone when signaling an error is appropriate. (*Note Errors::.) + - Function: icon-glyph-p object + This function returns non-`nil' if OBJECT is a glyph of type + `icon'. - - Function: ding &optional DONT-TERMINATE SOUND DEVICE - This function beeps, or flashes the screen (see `visible-bell' - below). It also terminates any keyboard macro currently executing - unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it - should be a symbol specifying which sound to make. This sound - will be played if `visible-bell' is `nil'. (This only works if - sound support was compiled into the executable and you are running - on the console of a Sun SparcStation, SGI, HP9000s700, or Linux - PC. Otherwise you just get a beep.) The optional third argument - specifies what device to make the sound on, and defaults to the - selected device. + - Function: pointer-glyph-p object + This function returns non-`nil' if OBJECT is a glyph of type + `pointer'. - - Function: beep &optional DONT-TERMINATE SOUND DEVICE - This is a synonym for `ding'. + +File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs - - User Option: visible-bell - This variable determines whether XEmacs should flash the screen to - represent a bell. Non-`nil' means yes, `nil' means no. On TTY - devices, this is effective only if the Termcap entry for the - terminal type has the visible bell flag (`vb') set. +Mouse Pointer +============= - - Variable: sound-alist - This variable holds an alist associating names with sounds. When - `beep' or `ding' is called with one of the name symbols, the - associated sound will be generated instead of the standard beep. + 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.) - Each element of `sound-alist' is a list describing a sound. The - first element of the list is the name of the sound being defined. - Subsequent elements of the list are alternating keyword/value - pairs: + +File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs - `sound' - A string of raw sound data, or the name of another sound to - play. The symbol `t' here means use the default X beep. +Redisplay Glyphs +================ - `volume' - An integer from 0-100, defaulting to `bell-volume'. + - Glyph: truncation-glyph + This variable specifies what is displayed at the end of truncated + lines. - `pitch' - If using the default X beep, the pitch (Hz) to generate. + - Glyph: continuation-glyph + This variable specifies what is displayed at the end of wrapped + lines. - `duration' - If using the default X beep, the duration (milliseconds). + - Glyph: octal-escape-glyph + This variable specifies what to prefix character codes displayed + in octal with. - For compatibility, elements of `sound-alist' may also be: + - Glyph: hscroll-glyph + This variable specifies what to display at the beginning of + horizontally scrolled lines. - * `( sound-name . )' + - 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 + ("..."). - * `( sound-name )' + - Glyph: control-arrow-glyph + This variable specifies what to use as an arrow for control + characters. - You should probably add things to this list by calling the function - `load-sound-file'. + +File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs - Caveats: +Subwindows +========== - - You can only play audio data if running on the console screen - of a Sun SparcStation, SGI, or HP9000s700. + Subwindows are not currently implemented. - - The pitch, duration, and volume options are available - everywhere, but many X servers ignore the `pitch' option. + - Function: subwindowp object + This function returns non-`nil' if OBJECT is a subwindow. - The following beep-types are used by XEmacs itself: + +File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top - `auto-save-error' - when an auto-save does not succeed +Annotations +*********** - `command-error' - when the XEmacs command loop catches an error + 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. - `undefined-key' - when you type a key that is undefined +* Menu: - `undefined-click' - when you use an undefined mouse-click combination +* 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. - `no-completion' - during completing-read + +File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations - `y-or-n-p' - when you type something other than 'y' or 'n' +Annotation Basics +================= - `yes-or-no-p' - when you type something other than 'yes' or 'no' + Marginal annotations are notes associated with a particular location +in a buffer. They may be displayed in a margin created on the +left-hand or right-hand side of the frame, in any whitespace at the +beginning or end of a line, or inside of the text itself. Every +annotation may have an associated action to be performed when the +annotation is selected. The term "annotation" is used to refer to an +individual note. The term "margin" is generically used to refer to the +whitespace before the first character on a line or after the last +character on a line. + + Each annotation has the following characteristics: +GLYPH + This is a glyph object and is used as the displayed representation + of the annotation. + +DOWN-GLYPH + If given, this glyph is used as the displayed representation of + the annotation when the mouse is pressed down over the annotation. + +FACE + The face with which to display the glyph. + +SIDE + Which side of the text (left or right) the annotation is displayed + at. + +ACTION + If non-`nil', this field must contain a function capable of being + the first argument to `funcall'. This function is normally + evaluated with a single argument, the value of the DATA field, + each time the annotation is selected. However, if the WITH-EVENT + parameter to `make-annotation' is non-`nil', the function is + called with two arguments. The first argument is the same as + before, and the second argument is the event (a button-up event, + usually) that activated the annotation. + +DATA + Not used internally. This field can contain any E-Lisp object. + It is passed as the first argument to ACTION described above. + +MENU + A menu displayed when the right mouse button is pressed over the + annotation. + + The margin is divided into "outside" and "inside". The outside +margin is space on the left or right side of the frame which normal text +cannot be displayed in. The inside margin is that space between the +leftmost or rightmost point at which text can be displayed and where the +first or last character actually is. + + There are four different "layout types" which affect the exact +location an annotation appears. + +`outside-margin' + The annotation is placed in the outside margin area. as close as + possible to the edge of the frame. If the outside margin is not + wide enough for an annotation to fit, it is not displayed. + +`inside-margin' + The annotation is placed in the inside margin area, as close as + possible to the edge of the frame. If the inside margin is not + wide enough for the annotation to fit, it will be displayed using + any available outside margin space if and only if the specifier + `use-left-overflow' or `use-right-overflow' (depending on which + side the annotation appears in) is non-`nil'. + +`whitespace' + The annotation is placed in the inside margin area, as close as + possible to the first or last non-whitespace character on a line. + If the inside margin is not wide enough for the annotation to fit, + it will be displayed if and only if the specifier + `use-left-overflow' or `use-right-overflow' (depending on which + side the annotation appears in) is non-`nil'. + +`text' + The annotation is placed at the position it is inserted. It will + create enough space for itself inside of the text area. It does + not take up a place in the logical buffer, only in the display of + the buffer. + + The current layout policy is that all `whitespace' annotations are +displayed first. Next, all `inside-margin' annotations are displayed +using any remaining space. Finally as many `outside-margin' +annotations are displayed as possible. The `text' annotations will +always display as they create their own space to display in. - `default' - used when nothing else is appropriate. + +File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations - Other lisp packages may use other beep types, but these are the - ones that the C kernel of XEmacs uses. +Annotation Primitives +===================== - - User Option: bell-volume - This variable specifies the default volume for sounds, from 0 to - 100. + - Function: make-annotation glyph &optional position layout buffer + with-event d-glyph rightp + This function creates a marginal annotation at position POS in + BUFFER. The annotation is displayed using GLYPH, which should be + a glyph object or a string, and is positioned using layout policy + LAYOUT. If POS is `nil', point is used. If LAYOUT is `nil', + `whitespace' is used. If BUFFER is `nil', the current buffer is + used. - - Command: load-default-sounds - This function loads and installs some sound files as beep-types. + If WITH-EVENT is non-`nil', then when an annotation is activated, + the triggering event is passed as the second arg to the annotation + function. If D-GLYPH is non-`nil' then it is used as the glyph + that will be displayed when button1 is down. If RIGHTP is + non-`nil' then the glyph will be displayed on the right side of + the buffer instead of the left. - - Command: load-sound-file FILENAME SOUND-NAME &optional VOLUME - This function reads in an audio file and adds it to `sound-alist'. - The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME - should be a symbol, specifying the name of the sound. If VOLUME - is specified, the sound will be played at that volume; otherwise, - the value of BELL-VOLUME will be used. + The newly created annotation is returned. - - Function: play-sound SOUND &optional VOLUME DEVICE - This function plays sound SOUND, which should be a symbol - mentioned in `sound-alist'. If VOLUME is specified, it overrides - the value (if any) specified in `sound-alist'. DEVICE specifies - the device to play the sound on, and defaults to the selected - device. + - Function: delete-annotation annotation + This function removes ANNOTATION from its buffer. This does not + modify the buffer text. - - Command: play-sound-file FILE &optional VOLUME DEVICE - This function plays the named sound file at volume VOLUME, which - defaults to `bell-volume'. DEVICE specifies the device to play - the sound on, and defaults to the selected device. + - Function: annotationp annotation + This function returns `t' if ANNOTATION is an annotation, `nil' + otherwise.  -File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top +File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations -Hash Tables -*********** +Annotation Properties +===================== - - Function: hash-table-p OBJECT - This function returns `t' if OBJECT is a hash table, else `nil'. + - Function: annotation-glyph annotation + This function returns the glyph object used to display ANNOTATION. -* Menu: + - Function: set-annotation-glyph annotation glyph &optional layout side + This function sets the glyph of ANNOTATION to GLYPH, which should + be a glyph object. If LAYOUT is non-`nil', set the layout policy + of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the + side of the buffer at which the annotation is displayed to the + given side. The new value of `annotation-glyph' is returned. -* Introduction to Hash Tables:: Hash tables are fast data structures for - implementing simple tables (i.e. finite - mappings from keys to values). -* Working With Hash Tables:: Hash table functions. -* Weak Hash Tables:: Hash tables with special garbage-collection - behavior. + - Function: annotation-down-glyph annotation + This function returns the glyph used to display ANNOTATION when + the left mouse button is depressed on the annotation. - -File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables - -Introduction to Hash Tables -=========================== - - A "hash table" is a data structure that provides mappings from -arbitrary Lisp objects called "keys" to other arbitrary Lisp objects -called "values". A key/value pair is sometimes called an "entry" in -the hash table. There are many ways other than hash tables of -implementing the same sort of mapping, e.g. association lists (*note -Association Lists::.) and property lists (*note Property Lists::.), but -hash tables provide much faster lookup when there are many entries in -the mapping. Hash tables are an implementation of the abstract data -type "dictionary", also known as "associative array". - - Internally, hash tables are hashed using the "linear probing" hash -table implementation method. This method hashes each key to a -particular spot in the hash table, and then scans forward sequentially -until a blank entry is found. To look up a key, hash to the appropriate -spot, then search forward for the key until either a key is found or a -blank entry stops the search. This method is used in preference to -double hashing because of changes in recent hardware. The penalty for -non-sequential access to memory has been increasing, and this -compensates for the problem of clustering that linear probing entails. - - When hash tables are created, the user may (but is not required to) -specify initial properties that influence performance. - - Use the `:size' parameter to specify the number of entries that are -likely to be stored in the hash table, to avoid the overhead of resizing -the table. But if the pre-allocated space for the entries is never -used, it is simply wasted and makes XEmacs slower. Excess unused hash -table entries exact a small continuous performance penalty, since they -must be scanned at every garbage collection. If the number of entries -in the hash table is unknown, simply avoid using the `:size' keyword. - - Use the `:rehash-size' and `:rehash-threshold' keywords to adjust -the algorithm for deciding when to rehash the hash table. For -temporary hash tables that are going to be very heavily used, use a -small rehash threshold, for example, 0.4 and a large rehash size, for -example 2.0. For permanent hash tables that will be infrequently used, -specify a large rehash threshold, for example 0.8. - - Hash tables can also be created by the lisp reader using structure -syntax, for example: - #s(hash-table size 20 data (foo 1 bar 2)) - - The structure syntax accepts the same keywords as `make-hash-table' -(without the `:' character), as well as the additional keyword `data', -which specifies the initial hash table contents. - - - Function: make-hash-table &key `test' `size' `rehash-size' - `rehash-threshold' `weakness' - This function returns a new empty hash table object. - - Keyword `:test' can be `eq', `eql' (default) or `equal'. - Comparison between keys is done using this function. If speed is - important, consider using `eq'. When storing strings in the hash - table, you will likely need to use `equal'. - - Keyword `:size' specifies the number of keys likely to be inserted. - This number of entries can be inserted without enlarging the hash - table. - - Keyword `:rehash-size' must be a float greater than 1.0, and - specifies the factor by which to increase the size of the hash - table when enlarging. - - Keyword `:rehash-threshold' must be a float between 0.0 and 1.0, - and specifies the load factor of the hash table which triggers - enlarging. - - Keyword `:weakness' can be `nil' (default), `t', `key' or `value'. - - A weak hash table is one whose pointers do not count as GC - referents: for any key-value pair in the hash table, if the only - remaining pointer to either the key or the value is in a weak hash - table, then the pair will be removed from the hash table, and the - key and value collected. A non-weak hash table (or any other - pointer) would prevent the object from being collected. - - A key-weak hash table is similar to a fully-weak hash table except - that a key-value pair will be removed only if the key remains - unmarked outside of weak hash tables. The pair will remain in the - hash table if the key is pointed to by something other than a weak - hash table, even if the value is not. - - A value-weak hash table is similar to a fully-weak hash table - except that a key-value pair will be removed only if the value - remains unmarked outside of weak hash tables. The pair will - remain in the hash table if the value is pointed to by something - other than a weak hash table, even if the key is not. - - - Function: copy-hash-table HASH-TABLE - This function returns a new hash table which contains the same - keys and values as HASH-TABLE. The keys and values will not - themselves be copied. - - - Function: hash-table-count HASH-TABLE - This function returns the number of entries in HASH-TABLE. - - - Function: hash-table-test HASH-TABLE - This function returns the test function of HASH-TABLE. This can - be one of `eq', `eql' or `equal'. - - - Function: hash-table-size HASH-TABLE - This function returns the current number of slots in HASH-TABLE, - whether occupied or not. - - - Function: hash-table-rehash-size HASH-TABLE - This function returns the current rehash size of HASH-TABLE. This - is a float greater than 1.0; the factor by which HASH-TABLE is - enlarged when the rehash threshold is exceeded. - - - Function: hash-table-rehash-threshold HASH-TABLE - This function returns the current rehash threshold of HASH-TABLE. - This is a float between 0.0 and 1.0; the maximum "load factor" of - HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing. - - - Function: hash-table-weakness HASH-TABLE - This function returns the weakness of HASH-TABLE. This can be one - of `nil', `t', `key' or `value'. + - Function: set-annotation-down-glyph annotation glyph + This function returns the glyph used to display ANNOTATION when + the left mouse button is depressed on the annotation to GLYPH, + which should be a glyph object. - -File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables + - Function: annotation-face annotation + This function returns the face associated with ANNOTATION. -Working With Hash Tables -======================== + - Function: set-annotation-face annotation face + This function sets the face associated with ANNOTATION to FACE. - - Function: puthash KEY VALUE HASH-TABLE - This function hashes KEY to VALUE in HASH-TABLE. + - Function: annotation-layout annotation + This function returns the layout policy of ANNOTATION. - - Function: gethash KEY HASH-TABLE &optional DEFAULT - This function finds the hash value for KEY in HASH-TABLE. If - there is no entry for KEY in HASH-TABLE, DEFAULT is returned - (which in turn defaults to `nil'). + - Function: set-annotation-layout annotation layout + This function sets the layout policy of ANNOTATION to LAYOUT. - - Function: remhash KEY HASH-TABLE - This function removes the entry for KEY from HASH-TABLE. Does - nothing if there is no entry for KEY in HASH-TABLE. + - Function: annotation-side annotation + This function returns the side of the buffer that ANNOTATION is + displayed on. Return value is a symbol, either `left' or `right'. - - Function: clrhash HASH-TABLE - This function removes all entries from HASH-TABLE, leaving it - empty. + - Function: annotation-data annotation + This function returns the data associated with ANNOTATION. - - Function: maphash FUNCTION HASH-TABLE - This function maps FUNCTION over entries in HASH-TABLE, calling it - with two args, each key and value in the hash table. + - Function: set-annotation-data annotation data + This function sets the data field of ANNOTATION to DATA. DATA is + returned. - FUNCTION may not modify HASH-TABLE, with the one exception that - FUNCTION may remhash or puthash the entry currently being - processed by FUNCTION. + - Function: annotation-action annotation + This function returns the action associated with ANNOTATION. - -File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables - -Weak Hash Tables -================ - - A "weak hash table" is a special variety of hash table whose -elements do not count as GC referents. For any key-value pair in such a -hash table, if either the key or value (or in some cases, if one -particular one of the two) has no references to it outside of weak hash -tables (and similar structures such as weak lists), the pair will be -removed from the table, and the key and value collected. A non-weak -hash table (or any other pointer) would prevent the objects from being -collected. + - Function: set-annotation-action annotation action + This function sets the action field of ANNOTATION to ACTION. + ACTION is returned.. - Weak hash tables are useful for keeping track of information in a -non-obtrusive way, for example to implement caching. If the cache -contains objects such as buffers, markers, image instances, etc. that -will eventually disappear and get garbage-collected, using a weak hash -table ensures that these objects are collected normally rather than -remaining around forever, long past their actual period of use. -(Otherwise, you'd have to explicitly map over the hash table every so -often and remove unnecessary elements.) + - Function: annotation-menu annotation + This function returns the menu associated with ANNOTATION. - There are three types of weak hash tables: + - Function: set-annotation-menu annotation menu + This function sets the menu associated with ANNOTATION to MENU. + This menu will be displayed when the right mouse button is pressed + over the annotation. -fully weak hash tables - In these hash tables, a pair disappears if either the key or the - value is unreferenced outside of the table. + - Function: annotation-visible annotation + This function returns `t' if there is enough available space to + display ANNOTATION, `nil' otherwise. -key-weak hash tables - In these hash tables, a pair disappears if the key is unreferenced - outside of the table, regardless of how the value is referenced. + - Function: annotation-width annotation + This function returns the width of ANNOTATION in pixels. -value-weak hash tables - In these hash tables, a pair disappears if the value is - unreferenced outside of the table, regardless of how the key is - referenced. + - Function: hide-annotation annotation + This function removes ANNOTATION's glyph, making it invisible. - Also see *Note Weak Lists::. - - Weak hash tables are created by specifying the `:weakness' keyword to -`make-hash-table'. + - Function: reveal-annotation annotation + This function restores ANNOTATION's glyph, making it visible.  -File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top - -Range Tables -************ - - A range table is a table that efficiently associated values with -ranges of integers. +File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations - Note that range tables have a read syntax, like this: - - #s(range-table data ((-3 2) foo (5 20) bar)) +Locating Annotations +==================== - This maps integers in the range (-3, 2) to `foo' and integers in the -range (5, 20) to `bar'. + - Function: annotations-in-region start end buffer + This function returns a list of all annotations in BUFFER which + are between START and END inclusively. - - Function: range-table-p OBJECT - Return non-`nil' if OBJECT is a range table. + - Function: annotations-at &optional position buffer + This function returns a list of all annotations at POSITION in + BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil' + the current buffer is used. -* Menu: + - Function: annotation-list &optional buffer + This function returns a list of all annotations in BUFFER. If + BUFFER is `nil', the current buffer is used. -* Introduction to Range Tables:: Range tables efficiently map ranges of - integers to values. -* Working With Range Tables:: Range table functions. + - Function: all-annotations + This function returns a list of all annotations in all buffers in + existence.  -File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables - -Introduction to Range Tables -============================ +File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations - - Function: make-range-table - Make a new, empty range table. +Margin Primitives +================= - - Function: copy-range-table OLD-TABLE - Make a new range table which contains the same values for the same - ranges as the given table. The values will not themselves be - copied. + The margin widths are controllable on a buffer-local, window-local, +frame-local, device-local, or device-type-local basis through the use +of specifiers. *Note Specifiers::. + + - Specifier: left-margin-width + This is a specifier variable controlling the width of the left + outside margin, in characters. Use `set-specifier' to change its + value. + + - Specifier: right-margin-width + This is a specifier variable controlling the width of the right + outside margin, in characters. Use `set-specifier' to change its + value. + + - Specifier: use-left-overflow + If non-`nil', use the left outside margin as extra whitespace when + displaying `whitespace' and `inside-margin' annotations. Defaults + to `nil'. This is a specifier variable; use `set-specifier' to + change its value. + + - Specifier: use-right-overflow + If non-`nil', use the right outside margin as extra whitespace when + displaying `whitespace' and `inside-margin' annotations. Defaults + to `nil'. This is a specifier variable; use `set-specifier' to + change its value. + + - Function: window-left-margin-pixel-width &optional window + This function returns the width in pixels of the left outside + margin of WINDOW. If WINDOW is `nil', the selected window is + assumed. + + - Function: window-right-margin-pixel-width &optional window + This function returns the width in pixels of the right outside + margin of WINDOW. If WINDOW is `nil', the selected window is + assumed. + + The margin colors are controlled by the faces `left-margin' and +`right-margin'. These can be set using the X resources +`Emacs.left-margin.background' and `Emacs.left-margin.foreground'; +likewise for the right margin.  -File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables - -Working With Range Tables -========================= +File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations - - Function: get-range-table POS TABLE &optional DEFAULT - This function finds value for position POS in TABLE. If there is - no corresponding value, return DEFAULT (defaults to `nil'). +Annotation Hooks +================ - - Function: put-range-table START END VAL TABLE - This function sets the value for range (START, END) to be VAL in - TABLE. + The following three hooks are provided for use with the marginal +annotations: - - Function: remove-range-table START END TABLE - This function removes the value for range (START, END) in TABLE. +`before-delete-annotation-hook' + This hook is called immediately before an annotation is destroyed. + It is passed a single argument, the annotation being destroyed. - - Function: clear-range-table TABLE - This function flushes TABLE. +`after-delete-annotation-hook' + This normal hook is called immediately after an annotation is + destroyed. - - Function: map-range-table FUNCTION TABLE - This function maps FUNCTION over entries in TABLE, calling it with - three args, the beginning and end of the range and the - corresponding value. +`make-annotation-hook' + This hook is called immediately after an annotation is created. + It is passed a single argument, the newly created annotation.  -File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top +File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top -Databases -********* +Emacs Display +************* - - Function: databasep OBJECT - This function returns non-`nil' if OBJECT is a database. + This chapter describes a number of other features related to the +display that XEmacs presents to the user. * Menu: -* Connecting to a Database:: -* Working With a Database:: -* Other Database Functions:: +* Refresh Screen:: Clearing the screen and redrawing everything on it. +* Truncation:: Folding or wrapping long text lines. +* The Echo Area:: Where messages are displayed. +* Warnings:: Display of Warnings. +* Invisible Text:: Hiding part of the buffer text. +* Selective Display:: Hiding part of the buffer text (the old way). +* Overlay Arrow:: Display of an arrow to indicate position. +* Temporary Displays:: Displays that go away automatically. +* Blinking:: How XEmacs shows the matching open parenthesis. +* Usual Display:: The usual conventions for displaying nonprinting chars. +* Display Tables:: How to specify other conventions. +* Beeping:: Audible signal to the user.  -File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases - -Connecting to a Database -======================== - - - Function: open-database FILE &optional TYPE SUBTYPE ACCESS MODE - This function opens database FILE, using database method TYPE and - SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS - can be any combination of `r' `w' and `+', for read, write, and - creation flags. - - TYPE can have the value `'dbm' or `'berkeley_db' to select the - type of database file to use. (Note: XEmacs may not support both - of these types.) - - For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should by - `nil'. - - For a TYPE of `'berkeley_db', the following subtypes are - available: `'hash', `'btree', and `'recno'. See the manpages for - the Berkeley DB functions to more information about these types. - - - Function: close-database OBJ - This function closes database OBJ. - - - Function: database-live-p OBJ - This function returns `t' iff OBJ is an active database, else - `nil'. +File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display + +Refreshing the Screen +===================== + + The function `redraw-frame' redisplays the entire contents of a +given frame. *Note Frames::. + + - Function: redraw-frame frame + This function clears and redisplays frame FRAME. + + Even more powerful is `redraw-display': + + - Command: redraw-display &optional device + This function redraws all frames on DEVICE marked as having their + image garbled. DEVICE defaults to the selected device. If DEVICE + is `t', all devices will have their frames checked. + + Processing user input takes absolute priority over redisplay. If you +call these functions when input is available, they do nothing +immediately, but a full redisplay does happen eventually--after all the +input has been processed. + + Normally, suspending and resuming XEmacs also refreshes the screen. +Some terminal emulators record separate contents for display-oriented +programs such as XEmacs and for ordinary sequential display. If you are +using such a terminal, you might want to inhibit the redisplay on +resumption. *Note Suspending XEmacs::. + + - Variable: no-redraw-on-reenter + This variable controls whether XEmacs redraws the entire screen + after it has been suspended and resumed. Non-`nil' means yes, + `nil' means no. + + The above functions do not actually cause the display to be updated; +rather, they clear out the internal display records that XEmacs +maintains, so that the next time the display is updated it will be +redrawn from scratch. Normally this occurs the next time that +`next-event' or `sit-for' is called; however, a display update will not +occur if there is input pending. *Note Command Loop::. + + - Function: force-cursor-redisplay + This function causes an immediate update of the cursor on the + selected frame. (This function does not exist in FSF Emacs.)