GNU Info

(elisp)Invisible Text

---

Next: Selective Display Prev: The Echo Area Up: Display

---

Enter node , (file) or (file)node

Invisible Text
==============

   You can make characters "invisible", so that they do not appear on
the screen, with the `invisible' property.  This can be either a text
property (Note: Text Properties) or a property of an overlay (Note:
Overlays).

   In the simplest case, any non-`nil' `invisible' property makes a
character invisible.  This is the default case--if you don't alter the
default value of `buffer-invisibility-spec', this is how the
`invisible' property works.

   More generally, you can use the variable `buffer-invisibility-spec'
to control which values of the `invisible' property make text
invisible.  This permits you to classify the text into different subsets
in advance, by giving them different `invisible' values, and
subsequently make various subsets visible or invisible by changing the
value of `buffer-invisibility-spec'.

   Controlling visibility with `buffer-invisibility-spec' is especially
useful in a program to display the list of entries in a database.  It
permits the implementation of convenient filtering commands to view
just a part of the entries in the database.  Setting this variable is
very fast, much faster than scanning all the text in the buffer looking
for properties to change.

 - Variable: buffer-invisibility-spec
     This variable specifies which kinds of `invisible' properties
     actually make a character invisible.

    `t'
          A character is invisible if its `invisible' property is
          non-`nil'.  This is the default.

    a list
          Each element of the list specifies a criterion for
          invisibility; if a character's `invisible' property fits any
          one of these criteria, the character is invisible.  The list
          can have two kinds of elements:

         `ATOM'
               A character is invisible if its `invisible' property
               value is ATOM or if it is a list with ATOM as a member.

         `(ATOM . t)'
               A character is invisible if its `invisible' property
               value is ATOM or if it is a list with ATOM as a member.
               Moreover, if this character is at the end of a line and
               is followed by a visible newline, it displays an
               ellipsis.

   Two functions are specifically provided for adding elements to
`buffer-invisibility-spec' and removing elements from it.

 - Function: add-to-invisibility-spec element
     Add the element ELEMENT to `buffer-invisibility-spec' (if it is
     not already present in that list).

 - Function: remove-from-invisibility-spec element
     Remove the element ELEMENT from `buffer-invisibility-spec'.  This
     does nothing if ELEMENT is not in the list.

   One convention about the use of `buffer-invisibility-spec' is that a
major mode should use the mode's own name as an element of
`buffer-invisibility-spec' and as the value of the `invisible' property:

     ;; If you want to display an ellipsis:
     (add-to-invisibility-spec '(my-symbol . t))
     ;; If you don't want ellipsis:
     (add-to-invisibility-spec 'my-symbol)
     
     (overlay-put (make-overlay beginning end)
                  'invisible 'my-symbol)
     
     ;; When done with the overlays:
     (remove-from-invisibility-spec '(my-symbol . t))
     ;; Or respectively:
     (remove-from-invisibility-spec 'my-symbol)

   Ordinarily, commands that operate on text or move point do not care
whether the text is invisible.  The user-level line motion commands
explicitly ignore invisible newlines if `line-move-ignore-invisible' is
non-`nil', but only because they are explicitly programmed to do so.

   Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text.  To enable
this, the overlay should have a non-`nil' `isearch-open-invisible'
property.  The property value should be a function to be called with
the overlay as an argument.  This function should make the overlay
visible permanently; it is used when the match overlaps the overlay on
exit from the search.

   During the search, such overlays are made temporarily visible by
temporarily modifying their invisible and intangible properties.  If you
want this to be done differently for a certain overlay, give it an
`isearch-open-invisible-temporary' property which is a function.  The
function is called with two arguments: the first is the overlay, and
the second is `nil' to make the overlay visible, or `t' to make it
invisible again.