Abstract base class for filters which collect locator results. More...

#include <qgslocatorfilter.h>

Inheritance diagram for QgsLocatorFilter:

Public Types
enum	Flag { FlagFast = 1 << 1 }
	Flags for locator behavior. More...

typedef QFlags< Flag >	Flags

enum	Priority { Highest , High , Medium , Low , Lowest }
	Filter priority. Controls the order of results in the locator. More...

Signals
void	finished ()
	Emitted when the filter finishes fetching results.

void	resultFetched (const QgsLocatorResult &result)
	Should be emitted by filters whenever they encounter a matching result during within their fetchResults() implementation.

Public Member Functions
	QgsLocatorFilter (QObject *parent=nullptr)
	Constructor for QgsLocatorFilter.

QString	activePrefix () const
	Returns the prefix in use in the locator is entered.

virtual void	clearPreviousResults ()
	This method will be called on main thread on the original filter (not a clone) before fetching results or before triggering a result to clear any change made by a former call to triggerResult.

virtual QgsLocatorFilter *	clone () const =0
	Creates a clone of the filter.

virtual QString	description () const
	Returns a translated, description for the filter.

virtual QString	displayName () const =0
	Returns a translated, user-friendly name for the filter.

bool	enabled () const
	Returns `true` if the filter is enabled.

virtual void	fetchResults (const QString &string, const QgsLocatorContext &context, QgsFeedback *feedback)=0
	Retrieves the filter results for a specified search string.

int	fetchResultsDelay () const
	Returns the delay (in milliseconds) for the filter to wait prior to fetching results.

virtual QgsLocatorFilter::Flags	flags () const
	Returns flags which specify the filter's behavior.

virtual bool	hasConfigWidget () const
	Should return `true` if the filter has a configuration widget.

void	logMessage (const QString &message, Qgis::MessageLevel level=Qgis::MessageLevel::Info)
	Logs a message to the log panel.

virtual QString	name () const =0
	Returns the unique name for the filter.

virtual void	openConfigWidget (QWidget *parent=nullptr)
	Opens the configuration widget for the filter (if it has one), with the specified parent widget.

virtual QString	prefix () const
	Returns the search prefix character(s) for this filter.

virtual QStringList	prepare (const QString &string, const QgsLocatorContext &context)
	Prepares the filter instance for an upcoming search for the specified string.

virtual Priority	priority () const
	Returns the priority for the filter, which controls how results are ordered in the locator.

virtual void	resultDeselected (const QgsLocatorResult &result)
	This is called when a result is deselected.

virtual void	resultSelected (const QgsLocatorResult &result)
	This is called when the result is selected by the user.

void	setActivePrefix (const QString &activePrefix)
	Sets the prefix as being used by the locator.

void	setEnabled (bool enabled)
	Sets whether the filter is enabled.

void	setFetchResultsDelay (int delay)
	Sets a delay (in milliseconds) for the filter to wait prior to fetching results.

void	setUseWithoutPrefix (bool useWithoutPrefix)
	Sets whether the filter should be used when no prefix is entered.

virtual void	triggerResult (const QgsLocatorResult &result)=0
	Triggers a filter result from this filter.

virtual void	triggerResultFromAction (const QgsLocatorResult &result, const int actionId)
	Triggers a filter result from this filter for an entry in the context menu.

bool	useWithoutPrefix () const
	Returns `true` if the filter should be used when no prefix is entered.

Static Public Member Functions
static double	fuzzyScore (const QString &candidate, const QString &search)
	Tests a candidate string to see how likely it is a match for a specified search string.

static bool	stringMatches (const QString &candidate, const QString &search)
	Tests a candidate string to see if it should be considered a match for a specified search string.

Detailed Description

Abstract base class for filters which collect locator results.

Note: If the configuration of the filter is changed outside of the main application settings, one needs to invalidate current results of the locator widget:

See also: QgisInterface::invalidateLocatorResults

Definition at line 175 of file qgslocatorfilter.h.

Member Typedef Documentation

◆ Flags

typedef QFlags< Flag > QgsLocatorFilter::Flags

Definition at line 197 of file qgslocatorfilter.h.

Member Enumeration Documentation

◆ Flag

enum QgsLocatorFilter::Flag

Flags for locator behavior.

Enumerator
FlagFast	Filter finds results quickly and can be safely run in the main thread.

Definition at line 193 of file qgslocatorfilter.h.

◆ Priority

enum QgsLocatorFilter::Priority

Filter priority. Controls the order of results in the locator.

Enumerator
Highest	Highest priority.
High	High priority.
Medium	Medium priority.
Low	Low priority.
Lowest	Lowest priority.

Definition at line 182 of file qgslocatorfilter.h.

Constructor & Destructor Documentation

◆ QgsLocatorFilter()

QgsLocatorFilter::QgsLocatorFilter ( QObject * parent = nullptr )

Constructor for QgsLocatorFilter.

Definition at line 27 of file qgslocatorfilter.cpp.

Member Function Documentation

◆ activePrefix()

QString QgsLocatorFilter::activePrefix ( ) const

Returns the prefix in use in the locator is entered.

See also: setActivePrefix()

Since: QGIS 3.2

Definition at line 83 of file qgslocatorfilter.cpp.

◆ clearPreviousResults()

virtual void QgsLocatorFilter::clearPreviousResults ( )

inlinevirtual

This method will be called on main thread on the original filter (not a clone) before fetching results or before triggering a result to clear any change made by a former call to triggerResult.

For instance, this can be used to remove any on-canvas rubber bands which have been created when a previous search result was triggered.

Since: QGIS 3.2

Definition at line 321 of file qgslocatorfilter.h.

◆ clone()

virtual QgsLocatorFilter * QgsLocatorFilter::clone ( ) const

pure virtual

Creates a clone of the filter.

New requests are always executed in a clone of the original filter.

◆ description()

virtual QString QgsLocatorFilter::description ( ) const

inlinevirtual

Returns a translated, description for the filter.

Since: QGIS 3.20

Definition at line 227 of file qgslocatorfilter.h.

◆ displayName()

virtual QString QgsLocatorFilter::displayName ( ) const

pure virtual

Returns a translated, user-friendly name for the filter.

See also: name()

◆ enabled()

bool QgsLocatorFilter::enabled ( ) const

Returns true if the filter is enabled.

See also: setEnabled()

Definition at line 53 of file qgslocatorfilter.cpp.

◆ fetchResults()

virtual void QgsLocatorFilter::fetchResults	(	const QString &	string,
		const QgsLocatorContext &	context,
		QgsFeedback *	feedback
	)

pure virtual

Retrieves the filter results for a specified search string.

The context argument encapsulates the context relating to the search (such as a map extent to prioritize).

Implementations of fetchResults() should emit the resultFetched() signal whenever they encounter a matching result.

Subclasses should periodically check the feedback object to determine whether the query has been canceled. If so, the subclass should return from this method as soon as possible.

This will be called from a background thread unless flags() returns the QgsLocatorFilter::FlagFast flag.

◆ fetchResultsDelay()

int QgsLocatorFilter::fetchResultsDelay ( ) const

inline

Returns the delay (in milliseconds) for the filter to wait prior to fetching results.

See also: setFetchResultsDelay()

Since: QGIS 3.18

Definition at line 407 of file qgslocatorfilter.h.

◆ finished

void QgsLocatorFilter::finished ( )

signal

Emitted when the filter finishes fetching results.

◆ flags()

QgsLocatorFilter::Flags QgsLocatorFilter::flags ( ) const

virtual

Returns flags which specify the filter's behavior.

Definition at line 32 of file qgslocatorfilter.cpp.

◆ fuzzyScore()

double QgsLocatorFilter::fuzzyScore	(	const QString &	candidate,
		const QString &	search
	)

static

Tests a candidate string to see how likely it is a match for a specified search string.

Since: QGIS 3.14

Definition at line 48 of file qgslocatorfilter.cpp.

◆ hasConfigWidget()

bool QgsLocatorFilter::hasConfigWidget ( ) const

virtual

Should return true if the filter has a configuration widget.

See also: openConfigWidget()

Definition at line 63 of file qgslocatorfilter.cpp.

◆ logMessage()

void QgsLocatorFilter::logMessage	(	const QString &	message,
		Qgis::MessageLevel	level = `Qgis::MessageLevel::Info`
	)

Logs a message to the log panel.

Warning: in Python, do not use print() method as it might result in crashes since fetching results does not happen in the main thread.

Since: QGIS 3.2

Definition at line 99 of file qgslocatorfilter.cpp.

◆ name()

virtual QString QgsLocatorFilter::name ( ) const

pure virtual

Returns the unique name for the filter.

This should be an untranslated string identifying the filter.

See also: displayName()

◆ openConfigWidget()

void QgsLocatorFilter::openConfigWidget ( QWidget * parent = nullptr )

virtual

Opens the configuration widget for the filter (if it has one), with the specified parent widget.

The base class implementation does nothing. Subclasses can override this to show their own custom configuration widget.

Note: hasConfigWidget() must return true to indicate that the filter supports configuration.

Definition at line 68 of file qgslocatorfilter.cpp.

◆ prefix()

virtual QString QgsLocatorFilter::prefix ( ) const

inlinevirtual

Returns the search prefix character(s) for this filter.

Prefix a search with these characters will restrict the locator search to only include results from this filter.

Note: Plugins are not permitted to utilize prefixes with < 3 characters, as these are reserved for core QGIS functions. If a plugin registers a filter with a prefix shorter than 3 characters then the prefix will be ignored.; Prefixes might be overridden by user preferences.

See also: activePrefix()

Definition at line 251 of file qgslocatorfilter.h.

◆ prepare()

virtual QStringList QgsLocatorFilter::prepare	(	const QString &	string,
		const QgsLocatorContext &	context
	)

inlinevirtual

Prepares the filter instance for an upcoming search for the specified string.

This method is always called from the main thread, and individual filter subclasses should perform whatever tasks are required in order to allow a subsequent search to safely execute on a background thread. The method returns an autocompletion list

Definition at line 260 of file qgslocatorfilter.h.

◆ priority()

virtual Priority QgsLocatorFilter::priority ( ) const

inlinevirtual

Returns the priority for the filter, which controls how results are ordered in the locator.

Definition at line 238 of file qgslocatorfilter.h.

◆ resultDeselected()

virtual void QgsLocatorFilter::resultDeselected ( const QgsLocatorResult & result )

inlinevirtual

This is called when a result is deselected.

The filter subclass can implement logic here.

Since: QGIS 3.40

Definition at line 303 of file qgslocatorfilter.h.

◆ resultFetched

void QgsLocatorFilter::resultFetched ( const QgsLocatorResult & result )

signal

Should be emitted by filters whenever they encounter a matching result during within their fetchResults() implementation.

◆ resultSelected()

virtual void QgsLocatorFilter::resultSelected ( const QgsLocatorResult & result )

inlinevirtual

This is called when the result is selected by the user.

The filter subclass can implement logic here.

Since: QGIS 3.40

Definition at line 295 of file qgslocatorfilter.h.

◆ setActivePrefix()

void QgsLocatorFilter::setActivePrefix ( const QString & activePrefix )

Sets the prefix as being used by the locator.

See also: activePrefix()

Note: If activePrefix is empty, no prefix is used. If activePrefix is NULL, the default prefix is used.

Since: QGIS 3.2

Definition at line 94 of file qgslocatorfilter.cpp.

◆ setEnabled()

void QgsLocatorFilter::setEnabled ( bool enabled )

Sets whether the filter is enabled.

See also: enabled()

Definition at line 58 of file qgslocatorfilter.cpp.

◆ setFetchResultsDelay()

void QgsLocatorFilter::setFetchResultsDelay ( int delay )

inline

Sets a delay (in milliseconds) for the filter to wait prior to fetching results.

See also: fetchResultsDelay()

Note: If the locator filter has a FastFlag, this value is ignored.

Since: QGIS 3.18

Definition at line 415 of file qgslocatorfilter.h.

◆ setUseWithoutPrefix()

void QgsLocatorFilter::setUseWithoutPrefix ( bool useWithoutPrefix )

Sets whether the filter should be used when no prefix is entered.

See also: useWithoutPrefix()

Definition at line 78 of file qgslocatorfilter.cpp.

◆ stringMatches()

bool QgsLocatorFilter::stringMatches	(	const QString &	candidate,
		const QString &	search
	)

static

Tests a candidate string to see if it should be considered a match for a specified search string.

Filter subclasses should use this method when comparing strings instead of directly using QString::contains() or Python 'in' checks.

Definition at line 43 of file qgslocatorfilter.cpp.

◆ triggerResult()

virtual void QgsLocatorFilter::triggerResult ( const QgsLocatorResult & result )

pure virtual

Triggers a filter result from this filter.

This is called when one of the results obtained by a call to fetchResults() is triggered by a user. The filter subclass must implement logic here to perform the desired operation for the search result. E.g. a file search filter would open file associated with the triggered result.

◆ triggerResultFromAction()

void QgsLocatorFilter::triggerResultFromAction	(	const QgsLocatorResult &	result,
		const int	actionId
	)

virtual

Triggers a filter result from this filter for an entry in the context menu.

The entry is identified by its actionId as specified in the result of this filter.

See also: triggerResult()

Since: QGIS 3.6

Definition at line 37 of file qgslocatorfilter.cpp.

◆ useWithoutPrefix()

bool QgsLocatorFilter::useWithoutPrefix ( ) const

Returns true if the filter should be used when no prefix is entered.

See also: setUseWithoutPrefix()

Definition at line 73 of file qgslocatorfilter.cpp.

The documentation for this class was generated from the following files:

/build/qgis-3.41.0+git20241214+cea29feecf2+99sid/src/core/locator/qgslocatorfilter.h
/build/qgis-3.41.0+git20241214+cea29feecf2+99sid/src/core/locator/qgslocatorfilter.cpp

Public Types

Signals

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Flags

Member Enumeration Documentation

◆ Flag

◆ Priority

Constructor & Destructor Documentation

◆ QgsLocatorFilter()

Member Function Documentation

◆ activePrefix()

◆ clearPreviousResults()

◆ clone()

◆ description()

◆ displayName()

◆ enabled()

◆ fetchResults()

◆ fetchResultsDelay()

◆ finished

◆ flags()

◆ fuzzyScore()

◆ hasConfigWidget()

◆ logMessage()

◆ name()

◆ openConfigWidget()

◆ prefix()

◆ prepare()

◆ priority()

◆ resultDeselected()

◆ resultFetched

◆ resultSelected()

◆ setActivePrefix()

◆ setEnabled()

◆ setFetchResultsDelay()

◆ setUseWithoutPrefix()

◆ stringMatches()

◆ triggerResult()

◆ triggerResultFromAction()

◆ useWithoutPrefix()