Code Folding - User Interface Specification


Author: Gabriel Tichy

$Revision: 1.12 $
Document History: available in CVS

Table of Contents:

1 Introduction
Overview of Functionality
References

2 Detailed Specification
Visual Appearance
Fold Actions
Settings
Menus & Toolbars

3 Notes
Open Issues
Discussion
Required Graphics

Introduction

Overview of Functionality

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:

  • Plus sign - appears at the first line of a collapsed fold
  • Minus sign - appears at the first line of an expanded fold
  • Ending sign - appears at the last line of an expanded fold
  • vertical line - appears between Minus sign and Ending sign of an expanded fold

Plus sign and Minus sign can be clicked by mouse. Clicking on Plus sign sign expands the fold. Clicking on Minus sign 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.

Open Issues

Highlighted in the specification itself.

Discussion

The discussion threads on nbui mailinglist:
[nbdev] Code Folding
[nbui] Code Folding - UI Specification

Required Graphics

Not required any at the moment.

Project Features

About this Project

ui was started in November 2009, is owned by Jiří Kovalský, and has 44 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20160708.bf2ac18). © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
 
 
Close
loading
Please Confirm
Close