plugIns.doxygen   plugIns.doxygen 
skipping to change at line 38 skipping to change at line 38
We hope that the plugin system will allow third party developers to write e xtensions to Stellarium which might not otherwise be included in the core p rogram, and that the system will allow for prototyping of new features befo re inclusion into the core. We hope that the plugin system will allow third party developers to write e xtensions to Stellarium which might not otherwise be included in the core p rogram, and that the system will allow for prototyping of new features befo re inclusion into the core.
@section staticAndDynamicPlugins Static and Dynamic Plugins @section staticAndDynamicPlugins Static and Dynamic Plugins
Plugins can be built and used in two different ways: Plugins can be built and used in two different ways:
- <b>dynamic plugins</b> are stand-alone dynamic libraries (separate files with <tt>.so</tt> extension on Linux, <tt>.dll</tt> in Windows or <tt>.dyl ib</tt> on Mac OS X) that are loaded at run-time (on start-up) by Stellariu m. This allows dynamic plugins to be distributed separately from Stellarium . - <b>dynamic plugins</b> are stand-alone dynamic libraries (separate files with <tt>.so</tt> extension on Linux, <tt>.dll</tt> in Windows or <tt>.dyl ib</tt> on Mac OS X) that are loaded at run-time (on start-up) by Stellariu m. This allows dynamic plugins to be distributed separately from Stellarium .
- <b>static plugins</b> are linked statically at build-time. They become " built-in", a part of Stellarium's binary files. This is used to release fix ed versions of some "official" plugins together with Stellarium's releases. - <b>static plugins</b> are linked statically at build-time. They become " built-in", a part of Stellarium's binary files. This is used to release fix ed versions of some "official" plugins together with Stellarium's releases.
As Stellarium's plugin interface has changed over time, plugins for differe nt versions so far are not interchangeable. This is the reason why the offi cial plugins have been linked statically to the official release. As Stellarium's plugin interface has changed over time, plugins for differe nt versions so far are not interchangeable. This is the reason why the offi cial plugins have been linked statically to the official release.
Static plugins require changes in the core code of Stellarium (the addition of Qt macros in several classes). This is why adding a new static plugin r equires either asking the developers to add it to the main distribution, or creating and distributing a custom build. Static plugins require changes in the core code of Stellarium (the addition of %Qt macros in several classes). This is why adding a new static plugin requires either asking the developers to add it to the main distribution, o r creating and distributing a custom build.
Dynamic plugin libriaries need to be installed in a proper place in Stellar ium's \ref fileStructure "file tree" to function. Stellarium is looking for plugins in the <tt>/modules</tt> subdirectory of the user data directory o r the installation data directory. Each plugin library must be in its own s ubdiretory of the <tt>/modules</tt> directory. If the plugin is called "MyP lugin", then its subdirectory should be also called <tt>/MyPlugin</tt> and the main name (without the extension) of the plugin binary file should be < tt>libMyPlugin</tt>. So, for example, the file tree should look like this o n Windows XP: Dynamic plugin libriaries need to be installed in a proper place in Stellar ium's \ref fileStructure "file tree" to function. Stellarium is looking for plugins in the <tt>/modules</tt> subdirectory of the user data directory o r the installation data directory. Each plugin library must be in its own s ubdiretory of the <tt>/modules</tt> directory. If the plugin is called "MyP lugin", then its subdirectory should be also called <tt>/MyPlugin</tt> and the main name (without the extension) of the plugin binary file should be < tt>libMyPlugin</tt>. So, for example, the file tree should look like this o n Windows XP:
- <tt>C:/Documents and Settings/User/Application Data/Stellarium/</tt> (us er data directory) - <tt>C:/Documents and Settings/User/Application Data/Stellarium/</tt> (us er data directory)
- <tt>modules/</tt> - <tt>modules/</tt>
- <tt>MyPlugin/</tt> - <tt>MyPlugin/</tt>
- <tt>libMyPlugin.dll</tt> - <tt>libMyPlugin.dll</tt>
See the implementation of StelModuleMgr::getPluginsList() for more details. See the implementation of StelModuleMgr::getPluginsList() for more details.
@section code Coding @section code Coding
A plugin should contain a main class deriving from the StelModule class as well as an instance of the StelPluginInterface which allows Stellarium to l oad it. At startup, the StelModuleMgr will load the library, and an instanc e of the StelModule it contains will be instantiated and added to the list of other "normal" StelModules. A plugin should contain a main class deriving from the StelModule class as well as an instance of the StelPluginInterface which allows Stellarium to l oad it. At startup, the StelModuleMgr will load the library, and an instanc e of the StelModule it contains will be instantiated and added to the list of other "normal" StelModules.
A plugin can interact with the users in many ways, not limited to: A plugin can interact with the users in many ways, not limited to:
- painting directly on the viewport like other StelModules (see the exampl es below); - painting directly on the viewport like other StelModules (see the exampl es below);
- defining <a href="http://doc.qt.nokia.com/latest/qaction.html">QActions< /a> triggered with keyboard shortcut combinations with StelGui::addGuiActio ns(); - defining <a href="http://doc.qt.nokia.com/stable/qaction.html">QActions< /a> triggered with keyboard shortcut combinations with StelGui::addGuiActio ns();
- buttons (StelButton) added to the bottom button bar (BottomStelBar; see the examples below); - buttons (StelButton) added to the bottom button bar (BottomStelBar; see the examples below);
- windows (subclasses of StelDialog) that can be designed with Qt's UI edi - windows (subclasses of StelDialog) that can be designed with %Qt's UI ed
tor (see the examples and the configuration windows of the official plugins itor (see the examples and the configuration windows of the official plugin
); s);
- custom controls displayed anywhere on the screen based on any of the cla - custom controls displayed anywhere on the screen based on any of the cla
sses that inherit <a href="http://doc.qt.nokia.com/latest/qgraphicsitem.htm sses that inherit <a href="http://doc.qt.nokia.com/stable/qgraphicsitem.htm
l">QGraphicsItem</a> (see <a href="http://doc.qt.nokia.com/latest/graphicsv l">QGraphicsItem</a> (see <a href="http://doc.qt.nokia.com/stable/graphicsv
iew.html">the documentation of Qt's Graphics View Framework</a>). To get a iew.html">the documentation of Qt's Graphics View Framework</a>). To get a
base widget to work on, use StelGui::getSkyGui(). base widget to work on, use StelGui::getSkyGui().
<em>Plugin developers - please note that classes used in plugins must inher it code from the core which is published under the GNU GPL. <strong>If you distribute a binary plugin, you must do so under the terms of the same GNU General Public License that Stellarium uses</strong> (as of August 2011, th is is GNU GPL "version 2 or any later version"). No sneaky closed-source sh enanigans now.</em> <em>Plugin developers - please note that classes used in plugins must inher it code from the core which is published under the GNU GPL. <strong>If you distribute a binary plugin, you must do so under the terms of the same GNU General Public License that Stellarium uses</strong> (as of August 2011, th is is GNU GPL "version 2 or any later version"). No sneaky closed-source sh enanigans now.</em>
@section examplePlugins Example Plugins @section examplePlugins Example Plugins
There are a few simple \b static plugins written and maintained by the Stel larium developer team that can serve as examples. There are a few simple \b static plugins written and maintained by the Stel larium developer team that can serve as examples.
- <a href="http://bazaar.launchpad.net/~stellarium/stellarium/trunk/files/ head%3A/plugins/HelloStelModule/">HelloStelModule plugin</a>: minimal plugi n, intended as an example. - <a href="http://bazaar.launchpad.net/~stellarium/stellarium/trunk/files/ head%3A/plugins/HelloStelModule/">HelloStelModule plugin</a>: minimal plugi n, intended as an example.
- <a href="http://bazaar.launchpad.net/%7Estellarium/stellarium/trunk/file s/head%3A/plugins/AngleMeasure/">AngleMeasure plugin</a>: simple plugin, in tended as a guide to new developers. - <a href="http://bazaar.launchpad.net/%7Estellarium/stellarium/trunk/file s/head%3A/plugins/AngleMeasure/">AngleMeasure plugin</a>: simple plugin, in tended as a guide to new developers.
- <a href="http://bazaar.launchpad.net/%7Estellarium/stellarium/trunk/file s/head%3A/plugins/CompassMarks/"> CompassMarks plugin</a>: simple plugin, i ntended as a guide to new developers. - <a href="http://bazaar.launchpad.net/%7Estellarium/stellarium/trunk/file s/head%3A/plugins/CompassMarks/"> CompassMarks plugin</a>: simple plugin, i ntended as a guide to new developers.
 End of changes. 3 change blocks. 
10 lines changed or deleted 10 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/