Program source code and other structured text files can be thought of as containing a hierarchy of sections, which themselves might contain sub-sections. The folding feature lets you selectively hide and show these sections, replacing hidden ones with a single line that serves as an “overview” of that section. Folding is disabled by default. To enable it, you must choose one of the available folding modes.
“Indent” mode creates folds based on a line's leading whitespace; the more leading whitespace a block of text has, the further down it is in the hierarchy. For example:
This is a section This is a sub-section This is another sub-section This is a sub-sub-section Another top-level section
“Explicit” mode folds away blocks of text surrounded with “{{{” and “}}}”. For example:
{{{ The first line of a fold. When this fold is collapsed, only the above line will be visible. {{{ A sub-section. With text inside it. }}} {{{ Another sub-section. }}} }}}
Both modes have distinct advantages and disadvantages; indent folding requires no changes to be made to a buffer's text and does a decent job with most program source. Explicit folding requires “fold markers” to be inserted into the text, but is more flexible in exactly what to fold away.
Some plugins might add additional folding modes; see Chapter 9, Installing and Using Plugins for information about plugins.
Folding can be enabled in one of several ways:
On a global or mode-specific basis in the Editing pane of the Utilities>Global Options dialog box. See the section called “The Editing Pane”.
In the current buffer for the duration of the editing session in the Utilities>Buffer Options dialog box. See the section called “The Buffer Options Dialog Box”.
In the current buffer for future editing sessions
by placing the following in the first or last 10 lines of a buffer,
where mode
is either “indent”,
“explicit”, or the name of a plugin folding mode:
:folding=mode
:
When using indent folding, portions of the buffer may become inaccessible if you change the leading indent of the first line of a collapsed fold. If you experience this, you can use the Expand All Folds command to make the text visible again.
The first line of each fold has a triangle
drawn next to it in the gutter (see the section called “Interface Overview” for
more information about the gutter). The triangle points toward the
line when the fold is collapsed, and downward when the fold is
expanded.
Clicking the triangle collapses and
expands the fold. To expand all sub-folds as well, hold down the
Shift
while clicking.
The first line of a collapsed fold is drawn with a background color that depends on the fold level, and the number of lines in the fold is shown to the right of the line's text.
Folds can also be collapsed and expanded using menu item commands and keyboard shortcuts.
Folding>Collapse
Fold (shortcut: A+BACK_SPACE
)
collapses the fold
containing the caret.
Folding>Expand
Fold One Level (shortcut: A+ENTER
)
expands the
fold containing the caret. Nested folds will remain collapsed,
and the caret will be positioned on the first nested fold (if any).
Folding>Expand
Fold Fully (shortcut: AS+ENTER
)
expands the fold
containing the caret, also expanding any nested folds.
Folding>Collapse
All Folds (shortcut: C+e c
)
collapses all folds in the buffer.
Folding>Expand
All Folds (shortcut: C+e x
)
expands all folds in the buffer.
Folding>Go to Parent
Fold (shortcut: C+e u
) moves
the caret to the fold containing the one at the caret position.
Folding>Go to Previous
Fold (shortcut: A+UP
) moves
the caret to the fold immediately before the caret position.
Folding>Go to Next
Fold (shortcut: A+DOWN
) moves
the caret to the fold immediately after the caret position.
Folding>Add
Explicit Fold (shortcut: C+e a
)
surrounds the
selection with “{{{” and “}}}”. If the
current buffer's edit mode defines comment strings (see
the section called “Commenting Out Code”) the explicit fold markers will
automatically be commented out as well.
Folding>Select
Fold
(shortcut: C+e s
)
selects all lines within the fold containing the caret.
Control
-clicking a fold expansion triangle
in the gutter has the same effect.
Folding>Expand
Folds With Level (shortcut:
C+e ENTER
)
reads the next character entered at the keyboard, and
expands folds in the buffer
with a fold level less than that specified, while collapsing all others.
key
Sometimes it is desirable to have files open with folds initially collapsed. This can be configured as follows:
On a global or mode-specific basis in the Editing pane of the Utilities>Global Options dialog box. See the section called “The Editing Pane”.
In the current buffer for future editing sessions
by placing the following in the first or last 10 lines of a buffer,
where level
is the desired fold level:
:collapseFolds=level
:
The narrowing feature temporarily “narrows” the display of a buffer to a specified region. Text outside the region is not shown, but is still present in the buffer.
Holding down Alt
while clicking a fold expansion triangle in the gutter will hide all lines the buffer except
those contained in the clicked fold.
Folding>Narrow
Buffer to Fold (shortcut: C+e n n
)
hides all lines the buffer except
those in the fold containing the caret.
Folding>Narrow
Buffer to Selection (shortcut: C+e n s
)
hides all lines the buffer
except those in the selection.
Folding>Expand
All Folds (shortcut: C+e x
)
shows lines that were hidden as a result of narrowing.