GtkSource.SearchContext¶

Subclasses:: None

Methods¶

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

class	`new` (buffer, settings)
	`backward` (iter)
	`backward2` (iter)
	`backward_async` (iter, cancellable, callback, *user_data)
	`backward_finish` (result)
	`backward_finish2` (result)
	`forward` (iter)
	`forward2` (iter)
	`forward_async` (iter, cancellable, callback, *user_data)
	`forward_finish` (result)
	`forward_finish2` (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)
	`replace2` (match_start, match_end, replace, replace_length)
	`replace_all` (replace, replace_length)
	`set_highlight` (highlight)
	`set_match_style` (match_style)
	`set_settings` (settings)

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`	`int`	r	Regular expression error
`settings`	`GtkSource.SearchSettings`	r/w/c	The associated `GtkSource.SearchSettings`

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class GtkSource.SearchContext(**kwargs)¶

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

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 GtkSource.SearchSettings object will be created, that you can retrieve with GtkSource.SearchContext.get_settings().

New in version 3.10.

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.

Return type:

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

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.

New in version 3.10.

Deprecated since version 3.22: Use GtkSource.SearchContext.backward2() instead.

backward2(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.

The difference with GtkSource.SearchContext.backward() is that the has_wrapped_around out parameter has been added for convenience.

If the GtkSource.SearchSettings :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 GtkSource.SearchSettings :wrap-around property.

New in version 3.22.

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 GtkSource.SearchContext.backward2().

See the documentation of GtkSource.SearchContext.backward2() for more details.

See the 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. GtkSource.SearchContext.backward_async() takes ownership of cancellable, so you can unref it after calling this function.

New in version 3.10.

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.

Return type:

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

Finishes a backward search started with GtkSource.SearchContext.backward_async().

New in version 3.10.

Deprecated since version 3.22: Use GtkSource.SearchContext.backward_finish2() instead.

backward_finish2(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 GtkSource.SearchContext.backward_async().

See the documentation of GtkSource.SearchContext.backward2() for more details.

New in version 3.22.

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.

Return type:

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

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.

New in version 3.10.

Deprecated since version 3.22: Use GtkSource.SearchContext.forward2() instead.

forward2(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.

The difference with GtkSource.SearchContext.forward() is that the has_wrapped_around out parameter has been added for convenience.

If the GtkSource.SearchSettings :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 GtkSource.SearchSettings :wrap-around property.

New in version 3.22.

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 GtkSource.SearchContext.forward2().

See the documentation of GtkSource.SearchContext.forward2() for more details.

See the 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. GtkSource.SearchContext.forward_async() takes ownership of cancellable, so you can unref it after calling this function.

New in version 3.10.

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.

Return type:

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

Finishes a forward search started with GtkSource.SearchContext.forward_async().

New in version 3.10.

Deprecated since version 3.22: Use GtkSource.SearchContext.forward_finish2() instead.

forward_finish2(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 GtkSource.SearchContext.forward_async().

See the documentation of GtkSource.SearchContext.forward2() for more details.

New in version 3.22.

get_buffer()¶

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

New in version 3.10.

get_highlight()¶

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

New in version 3.10.

get_match_style()¶

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

New in version 3.16.

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.

New in version 3.10.

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.

New in version 3.10.

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 GtkSource.SearchSettings :search-text breaks a rule, the error can be retrieved with this function. The error domain is #G_REGEX_ERROR.

Free the return value with GLib.Error.free().

New in version 3.10.

get_settings()¶

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

New in version 3.10.

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.

For a regular expression replacement, you can check if replace is valid by calling GLib.Regex.check_replacement(). The replace text can contain backreferences; read the GLib.Regex.replace() documentation for more details.

New in version 3.10.

Deprecated since version 3.22: Use GtkSource.SearchContext.replace2() instead.

replace2(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.

Unlike with GtkSource.SearchContext.replace(), the 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 GLib.Regex.check_replacement(). The replace text can contain backreferences; read the GLib.Regex.replace() documentation for more details.

New in version 3.22.

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 GLib.Regex.check_replacement(). The replace text can contain backreferences; read the GLib.Regex.replace() documentation for more details.

New in version 3.10.

set_highlight(highlight)¶

Parameters:: highlight (bool) – the setting.

Enables or disables the search occurrences highlighting.

New in version 3.10.

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 GtkSource.SearchContext.set_highlight().

New in version 3.16.

set_settings(settings)¶

Parameters:: settings (GtkSource.SearchSettings or None) – the new GtkSource.SearchSettings, or None.

Associate a GtkSource.SearchSettings with the search context. If settings is None, a new one will be created.

The search context holds a reference to settings.

New in version 3.10.

Deprecated since version 3.24: The GtkSource.SearchContext :settings property will become a construct-only property in a future version. Create a new GtkSource.SearchContext instead, or change the GtkSource.SearchSettings properties. When the GtkSource.SearchContext :settings property will become construct-only, it will be possible to simplify some code that needed to listen to the notify::settings signal.

Property Details¶

GtkSource.SearchContext.props.buffer¶

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

The GtkSource.Buffer associated to the search context.

New in version 3.10.

GtkSource.SearchContext.props.highlight¶

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

Highlight the search occurrences.

New in version 3.10.

GtkSource.SearchContext.props.match_style¶

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

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

New in version 3.16.

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.

New in version 3.10.

GtkSource.SearchContext.props.regex_error¶

Name:: regex-error
Type:: int
Default Value:: None
Flags:: READABLE

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

Free with GLib.Error.free().

New in version 3.10.

GtkSource.SearchContext.props.settings¶

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

The GtkSource.SearchSettings associated to the search context.

New in version 3.10.