ScriptInterface.hh 10.4 KB
Newer Older
 Jan Möbius committed Aug 05, 2009 1 /*===========================================================================*\  Jan Möbius committed Nov 25, 2010 2 3 * * * OpenFlipper *  Jan Möbius committed Jan 26, 2011 4 * Copyright (C) 2001-2011 by Computer Graphics Group, RWTH Aachen *  Jan Möbius committed Nov 25, 2010 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 * www.openflipper.org * * * *--------------------------------------------------------------------------- * * This file is part of OpenFlipper. * * * * OpenFlipper is free software: you can redistribute it and/or modify * * it under the terms of the GNU Lesser General Public License as * * published by the Free Software Foundation, either version 3 of * * the License, or (at your option) any later version with the * * following exceptions: * * * * If other files instantiate templates or use macros * * or inline functions from this file, or you compile this file and * * link it with other files to produce an executable, this file does * * not by itself cause the resulting executable to be covered by the * * GNU Lesser General Public License. This exception does not however * * invalidate any other reasons why the executable file might be * * covered by the GNU Lesser General Public License. * * * * OpenFlipper 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 Lesser General Public License for more details. * * * * You should have received a copy of the GNU LesserGeneral Public * * License along with OpenFlipper. If not, * * see . * * *  Jan Möbius committed Aug 05, 2009 33 34 35 \*===========================================================================*/ /*===========================================================================*\  Jan Möbius committed Nov 25, 2010 36 37 38 39 40 * * * $Revision$ * * $LastChangedBy$ * * $Date$ * * *  Jan Möbius committed Aug 05, 2009 41 \*===========================================================================*/  Jan Möbius committed Aug 29, 2008 42   Jan Möbius committed Oct 16, 2008 43 44 #ifndef SCRIPTINTERFACE_HH #define SCRIPTINTERFACE_HH  Jan Möbius committed Aug 29, 2008 45 46 47  #include  Jan Möbius committed Mar 01, 2011 48 49 50 51 52 53 54 55 56 57 58 /** \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 * *  Jan Möbius committed Aug 29, 2008 59 60 */ class ScriptInterface {  Jan Möbius committed Oct 16, 2008 61   Mike Kremer committed Feb 10, 2009 62 63 64 65  public: /// Destructor virtual ~ScriptInterface() {};  Jan Möbius committed Oct 16, 2008 66   Jan Möbius committed Mar 01, 2011 67 68 69 70  //=========================================================================== /** @name Script execution * @{ */ //===========================================================================  Jan Möbius committed Oct 16, 2008 71   Jan Möbius committed Mar 01, 2011 72  signals:  Jan Möbius committed Aug 29, 2008 73  /** Emit this signal to execute a script  Jan Möbius committed Mar 01, 2011 74 75 76 77 78 79 80 81 82 83 84  * * @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 ) {}; /** @} */  Jan Möbius committed Oct 16, 2008 85   Jan Möbius committed Mar 01, 2011 86 87 88 89 90 91  //=========================================================================== /** @name Function Information * @{ */ //=========================================================================== signals:  Jan Möbius committed Oct 16, 2008 92   Jan Möbius committed Aug 29, 2008 93  /** With this signal you can get a list of all available scripting functions  Jan Möbius committed Mar 01, 2011 94  * @param _functions All available functions  Jan Möbius committed Aug 29, 2008 95  */  Jan Möbius committed Mar 01, 2011 96  virtual void getAvailableFunctions(QStringList& _functions) { };  Dirk Wilden committed Oct 15, 2008 97 98 99 100 101 102 103 104  /** With this signal you can get descriptions about a given function if available * * @param _function name of the function (e.g. plugin.function) * @param _description a description for the function * @param _parameters list of names for the parameters * @param _descriptions list of descriptions for the parameters (_descriptions[i] corresponds to _parameters[i]) */  Jan Möbius committed Mar 01, 2011 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156  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 * @{ */ //===========================================================================  Jan Möbius committed Oct 16, 2008 157   Jan Möbius committed Aug 29, 2008 158  private slots:  Jan Möbius committed Oct 16, 2008 159   Jan Möbius committed Aug 29, 2008 160  /** Slot for a scripting plugin. Gets the Script and executes it.  Jan Möbius committed Oct 16, 2008 161  *  Jan Möbius committed Aug 29, 2008 162  * @param _pluginName Name of the plugin that executed a scriptable function  Jan Möbius committed Mar 01, 2011 163  * @param _functionWithParameters Name with parameters (values!) of the function to call.  Jan Möbius committed Aug 29, 2008 164  */  Jan Möbius committed Mar 01, 2011 165  virtual void slotScriptInfo( QString _pluginName , QString _functionWithParameters ) {};  Jan Möbius committed Oct 16, 2008 166 167   Jan Möbius committed Mar 01, 2011 168  /** Slot for a scripting plugin. Gets the Script as QString and executes it.  Jan Möbius committed Oct 16, 2008 169  *  Jan Möbius committed Mar 01, 2011 170  * @param _script Script to execute as a QString  Jan Möbius committed Aug 29, 2008 171  */  Jan Möbius committed Mar 01, 2011 172  virtual void slotExecuteScript( QString _script ) {};  Jan Möbius committed Oct 16, 2008 173 174   Jan Möbius committed Mar 01, 2011 175  /** Slot for a scripting plugin. Gets the Script as a filename, opens and executes it.  Jan Möbius committed Aug 29, 2008 176  */  Jan Möbius committed Mar 01, 2011 177  virtual void slotExecuteFileScript( QString _filename ) {};  Jan Möbius committed Oct 16, 2008 178   Jan Möbius committed Mar 01, 2011 179  /** @} */  Jan Möbius committed Oct 16, 2008 180   Jan Möbius committed Aug 29, 2008 181 182 };  Jan Möbius committed Mar 01, 2011 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 /** \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.
• 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.
• Execute scripts which are provided in a file (ScriptInterface::executeFileScript()). \code emit executeFileScript( "/home/user/script.ofs" ); \endcode
• 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. move.translate( ObjectId , Vector(1 , 0 , 0 ) ) ) \code emit scriptInfo( "translate( ObjectId , Vector(1 , 0 , 0 ) )" ); \endcode
• 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 pluginname.functionname \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.
To use the ScriptInterface:
• include ScriptInterface.hh in your plugins header file
• derive your plugin from the class ScriptInterface
• add Q_INTERFACES(ScriptInterface) to your plugin class
• And add the signals or slots you want to use to your plugin class (You don't need to implement all of them)
An easier interface to call functions is available by the \ref RPCInterfacePage "RPC Interface". Additionally it is  Jan Möbius committed Mar 01, 2011 239 possible to connect signals and slots across plugins via the \ref pluginConnectionInterfacePage "Plugin Connection Interface"  Jan Möbius committed Mar 01, 2011 240 241 242 243  */  Jan Möbius committed Oct 16, 2008 244 245 Q_DECLARE_INTERFACE(ScriptInterface,"OpenFlipper.ScriptInterface/1.1")  Jan Möbius committed Aug 29, 2008 246 #endif // SCRIPTINTERFACE_HH