1/*
2 Copyright (c) 2010 KDAB
3 Author: Tobias Koenig <tokoe@kde.org>
4
5 This library is free software; you can redistribute it and/or modify it
6 under the terms of the GNU Library General Public License as published by
7 the Free Software Foundation; either version 2 of the License, or (at your
8 option) any later version.
9
10 This library is distributed in the hope that it will be useful, but WITHOUT
11 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18 02110-1301, USA.
19*/
20
21#ifndef ABSTRACTDIFFERENCESREPORTER_P_H
22#define ABSTRACTDIFFERENCESREPORTER_P_H
23
24namespace Akonadi {
25
26/**
27 * @short An interface to report differences between two arbitrary objects.
28 *
29 * This interface can be used to report differences between two arbitrary objects
30 * by describing a virtual table with three columns. The first column contains the name
31 * of the property that is compared, the second column the property value of the one
32 * object and the third column the property of the other object.
33 *
34 * The rows of this table can have different modes:
35 * @li NormalMode The left and right columns show the same property values.
36 * @li ConflictMode The left and right columns show conflicting property values.
37 * @li AdditionalLeftMode The left column contains a property value that is not available in the right column.
38 * @li AdditionalRightMode The right column contains a property value that is not available in the left column.
39 *
40 * Example:
41 *
42 * @code
43 * // add differences of a contact
44 * const KABC::Addressee contact1 = ...
45 * const KABC::Addressee contact2 = ...
46 *
47 * AbstractDifferencesReporter *reporter = ...
48 * reporter->setPropertyNameTitle( i18n( "Contact fields" ) );
49 * reporter->setLeftPropertyValueTitle( i18n( "Changed Contact" ) );
50 * reporter->setRightPropertyValueTitle( i18n( "Conflicting Contact" ) );
51 *
52 * // check given name
53 * if ( contact1.givenName() != contact2.givenName() )
54 * reporter->addProperty( AbstractDifferencesReporter::ConflictMode, i18n( "Given Name" ),
55 * contact1.givenName(), contact2.givenName() );
56 * else
57 * reporter->addProperty( AbstractDifferencesReporter::NormalMode, i18n( "Given Name" ),
58 * contact1.givenName(), contact2.givenName() );
59 *
60 * // check family name
61 * if ( contact1.familyName() != contact2.familyName() )
62 * reporter->addProperty( AbstractDifferencesReporter::ConflictMode, i18n( "Family Name" ),
63 * contact1.givenName(), contact2.givenName() );
64 * else
65 * reporter->addProperty( AbstractDifferencesReporter::NormalMode, i18n( "Family Name" ),
66 * contact1.givenName(), contact2.givenName() );
67 *
68 * // check emails
69 * const QStringList leftEmails = contact1.emails();
70 * const QStringList rightEmails = contact2.emails();
71 *
72 * foreach ( const QString &leftEmail, leftEmails ) {
73 * if ( rightEmails.contains( leftEmail ) )
74 * reporter->addProperty( AbstractDifferencesReporter::NormalMode, i18n( "Email" ),
75 * leftEmail, leftEmail );
76 * else
77 * reporter->addProperty( AbstractDifferencesReporter::AdditionalLeftMode, i18n( "Email" ),
78 * leftEmail, QString() );
79 * }
80 *
81 * foreach ( const QString &rightEmail, rightEmails ) {
82 * if ( !leftEmails.contains( rightEmail ) )
83 * reporter->addProperty( AbstractDifferencesReporter::AdditionalRightMode, i18n( "Email" ),
84 * QString(), rightEmail );
85 * }
86 *
87 * @endcode
88 *
89 * @author Tobias Koenig <tokoe@kde.org>
90 * @since 4.6
91 */
92class AbstractDifferencesReporter
93{
94 public:
95 /**
96 * Describes the property modes.
97 */
98 enum Mode {
99 NormalMode, ///< The left and right column show the same property values.
100 ConflictMode, ///< The left and right column show conflicting property values.
101 AdditionalLeftMode, ///< The left column contains a property value that is not available in the right column.
102 AdditionalRightMode ///< The right column contains a property value that is not available in the left column.
103 };
104
105 /**
106 * Destroys the abstract differences reporter.
107 */
108 virtual ~AbstractDifferencesReporter() {}
109
110 /**
111 * Sets the @p title of the property name column.
112 */
113 virtual void setPropertyNameTitle( const QString &title ) = 0;
114
115 /**
116 * Sets the @p title of the column that shows the property values
117 * of the left object.
118 */
119 virtual void setLeftPropertyValueTitle( const QString &title ) = 0;
120
121 /**
122 * Sets the @p title of the column that shows the property values
123 * of the right object.
124 */
125 virtual void setRightPropertyValueTitle( const QString &title ) = 0;
126
127 /**
128 * Adds a new property entry to the table.
129 *
130 * @param mode Describes the mode of the property. If mode is AdditionalLeftMode or AdditionalRightMode, rightValue resp. leftValue
131 * should be QString().
132 * @param name The user visible name of the property.
133 * @param leftValue The user visible property value of the left object.
134 * @param rightValue The user visible property value of the right object.
135 */
136 virtual void addProperty( Mode mode, const QString &name, const QString &leftValue, const QString &rightValue ) = 0;
137};
138
139}
140
141#endif
142