Akonadi

abstractdifferencesreporter.h
1 /*
2  SPDX-FileCopyrightText: 2010 KDAB
3  SPDX-FileContributor: Tobias Koenig <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #pragma once
9 
10 namespace 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 <[email protected]>
76  * @since 4.6
77  */
79 {
80 public:
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 
124 protected:
125  explicit AbstractDifferencesReporter() = default;
126 
127 private:
128  Q_DISABLE_COPY_MOVE(AbstractDifferencesReporter)
129 };
130 
131 }
132 
virtual void setPropertyNameTitle(const QString &title)=0
Sets the title of the property name column.
virtual void addProperty(Mode mode, const QString &name, const QString &leftValue, const QString &rightValue)=0
Adds a new property entry to the table.
virtual void setLeftPropertyValueTitle(const QString &title)=0
Sets the title of the column that shows the property values of the left object.
@ 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.
An interface to report differences between two arbitrary objects.
virtual void setRightPropertyValueTitle(const QString &title)=0
Sets the title of the column that shows the property values of the right object.
virtual ~AbstractDifferencesReporter()=default
Destroys the abstract differences reporter.
@ 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.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Jun 30 2022 03:51:45 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.