/*
    kopetepropertycontainer.h - Kopete Property Container

    Copyright (c) 2007      by Gustavo Pichorim Boiko <gustavo.boiko@kdemail.net>
    Copyright (c) 2002-2004 by Duncan Mac-Vicar Prett <duncan@kde.org>
    Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
    Copyright (c) 2002-2004 by Olivier Goffart        <ogoffart@kde.org>

    Kopete    (c) 2002-2007 by the Kopete developers  <kopete-devel@kde.org>

    *************************************************************************
    *                                                                       *
    * This library is free software; you can redistribute it and/or         *
    * modify it under the terms of the GNU Lesser General Public            *
    * License as published by the Free Software Foundation; either          *
    * version 2 of the License, or (at your option) any later version.      *
    *                                                                       *
    *************************************************************************
*/

#ifndef KOPETEPROPERTYCONTAINER_H
#define KOPETEPROPERTYCONTAINER_H

#include <QObject>


#include "kopeteglobal.h"
#include "libkopete_export.h"
#include "libkopete_debug.h"

namespace Kopete {
/**
 * @author Gustavo Pichorim Boiko <gustavo.boiko@kdemail.net>
 *
 * This class abstracts a generic contact
 * Use it for inserting contacts in the contact list for example.
 */
class LIBKOPETE_EXPORT PropertyContainer : public QObject
{
    Q_OBJECT

public:
    /**
     * @brief A container for properties.
     *
     * This class provides an interface for reading and writing properties.
     */
    PropertyContainer(QObject *parent = nullptr);

    virtual ~PropertyContainer();

    /**
     * @brief Serialize the persistent properties for storage in the contact list.
     *
     * Does the same as serialize() does but for KopeteContactProperties
     * set in this contact with their persistency flag turned on.
     * In contrary to serialize() this does not need to be reimplemented.
     *
     */
    void serializeProperties(QMap<QString, QString> &serializedData) const;

    /**
     * @brief Deserialize the contacts persistent properties
     */
    void deserializeProperties(const QMap<QString, QString> &serializedData);

    /**
     * @return A QStringList containing all property keys
     **/
    QStringList properties() const;

    /**
     * Check for existence of a certain property stored
     * using "key".
     * \param key the property to check for
     **/
    bool hasProperty(const QString &key) const;

    /**
     * \brief Get the value of a property with key "key".
     *
     * If you don't know the type of the returned QVariant, you will need
     * to check for it.
     * \return the value of the property
     **/
    const Kopete::Property &property(const QString &key) const;
    const Kopete::Property &property(const Kopete::PropertyTmpl &tmpl) const;

    /**
     * \brief Add or Set a property for this contact.
     *
     * @param tmpl The template this property is based on, key, label etc. are
     * taken from this one
     * @param value The value to store
     *
     * \note Setting a NULL value or an empty QString castable value
     * removes the property if it already existed.
     * <b>Don't</b> abuse this for property-removal, instead use
     * @ref removeProperty() if you want to remove on purpose.
     * The Removal is done to clean up the list of properties and to purge them
     * from UI.
     **/
    void setProperty(const Kopete::PropertyTmpl &tmpl, const QVariant &value);

    /**
     * \brief Remove a property if it exists
     *
     * @param tmpl the template this property is based on
     **/
    void removeProperty(const Kopete::PropertyTmpl &tmpl);

Q_SIGNALS:
    void propertyChanged(Kopete::PropertyContainer *container, const QString &key, const QVariant &oldValue, const QVariant &newValue);

private:
    class Private;
    Private *const d;
};
} //END namespace Kopete

#endif
