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.
 
 
 
 
 
 

440 lines
15 KiB

  1. // -*- mode: c++; c-basic-offset: 2 -*-
  2. /* This file is part of the KDE libraries
  3. Copyright (C) 2000 Kurt Granroth <granroth@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 version 2 as published by the Free Software Foundation.
  7. This library is distributed in the hope that it will be useful,
  8. but WITHOUT ANY WARRANTY; without even the implied warranty of
  9. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  10. Library General Public License for more details.
  11. You should have received a copy of the GNU Library General Public License
  12. along with this library; see the file COPYING.LIB. If not, write to
  13. the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  14. Boston, MA 02110-1301, USA.
  15. */
  16. #ifndef _KEDITTOOLBAR_H
  17. #define _KEDITTOOLBAR_H
  18. #include <tqwidget.h>
  19. #include <kxmlguiclient.h>
  20. #include <kdialogbase.h>
  21. class KProcess;
  22. class KActionCollection;
  23. class TQComboBox;
  24. class TQToolButton;
  25. class KListView;
  26. class TQListViewItem;
  27. class KEditToolbarWidget;
  28. class KEditToolbarPrivate;
  29. class KEditToolbarWidgetPrivate;
  30. namespace
  31. {
  32. class ToolbarItem;
  33. class ToolbarListView;
  34. }
  35. /**
  36. * @short A dialog used to customize or configure toolbars.
  37. *
  38. * This dialog only works if your application uses the XML UI
  39. * framework for creating menus and toolbars. It depends on the XML
  40. * files to describe the toolbar layouts and it requires the actions
  41. * to determine which buttons are active.
  42. *
  43. * Typically, you would include the KStdAction::configureToolbars()
  44. * standard action in your application. In your slot to this action,
  45. * you would have something like so:
  46. *
  47. * \code
  48. * KEditToolbar dlg(actionCollection());
  49. * if (dlg.exec())
  50. * {
  51. * createGUI();
  52. * }
  53. * \endcode
  54. *
  55. * That code snippet also takes care of redrawing the menu and
  56. * toolbars if you have made any changes.
  57. *
  58. * If you are using KMainWindow's settings methods (either save/apply manually
  59. * or autoSaveSettings), you should write something like:
  60. * \code
  61. * void MyClass::slotConfigureToolbars()
  62. * {
  63. * saveMainWindowSettings( KGlobal::config(), "MainWindow" );
  64. * KEditToolbar dlg(actionCollection());
  65. * connect(&dlg,TQT_SIGNAL(newToolbarConfig()),this,TQT_SLOT(slotNewToolbarConfig()));
  66. * dlg.exec();
  67. * }
  68. *
  69. * void MyClass::slotNewToolbarConfig() // This is called when OK, Apply or Defaults is clicked
  70. * {
  71. * ...if you use any action list, use plugActionList on each here...
  72. * createGUI();
  73. * applyMainWindowSettings( KGlobal::config(), "MainWindow" );
  74. * }
  75. * \endcode
  76. *
  77. * Note that the procedure is a bit different for KParts applications.
  78. * In this case, you need only pass along a pointer to your
  79. * application's KXMLGUIFactory object. The editor will take care of
  80. * finding all of the action collections and XML files. The editor
  81. * aims to be semi-intelligent about where it assigns any
  82. * modifications. In other words, it will not write out part specific
  83. * changes to your shell's XML file.
  84. *
  85. * An example would be:
  86. *
  87. * \code
  88. * saveMainWindowSettings( KGlobal::config(), "MainWindow" );
  89. * KEditToolbar dlg(factory());
  90. * connect(&dlg,TQT_SIGNAL(newToolbarConfig()),this,TQT_SLOT(slotNewToolbarConfig()));
  91. * dlg.exec();
  92. *
  93. * void MyClass::slotNewToolbarConfig() // This is called when OK, Apply or Defaults is clicked
  94. * {
  95. * ...if you use any action list, use plugActionList on each here...
  96. * // Do NOT call createGUI()!
  97. * applyMainWindowSettings( KGlobal::config(), "MainWindow" );
  98. * }
  99. * \endcode
  100. *
  101. * @author Kurt Granroth <granroth@kde.org>
  102. * @version $Id$
  103. */
  104. class TDEUI_EXPORT KEditToolbar : public KDialogBase
  105. {
  106. Q_OBJECT
  107. public:
  108. /**
  109. * Constructor for apps that do not use components.
  110. *
  111. * This is the
  112. * only entry point to this class. You @em must pass along your
  113. * collection of actions (some of which appear in your toolbars).
  114. * The other two parameters are optional.
  115. *
  116. * The second parameter, xmlfile(), is the name (absolute or
  117. * relative) of your application's UI resource file. If it is
  118. * left blank, then the resource file: share/apps/appname/appnameui.rc
  119. * is used. This is the same resource file that is used by the
  120. * default createGUI() function in KMainWindow so you're usually
  121. * pretty safe in leaving it blank.
  122. *
  123. * The third parameter, global(), controls whether or not the
  124. * global resource file is used. If this is @p true, then you may
  125. * edit all of the actions in your toolbars -- global ones and
  126. * local one. If it is @p false, then you may edit only your
  127. * application's entries. The only time you should set this to
  128. * false is if your application does not use the global resource
  129. * file at all (very rare).
  130. *
  131. * @param collection The collection of actions to work on.
  132. * @param xmlfile The application's local resource file.
  133. * @param global If @p true, then the global resource file will also
  134. * be parsed.
  135. * @param parent The parent of the dialog.
  136. * @param name An internal name.
  137. */
  138. KEditToolbar(KActionCollection *collection,
  139. const TQString& xmlfile = TQString::null, bool global = true,
  140. TQWidget* parent = 0, const char* name = 0);
  141. //KDE 4.0: merge the two constructors
  142. /* Constructor for apps that do not use components, which has an extra argument
  143. * specifying the toolbar to be shown.
  144. * @param defaultToolbar The toolbar with this name will appear for editing.
  145. * @param collection The collection of actions to work on.
  146. * @param xmlfile The application's local resource file.
  147. * @param global If @p true, then the global resource file will also
  148. * be parsed.
  149. * @param parent The parent of the dialog.
  150. * @param name An internal name.
  151. * @since 3.2
  152. */
  153. KEditToolbar(const TQString& defaultToolbar, KActionCollection *collection,
  154. const TQString& xmlfile = TQString::null, bool global = true,
  155. TQWidget* parent = 0, const char* name = 0);
  156. /**
  157. * Constructor for KParts based apps.
  158. *
  159. * The main parameter, factory(), is a pointer to the
  160. * XML GUI factory object for your application. It contains a list
  161. * of all of the GUI clients (along with the action collections and
  162. * xml files) and the toolbar editor uses that.
  163. *
  164. * Use this like so:
  165. * \code
  166. * KEditToolbar edit(factory());
  167. * if ( edit.exec() )
  168. * ...
  169. * \endcode
  170. *
  171. * @param factory Your application's factory object
  172. * @param parent The usual parent for the dialog.
  173. * @param name An internal name.
  174. *
  175. * Some people seem tempted to use this also in non-KParts apps, using KMainWindow::guiFactory().
  176. * This works, but only _if_ setting conserveMemory to false when calling
  177. * KMainWindow::createGUI()! If not, use the other KEditToolbar constructor.
  178. */
  179. KEditToolbar(KXMLGUIFactory* factory, TQWidget* parent = 0, const char* name = 0);
  180. //KDE 4.0: merge the two constructors
  181. /** Constructor for KParts based apps, which has an extra argument
  182. * specifying the toolbar to be shown.
  183. *
  184. * @param defaultToolbar The toolbar with this name will appear for editing.
  185. * @param factory Your application's factory object
  186. * @param parent The usual parent for the dialog.
  187. * @param name An internal name.
  188. * @since 3.2
  189. */
  190. KEditToolbar(const TQString& defaultToolbar, KXMLGUIFactory* factory,
  191. TQWidget* parent = 0, const char* name = 0);
  192. /// destructor
  193. ~KEditToolbar();
  194. /** Sets the default toolbar, which will be auto-selected when the constructor without the
  195. * defaultToolbar argument is used.
  196. * @param toolbarName the name of the toolbar
  197. * @since 3.3
  198. */
  199. static void setDefaultToolbar(const char *toolbarName);
  200. protected slots:
  201. /**
  202. * Overridden in order to save any changes made to the toolbars
  203. */
  204. virtual void slotOk();
  205. /**
  206. * idem
  207. */
  208. virtual void slotApply();
  209. /** should OK really save?
  210. * @internal
  211. **/
  212. void acceptOK(bool b);
  213. /**
  214. * Set toolbars to default value
  215. **/
  216. void slotDefault();
  217. signals:
  218. /**
  219. * Signal emitted when 'apply' or 'ok' is clicked or toolbars were resetted.
  220. * Connect to it, to plug action lists and to call applyMainWindowSettings
  221. * (see sample code in this class's documentation)
  222. */
  223. void newToolbarConfig();
  224. private:
  225. void init();
  226. KEditToolbarWidget *m_widget;
  227. protected:
  228. virtual void virtual_hook( int id, void* data );
  229. private:
  230. KEditToolbarPrivate *d;
  231. static const char *s_defaultToolbar;
  232. };
  233. /**
  234. * @short A widget used to customize or configure toolbars
  235. *
  236. * This is the widget that does all of the work for the
  237. * KEditToolbar dialog. In most cases, you will want to use the
  238. * dialog instead of this widget directly.
  239. *
  240. * Typically, you would use this widget only if you wanted to embed
  241. * the toolbar editing directly into your existing configure or
  242. * preferences dialog.
  243. *
  244. * This widget only works if your application uses the XML UI
  245. * framework for creating menus and toolbars. It depends on the XML
  246. * files to describe the toolbar layouts and it requires the actions
  247. * to determine which buttons are active.
  248. *
  249. * @author Kurt Granroth <granroth@kde.org>
  250. * @version $Id$
  251. */
  252. class TDEUI_EXPORT KEditToolbarWidget : public TQWidget, virtual public KXMLGUIClient
  253. {
  254. Q_OBJECT
  255. public:
  256. /**
  257. * Constructor. This is the only entry point to this class. You
  258. * @p must pass along your collection of actions (some of which
  259. * appear in your toolbars). The other three parameters are
  260. * optional.
  261. *
  262. * The second parameter, xmlfile, is the name (absolute or
  263. * relative) of your application's UI resource file. If it is
  264. * left blank, then the resource file: share/apps/appname/appnameui.rc
  265. * is used. This is the same resource file that is used by the
  266. * default createGUI function in KMainWindow so you're usually
  267. * pretty safe in leaving it blank.
  268. *
  269. * The third parameter, global, controls whether or not the
  270. * global resource file is used. If this is true, then you may
  271. * edit all of the actions in your toolbars -- global ones and
  272. * local one. If it is false, then you may edit only your
  273. * application's entries. The only time you should set this to
  274. * false is if your application does not use the global resource
  275. * file at all (very rare)
  276. *
  277. * The last parameter, parent, is the standard parent stuff.
  278. *
  279. * @param collection The collection of actions to work on
  280. * @param xmlfile The application's local resource file
  281. * @param global If true, then the global resource file will also
  282. * be parsed
  283. * @param parent This widget's parent
  284. */
  285. KEditToolbarWidget(KActionCollection *collection,
  286. const TQString& xmlfile = TQString::null,
  287. bool global = true, TQWidget *parent = 0L);
  288. //KDE 4.0: merge the two constructors
  289. /* Same as above, with an extra agrument specifying the toolbar to be shown.
  290. *
  291. * @param defaultToolbar The toolbar with this name will appear for editing.
  292. * @param collection The collection of actions to work on
  293. * @param xmlfile The application's local resource file
  294. * @param global If true, then the global resource file will also
  295. * be parsed
  296. * @param parent This widget's parent
  297. * @since 3.2
  298. */
  299. KEditToolbarWidget(const TQString& defaultToolbar,
  300. KActionCollection *collection,
  301. const TQString& file = TQString::null,
  302. bool global = true,
  303. TQWidget *parent = 0L);
  304. /**
  305. * Constructor for KParts based apps.
  306. *
  307. * The first parameter, factory, is a pointer to the XML GUI
  308. * factory object for your application. It contains a list of all
  309. * of the GUI clients (along with the action collections and xml
  310. * files) and the toolbar editor uses that.
  311. *
  312. * The second parameter, parent, is the standard parent
  313. *
  314. * Use this like so:
  315. * \code
  316. * KEditToolbar edit(factory());
  317. * if ( edit.exec() )
  318. * ...
  319. * \endcode
  320. *
  321. * @param factory Your application's factory object
  322. * @param parent This widget's parent
  323. */
  324. KEditToolbarWidget(KXMLGUIFactory* factory, TQWidget *parent = 0L);
  325. //KDE 4.0: merge the two constructors
  326. /* Same as above, with an extra agrument specifying the toolbar to be shown.
  327. *
  328. *
  329. * @param defaultToolbar The toolbar with this name will appear for editing.
  330. * @param factory Your application's factory object
  331. * @param parent This widget's parent
  332. * @since 3.2
  333. */
  334. KEditToolbarWidget(const TQString& defaultToolbar,
  335. KXMLGUIFactory* factory,
  336. TQWidget *parent = 0L);
  337. /**
  338. * Destructor. Note that any changes done in this widget will
  339. * @p NOT be saved in the destructor. You @p must call save()
  340. * to do that.
  341. */
  342. virtual ~KEditToolbarWidget();
  343. /**
  344. * @internal Reimplemented for internal purposes.
  345. */
  346. virtual KActionCollection *actionCollection() const;
  347. /**
  348. * Save any changes the user made. The file will be in the user's
  349. * local directory (usually $HOME/.trinity/share/apps/\<appname\>). The
  350. * filename will be the one specified in the constructor.. or the
  351. * made up one if the filename was NULL.
  352. *
  353. * @return The status of whether or not the save succeeded.
  354. */
  355. bool save();
  356. /**
  357. * Remove and readd all KMXLGUIClients to update the GUI
  358. * @since 3.5
  359. */
  360. void rebuildKXMLGUIClients();
  361. signals:
  362. /**
  363. * Emitted whenever any modifications are made by the user.
  364. */
  365. void enableOk(bool);
  366. protected slots:
  367. void slotToolbarSelected(const TQString& text);
  368. void slotInactiveSelected(TQListViewItem *item);
  369. void slotActiveSelected(TQListViewItem *item);
  370. void slotDropped(KListView *list, TQDropEvent *e, TQListViewItem *after);
  371. void slotInsertButton();
  372. void slotRemoveButton();
  373. void slotUpButton();
  374. void slotDownButton();
  375. void slotChangeIcon();
  376. private slots:
  377. void slotProcessExited( KProcess* );
  378. protected: // KDE4: make private
  379. void setupLayout();
  380. void insertActive(ToolbarItem *item, TQListViewItem *before, bool prepend = false);
  381. void removeActive(ToolbarItem *item);
  382. void moveActive(ToolbarItem *item, TQListViewItem *before);
  383. void initNonKPart(KActionCollection *collection, const TQString& file, bool global);
  384. void initKPart(KXMLGUIFactory* factory);
  385. void loadToolbarCombo(const TQString& defaultToolbar = TQString::null);
  386. void loadActionList(TQDomElement& elem);
  387. void updateLocal(TQDomElement& elem);
  388. private:
  389. ToolbarListView *m_inactiveList;
  390. ToolbarListView *m_activeList;
  391. TQComboBox *m_toolbarCombo;
  392. TQToolButton *m_upAction;
  393. TQToolButton *m_removeAction;
  394. TQToolButton *m_insertAction;
  395. TQToolButton *m_downAction;
  396. protected:
  397. virtual void virtual_hook( int id, void* data );
  398. private:
  399. KEditToolbarWidgetPrivate *d;
  400. };
  401. #endif // _KEDITTOOLBAR_H