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 | |
26 | class QStringList; |
27 | |
28 | namespace Akonadi { |
29 | |
30 | class Item; |
31 | class 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 | */ |
82 | class AKONADI_EXPORT ItemMonitor |
83 | { |
84 | public: |
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 | |
105 | protected: |
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 | |
144 | private: |
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 | |