/***************************************************************************
 * object.h
 * This file is part of the KDE project
 * copyright (C)2004-2006 by Sebastian Sauer (mail@dipe.org)
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 * You should have received a copy of the GNU Library General Public License
 * along with this program; see the file COPYING.  If not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 ***************************************************************************/

#ifndef KROSS_OBJECT_H
#define KROSS_OBJECT_H

#include <QtCore/QString>
#include <QtCore/QStringList>
#include <QtCore/QMap>
#include <QtCore/QVariant>
#include <QtCore/QSharedData>
#include <QtCore/QExplicitlySharedDataPointer>

#include "krossconfig.h"
#include "errorinterface.h"

namespace Kross
{

/**
 * The class Object does provide us scripting objects like
 * class instances to the C++ world.
 *
 * This class implementates reference counting for shared
 * objects. So, no need to take care of freeing objects.
 *
 * Sample that does use the \a Object functionality to
 * pass a Javascript classinstance to C++ code which then
 * calls a method the classinstance provides.
 * \code
 * class MyObject : public QObject
 * {
 *     public Q_SLOTS:
 *         QVariant myFunction(Kross::Object::Ptr obj) {
 *             QVariantList args;
 *             return obj->callMethod("myMethod", args);
 *         }
 * };
 * \endcode
 * \code
 * function MyClass(result) {
 *     this.myMethod = function() {
 *         return result;
 *     }
 * }
 * var myclass = new MyClass("my string");
 * var r = MyObject.myFunction(myclass);
 * print(r); // prints "my string"
 * \endcode
 *
 * \since 4.1
 */
class KROSSCORE_EXPORT Object : public QSharedData, public ErrorInterface
{
public:

    /**
     * Shared pointer to implement reference-counting.
     */
    typedef QExplicitlySharedDataPointer<Object> Ptr;

    /**
     * Default constructor.
     */
    explicit Object();

    /**
     * Copy constructor.
     */
    Object(const Object &other);

    /**
     * Destructor.
     */
    virtual ~Object();

    /**
     * Pass a call to the object and evaluated it.
     *
     * \param name Each call has a name that says what
     * should be called.
     * \param args The optional list of arguments
     * passed to the call.
     * \return The call-result as QVariant.
     */
    virtual QVariant callMethod(const QString &name,
                                const QVariantList &args = QVariantList());

    /**
     * Return a list of supported callable objects.
     *
     * \return List of supported calls.
     */
    virtual QStringList methodNames();

    /**
     * \internal used virtual hook to easier the job to keep
     * binary compatibility.
     */
    virtual void virtual_hook(int id, void *ptr);

private:
    /// \internal d-pointer class.
    class Private;
    /// \internal d-pointer instance.
    Private *const d;
};
}

Q_DECLARE_METATYPE(Kross::Object::Ptr)

#endif

