Akonadi

itemmonitor.h
1 /*
2  SPDX-FileCopyrightText: 2007-2008 Tobias Koenig <[email protected]>
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 
14 namespace Akonadi
15 {
16 class Item;
17 class ItemFetchScope;
18 class 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 <[email protected]>
68  */
69 class AKONADICORE_EXPORT ItemMonitor
70 {
71 public:
72  /**
73  * Creates a new item monitor.
74  */
75  ItemMonitor();
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 
92 protected:
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 
131 private:
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 }
141 
A convenience class to monitor a single item for changes.
Definition: itemmonitor.h:69
Represents a PIM item stored in Akonadi storage.
Definition: item.h:104
Specifies which parts of an item should be fetched from the Akonadi storage.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Jun 30 2022 03:51:46 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.