Folding

The fundamental operation in folding is making lines invisible or visible. Line visibility is a property of the view rather than the document so each view may be displaying a different set of lines. From the point of view of the user, lines are hidden and displayed using fold points. Generally, the fold points of a document are based on the hierarchical structure of the document contents. In Python, the hierarchy is determined by indentation and in C++ by brace characters. This hierarchy can be represented within a Scintilla document object by attaching a numeric “fold level” to each line. The fold level is most easily set by a lexer, but you can also set it with messages.

It is up to your code to set the connection between user actions and folding and unfolding. The best way to see how this is done is to search the SciTE source code for the messages used in this section of the documentation and see how they are used. You will also need to use markers and a folding margin to complete your folding implementation. The “fold” property should be set to “1” with child_set_property() (“fold”, “1”) to enable folding.

gtkscintilla.Scintilla.visible_from_doc_line(docLine)

When some lines are folded, then a particular line in the document may be displayed at a different position to its document position. If no lines are folded, this message returns docLine. Otherwise, this returns the display line (counting the very first visible line as 0). The display line of an invisible line is the same as the previous visible line. The display line number of the first line in the document is 0. If there is folding and docLine is outside the range of lines in the document, the return value is -1. Lines can occupy more than one display line if they wrap.

gtkscintilla.Scintilla.doc_line_from_visible(displayLine)

When some lines are hidden, then a particular line in the document may be displayed at a different position to its document position. This message returns the document line number that corresponds to a display line (counting the display line of the first line in the document as 0). If displayLine is less than or equal to 0, the result is 0. If displayLine is greater than or equal to the number of displayed lines, the result is the number of lines in the document.

gtkscintilla.Scintilla.show_lines(lineStart, lineEnd)

gtkscintilla.Scintilla.hide_lines(lineStart, lineEnd)

gtkscintilla.Scintilla.get_line_visible(line)

The first two messages mark a range of lines as visible or invisible and then redraw the display. The third message reports on the visible state of a line and returns 1 if it is visible and 0 if it is not visible. These messages have no effect on fold levels or fold flags. The first line can not be hidden.

gtkscintilla.Scintilla.set_fold_level(line, level)

gtkscintilla.Scintilla.set_fold_level(line)

These two messages set and get a 32-bit value that contains the fold level of a line and some flags associated with folding. The fold level is a number in the range 0 to SC_FOLDLEVELNUMBERMASK (4095). However, the initial fold level is set to SC_FOLDLEVELBASE (1024) to allow unsigned arithmetic on folding levels. There are two addition flag bits. SC_FOLDLEVELWHITEFLAG indicates that the line is blank and allows it to be treated slightly different then its level may indicate. For example, blank lines should generally not be fold points and will be considered part of the preceding section even though they may have a lesser fold level. SC_FOLDLEVELHEADERFLAG indicates that the line is a header (fold point).

Use set_fold_level() (line, thisLevel | SC_FOLDLEVELHEADERFLAG). If you use a lexer, you should not need to use set_fold_level() as this is far better handled by the lexer. You will need to use set_fold_level() to decide how to handle user folding requests. If you do change the fold levels, the folding margin will update to match your changes.

gtkscintilla.Scintilla.set_fold_flags(flags)

In addition to showing markers in the folding margin, you can indicate folds to the user by drawing lines in the text area. The lines are drawn in the foreground colour set for STYLE_DEFAULT. Bits set in flags determine where folding lines are drawn:

Value Effect 1 Experimental - draw boxes if expanded 2 Draw above if expanded 4 Draw above if not expanded 8 Draw below if expanded 16 Draw below if not expanded 64 display hexadecimal fold levels in line margin to aid debugging of folding. This feature needs to be redesigned to be sensible.

This message causes the display to redraw.

gtkscintilla.Scintilla.get_last_child(startLine, level)

This message searches for the next line after startLine, that has a folding level that is less than or equal to level and then returns the previous line number. If you set level to -1, level is set to the folding level of line startLine. If from is a fold point, get_last_child() (from, -1) returns the last line that would be in made visible or hidden by toggling the fold state.

gtkscintilla.Scintilla.get_fold_parent(startLine)

This message returns the line number of the first line before startLine that is marked as a fold point with SC_FOLDLEVELHEADERFLAG and has a fold level less than the startLine. If no line is found, or if the header flags and fold levels are inconsistent, the return value is -1.

gtkscintilla.Scintilla.toggle_fold(line)

Each fold point may be either expanded, displaying all its child lines, or contracted, hiding all the child lines. This message toggles the folding state of the given line as long as it has the SC_FOLDLEVELHEADERFLAG set. This message takes care of folding or expanding all the lines that depend on the line. The display updates after this message.

gtkscintilla.Scintilla.set_fold_expanded(line, expanded)

gtkscintilla.Scintilla.set_fold_expanded(line)

These messages set and get the expanded state of a single line. The set message has no effect on the visible state of the line or any lines that depend on it. It does change the markers in the folding margin. If you ask for the expansion state of a line that is outside the document, the result is false (0).

If you just want to toggle the fold state of one line and handle all the lines that are dependent on it, it is much easier to use toggle_fold() . You would use the set_fold_expanded() message to process many folds without updating the display until you had finished. See SciTEBase::FoldAll() and SciTEBase::Expand() for examples of the use of these messages.

gtkscintilla.Scintilla.ensure_visible(line)

gtkscintilla.Scintilla.ensure_visible_enforce_policy(line)

A line may be hidden because more than one of its parent lines is contracted. Both these message travels up the fold hierarchy, expanding any contracted folds until they reach the top level. The line will then be visible. If you use ensure_visible_enforce_policy() , the vertical caret policy set by child_set() TVISIBLEPOLICY is then applied.