:right-sidebar: True SearchContext =================================================================== .. currentmodule:: gi.repository.GtkSource .. class:: SearchContext(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Search context. A ``GtkSourceSearchContext`` is used for the search and replace in a :obj:`~gi.repository.GtkSource.Buffer`\. The search settings are represented by a :obj:`~gi.repository.GtkSource.SearchSettings` object. There can be a many-to-many relationship between buffers and search settings, with the search contexts in-between: a search settings object can be shared between several search contexts; and a buffer can contain several search contexts at the same time. The total number of search occurrences can be retrieved with :obj:`~gi.repository.SearchContext.get_occurrences_count`\. To know the position of a certain match, use :obj:`~gi.repository.SearchContext.get_occurrence_position`\. The buffer is scanned asynchronously, so it doesn't block the user interface. For each search, the buffer is scanned at most once. After that, navigating through the occurrences doesn't require to re-scan the buffer entirely. To search forward, use :obj:`~gi.repository.SearchContext.forward` or :obj:`~gi.repository.SearchContext.forward_async` for the asynchronous version. The backward search is done similarly. To replace a search match, or all matches, use :obj:`~gi.repository.SearchContext.replace` and :obj:`~gi.repository.SearchContext.replace_all`\. The search occurrences are highlighted by default. To disable it, use :obj:`~gi.repository.SearchContext.set_highlight`\. You can enable the search highlighting for several ``GtkSourceSearchContext``\s attached to the same buffer. Moreover, each of those ``GtkSourceSearchContext``\s can have a different text style associated. Use :obj:`~gi.repository.SearchContext.set_match_style` to specify the :obj:`~gi.repository.GtkSource.Style` to apply on search matches. Note that the :obj:`~gi.repository.GtkSource.SearchContext.props.highlight` and :obj:`~gi.repository.GtkSource.SearchContext.props.match_style` properties are in the ``GtkSourceSearchContext`` class, not :obj:`~gi.repository.GtkSource.SearchSettings`\. Appearance settings should be tied to one, and only one buffer, as different buffers can have different style scheme associated (a :obj:`~gi.repository.GtkSource.SearchSettings` object can be bound indirectly to several buffers). The concept of "current match" doesn't exist yet. A way to highlight differently the current match is to select it. A search occurrence's position doesn't depend on the cursor position or other parameters. Take for instance the buffer "aaaa" with the search text "aa". The two occurrences are at positions [0:2] and [2:4]. If you begin to search at position 1, you will get the occurrence [2:4], not [1:3]. This is a prerequisite for regular expression searches. The pattern ".\*" matches the entire line. If the cursor is at the middle of the line, you don't want the rest of the line as the occurrence, you want an entire line. (As a side note, regular expression searches can also match multiple lines.) In the GtkSourceView source code, there is an example of how to use the search and replace API: see the tests/test-search.c file. It is a mini application for the search and replace, with a basic user interface. 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) -> ~typing.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[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> 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) -> ~typing.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) -> ~typing.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[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> 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) -> ~typing.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 type of the None singleton. .. attribute:: props.highlight :type: bool The type of the None singleton. .. attribute:: props.match_style :type: ~gi.repository.GtkSource.Style The type of the None singleton. .. attribute:: props.occurrences_count :type: int The type of the None singleton. .. attribute:: props.regex_error :type: ~gi.repository.GLib.GError The type of the None singleton. .. attribute:: props.settings :type: ~gi.repository.GtkSource.SearchSettings The type of the None singleton.