:right-sidebar: True View =================================================================== .. currentmodule:: gi.repository.GtkSource .. class:: View(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.TextView`, :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.GtkSource.Map` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.AccessibleText`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`, :class:`~gi.repository.Gtk.Scrollable` Subclass of :obj:`~gi.repository.Gtk.TextView`\. ``GtkSourceView`` is the main class of the GtkSourceView library. Use a :obj:`~gi.repository.GtkSource.Buffer` to display text with a ``GtkSourceView``\. This class provides: - Show the line numbers; - Show a right margin; - Highlight the current line; - Indentation settings; - Configuration for the Home and End keyboard keys; - Configure and show line marks; - And a few other things. An easy way to test all these features is to use the test-widget mini-program provided in the GtkSourceView repository, in the tests/ directory. GtkSourceView as GtkBuildable -------------------------------------------------------------------------------- The GtkSourceView implementation of the :obj:`~gi.repository.Gtk.Buildable` interface exposes the :obj:`~gi.repository.GtkSource.View.props.completion` object with the internal-child "completion". An example of a UI definition fragment with GtkSourceView: .. code-block:: xml :dedent: 4 True False Changing the Font -------------------------------------------------------------------------------- Gtk CSS provides the best way to change the font for a ``GtkSourceView`` in a manner that allows for components like :obj:`~gi.repository.GtkSource.Map` to scale the desired font. .. code-block:: c :dedent: GtkCssProvider *provider = gtk_css_provider_new (); gtk_css_provider_load_from_string (provider, "textview { font-family: Monospace; font-size: 8pt; }"); gtk_style_context_add_provider (gtk_widget_get_style_context (view), GTK_STYLE_PROVIDER (provider), GTK_STYLE_PROVIDER_PRIORITY_APPLICATION); g_object_unref (provider); .. code-block:: python :dedent: provider = Gtk.CssProvider() provider.load_from_string("textview { font-family: Monospace; font-size: 8pt; }") style_context = view.get_style_context() style_context.add_provider(provider, Gtk.STYLE_PROVIDER_PRIORITY_APPLICATION) If you need to adjust the font or size of font within a portion of the document only, you should use a :obj:`~gi.repository.Gtk.TextTag` with the :obj:`~gi.repository.Gtk.TextTag.props.family` or :obj:`~gi.repository.Gtk.TextTag.props.scale` set so that the font size may be scaled relative to the default font set in CSS. Constructors ------------ .. rst-class:: interim-class .. class:: View :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new ``GtkSourceView``\. By default, an empty :obj:`~gi.repository.GtkSource.Buffer` will be lazily created and can be retrieved with :obj:`~gi.repository.Gtk.TextView.get_buffer`\. If you want to specify your own buffer, either override the :obj:`~gi.repository.Gtk.TextView.create_buffer` factory method, or use :obj:`~gi.repository.View.new_with_buffer`\. .. classmethod:: new_with_buffer(buffer: ~gi.repository.GtkSource.Buffer) -> ~gi.repository.Gtk.Widget Creates a new :obj:`~gi.repository.GtkSource.View` widget displaying the buffer ``buffer``\. One buffer can be shared among many widgets. :param buffer: a :obj:`~gi.repository.GtkSource.Buffer`\. Methods ------- .. rst-class:: interim-class .. class:: View :no-index: .. method:: do_line_mark_activated(self, iter: ~gi.repository.Gtk.TextIter, button: int, state: ~gi.repository.Gdk.ModifierType, n_presses: int) -> None :param iter: :param button: :param state: :param n_presses: .. method:: do_move_lines(self, down: bool) -> None :param down: .. method:: do_move_words(self, step: int) -> None :param step: .. method:: do_push_snippet(self, snippet: ~gi.repository.GtkSource.Snippet, location: ~gi.repository.Gtk.TextIter | None = None) -> None :param snippet: :param location: .. method:: do_show_completion(self) -> None .. method:: get_annotations() -> ~gi.repository.GtkSource.Annotations Gets the :obj:`~gi.repository.GtkSource.Annotations` associated with ``view``\. The returned object is guaranteed to be the same for the lifetime of ``view``\. Each :obj:`~gi.repository.GtkSource.View` object has a different :obj:`~gi.repository.GtkSource.Annotations`\. .. versionadded:: 5.18 .. method:: get_auto_indent() -> bool Returns whether auto-indentation of text is enabled. .. method:: get_background_pattern() -> ~gi.repository.GtkSource.BackgroundPatternType Returns the :obj:`~gi.repository.GtkSource.BackgroundPatternType` specifying if and how the background pattern should be displayed for this ``view``\. .. method:: get_completion() -> ~gi.repository.GtkSource.Completion Gets the :obj:`~gi.repository.GtkSource.Completion` associated with ``view``\. The returned object is guaranteed to be the same for the lifetime of ``view``\. Each ``GtkSourceView`` object has a different :obj:`~gi.repository.GtkSource.Completion`\. .. method:: get_enable_snippets() -> bool Gets the :obj:`~gi.repository.GtkSource.View.props.enable_snippets` property. If :const:`True`, matching snippets found in the :obj:`~gi.repository.GtkSource.SnippetManager` may be expanded when the user presses Tab after a word in the :obj:`~gi.repository.GtkSource.View`\. .. method:: get_gutter(window_type: ~gi.repository.Gtk.TextWindowType) -> ~gi.repository.GtkSource.Gutter Returns the :obj:`~gi.repository.GtkSource.Gutter` object associated with ``window_type`` for ``view``\. Only %GTK_TEXT_WINDOW_LEFT and %GTK_TEXT_WINDOW_RIGHT are supported, respectively corresponding to the left and right gutter. The line numbers and mark category icons are rendered in the left gutter. :param window_type: the gutter window type. .. method:: get_highlight_current_line() -> bool Returns whether the current line is highlighted. .. method:: get_hover() -> ~gi.repository.GtkSource.Hover Gets the :obj:`~gi.repository.GtkSource.Hover` associated with ``view``\. The returned object is guaranteed to be the same for the lifetime of ``view``\. Each :obj:`~gi.repository.GtkSource.View` object has a different :obj:`~gi.repository.GtkSource.Hover`\. .. method:: get_indent_on_tab() -> bool Returns whether when the tab key is pressed the current selection should get indented instead of replaced with the ``\t`` character. .. method:: get_indent_width() -> int Returns the number of spaces to use for each step of indent. See :obj:`~gi.repository.View.set_indent_width` for details. .. method:: get_indenter() -> ~gi.repository.GtkSource.Indenter | None Gets the :obj:`~gi.repository.GtkSource.View.props.indenter` property. .. method:: get_insert_spaces_instead_of_tabs() -> bool Returns whether when inserting a tabulator character it should be replaced by a group of space characters. .. method:: get_mark_attributes(category: str, priority: int) -> ~gi.repository.GtkSource.MarkAttributes Gets attributes and priority for the ``category``\. :param category: the category. :param priority: place where priority of the category will be stored. .. method:: get_right_margin_position() -> int Gets the position of the right margin in the given ``view``\. .. method:: get_show_line_marks() -> bool Returns whether line marks are displayed beside the text. .. method:: get_show_line_numbers() -> bool Returns whether line numbers are displayed beside the text. .. method:: get_show_right_margin() -> bool Returns whether a right margin is displayed. .. method:: get_smart_backspace() -> bool Returns :const:`True` if pressing the Backspace key will try to delete spaces up to the previous tab stop. .. method:: get_smart_home_end() -> ~gi.repository.GtkSource.SmartHomeEndType Returns a :obj:`~gi.repository.GtkSource.SmartHomeEndType` end value specifying how the cursor will move when HOME and END keys are pressed. .. method:: get_space_drawer() -> ~gi.repository.GtkSource.SpaceDrawer Gets the :obj:`~gi.repository.GtkSource.SpaceDrawer` associated with ``view``\. The returned object is guaranteed to be the same for the lifetime of ``view``\. Each :obj:`~gi.repository.GtkSource.View` object has a different :obj:`~gi.repository.GtkSource.SpaceDrawer`\. .. method:: get_tab_width() -> int Returns the width of tabulation in characters. .. method:: get_visual_column(iter: ~gi.repository.Gtk.TextIter) -> int Determines the visual column at ``iter`` taking into consideration the :obj:`~gi.repository.GtkSource.View.props.tab_width` of ``view``\. :param iter: a position in ``view``\. .. method:: indent_lines(start: ~gi.repository.Gtk.TextIter, end: ~gi.repository.Gtk.TextIter) -> None Inserts one indentation level at the beginning of the specified lines. The empty lines are not indented. :param start: :obj:`~gi.repository.Gtk.TextIter` of the first line to indent :param end: :obj:`~gi.repository.Gtk.TextIter` of the last line to indent .. method:: push_snippet(snippet: ~gi.repository.GtkSource.Snippet, location: ~gi.repository.Gtk.TextIter | None = None) -> None Inserts a new snippet at ``location`` If another snippet was already active, it will be paused and the new snippet will become active. Once the focus positions of ``snippet`` have been exhausted, editing will return to the previous snippet. :param snippet: a :obj:`~gi.repository.GtkSource.Snippet` :param location: a :obj:`~gi.repository.Gtk.TextIter` or :const:`None` for the cursor position .. method:: set_auto_indent(enable: bool) -> None If :const:`True` auto-indentation of text is enabled. When Enter is pressed to create a new line, the auto-indentation inserts the same indentation as the previous line. This is **not** a "smart indentation" where an indentation level is added or removed depending on the context. :param enable: whether to enable auto indentation. .. method:: set_background_pattern(background_pattern: ~gi.repository.GtkSource.BackgroundPatternType) -> None Set if and how the background pattern should be displayed. :param background_pattern: the :obj:`~gi.repository.GtkSource.BackgroundPatternType`\. .. method:: set_enable_snippets(enable_snippets: bool) -> None Sets the :obj:`~gi.repository.GtkSource.View.props.enable_snippets` property. If ``enable_snippets`` is :const:`True`, matching snippets found in the :obj:`~gi.repository.GtkSource.SnippetManager` may be expanded when the user presses Tab after a word in the :obj:`~gi.repository.GtkSource.View`\. :param enable_snippets: if snippets should be enabled .. method:: set_highlight_current_line(highlight: bool) -> None If ``highlight`` is :const:`True` the current line will be highlighted. :param highlight: whether to highlight the current line. .. method:: set_indent_on_tab(enable: bool) -> None If :const:`True`, when the tab key is pressed when several lines are selected, the selected lines are indented of one level instead of being replaced with a ``\t`` character. Shift+Tab unindents the selection. If the first or last line is not selected completely, it is also indented or unindented. When the selection doesn't span several lines, the tab key always replaces the selection with a normal ``\t`` character. :param enable: whether to indent a block when tab is pressed. .. method:: set_indent_width(width: int) -> None Sets the number of spaces to use for each step of indent when the tab key is pressed. If ``width`` is -1, the value of the :obj:`~gi.repository.GtkSource.View.props.tab_width` property will be used. The :obj:`~gi.repository.GtkSource.View.props.indent_width` interacts with the :obj:`~gi.repository.GtkSource.View.props.insert_spaces_instead_of_tabs` property and :obj:`~gi.repository.GtkSource.View.props.tab_width`\. An example will be clearer: If the :obj:`~gi.repository.GtkSource.View.props.indent_width` is 4 and :obj:`~gi.repository.GtkSource.View.props.tab_width` is 8 and :obj:`~gi.repository.GtkSource.View.props.insert_spaces_instead_of_tabs` is :const:`False`, then pressing the tab key at the beginning of a line will insert 4 spaces. So far so good. Pressing the tab key a second time will remove the 4 spaces and insert a ``\t`` character instead (since :obj:`~gi.repository.GtkSource.View.props.tab_width` is 8). On the other hand, if :obj:`~gi.repository.GtkSource.View.props.insert_spaces_instead_of_tabs` is :const:`True`, the second tab key pressed will insert 4 more spaces for a total of 8 spaces in the :obj:`~gi.repository.Gtk.TextBuffer`\. The test-widget program (available in the GtkSourceView repository) may be useful to better understand the indentation settings (enable the space drawing!). :param width: indent width in characters. .. method:: set_indenter(indenter: ~gi.repository.GtkSource.Indenter | None = None) -> None Sets the indenter for ``view`` to ``indenter``\. Note that the indenter will not be used unless :obj:`~gi.repository.GtkSource.View`\:auto-indent has been set to :const:`True`. :param indenter: a :obj:`~gi.repository.GtkSource.Indenter` or :const:`None` .. method:: set_insert_spaces_instead_of_tabs(enable: bool) -> None If :const:`True` a tab key pressed is replaced by a group of space characters. Of course it is still possible to insert a real ``\t`` programmatically with the :obj:`~gi.repository.Gtk.TextBuffer` API. :param enable: whether to insert spaces instead of tabs. .. method:: set_mark_attributes(category: str, attributes: ~gi.repository.GtkSource.MarkAttributes, priority: int) -> None Sets attributes and priority for the ``category``\. :param category: the category. :param attributes: mark attributes. :param priority: priority of the category. .. method:: set_right_margin_position(pos: int) -> None Sets the position of the right margin in the given ``view``\. :param pos: the width in characters where to position the right margin. .. method:: set_show_line_marks(show: bool) -> None If :const:`True` line marks will be displayed beside the text. :param show: whether line marks should be displayed. .. method:: set_show_line_numbers(show: bool) -> None If :const:`True` line numbers will be displayed beside the text. :param show: whether line numbers should be displayed. .. method:: set_show_right_margin(show: bool) -> None If :const:`True` a right margin is displayed. :param show: whether to show a right margin. .. method:: set_smart_backspace(smart_backspace: bool) -> None When set to :const:`True`, pressing the Backspace key will try to delete spaces up to the previous tab stop. :param smart_backspace: whether to enable smart Backspace handling. .. method:: set_smart_home_end(smart_home_end: ~gi.repository.GtkSource.SmartHomeEndType) -> None Set the desired movement of the cursor when HOME and END keys are pressed. :param smart_home_end: the desired behavior among :obj:`~gi.repository.GtkSource.SmartHomeEndType`\. .. method:: set_tab_width(width: int) -> None Sets the width of tabulation in characters. The :obj:`~gi.repository.Gtk.TextBuffer` still contains ``\t`` characters, but they can take a different visual width in a :obj:`~gi.repository.GtkSource.View` widget. :param width: width of tab in characters. .. method:: unindent_lines(start: ~gi.repository.Gtk.TextIter, end: ~gi.repository.Gtk.TextIter) -> None Removes one indentation level at the beginning of the specified lines. :param start: :obj:`~gi.repository.Gtk.TextIter` of the first line to indent :param end: :obj:`~gi.repository.Gtk.TextIter` of the last line to indent Properties ---------- .. rst-class:: interim-class .. class:: View :no-index: .. attribute:: props.annotations :type: ~gi.repository.GtkSource.Annotations The :obj:`~gi.repository.GtkSource.Annotations` object associated with the view. .. versionadded:: 5.18 .. attribute:: props.auto_indent :type: bool .. attribute:: props.background_pattern :type: ~gi.repository.GtkSource.BackgroundPatternType Draw a specific background pattern on the view. .. attribute:: props.completion :type: ~gi.repository.GtkSource.Completion The completion object associated with the view .. attribute:: props.enable_snippets :type: bool The property denotes if snippets should be expanded when the user presses Tab after having typed a word matching the snippets found in :obj:`~gi.repository.GtkSource.SnippetManager`\. The user may tab through focus-positions of the snippet if any are available by pressing Tab repeatedly until the desired focus position is selected. .. attribute:: props.highlight_current_line :type: bool .. attribute:: props.indent_on_tab :type: bool .. attribute:: props.indent_width :type: int Width of an indentation step expressed in number of spaces. .. attribute:: props.indenter :type: ~gi.repository.GtkSource.Indenter The property is a :obj:`~gi.repository.GtkSource.Indenter` to use to indent as the user types into the :obj:`~gi.repository.GtkSource.View`\. .. attribute:: props.insert_spaces_instead_of_tabs :type: bool .. attribute:: props.right_margin_position :type: int Position of the right margin. .. attribute:: props.show_line_marks :type: bool Whether to display line mark pixbufs .. attribute:: props.show_line_numbers :type: bool Whether to display line numbers .. attribute:: props.show_right_margin :type: bool Whether to display the right margin. .. attribute:: props.smart_backspace :type: bool Whether smart Backspace should be used. .. attribute:: props.smart_home_end :type: ~gi.repository.GtkSource.SmartHomeEndType Set the behavior of the HOME and END keys. .. attribute:: props.space_drawer :type: ~gi.repository.GtkSource.SpaceDrawer The :obj:`~gi.repository.GtkSource.SpaceDrawer` object associated with the view. .. attribute:: props.tab_width :type: int Width of a tab character expressed in number of spaces. Signals ------- .. rst-class:: interim-class .. class:: View.signals :no-index: .. method:: change_case(case_type: ~gi.repository.GtkSource.ChangeCaseType) -> None Keybinding signal to change case of the text at the current cursor position. :param case_type: the case to use .. method:: change_number(count: int) -> None Keybinding signal to edit a number at the current cursor position. :param count: the number to add to the number at the current position .. method:: join_lines() -> None Keybinding signal to join the lines currently selected. .. method:: line_mark_activated(iter: ~gi.repository.Gtk.TextIter, button: int, state: ~gi.repository.Gdk.ModifierType, n_presses: int) -> None Emitted when a line mark has been activated (for instance when there was a button press in the line marks gutter). You can use ``iter`` to determine on which line the activation took place. :param iter: a :obj:`~gi.repository.Gtk.TextIter` :param button: the button that was pressed :param state: the modifier state, if any :param n_presses: the number of presses .. method:: move_lines(down: bool) -> None The signal is a keybinding which gets emitted when the user initiates moving a line. The default binding key is Alt+Up/Down arrow. And moves the currently selected lines, or the current line up or down by one line. :param down: :const:`True` to move down, :const:`False` to move up. .. method:: move_to_matching_bracket(extend_selection: bool) -> None Keybinding signal to move the cursor to the matching bracket. :param extend_selection: :const:`True` if the move should extend the selection .. method:: move_words(count: int) -> None The signal is a keybinding which gets emitted when the user initiates moving a word. The default binding key is Alt+Left/Right Arrow and moves the current selection, or the current word by one word. :param count: the number of words to move over .. method:: push_snippet(snippet: ~gi.repository.GtkSource.Snippet, location: ~gi.repository.Gtk.TextIter) -> ~gi.repository.Gtk.TextIter The signal is emitted to insert a new snippet into the view. If another snippet was active, it will be paused until all focus positions of ``snippet`` have been exhausted. ``location`` will be updated to point at the end of the snippet. :param snippet: a :obj:`~gi.repository.GtkSource.Snippet` :param location: a :obj:`~gi.repository.Gtk.TextIter` .. method:: show_completion() -> None The signal is a key binding signal which gets emitted when the user requests a completion, by pressing Controlspace. This will create a :obj:`~gi.repository.GtkSource.CompletionContext` with the activation type as :const:`~gi.repository.GtkSource.CompletionActivation.USER_REQUESTED`. Applications should not connect to it, but may emit it with :obj:`~gi.repository.GObject.signal_emit_by_name` if they need to activate the completion by another means, for example with another key binding or a menu entry. .. method:: smart_home_end(iter: ~gi.repository.Gtk.TextIter, count: int) -> None Emitted when a the cursor was moved according to the smart home end setting. The signal is emitted after the cursor is moved, but during the :obj:`~gi.repository.Gtk.TextView.signals.move_cursor` action. This can be used to find out whether the cursor was moved by a normal home/end or by a smart home/end. :param iter: a :obj:`~gi.repository.Gtk.TextIter` :param count: the count Virtual Methods --------------- .. rst-class:: interim-class .. class:: View :no-index: .. method:: do_line_mark_activated(iter: ~gi.repository.Gtk.TextIter, button: int, state: ~gi.repository.Gdk.ModifierType, n_presses: int) -> None :param iter: :param button: :param state: :param n_presses: .. method:: do_move_lines(down: bool) -> None :param down: .. method:: do_move_words(step: int) -> None :param step: .. method:: do_push_snippet(snippet: ~gi.repository.GtkSource.Snippet, location: ~gi.repository.Gtk.TextIter | None = None) -> None Inserts a new snippet at ``location`` If another snippet was already active, it will be paused and the new snippet will become active. Once the focus positions of ``snippet`` have been exhausted, editing will return to the previous snippet. :param snippet: a :obj:`~gi.repository.GtkSource.Snippet` :param location: a :obj:`~gi.repository.Gtk.TextIter` or :const:`None` for the cursor position .. method:: do_show_completion() -> None Fields ------ .. rst-class:: interim-class .. class:: View :no-index: .. attribute:: parent_instance