Kross

action.h
1 /***************************************************************************
2  * action.h
3  * This file is part of the KDE project
4  * copyright (C)2004-2007 by Sebastian Sauer ([email protected])
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Library General Public
8  * License as published by the Free Software Foundation; either
9  * version 2 of the License, or (at your option) any later version.
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Library General Public License for more details.
14  * You should have received a copy of the GNU Library General Public License
15  * along with this program; see the file COPYING. If not, write to
16  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17  * Boston, MA 02110-1301, USA.
18  ***************************************************************************/
19 
20 #ifndef KROSS_ACTION_H
21 #define KROSS_ACTION_H
22 
23 #include <QVariant>
24 #include <QObject>
25 #include <QDir>
26 #include <QUrl>
27 #include <QAction>
28 #include <QDomAttr>
29 #include <QScriptable>
30 
31 #include "errorinterface.h"
32 #include "childreninterface.h"
33 
34 namespace Kross
35 {
36 
37 class Script;
38 
39 /**
40  * The Action class is an abstract container to deal with scripts
41  * like a single standalone script file. Each action holds a reference
42  * to the matching @a Kross::Interpreter created @a Kross::Script
43  * instance.
44  *
45  * The \a Manager takes care of handling the \a Action instances
46  * application by providing access to \a ActionCollection containers
47  * for those \a Action instances.
48  *
49  * Once you've such a Action instance you're able to perform actions
50  * with it like executing scripting code.
51  *
52  * Following sample shows "Hello World." executed with the python
53  * interpreter:
54  * \code
55  * # Create a new Kross::Action instance.
56  * Kross::Action* action = new Kross::Action(0,"MyFirstScript");
57  * # Set the interpreter we like to use. This could be e.g. "python" or "ruby".
58  * action->setInterpreter("python");
59  * # Set the scripting code.
60  * action->setCode("print \"Hello World.\"");
61  * # Execute the scripting code.
62  * action->trigger();
63  * \endcode
64  *
65  * Following sample demonstrates how to execute an external python script
66  * file. The script file itself is named "mytest.py" and contains:
67  * \code
68  * # this function got called from within C++
69  * def myfunction(args):
70  * print "Arguments are: %s" % args
71  * # Import the published QObject's
72  * import MyFirstQObject, MySecondQObject
73  * # Call a slot MyFirstQObject provides.
74  * MyFirstQObject.someSlot("Some string")
75  * # Set a property MySecondQObject provides.
76  * MySecondQObject.someProperty = "Other string"
77  * \endcode
78  * Then you are able to load the script file, publish QObject instances
79  * and let the script do whatever it likes to do:
80  * \code
81  * # Publish a QObject instance for all Kross::Action instances.
82  * Kross::Manager::self().addObject(myqobject1, "MyFirstQObject")
83  * # Create a new Kross::Action instance.
84  * Kross::Action* action = new Kross::Action(0,"MySecondScript");
85  * # Publish a QObject instance only for the Kross::Action instance.
86  * action->addObject(myqobject2, "MySecondQObject");
87  * # Set the script file we like to execute.
88  * action->setFile("/home/myuser/mytest.py");
89  * # Execute the script file.
90  * action->trigger();
91  * # Call the "myfunction" defined in the "mytest.py" python script.
92  * QVariant result = action->callFunction("myfunction", QVariantList()<<"Arg");
93  * \endcode
94  */
95 class KROSSCORE_EXPORT Action
96  : public QAction
97  , public QScriptable
98  , public ChildrenInterface
99  , public ErrorInterface
100 {
101  Q_OBJECT
102 
103 public:
104 
105  /**
106  * Constructor.
107  *
108  * \param parent The parent QObject this \a Action is a child of.
109  * \param name The unique name this Action has. It's used
110  * e.g. at the \a Manager to identify the Action. The
111  * name is accessible via \a QObject::objectName .
112  * \deprecated since 4.3: pass search path to fromDomElement() and toDomElement()
113  */
114  Action(QObject *parent, const QString &name, const QDir &packagepath = QDir()); //BIC may be removed in favour of the next c'tor
115 
116  /**
117  * Constructor.
118  *
119  * \param parent The parent QObject this \a Action is a child of.
120  * \param url The URL should point to a valid scripting file.
121  * This \a Action will be filled with the content of the
122  * file (e.g. the file is read and \a code should return
123  * its content and it's also tried to determine the
124  * \a interpreter ). Remember to use QUrl c'tor explicitly.
125  * The name will be set to url.path()
126  */
127  Action(QObject *parent, const QUrl &url);
128 
129  /**
130  * Destructor.
131  */
132  ~Action() override;
133 
134  /**
135  * Method to read settings from the QDomElement \p element that
136  * contains details about e.g. the displayed text, the file to
137  * execute or the used interpreter.
138  * \todo BIC merge
139  */
140  void fromDomElement(const QDomElement &element);
141 
142  /**
143  * Method to read settings from the QDomElement \p element that
144  * contains details about e.g. the displayed text, the file to
145  * execute or the used interpreter.
146  *
147  * \param searchPath List of directories where to search the script if its path is relative
148  * First item is given the highest priority.
149  */
150  void fromDomElement(const QDomElement &element, const QStringList &searchPath/* = QStringList()*/);
151 
152  /**
153  * \return a QDomElement that contains the settings like e.g. the
154  * displayed text, the file to execute or the used interpreter
155  * of this \a Action instance.
156  */
157  QDomElement toDomElement() const;
158 
159  /**
160  * \return a QDomElement that contains the settings like e.g. the
161  * displayed text, the file to execute or the used interpreter
162  * of this \a Action instance.
163  * \param searchPath if given, find the closest directory containing the scriptfile
164  * and write relative filepath
165  */
166  QDomElement toDomElement(const QStringList &searchPath/* = QStringList()*/) const;
167 
168  /**
169  * Initialize the \a Script instance.
170  *
171  * Normally there is no need to call this function directly because
172  * if will be called internally if needed (e.g. on \a execute ).
173  *
174  * \return true if the initialization was successful else
175  * false is returned.
176  */
177  bool initialize();
178 
179  /**
180  * Finalize the \a Script instance and frees any cached or still
181  * running executions. Normally there is no need to call this
182  * function directly because the \a Action will take care
183  * of calling it if needed.
184  */
185  void finalize();
186 
187  /**
188  * \return true if the action is finalized, which means the
189  * action is currently not running.
190  */
191  bool isFinalized() const;
192 
193  /**
194  * \return the \a Kross::Script implementation used by the scripting
195  * backend. This returns NULL until the action got triggered or if
196  * there was an error before that.
197  *
198  * Normally it shouldn't be necessary to deal with the scripting backend
199  * depending instance of a \a Kross::Script implementation since this
200  * \a Action class already decorates all the things needed. It
201  * may however be useful to provide additional interpreter dependent
202  * functionality.
203  */
204  Script *script() const;
205 
206 public Q_SLOTS:
207 
208  /**
209  * \return the objectName for this Action.
210  */
211  QString name() const;
212 
213  /**
214  * \return the version number this Action has.
215  * Per default 0 is returned.
216  */
217  int version() const;
218 
219  /**
220  * \return the optional description for this Action.
221  */
222  QString description() const;
223 
224  /**
225  * Set the optional description for this Action.
226  */
227  void setDescription(const QString &description);
228 
229  /**
230  * Return the name of the icon.
231  */
232  QString iconName() const;
233 
234  /**
235  * Set the name of the icon to \p iconname .
236  */
237  void setIconName(const QString &iconname);
238 
239  /**
240  * Return true if this Action is enabled else false is returned.
241  */
242  bool isEnabled() const;
243 
244  /**
245  * Set the enable state of this Action to \p enabled .
246  */
247  void setEnabled(bool enabled);
248 
249  /**
250  * \return the script file that should be executed.
251  */
252  QString file() const;
253 
254  /**
255  * Set the script file that should be executed.
256  */
257  bool setFile(const QString &scriptfile);
258 
259  /**
260  * \return the scriptcode this Action holds.
261  */
262  QByteArray code() const;
263 
264  /**
265  * Set the scriptcode \p code this Action should execute.
266  */
267  void setCode(const QByteArray &code);
268 
269  /**
270  * \return the name of the interpreter. Could be for
271  * example "python" or "ruby".
272  */
273  QString interpreter() const;
274 
275  /**
276  * Set the name of the interpreter (javascript, python or ruby).
277  */
278  void setInterpreter(const QString &interpretername);
279 
280  /**
281  * \return the current path the script is running in or
282  * an empty string if there is no current path defined.
283  */
284  QString currentPath() const;
285 
286  /**
287  * Add a QObject instance to the action. This instance will
288  * be published to scripts.
289  */
290  void addQObject(QObject *obj, const QString &name = QString());
291 
292  /**
293  * \return the QObject with the object name \p name .
294  */
295  QObject *qobject(const QString &name) const;
296 
297  /**
298  * \return a list of QObject object names.
299  */
300  QStringList qobjectNames() const;
301 
302  /**
303  * \return a map of options this \a Action defines.
304  * The options are returned call-by-ref, so you are able to
305  * manipulate them.
306  */
307  QVariantMap options() const;
308 
309  /**
310  * \return the value of the option defined with \p name .
311  * If there doesn't exist an option with such a name,
312  * the \p defaultvalue is returned.
313  */
314  QVariant option(const QString &name, const QVariant &defaultvalue = QVariant());
315 
316  /**
317  * Set the \a Interpreter::Option value.
318  */
319  bool setOption(const QString &name, const QVariant &value);
320 
321  /**
322  * \return the list of functionnames.
323  */
324  QStringList functionNames();
325 
326  /**
327  * Call a function in the script.
328  *
329  * \param name The name of the function which should be called.
330  * \param args The optional list of arguments.
331  */
332  QVariant callFunction(const QString &name, const QVariantList &args = QVariantList());
333 
334  /**
335  * Evaluate some scripting code.
336  *
337  * Example how this can be used:
338  * \code
339  * Kross::Action* a = new Kross::Action(0, "MyScript");
340  * a->setInterpreter("python");
341  * a->setCode("def myFunc(x): return x");
342  * a->trigger();
343  * int three = a->evaluate("1+2").toInt(); // returns 3
344  * int nine = a->evaluate("myFunc(9)").toInt(); // returns 9
345  * \endcode
346  *
347  * \param code The scripting code to evaluate.
348  * \return The return value of the evaluation.
349  */
350  QVariant evaluate(const QByteArray &code);
351 
352 Q_SIGNALS:
353 
354  /**
355  * This signal is emitted if the content of the Action
356  * was changed. The \a ActionCollection instances this Action
357  * is a child of are connected with this signal to fire up
358  * their own updated signal if an Action of them was updated.
359  */
360  void updated();
361 
362  /// This signal is emitted when the data of the Action is changed
363  void dataChanged(Action *);
364 
365  /**
366  * This signal is emitted before the script got executed.
367  */
368  void started(Kross::Action *);
369 
370  /**
371  * This signal is emitted after the script got executed.
372  */
373  void finished(Kross::Action *);
374 
375  /**
376  * This signal is emitted once a script finalized.
377  */
378  void finalized(Kross::Action *);
379 
380 private Q_SLOTS:
381 
382  /**
383  * This private slot is connected with the \a QAction::triggered
384  * signal. To execute the script just emit that signal and this
385  * slot tries to execute the script.
386  */
387  void slotTriggered();
388 
389 private:
390  /// \internal d-pointer class.
391  class Private;
392  /// \internal d-pointer instance.
393  Private *const d;
394 };
395 
396 }
397 
398 #endif
399 
Base class for interpreter dependent functionality each script provides.
Definition: core/script.h:44
Interface for error-handling.
Definition: action.cpp:36
const QLatin1String name
Interface for managing Object collections.
The Action class is an abstract container to deal with scripts like a single standalone script file...
Definition: action.h:95
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Nov 29 2021 22:51:27 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.