Buffer

class Buffer(**properties: Any)

Superclasses: TextBuffer, Object

Subclass of TextBuffer.

A GtkSourceBuffer object is the model for View widgets. It extends the TextBuffer class by adding features useful to display and edit source code such as syntax highlighting and bracket matching.

To create a GtkSourceBuffer use new or new_with_language. The second form is just a convenience function which allows you to initially set a Language. You can also directly create a View and get its Buffer with get_buffer.

The highlighting is enabled by default, but you can disable it with set_highlight_syntax.

Context Classes:

It is possible to retrieve some information from the syntax highlighting engine. The default context classes that are applied to regions of a GtkSourceBuffer:

• comment: the region delimits a comment;

• no-spell-check: the region should not be spell checked;

• path: the region delimits a path to a file;

• string: the region delimits a string.

Custom language definition files can create their own context classes, since the functions like iter_has_context_class take a string parameter as the context class.

GtkSourceBuffer provides an API to access the context classes: iter_has_context_class, get_context_classes_at_iter, iter_forward_to_context_class_toggle and iter_backward_to_context_class_toggle.

And the highlight_updated signal permits to be notified when a context class region changes.

Each context class has also an associated TextTag with the name gtksourceview:context-classes:<name>. For example to retrieve the TextTag for the string context class, one can write:

GtkTextTagTable *tag_table;
GtkTextTag *tag;

tag_table = gtk_text_buffer_get_tag_table (buffer);
tag = gtk_text_tag_table_lookup (tag_table, "gtksourceview:context-classes:string");

The tag must be used for read-only purposes.

Accessing a context class via the associated TextTag is less convenient than the GtkSourceBuffer API, because:

• The tag doesn’t always exist, you need to listen to the tag_added and tag_removed signals.

• Instead of the highlight_updated signal, you can listen to the apply_tag and remove_tag signals.

A possible use-case for accessing a context class via the associated TextTag is to read the region but without adding a hard dependency on the GtkSourceView library (for example for a spell-checking library that wants to read the no-spell-check region).

Constructors

class Buffer

classmethod new(table: TextTagTable | None = None) → Buffer

Creates a new source buffer.

Parameters:

table – a TextTagTable, or None to create a new one.

classmethod new_with_language(language: Language) → Buffer

Creates a new source buffer using the highlighting patterns in language.

This is equivalent to creating a new source buffer with a new tag table and then calling set_language.

Parameters:

language – a Language.

Methods

class Buffer

backward_iter_to_source_mark(category: str | None = None) → tuple[bool, TextIter]

Moves iter to the position of the previous Mark of the given category.

Returns True if iter was moved. If category is NULL, the previous source mark can be of any category.

Parameters:

category – category to search for, or None

change_case(case_type: ChangeCaseType, start: TextIter, end: TextIter) → None

Changes the case of the text between the specified iterators.

Since 5.4, this function will update the position of start and end to surround the modified text.

Parameters:

• case_type – how to change the case.

• start – a TextIter.

• end – a TextIter.

create_source_mark(name: str | None, category: str, where: TextIter) → Mark

Creates a source mark in the buffer of category category.

A source mark is a TextMark but organized into categories. Depending on the category a pixbuf can be specified that will be displayed along the line of the mark.

Like a TextMark, a Mark can be anonymous if the passed name is None. Also, the buffer owns the marks so you shouldn’t unreference it.

Marks always have left gravity and are moved to the beginning of the line when the user deletes the line they were in.

Typical uses for a source mark are bookmarks, breakpoints, current executing instruction indication in a source file, etc..

Parameters:

• name – the name of the mark, or None.

• category – a string defining the mark category.

• where – location to place the mark.

ensure_highlight(start: TextIter, end: TextIter) → None

Forces buffer to analyze and highlight the given area synchronously.

Note:

This is a potentially slow operation and should be used only when you need to make sure that some text not currently visible is highlighted, for instance before printing.

Parameters:

• start – start of the area to highlight.

• end – end of the area to highlight.

forward_iter_to_source_mark(category: str | None = None) → tuple[bool, TextIter]

Moves iter to the position of the next Mark of the given category.

Returns True if iter was moved. If category is NULL, the next source mark can be of any category.

Parameters:

category – category to search for, or None

get_context_classes_at_iter(iter: TextIter) → list[str]

Get all defined context classes at iter.

See the Buffer description for the list of default context classes.

Parameters:

iter – a TextIter.

get_highlight_matching_brackets() → bool

Determines whether bracket match highlighting is activated for the source buffer.

get_highlight_syntax() → bool

Determines whether syntax highlighting is activated in the source buffer.

get_implicit_trailing_newline() → bool

get_language() → Language | None

Returns the Language associated with the buffer, see set_language.

The returned object should not be unreferenced by the user.

get_loading() → bool

get_source_marks_at_iter(iter: TextIter, category: str | None = None) → list[Mark]

Returns the list of marks of the given category at iter.

If category is None it returns all marks at iter.

Parameters:

• iter – an iterator.

• category – category to search for, or None

get_source_marks_at_line(line: int, category: str | None = None) → list[Mark]

Returns the list of marks of the given category at line.

If category is None, all marks at line are returned.

Parameters:

• line – a line number.

• category – category to search for, or None

get_style_scheme() → StyleScheme | None

Returns the StyleScheme associated with the buffer, see set_style_scheme.

The returned object should not be unreferenced by the user.

iter_backward_to_context_class_toggle(context_class: str) → tuple[bool, TextIter]

Moves backward to the next toggle (on or off) of the context class.

If no matching context class toggles are found, returns False, otherwise True. Does not return toggles located at iter, only toggles after iter. Sets iter to the location of the toggle, or to the end of the buffer if no toggle is found.

See the Buffer description for the list of default context classes.

Parameters:

context_class – the context class.

iter_forward_to_context_class_toggle(context_class: str) → tuple[bool, TextIter]

Moves forward to the next toggle (on or off) of the context class.

If no matching context class toggles are found, returns False, otherwise True. Does not return toggles located at iter, only toggles after iter. Sets iter to the location of the toggle, or to the end of the buffer if no toggle is found.

See the Buffer description for the list of default context classes.

Parameters:

context_class – the context class.

iter_has_context_class(iter: TextIter, context_class: str) → bool

Check if the class context_class is set on iter.

See the Buffer description for the list of default context classes.

Parameters:

• iter – a TextIter.

• context_class – class to search for.

join_lines(start: TextIter, end: TextIter) → None

Joins the lines of text between the specified iterators.

Parameters:

• start – a TextIter.

• end – a TextIter.

remove_source_marks(start: TextIter, end: TextIter, category: str | None = None) → None

Remove all marks of category between start and end from the buffer.

If category is NULL, all marks in the range will be removed.

Parameters:

• start – a TextIter.

• end – a TextIter.

• category – category to search for, or None.

set_highlight_matching_brackets(highlight: bool) → None

Controls the bracket match highlighting function in the buffer.

If activated, when you position your cursor over a bracket character (a parenthesis, a square bracket, etc.) the matching opening or closing bracket character will be highlighted.

Parameters:

highlight – True if you want matching brackets highlighted.

set_highlight_syntax(highlight: bool) → None

Controls whether syntax is highlighted in the buffer.

If highlight is True, the text will be highlighted according to the syntax patterns specified in the Language set with set_language.

If highlight is False, syntax highlighting is disabled and all the TextTag objects that have been added by the syntax highlighting engine are removed from the buffer.

Parameters:

highlight – True to enable syntax highlighting, False to disable it.

set_implicit_trailing_newline(implicit_trailing_newline: bool) → None

Sets whether the buffer has an implicit trailing newline.

If an explicit trailing newline is present in a TextBuffer, TextView shows it as an empty line. This is generally not what the user expects.

If implicit_trailing_newline is True (the default value):

• when a FileLoader loads the content of a file into the buffer, the trailing newline (if present in the file) is not inserted into the buffer.

• when a FileSaver saves the content of the buffer into a file, a trailing newline is added to the file.

On the other hand, if implicit_trailing_newline is False, the file’s content is not modified when loaded into the buffer, and the buffer’s content is not modified when saved into a file.

Parameters:

implicit_trailing_newline – the new value.

set_language(language: Language | None = None) → None

Associates a Language with the buffer.

Note that a Language affects not only the syntax highlighting, but also the context classes. If you want to disable just the syntax highlighting, see set_highlight_syntax.

The buffer holds a reference to language.

Parameters:

language – a Language to set, or None.

set_style_scheme(scheme: StyleScheme | None = None) → None

Sets a StyleScheme to be used by the buffer and the view.

Note that a StyleScheme affects not only the syntax highlighting, but also other View features such as highlighting the current line, matching brackets, the line numbers, etc.

Instead of setting a None scheme, it is better to disable syntax highlighting with set_highlight_syntax, and setting the StyleScheme with the “classic” or “tango” ID, because those two style schemes follow more closely the GTK theme (for example for the background color).

The buffer holds a reference to scheme.

Parameters:

scheme – a StyleScheme or None.

sort_lines(start: TextIter, end: TextIter, flags: SortFlags, column: int) → None

Sort the lines of text between the specified iterators.

Parameters:

• start – a TextIter.

• end – a TextIter.

• flags – SortFlags specifying how the sort should behave

• column – sort considering the text starting at the given column

Properties

class Buffer

props.highlight_matching_brackets: bool

Whether to highlight matching brackets in the buffer.

props.highlight_syntax: bool

Whether to highlight syntax in the buffer.

props.implicit_trailing_newline: bool

Whether the buffer has an implicit trailing newline. See set_implicit_trailing_newline.

props.language: Language

props.loading: bool

The “loading” property denotes that a GtkSourceFileLoader is currently loading the buffer.

Applications may want to use this setting to avoid doing work while the buffer is loading such as spellchecking.

Added in version 5.10.

props.style_scheme: StyleScheme

Style scheme. It contains styles for syntax highlighting, optionally foreground, background, cursor color, current line color, and matching brackets style.

Signals

class Buffer.signals

bracket_matched(iter: TextIter | None, state: BracketMatchType) → None

iter is set to a valid iterator pointing to the matching bracket if state is FOUND. Otherwise iter is meaningless.

The signal is emitted only when the state changes, typically when the cursor moves.

A use-case for this signal is to show messages in a Statusbar.

Parameters:

• iter – if found, the location of the matching bracket.

• state – state of bracket matching.

cursor_moved() → None

The “cursor-moved” signal is emitted when then insertion mark has moved.

highlight_updated(start: TextIter, end: TextIter) → None

The ::highlight-updated signal is emitted when the syntax highlighting and context classes are updated in a certain region of the buffer.

Parameters:

• start – the start of the updated region

• end – the end of the updated region

source_mark_updated(mark: TextMark) → None

The ::source-mark-updated signal is emitted each time a mark is added to, moved or removed from the buffer.

Parameters:

mark – the Mark

Virtual Methods

class Buffer

do_bracket_matched(iter: TextIter, state: BracketMatchType) → None

Parameters:

• iter

• state

Fields

class Buffer

parent_instance