GtkSource.Buffer

g GObject.Object GObject.Object Gtk.TextBuffer Gtk.TextBuffer GObject.Object->Gtk.TextBuffer GtkSource.Buffer GtkSource.Buffer Gtk.TextBuffer->GtkSource.Buffer

Subclasses:

None

Methods

Inherited:

Gtk.TextBuffer (71), GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class

new (table)

class

new_with_language (language)

backward_iter_to_source_mark (iter, category)

change_case (case_type, start, end)

create_source_mark (name, category, where)

ensure_highlight (start, end)

forward_iter_to_source_mark (iter, category)

get_context_classes_at_iter (iter)

get_highlight_matching_brackets ()

get_highlight_syntax ()

get_implicit_trailing_newline ()

get_language ()

get_loading ()

get_source_marks_at_iter (iter, category)

get_source_marks_at_line (line, category)

get_style_scheme ()

iter_backward_to_context_class_toggle (iter, context_class)

iter_forward_to_context_class_toggle (iter, context_class)

iter_has_context_class (iter, context_class)

join_lines (start, end)

remove_source_marks (start, end, category)

set_highlight_matching_brackets (highlight)

set_highlight_syntax (highlight)

set_implicit_trailing_newline (implicit_trailing_newline)

set_language (language)

set_style_scheme (scheme)

sort_lines (start, end, flags, column)

Virtual Methods

Inherited:

Gtk.TextBuffer (15), GObject.Object (7)

do_bracket_matched (iter, state)

Properties

Inherited:

Gtk.TextBuffer (7)

Name

Type

Flags

Short Description

highlight-matching-brackets

bool

r/w

Whether to highlight matching brackets

highlight-syntax

bool

r/w

Whether to highlight syntax in the buffer

implicit-trailing-newline

bool

r/w/c

language

GtkSource.Language

r/w

Language object to get highlighting patterns from

loading

bool

r

If a GtkSource.FileLoader is loading the buffer

style-scheme

GtkSource.StyleScheme

r/w

Style scheme

Signals

Inherited:

Gtk.TextBuffer (15), GObject.Object (1)

Name

Short Description

bracket-matched

iter is set to a valid iterator pointing to the matching bracket if state is GtkSource.BracketMatchType.FOUND.

cursor-moved

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

highlight-updated

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

source-mark-updated

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

Fields

Inherited:

Gtk.TextBuffer (15), GObject.Object (1)

Name

Type

Access

Description

parent_instance

Gtk.TextBuffer

r

Class Details

class GtkSource.Buffer(**kwargs)
Bases:

Gtk.TextBuffer

Abstract:

No

Structure:

GtkSource.BufferClass

Subclass of [class`Gtk`.TextBuffer].

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

To create a GtkSourceBuffer use [ctor`GtkSource`.Buffer.new] or [ctor`GtkSource`.Buffer.new_with_language]. The second form is just a convenience function which allows you to initially set a [class`Language`]. You can also directly create a [class`View`] and get its [class`Buffer`] with [method`Gtk`.TextView.get_buffer].

The highlighting is enabled by default, but you can disable it with [method`Buffer`.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 [method`Buffer`.iter_has_context_class] take a string parameter as the context class.

GtkSourceBuffer provides an API to access the context classes: [method`Buffer`.iter_has_context_class], [method`Buffer`.get_context_classes_at_iter], [method`Buffer`.iter_forward_to_context_class_toggle] and [method`Buffer`.iter_backward_to_context_class_toggle].

And the [signal`GtkSource`.Buffer::highlight-updated] signal permits to be notified when a context class region changes.

Each context class has also an associated [class`Gtk`.TextTag] with the name gtksourceview:context-classes:<name>. For example to retrieve the [class`Gtk`.TextTag] for the string context class, one can write: ```c Gtk.TextTagTable *tag_table; Gtk.TextTag *tag;

tag_table = Gtk.TextBuffer.get_tag_table (buffer); tag = Gtk.TextTagTable.lookup (tag_table, “gtksourceview:context-classes:py:data::string<GtkSource.Buffer.props.string>"); ```

The tag must be used for read-only purposes.

Accessing a context class via the associated [class`Gtk`.TextTag] is less convenient than the GtkSourceBuffer API, because:

  • The tag doesn’t always exist, you need to listen to the [signal`Gtk`.TextTagTable::tag-added] and [signal`Gtk`.TextTagTable::tag-removed] signals.

  • Instead of the [signal`GtkSource`.Buffer::highlight-updated] signal, you can listen to the [signal`Gtk`.TextBuffer::apply-tag] and [signal`Gtk`.TextBuffer::remove-tag] signals.

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

classmethod new(table)
Parameters:

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

Returns:

a new source buffer.

Return type:

GtkSource.Buffer

Creates a new source buffer.

classmethod new_with_language(language)
Parameters:

language (GtkSource.Language) – a GtkSource.Language.

Returns:

a new source buffer which will highlight text according to the highlighting patterns in language.

Return type:

GtkSource.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 [method`Buffer`.set_language].

backward_iter_to_source_mark(iter, category)
Parameters:
Returns:

whether iter was moved.

iter:

an iterator.

Return type:

(bool, iter: Gtk.TextIter)

Moves iter to the position of the previous [class`Mark`] of the given category.

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

change_case(case_type, start, end)
Parameters:

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.

create_source_mark(name, category, where)
Parameters:

  • name (str or None) – the name of the mark, or None.

  • category (str) – a string defining the mark category.

  • where (Gtk.TextIter) – location to place the mark.

Returns:

a new [class`Mark`], owned by the buffer.

Return type:

GtkSource.Mark

Creates a source mark in the buffer of category category.

A source mark is a [class`Gtk`.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 [class`Gtk`.TextMark], a [class`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..

ensure_highlight(start, end)
Parameters:

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.

forward_iter_to_source_mark(iter, category)
Parameters:
Returns:

whether iter was moved.

iter:

an iterator.

Return type:

(bool, iter: Gtk.TextIter)

Moves iter to the position of the next [class`Mark`] of the given category.

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

get_context_classes_at_iter(iter)
Parameters:

iter (Gtk.TextIter) – a Gtk.TextIter.

Returns:

a new None terminated array of context class names. Use GLib.strfreev() to free the array if it is no longer needed.

Return type:

[str]

Get all defined context classes at iter.

See the [class`Buffer`] description for the list of default context classes.

get_highlight_matching_brackets()
Returns:

True if the source buffer will highlight matching brackets.

Return type:

bool

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

get_highlight_syntax()
Returns:

True if syntax highlighting is enabled, False otherwise.

Return type:

bool

Determines whether syntax highlighting is activated in the source buffer.

get_implicit_trailing_newline()
Returns:

whether the self has an implicit trailing newline.

Return type:

bool

get_language()
Returns:

the [class`Language`] associated with the buffer, or None.

Return type:

GtkSource.Language or None

Returns the [class`Language`] associated with the buffer, see [method`Buffer`.set_language].

The returned object should not be unreferenced by the user.

get_loading()
Return type:

bool

get_source_marks_at_iter(iter, category)
Parameters:
Returns:

a newly allocated GLib.SList.

Return type:

[GtkSource.Mark]

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

If category is None it returns all marks at iter.

get_source_marks_at_line(line, category)
Parameters:

  • line (int) – a line number.

  • category (str or None) – category to search for, or None

Returns:

a newly allocated GLib.SList.

Return type:

[GtkSource.Mark]

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

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

get_style_scheme()
Returns:

the [class`StyleScheme`] associated with the buffer, or None.

Return type:

GtkSource.StyleScheme or None

Returns the [class`StyleScheme`] associated with the buffer, see [method`Buffer`.set_style_scheme].

The returned object should not be unreferenced by the user.

iter_backward_to_context_class_toggle(iter, context_class)
Parameters:
Returns:

whether we found a context class toggle before iter

iter:

a Gtk.TextIter.

Return type:

(bool, iter: Gtk.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 [class`Buffer`] description for the list of default context classes.

iter_forward_to_context_class_toggle(iter, context_class)
Parameters:
Returns:

whether we found a context class toggle after iter

iter:

a Gtk.TextIter.

Return type:

(bool, iter: Gtk.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 [class`Buffer`] description for the list of default context classes.

iter_has_context_class(iter, context_class)
Parameters:
Returns:

whether iter has the context class.

Return type:

bool

Check if the class context_class is set on iter.

See the [class`Buffer`] description for the list of default context classes.

join_lines(start, end)
Parameters:

Joins the lines of text between the specified iterators.

remove_source_marks(start, end, category)
Parameters:

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

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

set_highlight_matching_brackets(highlight)
Parameters:

highlight (bool) – True if you want matching brackets highlighted.

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.

set_highlight_syntax(highlight)
Parameters:

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

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 [class`Language`] set with [method`Buffer`.set_language].

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

set_implicit_trailing_newline(implicit_trailing_newline)
Parameters:

implicit_trailing_newline (bool) – the new value.

Sets whether the self has an implicit trailing newline.

If an explicit trailing newline is present in a [class`Gtk`.TextBuffer], [class`Gtk`.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 [class`FileLoader`] loads the content of a file into the self, the trailing newline (if present in the file) is not inserted into the self.

  • when a [class`FileSaver`] saves the content of the self 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 self, and the self's content is not modified when saved into a file.

set_language(language)
Parameters:

language (GtkSource.Language or None) – a GtkSource.Language to set, or None.

Associates a [class`Language`] with the buffer.

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

The buffer holds a reference to language.

set_style_scheme(scheme)
Parameters:

scheme (GtkSource.StyleScheme or None) – a GtkSource.StyleScheme or None.

Sets a [class`StyleScheme`] to be used by the buffer and the view.

Note that a [class`StyleScheme`] affects not only the syntax highlighting, but also other [class`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 [method`Buffer`.set_highlight_syntax], and setting the [class`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.

sort_lines(start, end, flags, column)
Parameters:

Sort the lines of text between the specified iterators.

do_bracket_matched(iter, state) virtual
Parameters:

Signal Details

GtkSource.Buffer.signals.bracket_matched(buffer, iter, state)
Signal Name:

bracket-matched

Flags:

RUN_LAST

Parameters:

iter is set to a valid iterator pointing to the matching bracket if state is GtkSource.BracketMatchType.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 [class`Gtk`.Statusbar].

GtkSource.Buffer.signals.cursor_moved(buffer)
Signal Name:

cursor-moved

Flags:

RUN_LAST

Parameters:

buffer (GtkSource.Buffer) – The object which received the signal

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

GtkSource.Buffer.signals.highlight_updated(buffer, start, end)
Signal Name:

highlight-updated

Flags:

RUN_LAST

Parameters:

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

GtkSource.Buffer.signals.source_mark_updated(buffer, mark)
Signal Name:

source-mark-updated

Flags:

RUN_LAST

Parameters:

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

Property Details

GtkSource.Buffer.props.highlight_matching_brackets
Name:

highlight-matching-brackets

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE

Whether to highlight matching brackets in the buffer.

GtkSource.Buffer.props.highlight_syntax
Name:

highlight-syntax

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE

Whether to highlight syntax in the buffer.

GtkSource.Buffer.props.implicit_trailing_newline
Name:

implicit-trailing-newline

Type:

bool

Default Value:

True

Flags:

READABLE, WRITABLE, CONSTRUCT

Whether the buffer has an implicit trailing newline. See [method`Buffer`.set_implicit_trailing_newline].

GtkSource.Buffer.props.language
Name:

language

Type:

GtkSource.Language

Default Value:

None

Flags:

READABLE, WRITABLE

Language object to get highlighting patterns from

GtkSource.Buffer.props.loading
Name:

loading

Type:

bool

Default Value:

False

Flags:

READABLE

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.

New in version 5.10.

GtkSource.Buffer.props.style_scheme
Name:

style-scheme

Type:

GtkSource.StyleScheme

Default Value:

None

Flags:

READABLE, WRITABLE

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