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 (74), GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class

new (table)

class

new_with_language (language)

backward_iter_to_source_mark (iter, category)

begin_not_undoable_action ()

can_redo ()

can_undo ()

change_case (case_type, start, end)

create_source_mark (name, category, where)

end_not_undoable_action ()

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_max_undo_levels ()

get_source_marks_at_iter (iter, category)

get_source_marks_at_line (line, category)

get_style_scheme ()

get_undo_manager ()

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)

redo ()

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_max_undo_levels (max_undo_levels)

set_style_scheme (scheme)

set_undo_manager (manager)

sort_lines (start, end, flags, column)

undo ()

Virtual Methods

Inherited:

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

do_bracket_matched (iter, state)

do_redo ()

do_undo ()

Properties

Inherited:

Gtk.TextBuffer (6)

Name

Type

Flags

Short Description

can-redo

bool

r

Whether Redo operation is possible

can-undo

bool

r

Whether Undo operation is possible

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

max-undo-levels

int

r/w

Number of undo levels for the buffer

style-scheme

GtkSource.StyleScheme

r/w

Style scheme

undo-manager

GtkSource.UndoManager

r/w/c

The buffer undo manager

Signals

Inherited:

Gtk.TextBuffer (13), 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.

highlight-updated

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

redo

The ::redo signal is emitted to redo the last undo operation.

source-mark-updated

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

undo

The ::undo signal is emitted to undo the last user action which modified the buffer.

Fields

Inherited:

Gtk.TextBuffer (13), 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

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 GtkSource.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 GtkSource.Mark of the given category. Returns True if iter was moved. If category is None, the previous source mark can be of any category.

New in version 2.2.

begin_not_undoable_action()

Marks the beginning of a not undoable action on the buffer, disabling the undo manager. Typically you would call this function before initially setting the contents of the buffer (e.g. when loading a file in a text editor).

You may nest GtkSource.Buffer.begin_not_undoable_action() / GtkSource.Buffer.end_not_undoable_action() blocks.

can_redo()
Returns:

True if a redo is possible.

Return type:

bool

Determines whether a source buffer can redo the last action (i.e. if the last operation was an undo).

can_undo()
Returns:

True if it’s possible to undo the last action.

Return type:

bool

Determines whether a source buffer can undo the last action.

change_case(case_type, start, end)
Parameters:

Changes the case of the text between the specified iterators.

New in version 3.12.

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 GtkSource.Mark, owned by the buffer.

Return type:

GtkSource.Mark

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

Like a Gtk.TextMark, a GtkSource.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..

New in version 2.2.

end_not_undoable_action()

Marks the end of a not undoable action on the buffer. When the last not undoable block is closed through the call to this function, the list of undo actions is cleared and the undo manager is re-enabled.

ensure_highlight(start, end)
Parameters:

Forces buffer to analyze and highlight the given area synchronously.

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 GtkSource.Mark of the given category. Returns True if iter was moved. If category is None, the next source mark can be of any category.

New in version 2.2.

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 GtkSource.Buffer description for the list of default context classes.

New in version 2.10.

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

New in version 3.14.

get_language()
Returns:

the GtkSource.Language associated with the buffer, or None.

Return type:

GtkSource.Language or None

Returns the GtkSource.Language associated with the buffer, see GtkSource.Buffer.set_language(). The returned object should not be unreferenced by the user.

get_max_undo_levels()
Returns:

the maximum number of possible undo levels or -1 if no limit is set.

Return type:

int

Determines the number of undo levels the buffer will track for buffer edits.

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.

New in version 2.2.

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.

New in version 2.2.

get_style_scheme()
Returns:

the GtkSource.StyleScheme associated with the buffer, or None.

Return type:

GtkSource.StyleScheme or None

Returns the GtkSource.StyleScheme associated with the buffer, see GtkSource.Buffer.set_style_scheme(). The returned object should not be unreferenced by the user.

get_undo_manager()
Returns:

the GtkSource.UndoManager associated with the buffer, or None.

Return type:

GtkSource.UndoManager or None

Returns the GtkSource.UndoManager associated with the buffer, see GtkSource.Buffer.set_undo_manager(). 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 GtkSource.Buffer description for the list of default context classes.

New in version 2.10.

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 GtkSource.Buffer description for the list of default context classes.

New in version 2.10.

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 GtkSource.Buffer description for the list of default context classes.

New in version 2.10.

join_lines(start, end)
Parameters:

Joins the lines of text between the specified iterators.

New in version 3.16.

redo()

Redoes the last undo operation. Use GtkSource.Buffer.can_redo() to check whether a call to this function will have any effect.

This function emits the GtkSource.Buffer ::redo signal.

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.

New in version 2.2.

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 GtkSource.Language set with GtkSource.Buffer.set_language().

If highlight is False, syntax highlighting is disabled and all the 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 Gtk.TextBuffer, 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 GtkSource.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 GtkSource.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.

New in version 3.14.

set_language(language)
Parameters:

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

Associates a GtkSource.Language with the buffer.

Note that a GtkSource.Language affects not only the syntax highlighting, but also the ‘context classes [context-classes]’. If you want to disable just the syntax highlighting, see GtkSource.Buffer.set_highlight_syntax().

The buffer holds a reference to language.

set_max_undo_levels(max_undo_levels)
Parameters:

max_undo_levels (int) – the desired maximum number of undo levels.

Sets the number of undo levels for user actions the buffer will track. If the number of user actions exceeds the limit set by this function, older actions will be discarded.

If max_undo_levels is -1, the undo/redo is unlimited.

If max_undo_levels is 0, the undo/redo is disabled.

set_style_scheme(scheme)
Parameters:

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

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

Note that a GtkSource.StyleScheme affects not only the syntax highlighting, but also other GtkSource.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 GtkSource.Buffer.set_highlight_syntax(), and setting the GtkSource.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.

set_undo_manager(manager)
Parameters:

manager (GtkSource.UndoManager or None) – A GtkSource.UndoManager or None.

Set the buffer undo manager. If manager is None the default undo manager will be set.

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

Sort the lines of text between the specified iterators.

New in version 3.18.

undo()

Undoes the last user action which modified the buffer. Use GtkSource.Buffer.can_undo() to check whether a call to this function will have any effect.

This function emits the GtkSource.Buffer ::undo signal.

do_bracket_matched(iter, state) virtual
Parameters:
do_redo() virtual

Redoes the last undo operation. Use GtkSource.Buffer.can_redo() to check whether a call to this function will have any effect.

This function emits the GtkSource.Buffer ::redo signal.

do_undo() virtual

Undoes the last user action which modified the buffer. Use GtkSource.Buffer.can_undo() to check whether a call to this function will have any effect.

This function emits the GtkSource.Buffer ::undo signal.

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 Gtk.Statusbar.

New in version 2.12.

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 [context-classes]’ are updated in a certain region of the buffer.

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

redo

Flags:

RUN_LAST

Parameters:

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

The ::redo signal is emitted to redo the last undo operation.

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.

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

undo

Flags:

RUN_LAST

Parameters:

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

The ::undo signal is emitted to undo the last user action which modified the buffer.

Property Details

GtkSource.Buffer.props.can_redo
Name:

can-redo

Type:

bool

Default Value:

False

Flags:

READABLE

Whether Redo operation is possible

GtkSource.Buffer.props.can_undo
Name:

can-undo

Type:

bool

Default Value:

False

Flags:

READABLE

Whether Undo operation is possible

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 GtkSource.Buffer.set_implicit_trailing_newline().

New in version 3.14.

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.max_undo_levels
Name:

max-undo-levels

Type:

int

Default Value:

-1

Flags:

READABLE, WRITABLE

Number of undo levels for the buffer. -1 means no limit. This property will only affect the default undo manager.

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.

GtkSource.Buffer.props.undo_manager
Name:

undo-manager

Type:

GtkSource.UndoManager

Default Value:

None

Flags:

READABLE, WRITABLE, CONSTRUCT

The buffer undo manager