QGIS API Documentation  3.0.2-Girona (307d082)
Signals | Public Member Functions | List of all members
QgsLocator Class Reference

Handles the management of QgsLocatorFilter objects and async collection of search results from them. More...

#include <qgslocator.h>

Inheritance diagram for QgsLocator:
Inheritance graph
[legend]

Signals

void finished ()
 Emitted when locator has finished a query, either as a result of successful completion or early cancelation. More...
 
void foundResult (const QgsLocatorResult &result)
 Emitted whenever a filter encounters a matching result after the fetchResults() method is called. More...
 

Public Member Functions

 QgsLocator (QObject *parent=nullptr)
 Constructor for QgsLocator. More...
 
 ~QgsLocator () override
 Destructor for QgsLocator. More...
 
void cancel ()
 Cancels any current running query, and blocks until query is completely canceled by all filters. More...
 
void cancelWithoutBlocking ()
 Triggers cancelation of any current running query without blocking. More...
 
void deregisterFilter (QgsLocatorFilter *filter)
 Deregisters a filter from the locator and deletes it. More...
 
void fetchResults (const QString &string, const QgsLocatorContext &context, QgsFeedback *feedback=nullptr)
 Triggers the background fetching of filter results for a specified search string. More...
 
QList< QgsLocatorFilter * > filters ()
 Returns the list of filters registered in the locator. More...
 
bool isRunning () const
 Returns true if a query is currently being executed by the locator. More...
 
QMap< QString, QgsLocatorFilter * > prefixedFilters () const
 Returns a map of prefix to filter, for all registered filters with valid prefixes. More...
 
void registerFilter (QgsLocatorFilter *filter)
 Registers a filter within the locator. More...
 

Detailed Description

Handles the management of QgsLocatorFilter objects and async collection of search results from them.

QgsLocator acts as both a registry for QgsLocatorFilter objects and a means of firing up asynchronous queries against these filter objects.

Filters are first registered to the locator by calling registerFilter(). Registering filters transfers their ownership to the locator object. Plugins which register filters to the locator must take care to correctly call deregisterFilter() and deregister their filter upon plugin unload to avoid crashes.

In order to trigger a search across registered filters, the fetchResults() method is called. This triggers threaded calls to QgsLocatorFilter::fetchResults() for all registered filters. As individual filters find matching results, the foundResult() signal will be triggered for each result. Callers should connect this signal to an appropriate slot designed to collect and handle these results. Since foundResult() is triggered whenever a filter encounters an individual result, it will usually be triggered many times for a single call to fetchResults().

Since
QGIS 3.0

Definition at line 54 of file qgslocator.h.

Constructor & Destructor Documentation

◆ QgsLocator()

QgsLocator::QgsLocator ( QObject *  parent = nullptr)

Constructor for QgsLocator.

Definition at line 23 of file qgslocator.cpp.

◆ ~QgsLocator()

QgsLocator::~QgsLocator ( )
override

Destructor for QgsLocator.

Destruction will block while any currently running query is terminated.

Definition at line 29 of file qgslocator.cpp.

Member Function Documentation

◆ cancel()

void QgsLocator::cancel ( )

Cancels any current running query, and blocks until query is completely canceled by all filters.

See also
cancelWithoutBlocking()

Definition at line 177 of file qgslocator.cpp.

◆ cancelWithoutBlocking()

void QgsLocator::cancelWithoutBlocking ( )

Triggers cancelation of any current running query without blocking.

The query may take some time to cancel after calling this.

See also
cancel()

Definition at line 182 of file qgslocator.cpp.

◆ deregisterFilter()

void QgsLocator::deregisterFilter ( QgsLocatorFilter filter)

Deregisters a filter from the locator and deletes it.

Calling this will block whilst any currently running query is terminated.

Plugins which register filters to the locator must take care to correctly call deregisterFilter() to deregister their filters upon plugin unload to avoid crashes.

See also
registerFilter()

Definition at line 35 of file qgslocator.cpp.

◆ fetchResults()

void QgsLocator::fetchResults ( const QString &  string,
const QgsLocatorContext context,
QgsFeedback feedback = nullptr 
)

Triggers the background fetching of filter results for a specified search string.

The context argument encapsulates the context relating to the search (such as a map extent to prioritize).

If specified, the feedback object must exist for the lifetime of this query.

The foundResult() signal will be emitted for each individual result encountered by the registered filters.

Definition at line 84 of file qgslocator.cpp.

◆ filters()

QList< QgsLocatorFilter * > QgsLocator::filters ( )

Returns the list of filters registered in the locator.

See also
prefixedFilters()

Definition at line 45 of file qgslocator.cpp.

◆ finished

void QgsLocator::finished ( )
signal

Emitted when locator has finished a query, either as a result of successful completion or early cancelation.

◆ foundResult

void QgsLocator::foundResult ( const QgsLocatorResult result)
signal

Emitted whenever a filter encounters a matching result after the fetchResults() method is called.

◆ isRunning()

bool QgsLocator::isRunning ( ) const

Returns true if a query is currently being executed by the locator.

Definition at line 188 of file qgslocator.cpp.

◆ prefixedFilters()

QMap< QString, QgsLocatorFilter * > QgsLocator::prefixedFilters ( ) const

Returns a map of prefix to filter, for all registered filters with valid prefixes.

See also
filters()

Definition at line 50 of file qgslocator.cpp.

◆ registerFilter()

void QgsLocator::registerFilter ( QgsLocatorFilter filter)

Registers a filter within the locator.

Ownership of the filter is transferred to the locator.

Warning
Plugins which register filters to the locator must take care to correctly call deregisterFilter() and deregister their filters upon plugin unload to avoid crashes.
See also
deregisterFilter()

Definition at line 55 of file qgslocator.cpp.


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