Class: QgsLocatorFilter¶

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

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: clone(), displayName(), fetchResults(), name(), triggerResult()

Class Hierarchy¶

Base classes¶

QObject

Subclasses¶

QgsAbstractGeocoderLocatorFilter

An abstract base class which implements a locator filter populated from a QgsGeocoderInterface.

Abstract Methods

`clone`	Creates a clone of the filter.
`displayName`	Returns a translated, user-friendly name for the filter.
`fetchResults`	Retrieves the filter results for a specified search string.
`name`	Returns the unique name for the filter.
`triggerResult`	Triggers a filter result from this filter.

Methods

`activePrefix`	Returns the prefix in use in the locator is entered.
`enabled`	Returns `True` if the filter is enabled.
`fetchResultsDelay`	Returns the delay (in milliseconds) for the filter to wait prior to fetching results.
`logMessage`	Logs a message to the log panel
`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.
`useWithoutPrefix`	Returns `True` if the filter should be used when no prefix is entered.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsLocatorFilter. See the FAQ for more details.

`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.
`description`	Returns a translated, description for the filter.
`flags`	Returns flags which specify the filter's behavior.
`hasConfigWidget`	Should return `True` if the filter has a configuration widget.
`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.
`resultDeselected`	This is called when a result is deselected.
`resultSelected`	This is called when the result is selected by the user.
`triggerResultFromAction`	Triggers a filter result from this filter for an entry in the context menu.

Static Methods

`fuzzyScore`	Tests a candidate string to see how likely it is a match for a specified search string.
`stringMatches`	Tests a candidate string to see if it should be considered a match for a specified search string.

Signals

`finished`	Emitted when the filter finishes fetching results.
`resultFetched`	Should be emitted by filters whenever they encounter a matching result during within their `fetchResults()` implementation.

Attributes

`FlagFast`
`High`
`Highest`
`Low`
`Lowest`
`Medium`

class qgis.core.QgsLocatorFilter[source]¶

Bases: QObject

__init__(parent: QObject | None = None)

Constructor for QgsLocatorFilter.

Parameters:: parent (Optional[QObject] = None)

class Flag¶: Bases: int

FlagFast = 2¶

class Flags¶
class Flags(f: QgsLocatorFilter.Flags | QgsLocatorFilter.Flag)
class Flags(a0: QgsLocatorFilter.Flags): Bases: object

High = 1¶

Highest = 0¶

Low = 3¶

Lowest = 4¶

Medium = 2¶

class Priority¶: Bases: int

activePrefix(self) → str[source]¶

Returns the prefix in use in the locator is entered.

See also

setActivePrefix()

Added in version 3.2.

Return type:: str

virtual clearPreviousResults(self)[source]¶: 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.

Added in version 3.2.

abstract clone(self) → QgsLocatorFilter | None[source]¶

Creates a clone of the filter. New requests are always executed in a clone of the original filter.

Return type:: Optional[QgsLocatorFilter]

virtual description(self) → str[source]¶

Returns a translated, description for the filter.

Added in version 3.20.

Return type:: str

abstract displayName(self) → str[source]¶

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

See also

name()

Return type:: str

enabled(self) → bool[source]¶

Returns True if the filter is enabled.

See also

setEnabled()

Return type:: bool

abstract fetchResults(self, string: str | None, context: QgsLocatorContext, feedback: QgsFeedback | None)[source]¶

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:

string (Optional[str])
context (QgsLocatorContext)
feedback (Optional[QgsFeedback])

fetchResultsDelay(self) → int[source]¶

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

See also

setFetchResultsDelay()

Added in version 3.18.

Return type:: int

signal finished[source]¶: Emitted when the filter finishes fetching results.

virtual flags(self) → QgsLocatorFilter.Flags[source]¶

Returns flags which specify the filter’s behavior.

Return type:: QgsLocatorFilter.Flags

static fuzzyScore(candidate: str | None, search: str | None) → float[source]¶

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

Added in version 3.14.

Parameters:

candidate (Optional[str])
search (Optional[str])

Return type:

float

virtual hasConfigWidget(self) → bool[source]¶

Should return True if the filter has a configuration widget.

See also

openConfigWidget()

Return type:: bool

logMessage(self, message: str | None, level: Qgis.MessageLevel = Qgis.MessageLevel.Info)[source]¶

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.

Added in version 3.2.

Parameters:

message (Optional[str])
level (Qgis.MessageLevel = Qgis.MessageLevel.Info)

abstract name(self) → str[source]¶

Returns the unique name for the filter. This should be an untranslated string identifying the filter.

See also

displayName()

Return type:: str

virtual openConfigWidget(self, parent: QWidget | None = None)[source]¶

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 (Optional[QWidget] = None)

virtual prefix(self) → str[source]¶

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

virtual prepare(self, string: str | None, context: QgsLocatorContext) → List[str][source]¶

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 (Optional[str])
context (QgsLocatorContext)

Return type:

List[str]

virtual priority(self) → QgsLocatorFilter.Priority[source]¶

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

Return type:: QgsLocatorFilter.Priority

virtual resultDeselected(self, result: QgsLocatorResult)[source]¶

This is called when a result is deselected. The filter subclass can implement logic here.

Added in version 3.40.

Parameters:: result (QgsLocatorResult)

signal resultFetched(result: QgsLocatorResult)[source]¶

Should be emitted by filters whenever they encounter a matching result during within their fetchResults() implementation.

Parameters:: result (QgsLocatorResult)

virtual resultSelected(self, result: QgsLocatorResult)[source]¶

This is called when the result is selected by the user. The filter subclass can implement logic here.

Added in version 3.40.

Parameters:: result (QgsLocatorResult)

setEnabled(self, enabled: bool)[source]¶

Sets whether the filter is enabled.

See also

enabled()

Parameters:: enabled (bool)

setFetchResultsDelay(self, delay: int)[source]¶

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

See also

fetchResultsDelay()

Note

If the locator filter has a FastFlag, this value is ignored.

Added in version 3.18.

Parameters:: delay (int)

setUseWithoutPrefix(self, useWithoutPrefix: bool)[source]¶

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

See also

useWithoutPrefix()

Parameters:: useWithoutPrefix (bool)

static stringMatches(candidate: str | None, search: str | None) → bool[source]¶

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 (Optional[str])
search (Optional[str])

Return type:

bool

abstract triggerResult(self, result: QgsLocatorResult)[source]¶

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)

virtual triggerResultFromAction(self, result: QgsLocatorResult, actionId: int)[source]¶

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

Added in version 3.6.

Parameters:

result (QgsLocatorResult)
actionId (int)

useWithoutPrefix(self) → bool[source]¶

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

See also

setUseWithoutPrefix()

Return type:: bool