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.

part.h 21KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702
  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 _KPART_H
  18. #define _KPART_H
  19. #include <tqstring.h>
  20. #include <tqdom.h>
  21. #include <tqguardedptr.h>
  22. #include <kurl.h>
  23. #include <kxmlguiclient.h>
  24. class TDEInstance;
  25. class TQWidget;
  26. class TDEAction;
  27. class TDEActionCollection;
  28. class TQEvent;
  29. struct QUnknownInterface;
  30. namespace TDEIO {
  31. class Job;
  32. }
  33. namespace KParts
  34. {
  35. class PartManager;
  36. class Plugin;
  37. class PartPrivate;
  38. class PartActivateEvent;
  39. class PartSelectEvent;
  40. class GUIActivateEvent;
  41. class PartBasePrivate;
  42. /**
  43. * Base class for all parts.
  44. *
  45. * @short Base class for all parts.
  46. */
  47. class TDEPARTS_EXPORT PartBase : virtual public KXMLGUIClient
  48. {
  49. friend class PartBasePrivate;
  50. public:
  51. /**
  52. * Constructor.
  53. */
  54. PartBase();
  55. /**
  56. * Destructor.
  57. */
  58. virtual ~PartBase();
  59. /**
  60. * Internal method. Called by KParts::Part to specify the parent object for plugin objects.
  61. *
  62. * @internal
  63. */
  64. void setPartObject( TQObject *object );
  65. TQObject *partObject() const;
  66. protected:
  67. /**
  68. * Set the instance ( TDEInstance) for this part.
  69. *
  70. * Call this *first* in the inherited class constructor,
  71. * because it loads the i18n catalogues.
  72. */
  73. virtual void setInstance( TDEInstance *instance );
  74. /**
  75. * Set the instance ( TDEInstance) for this part.
  76. *
  77. * Call this *first* in the inherited class constructor,
  78. * because it loads the i18n catalogues.
  79. */
  80. virtual void setInstance( TDEInstance *instance, bool loadPlugins );
  81. /**
  82. * We have three different policies, whether to load new plugins or not. The
  83. * value in the TDEConfig object of the TDEInstance object always overrides
  84. * LoadPlugins and LoadPluginsIfEnabled.
  85. */
  86. enum PluginLoadingMode {
  87. /**
  88. * Don't load any plugins at all.
  89. */
  90. DoNotLoadPlugins = 0,
  91. /**
  92. * Load new plugins automatically. Can be
  93. * overridden by the plugin if it sets
  94. * EnabledByDefault=false in the corresponding
  95. * .desktop file.
  96. */
  97. LoadPlugins = 1,
  98. /**
  99. * New plugins are disabled by default. Can be
  100. * overridden by the plugin if it sets
  101. * EnabledByDefault=true in the corresponding
  102. * .desktop file.
  103. */
  104. LoadPluginsIfEnabled = 2
  105. };
  106. /**
  107. * Load the Plugins honoring the PluginLoadingMode.
  108. *
  109. * If you call this method in an already constructed GUI (like when the user
  110. * has changed which plugins are enabled) you need to add the new plugins to
  111. * the KXMLGUIFactory:
  112. * \code
  113. * if( factory() )
  114. * {
  115. * TQPtrList<KParts::Plugin> plugins = KParts::Plugin::pluginObjects( this );
  116. * TQPtrListIterator<KParts::Plugin> it( plugins );
  117. * KParts::Plugin * plugin;
  118. * while( ( plugin = it.current() ) != 0 )
  119. * {
  120. * ++it;
  121. * factory()->addClient( plugin );
  122. * }
  123. * }
  124. * \endcode
  125. */
  126. void loadPlugins( TQObject *parent, KXMLGUIClient *parentGUIClient, TDEInstance *instance );
  127. /**
  128. * For a KParts::Part: call this before setInstance().
  129. * For a KParts::MainWindow: call this before createGUI().
  130. */
  131. void setPluginLoadingMode( PluginLoadingMode loadingMode );
  132. private:
  133. PartBasePrivate *d;
  134. TQObject *m_obj;
  135. };
  136. /**
  137. * Base class for parts.
  138. *
  139. * A "part" is a GUI component, featuring:
  140. * @li A widget embeddedable in any application.
  141. * @li GUI elements that will be merged in the "host" user interface
  142. * (menubars, toolbars... ).
  143. *
  144. * <b>About the widget:</b>\n
  145. *
  146. * Note that KParts::Part does not inherit TQWidget.
  147. * This is due to the fact that the "visual representation"
  148. * will probably not be a mere TQWidget, but an elaborate one.
  149. * That's why when implementing your KParts::Part (or derived)
  150. * you should call KParts::Part::setWidget() in your constructor.
  151. *
  152. * <b>About the GUI elements:</b>\n
  153. *
  154. * Those elements trigger actions, defined by the part (action()).
  155. * The layout of the actions in the GUI is defined by an XML file (setXMLFile()).
  156. *
  157. * See also ReadOnlyPart and ReadWritePart, which define the
  158. * framework for a "viewer" part and for an "editor"-like part.
  159. * Use Part directly only if your part doesn't fit into those.
  160. */
  161. class TDEPARTS_EXPORT Part : public TQObject, public PartBase
  162. {
  163. Q_OBJECT
  164. public:
  165. /**
  166. * Constructor.
  167. *
  168. * @param parent Parent object of the part.
  169. * @param name QT-internal name of the part.
  170. */
  171. Part( TQObject *parent = 0, const char* name = 0 );
  172. /**
  173. * Destructor.
  174. */
  175. virtual ~Part();
  176. /**
  177. * Embed this part into a host widget.
  178. *
  179. * You don't need to do this if you created the widget with the
  180. * correct parent widget - this is just a TQWidget::reparent().
  181. * Note that the Part is still the holder
  182. * of the TQWidget, meaning that if you delete the Part,
  183. * then the widget gets destroyed as well, and vice-versa.
  184. * This method is not recommended since creating the widget with the correct
  185. * parent is simpler anyway.
  186. */
  187. virtual void embed( TQWidget * parentWidget );
  188. /**
  189. * @return The widget defined by this part, set by setWidget().
  190. */
  191. virtual TQWidget *widget();
  192. /**
  193. * @internal
  194. * Used by the part manager.
  195. */
  196. virtual void setManager( PartManager * manager );
  197. /**
  198. * Returns the part manager handling this part, if any (0L otherwise).
  199. */
  200. PartManager * manager() const;
  201. /**
  202. * Returns the part (this, or a child part) at the given global position.
  203. * This is called by the part manager to ask whether a part should be activated
  204. * when clicking somewhere. In most cases the default implementation is enough.
  205. * Reimplement this if your part has child parts in some areas (like in tdehtml or koffice)
  206. * @param widget the part widget being clicked - usually the same as widget(), except in koffice.
  207. * @param globalPos the mouse coordinates in global coordinates
  208. */
  209. virtual Part *hitTest( TQWidget *widget, const TQPoint &globalPos );
  210. /**
  211. * @param selectable Indicates whether the part is selectable or not.
  212. */
  213. virtual void setSelectable( bool selectable );
  214. /**
  215. * Returns whether the part is selectable or not.
  216. */
  217. bool isSelectable() const;
  218. signals:
  219. /**
  220. * Emitted by the part, to set the caption of the window(s)
  221. * hosting this part
  222. */
  223. void setWindowCaption( const TQString & caption );
  224. /**
  225. * Emited by the part, to set a text in the statusbar of the window(s)
  226. * hosting this part
  227. */
  228. void setStatusBarText( const TQString & text );
  229. protected:
  230. /**
  231. * Set the main widget.
  232. *
  233. * Call this in the Part-inherited class constructor.
  234. */
  235. virtual void setWidget( TQWidget * widget );
  236. /**
  237. * @internal
  238. */
  239. virtual void customEvent( TQCustomEvent *event );
  240. /**
  241. * Convenience method which is called when the Part received a PartActivateEvent .
  242. * Reimplement this if you don't want to reimplement event and test for the event yourself
  243. * or even install an event filter.
  244. */
  245. virtual void partActivateEvent( PartActivateEvent *event );
  246. /**
  247. * Convenience method which is called when the Part received a
  248. * PartSelectEvent .
  249. * Reimplement this if you don't want to reimplement event and
  250. * test for the event yourself or even install an event filter.
  251. */
  252. virtual void partSelectEvent( PartSelectEvent *event );
  253. /**
  254. * Convenience method which is called when the Part received a
  255. * GUIActivateEvent .
  256. * Reimplement this if you don't want to reimplement event and
  257. * test for the event yourself or even install an event filter.
  258. */
  259. virtual void guiActivateEvent( GUIActivateEvent *event );
  260. /**
  261. * Convenience method for KXMLGUIFactory::container.
  262. * @return a container widget owned by the Part's GUI.
  263. */
  264. TQWidget *hostContainer( const TQString &containerName );
  265. private slots:
  266. void slotWidgetDestroyed();
  267. private:
  268. TQGuardedPtr<TQWidget> m_widget;
  269. PartManager * m_manager;
  270. PartPrivate *d;
  271. };
  272. class ReadWritePart;
  273. class ReadOnlyPartPrivate;
  274. /**
  275. * Base class for any "viewer" part.
  276. *
  277. * This class takes care of network transparency for you,
  278. * in the simplest way (downloading to a temporary file, then letting the part
  279. * load from the temporary file).
  280. * To use the built-in network transparency, you only need to implement
  281. * openFile(), not openURL().
  282. *
  283. * To implement network transparency differently (e.g. for progressive loading,
  284. * like a web browser does for instance), or to prevent network transparency
  285. * (but why would you do that?), you can override openURL().
  286. *
  287. * KParts Application can use the signals to show feedback while the URL is being loaded.
  288. *
  289. * ReadOnlyPart handles the window caption by setting it to the current URL
  290. * (set in openURL(), and each time the part is activated).
  291. * If you want another caption, set it in openFile() and
  292. * (if the part might ever be used with a part manager) in guiActivateEvent()
  293. */
  294. class TDEPARTS_EXPORT ReadOnlyPart : public Part
  295. {
  296. Q_OBJECT
  297. friend class ReadWritePart;
  298. public:
  299. /**
  300. * Constructor
  301. * See also Part for the setXXX methods to call.
  302. */
  303. ReadOnlyPart( TQObject *parent = 0, const char *name = 0 );
  304. /**
  305. * Destructor
  306. */
  307. virtual ~ReadOnlyPart();
  308. /**
  309. * Call this to turn off the progress info dialog used by
  310. * the internal TDEIO job. Use this if you provide another way
  311. * of displaying progress info (e.g. a statusbar), using the
  312. * signals emitted by this class, and/or those emitted by
  313. * the Job given by started.
  314. */
  315. void setProgressInfoEnabled( bool show );
  316. /**
  317. * Returns whether the part shows the progress info dialog used by internal
  318. * TDEIO job.
  319. */
  320. bool isProgressInfoEnabled() const;
  321. #ifndef KDE_NO_COMPAT
  322. void showProgressInfo( bool show );
  323. #endif
  324. public slots:
  325. /**
  326. * Only reimplement openURL if you don't want the network transparency support
  327. * to download from the url into a temporary file (when the url isn't local).
  328. * Otherwise, reimplement openFile() only .
  329. *
  330. * If you reimplement it, don't forget to set the caption, usually with
  331. * emit setWindowCaption( url.prettyURL() );
  332. */
  333. virtual bool openURL( const KURL &url );
  334. public:
  335. /**
  336. * Returns the currently in part used URL.
  337. *
  338. * @return The current used URL.
  339. */
  340. KURL url() const { return m_url; }
  341. /**
  342. * Called when closing the current url (e.g. document), for instance
  343. * when switching to another url (note that openURL() calls it
  344. * automatically in this case).
  345. * If the current URL is not fully loaded yet, aborts loading.
  346. * Deletes the temporary file used when the url is remote.
  347. * @return always true, but the return value exists for reimplementations
  348. */
  349. virtual bool closeURL();
  350. public:
  351. /**
  352. * Initiate sending data to this part.
  353. * This is an alternative to openURL, which allows the user of the part
  354. * to load the data itself, and send it progressively to the part.
  355. *
  356. * @param mimeType the type of data that is going to be sent to this part.
  357. * @param url the URL representing this data. Although not directly used,
  358. * every ReadOnlyPart has a URL (see url()), so this simply sets it.
  359. * @return true if the part supports progressive loading and accepts data, false otherwise.
  360. */
  361. bool openStream( const TQString& mimeType, const KURL& url );
  362. /**
  363. * Send some data to the part. openStream must have been called previously,
  364. * and must have returned true.
  365. * @return true if the data was accepted by the part. If false is returned,
  366. * the application should stop sending data, and doesn't have to call closeStream.
  367. */
  368. bool writeStream( const TQByteArray& data );
  369. /**
  370. * Terminate the sending of data to the part.
  371. * With some data types (text, html...) closeStream might never actually be called,
  372. * in the case of continuous streams, for instance plain text or HTML data.
  373. */
  374. bool closeStream();
  375. private: // Makes no sense for inherited classes to call those. But make it protected there.
  376. /**
  377. * Called by openStream to initiate sending of data.
  378. * Parts which implement progress loading should check the @p mimeType
  379. * parameter, and return true if they can accept a data stream of that type.
  380. */
  381. virtual bool doOpenStream( const TQString& /*mimeType*/ ) { return false; }
  382. /**
  383. * Receive some data from the hosting application.
  384. * In this method the part should attempt to display the data progressively.
  385. * With some data types (text, html...) closeStream might never actually be called,
  386. * in the case of continuous streams. This can't happen with e.g. images.
  387. */
  388. virtual bool doWriteStream( const TQByteArray& /*data*/ ) { return false; }
  389. /**
  390. * This is called by closeStream(), to indicate that all the data has been sent.
  391. * Parts should ensure that all of the data is displayed at this point.
  392. * @return whether the data could be displayed correctly.
  393. */
  394. virtual bool doCloseStream() { return false; }
  395. signals:
  396. /**
  397. * The part emits this when starting data.
  398. * If using a TDEIO::Job, it sets the job in the signal, so that
  399. * progress information can be shown. Otherwise, job is 0.
  400. **/
  401. void started( TDEIO::Job * );
  402. /**
  403. * Emit this when you have completed loading data.
  404. * Hosting apps will want to know when the process of loading the data
  405. * is finished, so that they can access the data when everything is loaded.
  406. **/
  407. void completed();
  408. /**
  409. * Same as the above signal except it indicates whether there is
  410. * a pending action to be executed on a delay timer. An example of
  411. * this is the meta-refresh tags on web pages used to reload/redirect
  412. * after a certain period of time. This signal is useful if you want
  413. * to give the user the ability to cancel such pending actions.
  414. *
  415. * @param pendingAction true if a pending action exists, false otherwise.
  416. */
  417. void completed( bool pendingAction );
  418. /**
  419. * Emit this if loading is canceled by the user or by an error.
  420. * @param errMsg the error message, empty if the user canceled the loading voluntarily.
  421. */
  422. void canceled( const TQString &errMsg );
  423. protected slots:
  424. void slotJobFinished( TDEIO::Job * job );
  425. protected:
  426. /**
  427. * If the part uses the standard implementation of openURL(),
  428. * it must reimplement this, to open @p m_file.
  429. * Otherwise simply define it to { return false; }
  430. */
  431. virtual bool openFile() = 0;
  432. /**
  433. * @internal
  434. */
  435. void abortLoad();
  436. /**
  437. * Reimplemented from Part, so that the window caption is set to
  438. * the current url (decoded) when the part is activated.
  439. * This is the usual behavior in 99% of the apps.
  440. * Reimplement if you don't like it - test for event->activated() !
  441. *
  442. * Technical note : this is done with GUIActivateEvent and not with
  443. * PartActivateEvent because it's handled by the mainwindow
  444. * (which gets the even after the PartActivateEvent events have been sent)
  445. */
  446. virtual void guiActivateEvent( GUIActivateEvent *event );
  447. /**
  448. * Remote (or local) url - the one displayed to the user.
  449. */
  450. KURL m_url;
  451. /**
  452. * Local file - the only one the part implementation should deal with.
  453. */
  454. TQString m_file;
  455. /**
  456. * If @p true, @p m_file is a temporary file that needs to be deleted later.
  457. */
  458. bool m_bTemp;
  459. private:
  460. ReadOnlyPartPrivate *d;
  461. };
  462. /**
  463. * Base class for an "editor" part.
  464. *
  465. * This class handles network transparency for you.
  466. * Anything that can open a URL, allow modifications, and save
  467. * (to the same URL or a different one).
  468. *
  469. * A read-write part can be set to read-only mode, using setReadWrite().
  470. *
  471. * Part writers :
  472. * Any part inheriting ReadWritePart should check isReadWrite()
  473. * before allowing any action that modifies the part.
  474. * The part probably wants to reimplement setReadWrite, disable those
  475. * actions. Don't forget to call the parent setReadWrite().
  476. */
  477. class TDEPARTS_EXPORT ReadWritePart : public ReadOnlyPart
  478. {
  479. Q_OBJECT
  480. public:
  481. /**
  482. * Constructor.
  483. * See parent constructor for instructions.
  484. */
  485. ReadWritePart( TQObject *parent = 0, const char *name = 0 );
  486. /**
  487. * Destructor.
  488. * Applications using a ReadWritePart should make sure, before
  489. * destroying it, to call closeURL().
  490. * In TDEMainWindow::queryClose(), for instance, they should allow
  491. * closing only if the return value of closeURL() was true.
  492. * This allows to cancel.
  493. */
  494. virtual ~ReadWritePart();
  495. /**
  496. * @return true if the part is in read-write mode
  497. */
  498. bool isReadWrite() const { return m_bReadWrite; }
  499. /**
  500. * Changes the behavior of this part to readonly or readwrite.
  501. * @param readwrite set to true to enable readwrite mode
  502. */
  503. virtual void setReadWrite ( bool readwrite = true );
  504. /**
  505. * @return true if the document has been modified.
  506. */
  507. bool isModified() const { return m_bModified; }
  508. /**
  509. * If the document has been modified, ask the user to save changes.
  510. * This method is meant to be called from TDEMainWindow::queryClose().
  511. * It will also be called from closeURL().
  512. *
  513. * @return true if closeURL() can be called without the user losing
  514. * important data, false if the user chooses to cancel.
  515. *
  516. * @since 3.2
  517. */
  518. // TODO: Make virtual for KDE 4
  519. bool queryClose();
  520. /**
  521. * Called when closing the current url (e.g. document), for instance
  522. * when switching to another url (note that openURL() calls it
  523. * automatically in this case).
  524. *
  525. * If the current URL is not fully loaded yet, aborts loading.
  526. *
  527. * If isModified(), queryClose() will be called.
  528. *
  529. * @return false on cancel
  530. */
  531. virtual bool closeURL();
  532. /**
  533. * Call this method instead of the above if you need control if
  534. * the save prompt is shown. For example, if you call queryClose()
  535. * from TDEMainWindow::queryClose(), you would not want to prompt
  536. * again when closing the url.
  537. *
  538. * Equivalent to promptToSave ? closeURL() : ReadOnlyPart::closeURL()
  539. *
  540. * @since 3.2
  541. */
  542. // TODO: Make virtual for KDE 4
  543. bool closeURL( bool promptToSave );
  544. /**
  545. * Save the file to a new location.
  546. *
  547. * Calls save(), no need to reimplement
  548. */
  549. virtual bool saveAs( const KURL &url );
  550. /**
  551. * Sets the modified flag of the part.
  552. */
  553. virtual void setModified( bool modified );
  554. signals:
  555. /**
  556. * @since 3.2, remove in KDE 4, when queryClose is made virtual
  557. *
  558. * set handled to true, if you don't want the default handling
  559. * set abortClosing to true, if you handled the request,
  560. * but for any reason don't want to allow closing the document
  561. */
  562. void sigQueryClose(bool *handled, bool* abortClosing);
  563. public slots:
  564. /**
  565. * Call setModified() whenever the contents get modified.
  566. * This is a slot for convenience, so that you can connect it
  567. * to a signal, like textChanged().
  568. */
  569. virtual void setModified();
  570. /**
  571. * Save the file in the location from which it was opened.
  572. * You can connect this to the "save" action.
  573. * Calls saveFile() and saveToURL(), no need to reimplement.
  574. */
  575. virtual bool save();
  576. /**
  577. * Waits for any pending upload job to finish and returns whether the
  578. * last save() action was successful.
  579. */
  580. bool waitSaveComplete();
  581. protected:
  582. /**
  583. * Save to a local file.
  584. * You need to implement it, to save to @p m_file.
  585. * The framework takes care of re-uploading afterwards.
  586. *
  587. * @return true on success, false on failure.
  588. * On failure the function should inform the user about the
  589. * problem with an appropriate message box. Standard error
  590. * messages can be constructed using TDEIO::buildErrorString()
  591. * in combination with the error codes defined in tdeio/global.h
  592. */
  593. virtual bool saveFile() = 0;
  594. /**
  595. * Save the file.
  596. *
  597. * Uploads the file, if @p m_url is remote.
  598. * This will emit started(), and either completed() or canceled(),
  599. * in case you want to provide feedback.
  600. * @return true on success, false on failure.
  601. */
  602. virtual bool saveToURL();
  603. protected slots:
  604. /**
  605. * @internal
  606. */
  607. void slotUploadFinished( TDEIO::Job * job );
  608. private:
  609. void prepareSaving();
  610. private:
  611. bool m_bModified;
  612. bool m_bReadWrite;
  613. bool m_bClosing;
  614. };
  615. } // namespace
  616. #endif