Code Folding - User Interface Specification
Author: Gabriel Tichy
$Revision: 1.12 $
Document History: available in CVS
- Table of Contents:
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.
Source Editor contains a new folding margin and a special folding sign (for
collapsed fold) that appears directly in the editing pane.
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
and 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 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|
|import list||everything except first import|
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).
Figure: Tooltip over the fold sign
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:
|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.
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.
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.
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.
DefinitionCode 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.
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.
Highlighted in the specification itself.
The discussion threads on nbui mailinglist:
[nbdev] Code Folding
[nbui] Code Folding - UI Specification
Not required any at the moment.