Akonadi

abstractdifferencesreporter.h
1/*
2 SPDX-FileCopyrightText: 2010 KDAB
3 SPDX-FileContributor: Tobias Koenig <tokoe@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#pragma once
9
10namespace Akonadi
11{
12/**
13 * @short An interface to report differences between two arbitrary objects.
14 *
15 * This interface can be used to report differences between two arbitrary objects
16 * by describing a virtual table with three columns. The first column contains the name
17 * of the property that is compared, the second column the property value of the one
18 * object and the third column the property of the other object.
19 *
20 * The rows of this table can have different modes:
21 * @li NormalMode The left and right columns show the same property values.
22 * @li ConflictMode The left and right columns show conflicting property values.
23 * @li AdditionalLeftMode The left column contains a property value that is not available in the right column.
24 * @li AdditionalRightMode The right column contains a property value that is not available in the left column.
25 *
26 * Example:
27 *
28 * @code
29 * // add differences of a contact
30 * const KContacts::Addressee contact1 = ...
31 * const KContacts::Addressee contact2 = ...
32 *
33 * AbstractDifferencesReporter *reporter = ...
34 * reporter->setPropertyNameTitle( i18n( "Contact fields" ) );
35 * reporter->setLeftPropertyValueTitle( i18n( "Changed Contact" ) );
36 * reporter->setRightPropertyValueTitle( i18n( "Conflicting Contact" ) );
37 *
38 * // check given name
39 * if ( contact1.givenName() != contact2.givenName() )
40 * reporter->addProperty( AbstractDifferencesReporter::ConflictMode, i18n( "Given Name" ),
41 * contact1.givenName(), contact2.givenName() );
42 * else
43 * reporter->addProperty( AbstractDifferencesReporter::NormalMode, i18n( "Given Name" ),
44 * contact1.givenName(), contact2.givenName() );
45 *
46 * // check family name
47 * if ( contact1.familyName() != contact2.familyName() )
48 * reporter->addProperty( AbstractDifferencesReporter::ConflictMode, i18n( "Family Name" ),
49 * contact1.givenName(), contact2.givenName() );
50 * else
51 * reporter->addProperty( AbstractDifferencesReporter::NormalMode, i18n( "Family Name" ),
52 * contact1.givenName(), contact2.givenName() );
53 *
54 * // check emails
55 * const QStringList leftEmails = contact1.emails();
56 * const QStringList rightEmails = contact2.emails();
57 *
58 * for ( const QString &leftEmail : leftEmails ) {
59 * if ( rightEmails.contains( leftEmail ) )
60 * reporter->addProperty( AbstractDifferencesReporter::NormalMode, i18n( "Email" ),
61 * leftEmail, leftEmail );
62 * else
63 * reporter->addProperty( AbstractDifferencesReporter::AdditionalLeftMode, i18n( "Email" ),
64 * leftEmail, QString() );
65 * }
66 *
67 * for( const QString &rightEmail : rightEmails ) {
68 * if ( !leftEmails.contains( rightEmail ) )
69 * reporter->addProperty( AbstractDifferencesReporter::AdditionalRightMode, i18n( "Email" ),
70 * QString(), rightEmail );
71 * }
72 *
73 * @endcode
74 *
75 * @author Tobias Koenig <tokoe@kde.org>
76 * @since 4.6
77 */
79{
80public:
81 /**
82 * Describes the property modes.
83 */
84 enum Mode {
85 NormalMode, ///< The left and right column show the same property values.
86 ConflictMode, ///< The left and right column show conflicting property values.
87 AdditionalLeftMode, ///< The left column contains a property value that is not available in the right column.
88 AdditionalRightMode ///< The right column contains a property value that is not available in the left column.
89 };
90
91 /**
92 * Destroys the abstract differences reporter.
93 */
94 virtual ~AbstractDifferencesReporter() = default;
95
96 /**
97 * Sets the @p title of the property name column.
98 */
99 virtual void setPropertyNameTitle(const QString &title) = 0;
100
101 /**
102 * Sets the @p title of the column that shows the property values
103 * of the left object.
104 */
105 virtual void setLeftPropertyValueTitle(const QString &title) = 0;
106
107 /**
108 * Sets the @p title of the column that shows the property values
109 * of the right object.
110 */
111 virtual void setRightPropertyValueTitle(const QString &title) = 0;
112
113 /**
114 * Adds a new property entry to the table.
115 *
116 * @param mode Describes the mode of the property. If mode is AdditionalLeftMode or AdditionalRightMode, rightValue resp. leftValue
117 * should be QString().
118 * @param name The user visible name of the property.
119 * @param leftValue The user visible property value of the left object.
120 * @param rightValue The user visible property value of the right object.
121 */
122 virtual void addProperty(Mode mode, const QString &name, const QString &leftValue, const QString &rightValue) = 0;
123
124protected:
125 explicit AbstractDifferencesReporter() = default;
126
127private:
128 Q_DISABLE_COPY_MOVE(AbstractDifferencesReporter)
129};
130
131}
An interface to report differences between two arbitrary objects.
virtual void addProperty(Mode mode, const QString &name, const QString &leftValue, const QString &rightValue)=0
Adds a new property entry to the table.
virtual ~AbstractDifferencesReporter()=default
Destroys the abstract differences reporter.
virtual void setPropertyNameTitle(const QString &title)=0
Sets the title of the property name column.
@ AdditionalLeftMode
The left column contains a property value that is not available in the right column.
@ NormalMode
The left and right column show the same property values.
@ ConflictMode
The left and right column show conflicting property values.
@ AdditionalRightMode
The right column contains a property value that is not available in the left column.
virtual void setRightPropertyValueTitle(const QString &title)=0
Sets the title of the column that shows the property values of the right object.
virtual void setLeftPropertyValueTitle(const QString &title)=0
Sets the title of the column that shows the property values of the left object.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 8 2024 11:54:19 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.