Handles the management of QgsLocatorFilter objects and async collection of search results from them. More...

#include <qgslocator.h>

Inheritance diagram for QgsLocator:

Signals
void	finished ()
	Emitted when locator has finished a query, either as a result of successful completion or early cancellation.

void	foundResult (const QgsLocatorResult &result)
	Emitted whenever a filter encounters a matching result after the fetchResults() method is called.

void	searchPrepared ()
	Emitted when locator has prepared the search (.

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

	~QgsLocator () override
	Destructor for QgsLocator.

void	cancel ()
	Cancels any current running query, and blocks until query is completely canceled by all filters.

void	cancelWithoutBlocking ()
	Triggers cancellation of any current running query without blocking.

void	clearPreviousResults ()
	Will call clearPreviousResults on all filters.

QStringList	completionList () const
	Returns the list for auto completion This list is updated when preparing the search.

void	deregisterFilter (QgsLocatorFilter *filter)
	Deregisters a filter from the locator and deletes it.

void	fetchResults (const QString &string, const QgsLocatorContext &context, QgsFeedback *feedback=nullptr)
	Triggers the background fetching of filter results for a specified search string.

QList< QgsLocatorFilter * >	filters (const QString &prefix=QString())
	Returns the list of filters registered in the locator.

bool	isRunning () const
	Returns `true` if a query is currently being executed by the locator.

Q_DECL_DEPRECATED QMap< QString, QgsLocatorFilter * >	prefixedFilters () const
	Returns a map of prefix to filter, for all registered filters with valid prefixes.

void	registerFilter (QgsLocatorFilter *filter)
	Registers a filter within the locator.

Static Public Attributes
static const QList< QString >	CORE_FILTERS
	List of core filters (i.e. not plugin filters)

static const QgsSettingsEntryBool *	settingsLocatorFilterDefault = new QgsSettingsEntryBool( QStringLiteral( "default" ), sTreeLocatorFilters, false, QObject::tr( "Locator filter default value" ) )
	Settings entry locator filter default value.

static const QgsSettingsEntryBool *	settingsLocatorFilterEnabled = new QgsSettingsEntryBool( QStringLiteral( "enabled" ), sTreeLocatorFilters, true, QObject::tr( "Locator filter enabled" ) )
	Settings entry locator filter enabled.

static const QgsSettingsEntryString *	settingsLocatorFilterPrefix = new QgsSettingsEntryString( QStringLiteral( "prefix" ), sTreeLocatorFilters, QString(), QObject::tr( "Locator filter prefix" ) )
	Settings entry locator filter prefix.

static QgsSettingsTreeNamedListNode *	sTreeLocatorFilters = QgsSettingsTree::treeRoot()->createNamedListNode( QStringLiteral( "locator-filters" ) )

Detailed Description

Handles the management of QgsLocatorFilter objects and async collection of search results from them.

QgsLocator acts as both a registry for QgsLocatorFilter objects and a means of firing up asynchronous queries against these filter objects.

Filters are first registered to the locator by calling registerFilter(). Registering filters transfers their ownership to the locator object. Plugins which register filters to the locator must take care to correctly call deregisterFilter() and deregister their filter upon plugin unload to avoid crashes.

In order to trigger a search across registered filters, the fetchResults() method is called. This triggers threaded calls to QgsLocatorFilter::fetchResults() for all registered filters. As individual filters find matching results, the foundResult() signal will be triggered for each result. Callers should connect this signal to an appropriate slot designed to collect and handle these results. Since foundResult() is triggered whenever a filter encounters an individual result, it will usually be triggered many times for a single call to fetchResults().

Definition at line 60 of file qgslocator.h.

Constructor & Destructor Documentation

◆ QgsLocator()

QgsLocator::QgsLocator ( QObject * parent = nullptr )

Constructor for QgsLocator.

Definition at line 45 of file qgslocator.cpp.

◆ ~QgsLocator()

QgsLocator::~QgsLocator ( )

override

Destructor for QgsLocator.

Destruction will block while any currently running query is terminated.

Definition at line 51 of file qgslocator.cpp.

Member Function Documentation

◆ cancel()

void QgsLocator::cancel ( )

Cancels any current running query, and blocks until query is completely canceled by all filters.

See also: cancelWithoutBlocking()

Definition at line 260 of file qgslocator.cpp.

◆ cancelWithoutBlocking()

void QgsLocator::cancelWithoutBlocking ( )

Triggers cancellation of any current running query without blocking.

The query may take some time to cancel after calling this.

See also: cancel()

Definition at line 265 of file qgslocator.cpp.

◆ clearPreviousResults()

void QgsLocator::clearPreviousResults ( )

Will call clearPreviousResults on all filters.

Since: QGIS 3.2

Definition at line 276 of file qgslocator.cpp.

◆ completionList()

QStringList QgsLocator::completionList ( ) const

inline

Returns the list for auto completion This list is updated when preparing the search.

Since: QGIS 3.16

Definition at line 156 of file qgslocator.h.

◆ deregisterFilter()

void QgsLocator::deregisterFilter ( QgsLocatorFilter * filter )

Deregisters a filter from the locator and deletes it.

Calling this will block whilst any currently running query is terminated.

Plugins which register filters to the locator must take care to correctly call deregisterFilter() to deregister their filters upon plugin unload to avoid crashes.

See also: registerFilter()

Definition at line 57 of file qgslocator.cpp.

◆ fetchResults()

void QgsLocator::fetchResults	(	const QString &	string,
		const QgsLocatorContext &	context,
		QgsFeedback *	feedback = `nullptr`
	)

Triggers the background fetching of filter results for a specified search string.

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

If specified, the feedback object must exist for the lifetime of this query.

The foundResult() signal will be emitted for each individual result encountered by the registered filters.

Definition at line 134 of file qgslocator.cpp.

◆ filters()

QList< QgsLocatorFilter * > QgsLocator::filters ( const QString & prefix = QString() )

Returns the list of filters registered in the locator.

Parameters

prefix If prefix is not empty, the list returned corresponds to the filter with the given active prefix

See also: prefixedFilters()

Definition at line 64 of file qgslocator.cpp.

◆ finished

void QgsLocator::finished ( )

signal

Emitted when locator has finished a query, either as a result of successful completion or early cancellation.

◆ foundResult

void QgsLocator::foundResult ( const QgsLocatorResult & result )

signal

Emitted whenever a filter encounters a matching result after the fetchResults() method is called.

◆ isRunning()

bool QgsLocator::isRunning ( ) const

Returns true if a query is currently being executed by the locator.

Definition at line 271 of file qgslocator.cpp.

◆ prefixedFilters()

QMap< QString, QgsLocatorFilter * > QgsLocator::prefixedFilters ( ) const

Returns a map of prefix to filter, for all registered filters with valid prefixes.

See also: filters()

Deprecated:: QGIS 3.2. Use filters() instead.

Definition at line 84 of file qgslocator.cpp.

◆ registerFilter()

void QgsLocator::registerFilter ( QgsLocatorFilter * filter )

Registers a filter within the locator.

Ownership of the filter is transferred to the locator.

Warning: Plugins which register filters to the locator must take care to correctly call deregisterFilter() and deregister their filters upon plugin unload to avoid crashes.

See also: deregisterFilter()

Definition at line 97 of file qgslocator.cpp.

◆ searchPrepared

void QgsLocator::searchPrepared ( )

signal

Emitted when locator has prepared the search (.

See also: QgsLocatorFilter::prepare) before the search is actually performed

Since: QGIS 3.16

Member Data Documentation

◆ CORE_FILTERS

const QList< QString > QgsLocator::CORE_FILTERS

static

Initial value:

= QList<QString>() << QStringLiteral( "actions" )
    <<  QStringLiteral( "processing_alg" )
    <<  QStringLiteral( "layertree" )
    <<  QStringLiteral( "layouts" )
    <<  QStringLiteral( "features" )
    <<  QStringLiteral( "allfeatures" )
    <<  QStringLiteral( "calculator" )
    <<  QStringLiteral( "bookmarks" )
    <<  QStringLiteral( "optionpages" )
    <<  QStringLiteral( "edit_features" )
    <<  QStringLiteral( "goto" )
    <<  QStringLiteral( "nominatimgeocoder" )

List of core filters (i.e. not plugin filters)

Definition at line 67 of file qgslocator.h.

◆ settingsLocatorFilterDefault

const QgsSettingsEntryBool * QgsLocator::settingsLocatorFilterDefault = new QgsSettingsEntryBool( QStringLiteral( "default" ), sTreeLocatorFilters, false, QObject::tr( "Locator filter default value" ) )

static

Settings entry locator filter default value.

Definition at line 164 of file qgslocator.h.

◆ settingsLocatorFilterEnabled

const QgsSettingsEntryBool * QgsLocator::settingsLocatorFilterEnabled = new QgsSettingsEntryBool( QStringLiteral( "enabled" ), sTreeLocatorFilters, true, QObject::tr( "Locator filter enabled" ) )

static

Settings entry locator filter enabled.

Definition at line 162 of file qgslocator.h.

◆ settingsLocatorFilterPrefix

const QgsSettingsEntryString * QgsLocator::settingsLocatorFilterPrefix = new QgsSettingsEntryString( QStringLiteral( "prefix" ), sTreeLocatorFilters, QString(), QObject::tr( "Locator filter prefix" ) )

static

Settings entry locator filter prefix.

Definition at line 166 of file qgslocator.h.

◆ sTreeLocatorFilters

QgsSettingsTreeNamedListNode* QgsLocator::sTreeLocatorFilters = QgsSettingsTree::treeRoot()->createNamedListNode( QStringLiteral( "locator-filters" ) )

inlinestatic

Definition at line 159 of file qgslocator.h.

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

/build/qgis-3.41.0+git20241225+af5edcb665c+99sid/src/core/locator/qgslocator.h
/build/qgis-3.41.0+git20241225+af5edcb665c+99sid/src/core/locator/qgslocator.cpp

Signals

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QgsLocator()

◆ ~QgsLocator()

Member Function Documentation

◆ cancel()

◆ cancelWithoutBlocking()

◆ clearPreviousResults()

◆ completionList()

◆ deregisterFilter()

◆ fetchResults()

◆ filters()

◆ finished

◆ foundResult

◆ isRunning()

◆ prefixedFilters()

◆ registerFilter()

◆ searchPrepared

Member Data Documentation

◆ CORE_FILTERS

◆ settingsLocatorFilterDefault

◆ settingsLocatorFilterEnabled

◆ settingsLocatorFilterPrefix

◆ sTreeLocatorFilters