GI.GtkSource.Objects.SearchContext

Search context.

A GtkSourceSearchContext is used for the search and replace in a [classbuffer]. The search settings are represented by a [classsearchSettings] 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 [methodsearchContext.get_occurrences_count]. To know the position of a certain match, use [methodsearchContext.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 [methodsearchContext.forward] or [methodsearchContext.forward_async] for the asynchronous version. The backward search is done similarly. To replace a search match, or all matches, use [methodsearchContext.replace] and [methodsearchContext.replace_all].

The search occurrences are highlighted by default. To disable it, use [methodsearchContext.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 [methodsearchContext.set_match_style] to specify the [classstyle] to apply on search matches.

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

Exported types

newtype SearchContext

Memory-managed wrapper type.

Constructors

SearchContext (ManagedPtr SearchContext)

Instances

Eq SearchContext

Defined in GI.GtkSource.Objects.SearchContext

Methods

(==) :: SearchContext -> SearchContext -> Bool

(/=) :: SearchContext -> SearchContext -> Bool

GObject SearchContext

Defined in GI.GtkSource.Objects.SearchContext

ManagedPtrNewtype SearchContext

Defined in GI.GtkSource.Objects.SearchContext

Methods

toManagedPtr :: SearchContext -> ManagedPtr SearchContext

TypedObject SearchContext

Defined in GI.GtkSource.Objects.SearchContext

Methods

glibType :: IO GType

HasParentTypes SearchContext

Defined in GI.GtkSource.Objects.SearchContext

IsGValue (Maybe SearchContext)

Convert SearchContext to and from GValue. See toGValue and fromGValue.

Defined in GI.GtkSource.Objects.SearchContext

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe SearchContext -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe SearchContext)

type ParentTypes SearchContext

Defined in GI.GtkSource.Objects.SearchContext

type ParentTypes SearchContext = '[Object]

class (GObject o, IsDescendantOf SearchContext o) => IsSearchContext o

Type class for types which can be safely cast to SearchContext, for instance with toSearchContext.

Instances

(GObject o, IsDescendantOf SearchContext o) => IsSearchContext o

Defined in GI.GtkSource.Objects.SearchContext

toSearchContext :: (MonadIO m, IsSearchContext o) => o -> m SearchContext

Cast to SearchContext, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

backward, backwardAsync, backwardFinish, bindProperty, bindPropertyFull, forceFloating, forward, forwardAsync, forwardFinish, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, replace, replaceAll, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

Getters

getBuffer, getData, getHighlight, getMatchStyle, getOccurrencePosition, getOccurrencesCount, getProperty, getQdata, getRegexError, getSettings.

Setters

setData, setDataFull, setHighlight, setMatchStyle, setProperty.

backward

searchContextBackward

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> TextIter

iter: start of search.

-> m (Bool, TextIter, TextIter, Bool)

Returns: whether a match was found.

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 [propertysearchSettings:wrap-around] property is False, this function doesn't try to wrap around.

The hasWrappedAround out parameter is set independently of whether a match is found. So if this function returns False, hasWrappedAround will have the same value as the [propertysearchSettings:wrap-around] property.

backwardAsync

searchContextBackwardAsync

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a, IsCancellable b)

=> a

search: a SearchContext.

-> TextIter

iter: start of search.

-> Maybe b

cancellable: a Cancellable, or Nothing.

-> Maybe AsyncReadyCallback

callback: a AsyncReadyCallback to call when the operation is finished.

-> m ()

The asynchronous version of [methodsearchContext.backward].

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

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

backwardFinish

searchContextBackwardFinish

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a, IsAsyncResult b)

=> a

search: a SearchContext.

-> b

result: a AsyncResult.

-> m (TextIter, TextIter, Bool)

(Can throw GError)

Finishes a backward search started with [methodsearchContext.backward_async].

See the documentation of [methodsearchContext.backward] for more details.

forward

searchContextForward

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> TextIter

iter: start of search.

-> m (Bool, TextIter, TextIter, Bool)

Returns: whether a match was found.

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 [propertysearchSettings:wrap-around] property is False, this function doesn't try to wrap around.

The hasWrappedAround out parameter is set independently of whether a match is found. So if this function returns False, hasWrappedAround will have the same value as the [propertysearchSettings:wrap-around] property.

forwardAsync

searchContextForwardAsync

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a, IsCancellable b)

=> a

search: a SearchContext.

-> TextIter

iter: start of search.

-> Maybe b

cancellable: a Cancellable, or Nothing.

-> Maybe AsyncReadyCallback

callback: a AsyncReadyCallback to call when the operation is finished.

-> m ()

The asynchronous version of [methodsearchContext.forward].

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

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

forwardFinish

searchContextForwardFinish

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a, IsAsyncResult b)

=> a

search: a SearchContext.

-> b

result: a AsyncResult.

-> m (TextIter, TextIter, Bool)

(Can throw GError)

Finishes a forward search started with [methodsearchContext.forward_async].

See the documentation of [methodsearchContext.forward] for more details.

getBuffer

searchContextGetBuffer

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> m Buffer

Returns: the associated buffer.

No description available in the introspection data.

getHighlight

searchContextGetHighlight

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> m Bool

Returns: whether to highlight the search occurrences.

No description available in the introspection data.

getMatchStyle

searchContextGetMatchStyle

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> m Style

Returns: the Style to apply on search matches.

No description available in the introspection data.

getOccurrencePosition

searchContextGetOccurrencePosition

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> TextIter

matchStart: the start of the occurrence.

-> TextIter

matchEnd: the end of the occurrence.

-> m Int32

Returns: the position of the search occurrence. The first occurrence has the position 1 (not 0). Returns 0 if matchStart and matchEnd don't delimit an occurrence. Returns -1 if the position is not yet known.

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 matchStart and matchEnd don't delimit an occurrence.

getOccurrencesCount

searchContextGetOccurrencesCount

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> m Int32

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

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.

getRegexError

searchContextGetRegexError

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> m (Maybe GError)

Returns: the GError, or Nothing if the pattern is valid.

Regular expression patterns must follow certain rules. If [propertysearchSettings:search-text] breaks a rule, the error can be retrieved with this function.

The error domain is [errorgLib.RegexError].

Free the return value with errorFree.

getSettings

searchContextGetSettings

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> m SearchSettings

Returns: the search settings.

No description available in the introspection data.

new

searchContextNew

Arguments

:: (HasCallStack, MonadIO m, IsBuffer a, IsSearchSettings b)

=> a

buffer: a Buffer.

-> Maybe b

settings: a SearchSettings, or Nothing.

-> m SearchContext

Returns: a new search context.

Creates a new search context, associated with buffer, and customized with settings.

If settings is Nothing, a new [classsearchSettings] object will be created, that you can retrieve with [methodsearchContext.get_settings].

replace

searchContextReplace

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> TextIter

matchStart: the start of the match to replace.

-> TextIter

matchEnd: the end of the match to replace.

-> Text

replace: the replacement text.

-> Int32

replaceLength: the length of replace in bytes, or -1.

-> m ()

(Can throw GError)

Replaces a search match by another text. If matchStart and matchEnd doesn't correspond to a search match, False is returned.

matchStart and matchEnd iters are revalidated to point to the replacement text boundaries.

For a regular expression replacement, you can check if replace is valid by calling [funcgLib.Regex.check_replacement]. The replace text can contain backreferences.

replaceAll

searchContextReplaceAll

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> Text

replace: the replacement text.

-> Int32

replaceLength: the length of replace in bytes, or -1.

-> m Word32

Returns: the number of replaced matches. (Can throw GError)

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 [funcgLib.Regex.check_replacement]. The replace text can contain backreferences.

setHighlight

searchContextSetHighlight

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a)

=> a

search: a SearchContext.

-> Bool

highlight: the setting.

-> m ()

Enables or disables the search occurrences highlighting.

setMatchStyle

searchContextSetMatchStyle

Arguments

:: (HasCallStack, MonadIO m, IsSearchContext a, IsStyle b)

=> a

search: a SearchContext.

-> Maybe b

matchStyle: a Style, or Nothing.

-> m ()

Set the style to apply on search matches.

If matchStyle is Nothing, default theme's scheme 'match-style' will be used. To enable or disable the search highlighting, use [methodsearchContext.set_highlight].

Properties

buffer

The [classbuffer] associated to the search context.

constructSearchContextBuffer :: (IsSearchContext o, MonadIO m, IsBuffer a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “buffer” property. This is rarely needed directly, but it is used by new.

getSearchContextBuffer :: (MonadIO m, IsSearchContext o) => o -> m Buffer

Get the value of the “buffer” property. When overloading is enabled, this is equivalent to

get searchContext #buffer

highlight

Highlight the search occurrences.

constructSearchContextHighlight :: (IsSearchContext o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “highlight” property. This is rarely needed directly, but it is used by new.

getSearchContextHighlight :: (MonadIO m, IsSearchContext o) => o -> m Bool

Get the value of the “highlight” property. When overloading is enabled, this is equivalent to

get searchContext #highlight

setSearchContextHighlight :: (MonadIO m, IsSearchContext o) => o -> Bool -> m ()

Set the value of the “highlight” property. When overloading is enabled, this is equivalent to

set searchContext [ #highlight := value ]

matchStyle

A [classstyle], or Nothing for theme's scheme default style.

clearSearchContextMatchStyle :: (MonadIO m, IsSearchContext o) => o -> m ()

Set the value of the “match-style” property to Nothing. When overloading is enabled, this is equivalent to

clear #matchStyle

constructSearchContextMatchStyle :: (IsSearchContext o, MonadIO m, IsStyle a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “match-style” property. This is rarely needed directly, but it is used by new.

getSearchContextMatchStyle :: (MonadIO m, IsSearchContext o) => o -> m Style

Get the value of the “match-style” property. When overloading is enabled, this is equivalent to

get searchContext #matchStyle

setSearchContextMatchStyle :: (MonadIO m, IsSearchContext o, IsStyle a) => o -> a -> m ()

Set the value of the “match-style” property. When overloading is enabled, this is equivalent to

set searchContext [ #matchStyle := value ]

occurrencesCount

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.

getSearchContextOccurrencesCount :: (MonadIO m, IsSearchContext o) => o -> m Int32

Get the value of the “occurrences-count” property. When overloading is enabled, this is equivalent to

get searchContext #occurrencesCount

regexError

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

Free with errorFree.

getSearchContextRegexError :: (MonadIO m, IsSearchContext o) => o -> m (Maybe GError)

Get the value of the “regex-error” property. When overloading is enabled, this is equivalent to

get searchContext #regexError

settings

The [classsearchSettings] associated to the search context.

This property is construct-only since version 4.0.

constructSearchContextSettings :: (IsSearchContext o, MonadIO m, IsSearchSettings a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “settings” property. This is rarely needed directly, but it is used by new.

getSearchContextSettings :: (MonadIO m, IsSearchContext o) => o -> m SearchSettings

Get the value of the “settings” property. When overloading is enabled, this is equivalent to

get searchContext #settings