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

Documented RPC Interface

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@11055 383ad7c9-94d9-4d36-a494-682f7c89f535
parent 77462e71
......@@ -46,7 +46,18 @@
#include <OpenFlipper/BasePlugin/RPCWrappers.hh>
/** Interface for all Plugins which do remote procedure calls ( and cross plugin calls).\n
/** \file RPCInterfacePage.hh
*
* Interface for calling functions across plugins. \ref RPCInterfacePage
*/
/** \brief Interface to call functions across plugins.
*
* \ref RPCInterfacePage "Detailed description"
* \n
* \n
*
* Interface for all Plugins which do remote procedure calls ( and cross plugin calls).\n
* The functions provided in the interface are only used to verify that certain plugins or
* functions are available. The actual calls are in the RPCWrappers.hh file.
*/
......@@ -60,6 +71,7 @@ class RPCInterface {
signals :
/** Check if the plugin exists in the current Environment \n
*
* @param _pluginName Name of the Plugin (has to be the clean version .. no Spaces etc)
* @param _exists found or not
*/
......@@ -75,6 +87,67 @@ class RPCInterface {
};
/** \page RPCInterfacePage RPC Interface
\image html RPCInterface.png
\n
The RPCInterface can be used by plugins to call functions from other OpenFlipper plugins. The calls are
internally transformed into scripting calls and passed to the other plugins.
You can directly connect signals and slots via the \ref pluginConnectionInterfacePage .
The interface itself contains two basic functions which can be used to check if another plugin exists (RPCInterface::pluginExists())
or if a specific function exists in another plugin (RPCInterface::functionExists()). Both functions get the clean name
of the plugin to check. To get that name, just open the script editor in OpenFlipper which lists all plugins and their
available functions.
Example Code for plugins:
\code
bool isPluginAvailable;
emit pluginExists ("scripting", isPluginAvailable);
\endcode
Example Code for functions:
\code
bool isFunctionAvailable;
emit functionExists ("scripting", "showScriptInEditor(QString)", isFunctionAvailable);
\endcode
In addition to these basic functions there is a set of template functions in RPCWrappers.hh which can be used to directly call
a function from another plugin via the scripting system. This requires the parameters to be registered to the QT MetaObject system which
is already done for the most common types of variables.
For calling a function you can use RPC::callFunction() or RPC::callFunctionValue() if the called function returns a value.
These functions get the pluginName and the function name and call the requested function via scripting.
It is possible to supply additional parameters to these functions that will be passed to the called function.
Example code:
\code
// call without getting return value
RPC::callFunction ("pluginName", "FunctionName");
// call without getting return value and suplying a parameter
int parameter1
RPC::callFunction ("pluginName", "FunctionName", parameter1);
// call with getting return value which is defined as the template parameter
QString parameter2
bool value = RPC::callFunctionValue<bool> ("pluginName", "FunctionName", parameter1, parameter2);
\endcode
To use the RPCInterface:
<ul>
<li> include RPCInterface.hh in your plugins header file
<li> derive your plugin from the class RPCInterface
<li> add Q_INTERFACES(RPCInterface) 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>
*/
Q_DECLARE_INTERFACE(RPCInterface,"OpenFlipper.RPCInterface/1.0")
#endif // RPCINTERFACE_HH
......@@ -41,22 +41,14 @@
\*===========================================================================*/
//
// C++ Interface: RPCInterface
//
// Description:
//
//
// Author: Jan Moebius <jan_moebius@web.de>, (C) 2007
//
#include <OpenFlipper/BasePlugin/RPCWrappers.hh>
#include <iostream>
namespace RPC {
/** Internal pointer to the script engine. Don't use it directly!
*
*/
static QScriptEngine* engine_;
QScriptValue callFunction( QString _plugin, QString _functionName , std::vector< QScriptValue > _parameters ) {
......
......@@ -40,19 +40,12 @@
* *
\*===========================================================================*/
//
// C++ Interface: RPCInterface
//
// Description:
//
//
// Author: Jan Moebius <jan_moebius@web.de>, (C) 2007
//
/**
* \file RPCWrappers.hh
* This file contains functions to call functions and procedures across plugins.
* The Qt Scripting system is used to pass the calls between different plugins.
* The QT Scripting system is used to pass the calls between different plugins.
*
* Usage is described in \ref RPCInterfacePage
*/
#ifndef RPCWRAPPERS_HH
......@@ -62,22 +55,19 @@
#include <vector>
#include <OpenFlipper/common/Types.hh>
/** Namespace containing RPC helper functions used to call functions across plugins
*/
/**
* Example code :
* QString version = RPC::callFunctionValue< QString >("backup","version");
* int count = RPC::callFunctionValue< int >("info","vertexCount",2);
/** Namespace containing RPC helper functions used to call functions across plugins
*
* Usage is described in \ref RPCInterfacePage
*/
namespace RPC {
/** \brief get a pointer to the scripting engine
//===========================================================================
/** @name Call functions across plugins (simple calls)
*
*/
DLLEXPORT
QScriptEngine* getScriptEngine();
* These functions can be used to call functions in other plugins.
* @{ */
//===========================================================================
/** \brief call a function provided by a plugin
*
......@@ -87,16 +77,32 @@ QScriptEngine* getScriptEngine();
DLLEXPORT
QScriptValue callFunction( QString _plugin, QString _functionName );
/** \brief call a function provided by a plugin getting multiple parameters
/** \brief Call a function provided by a plugin getting multiple parameters
*
* @param _plugin Plugin name ( Scripting name )
* This function gets the parameters which are converted to a QScriptValue on your own.
*
* @param _plugin Plugin name ( Scripting name of the plugin )
* @param _functionName Name of the remote function
* @param _parameters vector of scriptvalues containing the functions parameters in the right order
*/
DLLEXPORT
QScriptValue callFunction( QString _plugin, QString _functionName , std::vector< QScriptValue > _parameters );
/** @} */
//===========================================================================
/** @name Call functions across plugins
*
* These templates can be used to call functions in other plugins.
* @{ */
//===========================================================================
/** \brief call a function in another plugin
*
* @param _plugin Plugin name ( Scripting name of the plugin )
* @param _functionName Name of the remote function
* @param _t0 Parameter passed to the function
*/
template <typename T0>
void callFunction( QString _plugin, QString _functionName, T0 _t0) {
QScriptEngine* engine = getScriptEngine();
......@@ -164,6 +170,22 @@ void callFunction( QString _plugin, QString _functionName, T0 _t0 , T1 _t1 , T2
callFunction(_plugin,_functionName,parameters);
}
/** @} */
//===========================================================================
/** @name Call functions across plugins which return a value
*
* These templates can be used to call functions that return a value.
* You have to pass the type of return value as the first template parameter.
* @{ */
//===========================================================================
/** \brief call a function in another plugin and get a return parameter
*
* @param _plugin Plugin name ( Scripting name of the plugin )
* @param _functionName Name of the remote function
* @return value returned by the called function
*/
template <typename ReturnValue >
ReturnValue callFunctionValue( QString _plugin, QString _functionName) {
return qscriptvalue_cast< ReturnValue >( callFunction(_plugin,_functionName) );
......@@ -207,6 +229,23 @@ ReturnValue callFunctionValue( QString _plugin, QString _functionName, T0 _t0 ,
return qscriptvalue_cast<ReturnValue>( callFunction(_plugin,_functionName,parameters) );
}
/** @} */
//===========================================================================
/** @name Script Engine Controls
*
* Functions to get the scripting engine. Normally you don't need them. And
* RPC::setScriptEngine should never be used!
* @{ */
//===========================================================================
/** \brief get a pointer to OpenFlippers core scripting engine
*
*/
DLLEXPORT
QScriptEngine* getScriptEngine();
/** \brief DONT USE! (Function to set the internal reference to the script Engine)
*
......@@ -215,6 +254,8 @@ ReturnValue callFunctionValue( QString _plugin, QString _functionName, T0 _t0 ,
DLLEXPORT
void setScriptEngine( QScriptEngine* _engine );
/** @} */
}
#endif // RPCWRAPPERS_HH
......@@ -63,7 +63,6 @@ MouseInterface
OptionsInterface
PickingInterface
ProcessInterface
RPCInterface
SecurityInterface
TextureInterface
TypeInterface
......@@ -101,11 +100,6 @@ Allows your plugin to provide a texture. ( TextureInterface )
Handle mouse picking in your plugin ( PickingInterface )
\subsection RPCPlugin RPC Interface
\image html RPCInterface.png
This interface is used to call functions across different plugins ( RPCInterface ).
\subsection FilePlugin File Interface
\image html FileInterface.png
Provides functions to read and write custom filetypes ( FileInterface )
......@@ -178,30 +172,40 @@ Provides functions to create a separate widget in the toolbox on the right ( \re
\image html ToolbarInterface.png
Provides a function to add toolbar buttons. ( \ref toolbarInterfacePage )
\n
*/
/** \page pluginInterfacesDataHandling Object and Data Handling
This page shows interfaces for controlling and adding Objects.
*/
/** \page pluginInterfacesInputDevices Input Devices
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 RPCInterfacePage
\n
\image html RPCInterface.png
\n
Interface to call functions across plugins ( \ref RPCInterfacePage )
\n
\subpage scriptInterfacePage
\n
\image html ScriptInterface.png
\n
For plugins which provide scriptable functions ( \ref scriptInterfacePage )
\n
\subpage pluginConnectionInterfacePage
\n
\image html PluginConnectionInterface.png
\n
Enables the developer to connect signals and slots across plugins. ( \ref pluginConnectionInterfacePage )
\n
*/
......
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