Info Catalog elisp: Invisible Text elisp: Display elisp: Temporary Displays

elisp: Selective Display

 
 37.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, was designed for use
 in a Lisp program: it controls which lines are hidden by altering the
 text.  This kind of hiding is now obsolete; instead you can get the same
 effect with the ‘invisible’ property (Invisible Text).
 
    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.
 
         • If the value of ‘selective-display’ is ‘t’, then the character
           control-m marks the start of hidden 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 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 (‘...’).  Display Tables.
 

Info Catalog elisp: Invisible Text elisp: Display elisp: Temporary Displays