Next: , Previous: Invisible Text, Up: Display

38.7 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. This kind of hiding in some ways resembles the effect of the invisible property (see Invisible Text), but the two features are different and do not work the same way.

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 hidden. 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 hidden text. However, the replacement of newline characters with carriage return characters affects some editing commands. For example, next-line skips hidden lines, since it searches only for newlines. Modes that use selective display can also define commands that take account of the newlines, or that control which parts of the text are hidden.

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

When some portion of a buffer is hidden, the vertical movement commands operate as if that portion did not exist, allowing a single next-line command to skip any number of hidden lines. However, character movement commands (such as forward-char) do not skip the hidden portion, and it is possible (if tricky) to insert or delete text in an hidden 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 ----------
— User Option: selective-display-ellipses

If this buffer-local variable is non-nil, then Emacs displays ‘...’ at the end of a line that is followed by hidden 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 (‘...’). See Display Tables.