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 (see section Text Properties) or a property of an overlay (see section 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 data base. It permits the implementation of convenient filtering commands to view just a part of the entries in the data base. 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.

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 t to make the overlay visible, or nil to make it invisible again.

Go to the first, previous, next, last section, table of contents.