GtkSource.SearchContext¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` (buffer, settings)
	`backward` (iter)
	`backward_async` (iter, cancellable, callback, *user_data)
	`backward_finish` (result)
	`forward` (iter)
	`forward_async` (iter, cancellable, callback, *user_data)
	`forward_finish` (result)
	`get_buffer` ()
	`get_highlight` ()
	`get_match_style` ()
	`get_occurrence_position` (match_start, match_end)
	`get_occurrences_count` ()
	`get_regex_error` ()
	`get_settings` ()
	`replace` (match_start, match_end, replace, replace_length)
	`replace_all` (replace, replace_length)
	`set_highlight` (highlight)
	`set_match_style` (match_style)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`buffer`	`GtkSource.Buffer`	r/w/co	The associated `GtkSource.Buffer`
`highlight`	`bool`	r/w/c	Highlight search occurrences
`match-style`	`GtkSource.Style`	r/w/c	The text style for matches
`occurrences-count`	`int`	r	Total number of search occurrences
`regex-error`	`GLib.Error`	r	Regular expression error
`settings`	`GtkSource.SearchSettings`	r/w/co	The associated `GtkSource.SearchSettings`

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class GtkSource.SearchContext(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: GtkSource.SearchContextClass

Search context.

A GtkSourceSearchContext is used for the search and replace in a [class`Buffer`]. The search settings are represented by a [class`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 [method`SearchContext`.get_occurrences_count]. To know the position of a certain match, use [method`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 [method`SearchContext`.forward] or [method`SearchContext`.forward_async] for the asynchronous version. The backward search is done similarly. To replace a search match, or all matches, use [method`SearchContext`.replace] and [method`SearchContext`.replace_all].

The search occurrences are highlighted by default. To disable it, use [method`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 [method`SearchContext`.set_match_style] to specify the [class`Style`] to apply on search matches.

Note that the [property`SearchContext`:py:data::highlight<GtkSource.SearchContext.props.highlight>] and [property`SearchContext`:py:data::match-style<GtkSource.SearchContext.props.match_style>] properties are in the GtkSourceSearchContext class, not [class`SearchSettings`]. Appearance settings should be tied to one, and only one buffer, as different buffers can have different style scheme associated (a [class`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 GtkSource.View 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.

classmethod new(buffer, settings)¶

Parameters:

buffer (GtkSource.Buffer) – a GtkSource.Buffer.
settings (GtkSource.SearchSettings or None) – a GtkSource.SearchSettings, or None.

Returns:

a new search context.

Return type:

GtkSource.SearchContext

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

If settings is None, a new [class`SearchSettings`] object will be created, that you can retrieve with [method`SearchContext`.get_settings].

backward(iter)¶

Parameters:

iter (Gtk.TextIter) – start of search.

Returns:

whether a match was found.

match_start:: return location for start of match, or None.
match_end:: return location for end of match, or None.
has_wrapped_around:: return location to know whether the search has wrapped around, or None.

Return type:

(bool, match_start: Gtk.TextIter, match_end: Gtk.TextIter, has_wrapped_around: 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 [property`SearchSettings`:py:data::wrap-around<GtkSource.SearchContext.props.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 [property`SearchSettings`:py:data::wrap-around<GtkSource.SearchContext.props.wrap_around>] property.

backward_async(iter, cancellable, callback, *user_data)¶

Parameters:

iter (Gtk.TextIter) – start of search.
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None.
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the operation is finished.
user_data (object or None) – the data to pass to the callback function.

The asynchronous version of [method`SearchContext`.backward].

See the [iface`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 None. The method takes ownership of cancellable, so you can unref it after calling this function.

backward_finish(result)¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

whether a match was found.

match_start:: return location for start of match, or None.
match_end:: return location for end of match, or None.
has_wrapped_around:: return location to know whether the search has wrapped around, or None.

Return type:

(bool, match_start: Gtk.TextIter, match_end: Gtk.TextIter, has_wrapped_around: bool)

Finishes a backward search started with [method`SearchContext`.backward_async].

See the documentation of [method`SearchContext`.backward] for more details.

forward(iter)¶

Parameters:

iter (Gtk.TextIter) – start of search.

Returns:

whether a match was found.

match_start:: return location for start of match, or None.
match_end:: return location for end of match, or None.
has_wrapped_around:: return location to know whether the search has wrapped around, or None.

Return type:

(bool, match_start: Gtk.TextIter, match_end: Gtk.TextIter, has_wrapped_around: 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 [property`SearchSettings`:py:data::wrap-around<GtkSource.SearchContext.props.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 [property`SearchSettings`:py:data::wrap-around<GtkSource.SearchContext.props.wrap_around>] property.

forward_async(iter, cancellable, callback, *user_data)¶

Parameters:

iter (Gtk.TextIter) – start of search.
cancellable (Gio.Cancellable or None) – a Gio.Cancellable, or None.
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the operation is finished.
user_data (object or None) – the data to pass to the callback function.

The asynchronous version of [method`SearchContext`.forward].

See the [iface`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 None. The method takes ownership of cancellable, so you can unref it after calling this function.

forward_finish(result)¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult.

Raises:

GLib.Error

Returns:

whether a match was found.

match_start:: return location for start of match, or None.
match_end:: return location for end of match, or None.
has_wrapped_around:: return location to know whether the search has wrapped around, or None.

Return type:

(bool, match_start: Gtk.TextIter, match_end: Gtk.TextIter, has_wrapped_around: bool)

Finishes a forward search started with [method`SearchContext`.forward_async].

See the documentation of [method`SearchContext`.forward] for more details.

get_buffer()¶

Returns:: the associated buffer.
Return type:: GtkSource.Buffer

get_highlight()¶

Returns:: whether to highlight the search occurrences.
Return type:: bool

get_match_style()¶

Returns:: the GtkSource.Style to apply on search matches.
Return type:: GtkSource.Style

get_occurrence_position(match_start, match_end)¶

Parameters:

match_start (Gtk.TextIter) – the start of the occurrence.
match_end (Gtk.TextIter) – the end of the occurrence.

Returns:

the position of the search occurrence. The first occurrence has the position 1 (not 0). Returns 0 if match_start and match_end don’t delimit an occurrence. Returns -1 if the position is not yet known.

Return type:

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.

get_occurrences_count()¶

Returns:: the total number of search occurrences, or -1 if unknown.
Return type:: 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()¶

Returns:: the GLib.Error, or None if the pattern is valid.
Return type:: GLib.Error or None

Regular expression patterns must follow certain rules. If [property`SearchSettings`:py:data::search-text<GtkSource.SearchContext.props.search_text>] breaks a rule, the error can be retrieved with this function.

The error domain is [error`GLib`.RegexError].

Free the return value with [method`GLib`.Error.free].

get_settings()¶

Returns:: the search settings.
Return type:: GtkSource.SearchSettings

replace(match_start, match_end, replace, replace_length)¶

Parameters:

match_start (Gtk.TextIter) – the start of the match to replace.
match_end (Gtk.TextIter) – the end of the match to replace.
replace (str) – the replacement text.
replace_length (int) – the length of replace in bytes, or -1.

Raises:

GLib.Error

Returns:

whether the match has been replaced.

Return type:

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 [func`GLib`.Regex.check_replacement]. The replace text can contain backreferences.

replace_all(replace, replace_length)¶

Parameters:

replace (str) – the replacement text.
replace_length (int) – the length of replace in bytes, or -1.

Raises:

GLib.Error

Returns:

the number of replaced matches.

Return type:

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 [func`GLib`.Regex.check_replacement]. The replace text can contain backreferences.

set_highlight(highlight)¶

Parameters:: highlight (bool) – the setting.

Enables or disables the search occurrences highlighting.

set_match_style(match_style)¶

Parameters:: match_style (GtkSource.Style or None) – a GtkSource.Style, or 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 [method`SearchContext`.set_highlight].

Property Details¶

GtkSource.SearchContext.props.buffer¶

Name:: buffer
Type:: GtkSource.Buffer
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The [class`Buffer`] associated to the search context.

GtkSource.SearchContext.props.highlight¶

Name:: highlight
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, CONSTRUCT

Highlight the search occurrences.

GtkSource.SearchContext.props.match_style¶

Name:: match-style
Type:: GtkSource.Style
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT

A [class`Style`], or None for theme’s scheme default style.

GtkSource.SearchContext.props.occurrences_count¶

Name:: occurrences-count
Type:: int
Default Value:: 0
Flags:: READABLE

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.

GtkSource.SearchContext.props.regex_error¶

Name:: regex-error
Type:: GLib.Error
Default Value:: None
Flags:: READABLE

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

Free with [method`GLib`.Error.free].

GtkSource.SearchContext.props.settings¶

Name:: settings
Type:: GtkSource.SearchSettings
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The [class`SearchSettings`] associated to the search context.

This property is construct-only since version 4.0.