Folding API

[Neil Hodgson]

   Scintilla has provided low-level support for folding since early in its development but users of Scintilla have been required to build full folding features above this. This was often achieved by copying SciTE's folding code. Some of this functionality has now been moved into Scintilla so that it can be reused more easily. The API is:

SCI_FOLDLINE(int line, int action)
SCI_FOLDCHILDREN(int line, int action)
SCI_FOLDALL(int action)
These messages provide a higher-level approach to folding instead of setting expanded flags and showing or hiding individual lines.

An individual fold can be contracted/expanded/toggled with SCI_FOLDLINE. To affect all child folds as well call SCI_FOLDCHILDREN.

To affect the entire document call SCI_FOLDALL. With SC_FOLDACTION_TOGGLE the first fold header in the document is examined to decide whether to expand or contract.

Symbol	Value	Effect
SC_FOLDACTION_CONTRACT	0	Contract.
SC_FOLDACTION_EXPAND	1	Expand.
SC_FOLDACTION_TOGGLE	2	Toggle between contracted and expanded.

SCI_EXPANDCHILDREN(int line, int level)
This is used to respond to a change to a line causing its fold level or whether it is a header to change, perhaps when adding or removing a '{'.

By the time the container has received the notification that the line has changed, the fold level has already been set, so the container has to use the previous level in this call so that any range hidden underneath this line can be shown.

  These changes still require containers to respond to 3 notifications to fully implement folding: SCN_NEEDSHOWN, SCN_MODIFIED.SC_MOD_CHANGEFOLD, and SCN_MARGINCLICK. A future update will allow Scintilla to provide default implementations for these notifications so that containers can choose to implement folding with default behaviour by just setting one property.

   Neil

[Neil Hodgson]

   Added automatic folding feature. The API is:

SCI_SETAUTOMATICFOLD(int automaticFold)

SCI_GETAUTOMATICFOLD
Instead of implementing all the logic for handling folding in the container, Scintilla can provide behaviour that is adequate for many applications. The automaticFold argument is a bit set defining which of the 3 pieces of folding implementation should be enabled. Most applications should be able to use the SC_AUTOMATICFOLD_SHOW and SC_AUTOMATICFOLD_CHANGE flags unless they wish to implement quite different behavious such as defining their own fold structure. SC_AUTOMATICFOLD_CLICK is more likely to be set off when an application would like to add or change click behaviour such as showing method headers only when Shift+Alt is used in conjunction with a click.

Symbol	Value	Effect
SC_AUTOMATICFOLD_SHOW	1	Automatically show lines as needed. This avoids sending the SCN_NEEDSHOWN notification.
SC_AUTOMATICFOLD_CLICK	2	Handle clicks in fold margin automatically. This avoids sending the SCN_MARGINCLICK notification for folding margins.
SC_AUTOMATICFOLD_CHANGE	4	Show lines as needed when fold structure is changed. The SCN_MODIFIED notification is still sent unless it is disabled by the container.

   Neil

[Edwin]

Well done, Neil!

[RaptorX]

This is awesome!