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

activePrefix

Returns the prefix in use in the locator is entered.

childEvent

clearPreviousResults

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.

clone

Creates a clone of the filter.

connectNotify

customEvent

description

Returns a translated, description for the filter.

disconnectNotify

displayName

Returns a translated, user-friendly name for the filter.

enabled

Returns True if the filter is enabled.

fetchResults

Retrieves the filter results for a specified search string.

fetchResultsDelay

Returns the delay (in milliseconds) for the filter to wait prior to fetching results.

flags

Returns flags which specify the filter's behavior.

fuzzyScore

Tests a candidate string to see how likely it is a match for a specified search string.

hasConfigWidget

Should return True if the filter has a configuration widget.

isSignalConnected

logMessage

Logs a message to the log panel

name

Returns the unique name for the filter.

openConfigWidget

Opens the configuration widget for the filter (if it has one), with the specified parent widget.

prefix

Returns the search prefix character(s) for this filter.

prepare

Prepares the filter instance for an upcoming search for the specified string.

priority

Returns the priority for the filter, which controls how results are ordered in the locator.

receivers

sender

senderSignalIndex

setEnabled

Sets whether the filter is enabled.

setFetchResultsDelay

Sets a delay (in milliseconds) for the filter to wait prior to fetching results.

setUseWithoutPrefix

Sets whether the filter should be used when no prefix is entered.

stringMatches

Tests a candidate string to see if it should be considered a match for a specified search string.

timerEvent

triggerResult

Triggers a filter result from this filter.

triggerResultFromAction

Triggers a filter result from this filter for an entry in the context menu.

useWithoutPrefix

Returns True if the filter should be used when no prefix is entered.

Signals

finished

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

resultFetched

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

Attributes

FlagFast

High

Highest

Low

Lowest

Medium

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:

QgsLocatorFilter

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

name()

Return type:

str

enabled(self) bool

Returns True if the filter is enabled.

See also

setEnabled()

Return type:

bool

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

Retrieves the filter results for a specified search string. The context argument encapsulates the context relating to the search (such as a map extent to prioritize).

Implementations of fetchResults() should emit the resultFetched() 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:
fetchResultsDelay(self) int

Returns the delay (in milliseconds) for the filter to wait prior to fetching results.

New in version 3.18.

Return type:

int

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

flags(self) QgsLocatorFilter.Flags

Returns flags which specify the filter’s behavior.

Return type:

QgsLocatorFilter.Flags

fuzzyScore(candidate: str, search: str) float

Tests a candidate string to see how likely it is a match for a specified search 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.

Return type:

bool

isSignalConnected(self, QMetaMethod) bool
logMessage(self, message: str, level: Qgis.MessageLevel = Qgis.MessageLevel.Info)

Logs a message to the log panel

Warning

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

displayName()

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 return True 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

activePrefix()

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:
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:

QgsLocatorFilter.Priority

receivers(self, PYQT_SIGNAL) int
resultFetched

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
setEnabled(self, enabled: bool)

Sets whether the filter is enabled.

See also

enabled()

Parameters:

enabled (bool) –

setFetchResultsDelay(self, delay: int)

Sets a delay (in milliseconds) for the filter to wait prior to fetching results.

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.

Parameters:

useWithoutPrefix (bool) –

stringMatches(candidate: str, search: str) bool

Tests a candidate string to see if it should be considered a match for a specified search 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 to fetchResults() 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 its actionId as specified in the result of this filter.

See also

triggerResult()

New in version 3.6.

Parameters:
useWithoutPrefix(self) bool

Returns True if the filter should be used when no prefix is entered.

Return type:

bool