Kross

manager.h
1 /***************************************************************************
2  * manager.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_MANAGER_H
21 #define KROSS_MANAGER_H
22 
23 #include <QStringList>
24 #include <QMap>
25 #include <QObject>
26 #include <QUrl>
27 #include <QScriptable>
28 
29 #include "krossconfig.h"
30 #include "childreninterface.h"
31 #include "metatype.h"
32 
33 namespace Kross
34 {
35 
36 // Forward declarations.
37 class Interpreter;
38 class Action;
39 class ActionCollection;
40 class InterpreterInfo;
41 
42 /**
43  * The Manager class is a singleton that provides the main entry
44  * point to deal with the Kross Scripting Framework.
45  *
46  * Use \a Interpreter to just work with some implemented
47  * interpreter like python or ruby. While \a Action implements
48  * a flexible abstract container to deal with single script files.
49  */
50 class KROSSCORE_EXPORT Manager
51  : public QObject
52  , public QScriptable
53  , public ChildrenInterface
54 {
55  Q_OBJECT
56 
57 public:
58 
59  /**
60  * Return the Manager instance. Always use this
61  * function to access the Manager singleton.
62  */
63  static Manager &self();
64 
65  /**
66  * \return a map with \a InterpreterInfo* instances
67  * used to describe interpreters.
68  */
69  QHash<QString, InterpreterInfo *> interpreterInfos() const;
70 
71  /**
72  * \return true if there exists an interpreter with the
73  * name \p interpretername else false.
74  */
75  bool hasInterpreterInfo(const QString &interpretername) const;
76 
77  /**
78  * \return the \a InterpreterInfo* matching to the defined
79  * \p interpretername or NULL if there does not exists such
80  * a interpreter.
81  */
82  InterpreterInfo *interpreterInfo(const QString &interpretername) const;
83 
84  /**
85  * Return the name of the \a Interpreter that feels responsible
86  * for the defined \p file .
87  *
88  * \param file The filename we should try to determinate the
89  * interpretername for.
90  * \return The name of the \a Interpreter which will be used
91  * to execute the file or QString() if we failed to determinate
92  * a matching interpreter for the file.
93  */
94  const QString interpreternameForFile(const QString &file);
95 
96  /**
97  * Return the \a Interpreter instance defined by
98  * the interpretername.
99  *
100  * \param interpretername The name of the interpreter.
101  * e.g. "python" or "ruby".
102  * \return The Interpreter instance or NULL if there does not exists
103  * an interpreter with such an interpretername.
104  */
105  Interpreter *interpreter(const QString &interpretername) const;
106 
107  /**
108  * \return the root \a ActionCollection instance. Each collection
109  * could have children of other collections and/or
110  * \a Action instances.
111  */
112  ActionCollection *actionCollection() const;
113 
114  /**
115  * \return the \a MetaTypeHandler instance for custom types
116  * of type \p typeName .
117  *
118  * \since 4.2
119  */
120  MetaTypeHandler *metaTypeHandler(const QByteArray &typeName) const;
121 
122  /**
123  * Register a handler for custom types.
124  *
125  * See also the \a WrapperInterface class.
126  *
127  * \param typeName The custom type the handler should handle.
128  * \param handler Function that should be called to handle
129  * a custom type.
130  *
131  * \since 4.2
132  */
133  void registerMetaTypeHandler(const QByteArray &typeName, MetaTypeHandler::FunctionPtr *handler);
134 
135  /**
136  * Register a handler for custom types.
137  *
138  * See also the \a WrapperInterface class.
139  *
140  * \param typeName The custom type the handler should handle.
141  * \param handler Function that should be called to handle
142  * a custom type.
143  *
144  * \since 4.2
145  */
146  void registerMetaTypeHandler(const QByteArray &typeName, MetaTypeHandler::FunctionPtr2 *handler);
147 
148  /**
149  * Register a handler for custom types.
150  *
151  * See also the \a WrapperInterface class.
152  *
153  * \param typeName The custom type the handler should handle.
154  * \param handler Function that should be called to handle
155  * a custom type.
156  *
157  * \since 4.2
158  */
159  void registerMetaTypeHandler(const QByteArray &typeName, MetaTypeHandler *handler);
160 
161  /**
162  * Returns true if strict type handling is enabled.
163  *
164  * \since 4.2
165  */
166  bool strictTypesEnabled() const;
167 
168  /**
169  * Enable more strict type handling. If enabled then scripting-backends don't
170  * handle unknown pointer-types where no MetaTypeHandler was registered for.
171  * If disabled, such unknown types will be reinterpret_cast to QObject* what
172  * allows to also handle unknown QObject's but will also result in a crash
173  * if the unknown type isn't a QObject. Per default strict type handling is
174  * enabled.
175  *
176  * \since 4.2
177  */
178  void setStrictTypesEnabled(bool enabled);
179 
180  /**
181  * \return whether \p typeName has a handler assigned or not.
182  */
183  bool hasHandlerAssigned(const QByteArray &typeName) const;
184 public Q_SLOTS:
185 
186  /**
187  * \return a list of names of all supported scripting interpreters.
188  * The list may contain for example "python" and "ruby" depending
189  * on what interpreter-plugins are installed.
190  */
191  QStringList interpreters() const;
192 
193  /**
194  * \return true if there exists a \a Action QObject instance
195  * which is child of this \a Manager instance and is defined as \p name
196  * else false is returned.
197  */
198  bool hasAction(const QString &name);
199 
200  /**
201  * \return the \a Action QObject instance defined with \p name which is
202  * child of this \a Manager instance. If there exists no such \a Action
203  * yet, create one.
204  */
205  QObject *action(const QString &name);
206 
207  /**
208  * Load and return an external module. Modules are dynamic loadable
209  * plugins which could be loaded on demand to provide additional
210  * functionality.
211  *
212  * \param modulename The name of the module we should try to load.
213  * \return The QObject instance that represents the module or NULL
214  * if loading failed.
215  */
216  QObject *module(const QString &modulename);
217 
218  /**
219  * External modules are dynamically loadable and are normally deleted
220  * when the kross library is unloaded.
221  * Applications may choose to call deleteModules() instead to control
222  * deletion of the modules at another time.
223  */
224  void deleteModules();
225 
226  /**
227  * Execute a script file.
228  * \param file The script file that should be executed.
229  */
230  bool executeScriptFile(const QUrl &file = QUrl());
231 
232  void addQObject(QObject *obj, const QString &name = QString());
233  QObject *qobject(const QString &name) const;
234  QStringList qobjectNames() const;
235 
236 Q_SIGNALS:
237 
238  /**
239  * This signal is emitted when the execution of a script is started.
240  */
241  void started(Kross::Action *);
242 
243  /**
244  * This signal is emitted when the execution of a script is finished.
245  */
246  void finished(Kross::Action *);
247 
248 private:
249  /// \internal d-pointer class.
250  class Private;
251  /// \internal d-pointer instance.
252  Private *const d;
253 
254 public:
255 
256  /**
257  * The constructor. Use \a self() to access the Manager
258  * singleton instance and don't call this direct.
259  */
260  explicit Manager();
261 
262  /**
263  * Destructor.
264  */
265  ~Manager() override;
266 };
267 
268 }
269 
270 #endif
271 
Definition: action.cpp:36
The InterpreterInfo class provides abstract information about a Interpreter before the interpreter-ba...
Interface for managing Object collections.
Base class for interpreter implementations.
Base class for metatype-handlers as used returned by the Kross::Manager::metaTypeHandler() method...
Definition: metatype.h:195
The Action class is an abstract container to deal with scripts like a single standalone script file...
Definition: action.h:95
The ActionCollection class manages collections of Action instances.
The Manager class is a singleton that provides the main entry point to deal with the Kross Scripting ...
Definition: manager.h:50
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Oct 15 2021 23:01:09 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.