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.

componentfactory.h 17KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401
  1. #ifndef __tdeparts_componentfactory_h__
  2. #define __tdeparts_componentfactory_h__
  3. #include <tdeparts/factory.h>
  4. #include <tdeparts/part.h>
  5. #include <ktrader.h>
  6. #include <tqmetaobject.h>
  7. namespace KParts
  8. {
  9. // this is a namespace and not a class because stupid egcs 1.1.2 doesn't grok
  10. // static template methods in classes. !@%@#$!
  11. /**
  12. * Namespace for KParts components
  13. */
  14. namespace ComponentFactory
  15. {
  16. /**
  17. * This enum type defines the possible error cases that can happen
  18. * when loading a component.
  19. *
  20. * <ul>
  21. * <li><code>ErrNoServiceFound</code> - no service implementing the
  22. * given mimetype and fullfilling the given constraint expression
  23. * can be found.</li>
  24. * <li><code>ErrServiceProvidesNoLibrary</code> - the specified service
  25. * provides no shared library</li>
  26. * <li><code>ErrNoLibrary</code> - the specified library could not be
  27. * loaded. Use KLibLoader::lastErrorMessage for details.</li>
  28. * <li><code>ErrNoFactory</code> - the library does not export a factory
  29. * for creating components</li>
  30. * <li><code>ErrNoComponent</code> - the factory does not support creating
  31. * components of the specified type</li>
  32. * </ul>
  33. */
  34. enum ComponentLoadingError { ErrNoServiceFound = 1,
  35. ErrServiceProvidesNoLibrary,
  36. ErrNoLibrary,
  37. ErrNoFactory,
  38. ErrNoComponent };
  39. /**
  40. * This template function allows to ask the given factory to create an
  41. * instance of the given template type.
  42. *
  43. * Example of usage:
  44. * \code
  45. * MyPlugin *plugin = KParts::ComponentFactory::createInstanceFromFactory<MyPlugin>( factory, parent );
  46. * \endcode
  47. *
  48. * @param factory The factory to ask for the creation of the component
  49. * @param parent The parent object (see TQObject constructor)
  50. * @param name The name of the object to create (see TQObject constructor)
  51. * @param args A list of string arguments, passed to the factory and possibly
  52. * to the component (see KLibFactory)
  53. * @return A pointer to the newly created object or a null pointer if the
  54. * factory was unable to create an object of the given type.
  55. */
  56. template <class T>
  57. static T *createInstanceFromFactory( KLibFactory *factory, TQObject *parent = 0,
  58. const char *name = 0,
  59. const TQStringList &args = TQStringList() )
  60. {
  61. TQObject *object = factory->create( parent, name,
  62. T::staticMetaObject()->className(),
  63. args );
  64. T *result = tqt_dynamic_cast<T *>( object );
  65. if ( !result )
  66. delete object;
  67. return result;
  68. }
  69. /**
  70. * This template function allows to ask the given tdeparts factory to create an
  71. * instance of the given template type.
  72. *
  73. * Example of usage:
  74. * \code
  75. * KViewPart *doc = KParts::ComponentFactory::createPartInstanceFromFactory<KViewPart>( factory, parent );
  76. * \endcode
  77. *
  78. * @param factory The factory to ask for the creation of the component
  79. * @param parentWidget the parent widget for the part
  80. * @param widgetName the name of the part's widget
  81. * @param parent The parent object (see TQObject constructor)
  82. * @param name The name of the object to create (see TQObject constructor)
  83. * @param args A list of string arguments, passed to the factory and possibly
  84. * to the component (see KLibFactory)
  85. * @return A pointer to the newly created object or a null pointer if the
  86. * factory was unable to create an object of the given type.
  87. */
  88. template <class T>
  89. static T *createPartInstanceFromFactory( KParts::Factory *factory,
  90. TQWidget *parentWidget = 0,
  91. const char *widgetName = 0,
  92. TQObject *parent = 0,
  93. const char *name = 0,
  94. const TQStringList &args = TQStringList() )
  95. {
  96. KParts::Part *object = factory->createPart( parentWidget, widgetName,
  97. parent, name,
  98. T::staticMetaObject()->className(),
  99. args );
  100. T *result = tqt_dynamic_cast<T *>( object );
  101. if ( !result )
  102. delete object;
  103. return result;
  104. }
  105. /**
  106. * This template allows to load the specified library and ask the
  107. * factory to create an instance of the given template type.
  108. *
  109. * @param libraryName The library to open
  110. * @param parent The parent object (see TQObject constructor)
  111. * @param name The name of the object to create (see TQObject constructor)
  112. * @param args A list of string arguments, passed to the factory and possibly
  113. * to the component (see KLibFactory)
  114. * @param error
  115. * @return A pointer to the newly created object or a null pointer if the
  116. * factory was unable to create an object of the given type.
  117. */
  118. template <class T>
  119. static T *createInstanceFromLibrary( const char *libraryName, TQObject *parent = 0,
  120. const char *name = 0,
  121. const TQStringList &args = TQStringList(),
  122. int *error = 0 )
  123. {
  124. KLibrary *library = KLibLoader::self()->library( libraryName );
  125. if ( !library )
  126. {
  127. if ( error )
  128. *error = ErrNoLibrary;
  129. return 0;
  130. }
  131. KLibFactory *factory = library->factory();
  132. if ( !factory )
  133. {
  134. library->unload();
  135. if ( error )
  136. *error = ErrNoFactory;
  137. return 0;
  138. }
  139. T *res = createInstanceFromFactory<T>( factory, parent, name, args );
  140. if ( !res )
  141. {
  142. library->unload();
  143. if ( error )
  144. *error = ErrNoComponent;
  145. }
  146. return res;
  147. }
  148. template <class T>
  149. static T *createPartInstanceFromLibrary( const char *libraryName,
  150. TQWidget *parentWidget = 0,
  151. const char *widgetName = 0,
  152. TQObject *parent = 0,
  153. const char *name = 0,
  154. const TQStringList &args = TQStringList(),
  155. int *error = 0 )
  156. {
  157. KLibrary *library = KLibLoader::self()->library( libraryName );
  158. if ( !library )
  159. {
  160. if ( error )
  161. *error = ErrNoLibrary;
  162. return 0;
  163. }
  164. KLibFactory *factory = library->factory();
  165. if ( !factory )
  166. {
  167. library->unload();
  168. if ( error )
  169. *error = ErrNoFactory;
  170. return 0;
  171. }
  172. KParts::Factory *partFactory = tqt_dynamic_cast<KParts::Factory *>( factory );
  173. if ( !partFactory )
  174. {
  175. library->unload();
  176. if ( error )
  177. *error = ErrNoFactory;
  178. return 0;
  179. }
  180. T *res = createPartInstanceFromFactory<T>( partFactory, parentWidget,
  181. widgetName, parent, name, args );
  182. if ( !res )
  183. {
  184. library->unload();
  185. if ( error )
  186. *error = ErrNoComponent;
  187. }
  188. return res;
  189. }
  190. template <class T>
  191. static T *createInstanceFromService( const KService::Ptr &service,
  192. TQObject *parent = 0,
  193. const char *name = 0,
  194. const TQStringList &args = TQStringList(),
  195. int *error = 0 )
  196. {
  197. TQString library = service->library();
  198. if ( library.isEmpty() )
  199. {
  200. if ( error )
  201. *error = ErrServiceProvidesNoLibrary;
  202. return 0;
  203. }
  204. return createInstanceFromLibrary<T>( library.local8Bit().data(), parent,
  205. name, args, error );
  206. }
  207. template <class T>
  208. static T *createPartInstanceFromService( const KService::Ptr &service,
  209. TQWidget *parentWidget = 0,
  210. const char *widgetName = 0,
  211. TQObject *parent = 0,
  212. const char *name = 0,
  213. const TQStringList &args = TQStringList(),
  214. int *error = 0 )
  215. {
  216. TQString library = service->library();
  217. if ( library.isEmpty() )
  218. {
  219. if ( error )
  220. *error = ErrServiceProvidesNoLibrary;
  221. return 0;
  222. }
  223. return createPartInstanceFromLibrary<T>( library.local8Bit().data(), parentWidget,
  224. widgetName, parent, name, args, error );
  225. }
  226. template <class T, class ServiceIterator>
  227. static T *createInstanceFromServices( ServiceIterator begin, ServiceIterator end,
  228. TQObject *parent = 0,
  229. const char *name = 0,
  230. const TQStringList &args = TQStringList(),
  231. int *error = 0 )
  232. {
  233. for (; begin != end; ++begin )
  234. {
  235. KService::Ptr service = *begin;
  236. if ( error )
  237. *error = 0;
  238. T *component = createInstanceFromService<T>( service, parent, name,
  239. args, error );
  240. if ( component )
  241. return component;
  242. }
  243. if ( error )
  244. *error = ErrNoServiceFound;
  245. return 0;
  246. }
  247. template <class T, class ServiceIterator>
  248. static T *createPartInstanceFromServices( ServiceIterator begin,
  249. ServiceIterator end,
  250. TQWidget *parentWidget = 0,
  251. const char *widgetName = 0,
  252. TQObject *parent = 0,
  253. const char *name = 0,
  254. const TQStringList &args = TQStringList(),
  255. int *error = 0 )
  256. {
  257. for (; begin != end; ++begin )
  258. {
  259. KService::Ptr service = *begin;
  260. if ( error )
  261. *error = 0;
  262. T *component = createPartInstanceFromService<T>( service, parentWidget,
  263. widgetName, parent,
  264. name, args, error );
  265. if ( component )
  266. return component;
  267. }
  268. if ( error )
  269. *error = ErrNoServiceFound;
  270. return 0;
  271. }
  272. /**
  273. * This method creates and returns a plugin, from the trader query for a given serviceType.
  274. *
  275. * Example:
  276. * \code
  277. * KMyAppPlugin* plugin = KParts::ComponentFactory::createInstanceFromQuery<KMyAppPlugin>( serviceType, TQString::null, parentObject );
  278. * if ( plugin ) {
  279. * ....
  280. * }
  281. * \endcode
  282. *
  283. * @param serviceType the type of service for which to find a plugin
  284. * @param constraint an optional constraint to pass to the trader (see TDEIO::TDETrader)
  285. * @param parent the parent object for the part itself
  286. * @param name the name that will be given to the part
  287. * @param args A list of string arguments, passed to the factory and possibly
  288. * to the component (see KLibFactory)
  289. * @param error The int passed here will receive an error code in case of errors.
  290. * (See enum #ComponentLoadingError)
  291. * @return A pointer to the newly created object or a null pointer if the
  292. * factory was unable to create an object of the given type.
  293. */
  294. template <class T>
  295. static T *createInstanceFromQuery( const TQString &serviceType,
  296. const TQString &constraint = TQString::null,
  297. TQObject *parent = 0,
  298. const char *name = 0,
  299. const TQStringList &args = TQStringList(),
  300. int *error = 0 )
  301. {
  302. TDETrader::OfferList offers = TDETrader::self()->query( serviceType, constraint );
  303. if ( offers.isEmpty() )
  304. {
  305. if ( error )
  306. *error = ErrNoServiceFound;
  307. return 0;
  308. }
  309. return createInstanceFromServices<T>( offers.begin(),
  310. offers.end(),
  311. parent, name, args, error );
  312. }
  313. /**
  314. * This method creates and returns a KParts part from a serviceType (e.g. a mimetype).
  315. *
  316. * You can use this method to create a generic viewer - that can display any
  317. * kind of file, provided that there is a ReadOnlyPart installed for it - in 5 lines:
  318. * \code
  319. * // Given the following: KURL url, TQWidget* parentWidget and TQObject* parentObject.
  320. * TQString mimetype = KMimeType::findByURL( url )->name();
  321. * KParts::ReadOnlyPart* part = KParts::ComponentFactory::createPartInstanceFromQuery<KParts::ReadOnlyPart>( mimetype, TQString::null, parentWidget, 0, parentObject, 0 );
  322. * if ( part ) {
  323. * part->openURL( url );
  324. * part->widget()->show(); // also insert the widget into a layout, or simply use a TQVBox as parentWidget
  325. * }
  326. * \endcode
  327. *
  328. * @param serviceType the type of service for which to find a part, e.g. a mimetype
  329. * @param constraint an optional constraint to pass to the trader (see TDETrader)
  330. * @param parentWidget the parent widget, will be set as the parent of the part's widget
  331. * @param widgetName the name that will be given to the part's widget
  332. * @param parent the parent object for the part itself
  333. * @param name the name that will be given to the part
  334. * @param args A list of string arguments, passed to the factory and possibly
  335. * to the component (see KLibFactory)
  336. * @param error The int passed here will receive an error code in case of errors.
  337. * (See enum #ComponentLoadingError)
  338. * @return A pointer to the newly created object or a null pointer if the
  339. * factory was unable to create an object of the given type.
  340. */
  341. template <class T>
  342. static T *createPartInstanceFromQuery( const TQString &serviceType,
  343. const TQString &constraint,
  344. TQWidget *parentWidget = 0,
  345. const char *widgetName = 0,
  346. TQObject *parent = 0,
  347. const char *name = 0,
  348. const TQStringList &args = TQStringList(),
  349. int *error = 0 )
  350. {
  351. TDETrader::OfferList offers = TDETrader::self()->query( serviceType, TQString::fromLatin1("KParts/ReadOnlyPart"), constraint, TQString::null );
  352. if ( offers.isEmpty() )
  353. {
  354. if ( error )
  355. *error = ErrNoServiceFound;
  356. return 0;
  357. }
  358. return createPartInstanceFromServices<T>( offers.begin(), offers.end(),
  359. parentWidget, widgetName,
  360. parent, name, args, error );
  361. }
  362. }
  363. }
  364. /*
  365. * vim: et sw=4
  366. */
  367. #endif