Commit 21319015 authored by Jan Möbius's avatar Jan Möbius

Documented scripting interface

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@11051 383ad7c9-94d9-4d36-a494-682f7c89f535
parent 570a75a5
......@@ -45,9 +45,17 @@
#include <QtScript/QScriptEngine>
/** Interface for all Plugins which provide scriptable Functions.
* These Functions should follow some guidelines :
* -# Todo
/** \file ScriptInterface.hh
*
* Interface for controlling OpenFlippers scripting system. \ref scriptInterfacePage
*/
/** \brief Interface for all Plugins which provide scriptable Functions.\
*
* \ref scriptInterfacePage "Detailed description"
* \n
*
*
*/
class ScriptInterface {
......@@ -55,30 +63,37 @@ class ScriptInterface {
/// Destructor
virtual ~ScriptInterface() {};
signals :
/** \brief Emit this signal if a scriptable function is executed
*
* e.g. selectAllVertices( ObjectId )
*
* @param _functionName the called function
*/
virtual void scriptInfo( QString /*_functionName*/ ) {};
//===========================================================================
/** @name Script execution
* @{ */
//===========================================================================
signals:
/** Emit this signal to execute a script
* @param _script The script to execute
*/
virtual void executeScript( QString /*_script*/ ) {};
*
* @param _script The script to execute
*/
virtual void executeScript( QString _script ) {};
/** Emit this signal to execute a script from a file
* @param _filename Filename of the script to execute
*/
virtual void executeFileScript( QString _filename ) {};
/** @} */
/** Emit this signal to get the core scripting engine
* @param _engine The scripting Engine
*/
virtual void getScriptingEngine( QScriptEngine*& /*_engine*/ ) {};
//===========================================================================
/** @name Function Information
* @{ */
//===========================================================================
signals:
/** With this signal you can get a list of all available scripting functions
* @param _functions All available functions
* @param _functions All available functions
*/
virtual void getAvailableFunctions( QStringList& /*_functions*/ ) {};
virtual void getAvailableFunctions(QStringList& _functions) { };
/** With this signal you can get descriptions about a given function if available
*
......@@ -87,33 +102,145 @@ class ScriptInterface {
* @param _parameters list of names for the parameters
* @param _descriptions list of descriptions for the parameters (_descriptions[i] corresponds to _parameters[i])
*/
virtual void getDescription(QString /*_function*/, QString& /*_description*/,
QStringList& /*_parameters*/, QStringList& /*_descriptions*/ ) {};
virtual void getDescription(QString _function, QString& _description, QStringList& _parameters, QStringList& _descriptions) { };
/** @} */
//===========================================================================
/** @name Scripting History
* @{ */
//===========================================================================
signals:
/** \brief Emit this signal if a scriptable function is executed
*
* e.g. selectAllVertices( ObjectId )
*
* If you execute this function, you can append your functions to the script
* execution history in OpenFlipper. In this history OpenFlipper records operations
* that are scriptable. Later this list can be executed again and therefore
* reruns the recorded operations.
*
* The following example code shows a function called translate in a plugin,
* that gets an ObjectId as a parameter. The plugin which emits this function
* will automatically be added in the history ( e.g. \code move.translate( ObjectId , Vector(1 , 0 , 0 ) ) \endcode )
* \code
* emit scriptInfo( "translate( ObjectId , Vector(1 , 0 , 0 ) )" );
* \endcode
*
* @param _functionWithParameters The called function with all parameters
*/
virtual void scriptInfo( QString _functionWithParameters ) {};
/** @} */
//===========================================================================
/** @name Others
* @{ */
//===========================================================================
signals:
/** Emit this signal to get a reference to the core scripting engine
*
* @param _engine The scripting Engine
*/
virtual void getScriptingEngine( QScriptEngine*& _engine ) {};
/** @} */
//===========================================================================
/** @name Slots for a scripting control plugin like Plugin-Script
* @{ */
//===========================================================================
private slots:
/** Slot for a scripting plugin. Gets the Script and executes it.
*
* @param _pluginName Name of the plugin that executed a scriptable function
* @param _functionName Name of the executed function
* @param _functionWithParameters Name with parameters (values!) of the function to call.
*/
virtual void slotScriptInfo( QString /*_pluginName*/ , QString /*_functionName*/ ) {};
virtual void slotScriptInfo( QString _pluginName , QString _functionWithParameters ) {};
/** Slot for a scripting plugin. Gets the Script and executes it.
/** Slot for a scripting plugin. Gets the Script as QString and executes it.
*
* @param _script Script to execute
* @param _script Script to execute as a QString
*/
virtual void slotExecuteScript( QString /*_script*/ ) {};
virtual void slotExecuteScript( QString _script ) {};
/** Call this slot to open the given file and execute the script in it
/** Slot for a scripting plugin. Gets the Script as a filename, opens and executes it.
*/
virtual void slotExecuteFileScript( QString /*_filename*/ ) {};
virtual void slotExecuteFileScript( QString _filename ) {};
/** @} */
};
/** \page scriptInterfacePage Scripting Interface
\n
\image html ScriptInterface.png
\n
OpenFlipper uses QTs scripting system to provide scripting functions to the user and to the plugins.
It also includes a batch mode where OpenFlipper is started without an user interface. All plugins
which support this mode can than be controlled by command line supplied batch scripts without any user
interaction.
The ScriptingInterface has several functions to support scripting.
<ul>
<li> Execute scripts which are provided in a simple QString (ScriptInterface::executeScript()).
\code
emit executeScript( "translate( 5 , Vector(1 , 0 , 0 ) )" );
\endcode
This will translate The object with id 6 by the given vector.
<li> Execute scripts which are provided in a file (ScriptInterface::executeFileScript()).
\code
emit executeFileScript( "/home/user/script.ofs" );
\endcode
<li> If a scriptable slot is executed, it can add an entry to OpenFlippers script history. This history can
later be used to rerun a process in batch mode ( ScriptInterface::scriptInfo() ).
The following example code shows a function called translate in a plugin,
that gets an ObjectId as a parameter. The plugin which emits this function
will automatically be added in the history ( e.g. <tt> move.translate( ObjectId , Vector(1 , 0 , 0 ) ) </tt> )
\code
emit scriptInfo( "translate( ObjectId , Vector(1 , 0 , 0 ) )" );
\endcode
<li> Get Information about scriptable functions ( ScriptInterface::getAvailableFunctions(),ScriptInterface::getDescription() ).
The first function ( ScriptInterface::getAvailableFunctions() ) can be used to get a QStringlist of all available
functions. Each string is of the form <tt>pluginname.functionname</tt>
\code
// Update list of available functions
QStringList completeList;
emit getAvailableFunctions( completeList );
\endcode
The second function ( ScriptInterface::getDescription() ) can be used to get information about a function, if it was
provided by the developer.
</ul>
To use the ScriptInterface:
<ul>
<li> include ScriptInterface.hh in your plugins header file
<li> derive your plugin from the class ScriptInterface
<li> add Q_INTERFACES(ScriptInterface) to your plugin class
<li> And add the signals or slots you want to use to your plugin class (You don't need to implement all of them)
</ul>
An easier interface to call functions is available by the \ref RPCInterfacePage "RPC Interface". Additionally it is
possible to connect signals and slots across plugins via the \ref PluginConnectionInterfacePage "Plugin Connection Interface"
*/
Q_DECLARE_INTERFACE(ScriptInterface,"OpenFlipper.ScriptInterface/1.1")
#endif // SCRIPTINTERFACE_HH
......@@ -1516,6 +1516,11 @@ void Core::loadPlugin(QString filename, bool silent, QString& _licenseErrors, QO
connect(plugin , SIGNAL(executeScript(QString)),
this , SLOT(slotExecuteScript(QString)));
// Plugins to Core
if ( checkSignal(plugin,"executeFileScript(QString)") )
connect(plugin , SIGNAL(executeFileScript(QString)),
this , SLOT(slotExecuteFileScript(QString)));
// Core to plugins ( normally only one scripting plugin)
if ( checkSlot(plugin,"slotExecuteScript(QString)") )
connect(this , SIGNAL(executeScript(QString)),
......
......@@ -49,6 +49,8 @@ The following groups of Interfaces are available:
\subpage pluginInterfacesInputDevices
\subpage pluginInterfacesOtherInterfaces
\section todoInterfaces Interfaces todos for documentation:
......@@ -63,7 +65,6 @@ PickingInterface
PluginConnectionInterface
ProcessInterface
RPCInterface
ScriptInterface
SecurityInterface
TextureInterface
TypeInterface
......@@ -126,13 +127,6 @@ Specify own view modes ( ViewModeInterface )
\image html ViewInterface.png
This interface is used to add additional view widgets ( ViewInterface ).
\subsection ScriptPlugin Script Interface
\image html ScriptInterface.png
For plugins who provide scriptable functions ( ScriptInterface )
\subsection OptionsPlugin Options Interface
\image html OptionsInterface.png
This Interface is used by plugins which will provide their own options by
......@@ -199,6 +193,16 @@ This page shows interfaces which could be used to get data from input devices.
*/
/** \page pluginInterfacesOtherInterfaces Other Interfaces
This page shows interfaces for other operations.
\subpage scriptInterfacePage
\image html ScriptInterface.png
For plugins which provide scriptable functions ( \ref scriptInterfacePage )
*/
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment