GtkSource.SearchContext

g GObject.Object GObject.Object GtkSource.SearchContext GtkSource.SearchContext GObject.Object->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:
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:

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:

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