Akonadi Contacts

contactgroupsearchjob.h
1 /*
2  This file is part of Akonadi Contact.
3 
4  SPDX-FileCopyrightText: 2009 Tobias Koenig <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #pragma once
10 
11 #include "akonadi-contact_export.h"
12 
13 #include <item.h>
14 #include <itemsearchjob.h>
15 #include <kcontacts/contactgroup.h>
16 
17 namespace Akonadi
18 {
19 /**
20  * @short Job that searches for contact groups in the Akonadi storage.
21  *
22  * This job searches for contact groups that match given search criteria and returns
23  * the list of contact groups.
24  *
25  * @code
26  *
27  * Akonadi::ContactGroupSearchJob *job = new Akonadi::ContactGroupSearchJob();
28  * job->setQuery( Akonadi::ContactGroupSearchJob::Name, "Family Members" );
29  * connect( job, SIGNAL(result(KJob*)), this, SLOT(searchResult(KJob*)) );
30  *
31  * ...
32  *
33  * MyClass::searchResult( KJob *job )
34  * {
35  * Akonadi::ContactGroupSearchJob *searchJob = qobject_cast<Akonadi::ContactGroupSearchJob*>( job );
36  * const KContacts::ContactGroup::List contactGroups = searchJob->contactGroups();
37  * // do something with the contact groups
38  * }
39  *
40  * @endcode
41  *
42  * @author Tobias Koenig <[email protected]>
43  * @since 4.4
44  */
45 class AKONADI_CONTACT_EXPORT ContactGroupSearchJob : public ItemSearchJob
46 {
47  Q_OBJECT
48 
49 public:
50  /**
51  * Creates a new contact group search job.
52  *
53  * @param parent The parent object.
54  */
55  explicit ContactGroupSearchJob(QObject *parent = nullptr);
56 
57  /**
58  * Destroys the contact group search job.
59  */
61 
62  /**
63  * Describes the criteria that can be searched for.
64  */
65  enum Criterion {
66  Name ///< The name of the contact group.
67  };
68 
69  /**
70  * Describes the type of pattern matching that shall be used.
71  *
72  * @since 4.5
73  */
74  enum Match {
75  ExactMatch, ///< The result must match exactly the pattern (case sensitive).
76  StartsWithMatch, ///< The result must start with the pattern (case insensitive).
77  ContainsMatch ///< The result must contain the pattern (case insensitive).
78  };
79 
80  /**
81  * Sets the @p criterion and @p value for the search.
82  */
83  void setQuery(Criterion criterion, const QString &value);
84 
85  /**
86  * Sets the @p criterion and @p value for the search with @p match.
87  * @param criterion the query criterion to compare with
88  * @param value the value to match against
89  * @param match how to match the given value
90  * @since 4.5
91  */
92  void setQuery(Criterion criterion, const QString &value, Match match);
93 
94  /**
95  * Sets a @p limit on how many results will be returned by this search job.
96  * This is useful in situation where for example only the first search result is needed anyway,
97  * setting a limit of 1 here will greatly reduce the resource usage during the
98  * search.
99  * @param limit the limit to set
100  * @note this needs to be called before calling setQuery() to have an effect.
101  * By default, the number of results is unlimited.
102  *
103  * @since 4.4.3
104  */
105  void setLimit(int limit);
106 
107  /**
108  * Returns the contact groups that matched the search criteria.
109  */
110  Q_REQUIRED_RESULT KContacts::ContactGroup::List contactGroups() const;
111 
112 private:
113  //@cond PRIVATE
114  class Private;
115  Private *const d;
116  //@endcond
117 };
118 }
119 
Criterion
Describes the criteria that can be searched for.
The result must start with the pattern (case insensitive).
Match
Describes the type of pattern matching that shall be used.
Job that searches for contact groups in the Akonadi storage.
The result must match exactly the pattern (case sensitive).
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Jun 18 2021 23:08:56 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.