Struct sourceview5::SearchContext

pub struct SearchContext { /* private fields */ }

Search context.

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

The search occurrences are highlighted by default. To disable it, use set_highlight(). You can enable the search highlighting for several SearchContexts attached to the same buffer. Moreover, each of those SearchContexts can have a different text style associated. Use set_match_style() to specify the Style to apply on search matches.

Note that the highlight and match-style properties are in the SearchContext class, not SearchSettings. Appearance settings should be tied to one, and only one buffer, as different buffers can have different style scheme associated (a 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.

Properties

buffer

The Buffer associated to the search context.

Readable | Writeable | Construct Only

highlight

Highlight the search occurrences.

Readable | Writeable | Construct

match-style

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

Readable | Writeable | Construct

occurrences-count

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.

Readable

regex-error

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

Free with GLib::Error::free().

Readable

settings

The SearchSettings associated to the search context.

This property is construct-only since version 4.0.

Readable | Writeable | Construct Only

Implements

[trait@glib::ObjectExt]

GLib type: GObject with reference counted clone semantics.

Implementations

impl SearchContext

pub fn new( buffer: &impl IsA<Buffer>, settings: Option<&impl IsA<SearchSettings>>, ) -> 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 settings().

buffer

a #GtkSourceBuffer.

settings

a #GtkSourceSearchSettings, or None.

Returns

a new search context.

pub fn builder() -> SearchContextBuilder

Creates a new builder-pattern struct instance to construct SearchContext objects.

This method returns an instance of SearchContextBuilder which can be used to create SearchContext objects.

pub fn backward(&self, iter: &TextIter) -> Option<(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.

iter

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.

pub fn backward_async<P: FnOnce(Result<(TextIter, TextIter, bool), Error>) + 'static>( &self, iter: &TextIter, cancellable: Option<&impl IsA<Cancellable>>, callback: P, )

The asynchronous version of backward().

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. The method takes ownership of @cancellable, so you can unref it after calling this function.

iter

start of search.

cancellable

a #GCancellable, or None.

callback

a #GAsyncReadyCallback to call when the operation is finished.

pub fn backward_future( &self, iter: &TextIter, ) -> Pin<Box_<dyn Future<Output = Result<(TextIter, TextIter, bool), Error>> + 'static>>

pub fn forward(&self, iter: &TextIter) -> Option<(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.

iter

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.

pub fn forward_async<P: FnOnce(Result<(TextIter, TextIter, bool), Error>) + 'static>( &self, iter: &TextIter, cancellable: Option<&impl IsA<Cancellable>>, callback: P, )

The asynchronous version of forward().

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. The method takes ownership of @cancellable, so you can unref it after calling this function.

iter

start of search.

cancellable

a #GCancellable, or None.

callback

a #GAsyncReadyCallback to call when the operation is finished.

pub fn forward_future( &self, iter: &TextIter, ) -> Pin<Box_<dyn Future<Output = Result<(TextIter, TextIter, bool), Error>> + 'static>>

pub fn buffer(&self) -> Buffer

Returns

the associated buffer.

pub fn is_highlight(&self) -> bool

Returns

whether to highlight the search occurrences.

pub fn match_style(&self) -> Style

Returns

the #GtkSourceStyle to apply on search matches.

pub fn occurrence_position( &self, match_start: &TextIter, match_end: &TextIter, ) -> i32

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.

match_start

the start of the occurrence.

match_end

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.

pub fn occurrences_count(&self) -> i32

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.

Returns

the total number of search occurrences, or -1 if unknown.

pub fn regex_error(&self) -> Option<Error>

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

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

Returns

the #GError, or None if the pattern is valid.

pub fn settings(&self) -> SearchSettings

Returns

the search settings.

pub fn replace( &self, match_start: &mut TextIter, match_end: &mut TextIter, replace: &str, ) -> Result<(), Error>

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 GLib::Regex::check_replacement(). The @replace text can contain backreferences.

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.

Returns

whether the match has been replaced.

pub fn set_highlight(&self, highlight: bool)

Enables or disables the search occurrences highlighting.

highlight

the setting.

pub fn set_match_style(&self, match_style: Option<&Style>)

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

match_style

a #GtkSourceStyle, or None.

pub fn connect_highlight_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

pub fn connect_match_style_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

pub fn connect_occurrences_count_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

pub fn connect_regex_error_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

impl SearchContext

pub fn replace_all(&self, replace: &str) -> Result<(), Error>

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.

replace

the replacement text.

replace_length

the length of @replace in bytes, or -1.

Returns

the number of replaced matches.

Trait Implementations

impl Clone for SearchContext

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SearchContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SearchContext

fn default() -> Self

Returns the “default value” for a type.

impl HasParamSpec for SearchContext

type ParamSpec = ParamSpecObject

type SetValue = SearchContext

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, SearchContext>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for SearchContext

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the memory address of this object.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for SearchContext

fn cmp(&self, other: &Self) -> Ordering

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl ParentClassIs for SearchContext

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for SearchContext

fn eq(&self, other: &OT) -> bool

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for SearchContext

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for SearchContext

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for SearchContext