QgsLocatorFilter class

Abstract base class for filters which collect locator results.

Reference

Public types

enum Flag { FlagFast = 1 << 1 }: Flags for locator behavior.
enum Priority { Highest, High, Medium, Low, Lowest }: Filter priority. Controls the order of results in the locator.

Public static functions

static auto stringMatches(const QString& candidate, const QString& search) -> bool: Tests a candidate string to see if it should be considered a match for a specified search string.

Constructors, destructors, conversion operators

QgsLocatorFilter(QObject* parent = nullptr): Constructor for QgsLocatorFilter.

Public functions

auto activePrefix() const -> QString: Returns the prefix in use in the locator is entered.
void clearPreviousResults() virtual: 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.
auto clone() const -> QgsLocatorFilter* pure virtual: Creates a clone of the filter.
auto displayName() const -> QString pure virtual: Returns a translated, user-friendly name for the filter.
auto enabled() const -> bool: Returns true if the filter is enabled.
void fetchResults(const QString& string, const QgsLocatorContext& context, QgsFeedback* feedback) pure virtual: Retrieves the filter results for a specified search string.
auto flags() const -> QgsLocatorFilter::Flags virtual: Returns flags which specify the filter's behavior.
auto hasConfigWidget() const -> bool virtual: Should return true if the filter has a configuration widget.
void logMessage(const QString& message, Qgis::MessageLevel level = Qgis::Info): Logs a message to the log panel.
auto name() const -> QString pure virtual: Returns the unique name for the filter.
void openConfigWidget(QWidget* parent = nullptr) virtual: Opens the configuration widget for the filter (if it has one), with the specified parent widget.
auto prefix() const -> QString virtual: Returns the search prefix character(s) for this filter.
void prepare(const QString& string, const QgsLocatorContext& context) virtual: Prepares the filter instance for an upcoming search for the specified string.
auto priority() const -> Priority virtual: Returns the priority for the filter, which controls how results are ordered in the locator.
void setActivePrefix(const QString& activePrefix): Sets the prefix as being used by the locator.
void setEnabled(bool enabled): Sets whether the filter is enabled.
void setUseWithoutPrefix(bool useWithoutPrefix): Sets whether the filter should be used when no prefix is entered.
void triggerResult(const QgsLocatorResult& result) pure virtual: Triggers a filter result from this filter.
void triggerResultFromAction(const QgsLocatorResult& result, const int actionId) virtual: Triggers a filter result from this filter for an entry in the context menu.
auto useWithoutPrefix() const -> bool: Returns true if the filter should be used when no prefix is entered.

Signals

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

Enum documentation

enum QgsLocatorFilter::Flag

Flags for locator behavior.

Enumerators
FlagFast	Filter finds results quickly and can be safely run in the main thread.

enum QgsLocatorFilter::Priority

Filter priority. Controls the order of results in the locator.

Enumerators
Highest	Highest priority.
High	High priority.
Medium	Medium priority.
Low	Low priority.
Lowest	Lowest priority.

Function documentation

static bool QgsLocatorFilter::stringMatches(const QString& candidate, const QString& search)

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.

QString QgsLocatorFilter::activePrefix() const

Returns the prefix in use in the locator is entered.

void QgsLocatorFilter::clearPreviousResults() virtual

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.

QgsLocatorFilter* QgsLocatorFilter::clone() const pure virtual

Creates a clone of the filter.

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

QString QgsLocatorFilter::displayName() const pure virtual

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

bool QgsLocatorFilter::enabled() const

Returns true if the filter is enabled.

void QgsLocatorFilter::fetchResults(const QString& string, const QgsLocatorContext& context, QgsFeedback* feedback) pure virtual

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.

bool QgsLocatorFilter::hasConfigWidget() const virtual

Should return true if the filter has a configuration widget.

void QgsLocatorFilter::logMessage(const QString& message, Qgis::MessageLevel level = Qgis::Info)

Logs a message to the log panel.

QString QgsLocatorFilter::name() const pure virtual

Returns the unique name for the filter.

This should be an untranslated string identifying the filter.

void QgsLocatorFilter::openConfigWidget(QWidget* parent = nullptr) virtual

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.

QString QgsLocatorFilter::prefix() const virtual

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.

void QgsLocatorFilter::prepare(const QString& string, const QgsLocatorContext& context) virtual

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.

void QgsLocatorFilter::setActivePrefix(const QString& activePrefix)

Sets the prefix as being used by the locator.

void QgsLocatorFilter::setEnabled(bool enabled)

Sets whether the filter is enabled.

void QgsLocatorFilter::setUseWithoutPrefix(bool useWithoutPrefix)

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

void QgsLocatorFilter::triggerResult(const QgsLocatorResult& result) pure virtual

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.

void QgsLocatorFilter::triggerResultFromAction(const QgsLocatorResult& result, const int actionId) virtual

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.

bool QgsLocatorFilter::useWithoutPrefix() const

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