1/*
2 Copyright (c) 2007-2008 Tobias Koenig <tokoe@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_ITEMMONITOR_H
21#define AKONADI_ITEMMONITOR_H
22
23#include "akonadi_export.h"
24#include <qglobal.h>
25
26class QStringList;
27
28namespace Akonadi {
29
30class Item;
31class ItemFetchScope;
32
33/**
34 * @short A convenience class to monitor a single item for changes.
35 *
36 * This class can be used as a base class for classes that want to show
37 * a single item to the user and keep track of status changes of the item
38 * without having to using a Monitor object themself.
39 *
40 * Example:
41 *
42 * @code
43 *
44 * // A label that shows the name of a contact item
45 *
46 * class ContactLabel : public QLabel, public Akonadi::ItemMonitor
47 * {
48 * public:
49 * ContactLabel( QWidget *parent = 0 )
50 * : QLabel( parent )
51 * {
52 * setText( "No Name" );
53 * }
54 *
55 * protected:
56 * virtual void itemChanged( const Akonadi::Item &item )
57 * {
58 * if ( item.mimeType() != "text/directory" )
59 * return;
60 *
61 * const KABC::Addressee addr = item.payload<KABC::Addressee>();
62 * setText( addr.fullName() );
63 * }
64 *
65 * virtual void itemRemoved()
66 * {
67 * setText( "No Name" );
68 * }
69 * };
70 *
71 * ...
72 *
73 * ContactLabel *label = new ContactLabel( this );
74 *
75 * const Akonadi::Item item = fetchJob->items().first();
76 * label->setItem( item );
77 *
78 * @endcode
79 *
80 * @author Tobias Koenig <tokoe@kde.org>
81 */
82class AKONADI_EXPORT ItemMonitor
83{
84public:
85 /**
86 * Creates a new item monitor.
87 */
88 ItemMonitor();
89
90 /**
91 * Destroys the item monitor.
92 */
93 virtual ~ItemMonitor();
94
95 /**
96 * Sets the @p item that shall be monitored.
97 */
98 void setItem(const Item &item);
99
100 /**
101 * Returns the currently monitored item.
102 */
103 Item item() const;
104
105protected:
106 /**
107 * This method is called whenever the monitored item has changed.
108 *
109 * @param item The changed item.
110 */
111 virtual void itemChanged(const Item &item);
112
113 /**
114 * This method is called whenever the monitored item has been removed.
115 */
116 virtual void itemRemoved();
117
118 /**
119 * Sets the item fetch scope.
120 *
121 * Controls how much of an item's data is fetched from the server, e.g.
122 * whether to fetch the full item payload or only meta data.
123 *
124 * @param fetchScope The new scope for item fetch operations.
125 *
126 * @see fetchScope()
127 */
128 void setFetchScope(const ItemFetchScope &fetchScope);
129
130 /**
131 * Returns the item fetch scope.
132 *
133 * Since this returns a reference it can be used to conveniently modify the
134 * current scope in-place, i.e. by calling a method on the returned reference
135 * without storing it in a local variable. See the ItemFetchScope documentation
136 * for an example.
137 *
138 * @return a reference to the current item fetch scope
139 *
140 * @see setFetchScope() for replacing the current item fetch scope
141 */
142 ItemFetchScope &fetchScope();
143
144private:
145 //@cond PRIVATE
146 class Private;
147 Private *const d;
148 //@endcond
149
150 Q_DISABLE_COPY(ItemMonitor)
151};
152
153}
154
155#endif
156