-File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
-
-The Echo Area
-=============
-
- The "echo area" is used for displaying messages made with the
-`message' primitive, and for echoing keystrokes. It is not the same as
-the minibuffer, despite the fact that the minibuffer appears (when
-active) in the same place on the screen as the echo area. The `XEmacs
-Reference Manual' specifies the rules for resolving conflicts between
-the echo area and the minibuffer for use of that screen space (*note
-The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo
-area; see *Note Errors::.
-
- You can write output in the echo area by using the Lisp printing
-functions with `t' as the stream (*note Output Functions::), or as
-follows:
-
- - Function: message string &rest arguments
- This function displays a one-line message in the echo area. The
- argument STRING is similar to a C language `printf' control
- string. See `format' in *Note String Conversion::, for the details
- on the conversion specifications. `message' returns the
- constructed string.
-
- In batch mode, `message' prints the message text on the standard
- error stream, followed by a newline.
-
- If STRING is `nil', `message' clears the echo area. If the
- minibuffer is active, this brings the minibuffer contents back onto
- the screen immediately.
-
- (message "Minibuffer depth is %d."
- (minibuffer-depth))
- -| Minibuffer depth is 0.
- => "Minibuffer depth is 0."
-
- ---------- Echo Area ----------
- Minibuffer depth is 0.
- ---------- Echo Area ----------
-
- In addition to only displaying a message, XEmacs allows you to
-"label" your messages, giving you fine-grained control of their
-display. Message label is a symbol denoting the message type. Some
-standard labels are:
-
- * `message'--default label used by the `message' function;
-
- * `error'--default label used for reporting errors;
-
- * `progress'--progress indicators like `Converting... 45%' (not
- logged by default);
-
- * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
- default);
-
- * `command'--helper command messages like `Mark set' (not logged by
- default);
-
- * `no-log'--messages that should never be logged
-
- Several messages may be stacked in the echo area at once. Lisp
-programs may access these messages, or remove them as appropriate, via
-the message stack.
-
- - Function: display-message label message &optional frame stdout-p
- This function displays MESSAGE (a string) labeled as LABEL, as
- described above.
-
- The FRAME argument specifies the frame to whose minibuffer the
- message should be printed. This is currently unimplemented. The
- STDOUT-P argument is used internally.
-
- (display-message 'command "Mark set")
-
- - Function: lmessage label string &rest arguments
- This function displays a message STRING with label LABEL. It is
- similar to `message' in that it accepts a `printf'-like strings
- and any number of arguments.
-
- ;; Display a command message.
- (lmessage 'command "Comment column set to %d" comment-column)
-
- ;; Display a progress message.
- (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
-
- ;; Display a message that should not be logged.
- (lmessage 'no-log "Done")
-
- - Function: clear-message &optional label frame stdout-p no-restore
- This function remove any message with the given LABEL from the
- message-stack, erasing it from the echo area if it's currently
- displayed there.
-
- If a message remains at the head of the message-stack and
- NO-RESTORE is `nil', it will be displayed. The string which
- remains in the echo area will be returned, or `nil' if the
- message-stack is now empty. If LABEL is nil, the entire
- message-stack is cleared.
-
- ;; Show a message, wait for 2 seconds, and restore old minibuffer
- ;; contents.
- (message "A message")
- -| A message
- => "A Message"
- (lmessage 'my-label "Newsflash! Newsflash!")
- -| Newsflash! Newsflash!
- => "Newsflash! Newsflash!"
- (sit-for 2)
- (clear-message 'my-label)
- -| A message
- => "A message"
-
- Unless you need the return value or you need to specify a label,
- you should just use `(message nil)'.
-
- - Function: current-message &optional frame
- This function returns the current message in the echo area, or
- `nil'. The FRAME argument is currently unused.
-
- Some of the messages displayed in the echo area are also recorded in
-the ` *Message-Log*' buffer. Exactly which messages will be recorded
-can be tuned using the following variables.
-
- - User Option: log-message-max-size
- This variable specifies the maximum size of the ` *Message-log*'
- buffer.
-
- - Variable: log-message-ignore-labels
- This variable specifies the labels whose messages will not be
- logged. It should be a list of symbols.
-
- - Variable: log-message-ignore-regexps
- This variable specifies the regular expressions matching messages
- that will not be logged. It should be a list of regular
- expressions.
-
- Normally, packages that generate messages that might need to be
- ignored should label them with `progress', `prompt', or `no-log',
- so they can be filtered by `log-message-ignore-labels'.
-
- - Variable: echo-keystrokes
- This variable determines how much time should elapse before command
- characters echo. Its value must be a number, which specifies the
- number of seconds to wait before echoing. If the user types a
- prefix key (such as `C-x') and then delays this many seconds
- before continuing, the prefix key is echoed in the echo area. Any
- subsequent characters in the same command will be echoed as well.
-
- If the value is zero, then command input is not echoed.
-
- - Variable: cursor-in-echo-area
- This variable controls where the cursor appears when a message is
- displayed in the echo area. If it is non-`nil', then the cursor
- appears at the end of the message. Otherwise, the cursor appears
- at point--not in the echo area at all.
-
- The value is normally `nil'; Lisp programs bind it to `t' for
- brief periods of time.
-
-\1f
-File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
-
-Warnings
-========
-
- XEmacs contains a facility for unified display of various warnings.
-Unlike errors, warnings are displayed in the situations when XEmacs
-encounters a problem that is recoverable, but which should be fixed for
-safe future operation.
-
- For example, warnings are printed by the startup code when it
-encounters problems with X keysyms, when there is an error in `.emacs',
-and in other problematic situations. Unlike messages, warnings are
-displayed in a separate buffer, and include an explanatory message that
-may span across several lines. Here is an example of how a warning is
-displayed:
-
- (1) (initialization/error) An error has occurred while loading ~/.emacs:
-
- Symbol's value as variable is void: bogus-variable
-
- To ensure normal operation, you should investigate the cause of the error
- in your initialization file and remove it. Use the `-debug-init' option
- to XEmacs to view a complete error backtrace.
-
- Each warning has a "class" and a "priority level". The class is a
-symbol describing what sort of warning this is, such as
-`initialization', `resource' or `key-mapping'.
-
- The warning priority level specifies how important the warning is.
-The recognized warning levels, in increased order of priority, are:
-`debug', `info', `notice', `warning', `error', `critical', `alert' and
-`emergency'.
-
- - Function: display-warning class message &optional level
- This function displays a warning message MESSAGE (a string).
- CLASS should be a warning class symbol, as described above, or a
- list of such symbols. LEVEL describes the warning priority level.
- If unspecified, it default to `warning'.
-
- (display-warning 'resource
- "Bad resource specification encountered:
- something like
-
- Emacs*foo: bar
-
- You should replace the * with a . in order to get proper behavior when
- you use the specifier and/or `set-face-*' functions.")
-
- ---------- Warning buffer ----------
- (1) (resource/warning) Bad resource specification encountered:
- something like
-
- Emacs*foo: bar
-
- You should replace the * with a . in order to get proper behavior when
- you use the specifier and/or `set-face-*' functions.
- ---------- Warning buffer ----------
-
- - Function: lwarn class level message &rest args
- This function displays a formatted labeled warning message. As
- above, CLASS should be the warning class symbol, or a list of such
- symbols, and LEVEL should specify the warning priority level
- (`warning' by default).
-
- Unlike in `display-warning', MESSAGE may be a formatted message,
- which will be, together with the rest of the arguments, passed to
- `format'.
-
- (lwarn 'message-log 'warning
- "Error caught in `remove-message-hook': %s"
- (error-message-string e))
-
- - Variable: log-warning-minimum-level
- This variable specifies the minimum level of warnings that should
- be generated. Warnings with level lower than defined by this
- variable are completely ignored, as if they never happened.
-
- - Variable: display-warning-minimum-level
- This variable specifies the minimum level of warnings that should
- be displayed. Unlike `log-warning-minimum-level', setting this
- function does not suppress warnings entirely--they are still
- generated in the `*Warnings*' buffer, only they are not displayed
- by default.
-
- - Variable: log-warning-suppressed-classes
- This variable specifies a list of classes that should not be
- logged or displayed. If any of the class symbols associated with
- a warning is the same as any of the symbols listed here, the
- warning will be completely ignored, as it they never happened.
-
- - Variable: display-warning-suppressed-classes
- This variable specifies a list of classes that should not be
- logged or displayed. If any of the class symbols associated with
- a warning is the same as any of the symbols listed here, the
- warning will not be displayed. The warning will still logged in
- the *Warnings* buffer (unless also contained in
- `log-warning-suppressed-classes'), but the buffer will not be
- automatically popped up.
-
-\1f
-File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
-
-Invisible Text
-==============
-
- You can make characters "invisible", so that they do not appear on
-the screen, with the `invisible' property. This can be either a text
-property or a property of an overlay.
-
- In the simplest case, any non-`nil' `invisible' property makes a
-character invisible. This is the default case--if you don't alter the
-default value of `buffer-invisibility-spec', this is how the
-`invisibility' property works. This feature is much like selective
-display (*note Selective Display::), but more general and cleaner.
-
- More generally, you can use the variable `buffer-invisibility-spec'
-to control which values of the `invisible' property make text
-invisible. This permits you to classify the text into different subsets
-in advance, by giving them different `invisible' values, and
-subsequently make various subsets visible or invisible by changing the
-value of `buffer-invisibility-spec'.
-
- Controlling visibility with `buffer-invisibility-spec' is especially
-useful in a program to display the list of entries in a data base. It
-permits the implementation of convenient filtering commands to view
-just a part of the entries in the data base. Setting this variable is
-very fast, much faster than scanning all the text in the buffer looking
-for properties to change.
-
- - Variable: buffer-invisibility-spec
- This variable specifies which kinds of `invisible' properties
- actually make a character invisible.
-
- `t'
- A character is invisible if its `invisible' property is
- non-`nil'. This is the default.
-
- a list
- Each element of the list makes certain characters invisible.
- Ultimately, a character is invisible if any of the elements
- of this list applies to it. The list can have two kinds of
- elements:
-
- `ATOM'
- A character is invisible if its `invisible' property
- value is ATOM or if it is a list with ATOM as a member.
-
- `(ATOM . t)'
- A character is invisible if its `invisible' property
- value is ATOM or if it is a list with ATOM as a member.
- Moreover, if this character is at the end of a line and
- is followed by a visible newline, it displays an
- ellipsis.
-
- Ordinarily, commands that operate on text or move point do not care
-whether the text is invisible. However, the user-level line motion
-commands explicitly ignore invisible newlines.
-
-\1f
-File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
-
-Selective Display
-=================
-
- "Selective display" is a pair of features that hide certain lines on
-the screen.
-
- The first variant, explicit selective display, is designed for use in
-a Lisp program. The program controls which lines are hidden by altering
-the text. Outline mode has traditionally used this variant. It has
-been partially replaced by the invisible text feature (*note Invisible
-Text::); there is a new version of Outline mode which uses that instead.
-
- In the second variant, the choice of lines to hide is made
-automatically based on indentation. This variant is designed to be a
-user-level feature.
-
- The way you control explicit selective display is by replacing a
-newline (control-j) with a carriage return (control-m). The text that
-was formerly a line following that newline is now invisible. Strictly
-speaking, it is temporarily no longer a line at all, since only newlines
-can separate lines; it is now part of the previous line.
-
- Selective display does not directly affect editing commands. For
-example, `C-f' (`forward-char') moves point unhesitatingly into
-invisible text. However, the replacement of newline characters with
-carriage return characters affects some editing commands. For example,
-`next-line' skips invisible lines, since it searches only for newlines.
-Modes that use selective display can also define commands that take
-account of the newlines, or that make parts of the text visible or
-invisible.
-
- When you write a selectively displayed buffer into a file, all the
-control-m's are output as newlines. This means that when you next read
-in the file, it looks OK, with nothing invisible. The selective display
-effect is seen only within XEmacs.
-
- - Variable: selective-display
- This buffer-local variable enables selective display. This means
- that lines, or portions of lines, may be made invisible.
-
- * If the value of `selective-display' is `t', then any portion
- of a line that follows a control-m is not displayed.
-
- * If the value of `selective-display' is a positive integer,
- then lines that start with more than that many columns of
- indentation are not displayed.
-
- When some portion of a buffer is invisible, the vertical movement
- commands operate as if that portion did not exist, allowing a
- single `next-line' command to skip any number of invisible lines.
- However, character movement commands (such as `forward-char') do
- not skip the invisible portion, and it is possible (if tricky) to
- insert or delete text in an invisible portion.
-
- In the examples below, we show the _display appearance_ of the
- buffer `foo', which changes with the value of `selective-display'.
- The _contents_ of the buffer do not change.
-
- (setq selective-display nil)
- => nil
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column
- 3n this column
- 3n this column
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- (setq selective-display 2)
- => 2
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- - Variable: selective-display-ellipses
- If this buffer-local variable is non-`nil', then XEmacs displays
- `...' at the end of a line that is followed by invisible text.
- This example is a continuation of the previous one.
-
- (setq selective-display-ellipses t)
- => t
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column ...
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- You can use a display table to substitute other text for the
- ellipsis (`...'). *Note Display Tables::.
-
-\1f
-File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
-
-The Overlay Arrow
-=================
-
- The "overlay arrow" is useful for directing the user's attention to
-a particular line in a buffer. For example, in the modes used for
-interface to debuggers, the overlay arrow indicates the line of code
-about to be executed.
-
- - Variable: overlay-arrow-string
- This variable holds the string to display to call attention to a
- particular line, or `nil' if the arrow feature is not in use.
- Despite its name, the value of this variable can be either a string
- or a glyph (*note Glyphs::).
-
- - Variable: overlay-arrow-position
- This variable holds a marker that indicates where to display the
- overlay arrow. It should point at the beginning of a line. The
- arrow text appears at the beginning of that line, overlaying any
- text that would otherwise appear. Since the arrow is usually
- short, and the line usually begins with indentation, normally
- nothing significant is overwritten.
-
- The overlay string is displayed only in the buffer that this marker
- points into. Thus, only one buffer can have an overlay arrow at
- any given time.
-
- You can do the same job by creating an extent with a `begin-glyph'
-property. *Note Extent Properties::.
+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.