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