:right-sidebar: True SearchContext =================================================================== .. currentmodule:: gi.repository.GtkSource .. class:: SearchContext(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` :Constructors: :: SearchContext(**properties) new(buffer:GtkSource.Buffer, settings:GtkSource.SearchSettings=None) -> GtkSource.SearchContext Constructors ------------ .. rst-class:: interim-class .. class:: SearchContext :no-index: .. classmethod:: new(buffer: ~gi.repository.GtkSource.Buffer, settings: ~gi.repository.GtkSource.SearchSettings | None = None) -> ~gi.repository.GtkSource.SearchContext Creates a new search context, associated with ``buffer``, and customized with ``settings``. If ``settings`` is :const:`None`, a new :obj:`~gi.repository.GtkSource.SearchSettings` object will be created, that you can retrieve with :obj:`~gi.repository.SearchContext.get_settings`. :param buffer: a :obj:`~gi.repository.GtkSource.Buffer`. :param settings: a :obj:`~gi.repository.GtkSource.SearchSettings`, or :const:`None`. Methods ------- .. rst-class:: interim-class .. class:: SearchContext :no-index: .. method:: backward(iter: ~gi.repository.Gtk.TextIter) -> tuple[bool, ~gi.repository.Gtk.TextIter, ~gi.repository.Gtk.TextIter, bool] Synchronous backward search. It is recommended to use the asynchronous functions instead, to not block the user interface. However, if you are sure that the ``buffer`` is small, this function is more convenient to use. If the :obj:`~gi.repository.GtkSource.SearchSettings.props.wrap_around` property is :const:`False`, this function doesn't try to wrap around. The ``has_wrapped_around`` out parameter is set independently of whether a match is found. So if this function returns :const:`False`, ``has_wrapped_around`` will have the same value as the :obj:`~gi.repository.GtkSource.SearchSettings.props.wrap_around` property. :param iter: start of search. .. method:: backward_async(iter: ~gi.repository.Gtk.TextIter, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None The asynchronous version of :obj:`~gi.repository.SearchContext.backward`. See the :obj:`~gi.repository.Gio.AsyncResult` documentation to know how to use this function. If the operation is cancelled, the ``callback`` will only be called if ``cancellable`` was not :const:`None`. The method takes ownership of ``cancellable``, so you can unref it after calling this function. :param iter: start of search. :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`, or :const:`None`. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the operation is finished. :param user_data: the data to pass to the ``callback`` function. .. method:: backward_finish(result: ~gi.repository.Gio.AsyncResult) -> tuple[bool, ~gi.repository.Gtk.TextIter, ~gi.repository.Gtk.TextIter, bool] Finishes a backward search started with :obj:`~gi.repository.SearchContext.backward_async`. See the documentation of :obj:`~gi.repository.SearchContext.backward` for more details. :param result: a :obj:`~gi.repository.Gio.AsyncResult`. .. method:: forward(iter: ~gi.repository.Gtk.TextIter) -> tuple[bool, ~gi.repository.Gtk.TextIter, ~gi.repository.Gtk.TextIter, bool] Synchronous forward search. It is recommended to use the asynchronous functions instead, to not block the user interface. However, if you are sure that the ``buffer`` is small, this function is more convenient to use. If the :obj:`~gi.repository.GtkSource.SearchSettings.props.wrap_around` property is :const:`False`, this function doesn't try to wrap around. The ``has_wrapped_around`` out parameter is set independently of whether a match is found. So if this function returns :const:`False`, ``has_wrapped_around`` will have the same value as the :obj:`~gi.repository.GtkSource.SearchSettings.props.wrap_around` property. :param iter: start of search. .. method:: forward_async(iter: ~gi.repository.Gtk.TextIter, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None The asynchronous version of :obj:`~gi.repository.SearchContext.forward`. See the :obj:`~gi.repository.Gio.AsyncResult` documentation to know how to use this function. If the operation is cancelled, the ``callback`` will only be called if ``cancellable`` was not :const:`None`. The method takes ownership of ``cancellable``, so you can unref it after calling this function. :param iter: start of search. :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`, or :const:`None`. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the operation is finished. :param user_data: the data to pass to the ``callback`` function. .. method:: forward_finish(result: ~gi.repository.Gio.AsyncResult) -> tuple[bool, ~gi.repository.Gtk.TextIter, ~gi.repository.Gtk.TextIter, bool] Finishes a forward search started with :obj:`~gi.repository.SearchContext.forward_async`. See the documentation of :obj:`~gi.repository.SearchContext.forward` for more details. :param result: a :obj:`~gi.repository.Gio.AsyncResult`. .. method:: get_buffer() -> ~gi.repository.GtkSource.Buffer .. method:: get_highlight() -> bool .. method:: get_match_style() -> ~gi.repository.GtkSource.Style .. method:: get_occurrence_position(match_start: ~gi.repository.Gtk.TextIter, match_end: ~gi.repository.Gtk.TextIter) -> int Gets the position of a search occurrence. If the buffer is not already fully scanned, the position may be unknown, and -1 is returned. If 0 is returned, it means that this part of the buffer has already been scanned, and that ``match_start`` and ``match_end`` don't delimit an occurrence. :param match_start: the start of the occurrence. :param match_end: the end of the occurrence. .. method:: get_occurrences_count() -> int Gets the total number of search occurrences. If the buffer is not already fully scanned, the total number of occurrences is unknown, and -1 is returned. .. method:: get_regex_error() -> ~gi.repository.GLib.GError | None Regular expression patterns must follow certain rules. If :obj:`~gi.repository.GtkSource.SearchSettings.props.search_text` breaks a rule, the error can be retrieved with this function. The error domain is :obj:`~gi.repository.GLib.RegexError`. Free the return value with :obj:`~gi.repository.GLib.Error.free`. .. method:: get_settings() -> ~gi.repository.GtkSource.SearchSettings .. method:: replace(match_start: ~gi.repository.Gtk.TextIter, match_end: ~gi.repository.Gtk.TextIter, replace: str, replace_length: int) -> bool Replaces a search match by another text. If ``match_start`` and ``match_end`` doesn't correspond to a search match, :const:`False` is returned. ``match_start`` and ``match_end`` iters are revalidated to point to the replacement text boundaries. For a regular expression replacement, you can check if ``replace`` is valid by calling :obj:`~gi.repository.GLib.Regex.check_replacement`. The ``replace`` text can contain backreferences. :param match_start: the start of the match to replace. :param match_end: the end of the match to replace. :param replace: the replacement text. :param replace_length: the length of ``replace`` in bytes, or -1. .. method:: replace_all(replace: str, replace_length: int) -> int Replaces all search matches by another text. It is a synchronous function, so it can block the user interface. For a regular expression replacement, you can check if ``replace`` is valid by calling :obj:`~gi.repository.GLib.Regex.check_replacement`. The ``replace`` text can contain backreferences. :param replace: the replacement text. :param replace_length: the length of ``replace`` in bytes, or -1. .. method:: set_highlight(highlight: bool) -> None Enables or disables the search occurrences highlighting. :param highlight: the setting. .. method:: set_match_style(match_style: ~gi.repository.GtkSource.Style | None = None) -> None Set the style to apply on search matches. If ``match_style`` is :const:`None`, default theme's scheme 'match-style' will be used. To enable or disable the search highlighting, use :obj:`~gi.repository.SearchContext.set_highlight`. :param match_style: a :obj:`~gi.repository.GtkSource.Style`, or :const:`None`. Properties ---------- .. rst-class:: interim-class .. class:: SearchContext :no-index: .. attribute:: props.buffer :type: ~gi.repository.GtkSource.Buffer The :obj:`~gi.repository.GtkSource.Buffer` associated to the search context. .. attribute:: props.highlight :type: bool Highlight the search occurrences. .. attribute:: props.match_style :type: ~gi.repository.GtkSource.Style A :obj:`~gi.repository.GtkSource.Style`, or :const:`None` for theme's scheme default style. .. attribute:: props.occurrences_count :type: int The total number of search occurrences. If the search is disabled, the value is 0. If the buffer is not already fully scanned, the value is -1. .. attribute:: props.regex_error :type: ~gi.repository.GLib.GError If the regex search pattern doesn't follow all the rules, this :obj:`~gi.repository.GLib.Error` property will be set. If the pattern is valid, the value is :const:`None`. Free with :obj:`~gi.repository.GLib.Error.free`. .. attribute:: props.settings :type: ~gi.repository.GtkSource.SearchSettings The :obj:`~gi.repository.GtkSource.SearchSettings` associated to the search context. This property is construct-only since version 4.0.