QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
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 
37 class CORE_EXPORT QgsLocatorResult
38 {
39  public:
40 
44  QgsLocatorResult() = default;
45 
49  QgsLocatorResult( QgsLocatorFilter *filter, const QString &displayString, const QVariant &userData = QVariant() )
50  : filter( filter )
51  , displayString( displayString )
52  , mUserData( userData )
53  {}
54 
60  QVariant userData() const SIP_PYNAME( _userData );
61 
67  void setUserData( const QVariant &userData );
68 
72  QgsLocatorFilter *filter = nullptr;
73 
77  QString displayString;
78 
82  QString description;
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  private:
140 
144  QVariant mUserData;
145 
146 
147 };
148 
150 
151 
152 
160 class CORE_EXPORT QgsLocatorFilter : public QObject
161 {
162  Q_OBJECT
163 
164  public:
165 
167  enum Priority
168  {
172  Low,
173  Lowest
174  };
175  Q_ENUM( Priority )
176 
177 
178  enum Flag SIP_ENUM_BASETYPE( IntFlag )
179  {
180  FlagFast = 1 << 1,
181  };
182  Q_DECLARE_FLAGS( Flags, Flag )
183  Q_FLAG( Flags )
184 
185 
188  QgsLocatorFilter( QObject *parent = nullptr );
189 
194  virtual QgsLocatorFilter *clone() const = 0 SIP_FACTORY;
195 
200  virtual QString name() const = 0;
201 
206  virtual QString displayName() const = 0;
207 
212  virtual QString description() const { return QString(); }
213 
217  virtual QgsLocatorFilter::Flags flags() const;
218 
223  virtual Priority priority() const { return Medium; }
224 
236  virtual QString prefix() const { return QString(); }
237 
245  virtual QStringList prepare( const QString &string, const QgsLocatorContext &context ) { Q_UNUSED( string ) Q_UNUSED( context ); return QStringList();}
246 
262  virtual void fetchResults( const QString &string, const QgsLocatorContext &context, QgsFeedback *feedback ) = 0;
263 
272  virtual void triggerResult( const QgsLocatorResult &result ) = 0;
273 
280  virtual void triggerResultFromAction( const QgsLocatorResult &result, const int actionId );
281 
290  virtual void clearPreviousResults() {}
291 
297  bool useWithoutPrefix() const;
298 
304  void setUseWithoutPrefix( bool useWithoutPrefix );
305 
312  QString activePrefix() const;
313 
320  void setActivePrefix( const QString &activePrefix ) SIP_SKIP;
321 
328  static bool stringMatches( const QString &candidate, const QString &search );
329 
335  static double fuzzyScore( const QString &candidate, const QString &search );
336 
341  bool enabled() const;
342 
347  void setEnabled( bool enabled );
348 
353  virtual bool hasConfigWidget() const;
354 
361  virtual void openConfigWidget( QWidget *parent = nullptr );
362 
369  void logMessage( const QString &message, Qgis::MessageLevel level = Qgis::MessageLevel::Info );
370 
376  int fetchResultsDelay() const { return mFetchResultsDelay; }
377 
384  void setFetchResultsDelay( int delay ) { mFetchResultsDelay = delay; }
385 
386  signals:
387 
391  void finished();
392 
397  void resultFetched( const QgsLocatorResult &result );
398 
399  private:
400 
401  bool mEnabled = true;
402  bool mUseWithoutPrefix = true;
403  QString mActivePrefifx = QString();
404  int mFetchResultsDelay = 0;
405 
406 };
407 
410 
411 
412 #endif // QGSLOCATORFILTER_H
MessageLevel
Level for messages This will be used both for message log and message bar in application.
Definition: qgis.h:99
Base class for feedback objects to be used for cancellation of something running in a worker thread.
Definition: qgsfeedback.h:44
Encapsulates the properties relating to the context of a locator search.
Abstract base class for filters which collect locator results.
QFlags< Flag > Flags
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.
QgsLocatorResult()=default
Constructor for QgsLocatorResult.
QgsLocatorResult(QgsLocatorFilter *filter, const QString &displayString, const QVariant &userData=QVariant())
Constructor for QgsLocatorResult.
#define SIP_ENUM_BASETYPE(type)
Definition: qgis_sip.h:278
#define SIP_SKIP
Definition: qgis_sip.h:126
#define SIP_PYNAME(name)
Definition: qgis_sip.h:81
#define SIP_FACTORY
Definition: qgis_sip.h:76
Q_DECLARE_METATYPE(QgsDatabaseQueryLogEntry)
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsTextRendererUtils::CurvedTextFlags)
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.