Class: QgsLocatorFilter¶
- class qgis.core.QgsLocatorFilter¶
Bases:
PyQt5.QtCore.QObject
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 QgisInterface.invalidateLocatorResults
New in version 3.0.
QgsLocatorFilter(parent: QObject = None) Constructor for QgsLocatorFilter.
Methods
Returns the prefix in use in the locator is entered.
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.
Creates a clone of the filter.
Returns a translated, description for the filter.
Returns a translated, user-friendly name for the filter.
Returns
True
if the filter is enabled.Retrieves the filter results for a specified search
string
.Returns the delay (in milliseconds) for the filter to wait prior to fetching results.
Returns flags which specify the filter's behavior.
Tests a
candidate
string to see how likely it is a match for a specifiedsearch
string.Should return
True
if the filter has a configuration widget.Logs a
message
to the log panelReturns the unique name for the filter.
Opens the configuration widget for the filter (if it has one), with the specified
parent
widget.Returns the search prefix character(s) for this filter.
Prepares the filter instance for an upcoming search for the specified
string
.Returns the priority for the filter, which controls how results are ordered in the locator.
Sets whether the filter is
enabled
.Sets a
delay
(in milliseconds) for the filter to wait prior to fetching results.Sets whether the filter should be used when no prefix is entered.
Tests a
candidate
string to see if it should be considered a match for a specifiedsearch
string.Triggers a filter
result
from this filter.Triggers a filter
result
from this filter for an entry in the context menu.Returns
True
if the filter should be used when no prefix is entered.Signals
Emitted when the filter finishes fetching results.
Should be emitted by filters whenever they encounter a matching result during within their
fetchResults()
implementation.Attributes
- class Flag¶
Bases:
int
- FlagFast = 2¶
- class Flags¶
- class Flags(Union[QgsLocatorFilter.Flags, QgsLocatorFilter.Flag])
- class Flags(QgsLocatorFilter.Flags)
Bases:
sip.wrapper
- baseClass¶
alias of
QgsLocatorFilter
- High = 1¶
- Highest = 0¶
- Low = 3¶
- Lowest = 4¶
- Medium = 2¶
- class Priority¶
Bases:
int
- baseClass¶
alias of
QgsLocatorFilter
- activePrefix(self) str ¶
Returns the prefix in use in the locator is entered.
See also
setActivePrefix()
New in version 3.2.
- Return type
str
- childEvent(self, QChildEvent)¶
- clearPreviousResults(self)¶
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.
New in version 3.2.
- clone(self) QgsLocatorFilter ¶
Creates a clone of the filter. New requests are always executed in a clone of the original filter.
- Return type
- connectNotify(self, QMetaMethod)¶
- customEvent(self, QEvent)¶
- description(self) str ¶
Returns a translated, description for the filter.
New in version 3.20.
- Return type
str
- disconnectNotify(self, QMetaMethod)¶
- displayName(self) str ¶
Returns a translated, user-friendly name for the filter.
See also
- Return type
str
- enabled(self) bool ¶
Returns
True
if the filter is enabled.See also
- Return type
bool
- fetchResults(self, string: str, context: QgsLocatorContext, feedback: QgsFeedback)¶
Retrieves the filter results for a specified search
string
. Thecontext
argument encapsulates the context relating to the search (such as a map extent to prioritize).Implementations of
fetchResults()
should emit theresultFetched()
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.- Parameters
string (str) –
context (QgsLocatorContext) –
feedback (QgsFeedback) –
- fetchResultsDelay(self) int ¶
Returns the delay (in milliseconds) for the filter to wait prior to fetching results.
See also
New in version 3.18.
- Return type
int
- finished¶
Emitted when the filter finishes fetching results. [signal]
- flags(self) QgsLocatorFilter.Flags ¶
Returns flags which specify the filter’s behavior.
- Return type
- fuzzyScore(candidate: str, search: str) float ¶
Tests a
candidate
string to see how likely it is a match for a specifiedsearch
string.New in version 3.14.
- Parameters
candidate (str) –
search (str) –
- Return type
float
- hasConfigWidget(self) bool ¶
Should return
True
if the filter has a configuration widget.See also
- Return type
bool
- isSignalConnected(self, QMetaMethod) bool ¶
- logMessage(self, message: str, level: Qgis.MessageLevel = Qgis.MessageLevel.Info)¶
Logs a
message
to the log panelWarning
in Python, do not use
print()
method as it might result in crashes since fetching results does not happen in the main thread.New in version 3.2.
- Parameters
message (str) –
level (Qgis.MessageLevel = Qgis.MessageLevel.Info) –
- name(self) str ¶
Returns the unique name for the filter. This should be an untranslated string identifying the filter.
See also
- Return type
str
- openConfigWidget(self, parent: QWidget = None)¶
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 returnTrue
to indicate that the filter supports configuration.- Parameters
parent (QWidget = None) –
- prefix(self) str ¶
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.
Note
Prefixes might be overridden by user preferences.
See also
- Return type
str
- prepare(self, string: str, context: QgsLocatorContext) List[str] ¶
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- Parameters
string (str) –
context (QgsLocatorContext) –
- Return type
List[str]
- priority(self) QgsLocatorFilter.Priority ¶
Returns the priority for the filter, which controls how results are ordered in the locator.
- Return type
- receivers(self, PYQT_SIGNAL) int ¶
- resultFetched¶
Should be emitted by filters whenever they encounter a matching result during within their
fetchResults()
implementation. [signal]- Parameters
result (QgsLocatorResult) –
- sender(self) QObject ¶
- senderSignalIndex(self) int ¶
- setEnabled(self, enabled: bool)¶
Sets whether the filter is
enabled
.See also
- Parameters
enabled (bool) –
- setFetchResultsDelay(self, delay: int)¶
Sets a
delay
(in milliseconds) for the filter to wait prior to fetching results.See also
Note
If the locator filter has a FastFlag, this value is ignored.
New in version 3.18.
- Parameters
delay (int) –
- setUseWithoutPrefix(self, useWithoutPrefix: bool)¶
Sets whether the filter should be used when no prefix is entered.
See also
- Parameters
useWithoutPrefix (bool) –
- stringMatches(candidate: str, search: str) bool ¶
Tests a
candidate
string to see if it should be considered a match for a specifiedsearch
string. Filter subclasses should use this method when comparing strings instead of directly using QString.contains() or Python ‘in’ checks.- Parameters
candidate (str) –
search (str) –
- Return type
bool
- timerEvent(self, QTimerEvent)¶
- triggerResult(self, result: QgsLocatorResult)¶
Triggers a filter
result
from this filter. This is called when one of the results obtained by a call tofetchResults()
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.- Parameters
result (QgsLocatorResult) –
- triggerResultFromAction(self, result: QgsLocatorResult, actionId: int)¶
Triggers a filter
result
from this filter for an entry in the context menu. The entry is identified by itsactionId
as specified in the result of this filter.See also
New in version 3.6.
- Parameters
result (QgsLocatorResult) –
actionId (int) –
- useWithoutPrefix(self) bool ¶
Returns
True
if the filter should be used when no prefix is entered.See also
- Return type
bool