mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-05 08:53:45 +00:00
Code Issues Releases Activity

(Warnings): New node, and subnodes.

Browse Source 
(Fringes): New node.
This commit is contained in:
Richard M. Stallman 2003-08-06 01:23:14 +00:00
parent 46c7a6f087
commit 8a6ca431c7
1 changed files with 243 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
lispref/display.texi
View File

@ -15,6 +15,7 @@ that Emacs presents to the user.
* Forcing Redisplay:: Forcing redisplay.
* Truncation:: Folding or wrapping long text lines.
* The Echo Area:: Where messages are displayed.
* Warnings:: Displaying warning messages for the user.
* Invisible Text:: Hiding part of the buffer text.
* Selective Display:: Hiding part of the buffer text (the old way).
* Overlay Arrow:: Display of an arrow to indicate position.
@ -23,6 +24,7 @@ that Emacs presents to the user.
* Width:: How wide a character or string is on the screen.
* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
* Fringes:: Controlling window fringes.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Blinking:: How Emacs shows the matching open parenthesis.
@ -111,10 +113,9 @@ the rightmost column indicates a line that ``wraps'' onto the next line,
which is also called @dfn{continuing} the line. (The display table can
specify alternative indicators; see @ref{Display Tables}.)
@cindex fringes, and line continuation/truncation indicators
On a windowed display, the @samp{$} and @samp{\} indicators are
replaced with graphics bitmaps displayed on the thin areas right near
the window edges, called the @dfn{fringes}.
replaced with graphics bitmaps displayed in the window fringes
(@pxref{Fringes}).
Note that continuation is different from filling; continuation happens
on the screen only, not in the buffer contents, and it breaks a line
@ -327,6 +328,194 @@ sequence are echoed immediately.)
If the value is zero, then command input is not echoed.
@end defvar
@node Warnings
@section Reporting Warnings
@cindex warnings
@dfn{Warnings} are a facility for a program to inform the user of a
possible problem, but continue running.
@menu
* Warning Basics:: Warnings concepts and functions to report them.
* Warning Variables:: Variables programs bind to customize their warnings.
* Warning Options:: Variables users set to control display of warnings.
@end menu
@node Warning Basics
@subsection Warning Basics
@cindex severity level
Every warning has a textual message, which explains the problem for
the user, and a @dfn{severity level} which is a symbol. Here are the
possible severity levels, in order of decreasing severity, and their
meanings:
@table @code
@item :emergency
A problem that will seriously impair Emacs operation soon
if you do not attend to it promptly.
@item :error
A report of data or circumstances that are inherently wrong.
@item :warning
A report of data or circumstances that are not inherently wrong, but
raise suspicion of a possible problem.
@item :debug
A report of information that may be useful if you are debugging.
@end table
When your program encounters invalid input data, it can either
signal a Lisp error by calling @code{error} or @code{signal} or report
a warning with severity @code{:error}. Signaling a Lisp error is the
easiest thing to do, but it means the program cannot continue
processing. If you want to take the trouble to implement a way to
continue processing despite the bad data, then reporting a warning of
severity @code{:error} is the right way to inform the user of the
problem. For instance, the Emacs Lisp byte compiler can report an
error that way and continue compiling other functions. (If the
program signals a Lisp error and then handles it with
@code{condition-case}, the user won't see the error message; it could
show the message to the user by reporting it as a warning.)
@cinedex warning type
Each warning has a @dfn{warning type} to classify it. The type is a
list of symbols. The first symbol should be the custom group that you
use for the program's user options. For example, byte compiler
warnings use the warning type @code{(bytecomp)}. You can also
subcategorize the warnings, if you wish, by using more symbols in the
list.
@defun display-warning type message &optional level buffer-name
This function reports a warning, using @var{message} as the message
and @var{type} as the warning type. @var{level} should be the
severity level, with @code{:warning} being the default.
@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
for logging the warning. By default, it is @samp{*Warnings*}.
@end defun
@defun lwarn type level message &rest args
This function reports a warning using the value of @code{(format
@var{message} @var{args}...)} as the message. In other respects it is
equivalent to @code{display-warning}.
@end defun
@defun warn message &rest args
This function reports a warning using the value of @code{(format
@var{message} @var{args}...)} as the message, @code{(emacs)} as the
type, and @code{:warning} as the severity level. It exists for
compatibility only; we recommend not using it, because you should
specify a specific warning type.
@end defun
@node Warning Variables
@subsection Warning Variables
Programs can customize how their warnings appear by binding
the variables described in this section.
@defvar warning-levels
This list defines the meaning and severity order of the warning
severity levels. Each element defines one severity level,
and they are arranged in order of decreasing severity.
Each element has the form @code{(@var{level} @var{string}
@var{function})}, where @var{level} is the severity level it defines.
@var{string} specifies the textual description of this level.
@var{string} should use @samp{%s} to specify where to put the warning
type information, or it can omit the @samp{%s} so as not to include
that information.
The optional @var{function}, if non-@code{nil}, is a function to call
with no arguments, to get the user's attention.
Normally you should not change the value of this variable.
@end defvar
@defvar warning-prefix-function
If non-@code{nil}, te value is a function to generate prefix text for
warnings. Programs can bind the variable to a suitable function.
@code{display-warning} calls this function with the warnings buffer
current, and the function can insert text in it. That text becomes
the beginning of the warning message.
The function is called with two arguments, the severity level and its
entry in @code{warning-levels}. It should return a list to use as the
entry (this value need not be an actual member of
@code{warning-levels}). By constructing this value, the function to
change the severity of the warning, or specify different handling for
a given severity level.
If the variable's value is @code{nil} then there is no function
to call.
@end defvar
@defvar warning-series
Programs can bind this variable to @code{t} to say that the next
warning should begin a series. When several warnings form a series,
that means to leave point on the first warning of the series, rather
than keep move it for each warning so that it appears on the last one.
The series ends when the local binding is unbound and
@code{warning-series} becomes @code{nil} again.
The value can also be a symbol with a function definition. That is
equivalent to @code{t}, except that the next warning will also call
the function with no arguments with the warnings buffer current. The
function can insert text which will serve as a header for the series
of warnings.
Once a series has begun, the value is a marker which points to the
buffer position in the warnings buffer of the start of the series.
The variable's normal value is @code{nil}, which means to handle
each warning separately.
@end defvar
@defvar warning-fill-prefix
When this variable is non-@code{nil}, it specifies a fill prefix to
use for filling each warning's text.
@end defvar
@defvar warning-type-format
This variable specifies the format for displaying the warning type
in the warning message. The result of formatting the type this way
gets included in the message under the control of the string in the
entry in @code{warning-levels}. The default value is @code{" (%s)"}.
If you bind it to @code{""} then the warning type won't appear at
all.
@end defvar
@node Warning Options
@subsection Warning Options
These variables are used by users to control what happens
when a Lisp program reports a warning.
@defopt warning-minimum-level
This user option specifies the minimum severity level that should be
shown immediately to the user. The default is @code{:warning}, which
means to immediately display all warnings except @code{:debug}
warnings.
@end defopt
@defopt warning-minimum-log-level
This user option specifies the minimum severity level that should be
logged in the warnings buffer. The default is @code{:warning}, which
means to log all warnings except @code{:debug} warnings.
@end defopt
@defopt warning-suppress-types
This list specifies which warning types should not be displayed
immediately for the user. Each element of the list should be a list
of symbols. If its elements match the first elements in a warning
type, then that warning is not displayed immediately.
@end defopt
@defopt warning-suppress-log-types
This list specifies which warning types should not be logged in the
warnings buffer. Each element of the list should be a list of
symbols. If it matches the first few elements in a warning type, then
that warning is not logged.
@end defopt
@node Invisible Text
@section Invisible Text
@ -572,7 +761,6 @@ interface to debuggers, the overlay arrow indicates the line of code
about to be executed.
@defvar overlay-arrow-string
@cindex fringe, and overlay arrow display
This variable holds the string to display to call attention to a
particular line, or @code{nil} if the arrow feature is not in use.
On a graphical display the contents of the string are ignored; instead a
@ -2287,6 +2475,54 @@ Then, the font specifications for all but Chinese GB2312 characters have
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.
@node Fringes
@section Fringes
@cindex Fringes
The @dfn{fringes} of a window are thin vertical strips down the
sides that are used for displaying bitmaps that indicate truncation,
continuation, and horizontal scrolling, the overlay arrow. The
fringes normally appear between the display margins and the window
text, but you can put them outside the display margins for a specific
buffer by setting @code{fringes-outside-margins} buffer-locally to a
non-@code{nil} value.
@defvar fringes-outside-margins
If the value is non-@code{nil}, the frames appear outside
the display margins.
@end defvar
@defvar left-fringe-width
This variable, if non-@code{nil}, specifies the width of the left
fringe in pixels.
@end defvar
@defvar right-fringe-width
This variable, if non-@code{nil}, specifies the width of the right
fringe in pixels.
@end defvar
The values of these variables take effect when you display the
buffer in a window. If you change them while the buffer is visible,
you can call @code{set-buffer-window} to display it in a window again.
@defun set-window-fringes window left &optional right outside-margins
This function sets the fringe widthes of window @var{window}.
If window is @code{nil}, that stands for the selected window.
The argument @var{left} specifies the width in pixels of the left
fringe, and likewise @var{right} for the right fringe. A value of
@code{nil} for either one stands for the default width. If
@var{outside-margins} is non-@code{nil}, that specifies that fringes
should appear outside of the display margins.
@end defun
@defun window-fringes window
This function returns information about the fringes of a window
@var{window}. The value as the form @code{(@var{left-width}
@var{right-width} @var{frames-outside-margins}).
@end defun
@node Display Property
@section The @code{display} Property
@cindex display specification
@ -3225,9 +3461,9 @@ buffers that do not override it. @xref{Default Value}.
@defopt indicate-empty-lines
@tindex indicate-empty-lines
@cindex fringes, and empty line indication
When this is non-@code{nil}, Emacs displays a special glyph in
each empty line at the end of the buffer, on terminals that
support it (window systems).
When this is non-@code{nil}, Emacs displays a special glyph in the
fringe of each empty line at the end of the buffer, on terminals that
support it (window systems). @xref{Fringes}.
@end defopt
@defopt tab-width