Akonadi

collectionpropertiespage.h
1 /*
2  SPDX-FileCopyrightText: 2008 Volker Krause <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "akonadiwidgets_export.h"
10 
11 #include <QWidget>
12 
13 #include <memory>
14 
15 namespace Akonadi
16 {
17 class Collection;
18 class CollectionPropertiesPagePrivate;
19 
20 /**
21  * @short A single page in a collection properties dialog.
22  *
23  * The collection properties dialog can be extended by custom
24  * collection properties pages, which provide gui elements for
25  * viewing and changing collection attributes.
26  *
27  * The following example shows how to create a simple collection
28  * properties page for the secrecy attribute from the Akonadi::Attribute
29  * example.
30  *
31  * @code
32  *
33  * class SecrecyPage : public CollectionPropertiesPage
34  * {
35  * public:
36  * SecrecyPage( QWidget *parent = nullptr )
37  * : CollectionPropertiesPage( parent )
38  * {
39  * QVBoxLayout *layout = new QVBoxLayout( this );
40  *
41  * mSecrecy = new QComboBox( this );
42  * mSecrecy->addItem( "Public" );
43  * mSecrecy->addItem( "Private" );
44  * mSecrecy->addItem( "Confidential" );
45  *
46  * layout->addWidget( new QLabel( "Secrecy:" ) );
47  * layout->addWidget( mSecrecy );
48  *
49  * setPageTitle( i18n( "Secrecy" ) );
50  * }
51  *
52  * void load( const Collection &collection )
53  * {
54  * SecrecyAttribute *attr = collection.attribute( "secrecy" );
55  *
56  * switch ( attr->secrecy() ) {
57  * case SecrecyAttribute::Public: mSecrecy->setCurrentIndex( 0 ); break;
58  * case SecrecyAttribute::Private: mSecrecy->setCurrentIndex( 1 ); break;
59  * case SecrecyAttribute::Confidential: mSecrecy->setCurrentIndex( 2 ); break;
60  * }
61  * }
62  *
63  * void save( Collection &collection )
64  * {
65  * SecrecyAttribute *attr = collection.attribute( "secrecy" );
66  *
67  * switch ( mSecrecy->currentIndex() ) {
68  * case 0: attr->setSecrecy( SecrecyAttribute::Public ); break;
69  * case 1: attr->setSecrecy( SecrecyAttribute::Private ); break;
70  * case 2: attr->setSecrecy( SecrecyAttribute::Confidential ); break;
71  * }
72  * }
73  *
74  * bool canHandle( const Collection &collection ) const
75  * {
76  * return collection.hasAttribute( "secrecy" );
77  * }
78  * };
79  *
80  * AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY( SecrecyPageFactory, SecrecyPage )
81  *
82  * @endcode
83  *
84  * @see Akonadi::CollectionPropertiesDialog, Akonadi::CollectionPropertiesPageFactory
85  *
86  * @author Volker Krause <[email protected]>
87  */
88 class AKONADIWIDGETS_EXPORT CollectionPropertiesPage : public QWidget
89 {
90  Q_OBJECT
91 public:
92  /**
93  * Creates a new collection properties page.
94  *
95  * @param parent The parent widget.
96  */
97  explicit CollectionPropertiesPage(QWidget *parent = nullptr);
98 
99  /**
100  * Destroys the collection properties page.
101  */
102  ~CollectionPropertiesPage() override;
103 
104  /**
105  * Loads the page content from the given collection.
106  *
107  * @param collection The collection to load.
108  */
109  virtual void load(const Collection &collection) = 0;
110 
111  /**
112  * Saves page content to the given collection.
113  *
114  * @param collection Reference to the collection to save to.
115  */
116  virtual void save(Collection &collection) = 0;
117 
118  /**
119  * Checks if this page can actually handle the given collection.
120  *
121  * Returns @c true if the collection can be handled, @c false otherwise
122  * The default implementation returns always @c true. When @c false is returned
123  * this page is not shown in the properties dialog.
124  * @param collection The collection to check.
125  */
126  virtual bool canHandle(const Collection &collection) const;
127 
128  /**
129  * Sets the page title.
130  *
131  * @param title Translated, preferably short tab title.
132  */
133  void setPageTitle(const QString &title);
134 
135  /**
136  * Returns the page title.
137  */
138  Q_REQUIRED_RESULT QString pageTitle() const;
139 
140 private:
141  /// @cond PRIVATE
142  std::unique_ptr<CollectionPropertiesPagePrivate> const d;
143  /// @endcond
144 };
145 
146 /**
147  * @short A factory class for collection properties dialog pages.
148  *
149  * The factory encapsulates the creation of the collection properties
150  * dialog page.
151  * You can use the AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY macro
152  * to create a factory class automatically.
153  *
154  * @author Volker Krause <[email protected]>
155  */
156 class AKONADIWIDGETS_EXPORT CollectionPropertiesPageFactory
157 {
158 public:
159  /**
160  * Destroys the collection properties page factory.
161  */
163 
164  /**
165  * Returns the actual page widget.
166  *
167  * @param parent The parent widget.
168  */
169  virtual CollectionPropertiesPage *createWidget(QWidget *parent = nullptr) const = 0;
170 
171 protected:
172  explicit CollectionPropertiesPageFactory() = default;
173 
174 private:
175  Q_DISABLE_COPY_MOVE(CollectionPropertiesPageFactory)
176 };
177 
178 /**
179  * @def AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY
180  *
181  * The AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY macro can be used to
182  * create a factory for a custom collection properties page.
183  *
184  * @code
185  *
186  * class MyPage : public Akonadi::CollectionPropertiesPage
187  * {
188  * ...
189  * }
190  *
191  * AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY( MyPageFactory, MyPage )
192  *
193  * @endcode
194  *
195  * The macro takes two arguments, where the first one is the name of the
196  * factory class that shall be created and the second arguments is the name
197  * of the custom collection properties page class.
198  *
199  * @ingroup AkonadiMacros
200  */
201 #define AKONADI_COLLECTION_PROPERTIES_PAGE_FACTORY(factoryName, className) \
202  class factoryName : public Akonadi::CollectionPropertiesPageFactory \
203  { \
204  public: \
205  inline Akonadi::CollectionPropertiesPage *createWidget(QWidget *parent = nullptr) const override \
206  { \
207  return new className(parent); \
208  } \
209  };
210 
211 }
Represents a collection of PIM items.
Definition: collection.h:61
A single page in a collection properties dialog.
A factory class for collection properties dialog pages.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Oct 3 2023 04:01:59 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.