Code folding allows to collapse (hide) and expand certain parts of the document. These parts are called folds and they can be nested (fold can contain another fold). The fold can occupy more lines but it can be also just part of the one line. Folds are visualized in the document.

References

Please see the following User View document, which provide the foundation concepts for this document.

Detailed Specification

Code folds are created by editor depending on supported fold types for a particular source code. When a file is opened, all folds are identified and expanded by default, so the user can see the whole source code. However, he can define which fold types are collapsed when he opens a file.

Visual Appearance

Source Editor contains a new folding margin and a special folding sign (for collapsed fold) that appears directly in the editing pane.

Figure: Editor with the code folding feature (Fold signs are not in final shape)

Folding Margin

Folding margin is placed next to the margin for annotations glyphs and line numbers. However, it is visible only in documents which have the code folding feature turned on.

It is used for displaying these signs:

- appears at the first line of a collapsed fold
- appears at the first line of an expanded fold
- appears at the last line of an expanded fold
vertical line - appears between and of an expanded fold

Plus sign and Minus sign can be clicked by mouse. Clicking on sign expands the fold. Clicking on collapses the fold.

If showing of the line numbers is activated and some fold is collapsed, line numbers ordering is changed accordingly.

Fold Sign

Fold sign represents the hidden part of a collapsed fold. It has the same color as folding margin signs. Text content used in a fold sign consist of three characters using the default font of the document.
Different fold types can have different fold sign contents. Here is the table of fold signs used for Java source code:

Fold type	Fold Sign	What is hidden
method body		method body including braces
inner class body		class body including braces
javadoc comment		everything
import list		everything except first import

Fold Sign is the universal fold sign which can be used also for other fold types.

While editing, user can enter only first character of the fold sign with the caret. If he starts typing, the caret is automatically moved before the fold sign.

Double-click on the fold sign expands the fold. Mouse over the fold sign displays a tooltip. Tooltip shows the whole fold code (including the editor margin). Keyboard shortcut to display a tooltip (if the caret is inside fold sign) is Ctrl+F1 (common shortcut to display tooltips).

Fold Sign Tooltip
Figure: Tooltip over the fold sign

Fold Actions

Actions appear both in the main menu and in the editor right-click menu. See Menus & Toolbars section for details.
Here is the table of fold actions:

Action	Shortcut	Description
Collapse Fold	Ctrl+Minus	Collapse a fold. Depends on the current caret position.*
Expand Fold	Ctrl+Plus	Expand a fold. Depends on the current caret position.*
Collapse All Folds	Ctrl+Shift+Minus	Collapse all existing folds in the document.
Expand All Folds	Ctrl+Shift+Plus	Expand all existing folds in the document.
Collapse All Javadoc		Collapse all existing javadoc comments in the document.
Expand All Javadoc		Expand all existing javadoc comments in the document.
Collapse All Java Code		Collapse all code folds except javadoc comments.
Expand All Java Code		Expand all code folds except javadoc comments.

* The caret remembers its position. After collapse action, caret tries to have the same horizontal position (row number) as before. If collapse and expand actions are called (without moving the caret), an absolute caret position is not changed.

Settings

Code Folding property editor

Code Folding property is added to editor types for which the code folding can be used (Options -> Editing -> Editor Settings -> [*] Editor -> Properties tab -> Code Folding property).

|-----------------------------------------------|
| Code Folding                                  |
|-----------------------------------------------|
|                                               |
| [x] Use Code Folding                          |
|                                               |
| Fold Types Collapsed by Default:              |
|  [x] Method                                   |
|  [x] Inner Class                              |
|  [x] Import                                   |
|  [x] Javadoc Comment                          |
|  [x] Initial Comment                          |
|                                               |
|                                               |
|                     OK     Cancel     Help    |
|-----------------------------------------------|

Components of this property editor are:

Use Code Folding checkbox. If unchecked, code folding feature is disabled for this particular editor type (i.e. code folding margin is not displayed in editor as well). Following checkbox group is disabled as well.
Fold Types Collapsed by Default checkbox group. Contains all fold types of a particular document type.

Colors

Font and Colors property editor (Options -> Editing -> Editor Settings -> [*] Editor -> Properties tab -> Fonts & Colors) contains new Code Folding category:

Background Color changes a background color of the code folding margin and fold sign. Inherited by default.
Foreground Color changes a color of the fold sign and fold margin signs. RGB 102-102-102 value is used by default.
Font changes the font used for the fold sign text content. Inherited by default.

Menus & Toolbars

Code Folds submenu

Code Folds submenu contains all fold actions, i.e. four Collapse/Expand pairs which are divided by separators. Submenu itself appears in the View menu (of the main window) and source editor right-click menu.

Example: View -> Code Folds -> Expand Fold.

Custom Folds

Custom folds are folds specified directly in the code with special markers. They have bigger priority than java (or other language dependent) folds. If any custom fold overlaps java fold, only custom fold will be active. If custom fold is removed, java fold automatically appears again then.

Definition

Code folding markers have to be specified in the comments so that it can be made persistent as well as come from normal programming practices using even non-netbeans edit.

// <editor-fold defaultstate="collapsed" desc="user-description">
  ...any code...
// </editor-fold>

editor-fold tag - tags beginning and ending of the custom fold.
defaultstate - the fold is collapsed by default if the value is "collapsed", otherwise it's expanded.
desc - description, used as fold sign content when collapsed; name cannot contain quotes, special '\t' and '\n' characters.

Notes

Regarding supported (language dependent) fold types, specification covers only Java language. Fold types for other languages needs to be worked out gradually. Then, for each of them Code Folding property editor changes accordingly (fold signs as well possibly).

User View and previous design considered two fold modes: Default (language dependent) and User Defined (by selection of a part of the text). However, User Defined folds are not allowed for the meantime.