X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-37;h=d88e0586c7adab3202381fdd8ef27afa79dd028f;hb=d1099d83853ef66f415fbb5928243e0835dbdf79;hp=d15f1e071f21bff5ae9e9719ea82c915d123daa8;hpb=376658ea71d16dced8acff36c3e385ac3738d868;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-37 b/info/lispref.info-37 index d15f1e0..d88e058 100644 --- a/info/lispref.info-37 +++ b/info/lispref.info-37 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 3.12s from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,1231 +50,1118 @@ 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: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display - -Invisible Text -============== - - You can make characters "invisible", so that they do not appear on -the screen, with the `invisible' property. This can be either a text -property or a property of an overlay. - - In the simplest case, any non-`nil' `invisible' property makes a -character invisible. This is the default case--if you don't alter the -default value of `buffer-invisibility-spec', this is how the -`invisibility' property works. This feature is much like selective -display (*note Selective Display::), but more general and cleaner. - - More generally, you can use the variable `buffer-invisibility-spec' -to control which values of the `invisible' property make text -invisible. This permits you to classify the text into different subsets -in advance, by giving them different `invisible' values, and -subsequently make various subsets visible or invisible by changing the -value of `buffer-invisibility-spec'. - - Controlling visibility with `buffer-invisibility-spec' is especially -useful in a program to display the list of entries in a data base. It -permits the implementation of convenient filtering commands to view -just a part of the entries in the data base. Setting this variable is -very fast, much faster than scanning all the text in the buffer looking -for properties to change. - - - Variable: buffer-invisibility-spec - This variable specifies which kinds of `invisible' properties - actually make a character invisible. - - `t' - A character is invisible if its `invisible' property is - non-`nil'. This is the default. - - a list - Each element of the list makes certain characters invisible. - Ultimately, a character is invisible if any of the elements - of this list applies to it. The list can have two kinds of - elements: - - `ATOM' - A character is invisible if its `invisible' property - value is ATOM or if it is a list with ATOM as a member. - - `(ATOM . t)' - A character is invisible if its `invisible' property - value is ATOM or if it is a list with ATOM as a member. - Moreover, if this character is at the end of a line and - is followed by a visible newline, it displays an - ellipsis. - - Ordinarily, commands that operate on text or move point do not care -whether the text is invisible. However, the user-level line motion -commands explicitly ignore invisible newlines. - - -File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display - -Selective Display -================= - - "Selective display" is a pair of features that hide certain lines on -the screen. - - The first variant, explicit selective display, is designed for use in -a Lisp program. The program controls which lines are hidden by altering -the text. Outline mode has traditionally used this variant. It has -been partially replaced by the invisible text feature (*note Invisible -Text::); there is a new version of Outline mode which uses that instead. - - In the second variant, the choice of lines to hide is made -automatically based on indentation. This variant is designed to be a -user-level feature. - - The way you control explicit selective display is by replacing a -newline (control-j) with a carriage return (control-m). The text that -was formerly a line following that newline is now invisible. Strictly -speaking, it is temporarily no longer a line at all, since only newlines -can separate lines; it is now part of the previous line. - - Selective display does not directly affect editing commands. For -example, `C-f' (`forward-char') moves point unhesitatingly into -invisible text. However, the replacement of newline characters with -carriage return characters affects some editing commands. For example, -`next-line' skips invisible lines, since it searches only for newlines. -Modes that use selective display can also define commands that take -account of the newlines, or that make parts of the text visible or -invisible. - - When you write a selectively displayed buffer into a file, all the -control-m's are output as newlines. This means that when you next read -in the file, it looks OK, with nothing invisible. The selective display -effect is seen only within XEmacs. - - - Variable: selective-display - This buffer-local variable enables selective display. This means - that lines, or portions of lines, may be made invisible. - - * If the value of `selective-display' is `t', then any portion - of a line that follows a control-m is not displayed. - - * If the value of `selective-display' is a positive integer, - then lines that start with more than that many columns of - indentation are not displayed. - - When some portion of a buffer is invisible, the vertical movement - commands operate as if that portion did not exist, allowing a - single `next-line' command to skip any number of invisible lines. - However, character movement commands (such as `forward-char') do - not skip the invisible portion, and it is possible (if tricky) to - insert or delete text in an invisible portion. - - In the examples below, we show the _display appearance_ of the - buffer `foo', which changes with the value of `selective-display'. - The _contents_ of the buffer do not change. - - (setq selective-display nil) - => nil - - ---------- Buffer: foo ---------- - 1 on this column - 2on this column - 3n this column - 3n this column - 2on this column - 1 on this column - ---------- Buffer: foo ---------- - - (setq selective-display 2) - => 2 - - ---------- Buffer: foo ---------- - 1 on this column - 2on this column - 2on this column - 1 on this column - ---------- Buffer: foo ---------- - - - Variable: selective-display-ellipses - If this buffer-local variable is non-`nil', then XEmacs displays - `...' at the end of a line that is followed by invisible text. - This example is a continuation of the previous one. - - (setq selective-display-ellipses t) - => t - - ---------- Buffer: foo ---------- - 1 on this column - 2on this column ... - 2on this column - 1 on this column - ---------- Buffer: foo ---------- - - You can use a display table to substitute other text for the - ellipsis (`...'). *Note Display Tables::. - - -File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display - -The Overlay Arrow -================= - - The "overlay arrow" is useful for directing the user's attention to -a particular line in a buffer. For example, in the modes used for -interface to debuggers, the overlay arrow indicates the line of code -about to be executed. - - - Variable: overlay-arrow-string - This variable holds the string to display to call attention to a - particular line, or `nil' if the arrow feature is not in use. - Despite its name, the value of this variable can be either a string - or a glyph (*note Glyphs::). - - - Variable: overlay-arrow-position - This variable holds a marker that indicates where to display the - overlay arrow. It should point at the beginning of a line. The - arrow text appears at the beginning of that line, overlaying any - text that would otherwise appear. Since the arrow is usually - short, and the line usually begins with indentation, normally - nothing significant is overwritten. - - The overlay string is displayed only in the buffer that this marker - points into. Thus, only one buffer can have an overlay arrow at - any given time. - - You can do the same job by creating an extent with a `begin-glyph' -property. *Note Extent Properties::. +File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions + +Glyph Properties +---------------- + + Each glyph has a list of properties, which control all of the +aspects of the glyph's appearance. The following symbols have +predefined meanings: + +`image' + The image used to display the glyph. + +`baseline' + Percent above baseline that glyph is to be displayed. Only for + glyphs displayed inside of a buffer. + +`contrib-p' + Whether the glyph contributes to the height of the line it's on. + Only for glyphs displayed inside of a buffer. + +`face' + Face of this glyph (_not_ a specifier). + + - Function: set-glyph-property glyph property value &optional locale + tag-set how-to-add + This function changes a property of a GLYPH. + + For built-in properties, the actual value of the property is a + specifier and you cannot change this; but you can change the + specifications within the specifier, and that is what this + function will do. For user-defined properties, you can use this + function to either change the actual value of the property or, if + this value is a specifier, change the specifications within it. + + If PROPERTY is a built-in property, the specifications to be added + to this property can be supplied in many different ways: + + * If VALUE is a simple instantiator (e.g. a string naming a + pixmap filename) or a list of instantiators, then the + instantiator(s) will be added as a specification of the + property for the given LOCALE (which defaults to `global' if + omitted). + + * If VALUE is a list of specifications (each of which is a cons + of a locale and a list of instantiators), then LOCALE must be + `nil' (it does not make sense to explicitly specify a locale + in this case), and specifications will be added as given. + + * If VALUE is a specifier (as would be returned by + `glyph-property' if no LOCALE argument is given), then some + or all of the specifications in the specifier will be added + to the property. In this case, the function is really + equivalent to `copy-specifier' and LOCALE has the same + semantics (if it is a particular locale, the specification + for the locale will be copied; if a locale type, + specifications for all locales of that type will be copied; + if `nil' or `all', then all specifications will be copied). + + HOW-TO-ADD should be either `nil' or one of the symbols `prepend', + `append', `remove-tag-set-prepend', `remove-tag-set-append', + `remove-locale', `remove-locale-type', or `remove-all'. See + `copy-specifier' and `add-spec-to-specifier' for a description of + what each of these means. Most of the time, you do not need to + worry about this argument; the default behavior usually is fine. + + In general, it is OK to pass an instance object (e.g. as returned + by `glyph-property-instance') as an instantiator in place of an + actual instantiator. In such a case, the instantiator used to + create that instance object will be used (for example, if you set + a font-instance object as the value of the `font' property, then + the font name used to create that object will be used instead). + If some cases, however, doing this conversion does not make sense, + and this will be noted in the documentation for particular types + of instance objects. + + If PROPERTY is not a built-in property, then this function will + simply set its value if LOCALE is `nil'. However, if LOCALE is + given, then this function will attempt to add VALUE as the + instantiator for the given LOCALE, using `add-spec-to-specifier'. + If the value of the property is not a specifier, it will + automatically be converted into a `generic' specifier. + + - Function: glyph-property glyph property &optional locale + This function returns GLYPH's value of the given PROPERTY. + + If LOCALE is omitted, the GLYPH's actual value for PROPERTY will + be returned. For built-in properties, this will be a specifier + object of a type appropriate to the property (e.g. a font or color + specifier). For other properties, this could be anything. + + If LOCALE is supplied, then instead of returning the actual value, + the specification(s) for the given locale or locale type will be + returned. This will only work if the actual value of PROPERTY is + a specifier (this will always be the case for built-in properties, + but may or may not apply to user-defined properties). If the + actual value of PROPERTY is not a specifier, this value will + simply be returned regardless of LOCALE. + + The return value will be a list of instantiators (e.g. vectors + specifying pixmap data), or a list of specifications, each of + which is a cons of a locale and a list of instantiators. + Specifically, if LOCALE is a particular locale (a buffer, window, + frame, device, or `global'), a list of instantiators for that + locale will be returned. Otherwise, if LOCALE is a locale type + (one of the symbols `buffer', `window', `frame', or `device'), the + specifications for all locales of that type will be returned. + Finally, if LOCALE is `all', the specifications for all locales of + all types will be returned. + + The specifications in a specifier determine what the value of + PROPERTY will be in a particular "domain" or set of circumstances, + which is typically a particular Emacs window along with the buffer + it contains and the frame and device it lies within. The value is + derived from the instantiator associated with the most specific + locale (in the order buffer, window, frame, device, and `global') + that matches the domain in question. In other words, given a + domain (i.e. an Emacs window, usually), the specifier for PROPERTY + will first be searched for a specification whose locale is the + buffer contained within that window; then for a specification + whose locale is the window itself; then for a specification whose + locale is the frame that the window is contained within; etc. The + first instantiator that is valid for the domain (usually this + means that the instantiator is recognized by the device [i.e. the + X server or TTY device] that the domain is on). The function + `glyph-property-instance' actually does all this, and is used to + determine how to display the glyph. + + - Function: glyph-property-instance glyph property &optional domain + default no-fallback + This function returns the instance of GLYPH's PROPERTY in the + specified DOMAIN. + + Under most circumstances, DOMAIN will be a particular window, and + the returned instance describes how the specified property + actually is displayed for that window and the particular buffer in + it. Note that this may not be the same as how the property + appears when the buffer is displayed in a different window or + frame, or how the property appears in the same window if you + switch to another buffer in that window; and in those cases, the + returned instance would be different. + + The returned instance is an image-instance object, and you can + query it using the appropriate image instance functions. For + example, you could use `image-instance-depth' to find out the + depth (number of color planes) of a pixmap displayed in a + particular window. The results might be different from the + results you would get for another window (perhaps the user + specified a different image for the frame that window is on; or + perhaps the same image was specified but the window is on a + different X server, and that X server has different color + capabilities from this one). + + DOMAIN defaults to the selected window if omitted. + + DOMAIN can be a frame or device, instead of a window. The value + returned for such a domain is used in special circumstances when a + more specific domain does not apply; for example, a frame value + might be used for coloring a toolbar, which is conceptually + attached to a frame rather than a particular window. The value is + also useful in determining what the value would be for a + particular window within the frame or device, if it is not + overridden by a more specific specification. + + If PROPERTY does not name a built-in property, its value will + simply be returned unless it is a specifier object, in which case + it will be instanced using `specifier-instance'. + + Optional arguments DEFAULT and NO-FALLBACK are the same as in + `specifier-instance'. *Note Specifiers::. + + - Function: remove-glyph-property glyph property &optional locale + tag-set exact-p + This function removes a property from a glyph. For built-in + properties, this is analogous to `remove-specifier'. *Note + remove-specifier-p: Specifiers, for the meaning of the LOCALE, + TAG-SET, and EXACT-P arguments.  -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: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions + +Glyph Convenience Functions +--------------------------- + + The following functions are provided for working with specific +properties of a glyph. Note that these are exactly like calling the +general functions described above and passing in the appropriate value +for PROPERTY. + + Remember that if you want to determine the "value" of a specific +glyph property, you probably want to use the `*-instance' functions. +For example, to determine whether a glyph contributes to its line +height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The +latter will return a boolean specifier or a list of specifications, and +you probably aren't concerned with these.) + + - Function: glyph-image glyph &optional locale + This function is equivalent to calling `glyph-property' with a + property of `image'. The return value will be an image specifier + if LOCALE is `nil' or omitted; otherwise, it will be a + specification or list of specifications. + + - Function: set-glyph-image glyph spec &optional locale tag-set + how-to-add + This function is equivalent to calling `set-glyph-property' with a + property of `image'. + + - Function: glyph-image-instance glyph &optional domain default + no-fallback + This function returns the instance of GLYPH's image in the given + DOMAIN, and is equivalent to calling `glyph-property-instance' + with a property of `image'. The return value will be an image + instance. + + Normally DOMAIN will be a window or `nil' (meaning the selected + window), and an instance object describing how the image appears + in that particular window and buffer will be returned. + + - Function: glyph-contrib-p glyph &optional locale + This function is equivalent to calling `glyph-property' with a + property of `contrib-p'. The return value will be a boolean + specifier if LOCALE is `nil' or omitted; otherwise, it will be a + specification or list of specifications. + + - Function: set-glyph-contrib-p glyph spec &optional locale tag-set + how-to-add + This function is equivalent to calling `set-glyph-property' with a + property of `contrib-p'. + + - Function: glyph-contrib-p-instance glyph &optional domain default + no-fallback + This function returns whether the glyph contributes to its line + height in the given DOMAIN, and is equivalent to calling + `glyph-property-instance' with a property of `contrib-p'. The + return value will be either `nil' or `t'. (Normally DOMAIN will be + a window or `nil', meaning the selected window.) + + - Function: glyph-baseline glyph &optional locale + This function is equivalent to calling `glyph-property' with a + property of `baseline'. The return value will be a specifier if + LOCALE is `nil' or omitted; otherwise, it will be a specification + or list of specifications. + + - Function: set-glyph-baseline glyph spec &optional locale tag-set + how-to-add + This function is equivalent to calling `set-glyph-property' with a + property of `baseline'. + + - Function: glyph-baseline-instance glyph &optional domain default + no-fallback + This function returns the instance of GLYPH's baseline value in + the given DOMAIN, and is equivalent to calling + `glyph-property-instance' with a property of `baseline'. The + return value will be an integer or `nil'. + + Normally DOMAIN will be a window or `nil' (meaning the selected + window), and an instance object describing the baseline value + appears in that particular window and buffer will be returned. + + - Function: glyph-face glyph + This function returns the face of GLYPH. (Remember, this is not a + specifier, but a simple property.) + + - Function: set-glyph-face glyph face + This function changes the face of GLYPH to FACE.  -File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display - -Blinking Parentheses -==================== - - This section describes the mechanism by which XEmacs shows a matching -open parenthesis when the user inserts a close parenthesis. - - - Variable: blink-paren-function - The value of this variable should be a function (of no arguments) - to be called whenever a character with close parenthesis syntax is - inserted. The value of `blink-paren-function' may be `nil', in - which case nothing is done. - - *Please note:* This variable was named `blink-paren-hook' in - older Emacs versions, but since it is not called with the - standard convention for hooks, it was renamed to - `blink-paren-function' in version 19. - - - Variable: blink-matching-paren - If this variable is `nil', then `blink-matching-open' does nothing. - - - Variable: blink-matching-paren-distance - This variable specifies the maximum distance to scan for a matching - parenthesis before giving up. - - - Variable: blink-matching-paren-delay - This variable specifies the number of seconds for the cursor to - remain at the matching parenthesis. A fraction of a second often - gives good results, but the default is 1, which works on all - systems. - - - Function: blink-matching-open - This function is the default value of `blink-paren-function'. It - assumes that point follows a character with close parenthesis - syntax and moves the cursor momentarily to the matching opening - character. If that character is not already on the screen, it - displays the character's context in the echo area. To avoid long - delays, this function does not search farther than - `blink-matching-paren-distance' characters. - - Here is an example of calling this function explicitly. - - (defun interactive-blink-matching-open () - "Indicate momentarily the start of sexp before point." - (interactive) - (let ((blink-matching-paren-distance - (buffer-size)) - (blink-matching-paren t)) - (blink-matching-open))) - - -File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display - -Usual Display Conventions -========================= +File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions - 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: +Glyph Dimensions +---------------- - * Character codes 32 through 126 map to glyph codes 32 through 126. - Normally this means they display as themselves. + - Function: glyph-width glyph &optional window + This function returns the width of GLYPH on WINDOW. This may not + be exact as it does not take into account all of the context that + redisplay will. - * Character code 9 is a horizontal tab. It displays as whitespace - up to a position determined by `tab-width'. + - Function: glyph-ascent glyph &optional window + This function returns the ascent value of GLYPH on WINDOW. This + may not be exact as it does not take into account all of the + context that redisplay will. - * Character code 10 is a newline. + - Function: glyph-descent glyph &optional window + This function returns the descent value of GLYPH on WINDOW. This + may not be exact as it does not take into account all of the + context that redisplay will. - * All other codes in the range 0 through 31, and code 127, display - in one of two ways according to the value of `ctl-arrow'. If it is - non-`nil', these codes map to sequences of two glyphs, where the - first glyph is the ASCII code for `^'. (A display table can - specify a glyph to use instead of `^'.) Otherwise, these codes map - just like the codes in the range 128 to 255. - - * Character codes 128 through 255 map to sequences of four glyphs, - where the first glyph is the ASCII code for `\', and the others are - digit characters representing the code in octal. (A display table - can specify a glyph to use instead of `\'.) - - The usual display conventions apply even when there is a display -table, for any character whose entry in the active display table is -`nil'. Thus, when you set up a display table, you need only specify -the characters for which you want unusual behavior. - - These variables affect the way certain characters are displayed on -the screen. Since they change the number of columns the characters -occupy, they also affect the indentation functions. - - - User Option: ctl-arrow - This buffer-local variable controls how control characters are - displayed. If it is non-`nil', they are displayed as a caret - followed by the character: `^A'. If it is `nil', they are - displayed as a backslash followed by three octal digits: `\001'. - - - Variable: default-ctl-arrow - The value of this variable is the default value for `ctl-arrow' in - buffers that do not override it. *Note Default Value::. - - - User Option: tab-width - The value of this variable is the spacing between tab stops used - for displaying tab characters in Emacs buffers. The default is 8. - Note that this feature is completely independent from the - user-settable tab stops used by the command `tab-to-tab-stop'. - *Note Indent Tabs::. + - Function: glyph-height glyph &optional window + This function returns the height of GLYPH on WINDOW. (This is + equivalent to the sum of the ascent and descent values.) This may + not be exact as it does not take into account all of the context + that redisplay will.  -File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display - -Display Tables -============== - - You can use the "display table" feature to control how all 256 -possible character codes display on the screen. This is useful for -displaying European languages that have letters not in the ASCII -character set. +File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs - 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". +Images +====== * 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. +* Image Specifiers:: Specifying how an image will appear. +* Image Instantiator Conversion:: + Conversion is applied to image instantiators + at the time they are added to an + image specifier or at the time they + are passed to `make-image-instance'. +* Image Instances:: What an image specifier gets instanced as.  -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 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 &optional locale + This function returns non-`nil' if FORMAT is a valid image + instantiator format. + + If LOCALE is non-`nil' then the format is checked in that locale. + If LOCALE is `nil' the current console is used. + + Note that the return value for many formats listed above depends on + whether XEmacs was compiled with support for that format. + + - Function: image-instantiator-format-list + This function return a list of valid image-instantiator formats. + + - Variable: xpm-color-symbols + This variable holds definitions of logical color-names used when + reading XPM files. Elements of this list should be of the form + `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a + string, which is the name of the color to define; the + FORM-TO-EVALUATE should evaluate to a color specifier object, or a + string to be passed to `make-color-instance' (*note Colors::). If + a loaded XPM file references a symbolic color called COLOR-NAME, + it will display as the computed color instead. + + The default value of this variable defines the logical color names + `"foreground"' and `"background"' to be the colors of the + `default' face. + + - Variable: x-bitmap-file-path + A list of the directories in which X bitmap files may be found. + If `nil', this is initialized from the `"*bitmapFilePath"' + resource. This is used by the `make-image-instance' function + (however, note that if the environment variable `XBMLANGPATH' is + set, it is consulted first).  -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: 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: Character Descriptors, Prev: Active Display Table, Up: Display Tables +File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images -Character Descriptors ---------------------- +Image Instances +--------------- - 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: + Image-instance objects encapsulate the way a particular image +(pixmap, etc.) is displayed on a particular device. -a string - Display this particular string wherever the character is to be - displayed. + 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. -a glyph - Display this particular glyph wherever the character is to be - displayed. + - Function: image-instance-p object + This function returns non-`nil' if OBJECT is an image instance. -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. +* Menu: -`nil' - Display according to the standard interpretation (*note Usual - Display::). +* Image Instance Types:: Each image instances has a particular type. +* Image Instance Functions:: Functions for working with image instances.  -File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display - -Beeping -======= - - 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: 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: beep &optional dont-terminate sound device - This is a synonym for `ding'. - - - 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. - - - 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. - - 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: - - `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. - - `volume' - An integer from 0-100, defaulting to `bell-volume'. - - `pitch' - If using the default X beep, the pitch (Hz) to generate. - - `duration' - If using the default X beep, the duration (milliseconds). +File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances - For compatibility, elements of `sound-alist' may also be: +Image Instance Types +.................... - * `( sound-name . )' + 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. - * `( sound-name )' + The valid image instance types are - You should probably add things to this list by calling the function - `load-sound-file'. +`nothing' + Nothing is displayed. - Caveats: +`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. - - You can only play audio data if running on the console screen - of a Sun SparcStation, SGI, or HP9000s700. +`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). - - The pitch, duration, and volume options are available - everywhere, but many X servers ignore the `pitch' option. +`color-pixmap' + Displayed as a color pixmap. - The following beep-types are used by XEmacs itself: +`pointer' + Used as the mouse pointer for a window. - `auto-save-error' - when an auto-save does not succeed +`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. - `command-error' - when the XEmacs command loop catches an error + - Function: valid-image-instance-type-p type + This function returns non-`nil' if TYPE is a valid image instance + type. - `undefined-key' - when you type a key that is undefined + - Function: image-instance-type-list + This function returns a list of the valid image instance types. - `undefined-click' - when you use an undefined mouse-click combination + - 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'. - `no-completion' - during completing-read + - Function: text-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `text'. - `y-or-n-p' - when you type something other than 'y' or 'n' + - Function: mono-pixmap-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `mono-pixmap'. - `yes-or-no-p' - when you type something other than 'yes' or 'no' + - Function: color-pixmap-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `color-pixmap'. - `default' - used when nothing else is appropriate. + - Function: pointer-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `pointer'. - Other lisp packages may use other beep types, but these are the - ones that the C kernel of XEmacs uses. + - Function: subwindow-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `subwindow'. - - User Option: bell-volume - This variable specifies the default volume for sounds, from 0 to - 100. + - Function: nothing-image-instance-p object + This function returns non-`nil' if OBJECT is an image instance of + type `nothing'. - - Command: load-default-sounds - This function loads and installs some sound files as beep-types. - - - 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. - - - 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. - - - 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. - - -File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top - -Hash Tables -*********** - - - Function: hash-table-p object - This function returns `t' if OBJECT is a hash table, else `nil'. - -* Menu: - -* 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: widget-image-instance-p object + Return `t' if OBJECT is an image instance of type `widget'.  -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'. +File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances + +Image Instance Functions +........................ + + - Function: make-image-instance data &optional domain dest-types + noerror + This function creates a new image-instance object. + + DATA is an image instantiator, which describes the image (*note + Image Specifiers::). + + DEST-TYPES should be a list of allowed image instance types that + can be generated. The DEST-TYPES list is unordered. If multiple + destination types are possible for a given instantiator, the "most + natural" type for the instantiator's format is chosen. (For XBM, + the most natural types are `mono-pixmap', followed by + `color-pixmap', followed by `pointer'. For the other normal image + formats, the most natural types are `color-pixmap', followed by + `mono-pixmap', followed by `pointer'. For the string and + formatted-string formats, the most natural types are `text', + followed by `mono-pixmap' (not currently implemented), followed by + `color-pixmap' (not currently implemented). For MS Windows + resources, the most natural type for pointer resources is + `pointer', and for the others it's `color-pixmap'. The other + formats can only be instantiated as one type. (If you want to + control more specifically the order of the types into which an + image is instantiated, just call `make-image-instance' repeatedly + until it succeeds, passing less and less preferred destination + types each time. + + If DEST-TYPES is omitted, all possible types are allowed. + + DOMAIN specifies the domain to which the image instance will be + attached. This domain is termed the "governing domain". The type + of the governing domain depends on the image instantiator format. + (Although, more correctly, it should probably depend on the image + instance type.) For example, pixmap image instances are specific + to a device, but widget image instances are specific to a + particular XEmacs window because in order to display such a widget + when two windows onto the same buffer want to display the widget, + two separate underlying widgets must be created. (That's because a + widget is actually a child window-system window, and all + window-system windows have a unique existence on the screen.) This + means that the governing domain for a pixmap image instance will + be some device (most likely, the only existing device), whereas + the governing domain for a widget image instance will be some + XEmacs window. + + If you specify an overly general DOMAIN (e.g. a frame when a + window was wanted), an error is signaled. If you specify an overly + specific DOMAIN (e.g. a window when a device was wanted), the + corresponding general domain is fetched and used instead. For + `make-image-instance', it makes no difference whether you specify + an overly specific domain or the properly general domain derived + from it. However, it does matter when creating an image instance + by instantiating a specifier or glyph (e.g. with + `glyph-image-instance'), because the more specific domain causes + spec lookup to start there and proceed to more general domains. (It + would also matter when creating an image instance with an + instantiator format of `inherit', but we currently disallow this. + #### We should fix this.) n If omitted, DOMAIN defaults to the + selected window. + + NOERROR controls what happens when the image cannot be generated. + If `nil', an error message is generated. If `t', no messages are + generated and this function returns `nil'. If anything else, a + warning message is generated and this function returns `nil'. + + - Function: colorize-image-instance image-instance foreground + background + This function makes the image instance be displayed in the given + colors. Image instances come in two varieties: bitmaps, which are + 1 bit deep which are rendered in the prevailing foreground and + background colors; and pixmaps, which are of arbitrary depth + (including 1) and which have the colors explicitly specified. + This function converts a bitmap to a pixmap. If the image + instance was a pixmap already, nothing is done (and `nil' is + returned). Otherwise `t' is returned. + + - Function: image-instance-name image-instance + This function returns the name of the given image instance. + + - Function: image-instance-domain image-instance + Return the governing domain of the given IMAGE-INSTANCE. The + governing domain of an image instance is the domain that the image + instance is specific to. It is _NOT_ necessarily the domain that + was given to the call to `specifier-instance' that resulted in the + creation of this image instance. See `make-image-instance' for + more information on governing domains. + + - Function: image-instance-string image-instance + This function returns the string of the given image instance. + This will only be non-`nil' for text image instances. + + - Function: image-instance-file-name image-instance + This function returns the file name from which IMAGE-INSTANCE was + read, if known. + + - Function: image-instance-mask-file-name image-instance + This function returns the file name from which IMAGE-INSTANCE's + mask was read, if known. + + - Function: image-instance-depth image-instance + This function returns the depth of the image instance. This is 0 + for a mono pixmap, or a positive integer for a color pixmap. + + - Function: image-instance-height image-instance + This function returns the height of the image instance, in pixels. + + - Function: image-instance-width image-instance + This function returns the width of the image instance, in pixels. + + - Function: image-instance-hotspot-x image-instance + This function returns the X coordinate of the image instance's + hotspot, if known. This is a point relative to the origin of the + pixmap. When an image is used as a mouse pointer, the hotspot is + the point on the image that sits over the location that the + pointer points to. This is, for example, the tip of the arrow or + the center of the crosshairs. + + This will always be `nil' for a non-pointer image instance. + + - Function: image-instance-hotspot-y image-instance + This function returns the Y coordinate of the image instance's + hotspot, if known. + + - Function: image-instance-foreground image-instance + This function returns the foreground color of IMAGE-INSTANCE, if + applicable. This will be a color instance or `nil'. (It will only + be non-`nil' for colorized mono pixmaps and for pointers.) + + - Function: image-instance-background image-instance + This function returns the background color of IMAGE-INSTANCE, if + applicable. This will be a color instance or `nil'. (It will only + be non-`nil' for colorized mono pixmaps and for pointers.)  -File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables - -Working With Hash Tables -======================== - - - Function: puthash key value hash-table - This function hashes KEY to VALUE in HASH-TABLE. - - - 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: 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. +File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs - - Function: clrhash hash-table - This function removes all entries from HASH-TABLE, leaving it - empty. +Glyph Types +=========== - - 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. + 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. - FUNCTION may not modify HASH-TABLE, with the one exception that - FUNCTION may remhash or puthash the entry currently being - processed by FUNCTION. + * `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'. - -File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables - -Weak Hash Tables -================ + * `pointer' glyphs can be used to specify the mouse pointer. Their + image can be instantiated as `pointer'. - 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. + * `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'. - 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: 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'. - There are three types of weak hash tables: + - Function: valid-glyph-type-p glyph-type + Given a GLYPH-TYPE, this function returns non-`nil' if it is valid. -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: glyph-type-list + This function returns a list of valid glyph types. -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: buffer-glyph-p object + This function returns non-`nil' if OBJECT is a glyph of type + `buffer'. -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: icon-glyph-p object + This function returns non-`nil' if OBJECT is a glyph of type + `icon'. - Also see *Note Weak Lists::. - - Weak hash tables are created by specifying the `:weakness' keyword to -`make-hash-table'. + - Function: pointer-glyph-p object + This function returns non-`nil' if OBJECT is a glyph of type + `pointer'.  -File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top - -Range Tables -************ +File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs - A range table is a table that efficiently associated values with -ranges of integers. - - Note that range tables have a read syntax, like this: - - #s(range-table data ((-3 2) foo (5 20) bar)) - - This maps integers in the range (-3, 2) to `foo' and integers in the -range (5, 20) to `bar'. - - - Function: range-table-p object - Return non-`nil' if OBJECT is a range table. - -* Menu: +Mouse Pointer +============= -* Introduction to Range Tables:: Range tables efficiently map ranges of - integers to values. -* Working With Range Tables:: Range table functions. + The shape of the mouse pointer when over a particular section of a +frame is controlled using various glyph variables. Since the image of +a glyph is a specifier, it can be controlled on a per-buffer, +per-frame, per-window, or per-device basis. + + You should use `set-glyph-image' to set the following variables, +_not_ `setq'. + + - Glyph: text-pointer-glyph + This variable specifies the shape of the mouse pointer when over + text. + + - Glyph: nontext-pointer-glyph + This variable specifies the shape of the mouse pointer when over a + buffer, but not over text. If unspecified in a particular domain, + `text-pointer-glyph' is used. + + - Glyph: modeline-pointer-glyph + This variable specifies the shape of the mouse pointer when over + the modeline. If unspecified in a particular domain, + `nontext-pointer-glyph' is used. + + - Glyph: selection-pointer-glyph + This variable specifies the shape of the mouse pointer when over a + selectable text region. If unspecified in a particular domain, + `text-pointer-glyph' is used. + + - Glyph: gc-pointer-glyph + This variable specifies the shape of the mouse pointer when a + garbage collection is in progress. If the selected window is on a + window system and this glyph specifies a value (i.e. a pointer + image instance) in the domain of the selected window, the pointer + will be changed as specified during garbage collection. + Otherwise, a message will be printed in the echo area, as + controlled by `gc-message'. + + - Glyph: busy-pointer-glyph + This variable specifies the shape of the mouse pointer when XEmacs + is busy. If unspecified in a particular domain, the pointer is + not changed when XEmacs is busy. + + - Glyph: menubar-pointer-glyph + This variable specifies the shape of the mouse pointer when over + the menubar. If unspecified in a particular domain, the + window-system-provided default pointer is used. + + - Glyph: scrollbar-pointer-glyph + This variable specifies the shape of the mouse pointer when over a + scrollbar. If unspecified in a particular domain, the + window-system-provided default pointer is used. + + - Glyph: toolbar-pointer-glyph + This variable specifies the shape of the mouse pointer when over a + toolbar. If unspecified in a particular domain, + `nontext-pointer-glyph' is used. + + Internally, these variables are implemented in +`default-mouse-motion-handler', and thus only take effect when the +mouse moves. That function calls `set-frame-pointer', which sets the +current mouse pointer for a frame. + + - Function: set-frame-pointer frame image-instance + This function sets the mouse pointer of FRAME to the given pointer + image instance. You should not call this function directly. (If + you do, the pointer will change again the next time the mouse + moves.)  -File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables - -Introduction to Range Tables -============================ - - - Function: make-range-table - Make a new, empty range table. - - - 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. +File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs - -File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables +Redisplay Glyphs +================ -Working With Range Tables -========================= + - Glyph: truncation-glyph + This variable specifies what is displayed at the end of truncated + lines. - - 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'). + - Glyph: continuation-glyph + This variable specifies what is displayed at the end of wrapped + lines. - - Function: put-range-table start end val table - This function sets the value for range (START, END) to be VAL in - TABLE. + - Glyph: octal-escape-glyph + This variable specifies what to prefix character codes displayed + in octal with. - - Function: remove-range-table start end table - This function removes the value for range (START, END) in TABLE. + - Glyph: hscroll-glyph + This variable specifies what to display at the beginning of + horizontally scrolled lines. - - Function: clear-range-table table - This function flushes TABLE. + - 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 + ("..."). - - 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. + - Glyph: control-arrow-glyph + This variable specifies what to use as an arrow for control + characters.  -File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top +File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs -Databases -********* +Subwindows +========== - - Function: databasep object - This function returns non-`nil' if OBJECT is a database. + Subwindows are not currently implemented. -* Menu: - -* Connecting to a Database:: -* Working With a Database:: -* Other Database Functions:: + - Function: subwindowp object + This function returns non-`nil' if OBJECT is a subwindow.  -File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases - -Connecting to a Database -======================== +File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top - - 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'. +Annotations +*********** - 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. + 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. - - Function: close-database obj - This function closes database OBJ. +* Menu: - - Function: database-live-p obj - This function returns `t' iff OBJ is an active database, else - `nil'. +* 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.