TDE core libraries
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

plugin.h 6.1KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177
  1. /* This file is part of the KDE project
  2. Copyright (C) 1999 Simon Hausmann <hausmann@kde.org>
  3. (C) 1999 David Faure <faure@kde.org>
  4. This library is free software; you can redistribute it and/or
  5. modify it under the terms of the GNU Library General Public
  6. License as published by the Free Software Foundation; either
  7. version 2 of the License, or (at your option) any later version.
  8. This library is distributed in the hope that it will be useful,
  9. but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  11. Library General Public License for more details.
  12. You should have received a copy of the GNU Library General Public License
  13. along with this library; see the file COPYING.LIB. If not, write to
  14. the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  15. Boston, MA 02110-1301, USA.
  16. */
  17. #ifndef PLUGIN_H
  18. #define PLUGIN_H
  19. #include <tqobject.h>
  20. #include <tdeaction.h>
  21. #include <kxmlguiclient.h>
  22. class TDEInstance;
  23. namespace KParts
  24. {
  25. /**
  26. * A plugin is the way to add actions to an existing KParts application,
  27. * or to a Part.
  28. *
  29. * The XML of those plugins looks exactly like of the shell or parts,
  30. * with one small difference: The document tag should have an additional
  31. * attribute, named "library", and contain the name of the library implementing
  32. * the plugin.
  33. *
  34. * If you want this plugin to be used by a part, you need to
  35. * install the rc file under the directory
  36. * "data" (TDEDIR/share/apps usually)+"/instancename/kpartplugins/"
  37. * where instancename is the name of the part's instance.
  38. *
  39. * You should also install a "plugin info" .desktop file with the same name.
  40. * \see PluginInfo
  41. */
  42. class TDEPARTS_EXPORT Plugin : public TQObject, virtual public KXMLGUIClient
  43. {
  44. Q_OBJECT
  45. public:
  46. /**
  47. * Struct holding information about a plugin
  48. */
  49. struct PluginInfo
  50. {
  51. TQString m_relXMLFileName; ///< relative filename, i.e. kpartplugins/name
  52. TQString m_absXMLFileName; ///< full path of most recent filename matching the relative filename
  53. TQDomDocument m_document;
  54. };
  55. /**
  56. * Construct a new KParts plugin.
  57. */
  58. Plugin( TQObject* parent = 0, const char* name = 0 );
  59. /**
  60. * Destructor.
  61. */
  62. virtual ~Plugin();
  63. /**
  64. * Reimplemented for internal reasons
  65. */
  66. virtual TQString xmlFile() const;
  67. /**
  68. * Reimplemented for internal reasons
  69. */
  70. virtual TQString localXMLFile() const;
  71. /**
  72. * Load the plugin libraries from the directories appropriate
  73. * to @p instance and make the Plugin objects children of @p parent.
  74. *
  75. * It is recommended to use the last loadPlugins method instead,
  76. * to support enabling and disabling of plugins.
  77. */
  78. static void loadPlugins( TQObject *parent, const TDEInstance * instance );
  79. /**
  80. * Load the plugin libraries specified by the list @p docs and make the
  81. * Plugin objects children of @p parent .
  82. *
  83. * It is recommended to use the last loadPlugins method instead,
  84. * to support enabling and disabling of plugins.
  85. */
  86. static void loadPlugins( TQObject *parent, const TQValueList<PluginInfo> &pluginInfos );
  87. /**
  88. * Load the plugin libraries specified by the list @p pluginInfos, make the
  89. * Plugin objects children of @p parent, and use the given @p instance.
  90. *
  91. * It is recommended to use the last loadPlugins method instead,
  92. * to support enabling and disabling of plugins.
  93. */
  94. static void loadPlugins( TQObject *parent, const TQValueList<PluginInfo> &pluginInfos, const TDEInstance * instance );
  95. /**
  96. * Load the plugin libraries for the given @p instance, make the
  97. * Plugin objects children of @p parent, and insert the plugin as a child GUI client
  98. * of @p parentGUIClient.
  99. *
  100. * This method uses the TDEConfig object of the given instance, to find out which
  101. * plugins are enabled and which are disabled. What happens by default (i.e.
  102. * for new plugins that are not in that config file) is controlled by
  103. * @p enableNewPluginsByDefault. It can be overridden by the plugin if it
  104. * sets the X-TDE-PluginInfo-EnabledByDefault key in the .desktop file
  105. * (with the same name as the .rc file)
  106. *
  107. * If a disabled plugin is already loaded it will be removed from the GUI
  108. * factory and deleted.
  109. *
  110. * This method is automatically called by KParts::Plugin and by KParts::MainWindow.
  111. *
  112. * If you call this method in an already constructed GUI (like when the user
  113. * has changed which plugins are enabled) you need to add the new plugins to
  114. * the KXMLGUIFactory:
  115. * \code
  116. * if( factory() )
  117. * {
  118. * TQPtrList<KParts::Plugin> plugins = KParts::Plugin::pluginObjects( this );
  119. * TQPtrListIterator<KParts::Plugin> it( plugins );
  120. * KParts::Plugin * plugin;
  121. * while( ( plugin = it.current() ) != 0 )
  122. * {
  123. * ++it;
  124. * factory()->addClient( plugin );
  125. * }
  126. * }
  127. * \endcode
  128. */
  129. static void loadPlugins( TQObject *parent, KXMLGUIClient* parentGUIClient, TDEInstance* instance, bool enableNewPluginsByDefault = true );
  130. /**
  131. * Returns a list of plugin objects loaded for @p parent. This
  132. * functions basically calls the queryList method of
  133. * TQObject to retrieve the list of child objects inheriting
  134. * KParts::Plugin .
  135. **/
  136. static TQPtrList<Plugin> pluginObjects( TQObject *parent );
  137. protected:
  138. /**
  139. * Look for plugins in the @p instance's "data" directory (+"/kpartplugins")
  140. *
  141. * @return A list of TQDomDocument s, containing the parsed xml documents returned by plugins.
  142. */
  143. static TQValueList<Plugin::PluginInfo> pluginInfos( const TDEInstance * instance );
  144. /**
  145. * @internal
  146. * @return The plugin created from the library @p libname
  147. */
  148. static Plugin* loadPlugin( TQObject * parent, const char* libname );
  149. virtual void setInstance( TDEInstance *instance );
  150. private:
  151. static bool hasPlugin( TQObject* parent, const TQString& library );
  152. class PluginPrivate;
  153. PluginPrivate *d;
  154. };
  155. }
  156. #endif