kopete/libkopete/kopeteproperty.h

   1 /*
   2     kopeteproperty.h
   3
   4     Kopete::Property class
   5
   6     Copyright (c) 2007    by Gustavo Pichorim Boiko <gustavo.boiko@kdemail.net>
   7     Copyright (c) 2004    by Stefan Gehn <metz AT gehn.net>
   8     Copyright (c) 2006    by Michaël Larouche <larouche@kde.org>
   9
  10     Kopete    (c) 2004-2007    by the Kopete developers <kopete-devel@kde.org>
  11
  12     *************************************************************************
  13     *                                                                       *
  14     * This library is free software; you can redistribute it and/or         *
  15     * modify it under the terms of the GNU Lesser General Public            *
  16     * License as published by the Free Software Foundation; either          *
  17     * version 2 of the License, or (at your option) any later version.      *
  18     *                                                                       *
  19     *************************************************************************
  20 */
  21
  22 #ifndef _KOPETEPROPERTY_H_
  23 #define _KOPETEPROPERTY_H_
  24
  25 #include <QtCore/QVariant>
  26 #include <QtCore/QFlags>
  27
  28 #include "kopete_export.h"
  29
  30 namespace Kopete
  31 {
  32
  33 /**
  34  * @author Stefan Gehn <metz AT gehn.net>
  35  * @author Michaël Larouche <larouche@kde.org>
  36  *
  37  * The template class for registering properties in Kopete
  38  * You need to use this if you want to set properties for a
  39  * Kopete::Contact
  40  **/
  41 class KOPETE_EXPORT PropertyTmpl
  42 {
  43         public:
  44                 enum PropertyOption
  45                 {
  46                         NoProperty = 0x0,
  47                         PersistentProperty = 0x1,
  48                         RichTextProperty = 0x2,
  49                         PrivateProperty = 0x4
  50                 };
  51                 Q_DECLARE_FLAGS(PropertyOptions, PropertyOption)
  52
  53                 /**
  54                  * Constructor only used for empty PropertyTmpl objects
  55                  *
  56                  * Note: Only useful for the null object
  57                  **/
  58                 PropertyTmpl();
  59
  60                 /**
  61                  * Constructor
  62                  * @param key internal unique key for this template
  63                  * @param label a label to show for properties based on this template
  64                  * @param icon name of the icon to show for properties based on this template
  65                  * @param options set the options for that property. See PropertyOption enum.
  66                  **/
  67                 PropertyTmpl( const QString &key,
  68                         const QString &label,
  69                         const QString &icon = QString(),
  70                         PropertyOptions options = NoProperty);
  71
  72                 /**
  73                  * Copy constructor
  74                  **/
  75                 PropertyTmpl(const PropertyTmpl &other);
  76
  77                 /** Destructor */
  78                 ~PropertyTmpl();
  79
  80                 PropertyTmpl &operator=(const PropertyTmpl &other);
  81
  82                 bool operator==(const PropertyTmpl &other) const;
  83                 bool operator!=(const PropertyTmpl &other) const;
  84
  85                 /**
  86                  * Getter for the unique key. Properties based on this template will be
  87                  * stored with this key
  88                  **/
  89                 const QString &key() const;
  90
  91                 /**
  92                  * Getter for i18ned label
  93                  **/
  94                 const QString &label() const;
  95
  96                 /**
  97                  * Getter for icon to show aside or instead of @p label()
  98                  **/
  99                 const QString &icon() const;
 100
 101                 /**
 102                  * Return the options for that property.
 103                  */
 104                 PropertyOptions options() const;
 105
 106                 /**
 107                  * Returns true if properties based on this template should
 108                  * be saved across Kopete sessions, false otherwise.
 109                  **/
 110                 bool persistent() const;
 111
 112                 /**
 113                  * Returns true if properties based on this template are HTML formatted
 114                  **/
 115                 bool isRichText() const;
 116
 117                 /**
 118                  * Returns true if properties based on this template are invisible to the user
 119                  **/
 120                 bool isPrivate() const;
 121
 122                 /**
 123                  * An empty template, check for it using isNull()
 124                  */
 125                 static PropertyTmpl null;
 126
 127                 /**
 128                  * Returns true if this object is an empty template
 129                  **/
 130                 bool isNull() const;
 131
 132                 /**
 133                  * A Map of QString and PropertyTmpl objects, based on QMap
 134                  **/
 135                 typedef QMap<QString, PropertyTmpl>  Map;
 136
 137         private:
 138                 class Private;
 139                 Private *d;
 140 };
 141
 142 Q_DECLARE_OPERATORS_FOR_FLAGS(PropertyTmpl::PropertyOptions)
 143
 144 /**
 145  * @author Stefan Gehn <metz AT gehn.net>
 146  *
 147  * A data container for whatever information Kopete or any of its
 148  * plugins want to store for a Kopete::Contact
 149  **/
 150 class KOPETE_EXPORT Property
 151 {
 152         public:
 153                 /**
 154                  * Constructor only used for empty Property objects
 155                  *
 156                  * Note: you cannot set a label or value later on!
 157                  **/
 158                 Property();
 159
 160                 /**
 161                  * @param tmpl The contact property template this property is based on
 162                  * @param value The value this Property holds
 163                  **/
 164                 Property(const PropertyTmpl &tmpl, const QVariant &value);
 165
 166                 /**
 167                  * Copy constructor
 168                  **/
 169                 Property(const Property &other);
 170
 171                 /** Destructor **/
 172                 ~Property();
 173
 174                 Property &operator=(const Property &other);
 175
 176                 /**
 177                  * Getter for this properties template
 178                  **/
 179                 const PropertyTmpl &tmpl() const;
 180
 181                 /**
 182                  * Getter for this properties value
 183                  **/
 184                 const QVariant &value() const;
 185
 186                 /**
 187                  * The null, i.e. empty, Property
 188                  */
 189                 static Property null;
 190
 191                 /**
 192                  * Returns true if this object is an empty Property (i.e. it holds no
 193                  * value), false otherwise.
 194                  **/
 195                 bool isNull() const;
 196
 197                 /**
 198                  * Returns true if this property is HTML formatted
 199                  **/
 200                 bool isRichText() const;
 201
 202                 /**
 203                  * A map of key,Property items
 204                  **/
 205                 typedef QMap<QString, Property> Map;
 206
 207         private:
 208                 class Private;
 209                 Private *d;
 210 };
 211
 212 } // END namespace Kopete
 213
 214 #endif //_KOPETEPROPERTY_H_