15 |
* Forcing Redisplay:: Forcing redisplay. |
* Forcing Redisplay:: Forcing redisplay. |
16 |
* Truncation:: Folding or wrapping long text lines. |
* Truncation:: Folding or wrapping long text lines. |
17 |
* The Echo Area:: Where messages are displayed. |
* The Echo Area:: Where messages are displayed. |
18 |
|
* Warnings:: Displaying warning messages for the user. |
19 |
* Invisible Text:: Hiding part of the buffer text. |
* Invisible Text:: Hiding part of the buffer text. |
20 |
* Selective Display:: Hiding part of the buffer text (the old way). |
* Selective Display:: Hiding part of the buffer text (the old way). |
21 |
* Overlay Arrow:: Display of an arrow to indicate position. |
* Overlay Arrow:: Display of an arrow to indicate position. |
24 |
* Width:: How wide a character or string is on the screen. |
* Width:: How wide a character or string is on the screen. |
25 |
* Faces:: A face defines a graphics style for text characters: |
* Faces:: A face defines a graphics style for text characters: |
26 |
font, colors, etc. |
font, colors, etc. |
27 |
|
* Fringes:: Controlling window fringes. |
28 |
* Display Property:: Enabling special display features. |
* Display Property:: Enabling special display features. |
29 |
* Images:: Displaying images in Emacs buffers. |
* Images:: Displaying images in Emacs buffers. |
30 |
* Blinking:: How Emacs shows the matching open parenthesis. |
* Blinking:: How Emacs shows the matching open parenthesis. |
113 |
which is also called @dfn{continuing} the line. (The display table can |
which is also called @dfn{continuing} the line. (The display table can |
114 |
specify alternative indicators; see @ref{Display Tables}.) |
specify alternative indicators; see @ref{Display Tables}.) |
115 |
|
|
|
@cindex fringes, and line continuation/truncation indicators |
|
116 |
On a windowed display, the @samp{$} and @samp{\} indicators are |
On a windowed display, the @samp{$} and @samp{\} indicators are |
117 |
replaced with graphics bitmaps displayed on the thin areas right near |
replaced with graphics bitmaps displayed in the window fringes |
118 |
the window edges, called the @dfn{fringes}. |
(@pxref{Fringes}). |
119 |
|
|
120 |
Note that continuation is different from filling; continuation happens |
Note that continuation is different from filling; continuation happens |
121 |
on the screen only, not in the buffer contents, and it breaks a line |
on the screen only, not in the buffer contents, and it breaks a line |
328 |
If the value is zero, then command input is not echoed. |
If the value is zero, then command input is not echoed. |
329 |
@end defvar |
@end defvar |
330 |
|
|
331 |
|
@node Warnings |
332 |
|
@section Reporting Warnings |
333 |
|
@cindex warnings |
334 |
|
|
335 |
|
@dfn{Warnings} are a facility for a program to inform the user of a |
336 |
|
possible problem, but continue running. |
337 |
|
|
338 |
|
@menu |
339 |
|
* Warning Basics:: Warnings concepts and functions to report them. |
340 |
|
* Warning Variables:: Variables programs bind to customize their warnings. |
341 |
|
* Warning Options:: Variables users set to control display of warnings. |
342 |
|
@end menu |
343 |
|
|
344 |
|
@node Warning Basics |
345 |
|
@subsection Warning Basics |
346 |
|
@cindex severity level |
347 |
|
|
348 |
|
Every warning has a textual message, which explains the problem for |
349 |
|
the user, and a @dfn{severity level} which is a symbol. Here are the |
350 |
|
possible severity levels, in order of decreasing severity, and their |
351 |
|
meanings: |
352 |
|
|
353 |
|
@table @code |
354 |
|
@item :emergency |
355 |
|
A problem that will seriously impair Emacs operation soon |
356 |
|
if you do not attend to it promptly. |
357 |
|
@item :error |
358 |
|
A report of data or circumstances that are inherently wrong. |
359 |
|
@item :warning |
360 |
|
A report of data or circumstances that are not inherently wrong, but |
361 |
|
raise suspicion of a possible problem. |
362 |
|
@item :debug |
363 |
|
A report of information that may be useful if you are debugging. |
364 |
|
@end table |
365 |
|
|
366 |
|
When your program encounters invalid input data, it can either |
367 |
|
signal a Lisp error by calling @code{error} or @code{signal} or report |
368 |
|
a warning with severity @code{:error}. Signaling a Lisp error is the |
369 |
|
easiest thing to do, but it means the program cannot continue |
370 |
|
processing. If you want to take the trouble to implement a way to |
371 |
|
continue processing despite the bad data, then reporting a warning of |
372 |
|
severity @code{:error} is the right way to inform the user of the |
373 |
|
problem. For instance, the Emacs Lisp byte compiler can report an |
374 |
|
error that way and continue compiling other functions. (If the |
375 |
|
program signals a Lisp error and then handles it with |
376 |
|
@code{condition-case}, the user won't see the error message; it could |
377 |
|
show the message to the user by reporting it as a warning.) |
378 |
|
|
379 |
|
@cinedex warning type |
380 |
|
Each warning has a @dfn{warning type} to classify it. The type is a |
381 |
|
list of symbols. The first symbol should be the custom group that you |
382 |
|
use for the program's user options. For example, byte compiler |
383 |
|
warnings use the warning type @code{(bytecomp)}. You can also |
384 |
|
subcategorize the warnings, if you wish, by using more symbols in the |
385 |
|
list. |
386 |
|
|
387 |
|
@defun display-warning type message &optional level buffer-name |
388 |
|
This function reports a warning, using @var{message} as the message |
389 |
|
and @var{type} as the warning type. @var{level} should be the |
390 |
|
severity level, with @code{:warning} being the default. |
391 |
|
|
392 |
|
@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer |
393 |
|
for logging the warning. By default, it is @samp{*Warnings*}. |
394 |
|
@end defun |
395 |
|
|
396 |
|
@defun lwarn type level message &rest args |
397 |
|
This function reports a warning using the value of @code{(format |
398 |
|
@var{message} @var{args}...)} as the message. In other respects it is |
399 |
|
equivalent to @code{display-warning}. |
400 |
|
@end defun |
401 |
|
|
402 |
|
@defun warn message &rest args |
403 |
|
This function reports a warning using the value of @code{(format |
404 |
|
@var{message} @var{args}...)} as the message, @code{(emacs)} as the |
405 |
|
type, and @code{:warning} as the severity level. It exists for |
406 |
|
compatibility only; we recommend not using it, because you should |
407 |
|
specify a specific warning type. |
408 |
|
@end defun |
409 |
|
|
410 |
|
@node Warning Variables |
411 |
|
@subsection Warning Variables |
412 |
|
|
413 |
|
Programs can customize how their warnings appear by binding |
414 |
|
the variables described in this section. |
415 |
|
|
416 |
|
@defvar warning-levels |
417 |
|
This list defines the meaning and severity order of the warning |
418 |
|
severity levels. Each element defines one severity level, |
419 |
|
and they are arranged in order of decreasing severity. |
420 |
|
|
421 |
|
Each element has the form @code{(@var{level} @var{string} |
422 |
|
@var{function})}, where @var{level} is the severity level it defines. |
423 |
|
@var{string} specifies the textual description of this level. |
424 |
|
@var{string} should use @samp{%s} to specify where to put the warning |
425 |
|
type information, or it can omit the @samp{%s} so as not to include |
426 |
|
that information. |
427 |
|
|
428 |
|
The optional @var{function}, if non-@code{nil}, is a function to call |
429 |
|
with no arguments, to get the user's attention. |
430 |
|
|
431 |
|
Normally you should not change the value of this variable. |
432 |
|
@end defvar |
433 |
|
|
434 |
|
@defvar warning-prefix-function |
435 |
|
If non-@code{nil}, te value is a function to generate prefix text for |
436 |
|
warnings. Programs can bind the variable to a suitable function. |
437 |
|
@code{display-warning} calls this function with the warnings buffer |
438 |
|
current, and the function can insert text in it. That text becomes |
439 |
|
the beginning of the warning message. |
440 |
|
|
441 |
|
The function is called with two arguments, the severity level and its |
442 |
|
entry in @code{warning-levels}. It should return a list to use as the |
443 |
|
entry (this value need not be an actual member of |
444 |
|
@code{warning-levels}). By constructing this value, the function to |
445 |
|
change the severity of the warning, or specify different handling for |
446 |
|
a given severity level. |
447 |
|
|
448 |
|
If the variable's value is @code{nil} then there is no function |
449 |
|
to call. |
450 |
|
@end defvar |
451 |
|
|
452 |
|
@defvar warning-series |
453 |
|
Programs can bind this variable to @code{t} to say that the next |
454 |
|
warning should begin a series. When several warnings form a series, |
455 |
|
that means to leave point on the first warning of the series, rather |
456 |
|
than keep move it for each warning so that it appears on the last one. |
457 |
|
The series ends when the local binding is unbound and |
458 |
|
@code{warning-series} becomes @code{nil} again. |
459 |
|
|
460 |
|
The value can also be a symbol with a function definition. That is |
461 |
|
equivalent to @code{t}, except that the next warning will also call |
462 |
|
the function with no arguments with the warnings buffer current. The |
463 |
|
function can insert text which will serve as a header for the series |
464 |
|
of warnings. |
465 |
|
|
466 |
|
Once a series has begun, the value is a marker which points to the |
467 |
|
buffer position in the warnings buffer of the start of the series. |
468 |
|
|
469 |
|
The variable's normal value is @code{nil}, which means to handle |
470 |
|
each warning separately. |
471 |
|
@end defvar |
472 |
|
|
473 |
|
@defvar warning-fill-prefix |
474 |
|
When this variable is non-@code{nil}, it specifies a fill prefix to |
475 |
|
use for filling each warning's text. |
476 |
|
@end defvar |
477 |
|
|
478 |
|
@defvar warning-type-format |
479 |
|
This variable specifies the format for displaying the warning type |
480 |
|
in the warning message. The result of formatting the type this way |
481 |
|
gets included in the message under the control of the string in the |
482 |
|
entry in @code{warning-levels}. The default value is @code{" (%s)"}. |
483 |
|
If you bind it to @code{""} then the warning type won't appear at |
484 |
|
all. |
485 |
|
@end defvar |
486 |
|
|
487 |
|
@node Warning Options |
488 |
|
@subsection Warning Options |
489 |
|
|
490 |
|
These variables are used by users to control what happens |
491 |
|
when a Lisp program reports a warning. |
492 |
|
|
493 |
|
@defopt warning-minimum-level |
494 |
|
This user option specifies the minimum severity level that should be |
495 |
|
shown immediately to the user. The default is @code{:warning}, which |
496 |
|
means to immediately display all warnings except @code{:debug} |
497 |
|
warnings. |
498 |
|
@end defopt |
499 |
|
|
500 |
|
@defopt warning-minimum-log-level |
501 |
|
This user option specifies the minimum severity level that should be |
502 |
|
logged in the warnings buffer. The default is @code{:warning}, which |
503 |
|
means to log all warnings except @code{:debug} warnings. |
504 |
|
@end defopt |
505 |
|
|
506 |
|
@defopt warning-suppress-types |
507 |
|
This list specifies which warning types should not be displayed |
508 |
|
immediately for the user. Each element of the list should be a list |
509 |
|
of symbols. If its elements match the first elements in a warning |
510 |
|
type, then that warning is not displayed immediately. |
511 |
|
@end defopt |
512 |
|
|
513 |
|
@defopt warning-suppress-log-types |
514 |
|
This list specifies which warning types should not be logged in the |
515 |
|
warnings buffer. Each element of the list should be a list of |
516 |
|
symbols. If it matches the first few elements in a warning type, then |
517 |
|
that warning is not logged. |
518 |
|
@end defopt |
519 |
@node Invisible Text |
@node Invisible Text |
520 |
@section Invisible Text |
@section Invisible Text |
521 |
|
|
761 |
about to be executed. |
about to be executed. |
762 |
|
|
763 |
@defvar overlay-arrow-string |
@defvar overlay-arrow-string |
|
@cindex fringe, and overlay arrow display |
|
764 |
This variable holds the string to display to call attention to a |
This variable holds the string to display to call attention to a |
765 |
particular line, or @code{nil} if the arrow feature is not in use. |
particular line, or @code{nil} if the arrow feature is not in use. |
766 |
On a graphical display the contents of the string are ignored; instead a |
On a graphical display the contents of the string are ignored; instead a |
2475 |
Chinese GB2312 characters has a wild card @samp{*} in the @var{family} |
Chinese GB2312 characters has a wild card @samp{*} in the @var{family} |
2476 |
field. |
field. |
2477 |
|
|
2478 |
|
@node Fringes |
2479 |
|
@section Fringes |
2480 |
|
@cindex Fringes |
2481 |
|
|
2482 |
|
The @dfn{fringes} of a window are thin vertical strips down the |
2483 |
|
sides that are used for displaying bitmaps that indicate truncation, |
2484 |
|
continuation, and horizontal scrolling, the overlay arrow. The |
2485 |
|
fringes normally appear between the display margins and the window |
2486 |
|
text, but you can put them outside the display margins for a specific |
2487 |
|
buffer by setting @code{fringes-outside-margins} buffer-locally to a |
2488 |
|
non-@code{nil} value. |
2489 |
|
|
2490 |
|
@defvar fringes-outside-margins |
2491 |
|
If the value is non-@code{nil}, the frames appear outside |
2492 |
|
the display margins. |
2493 |
|
@end defvar |
2494 |
|
|
2495 |
|
@defvar left-fringe-width |
2496 |
|
This variable, if non-@code{nil}, specifies the width of the left |
2497 |
|
fringe in pixels. |
2498 |
|
@end defvar |
2499 |
|
|
2500 |
|
@defvar right-fringe-width |
2501 |
|
This variable, if non-@code{nil}, specifies the width of the right |
2502 |
|
fringe in pixels. |
2503 |
|
@end defvar |
2504 |
|
|
2505 |
|
The values of these variables take effect when you display the |
2506 |
|
buffer in a window. If you change them while the buffer is visible, |
2507 |
|
you can call @code{set-buffer-window} to display it in a window again. |
2508 |
|
|
2509 |
|
@defun set-window-fringes window left &optional right outside-margins |
2510 |
|
This function sets the fringe widthes of window @var{window}. |
2511 |
|
If window is @code{nil}, that stands for the selected window. |
2512 |
|
|
2513 |
|
The argument @var{left} specifies the width in pixels of the left |
2514 |
|
fringe, and likewise @var{right} for the right fringe. A value of |
2515 |
|
@code{nil} for either one stands for the default width. If |
2516 |
|
@var{outside-margins} is non-@code{nil}, that specifies that fringes |
2517 |
|
should appear outside of the display margins. |
2518 |
|
@end defun |
2519 |
|
|
2520 |
|
@defun window-fringes window |
2521 |
|
This function returns information about the fringes of a window |
2522 |
|
@var{window}. The value as the form @code{(@var{left-width} |
2523 |
|
@var{right-width} @var{frames-outside-margins}). |
2524 |
|
@end defun |
2525 |
|
|
2526 |
@node Display Property |
@node Display Property |
2527 |
@section The @code{display} Property |
@section The @code{display} Property |
2528 |
@cindex display specification |
@cindex display specification |
3461 |
@defopt indicate-empty-lines |
@defopt indicate-empty-lines |
3462 |
@tindex indicate-empty-lines |
@tindex indicate-empty-lines |
3463 |
@cindex fringes, and empty line indication |
@cindex fringes, and empty line indication |
3464 |
When this is non-@code{nil}, Emacs displays a special glyph in |
When this is non-@code{nil}, Emacs displays a special glyph in the |
3465 |
each empty line at the end of the buffer, on terminals that |
fringe of each empty line at the end of the buffer, on terminals that |
3466 |
support it (window systems). |
support it (window systems). @xref{Fringes}. |
3467 |
@end defopt |
@end defopt |
3468 |
|
|
3469 |
@defopt tab-width |
@defopt tab-width |