QGIS API Documentation  2.99.0-Master (19b062c)
Public Types | Signals | Public Member Functions | Static Public Member Functions | List of all members
QgsLocatorFilter Class Referenceabstract

Abstract base class for filters which collect locator results. More...

#include <qgslocatorfilter.h>

Inheritance diagram for QgsLocatorFilter:
Inheritance graph
[legend]

Public Types

enum  Priority {
  Highest, High, Medium, Low,
  Lowest
}
 Filter priority. Controls the order of results in the locator. More...
 

Signals

void resultFetched (const QgsLocatorResult &result)
 Should be emitted by filters whenever they encounter a matching result during within their fetchResults() implementation. More...
 

Public Member Functions

 QgsLocatorFilter (QObject *parent=nullptr)
 Constructor for QgsLocatorFilter. More...
 
virtual QString displayName () const =0
 Returns a translated, user-friendly name for the filter. More...
 
bool enabled () const
 Returns true if the filter is enabled. More...
 
virtual void fetchResults (const QString &string, const QgsLocatorContext &context, QgsFeedback *feedback)=0
 Retrieves the filter results for a specified search string. More...
 
virtual bool hasConfigWidget () const
 Should return true if the filter has a configuration widget. More...
 
virtual QString name () const =0
 Returns the unique name for the filter. More...
 
virtual void openConfigWidget (QWidget *parent=nullptr)
 Opens the configuration widget for the filter (if it has one), with the specified parent widget. More...
 
virtual QString prefix () const
 Returns the search prefix character(s) for this filter. More...
 
virtual Priority priority () const
 Returns the priority for the filter, which controls how results are ordered in the locator. More...
 
void setEnabled (bool enabled)
 Sets whether the filter is enabled. More...
 
void setUseWithoutPrefix (bool useWithoutPrefix)
 Sets whether the filter should be used when no prefix is entered. More...
 
virtual void triggerResult (const QgsLocatorResult &result)=0
 Triggers a filter result from this filter. More...
 
bool useWithoutPrefix () const
 Returns true if the filter should be used when no prefix is entered. More...
 

Static Public Member Functions

static bool 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. More...
 

Detailed Description

Abstract base class for filters which collect locator results.

Since
QGIS 3.0

Definition at line 93 of file qgslocatorfilter.h.

Member Enumeration Documentation

◆ Priority

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

Enumerator
Highest 

Highest priority.

High 

High priority.

Medium 

Medium priority.

Low 

Low priority.

Lowest 

Lowest priority.

Definition at line 100 of file qgslocatorfilter.h.

Constructor & Destructor Documentation

◆ QgsLocatorFilter()

QgsLocatorFilter::QgsLocatorFilter ( QObject *  parent = nullptr)

Constructor for QgsLocatorFilter.

Definition at line 22 of file qgslocatorfilter.cpp.

Member Function Documentation

◆ displayName()

virtual QString QgsLocatorFilter::displayName ( ) const
pure virtual

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

See also
name()

◆ enabled()

bool QgsLocatorFilter::enabled ( ) const

Returns true if the filter is enabled.

See also
setEnabled()

Definition at line 33 of file qgslocatorfilter.cpp.

◆ fetchResults()

virtual 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.

◆ hasConfigWidget()

bool QgsLocatorFilter::hasConfigWidget ( ) const
virtual

Should return true if the filter has a configuration widget.

See also
createConfigWidget()

Definition at line 43 of file qgslocatorfilter.cpp.

◆ name()

virtual QString QgsLocatorFilter::name ( ) const
pure virtual

Returns the unique name for the filter.

This should be an untranslated string identifying the filter.

See also
displayName()

◆ openConfigWidget()

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.

Note
hasConfigWidget() must return true to indicate that the filter supports configuration.

Definition at line 48 of file qgslocatorfilter.cpp.

◆ prefix()

virtual QString QgsLocatorFilter::prefix ( ) const
inlinevirtual

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.

Definition at line 141 of file qgslocatorfilter.h.

◆ priority()

virtual Priority QgsLocatorFilter::priority ( ) const
inlinevirtual

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

Definition at line 130 of file qgslocatorfilter.h.

◆ resultFetched

void QgsLocatorFilter::resultFetched ( const QgsLocatorResult result)
signal

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

◆ setEnabled()

void QgsLocatorFilter::setEnabled ( bool  enabled)

Sets whether the filter is enabled.

See also
enabled()

Definition at line 38 of file qgslocatorfilter.cpp.

◆ setUseWithoutPrefix()

void QgsLocatorFilter::setUseWithoutPrefix ( bool  useWithoutPrefix)

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

See also
useWithoutPrefix()

Definition at line 58 of file qgslocatorfilter.cpp.

◆ stringMatches()

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

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.

Definition at line 28 of file qgslocatorfilter.cpp.

◆ triggerResult()

virtual 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.

◆ useWithoutPrefix()

bool QgsLocatorFilter::useWithoutPrefix ( ) const

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

See also
setUseWithoutPrefix()

Definition at line 53 of file qgslocatorfilter.cpp.


The documentation for this class was generated from the following files: