Akonadi Contacts

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

KDE's Doxygen guidelines are available online.