GNU Info

(elisp)Selective Display

---

Next: Overlay Arrow Prev: Invisible Text Up: Display

---

Enter node , (file) or (file)node

Selective Display
=================

   "Selective display" refers to a pair of related features for hiding
certain lines on the screen.

   The first variant, explicit selective display, is designed for use in
a Lisp program: it controls which lines are hidden by altering the text.
The invisible text feature (Note: Invisible Text) has partially
replaced this feature.

   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 Emacs.

 - 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 the character
          control-m marks the start of invisible text; the control-m,
          and the rest of the line following it, are not displayed.
          This is explicit selective display.

        * 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 Emacs 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.