QGIS API Documentation  3.18.1-Zürich (202f1bf7e5)
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Modules Pages
qgslocatorfilter.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgslocatorfilter.h
3  ------------------
4  begin : May 2017
5  copyright : (C) 2017 by Nyall Dawson
6  email : nyall dot dawson at gmail dot com
7  ***************************************************************************/
8 
9 /***************************************************************************
10  * *
11  * This program is free software; you can redistribute it and/or modify *
12  * it under the terms of the GNU General Public License as published by *
13  * the Free Software Foundation; either version 2 of the License, or *
14  * (at your option) any later version. *
15  * *
16  ***************************************************************************/
17 
18 #ifndef QGSLOCATORFILTER_H
19 #define QGSLOCATORFILTER_H
20 
21 #include <QAction>
22 #include <QIcon>
23 #include <QString>
24 #include <QVariant>
25 
26 #include "qgis_core.h"
27 #include "qgslocatorcontext.h"
28 #include "qgslogger.h"
29 
30 class QgsFeedback;
31 class QgsLocatorFilter;
32 
39 class CORE_EXPORT QgsLocatorResult
40 {
41  public:
42 
46  QgsLocatorResult() = default;
47 
51  QgsLocatorResult( QgsLocatorFilter *filter, const QString &displayString, const QVariant &userData = QVariant() )
52  : filter( filter )
53  , displayString( displayString )
54  , userData( userData )
55  {}
56 
57 
63  QVariant getUserData() const;
64 
68  QgsLocatorFilter *filter = nullptr;
69 
73  QString displayString;
74 
78  QString description;
79 
83  QVariant userData;
84 
88  QIcon icon;
89 
93  double score = 0.5;
94 
102  QString group;
103 
110  struct CORE_EXPORT ResultAction
111  {
112  public:
114  ResultAction() = default;
115 
122  ResultAction( int id, QString text, QString iconPath = QString() )
123  : id( id )
124  , text( text )
125  , iconPath( iconPath )
126  {}
127  int id = -1;
128  QString text;
129  QString iconPath;
130  };
131 
138  QList<QgsLocatorResult::ResultAction> actions;
139 };
140 
142 
143 
144 
153 class CORE_EXPORT QgsLocatorFilter : public QObject
154 {
155  Q_OBJECT
156 
157  public:
158 
160  enum Priority
161  {
165  Low,
166  Lowest
167  };
168  Q_ENUM( Priority )
169 
170 
171  enum Flag
172  {
173  FlagFast = 1 << 1,
174  };
175  Q_DECLARE_FLAGS( Flags, Flag )
176  Q_FLAG( Flags )
177 
178 
181  QgsLocatorFilter( QObject *parent = nullptr );
182 
187  virtual QgsLocatorFilter *clone() const = 0 SIP_FACTORY;
188 
193  virtual QString name() const = 0;
194 
199  virtual QString displayName() const = 0;
200 
204  virtual QgsLocatorFilter::Flags flags() const;
205 
210  virtual Priority priority() const { return Medium; }
211 
223  virtual QString prefix() const { return QString(); }
224 
232  virtual QStringList prepare( const QString &string, const QgsLocatorContext &context ) { Q_UNUSED( string ) Q_UNUSED( context ); return QStringList();}
233 
249  virtual void fetchResults( const QString &string, const QgsLocatorContext &context, QgsFeedback *feedback ) = 0;
250 
259  virtual void triggerResult( const QgsLocatorResult &result ) = 0;
260 
267  virtual void triggerResultFromAction( const QgsLocatorResult &result, const int actionId );
268 
277  virtual void clearPreviousResults() {}
278 
284  bool useWithoutPrefix() const;
285 
291  void setUseWithoutPrefix( bool useWithoutPrefix );
292 
299  QString activePrefix() const;
300 
307  void setActivePrefix( const QString &activePrefix ) SIP_SKIP;
308 
315  static bool stringMatches( const QString &candidate, const QString &search );
316 
322  static double fuzzyScore( const QString &candidate, const QString &search );
323 
328  bool enabled() const;
329 
334  void setEnabled( bool enabled );
335 
340  virtual bool hasConfigWidget() const;
341 
348  virtual void openConfigWidget( QWidget *parent = nullptr );
349 
356  void logMessage( const QString &message, Qgis::MessageLevel level = Qgis::Info );
357 
363  int fetchResultsDelay() const { return mFetchResultsDelay; }
364 
371  void setFetchResultsDelay( int delay ) { mFetchResultsDelay = delay; }
372 
373  signals:
374 
378  void finished();
379 
384  void resultFetched( const QgsLocatorResult &result );
385 
386  private:
387 
388  bool mEnabled = true;
389  bool mUseWithoutPrefix = true;
390  QString mActivePrefifx = QString();
391  int mFetchResultsDelay = 0;
392 
393 };
394 
396 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLocatorFilter::Flags )
397 
398 
399 #endif // QGSLOCATORFILTER_H
400 
401 
MessageLevel
Level for messages This will be used both for message log and message bar in application.
Definition: qgis.h:89
@ Info
Definition: qgis.h:90
Base class for feedback objects to be used for cancellation of something running in a worker thread.
Definition: qgsfeedback.h:45
Encapsulates the properties relating to the context of a locator search.
Abstract base class for filters which collect locator results.
virtual QString prefix() const
Returns the search prefix character(s) for this filter.
virtual QgsLocatorFilter * clone() const =0
Creates a clone of the filter.
Flag
Flags for locator behavior.
int fetchResultsDelay() const
Returns the delay (in milliseconds) for the filter to wait prior to fetching results.
Priority
Filter priority. Controls the order of results in the locator.
@ Low
Low priority.
@ Highest
Highest priority.
@ Medium
Medium priority.
@ High
High priority.
void setFetchResultsDelay(int delay)
Sets a delay (in milliseconds) for the filter to wait prior to fetching results.
void finished()
Emitted when the filter finishes fetching results.
virtual QString displayName() const =0
Returns a translated, user-friendly name for the filter.
virtual Priority priority() const
Returns the priority for the filter, which controls how results are ordered in the locator.
virtual QString name() const =0
Returns the unique name for the filter.
virtual void triggerResult(const QgsLocatorResult &result)=0
Triggers a filter result from this filter.
virtual void clearPreviousResults()
This method will be called on main thread on the original filter (not a clone) before fetching result...
void resultFetched(const QgsLocatorResult &result)
Should be emitted by filters whenever they encounter a matching result during within their fetchResul...
virtual void fetchResults(const QString &string, const QgsLocatorContext &context, QgsFeedback *feedback)=0
Retrieves the filter results for a specified search string.
virtual QStringList prepare(const QString &string, const QgsLocatorContext &context)
Prepares the filter instance for an upcoming search for the specified string.
Encapsulates properties of an individual matching result found by a QgsLocatorFilter.
QList< QgsLocatorResult::ResultAction > actions
Additional actions to be used in a locator widget for the given result.
QVariant userData
Custom reference or other data set by the filter.
QString description
Descriptive text for result.
QgsLocatorResult()=default
Constructor for QgsLocatorResult.
QString displayString
String displayed for result.
QString group
Group the results by categories If left as empty string, this means that results are all shown withou...
QIcon icon
Icon for result.
QgsLocatorResult(QgsLocatorFilter *filter, const QString &displayString, const QVariant &userData=QVariant())
Constructor for QgsLocatorResult.
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_FACTORY
Definition: qgis_sip.h:76
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsField::ConfigurationFlags) CORE_EXPORT QDataStream &operator<<(QDataStream &out
Writes the field to stream out. QGIS version compatibility is not guaranteed.
Q_DECLARE_METATYPE(QgsMeshTimeSettings)
The ResultAction stores basic information for additional actions to be used in a locator widget for t...
ResultAction(int id, QString text, QString iconPath=QString())
Constructor for ResultAction The id used to recognized the action when the result is triggered.
ResultAction()=default
Constructor for ResultAction.