/[emacs]/emacs/lispref/display.texi
ViewVC logotype

Diff of /emacs/lispref/display.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.95 by rms, Tue Jul 22 15:25:22 2003 UTC revision 1.96 by rms, Wed Aug 6 01:23:14 2003 UTC
# Line 15  that Emacs presents to the user. Line 15  that Emacs presents to the user.
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.
# Line 23  that Emacs presents to the user. Line 24  that Emacs presents to the user.
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.
# Line 111  the rightmost column indicates a line th Line 113  the rightmost column indicates a line th
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
# Line 327  sequence are echoed immediately.) Line 328  sequence are echoed immediately.)
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    
# Line 572  interface to debuggers, the overlay arro Line 761  interface to debuggers, the overlay arro
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
# Line 2287  Then, the font specifications for all bu Line 2475  Then, the font specifications for all bu
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
# Line 3225  buffers that do not override it.  @xref{ Line 3461  buffers that do not override it.  @xref{
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

Legend:
Removed from v.1.95  
changed lines
  Added in v.1.96

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26