IDE Window: Editor Options Code Folding

From Free Pascal wiki
Revision as of 13:00, 26 March 2010 by Ggeldenhuys (talk | contribs) (Using the Mouse: - spelling mistake)
  • You can get this dialog via:
Menu / Environment / Editor options / Code folding
Source editor / popup menu / Options ...


About

Code folding allows certain structure or blocks of text to be "collapsed". This will hide all but the first line of the block, and the first line will be marked with the folded-symbol "[...]" at the end of that line.

Code folding is done by using a special area in the Gutter which displays the code folding tree. In the tree you will find nodes at the lines were a fold-able region starts.

  • [-] denotes the beginning of a fold-able block, which is not yet folded. This is called an expanded block. Clicking on the [-] Symbol will fold (collapse) this block.
  • [+] denotes the beginning of a fold-able block, which is folded (hidden). This is called an collapsed block. Clicking on the [+] symbol will unfold (expand) this block.
  • | a vertical line is shown in front of lines that belong to a fold-able region, but are not the top line of such a region. The vertical line always begins under the [+] sign and continues to the last line of the block. On the last line it displays a tiny edge.

Fold-able blocks can be nested or overlapped.

Settings

Code folding

The checkbox on top globally enables or disables code folding. If disabled, the Gutter will not display the fold tree neither.

Language specific options

Currently code folding is only supported for Pascal Source

Select (tick) the structures you like to be fold-able

Procedure
Entire procedures or functions
Var/Type (local)
Any var, type or const declaration block that is local to a procedure
Begin/End (procedure)
The begin-end block of a procedure or function. This is the most outer block only, which encloses the entire procedure
Begin/End (nested)
Any other begin-end block.
Repeat
Case
Try
Any entire Try-finally/except-end block
Except/Finally
Allows to fold the code between the Except of finally keyword, up to the "end" of the entire "try" block
Asm
Program
The entire code up to the "end." statement. (this is for "program" files not for units)
unit
The entire unit up to the "end."
unit section
Any interface, implementation, initialization or finalization block
uses
If your uses clause goes over more than one line.
Var/Type (global)
Any var, type or const declaration block (except for the ones local in a procedure)
Class/Object
public/private
Record
Nested comments
{$IFDEF}
Any IFDEF-ELSE-ENDIF
{%Region}
Allows to define your own blocks, by putting this special comment into the code. ends with {%Endregion}

Usage

Using the Mouse

You can click the left mouse buttons on the [+] and [-] symbols to fold/unfold code.

If you have nested nodes a click on a [+]/[-] node will only fold the node starting on this line. Outer or inner nodes are not affected. Inner nodes that where folded will keep there state.

Sometimes you have more than one node starting on the same line. For Example

 {$IFDEF WithFoo} for a := i to 10 do begin

In this case you may want to fold the nodes individually.

Also Not that, if any of the nodes on the line is folded, the default action is to unfold, and the gutter shows a [+] sign. (even though there may be more nodes that can still be folded)

The default mouse settings allow you the following. Note that all clicks only apply to folds starting on this line. Nested folds starting on a different line must be folded by clicking the symbol on their line.

Left Click on [-]
Fold one Node starting on this line. This will fold the node which starts closest to the end of the line ("begin" in the example)
Ctrl-Left Click on [-]
Fold all Node starting on this line.
Alt-Left Click on [-]/[+]
Folds onenode on this line. Each click will fold the next node traversing from the node starting closest to the end of the line to the one closest to the start of the line. This can be used to fold more than one node, because it always folds even if the gutter has a[+] sign.
Middle Click on [-] or [+]
The same as alt-left. Just avoids pressing ctrl
Left Click on [+]
Unfold one Node starting on this line. It will unfold the (folded) node closest to the start of the line. repeated clicks will unfold more nodes
Ctrl-Left Click on [+]
Unfold all Node starting on this line.

Why are nodes folded from the end towards the start of the line? If you have several nodes nested (like 2 {$ifdef); or 2 Repeat) then the inner node must end first (has less or sometimes equal) lines. This inner node is the one that starts second on the line

 Repeat {<<outer}   Repeat {<<inner}
   // do something
   Until InnerFlag = true;
 Until OuterFlag = true;

If you folded the outer ("repeat" towards the start of the line) node first, the inner one was hidden too.

This nesting is however not always true, if you mix {$ifdef} {%region} and pascal language nodes. If you need more control you can use the context menu or see the Advanced Mouse options.


Notes:

  • The middle clicks are not available, if the Mouse settings for the middle button are set to "ignore"
  • You can read the Advanced Mouse options to see how to add more or change the mouse settings.

Using the Context Menu

The Fold-Tree has a special context menu (right mouse button) which allows you to select any node starting on the current line to fold or unfold.

It also shows all nodes that include the current line (all nodes that can hide the current line) and allows to fold them.

Using Keyboard

Binding for the Keyboard can be changed in the options dialog (Environment menu / options), under Editor/"Key Mappings". There is a section "Text Folding commands".

The default are

  • Ctrl+ Shift+- (minus): Fold at the current line. Or if no fold node starts on this line, fold at previous line with a fold node.
  • Ctrl+ Shift++ (plus): Unfold at the current line
  • Ctrl+ Shift+0: Unfold all
  • Ctrl+ Shift+1..9: Fold at the level corresponding with the number
only act on pascal fold nodes (IFDEF and REGION are ignored)
e.g Ctrl+ Shift+2 will fold all nodes that are inside ONE outer fold node
Ctrl+ Shift+1 will fold everything

About {%Region}

 {%region}
 // some code
 {%endregion}
  

Allows to fold arbitrary blocks of code or text. It also accepts {$region}, but this will give a compiler warning.

{%region} is not recognized if it occurs inside a comment or string

 a := ' {%region} ';

does not start a fold-able block

You can specify

 {%region /fold}

if you want the fold to be collapsed automatically, when the file is loaded.