Class SearchContext

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gtksourceview.SearchContext

All Implemented Interfaces:

Proxy

@Generated("org.javagi.JavaGI")
public class SearchContext
extends GObject

Search context.

A GtkSourceSearchContext 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 getOccurrencesCount(). To know the position of a certain match, use getOccurrencePosition(TextIter, TextIter).

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(TextIter, TextIter, TextIter, Out) or forwardAsync(TextIter, Cancellable, AsyncReadyCallback) for the asynchronous version. The backward search is done similarly. To replace a search match, or all matches, use replace(TextIter, TextIter, String, int) and replaceAll(String, int).

The search occurrences are highlighted by default. To disable it, use setHighlight(boolean). 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 setMatchStyle(Style) to specify the Style to apply on search matches.

Note that the SearchContext:highlight and SearchContext:match-style properties are in the GtkSourceSearchContext 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	SearchContext.Builder<B extends SearchContext.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static class	SearchContext.SearchContextClass

Nested classes/interfaces inherited from class GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
SearchContext()	Create a new SearchContext.
SearchContext(MemorySegment address)	Create a SearchContext instance for the provided memory address.
SearchContext(Buffer buffer, @Nullable SearchSettings settings)	Creates a new search context, associated with buffer, and customized with settings.

Method Summary

Modifier and Type	Method	Description
protected SearchContext	asParent()	Return this instance as if it were its parent type.
boolean	backward(TextIter iter, @Nullable TextIter matchStart, @Nullable TextIter matchEnd, @Nullable Out<Boolean> hasWrappedAround)	Synchronous backward search.
void	backwardAsync(TextIter iter, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	The asynchronous version of backward(TextIter, TextIter, TextIter, Out).
boolean	backwardFinish(AsyncResult result, @Nullable TextIter matchStart, @Nullable TextIter matchEnd, @Nullable Out<Boolean> hasWrappedAround)	Finishes a backward search started with backwardAsync(TextIter, Cancellable, AsyncReadyCallback).
static SearchContext.Builder<? extends SearchContext.Builder>	builder()	A SearchContext.Builder object constructs a SearchContext with the specified properties.
boolean	forward(TextIter iter, @Nullable TextIter matchStart, @Nullable TextIter matchEnd, @Nullable Out<Boolean> hasWrappedAround)	Synchronous forward search.
void	forwardAsync(TextIter iter, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	The asynchronous version of forward(TextIter, TextIter, TextIter, Out).
boolean	forwardFinish(AsyncResult result, @Nullable TextIter matchStart, @Nullable TextIter matchEnd, @Nullable Out<Boolean> hasWrappedAround)	Finishes a forward search started with forwardAsync(TextIter, Cancellable, AsyncReadyCallback).
Buffer	getBuffer()
boolean	getHighlight()
@Nullable Style	getMatchStyle()
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
int	getOccurrencePosition(TextIter matchStart, TextIter matchEnd)	Gets the position of a search occurrence.
int	getOccurrencesCount()	Gets the total number of search occurrences.
@Nullable GError	getRegexError()	Regular expression patterns must follow certain rules.
SearchSettings	getSettings()
static @Nullable Type	getType()	Get the GType of the SearchContext class.
boolean	replace(TextIter matchStart, TextIter matchEnd, String replace, int replaceLength)	Replaces a search match by another text.
int	replaceAll(String replace, int replaceLength)	Replaces all search matches by another text.
void	setHighlight(boolean highlight)	Enables or disables the search occurrences highlighting.
void	setMatchStyle(@Nullable Style matchStyle)	Set the style to apply on search matches.

Methods inherited from class GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class ProxyInstance

equals, handle, hashCode

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SearchContext

public SearchContext(MemorySegment address)

Create a SearchContext instance for the provided memory address.

Parameters:

address - the memory address of the native object

SearchContext

public SearchContext(Buffer buffer,
 @Nullable SearchSettings settings)

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

If settings is null, a new SearchSettings object will be created, that you can retrieve with getSettings().

Parameters:

buffer - a GtkSourceBuffer.

settings - a GtkSourceSearchSettings, or null.

SearchContext

public SearchContext()

Create a new SearchContext.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the SearchContext class.

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected SearchContext asParent()

Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.

Overrides:

asParent in class GObject

Returns:

the instance as if it were its parent type

backward

public boolean backward(TextIter iter,
 @Nullable TextIter matchStart,
 @Nullable TextIter matchEnd,
 @Nullable Out<Boolean> hasWrappedAround)

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 SearchSettings: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 SearchSettings:wrap-around property.

Parameters:

iter - start of search.

matchStart - return location for start of match, or null.

matchEnd - return location for end of match, or null.

hasWrappedAround - return location to know whether the search has wrapped around, or null.

Returns:

whether a match was found.

backwardAsync

public void backwardAsync(TextIter iter,
 @Nullable Cancellable cancellable,
 @Nullable AsyncReadyCallback callback)

The asynchronous version of backward(TextIter, TextIter, TextIter, Out).

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

Parameters:

iter - start of search.

cancellable - a GCancellable, or null.

callback - a GAsyncReadyCallback to call when the operation is finished.

backwardFinish

public boolean backwardFinish(AsyncResult result,
 @Nullable TextIter matchStart,
 @Nullable TextIter matchEnd,
 @Nullable Out<Boolean> hasWrappedAround)
                       throws GErrorException

Finishes a backward search started with backwardAsync(TextIter, Cancellable, AsyncReadyCallback).

See the documentation of backward(TextIter, TextIter, TextIter, Out) for more details.

Parameters:

result - a GAsyncResult.

matchStart - return location for start of match, or null.

matchEnd - return location for end of match, or null.

hasWrappedAround - return location to know whether the search has wrapped around, or null.

Returns:

whether a match was found.

Throws:

GErrorException - see GError

forward

public boolean forward(TextIter iter,
 @Nullable TextIter matchStart,
 @Nullable TextIter matchEnd,
 @Nullable Out<Boolean> hasWrappedAround)

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 SearchSettings: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 SearchSettings:wrap-around property.

Parameters:

iter - start of search.

matchStart - return location for start of match, or null.

matchEnd - return location for end of match, or null.

hasWrappedAround - return location to know whether the search has wrapped around, or null.

Returns:

whether a match was found.

forwardAsync

public void forwardAsync(TextIter iter,
 @Nullable Cancellable cancellable,
 @Nullable AsyncReadyCallback callback)

The asynchronous version of forward(TextIter, TextIter, TextIter, Out).

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

Parameters:

iter - start of search.

cancellable - a GCancellable, or null.

callback - a GAsyncReadyCallback to call when the operation is finished.

forwardFinish

public boolean forwardFinish(AsyncResult result,
 @Nullable TextIter matchStart,
 @Nullable TextIter matchEnd,
 @Nullable Out<Boolean> hasWrappedAround)
                      throws GErrorException

Finishes a forward search started with forwardAsync(TextIter, Cancellable, AsyncReadyCallback).

See the documentation of forward(TextIter, TextIter, TextIter, Out) for more details.

Parameters:

result - a GAsyncResult.

matchStart - return location for start of match, or null.

matchEnd - return location for end of match, or null.

hasWrappedAround - return location to know whether the search has wrapped around, or null.

Returns:

whether a match was found.

Throws:

GErrorException - see GError

getBuffer

public Buffer getBuffer()

getHighlight

public boolean getHighlight()

getMatchStyle

public @Nullable Style getMatchStyle()

getOccurrencePosition

public int getOccurrencePosition(TextIter matchStart,
 TextIter matchEnd)

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.

Parameters:

matchStart - the start of the occurrence.

matchEnd - the end of the occurrence.

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.

getOccurrencesCount

public int getOccurrencesCount()

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.

getRegexError

public @Nullable GError getRegexError()

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

The error domain is GLib.RegexError.

Free the return value with GError#free.

Returns:

the GError, or null if the pattern is valid.

getSettings

public SearchSettings getSettings()

replace

public boolean replace(TextIter matchStart,
 TextIter matchEnd,
 String replace,
 int replaceLength)
                throws GErrorException

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 Regex#checkReplacement. The replace text can contain backreferences.

Parameters:

matchStart - the start of the match to replace.

matchEnd - the end of the match to replace.

replace - the replacement text.

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

Returns:

whether the match has been replaced.

Throws:

GErrorException - see GError

replaceAll

public int replaceAll(String replace,
 int replaceLength)
               throws GErrorException

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 Regex#checkReplacement. The replace text can contain backreferences.

Parameters:

replace - the replacement text.

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

Returns:

the number of replaced matches.

Throws:

GErrorException - see GError

setHighlight

public void setHighlight(boolean highlight)

Enables or disables the search occurrences highlighting.

Parameters:

highlight - the setting.

setMatchStyle

public void setMatchStyle(@Nullable Style matchStyle)

Set the style to apply on search matches.

If matchStyle is null, default theme's scheme 'match-style' will be used. To enable or disable the search highlighting, use setHighlight(boolean).

Parameters:

matchStyle - a GtkSourceStyle, or null.

builder

public static SearchContext.Builder<? extends SearchContext.Builder> builder()

A SearchContext.Builder object constructs a SearchContext with the specified properties. Use the various set...() methods to set properties, and finish construction with SearchContext.Builder.build().

Returns:

the builder object