Class: QgsLocator¶
- class qgis.core.QgsLocator(parent: QObject = None)¶
Bases:
PyQt5.QtCore.QObject
Constructor for QgsLocator.
Handles the management of
QgsLocatorFilter
objects and async collection of search results from them.QgsLocator
acts as both a registry forQgsLocatorFilter
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 callderegisterFilter()
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 toQgsLocatorFilter.fetchResults()
for all registered filters. As individual filters find matching results, thefoundResult()
signal will be triggered for each result. Callers should connect this signal to an appropriate slot designed to collect and handle these results. SincefoundResult()
is triggered whenever a filter encounters an individual result, it will usually be triggered many times for a single call tofetchResults()
.New in version 3.0:
Methods
Cancels any current running query, and blocks until query is completely canceled by all filters.
Triggers cancellation of any current running query without blocking.
Will call clearPreviousResults on all filters
Returns the list for auto completion This list is updated when preparing the search
Deregisters a
filter
from the locator and deletes it.Triggers the background fetching of filter results for a specified search
string
.Returns the list of filters registered in the locator.
Returns
True
if a query is currently being executed by the locator.Returns a map of prefix to filter, for all registered filters with valid prefixes.
Registers a
filter
within the locator.Signals
Emitted when locator has finished a query, either as a result of successful completion or early cancellation.
Emitted whenever a filter encounters a matching
result
after thefetchResults()
method is called.Emitted when locator has prepared the search (
QgsLocatorFilter.prepare()
) before the search is actually performedAttributes
- CORE_FILTERS = ['actions', 'processing_alg', 'layertree', 'layouts', 'features', 'allfeatures', 'calculator', 'bookmarks', 'optionpages', 'edit_features', 'goto']¶
- cancel(self)¶
Cancels any current running query, and blocks until query is completely canceled by all filters.
See also
- cancelWithoutBlocking(self)¶
Triggers cancellation of any current running query without blocking. The query may take some time to cancel after calling this.
See also
- 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
- 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
. Thecontext
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 (str) –
context (QgsLocatorContext) –
feedback (
QgsFeedback
= None) –
- 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
See also
- Return type
List[QgsLocatorFilter]
- finished¶
Emitted when locator has finished a query, either as a result of successful completion or early cancellation. [signal]
- foundResult¶
Emitted whenever a filter encounters a matching
result
after thefetchResults()
method is called. [signal]- Parameters
result (QgsLocatorResult) –
- 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
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.See also
- Parameters
filter (QgsLocatorFilter) –
- searchPrepared¶
Emitted when locator has prepared the search (
QgsLocatorFilter.prepare()
) before the search is actually performedNew in version 3.16: [signal]
- sender(self) QObject ¶
- senderSignalIndex(self) int ¶
- timerEvent(self, QTimerEvent)¶