GtkSourceSearchContext

GtkSourceSearchContext — Search context

Properties

GtkSourceBuffer * buffer Read / Write / Construct Only
gboolean highlight Read / Write / Construct
GtkSourceStyle * match-style Read / Write / Construct
gint occurrences-count Read
gpointer regex-error Read
GtkSourceSearchSettings * settings Read / Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ╰── GtkSourceSearchContext

Includes

#include <gtksourceview/gtksource.h>

Description

A GtkSourceSearchContext is used for the search and replace in a GtkSourceBuffer. The search settings are represented by a GtkSourceSearchSettings 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 gtk_source_search_context_get_occurrences_count(). To know the position of a certain match, use gtk_source_search_context_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 gtk_source_search_context_forward() or gtk_source_search_context_forward_async() for the asynchronous version. The backward search is done similarly. To replace a search match, or all matches, use gtk_source_search_context_replace() and gtk_source_search_context_replace_all().

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

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

Functions

gtk_source_search_context_new ()

GtkSourceSearchContext *
gtk_source_search_context_new (GtkSourceBuffer *buffer,
                               GtkSourceSearchSettings *settings);

Creates a new search context, associated with buffer , and customized with settings . If settings is NULL, a new GtkSourceSearchSettings object will be created, that you can retrieve with gtk_source_search_context_get_settings().

Parameters

buffer

a GtkSourceBuffer.

 

settings

a GtkSourceSearchSettings, or NULL.

[nullable]

Returns

a new search context.

Since: 3.10


gtk_source_search_context_get_buffer ()

GtkSourceBuffer *
gtk_source_search_context_get_buffer (GtkSourceSearchContext *search);

Parameters

search

a GtkSourceSearchContext.

 

Returns

the associated buffer.

[transfer none]

Since: 3.10


gtk_source_search_context_get_settings ()

GtkSourceSearchSettings *
gtk_source_search_context_get_settings
                               (GtkSourceSearchContext *search);

Parameters

search

a GtkSourceSearchContext.

 

Returns

the search settings.

[transfer none]

Since: 3.10


gtk_source_search_context_get_highlight ()

gboolean
gtk_source_search_context_get_highlight
                               (GtkSourceSearchContext *search);

Parameters

search

a GtkSourceSearchContext.

 

Returns

whether to highlight the search occurrences.

Since: 3.10


gtk_source_search_context_set_highlight ()

void
gtk_source_search_context_set_highlight
                               (GtkSourceSearchContext *search,
                                gboolean highlight);

Enables or disables the search occurrences highlighting.

Parameters

search

a GtkSourceSearchContext.

 

highlight

the setting.

 

Since: 3.10


gtk_source_search_context_get_match_style ()

GtkSourceStyle *
gtk_source_search_context_get_match_style
                               (GtkSourceSearchContext *search);

Parameters

search

a GtkSourceSearchContext.

 

Returns

the GtkSourceStyle to apply on search matches.

[transfer none]

Since: 3.16


gtk_source_search_context_set_match_style ()

void
gtk_source_search_context_set_match_style
                               (GtkSourceSearchContext *search,
                                GtkSourceStyle *match_style);

Set the style to apply on search matches. If match_style is NULL, default theme's scheme 'match-style' will be used. To enable or disable the search highlighting, use gtk_source_search_context_set_highlight().

Parameters

search

a GtkSourceSearchContext.

 

match_style

a GtkSourceStyle, or NULL.

[nullable]

Since: 3.16


gtk_source_search_context_get_occurrences_count ()

gint
gtk_source_search_context_get_occurrences_count
                               (GtkSourceSearchContext *search);

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.

Parameters

search

a GtkSourceSearchContext.

 

Returns

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

Since: 3.10


gtk_source_search_context_get_occurrence_position ()

gint
gtk_source_search_context_get_occurrence_position
                               (GtkSourceSearchContext *search,
                                const GtkTextIter *match_start,
                                const GtkTextIter *match_end);

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

search

a GtkSourceSearchContext.

 

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.

Since: 3.10


gtk_source_search_context_forward ()

gboolean
gtk_source_search_context_forward (GtkSourceSearchContext *search,
                                   const GtkTextIter *iter,
                                   GtkTextIter *match_start,
                                   GtkTextIter *match_end,
                                   gboolean *has_wrapped_around);

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

search

a GtkSourceSearchContext.

 

iter

start of search.

 

match_start

return location for start of match, or NULL.

[out][optional]

match_end

return location for end of match, or NULL.

[out][optional]

has_wrapped_around

return location to know whether the search has wrapped around, or NULL.

[out][optional]

Returns

whether a match was found.

Since: 4.0


gtk_source_search_context_forward_async ()

void
gtk_source_search_context_forward_async
                               (GtkSourceSearchContext *search,
                                const GtkTextIter *iter,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

The asynchronous version of gtk_source_search_context_forward().

See the documentation of gtk_source_search_context_forward() for more details.

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

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

Parameters

search

a GtkSourceSearchContext.

 

iter

start of search.

 

cancellable

a GCancellable, or NULL.

[nullable]

callback

a GAsyncReadyCallback to call when the operation is finished.

 

user_data

the data to pass to the callback function.

 

Since: 3.10


gtk_source_search_context_forward_finish ()

gboolean
gtk_source_search_context_forward_finish
                               (GtkSourceSearchContext *search,
                                GAsyncResult *result,
                                GtkTextIter *match_start,
                                GtkTextIter *match_end,
                                gboolean *has_wrapped_around,
                                GError **error);

Finishes a forward search started with gtk_source_search_context_forward_async().

See the documentation of gtk_source_search_context_forward() for more details.

Parameters

search

a GtkSourceSearchContext.

 

result

a GAsyncResult.

 

match_start

return location for start of match, or NULL.

[out][optional]

match_end

return location for end of match, or NULL.

[out][optional]

has_wrapped_around

return location to know whether the search has wrapped around, or NULL.

[out][optional]

error

a GError, or NULL.

 

Returns

whether a match was found.

Since: 4.0


gtk_source_search_context_backward ()

gboolean
gtk_source_search_context_backward (GtkSourceSearchContext *search,
                                    const GtkTextIter *iter,
                                    GtkTextIter *match_start,
                                    GtkTextIter *match_end,
                                    gboolean *has_wrapped_around);

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

search

a GtkSourceSearchContext.

 

iter

start of search.

 

match_start

return location for start of match, or NULL.

[out][optional]

match_end

return location for end of match, or NULL.

[out][optional]

has_wrapped_around

return location to know whether the search has wrapped around, or NULL.

[out][optional]

Returns

whether a match was found.

Since: 4.0


gtk_source_search_context_backward_async ()

void
gtk_source_search_context_backward_async
                               (GtkSourceSearchContext *search,
                                const GtkTextIter *iter,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

The asynchronous version of gtk_source_search_context_backward().

See the documentation of gtk_source_search_context_backward() for more details.

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

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

Parameters

search

a GtkSourceSearchContext.

 

iter

start of search.

 

cancellable

a GCancellable, or NULL.

[nullable]

callback

a GAsyncReadyCallback to call when the operation is finished.

 

user_data

the data to pass to the callback function.

 

Since: 3.10


gtk_source_search_context_backward_finish ()

gboolean
gtk_source_search_context_backward_finish
                               (GtkSourceSearchContext *search,
                                GAsyncResult *result,
                                GtkTextIter *match_start,
                                GtkTextIter *match_end,
                                gboolean *has_wrapped_around,
                                GError **error);

Finishes a backward search started with gtk_source_search_context_backward_async().

See the documentation of gtk_source_search_context_backward() for more details.

Parameters

search

a GtkSourceSearchContext.

 

result

a GAsyncResult.

 

match_start

return location for start of match, or NULL.

[out][optional]

match_end

return location for end of match, or NULL.

[out][optional]

has_wrapped_around

return location to know whether the search has wrapped around, or NULL.

[out][optional]

error

a GError, or NULL.

 

Returns

whether a match was found.

Since: 4.0


gtk_source_search_context_replace ()

gboolean
gtk_source_search_context_replace (GtkSourceSearchContext *search,
                                   GtkTextIter *match_start,
                                   GtkTextIter *match_end,
                                   const gchar *replace,
                                   gint replace_length,
                                   GError **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 g_regex_check_replacement(). The replace text can contain backreferences; read the g_regex_replace() documentation for more details.

Parameters

search

a GtkSourceSearchContext.

 

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.

 

error

location to a GError, or NULL to ignore errors.

 

Returns

whether the match has been replaced.

Since: 4.0


gtk_source_search_context_replace_all ()

guint
gtk_source_search_context_replace_all (GtkSourceSearchContext *search,
                                       const gchar *replace,
                                       gint replace_length,
                                       GError **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 g_regex_check_replacement(). The replace text can contain backreferences; read the g_regex_replace() documentation for more details.

Parameters

search

a GtkSourceSearchContext.

 

replace

the replacement text.

 

replace_length

the length of replace in bytes, or -1.

 

error

location to a GError, or NULL to ignore errors.

 

Returns

the number of replaced matches.

Since: 3.10


gtk_source_search_context_get_regex_error ()

GError *
gtk_source_search_context_get_regex_error
                               (GtkSourceSearchContext *search);

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

Free the return value with g_error_free().

Parameters

search

a GtkSourceSearchContext.

 

Returns

the GError, or NULL if the pattern is valid.

[nullable]

Since: 3.10

Types and Values

GtkSourceSearchContext

typedef struct _GtkSourceSearchContext GtkSourceSearchContext;

Property Details

The “buffer” property

  “buffer”                   GtkSourceBuffer *

The GtkSourceBuffer associated to the search context.

Flags: Read / Write / Construct Only

Since: 3.10


The “highlight” property

  “highlight”                gboolean

Highlight the search occurrences.

Flags: Read / Write / Construct

Default value: TRUE

Since: 3.10


The “match-style” property

  “match-style”              GtkSourceStyle *

A GtkSourceStyle, or NULL for theme's scheme default style.

Flags: Read / Write / Construct

Since: 3.16


The “occurrences-count” property

  “occurrences-count”        gint

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.

Flags: Read

Allowed values: >= -1

Default value: 0

Since: 3.10


The “regex-error” property

  “regex-error”              gpointer

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

Free with g_error_free().

Flags: Read

Since: 3.10


The “settings” property

  “settings”                 GtkSourceSearchSettings *

The GtkSourceSearchSettings associated to the search context.

This property is construct-only since version 4.0.

Flags: Read / Write / Construct Only

Since: 3.10