QGIS API Documentation  3.23.0-Master (eb871beae0)
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 <QIcon>
22 #include <QString>
23 #include <QVariant>
24 
25 #include "qgis_core.h"
26 #include "qgslocatorcontext.h"
27 #include "qgslogger.h"
28 
29 class QgsFeedback;
30 class QgsLocatorFilter;
31 
38 class CORE_EXPORT QgsLocatorResult
39 {
40  public:
41 
45  QgsLocatorResult() = default;
46 
50  QgsLocatorResult( QgsLocatorFilter *filter, const QString &displayString, const QVariant &userData = QVariant() )
51  : filter( filter )
52  , displayString( displayString )
53  , userData( userData )
54  {}
55 
56 
62  QVariant getUserData() const;
63 
67  QgsLocatorFilter *filter = nullptr;
68 
72  QString displayString;
73 
77  QString description;
78 
82  QVariant userData;
83 
87  QIcon icon;
88 
92  double score = 0.5;
93 
101  QString group;
102 
109  struct CORE_EXPORT ResultAction
110  {
111  public:
113  ResultAction() = default;
114 
121  ResultAction( int id, QString text, QString iconPath = QString() )
122  : id( id )
123  , text( text )
124  , iconPath( iconPath )
125  {}
126  int id = -1;
127  QString text;
128  QString iconPath;
129  };
130 
137  QList<QgsLocatorResult::ResultAction> actions;
138 };
139 
141 
142 
143 
152 class CORE_EXPORT QgsLocatorFilter : public QObject
153 {
154  Q_OBJECT
155 
156  public:
157 
159  enum Priority
160  {
164  Low,
165  Lowest
166  };
167  Q_ENUM( Priority )
168 
169 
170  enum Flag
171  {
172  FlagFast = 1 << 1,
173  };
174  Q_DECLARE_FLAGS( Flags, Flag )
175  Q_FLAG( Flags )
176 
177 
180  QgsLocatorFilter( QObject *parent = nullptr );
181 
186  virtual QgsLocatorFilter *clone() const = 0 SIP_FACTORY;
187 
192  virtual QString name() const = 0;
193 
198  virtual QString displayName() const = 0;
199 
204  virtual QString description() const { return QString(); }
205 
209  virtual QgsLocatorFilter::Flags flags() const;
210 
215  virtual Priority priority() const { return Medium; }
216 
228  virtual QString prefix() const { return QString(); }
229 
237  virtual QStringList prepare( const QString &string, const QgsLocatorContext &context ) { Q_UNUSED( string ) Q_UNUSED( context ); return QStringList();}
238 
254  virtual void fetchResults( const QString &string, const QgsLocatorContext &context, QgsFeedback *feedback ) = 0;
255 
264  virtual void triggerResult( const QgsLocatorResult &result ) = 0;
265 
272  virtual void triggerResultFromAction( const QgsLocatorResult &result, const int actionId );
273 
282  virtual void clearPreviousResults() {}
283 
289  bool useWithoutPrefix() const;
290 
296  void setUseWithoutPrefix( bool useWithoutPrefix );
297 
304  QString activePrefix() const;
305 
312  void setActivePrefix( const QString &activePrefix ) SIP_SKIP;
313 
320  static bool stringMatches( const QString &candidate, const QString &search );
321 
327  static double fuzzyScore( const QString &candidate, const QString &search );
328 
333  bool enabled() const;
334 
339  void setEnabled( bool enabled );
340 
345  virtual bool hasConfigWidget() const;
346 
353  virtual void openConfigWidget( QWidget *parent = nullptr );
354 
361  void logMessage( const QString &message, Qgis::MessageLevel level = Qgis::MessageLevel::Info );
362 
368  int fetchResultsDelay() const { return mFetchResultsDelay; }
369 
376  void setFetchResultsDelay( int delay ) { mFetchResultsDelay = delay; }
377 
378  signals:
379 
383  void finished();
384 
389  void resultFetched( const QgsLocatorResult &result );
390 
391  private:
392 
393  bool mEnabled = true;
394  bool mUseWithoutPrefix = true;
395  QString mActivePrefifx = QString();
396  int mFetchResultsDelay = 0;
397 
398 };
399 
401 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsLocatorFilter::Flags )
402 
403 
404 #endif // QGSLOCATORFILTER_H
405 
406 
MessageLevel
Level for messages This will be used both for message log and message bar in application.
Definition: qgis.h:107
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.
virtual QString description() const
Returns a translated, description for the filter.
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.