Akonadi

itemmonitor.h
1/*
2 SPDX-FileCopyrightText: 2007-2008 Tobias Koenig <tokoe@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "akonadicore_export.h"
10#include <qglobal.h>
11
12#include <memory>
13
14namespace Akonadi
15{
16class Item;
17class ItemFetchScope;
18class ItemMonitorPrivate;
19
20/**
21 * @short A convenience class to monitor a single item for changes.
22 *
23 * This class can be used as a base class for classes that want to show
24 * a single item to the user and keep track of status changes of the item
25 * without having to using a Monitor object themself.
26 *
27 * Example:
28 *
29 * @code
30 *
31 * // A label that shows the name of a contact item
32 *
33 * class ContactLabel : public QLabel, public Akonadi::ItemMonitor
34 * {
35 * public:
36 * ContactLabel( QWidget *parent = nullptr )
37 * : QLabel( parent )
38 * {
39 * setText( "No Name" );
40 * }
41 *
42 * protected:
43 * virtual void itemChanged( const Akonadi::Item &item )
44 * {
45 * if ( item.mimeType() != "text/directory" )
46 * return;
47 *
48 * const KContacts::Addressee addr = item.payload<KContacts::Addressee>();
49 * setText( addr.fullName() );
50 * }
51 *
52 * virtual void itemRemoved()
53 * {
54 * setText( "No Name" );
55 * }
56 * };
57 *
58 * ...
59 *
60 * ContactLabel *label = new ContactLabel( this );
61 *
62 * const Akonadi::Item item = fetchJob->items().at(0);
63 * label->setItem( item );
64 *
65 * @endcode
66 *
67 * @author Tobias Koenig <tokoe@kde.org>
68 */
69class AKONADICORE_EXPORT ItemMonitor
70{
71public:
72 /**
73 * Creates a new item monitor.
74 */
76
77 /**
78 * Destroys the item monitor.
79 */
80 virtual ~ItemMonitor();
81
82 /**
83 * Sets the @p item that shall be monitored.
84 */
85 void setItem(const Item &item);
86
87 /**
88 * Returns the currently monitored item.
89 */
90 Item item() const;
91
92protected:
93 /**
94 * This method is called whenever the monitored item has changed.
95 *
96 * @param item The changed item.
97 */
98 virtual void itemChanged(const Item &item);
99
100 /**
101 * This method is called whenever the monitored item has been removed.
102 */
103 virtual void itemRemoved();
104
105 /**
106 * Sets the item fetch scope.
107 *
108 * Controls how much of an item's data is fetched from the server, e.g.
109 * whether to fetch the full item payload or only meta data.
110 *
111 * @param fetchScope The new scope for item fetch operations.
112 *
113 * @see fetchScope()
114 */
115 void setFetchScope(const ItemFetchScope &fetchScope);
116
117 /**
118 * Returns the item fetch scope.
119 *
120 * Since this returns a reference it can be used to conveniently modify the
121 * current scope in-place, i.e. by calling a method on the returned reference
122 * without storing it in a local variable. See the ItemFetchScope documentation
123 * for an example.
124 *
125 * @return a reference to the current item fetch scope
126 *
127 * @see setFetchScope() for replacing the current item fetch scope
128 */
129 ItemFetchScope &fetchScope();
130
131private:
132 /// @cond PRIVATE
133 friend class ItemMonitorPrivate;
134 std::unique_ptr<ItemMonitorPrivate> const d;
135 /// @endcond
136
137 Q_DISABLE_COPY(ItemMonitor)
138};
139
140}
Specifies which parts of an item should be fetched from the Akonadi storage.
A convenience class to monitor a single item for changes.
Definition itemmonitor.h:70
virtual ~ItemMonitor()
Destroys the item monitor.
Represents a PIM item stored in Akonadi storage.
Definition item.h:101
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:13:38 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.