IDE Window: Editor Options Code Folding: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		This is part of the online help for the IDE. \
2	2		It describes the section: "Editor" / "Code Folding". You can open the described dialog in your IDE via:\
3	3		*The menu: "Tools" =\> "Options" / Editor options ...
4	4
5	5		- The source-editor pop-up context menu: "Options"
6	6
7	7		Navigation\
8	8
9	9		- [[IDE Window: Editor Options\|Editor Options]] Overview of all Editor Options
10	10
11	11
12	12
13	13		- [[IDE Window: IDE Options Dialog\|IDE Options]] Overview of all options for the IDE
14	14
15	15		------------------------------------------------------------------------
16	16
17	17		# About
18	18
19	19		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.
20	20
21	21		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.
22	22
23	23		- \[-\] denotes the beginning of an unfolded foldable block, also termed an expanded block. Clicking on the \[-\] symbol will fold (collapse) this block.
24	24		- \[+\] 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.
25	25		- \\| 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.
26	26
27	27		Foldable blocks can be nested or overlapped.
28	28
29	29		# Settings
30	30
31	31		## Code folding
32	32
33	33		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.
34	34
35	35		## Language specific options
36	36
37	37		Currently code folding is only supported for source code editors which are showing Object Pascal files (.pas, .pp, .lpr etc.), HTML, XML, standard text diff format files, or form files created by the Designer (usually named .lfm or *.dfm). For the editor to know which kind of lines and blocks of Pascal code should be foldable you have to specify what you want. At first installation, the Lazarus IDE sets a few of the following as defaults, but all are optional.
38	38
39	39		Select (tick) the Pascal sections you want to be foldable.
40	40
41	41		Procedure
42	42		Folds entire procedures or functions
43	43
44	44		Var/Type (local)
45	45		Folds any var, type or const declaration block that is local to a procedure
46	46
47	47		Begin/End (procedure)
48	48		Folds the begin-end block of a procedure or function. This is the outermost block (the one enclosing the whole procedure)
49	49
50	50		Begin/End (nested)
51	51		Folds any other begin-end block
52	52
53	53		Repeat
54	54
55	55		Case
56	56
57	57		Try
58	58		Folds any entire Try-finally/except-end block
59	59
60	60		Except/Finally
61	61		Lets you fold any code between the "except" or "finally" keyword and the closing "end" of the "try" block
62	62
63	63		Asm
64	64
65	65		Program
66	66		Folds the entire code up to the "end." statement. This applies to program files (.lpr, .dpr) not to units.
67	67
68	68		unit
69	69		Folds the entire unit up to the "end."
70	70
71	71		unit section
72	72		Folds any interface, implementation, initialization or finalization block
73	73
74	74		uses
75	75		If your uses clause goes over more than one line, you can fold it with this option
76	76
77	77		Var/Type (global)
78	78		Folds any var, type or const declaration block not local to a procedure/function/method
79	79
80	80		Class/Object
81	81
82	82		public/private
83	83
84	84		Record
85	85
86	86		Nested comments
87	87
88	88		{\$IFDEF}
89	89		Folds any IFDEF-ELSE-ENDIF
90	90
91	91		{%Region}
92	92		This lets you define your own blocks, by inserting this special IDE directive into your code. It needs a matching {%Endregion} directive later at the appropriate point. IDE directives are special comments recognised by the Lazarus IDE, but ignored by the compiler. As with standard Pascal syntax the character case of "region" and "endregion" does not matter. However, to be recognised as a fold directive there can be no spaces in the directive ({%ReGiOn} works, but {% Region} does not).
93	93
94	94		# Usage
95	95
96	96		## Using the Mouse
97	97
98	98		You can click the left mouse buttons on the \[+\] and \[-\] symbols to fold/unfold code.
99	99
100	100		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 were folded will keep their original state.
101	101
102	102		Sometimes you have more than one node starting on the same line. For Example
103	103
104		-	~~` {$IFDEF WithFoo} for a := i to 10 do begin`~~
	104	+	``` pascal
	105	+	{$IFDEF WithFoo} for a := i to 10 do begin
	106	+	```
105	107
106	108		In this case you may want to fold the nodes individually.
107	109
108	110		Note: 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).
109	111
110	112		The default mouse settings allow you to change various mouse/key combinations. Note that any clicks apply only to folds starting on this line. Nested folds starting on a different line must be folded by clicking the symbol on their line.
111	113
112	114		Left Click on \[-\]
113	115		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 above)
114	116
115	117		Ctrl-Left Click on \[-\]
116	118		Fold all nodes starting on this line.
117	119
118	120		Alt-Left Click on \[-\]/\[+\]
119	121		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.
120	122
121	123		Middle Click on \[-\] or \[+\]
122	124		The same as alt-Left, but saves you having to pressing Ctrl.
123	125
124	126		Left Click on \[+\]
125	127		Unfold one Node starting on this line. It will unfold the (folded) node closest to the start of the line. Repeated clicks unfold further nodes (if any)
126	128
127	129		Ctrl-Left Click on \[+\]
128	130		Unfold all nodes starting on this line.
129	131
130	132		Why are nodes folded from the end towards the start of the line? If you have several nodes nested (such as two {\$ifdef}s, or two repeat...until blocks) then the inner node must end first (because it probably has fewer lines). This inner node is the one that starts second on the line
131	133
132		-	~~` Repeat {<<outer} Repeat {<<inner}`\~~
133		-	~~` // do something`\~~
134		-	~~` Until InnerFlag = true;`\~~
135		-	~~` Until OuterFlag = true;`~~
	134	+	```text
	135	+	Repeat {<<outer} Repeat {<<inner}
	136	+	// do something
	137	+	Until InnerFlag = true;
	138	+	Until OuterFlag = true;
	139	+	```
136	140
137	141		If you folded the outer (first) "repeat" node first, the inner one would be hidden too.
138	142
139	143		However, this nesting is not always the case if you mix {\$ifdef} {%region} and Pascal language nodes. If you need more control you can use the context menu, or see the [[IDE Window: EditorMouseOptionsAdvanced\|Advanced Mouse options]].
140	144
141	145		Notes:
142	146
143	147		- Mouse middle clicks are unavailable, if the [[IDE Window: Editor Options Mouse\|Mouse settings]] for the middle button are set to "ignore"
144	148		- You can read [[IDE Window: EditorMouseOptionsAdvanced\|Advanced Mouse options]] to see how to add further mouse settings, or change existing mouse settings.
145	149
146	150		## Using the Context Menu
147	151
148	152		The Fold-Tree has a special context menu (accessed via a right mouse button click) which allows you to select any node starting on the current line to fold or unfold.
149	153
150	154		It also shows all nodes that include the current line (all nodes that can hide the current line) and lets you fold them.
151	155
152	156		## Using Keyboard
153	157
154	158		Bindings for the Keyboard can be changed in the Options dialog (Tools -\> Options...), under Editor/"Key Mappings". There is a section "Text Folding commands".
155	159
156	160		The defaults are
157	161
158	162		- `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.
159	163		- `Alt`+`Shift`+`+ (plus)`: Unfold at the current line
160	164		- `Alt`+`Shift`+`0`: Unfold all
161	165		- `Alt`+`Shift`+`1..9`: Fold at the level corresponding with the number
162	166
163	167
164	168		only act on Pascal fold nodes (IFDEF and REGION are ignored)
165	169
166	170		e.g `Alt`+`Shift`+`2` will fold all nodes that are inside ONE outer fold node
167	171
168	172		`Alt`+`Shift`+`1` will fold everything
169	173
170	174		# About {%Region}
171	175
172		-	~~` {%region}`\~~
173		-	~~` // some code`\~~
174		-	~~` {%endregion}`\~~
175		-	~~` `~~
	176	+	```text
	177	+	{%region}
	178	+	// some code
	179	+	{%endregion}
	180	+	```
176	181
177	182		This directive lets you fold arbitrary blocks of code or text. It also accepts {\$region}, but this will give a compiler warning.
178	183
179	184		{%region} is not recognized if it occurs inside a comment or string, so
180	185
181		-	~~` a := ' {%region} ';`~~
	186	+	``` pascal
	187	+	a := ' {%region} ';
	188	+	```
182	189
183	190		does not start a foldable block
184	191
185	192		You can specify
186	193
187		-	~~` {%region /fold}`~~
	194	+	```text
	195	+	{%region /fold}
	196	+	```
188	197
189	198		if you want the fold to start out collapsed on first loading the file.
190	199
191	200		---
192	201		From the Free Pascal wiki, page "IDE Window: Editor Options Code Folding", as it stood on 2021-01-30 after a change by FTurtle, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history