:right-sidebar: True Buffer =================================================================== .. currentmodule:: gi.repository.GtkSource .. class:: Buffer(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.TextBuffer`, :class:`~gi.repository.GObject.Object` Subclass of :obj:`~gi.repository.Gtk.TextBuffer`\. A ``GtkSourceBuffer`` object is the model for :obj:`~gi.repository.GtkSource.View` widgets. It extends the :obj:`~gi.repository.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 :obj:`~gi.repository.GtkSource.Buffer.new` or :obj:`~gi.repository.GtkSource.Buffer.new_with_language`\. The second form is just a convenience function which allows you to initially set a :obj:`~gi.repository.GtkSource.Language`\. You can also directly create a :obj:`~gi.repository.GtkSource.View` and get its :obj:`~gi.repository.GtkSource.Buffer` with :obj:`~gi.repository.Gtk.TextView.get_buffer`\. The highlighting is enabled by default, but you can disable it with :obj:`~gi.repository.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 :obj:`~gi.repository.Buffer.iter_has_context_class` take a string parameter as the context class. ``GtkSourceBuffer`` provides an API to access the context classes: :obj:`~gi.repository.Buffer.iter_has_context_class`\, :obj:`~gi.repository.Buffer.get_context_classes_at_iter`\, :obj:`~gi.repository.Buffer.iter_forward_to_context_class_toggle` and :obj:`~gi.repository.Buffer.iter_backward_to_context_class_toggle`\. And the :obj:`~gi.repository.GtkSource.Buffer.signals.highlight_updated` signal permits to be notified when a context class region changes. Each context class has also an associated :obj:`~gi.repository.Gtk.TextTag` with the name ``gtksourceview:context-classes:``\. For example to retrieve the :obj:`~gi.repository.Gtk.TextTag` for the string context class, one can write: .. code-block:: c :dedent: 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 :obj:`~gi.repository.Gtk.TextTag` is less convenient than the ``GtkSourceBuffer`` API, because: - The tag doesn't always exist, you need to listen to the :obj:`~gi.repository.Gtk.TextTagTable.signals.tag_added` and :obj:`~gi.repository.Gtk.TextTagTable.signals.tag_removed` signals. - Instead of the :obj:`~gi.repository.GtkSource.Buffer.signals.highlight_updated` signal, you can listen to the :obj:`~gi.repository.Gtk.TextBuffer.signals.apply_tag` and :obj:`~gi.repository.Gtk.TextBuffer.signals.remove_tag` signals. A possible use-case for accessing a context class via the associated :obj:`~gi.repository.Gtk.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 ------------ .. rst-class:: interim-class .. class:: Buffer :no-index: .. classmethod:: new(table: ~gi.repository.Gtk.TextTagTable | None = None) -> ~gi.repository.GtkSource.Buffer Creates a new source buffer. :param table: a :obj:`~gi.repository.Gtk.TextTagTable`\, or :const:`None` to create a new one. .. classmethod:: new_with_language(language: ~gi.repository.GtkSource.Language) -> ~gi.repository.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 :obj:`~gi.repository.Buffer.set_language`\. :param language: a :obj:`~gi.repository.GtkSource.Language`\. Methods ------- .. rst-class:: interim-class .. class:: Buffer :no-index: .. method:: backward_iter_to_source_mark(iter: ~gi.repository.Gtk.TextIter, category: str | None = None) -> ~typing.Tuple[bool, ~gi.repository.Gtk.TextIter] Moves ``iter`` to the position of the previous :obj:`~gi.repository.GtkSource.Mark` of the given category. Returns :const:`True` if ``iter`` was moved. If ``category`` is NULL, the previous source mark can be of any category. :param iter: an iterator. :param category: category to search for, or :const:`None` .. method:: change_case(case_type: ~gi.repository.GtkSource.ChangeCaseType, start: ~gi.repository.Gtk.TextIter, end: ~gi.repository.Gtk.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. :param case_type: how to change the case. :param start: a :obj:`~gi.repository.Gtk.TextIter`\. :param end: a :obj:`~gi.repository.Gtk.TextIter`\. .. method:: create_source_mark(name: str | None, category: str, where: ~gi.repository.Gtk.TextIter) -> ~gi.repository.GtkSource.Mark Creates a source mark in the ``buffer`` of category ``category``\. A source mark is a :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.TextMark`\, a :obj:`~gi.repository.GtkSource.Mark` can be anonymous if the passed ``name`` is :const:`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.. :param name: the name of the mark, or :const:`None`. :param category: a string defining the mark category. :param where: location to place the mark. .. method:: do_bracket_matched(self, iter: ~gi.repository.Gtk.TextIter, state: ~gi.repository.GtkSource.BracketMatchType) -> None :param iter: :param state: .. method:: ensure_highlight(start: ~gi.repository.Gtk.TextIter, end: ~gi.repository.Gtk.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. :param start: start of the area to highlight. :param end: end of the area to highlight. .. method:: forward_iter_to_source_mark(iter: ~gi.repository.Gtk.TextIter, category: str | None = None) -> ~typing.Tuple[bool, ~gi.repository.Gtk.TextIter] Moves ``iter`` to the position of the next :obj:`~gi.repository.GtkSource.Mark` of the given ``category``\. Returns :const:`True` if ``iter`` was moved. If ``category`` is NULL, the next source mark can be of any category. :param iter: an iterator. :param category: category to search for, or :const:`None` .. method:: get_context_classes_at_iter(iter: ~gi.repository.Gtk.TextIter) -> list[str] Get all defined context classes at ``iter``\. See the :obj:`~gi.repository.GtkSource.Buffer` description for the list of default context classes. :param iter: a :obj:`~gi.repository.Gtk.TextIter`\. .. method:: get_highlight_matching_brackets() -> bool Determines whether bracket match highlighting is activated for the source buffer. .. method:: get_highlight_syntax() -> bool Determines whether syntax highlighting is activated in the source buffer. .. method:: get_implicit_trailing_newline() -> bool .. method:: get_language() -> ~gi.repository.GtkSource.Language | None Returns the :obj:`~gi.repository.GtkSource.Language` associated with the buffer, see :obj:`~gi.repository.Buffer.set_language`\. The returned object should not be unreferenced by the user. .. method:: get_loading() -> bool .. method:: get_source_marks_at_iter(iter: ~gi.repository.Gtk.TextIter, category: str | None = None) -> list[~gi.repository.GtkSource.Mark] Returns the list of marks of the given category at ``iter``\. If ``category`` is :const:`None` it returns all marks at ``iter``\. :param iter: an iterator. :param category: category to search for, or :const:`None` .. method:: get_source_marks_at_line(line: int, category: str | None = None) -> list[~gi.repository.GtkSource.Mark] Returns the list of marks of the given category at ``line``\. If ``category`` is :const:`None`, all marks at ``line`` are returned. :param line: a line number. :param category: category to search for, or :const:`None` .. method:: get_style_scheme() -> ~gi.repository.GtkSource.StyleScheme | None Returns the :obj:`~gi.repository.GtkSource.StyleScheme` associated with the buffer, see :obj:`~gi.repository.Buffer.set_style_scheme`\. The returned object should not be unreferenced by the user. .. method:: iter_backward_to_context_class_toggle(iter: ~gi.repository.Gtk.TextIter, context_class: str) -> ~typing.Tuple[bool, ~gi.repository.Gtk.TextIter] Moves backward to the next toggle (on or off) of the context class. If no matching context class toggles are found, returns :const:`False`, otherwise :const:`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 :obj:`~gi.repository.GtkSource.Buffer` description for the list of default context classes. :param iter: a :obj:`~gi.repository.Gtk.TextIter`\. :param context_class: the context class. .. method:: iter_forward_to_context_class_toggle(iter: ~gi.repository.Gtk.TextIter, context_class: str) -> ~typing.Tuple[bool, ~gi.repository.Gtk.TextIter] Moves forward to the next toggle (on or off) of the context class. If no matching context class toggles are found, returns :const:`False`, otherwise :const:`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 :obj:`~gi.repository.GtkSource.Buffer` description for the list of default context classes. :param iter: a :obj:`~gi.repository.Gtk.TextIter`\. :param context_class: the context class. .. method:: iter_has_context_class(iter: ~gi.repository.Gtk.TextIter, context_class: str) -> bool Check if the class ``context_class`` is set on ``iter``\. See the :obj:`~gi.repository.GtkSource.Buffer` description for the list of default context classes. :param iter: a :obj:`~gi.repository.Gtk.TextIter`\. :param context_class: class to search for. .. method:: join_lines(start: ~gi.repository.Gtk.TextIter, end: ~gi.repository.Gtk.TextIter) -> None Joins the lines of text between the specified iterators. :param start: a :obj:`~gi.repository.Gtk.TextIter`\. :param end: a :obj:`~gi.repository.Gtk.TextIter`\. .. method:: remove_source_marks(start: ~gi.repository.Gtk.TextIter, end: ~gi.repository.Gtk.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. :param start: a :obj:`~gi.repository.Gtk.TextIter`\. :param end: a :obj:`~gi.repository.Gtk.TextIter`\. :param category: category to search for, or :const:`None`. .. method:: 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. :param highlight: :const:`True` if you want matching brackets highlighted. .. method:: set_highlight_syntax(highlight: bool) -> None Controls whether syntax is highlighted in the buffer. If ``highlight`` is :const:`True`, the text will be highlighted according to the syntax patterns specified in the :obj:`~gi.repository.GtkSource.Language` set with :obj:`~gi.repository.Buffer.set_language`\. If ``highlight`` is :const:`False`, syntax highlighting is disabled and all the :obj:`~gi.repository.Gtk.TextTag` objects that have been added by the syntax highlighting engine are removed from the buffer. :param highlight: :const:`True` to enable syntax highlighting, :const:`False` to disable it. .. method:: 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 :obj:`~gi.repository.Gtk.TextBuffer`\, :obj:`~gi.repository.Gtk.TextView` shows it as an empty line. This is generally not what the user expects. If ``implicit_trailing_newline`` is :const:`True` (the default value): - when a :obj:`~gi.repository.GtkSource.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 :obj:`~gi.repository.GtkSource.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 :const:`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. :param implicit_trailing_newline: the new value. .. method:: set_language(language: ~gi.repository.GtkSource.Language | None = None) -> None Associates a :obj:`~gi.repository.GtkSource.Language` with the buffer. Note that a :obj:`~gi.repository.GtkSource.Language` affects not only the syntax highlighting, but also the `context classes <./class.Buffer.html#context-classes>`__\. If you want to disable just the syntax highlighting, see :obj:`~gi.repository.Buffer.set_highlight_syntax`\. The buffer holds a reference to ``language``\. :param language: a :obj:`~gi.repository.GtkSource.Language` to set, or :const:`None`. .. method:: set_style_scheme(scheme: ~gi.repository.GtkSource.StyleScheme | None = None) -> None Sets a :obj:`~gi.repository.GtkSource.StyleScheme` to be used by the buffer and the view. Note that a :obj:`~gi.repository.GtkSource.StyleScheme` affects not only the syntax highlighting, but also other :obj:`~gi.repository.GtkSource.View` features such as highlighting the current line, matching brackets, the line numbers, etc. Instead of setting a :const:`None` ``scheme``\, it is better to disable syntax highlighting with :obj:`~gi.repository.Buffer.set_highlight_syntax`\, and setting the :obj:`~gi.repository.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``\. :param scheme: a :obj:`~gi.repository.GtkSource.StyleScheme` or :const:`None`. .. method:: sort_lines(start: ~gi.repository.Gtk.TextIter, end: ~gi.repository.Gtk.TextIter, flags: ~gi.repository.GtkSource.SortFlags, column: int) -> None Sort the lines of text between the specified iterators. :param start: a :obj:`~gi.repository.Gtk.TextIter`\. :param end: a :obj:`~gi.repository.Gtk.TextIter`\. :param flags: :obj:`~gi.repository.GtkSource.SortFlags` specifying how the sort should behave :param column: sort considering the text starting at the given column Properties ---------- .. rst-class:: interim-class .. class:: Buffer :no-index: .. attribute:: props.highlight_matching_brackets :type: bool The type of the None singleton. .. attribute:: props.highlight_syntax :type: bool The type of the None singleton. .. attribute:: props.implicit_trailing_newline :type: bool The type of the None singleton. .. attribute:: props.language :type: ~gi.repository.GtkSource.Language The type of the None singleton. .. attribute:: props.loading :type: bool The type of the None singleton. .. versionadded:: 5.10 .. attribute:: props.style_scheme :type: ~gi.repository.GtkSource.StyleScheme The type of the None singleton. Signals ------- .. rst-class:: interim-class .. class:: Buffer.signals :no-index: .. method:: bracket_matched(iter: ~gi.repository.Gtk.TextIter | None, state: ~gi.repository.GtkSource.BracketMatchType) -> None The type of the None singleton. :param iter: if found, the location of the matching bracket. :param state: state of bracket matching. .. method:: cursor_moved() -> None The type of the None singleton. .. method:: highlight_updated(start: ~gi.repository.Gtk.TextIter, end: ~gi.repository.Gtk.TextIter) -> None The type of the None singleton. :param start: the start of the updated region :param end: the end of the updated region .. method:: source_mark_updated(mark: ~gi.repository.Gtk.TextMark) -> None The type of the None singleton. :param mark: the :obj:`~gi.repository.GtkSource.Mark` Virtual Methods --------------- .. rst-class:: interim-class .. class:: Buffer :no-index: .. method:: do_bracket_matched(iter: ~gi.repository.Gtk.TextIter, state: ~gi.repository.GtkSource.BracketMatchType) -> None The type of the None singleton. :param iter: :param state: Fields ------ .. rst-class:: interim-class .. class:: Buffer :no-index: .. attribute:: parent_instance