SearchContext

class SearchContext(**properties: Any)

Superclasses: Object

Constructors:

SearchContext(**properties)
new(buffer:GtkSource.Buffer, settings:GtkSource.SearchSettings=None) -> GtkSource.SearchContext

Constructors

class SearchContext
classmethod new(buffer: Buffer, settings: SearchSettings | None = None) → SearchContext

Creates a new search context, associated with buffer, and customized with settings.

If settings is None, a new SearchSettings object will be created, that you can retrieve with get_settings.

Parameters:

Methods

class SearchContext
backward(iter: TextIter) → tuple[bool, TextIter, 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 wrap_around property is 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 False, has_wrapped_around will have the same value as the wrap_around property.

Parameters:

iter – start of search.

backward_async(iter: TextIter, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

The asynchronous version of backward.

See the AsyncResult documentation to know how to use this function.

If the operation is cancelled, the callback will only be called if cancellable was not None. The method takes ownership of cancellable, so you can unref it after calling this function.

Parameters:

  • iter – start of search.

  • cancellable – a Cancellable, or None.

  • callback – a AsyncReadyCallback to call when the operation is finished.

  • user_data – the data to pass to the callback function.

backward_finish(result: AsyncResult) → tuple[bool, TextIter, TextIter, bool]

Finishes a backward search started with backward_async.

See the documentation of backward for more details.

Parameters:

result – a AsyncResult.

forward(iter: TextIter) → tuple[bool, TextIter, 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 wrap_around property is 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 False, has_wrapped_around will have the same value as the wrap_around property.

Parameters:

iter – start of search.

forward_async(iter: TextIter, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

The asynchronous version of forward.

See the AsyncResult documentation to know how to use this function.

If the operation is cancelled, the callback will only be called if cancellable was not None. The method takes ownership of cancellable, so you can unref it after calling this function.

Parameters:

  • iter – start of search.

  • cancellable – a Cancellable, or None.

  • callback – a AsyncReadyCallback to call when the operation is finished.

  • user_data – the data to pass to the callback function.

forward_finish(result: AsyncResult) → tuple[bool, TextIter, TextIter, bool]

Finishes a forward search started with forward_async.

See the documentation of forward for more details.

Parameters:

result – a AsyncResult.

get_buffer() → Buffer
get_highlight() → bool
get_match_style() → Style
get_occurrence_position(match_start: TextIter, match_end: 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.

Parameters:

  • match_start – the start of the occurrence.

  • match_end – the end of the occurrence.

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.

get_regex_error() → GError | None

Regular expression patterns must follow certain rules. If search_text breaks a rule, the error can be retrieved with this function.

The error domain is RegexError.

Free the return value with free.

get_settings() → SearchSettings
replace(match_start: TextIter, match_end: 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, 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 check_replacement. The replace text can contain backreferences.

Parameters:

  • match_start – the start of the match to replace.

  • match_end – the end of the match to replace.

  • replace – the replacement text.

  • replace_length – the length of replace in bytes, or -1.

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 check_replacement. The replace text can contain backreferences.

Parameters:

  • replace – the replacement text.

  • replace_length – the length of replace in bytes, or -1.

set_highlight(highlight: bool) → None

Enables or disables the search occurrences highlighting.

Parameters:

highlight – the setting.

set_match_style(match_style: Style | None = None) → None

Set the style to apply on search matches.

If match_style is None, default theme’s scheme ‘match-style’ will be used. To enable or disable the search highlighting, use set_highlight.

Parameters:

match_style – a Style, or None.

Properties

class SearchContext
props.buffer: Buffer

The Buffer associated to the search context.

props.highlight: bool

Highlight the search occurrences.

props.match_style: Style

A Style, or None for theme’s scheme default style.

props.occurrences_count: 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.

props.regex_error: GError

If the regex search pattern doesn’t follow all the rules, this Error property will be set. If the pattern is valid, the value is None.

Free with free.

props.settings: SearchSettings

The SearchSettings associated to the search context.

This property is construct-only since version 4.0.