mirror of
https://bitbucket.org/smil3y/kdelibs.git
synced 2025-02-25 11:22:50 +00:00
400 lines
14 KiB
C++
400 lines
14 KiB
C++
/***************************************************************************
|
|
* action.h
|
|
* This file is part of the KDE project
|
|
* copyright (C)2004-2007 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_ACTION_H
|
|
#define KROSS_ACTION_H
|
|
|
|
#include <QtCore/QVariant>
|
|
#include <QtCore/QObject>
|
|
#include <QtCore/QDir>
|
|
#include <QtCore/QUrl>
|
|
#include <QtGui/QAction>
|
|
#include <QtXml/QDomAttr>
|
|
#include <QtScript/QScriptable>
|
|
|
|
#include "errorinterface.h"
|
|
#include "childreninterface.h"
|
|
|
|
namespace Kross {
|
|
|
|
class Script;
|
|
|
|
/**
|
|
* The Action class is an abstract container to deal with scripts
|
|
* like a single standalone script file. Each action holds a reference
|
|
* to the matching @a Kross::Interpreter created @a Kross::Script
|
|
* instance.
|
|
*
|
|
* The \a Manager takes care of handling the \a Action instances
|
|
* application by providing access to \a ActionCollection containers
|
|
* for those \a Action instances.
|
|
*
|
|
* Once you've such a Action instance you're able to perform actions
|
|
* with it like executing scripting code.
|
|
*
|
|
* Following sample shows "Hello World." executed with the python
|
|
* interpreter:
|
|
* \code
|
|
* # Create a new Kross::Action instance.
|
|
* Kross::Action* action = new Kross::Action(0,"MyFirstScript");
|
|
* # Set the interpreter we like to use. This could be e.g. "python", "ruby" or "kjs".
|
|
* action->setInterpreter("python");
|
|
* # Set the scripting code.
|
|
* action->setCode("print \"Hello World.\"");
|
|
* # Execute the scripting code.
|
|
* action->trigger();
|
|
* \endcode
|
|
*
|
|
* Following sample demonstrates how to execute an external python script
|
|
* file. The script file itself is named "mytest.py" and contains:
|
|
* \code
|
|
* # this function got called from within C++
|
|
* def myfunction(args):
|
|
* print "Arguments are: %s" % args
|
|
* # Import the published QObject's
|
|
* import MyFirstQObject, MySecondQObject
|
|
* # Call a slot MyFirstQObject provides.
|
|
* MyFirstQObject.someSlot("Some string")
|
|
* # Set a property MySecondQObject provides.
|
|
* MySecondQObject.someProperty = "Other string"
|
|
* \endcode
|
|
* Then you are able to load the script file, publish QObject instances
|
|
* and let the script do whatever it likes to do:
|
|
* \code
|
|
* # Publish a QObject instance for all Kross::Action instances.
|
|
* Kross::Manager::self().addObject(myqobject1, "MyFirstQObject")
|
|
* # Create a new Kross::Action instance.
|
|
* Kross::Action* action = new Kross::Action(0,"MySecondScript");
|
|
* # Publish a QObject instance only for the Kross::Action instance.
|
|
* action->addObject(myqobject2, "MySecondQObject");
|
|
* # Set the script file we like to execute.
|
|
* action->setFile("/home/myuser/mytest.py");
|
|
* # Execute the script file.
|
|
* action->trigger();
|
|
* # Call the "myfunction" defined in the "mytest.py" python script.
|
|
* QVariant result = action->callFunction("myfunction", QVariantList()<<"Arg");
|
|
* \endcode
|
|
*/
|
|
class KROSSCORE_EXPORT Action
|
|
: public QAction
|
|
, public QScriptable
|
|
, public ChildrenInterface
|
|
, public ErrorInterface
|
|
{
|
|
Q_OBJECT
|
|
|
|
public:
|
|
|
|
/**
|
|
* Constructor.
|
|
*
|
|
* \param parent The parent QObject this \a Action is a child of.
|
|
* \param name The unique name this Action has. It's used
|
|
* e.g. at the \a Manager to identify the Action. The
|
|
* name is accessible via \a QObject::objectName .
|
|
* \deprecated since 4.3: pass search path to fromDomElement() and toDomElement()
|
|
*/
|
|
Action(QObject* parent, const QString& name, const QDir& packagepath = QDir()); //BIC may be removed in favour of the next c'tor
|
|
|
|
/**
|
|
* Constructor.
|
|
*
|
|
* \param parent The parent QObject this \a Action is a child of.
|
|
* \param url The URL should point to a valid scripting file.
|
|
* This \a Action will be filled with the content of the
|
|
* file (e.g. the file is read and \a code should return
|
|
* its content and it's also tried to determine the
|
|
* \a interpreter ). Remember to use QUrl c'tor explicitly.
|
|
* The name will be set to url.path()
|
|
*/
|
|
Action(QObject* parent, const QUrl& url);
|
|
|
|
/**
|
|
* Destructor.
|
|
*/
|
|
virtual ~Action();
|
|
|
|
/**
|
|
* Method to read settings from the QDomElement \p element that
|
|
* contains details about e.g. the displayed text, the file to
|
|
* execute or the used interpreter.
|
|
* \todo BIC merge
|
|
*/
|
|
void fromDomElement(const QDomElement& element);
|
|
|
|
/**
|
|
* Method to read settings from the QDomElement \p element that
|
|
* contains details about e.g. the displayed text, the file to
|
|
* execute or the used interpreter.
|
|
*
|
|
* \param searchPath List of directories where to search the script if its path is relative
|
|
* First item is given the highest priority.
|
|
*/
|
|
void fromDomElement(const QDomElement& element, const QStringList& searchPath/* = QStringList()*/);
|
|
|
|
/**
|
|
* \return a QDomElement that contains the settings like e.g. the
|
|
* displayed text, the file to execute or the used interpreter
|
|
* of this \a Action instance.
|
|
*/
|
|
QDomElement toDomElement() const;
|
|
|
|
/**
|
|
* \return a QDomElement that contains the settings like e.g. the
|
|
* displayed text, the file to execute or the used interpreter
|
|
* of this \a Action instance.
|
|
* \param searchPath if given, find the closest directory containing the scriptfile
|
|
* and write relative filepath
|
|
*/
|
|
QDomElement toDomElement(const QStringList& searchPath/* = QStringList()*/) const;
|
|
|
|
/**
|
|
* Initialize the \a Script instance.
|
|
*
|
|
* Normally there is no need to call this function directly because
|
|
* if will be called internally if needed (e.g. on \a execute ).
|
|
*
|
|
* \return true if the initialization was successful else
|
|
* false is returned.
|
|
*/
|
|
bool initialize();
|
|
|
|
/**
|
|
* Finalize the \a Script instance and frees any cached or still
|
|
* running executions. Normally there is no need to call this
|
|
* function directly because the \a Action will take care
|
|
* of calling it if needed.
|
|
*/
|
|
void finalize();
|
|
|
|
/**
|
|
* \return true if the action is finalized, which means the
|
|
* action is currently not running.
|
|
*/
|
|
bool isFinalized() const;
|
|
|
|
/**
|
|
* \return the \a Kross::Script implementation used by the scripting
|
|
* backend. This returns NULL until the action got triggered or if
|
|
* there was an error before that.
|
|
*
|
|
* Normaly it shouldn't be necessary to deal with the scripting backend
|
|
* depending instance of a \a Kross::Script implementation since this
|
|
* \a Action class already decorates all the things needed. It
|
|
* may however be useful to provide additional interpreter dependent
|
|
* functionality.
|
|
*/
|
|
Script* script() const;
|
|
|
|
public Q_SLOTS:
|
|
|
|
/**
|
|
* \return the objectName for this Action.
|
|
*/
|
|
QString name() const;
|
|
|
|
/**
|
|
* \return the version number this Action has.
|
|
* Per default 0 is returned.
|
|
*/
|
|
int version() const;
|
|
|
|
/**
|
|
* \return the optional description for this Action.
|
|
*/
|
|
QString description() const;
|
|
|
|
/**
|
|
* Set the optional description for this Action.
|
|
*/
|
|
void setDescription(const QString& description);
|
|
|
|
/**
|
|
* Return the name of the icon.
|
|
*/
|
|
QString iconName() const;
|
|
|
|
/**
|
|
* Set the name of the icon to \p iconname .
|
|
*/
|
|
void setIconName(const QString& iconname);
|
|
|
|
/**
|
|
* Return true if this Action is enabled else false is returned.
|
|
*/
|
|
bool isEnabled() const;
|
|
|
|
/**
|
|
* Set the enable state of this Action to \p enabled .
|
|
*/
|
|
void setEnabled(bool enabled);
|
|
|
|
/**
|
|
* \return the script file that should be executed.
|
|
*/
|
|
QString file() const;
|
|
|
|
/**
|
|
* Set the script file that should be executed.
|
|
*/
|
|
bool setFile(const QString& scriptfile);
|
|
|
|
/**
|
|
* \return the scriptcode this Action holds.
|
|
*/
|
|
QByteArray code() const;
|
|
|
|
/**
|
|
* Set the scriptcode \p code this Action should execute.
|
|
*/
|
|
void setCode(const QByteArray& code);
|
|
|
|
/**
|
|
* \return the name of the interpreter. Could be for
|
|
* example "python" or "ruby".
|
|
*/
|
|
QString interpreter() const;
|
|
|
|
/**
|
|
* Set the name of the interpreter (javascript, python or ruby).
|
|
*/
|
|
void setInterpreter(const QString& interpretername);
|
|
|
|
/**
|
|
* \return the current path the script is running in or
|
|
* an empty string if there is no current path defined.
|
|
*/
|
|
QString currentPath() const;
|
|
|
|
/**
|
|
* Add a QObject instance to the action. This instance will
|
|
* be published to scripts.
|
|
*/
|
|
void addQObject(QObject* obj, const QString &name = QString());
|
|
|
|
/**
|
|
* \return the QObject with the object name \p name .
|
|
*/
|
|
QObject* qobject(const QString &name) const;
|
|
|
|
/**
|
|
* \return a list of QObject object names.
|
|
*/
|
|
QStringList qobjectNames() const;
|
|
|
|
/**
|
|
* \return a map of options this \a Action defines.
|
|
* The options are returned call-by-ref, so you are able to
|
|
* manipulate them.
|
|
*/
|
|
QVariantMap options() const;
|
|
|
|
/**
|
|
* \return the value of the option defined with \p name .
|
|
* If there doesn't exist an option with such a name,
|
|
* the \p defaultvalue is returned.
|
|
*/
|
|
QVariant option(const QString& name, const QVariant& defaultvalue = QVariant());
|
|
|
|
/**
|
|
* Set the \a Interpreter::Option value.
|
|
*/
|
|
bool setOption(const QString& name, const QVariant& value);
|
|
|
|
/**
|
|
* \return the list of functionnames.
|
|
*/
|
|
QStringList functionNames();
|
|
|
|
/**
|
|
* Call a function in the script.
|
|
*
|
|
* \param name The name of the function which should be called.
|
|
* \param args The optional list of arguments.
|
|
*/
|
|
QVariant callFunction(const QString& name, const QVariantList& args = QVariantList());
|
|
|
|
/**
|
|
* Evaluate some scripting code.
|
|
*
|
|
* Example how this can be used:
|
|
* \code
|
|
* Kross::Action* a = new Kross::Action(0, "MyScript");
|
|
* a->setInterpreter("python");
|
|
* a->setCode("def myFunc(x): return x");
|
|
* a->trigger();
|
|
* int three = a->evaluate("1+2").toInt(); // returns 3
|
|
* int nine = a->evaluate("myFunc(9)").toInt(); // returns 9
|
|
* \endcode
|
|
*
|
|
* \param code The scripting code to evaluate.
|
|
* \return The return value of the evaluation.
|
|
*/
|
|
QVariant evaluate(const QByteArray& code);
|
|
|
|
Q_SIGNALS:
|
|
|
|
/**
|
|
* This signal is emitted if the content of the Action
|
|
* was changed. The \a ActionCollection instances this Action
|
|
* is a child of are connected with this signal to fire up
|
|
* their own updated signal if an Action of them was updated.
|
|
*/
|
|
void updated();
|
|
|
|
/// This signal is emitted when the data of the Action is changed
|
|
void dataChanged(Action*);
|
|
|
|
/**
|
|
* This signal is emitted before the script got executed.
|
|
*/
|
|
void started(Kross::Action*);
|
|
|
|
/**
|
|
* This signal is emitted after the script got executed.
|
|
*/
|
|
void finished(Kross::Action*);
|
|
|
|
/**
|
|
* This signal is emitted once a script finalized.
|
|
*/
|
|
void finalized(Kross::Action*);
|
|
|
|
private Q_SLOTS:
|
|
|
|
/**
|
|
* This private slot is connected with the \a QAction::triggered
|
|
* signal. To execute the script just emit that signal and this
|
|
* slot tries to execute the script.
|
|
*/
|
|
void slotTriggered();
|
|
|
|
private:
|
|
/// \internal d-pointer class.
|
|
class Private;
|
|
/// \internal d-pointer instance.
|
|
Private* const d;
|
|
};
|
|
|
|
}
|
|
|
|
Q_DECLARE_METATYPE(Kross::Action*)
|
|
|
|
#endif
|
|
|