Class: QgsLocator

class qgis.core.QgsLocator

Bases: PyQt5.QtCore.QObject

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

New in version 3.0.

QgsLocator(parent: QObject = None) Constructor for QgsLocator.

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.

childEvent

clearPreviousResults

Will call clearPreviousResults on all filters

completionList

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

connectNotify

customEvent

deregisterFilter

Deregisters a filter from the locator and deletes it.

disconnectNotify

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.

isSignalConnected

prefixedFilters

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

receivers

registerFilter

Registers a filter within the locator.

sender

senderSignalIndex

timerEvent

Signals

finished

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

foundResult

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

searchPrepared

pyqtSignal(*types, name: str = ..., revision: int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

Attributes

CORE_FILTERS

CORE_FILTERS = ['actions', 'processing_alg', 'layertree', 'layouts', 'features', 'allfeatures', 'calculator', 'bookmarks', 'optionpages', 'edit_features', 'goto', 'nominatimgeocoder']
cancel(self)

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

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

childEvent(self, QChildEvent)
clearPreviousResults(self)

Will call clearPreviousResults on all filters

New in version 3.2.

completionList(self) List[str]

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

New in version 3.16.

Return type

List[str]

connectNotify(self, QMetaMethod)
customEvent(self, QEvent)
deregisterFilter(self, filter: QgsLocatorFilter)

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

disconnectNotify(self, QMetaMethod)
fetchResults(self, string: str, context: QgsLocatorContext, feedback: QgsFeedback = 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
filters(self, prefix: str = '') List[QgsLocatorFilter]

Returns the list of filters registered in the locator.

Parameters

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

Return type

List[QgsLocatorFilter]

finished

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type

PYQT_SIGNAL

foundResult

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type

PYQT_SIGNAL

isRunning(self) bool

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

Return type

bool

isSignalConnected(self, QMetaMethod) bool
prefixedFilters(self) object

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

See also

filters()

Deprecated since version QGIS: 3.2 use filters() instead

Return type

object

receivers(self, PYQT_SIGNAL) int
registerFilter(self, filter: QgsLocatorFilter)

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.

Parameters

filter (QgsLocatorFilter) –

searchPrepared

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Parameters
  • name (str = ...) –

  • revision (int = ...) –

  • arguments (Sequence = ...) –

Return type

PYQT_SIGNAL

sender(self) QObject
senderSignalIndex(self) int
timerEvent(self, QTimerEvent)