You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
koffice/lib/kross/main/scriptcontainer.h

211 lines
7.0 KiB

/***************************************************************************
* scriptcontainer.h
* This file is part of the KDE project
* copyright (C)2004-2005 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_API_SCRIPTCONTAINER_H
#define KROSS_API_SCRIPTCONTAINER_H
#include "mainmodule.h"
#include <qstring.h>
#include <qvariant.h>
#include <qobject.h>
#include <ksharedptr.h>
namespace Kross { namespace Api {
// Forward declarations.
class Object;
class List;
class ScriptContainerPrivate;
/**
* The ScriptContainer class is something like a single
* standalone scriptfile.
*
* Once you've such a ScriptContainer instance you're
* able to perform actions with it like to execute
* scripting code. The \a Manager takes care of
* handling the ScriptContainer instances application
* width.
*
* The class \a ScriptAction provides a higher level class
* to work with a \a ScriptContainer instances.
*/
class ScriptContainer : public MainModule
{
// We protected the constructor cause ScriptContainer
// instances should be created only within the
// Manager::getScriptContainer() method.
friend class Manager;
protected:
/**
* Constructor.
*
* The constructor is protected cause only with the
* \a ScriptManager it's possible to access
* \a ScriptContainer instances.
*
* \param name The unique name this ScriptContainer
* has. It's used e.g. at the \a Manager to
* identify the ScriptContainer.
*/
explicit ScriptContainer(const QString& name = QString::null);
public:
/// Shared pointer to implement reference-counting.
typedef KSharedPtr<ScriptContainer> Ptr;
/**
* Destructor.
*/
virtual ~ScriptContainer();
/**
* \return the unique name this ScriptContainer is
* reachable as.
*/
const QString getName() const;
/**
* Set the name this ScriptContainer is reachable as.
*/
void setName(const QString& name);
/**
* Return the scriptcode this ScriptContainer holds.
*/
QString getCode() const;
/**
* Set the scriptcode this ScriptContainer holds.
*/
void setCode(const QString& code);
/**
* \return the name of the interpreter used
* on \a execute.
*/
QString getInterpreterName() const;
/**
* Set the name of the interpreter used
* on \a execute.
*/
void setInterpreterName(const QString& interpretername);
/**
* \return the filename which will be executed
* on \a execute.
*/
QString getFile() const;
/**
* Set the filename which will be executed
* on \a execute. The \p scriptfile needs to
* be a valid local file or QString::null if
* you don't like to use a file rather then
* the with \a setCode() defined scripting code.
*/
void setFile(const QString& scriptfile);
/**
* \return a map of options this \a ScriptContainer defines.
* The options are returned call-by-ref, so you are able to
* manipulate them.
*/
QMap<QString, QVariant>& getOptions();
/**
* \return the value of the option defined with \p name .
* If there doesn't exists an option with such a name,
* the \p defaultvalue is returned. If \p recursive is
* true then first the \a ScriptContainer options are
* seeked for the matching \p name and if not found
* the \a Manager options are seeked for the \p name and
* if not found either the \p defaultvalue is returned.
*/
QVariant getOption(const QString name, QVariant defaultvalue = QVariant(), bool recursive = false);
/**
* Set the \a Interpreter::Option value.
*/
bool setOption(const QString name, const QVariant& value);
/**
* Execute the script container.
*/
Object::Ptr execute();
/**
* Return a list of functionnames the with
* \a setCode defined scriptcode spends.
*/
const QStringList getFunctionNames();
/**
* Call a function in the script container.
*
* \param functionname The name of the function
* to call.
* \param arguments Optional list of arguments
* passed to the function.
* \return \a Object instance representing
* the functioncall returnvalue.
*/
KSharedPtr<Object> callFunction(const QString& functionname, KSharedPtr<List> arguments = 0);
/**
* Return a list of classes.
*/
QStringList getClassNames();
/**
* Create and return a new class instance.
*/
KSharedPtr<Object> classInstance(const QString& classname);
/**
* Initialize the \a Script instance.
*
* Normaly it's not needed to call this function direct cause
* if will be internaly called if needed (e.g. on \a execute ).
*/
bool initialize();
/**
* Finalize the \a Script instance and free's any cached or still
* running executions. Normaly it's not needed to call this
* function direct cause the \a ScriptContainer will take care
* of calling it if needed.
*/
void finalize();
private:
/// Internaly used private d-pointer.
ScriptContainerPrivate* d;
};
}}
#endif