Akonadi

collectionpropertiespage.h
1/*
2 SPDX-FileCopyrightText: 2008 Volker Krause <vkrause@kde.org>
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
15namespace Akonadi
16{
17class Collection;
18class 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 <vkrause@kde.org>
87 */
88class AKONADIWIDGETS_EXPORT CollectionPropertiesPage : public QWidget
89{
90 Q_OBJECT
91public:
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 */
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 [[nodiscard]] QString pageTitle() const;
139
140private:
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 <vkrause@kde.org>
155 */
156class AKONADIWIDGETS_EXPORT CollectionPropertiesPageFactory
157{
158public:
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
171protected:
172 explicit CollectionPropertiesPageFactory() = default;
173
174private:
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}
A factory class for collection properties dialog pages.
virtual CollectionPropertiesPage * createWidget(QWidget *parent=nullptr) const =0
Returns the actual page widget.
A single page in a collection properties dialog.
~CollectionPropertiesPage() override
Destroys the collection properties page.
virtual void load(const Collection &collection)=0
Loads the page content from the given collection.
virtual void save(Collection &collection)=0
Saves page content to the given collection.
Represents a collection of PIM items.
Definition collection.h:62
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.