| Top |  |
 |
 |
 |
Functions
Properties
| GtkSourceBuffer * | buffer | Read / Write / Construct Only |
| gboolean | highlight | Read / Write / Construct |
| gint | occurrences-count | Read |
| gpointer | regex-error | Read |
| GtkSourceSearchSettings * | settings | Read / Write / Construct |
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. But currently, the same highlighting style is applied.
Note that the “highlight” property is in the
GtkSourceSearchContext class, not GtkSourceSearchSettings. The purpose is
to bind the appearance settings to only one buffer (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().
Since 3.10
gtk_source_search_context_get_buffer ()
GtkSourceBuffer *
gtk_source_search_context_get_buffer (GtkSourceSearchContext *search);
Since 3.10
gtk_source_search_context_get_settings ()
GtkSourceSearchSettings *
gtk_source_search_context_get_settings
(GtkSourceSearchContext *search);
Since 3.10
gtk_source_search_context_set_settings ()
void gtk_source_search_context_set_settings (GtkSourceSearchContext *search,GtkSourceSearchSettings *settings);
Associate a GtkSourceSearchSettings with the search context. If settings
is
NULL, a new one will be created.
The search context holds a reference to settings
.
Since 3.10
gtk_source_search_context_get_highlight ()
gboolean
gtk_source_search_context_get_highlight
(GtkSourceSearchContext *search);
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.
Since 3.10
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.
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.
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);
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.
Parameters
Since 3.10
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);
Asynchronous forward search. 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 |
||
iter |
start of search. |
|
cancellable |
a GCancellable, or |
[allow-none] |
callback |
a GAsyncReadyCallback to call when the operation is finished. |
|
user_data |
the data to pass to the |
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,GError **error);
Finishes a forward search started with
gtk_source_search_context_forward_async().
Parameters
search |
||
result |
a GAsyncResult. |
|
match_start |
return location for start of match, or |
[out][allow-none] |
match_end |
return location for end of match, or |
[out][allow-none] |
error |
Since 3.10
gtk_source_search_context_backward ()
gboolean gtk_source_search_context_backward (GtkSourceSearchContext *search,const GtkTextIter *iter,GtkTextIter *match_start,GtkTextIter *match_end);
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.
Parameters
Since 3.10
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);
Asynchronous backward search. 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 |
||
iter |
start of search. |
|
cancellable |
a GCancellable, or |
[allow-none] |
callback |
a GAsyncReadyCallback to call when the operation is finished. |
|
user_data |
the data to pass to the |
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,GError **error);
Finishes a backward search started with
gtk_source_search_context_backward_async().
Parameters
search |
||
result |
a GAsyncResult. |
|
match_start |
return location for start of match, or |
[out][allow-none] |
match_end |
return location for end of match, or |
[out][allow-none] |
error |
Since 3.10
gtk_source_search_context_replace ()
gboolean gtk_source_search_context_replace (GtkSourceSearchContext *search,const GtkTextIter *match_start,const 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.
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 |
||
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 |
|
error |
Since 3.10
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 |
||
replace |
the replacement text. |
|
replace_length |
the length of |
|
error |
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().
Since 3.10
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 “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
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.
Flags: Read / Write / Construct
Since 3.10