Class: QgsLocator

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

Class Hierarchy

Base classes

QObject

Methods

cancel	Cancels any current running query, and blocks until query is completely canceled by all filters.
cancelWithoutBlocking	Triggers cancellation of any current running query without blocking.
clearPreviousResults	Will call clearPreviousResults on all filters
completionList	Returns the list for auto completion This list is updated when preparing the search
deregisterFilter	Deregisters a filter from the locator and deletes it.
fetchResults	Triggers the background fetching of filter results for a specified search string.
filters	Returns the list of filters registered in the locator.
isRunning	Returns True if a query is currently being executed by the locator.
prefixedFilters	Returns a map of prefix to filter, for all registered filters with valid prefixes.
registerFilter	Registers a filter within the locator.

Signals

finished	Emitted when locator has finished a query, either as a result of successful completion or early cancellation.
foundResult	Emitted whenever a filter encounters a matching result after the fetchResults() method is called.
searchPrepared	Emitted when locator has prepared the search (QgsLocatorFilter.prepare()) before the search is actually performed

Attributes

CORE_FILTERS

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

class qgis.core.QgsLocator

Bases: QObject

__init__(parent: QObject | None = None)

Constructor for QgsLocator.

Parameters:

parent (Optional[QObject] = None)

CORE_FILTERS: List[str] = ['actions', 'processing_alg', 'layertree', 'layouts', 'features', 'allfeatures', 'calculator', 'bookmarks', 'optionpages', 'edit_features', 'goto', 'nominatimgeocoder']

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

cancel(self)

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

See also

cancelWithoutBlocking()

cancelWithoutBlocking(self)

Triggers cancellation of any current running query without blocking. The query may take some time to cancel after calling this.

See also

cancel()

clearPreviousResults(self)

Will call clearPreviousResults on all filters

Added in version 3.2.

completionList(self) → List[str]

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

Added in version 3.16.

Return type:

List[str]

deregisterFilter(self, filter: QgsLocatorFilter | None)

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

Parameters:

filter (Optional[QgsLocatorFilter])

fetchResults(self, string: str | None, context: QgsLocatorContext, feedback: QgsFeedback | None = None)

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.

Parameters:

• string (Optional[str])

• context (QgsLocatorContext)

• feedback (Optional[QgsFeedback] = None)

filters(self, prefix: str | None = '') → List[QgsLocatorFilter]

Returns the list of filters registered in the locator.

Parameters:

prefix (Optional[str] = '') – If prefix is not empty, the list returned corresponds to the filter with the given active prefix

See also

prefixedFilters()

Return type:

List[QgsLocatorFilter]

signal finished

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

signal foundResult(result: QgsLocatorResult)

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

Parameters:

result (QgsLocatorResult)

isRunning(self) → bool

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

Return type:

bool

prefixedFilters(self) → Any

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

See also

filters()

Deprecated since version 3.2: Use filters() instead.

Return type:

Any

registerFilter(self, filter: QgsLocatorFilter | None)

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

Parameters:

filter (Optional[QgsLocatorFilter])

signal searchPrepared

Emitted when locator has prepared the search (QgsLocatorFilter.prepare()) before the search is actually performed

Added in version 3.16.