IDE Window: Editor Options Code Folding

From Free Pascal wiki
Jump to navigationJump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

English (en)

This is part of the online help for the IDE.
It describes the section: "Editor" / "Code Folding". You can open the described dialog in your IDE via:

  • The menu: "Tools" => "Options" / Editor options ...
  • The source-editor pop-up menu: "Editor properties ...

Navigation

     

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. This tree has a node corresponding to each line of text at which a foldable region starts.

  • [-] denotes the beginning of an unfolded foldable block, also termed an expanded block. Clicking on the [-] symbol will fold (collapse) this block.
  • [+] denotes the beginning of a folded foldable block, i.e. a collapsed block in which all but the first line is already folded (hidden). Clicking on the [+] symbol will unfold (expand) this block.
  • | A vertical line is shown to the left of all foldable lines except the top line of such a foldable region. The vertical line begins immediately below the [+] sign and continues to the last line of the foldable block. On the last line it displays a tiny edge.

Foldable blocks can be nested or overlapped.

Settings

Code folding

The checkbox at the top enables or disables code folding globally in all source code windows. If disabled, folding functionality is removed, and the Gutter no longer displays a fold tree.

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 (Tools -> Options), under Editor/"Key Mappings". There is a section "Text Folding commands".

The default are

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