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 | |
24 | namespace 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 | */ |
92 | class 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 | |