GtkSourceSearchContext

GtkSourceSearchContext — The context of a search

Synopsis

#include <gtksourceview/gtksource.h>

                    GtkSourceSearchContext;
GtkSourceSearchContext * gtk_source_search_context_new  (GtkSourceBuffer *buffer,
                                                         GtkSourceSearchSettings *settings);
GtkSourceBuffer *   gtk_source_search_context_get_buffer
                                                        (GtkSourceSearchContext *search);
GtkSourceSearchSettings * gtk_source_search_context_get_settings
                                                        (GtkSourceSearchContext *search);
void                gtk_source_search_context_set_settings
                                                        (GtkSourceSearchContext *search,
                                                         GtkSourceSearchSettings *settings);
gboolean            gtk_source_search_context_get_highlight
                                                        (GtkSourceSearchContext *search);
void                gtk_source_search_context_set_highlight
                                                        (GtkSourceSearchContext *search,
                                                         gboolean highlight);
gint                gtk_source_search_context_get_occurrences_count
                                                        (GtkSourceSearchContext *search);
gint                gtk_source_search_context_get_occurrence_position
                                                        (GtkSourceSearchContext *search,
                                                         const GtkTextIter *match_start,
                                                         const GtkTextIter *match_end);
gboolean            gtk_source_search_context_forward   (GtkSourceSearchContext *search,
                                                         const GtkTextIter *iter,
                                                         GtkTextIter *match_start,
                                                         GtkTextIter *match_end);
void                gtk_source_search_context_forward_async
                                                        (GtkSourceSearchContext *search,
                                                         const GtkTextIter *iter,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            gtk_source_search_context_forward_finish
                                                        (GtkSourceSearchContext *search,
                                                         GAsyncResult *result,
                                                         GtkTextIter *match_start,
                                                         GtkTextIter *match_end,
                                                         GError **error);
gboolean            gtk_source_search_context_backward  (GtkSourceSearchContext *search,
                                                         const GtkTextIter *iter,
                                                         GtkTextIter *match_start,
                                                         GtkTextIter *match_end);
void                gtk_source_search_context_backward_async
                                                        (GtkSourceSearchContext *search,
                                                         const GtkTextIter *iter,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            gtk_source_search_context_backward_finish
                                                        (GtkSourceSearchContext *search,
                                                         GAsyncResult *result,
                                                         GtkTextIter *match_start,
                                                         GtkTextIter *match_end,
                                                         GError **error);
gboolean            gtk_source_search_context_replace   (GtkSourceSearchContext *search,
                                                         const GtkTextIter *match_start,
                                                         const GtkTextIter *match_end,
                                                         const gchar *replace,
                                                         gint replace_length,
                                                         GError **error);
guint               gtk_source_search_context_replace_all
                                                        (GtkSourceSearchContext *search,
                                                         const gchar *replace,
                                                         gint replace_length,
                                                         GError **error);
GError *            gtk_source_search_context_get_regex_error
                                                        (GtkSourceSearchContext *search);

Object Hierarchy

  GObject
   +----GtkSourceSearchContext

Properties

  "buffer"                   GtkSourceBuffer*      : Read / Write / Construct Only
  "highlight"                gboolean              : Read / Write / Construct
  "occurrences-count"        gint                  : Read
  "regex-error"              gpointer              : Read
  "settings"                 GtkSourceSearchSettings*  : 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, that can be shared between several GtkSourceSearchContexts. A buffer can contain several search contexts at the same time, but at most one search context per buffer can highlight its search occurrences.

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 to several buffers.

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.

Details

GtkSourceSearchContext

typedef struct _GtkSourceSearchContext GtkSourceSearchContext;

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

buffer :

 a GtkSourceBuffer.

settings :

 a GtkSourceSearchSettings, or NULL. [allow-none]

Returns :

 a new search context.

Since 3.10

gtk_source_search_context_get_buffer ()

GtkSourceBuffer *   gtk_source_search_context_get_buffer
                                                        (GtkSourceSearchContext *search);

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);

search :

 a GtkSourceSearchContext.

Returns :

 the search settings. [transfer none]

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.

search :

 a GtkSourceSearchContext.

settings :

 the new GtkSourceSearchSettings, or NULL. [allow-none]

Since 3.10

gtk_source_search_context_get_highlight ()

gboolean            gtk_source_search_context_get_highlight
                                                        (GtkSourceSearchContext *search);

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.

search :

 a GtkSourceSearchContext.

highlight :

 the setting.

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.

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.

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);

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.

search :

 a GtkSourceSearchContext.

iter :

 start of search.

match_start :

 return location for start of match, or NULL. [out][allow-none]

match_end :

 return location for end of match, or NULL. [out][allow-none]

Returns :

 whether a match was found.

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.

search :

 a GtkSourceSearchContext.

iter :

 start of search.

cancellable :

 a GCancellable, or NULL. [allow-none]

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,
                                                         GError **error);

Finishes a forward search started with gtk_source_search_context_forward_async().

search :

 a GtkSourceSearchContext.

result :

 a GAsyncResult.

match_start :

 return location for start of match, or NULL. [out][allow-none]

match_end :

 return location for end of match, or NULL. [out][allow-none]

error :

 a GError, or NULL.

Returns :

 whether a match was found.

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.

search :

 a GtkSourceSearchContext.

iter :

 start of search.

match_start :

 return location for start of match, or NULL. [out][allow-none]

match_end :

 return location for end of match, or NULL. [out][allow-none]

Returns :

 whether a match was found.

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.

search :

 a GtkSourceSearchContext.

iter :

 start of search.

cancellable :

 a GCancellable, or NULL. [allow-none]

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,
                                                         GError **error);

Finishes a backward search started with gtk_source_search_context_backward_async().

search :

 a GtkSourceSearchContext.

result :

 a GAsyncResult.

match_start :

 return location for start of match, or NULL. [out][allow-none]

match_end :

 return location for end of match, or NULL. [out][allow-none]

error :

 a GError, or NULL.

Returns :

 whether a match was found.

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.

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

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

search :

 a GtkSourceSearchContext.

Returns :

 the GError, or NULL if the pattern is valid.

Since 3.10

Property Details

The "buffer" property

  "buffer"                   GtkSourceBuffer*      : Read / Write / Construct Only

The GtkSourceBuffer associated to the search context.

Since 3.10

The "highlight" property

  "highlight"                gboolean              : Read / Write / Construct

Highlight the search occurrences.

Default value: TRUE

Since 3.10

The "occurrences-count" property

  "occurrences-count"        gint                  : Read

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.

Allowed values: >= -1

Default value: 0

Since 3.10

The "regex-error" property

  "regex-error"              gpointer              : Read

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

Since 3.10

The "settings" property

  "settings"                 GtkSourceSearchSettings*  : Read / Write / Construct

The GtkSourceSearchSettings associated to the search context.

Since 3.10

See Also

GtkSourceBuffer, GtkSourceSearchSettings
Generated by GTK-Doc V1.19.1