Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 1422 insertions, 0 deletions

diff --git a/kdeui/kactionclasses.h b/kdeui/kactionclasses.h
new file mode 100644
index 000000000..6c6fe5ca8
--- /dev/null
+++ b/kdeui/kactionclasses.h
@@ -0,0 +1,1422 @@
+/* This file is part of the KDE libraries
+    Copyright (C) 1999 Reginald Stadlbauer <[email protected]>
+              (C) 1999 Simon Hausmann <[email protected]>
+              (C) 2000 Nicolas Hadacek <[email protected]>
+              (C) 2000 Kurt Granroth <[email protected]>
+              (C) 2000 Michael Koch <[email protected]>
+              (C) 2001 Holger Freyther <[email protected]>
+              (C) 2002 Ellis Whitehead <[email protected]>
+              (C) 2003 Andras Mantia <[email protected]>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Library General Public
+    License version 2 as published by the Free Software Foundation.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Library General Public License for more details.
+
+    You should have received a copy of the GNU Library General Public License
+    along with this library; see the file COPYING.LIB.  If not, write to
+    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+    Boston, MA 02110-1301, USA.
+*/
+//$Id$
+
+#ifndef __kactionclasses_h__
+#define __kactionclasses_h__
+
+#include <kaction.h>
+
+#include <qkeysequence.h>
+#include <qobject.h>
+#include <qvaluelist.h>
+#include <qguardedptr.h>
+#include <kguiitem.h>
+#include <kshortcut.h>
+#include <kstdaction.h>
+#include <kicontheme.h>
+
+class QMenuBar;
+class QPopupMenu;
+class QComboBox;
+class QPoint;
+class QIconSet;
+class QString;
+class KToolBar;
+
+class KAccel;
+class KAccelActions;
+class KConfig;
+class KConfigBase;
+class KURL;
+class KInstance;
+class KToolBar;
+class KActionCollection;
+class KPopupMenu;
+class KMainWindow;
+
+/**
+ *  @short Checkbox like action.
+ *
+ *  Checkbox like action.
+ *
+ *  This action provides two states: checked or not.
+ *
+ */
+class KDEUI_EXPORT KToggleAction : public KAction
+{
+    Q_OBJECT
+    Q_PROPERTY( bool checked READ isChecked WRITE setChecked )
+    Q_PROPERTY( QString exclusiveGroup READ exclusiveGroup WRITE setExclusiveGroup )
+public:
+
+    /**
+     * Constructs a toggle action with text and potential keyboard
+     * accelerator but nothing else. Use this only if you really
+     * know what you are doing.
+     *
+     * @param text The text that will be displayed.
+     * @param cut The corresponding keyboard accelerator (shortcut).
+     * @param parent This action's parent.
+     * @param name An internal name for this action.
+     */
+    KToggleAction( const QString& text, const KShortcut& cut = KShortcut(), QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KToggleAction( const QString& text, const KShortcut& cut,
+                   const QObject* receiver, const char* slot, QObject* parent, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The icons that go with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KToggleAction( const QString& text, const QIconSet& pix, const KShortcut& cut = KShortcut(),
+             QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The dynamically loaded icon that goes with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KToggleAction( const QString& text, const QString& pix, const KShortcut& cut = KShortcut(),
+                   QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The icons that go with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KToggleAction( const QString& text, const QIconSet& pix, const KShortcut& cut,
+                   const QObject* receiver, const char* slot, QObject* parent, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The dynamically loaded icon that goes with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KToggleAction( const QString& text, const QString& pix, const KShortcut& cut,
+                   const QObject* receiver, const char* slot,
+                   QObject* parent, const char* name = 0 );
+
+    /**
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KToggleAction( QObject* parent = 0, const char* name = 0 );
+
+    /**
+     * Destructor
+     */
+    virtual ~KToggleAction();
+
+    /**
+     *  "Plug" or insert this action into a given widget.
+     *
+     *  This will typically be a menu or a toolbar.  From this point
+     *  on, you will never need to directly manipulate the item in the
+     *  menu or toolbar.  You do all enabling/disabling/manipulation
+     *  directly with your KToggleAction object.
+     *
+     *  @param widget The GUI element to display this action.
+     *  @param index  The index of the item.
+     */
+    virtual int plug( QWidget* widget, int index = -1 );
+
+    /**
+     *  Returns the actual state of the action.
+     */
+    bool isChecked() const;
+
+    /**
+     * @return which "exclusive group" this action is part of.
+     * @see setExclusiveGroup
+     */
+    QString exclusiveGroup() const;
+
+    /**
+     * Defines which "exclusive group" this action is part of.
+     * In a given exclusive group, only one toggle action can be checked
+     * at a any moment. Checking an action unchecks the other actions
+     * of the group.
+     */
+    virtual void setExclusiveGroup( const QString& name );
+
+    /**
+     * Defines the text (and icon, tooltip, whatsthis) that should be displayed
+     * instead of the normal text, when the action is checked.
+     * This feature replaces the checkmark that usually appears in front of the text, in menus.
+     * It is useful when the text is mainly a verb: e.g. "Show <foo>"
+     * should turn into "Hide <foo>" when activated.
+     *
+     * If hasIcon(), the icon is kept for the 'checked state', unless
+     * @p checkedItem defines an icon explicitely. Same thing for tooltip and whatsthis.
+     * @since 3.3
+     */
+    void setCheckedState( const KGuiItem& checkedItem );
+
+    /// Reimplemented for internal reasons
+    virtual QString toolTip() const;
+
+public slots:
+    /**
+     *  Sets the state of the action.
+     */
+    virtual void setChecked( bool );
+
+protected slots:
+    virtual void slotActivated();
+
+protected:
+    virtual void updateChecked( int id );
+
+signals:
+    void toggled( bool );
+
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KToggleActionPrivate;
+    KToggleActionPrivate *d;
+};
+
+/**
+ *  @short Radiobox like action.
+ *
+ * An action that operates like a radio button. At any given time
+ * only a single action from the group will be active.
+ */
+class KDEUI_EXPORT KRadioAction : public KToggleAction
+{
+  Q_OBJECT
+public:
+    /**
+     * Constructs a radio action with text and potential keyboard
+     * accelerator but nothing else. Use this only if you really
+     * know what you are doing.
+     *
+     * @param text The text that will be displayed.
+     * @param cut The corresponding keyboard accelerator (shortcut).
+     * @param parent This action's parent.
+     * @param name An internal name for this action.
+     */
+    KRadioAction( const QString& text, const KShortcut& cut = KShortcut(), QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KRadioAction( const QString& text, const KShortcut& cut,
+                  const QObject* receiver, const char* slot, QObject* parent, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The icons that go with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KRadioAction( const QString& text, const QIconSet& pix, const KShortcut& cut = KShortcut(),
+                  QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The dynamically loaded icon that goes with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KRadioAction( const QString& text, const QString& pix, const KShortcut& cut = KShortcut(),
+                  QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The icons that go with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KRadioAction( const QString& text, const QIconSet& pix, const KShortcut& cut,
+                  const QObject* receiver, const char* slot, QObject* parent, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The dynamically loaded icon that goes with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KRadioAction( const QString& text, const QString& pix, const KShortcut& cut,
+                  const QObject* receiver, const char* slot,
+                  QObject* parent, const char* name = 0 );
+
+    /**
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KRadioAction( QObject* parent = 0, const char* name = 0 );
+
+protected:
+    virtual void slotActivated();
+
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KRadioActionPrivate;
+    KRadioActionPrivate *d;
+};
+
+/**
+ *  @short Action for selecting one of several items
+ *
+ *  Action for selecting one of several items.
+ *
+ *  This action shows up a submenu with a list of items.
+ *  One of them can be checked. If the user clicks on an item
+ *  this item will automatically be checked,
+ *  the formerly checked item becomes unchecked.
+ *  There can be only one item checked at a time.
+ */
+class KDEUI_EXPORT KSelectAction : public KAction
+{
+    Q_OBJECT
+    Q_PROPERTY( int currentItem READ currentItem WRITE setCurrentItem )
+    Q_PROPERTY( QStringList items READ items WRITE setItems )
+    Q_PROPERTY( bool editable READ isEditable WRITE setEditable )
+    Q_PROPERTY( int comboWidth READ comboWidth WRITE setComboWidth )
+    Q_PROPERTY( QString currentText READ currentText )
+    Q_PROPERTY( bool menuAccelsEnabled READ menuAccelsEnabled WRITE setMenuAccelsEnabled )
+public:
+
+    /**
+     * Constructs a select action with text and potential keyboard
+     * accelerator but nothing else. Use this only if you really
+     * know what you are doing.
+     *
+     * @param text The text that will be displayed.
+     * @param cut The corresponding keyboard accelerator (shortcut).
+     * @param parent This action's parent.
+     * @param name An internal name for this action.
+     */
+    KSelectAction( const QString& text, const KShortcut& cut = KShortcut(), QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KSelectAction( const QString& text, const KShortcut& cut,
+                   const QObject* receiver, const char* slot, QObject* parent, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The icons that go with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KSelectAction( const QString& text, const QIconSet& pix, const KShortcut& cut = KShortcut(),
+             QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The dynamically loaded icon that goes with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KSelectAction( const QString& text, const QString& pix, const KShortcut& cut = KShortcut(),
+                   QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The icons that go with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KSelectAction( const QString& text, const QIconSet& pix, const KShortcut& cut,
+                   const QObject* receiver, const char* slot, QObject* parent, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The dynamically loaded icon that goes with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KSelectAction( const QString& text, const QString& pix, const KShortcut& cut,
+                   const QObject* receiver, const char* slot,
+                   QObject* parent, const char* name = 0 );
+
+    /**
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KSelectAction( QObject* parent = 0, const char* name = 0 );
+
+    /**
+     * Destructor
+     */
+    virtual ~KSelectAction();
+
+    /**
+     *  "Plug" or insert this action into a given widget.
+     *
+     *  This will typically be a menu or a toolbar.
+     *  From this point on, you will never need to directly
+     *  manipulate the item in the menu or toolbar.
+     *  You do all enabling/disabling/manipulation directly with your KSelectAction object.
+     *
+     *  @param widget The GUI element to display this action.
+     *  @param index  The index of the item.
+     */
+    virtual int plug( QWidget* widget, int index = -1 );
+
+    /**
+     * When this action is plugged into a toolbar, it creates a combobox.
+     * @return true if the combo editable.
+     */
+    virtual bool isEditable() const;
+
+    /**
+     * @return the items that can be selected with this action.
+     * Use setItems to set them.
+     */
+    virtual QStringList items() const;
+
+    /**
+     * Changes the text of item @param index to @param text .
+     */
+    virtual void changeItem( int index, const QString& text );
+
+    /**
+     * Returns the text of the currently selected item.
+     */
+    virtual QString currentText() const;
+
+    /**
+     * Returns the index of the current item.
+     * @see setCurrentItem
+     */
+    virtual int currentItem() const;
+
+    /**
+     * When this action is plugged into a toolbar, it creates a combobox.
+     * This returns the maximum width set by setComboWidth
+     */
+    virtual int comboWidth() const;
+
+    /**
+     * Sets the maximum items that are visible at once if the action
+     * is a combobox, that is the number of items in the combobox's viewport
+     * Only works before the action is plugged
+     * @since 3.5
+     */
+    void setMaxComboViewCount( int n );
+
+    /**
+     * Returns a pointer to the popup menu used by this action.
+     */
+    QPopupMenu* popupMenu() const;
+
+    /**
+     * @deprecated See setMenuAccelsEnabled .
+     * @since 3.1
+     */
+    void setRemoveAmpersandsInCombo( bool b ) KDE_DEPRECATED;
+    /// @since 3.1
+    bool removeAmpersandsInCombo() const;
+
+    /**
+     * Sets whether any occurrence of the ampersand character ( &amp; ) in items
+     * should be interpreted as keyboard accelerator for items displayed in a
+     * menu or not.
+     * @since 3.1
+     */
+    void setMenuAccelsEnabled( bool b );
+    /// @since 3.1
+    bool menuAccelsEnabled() const;
+
+    virtual bool isShortcutConfigurable() const { return false; }
+
+public slots:
+    /**
+     *  Sets the currently checked item.
+     *
+     *  @param index Index of the item (remember the first item is zero).
+     */
+    virtual void setCurrentItem( int index );
+
+    /**
+     * Sets the items to be displayed in this action
+     * You need to call this.
+     */
+    virtual void setItems( const QStringList &lst );
+
+    /**
+     * Clears up all the items in this action
+     */
+    virtual void clear();
+
+    /**
+     * When this action is plugged into a toolbar, it creates a combobox.
+     * This makes the combo editable or read-only.
+     */
+    virtual void setEditable( bool );
+
+    /**
+     * When this action is plugged into a toolbar, it creates a combobox.
+     * This gives a _maximum_ size to the combobox.
+     * The minimum size is automatically given by the contents (the items).
+     */
+    virtual void setComboWidth( int width );
+
+protected:
+    virtual void changeItem( int id, int index, const QString& text );
+
+    /**
+     * Depending on the menuAccelsEnabled property this method will return the
+     * actions items in a way for inclusion in a combobox with the ampersand
+     * character removed from all items or not.
+     * @since 3.1
+     */
+    QStringList comboItems() const;
+
+protected slots:
+    virtual void slotActivated( int id );
+    virtual void slotActivated( const QString &text );
+    virtual void slotActivated();
+
+signals:
+    /**
+     * This signal is emitted when an item is selected; @param index indicated
+     * the item selected.
+     */
+    void activated( int index );
+    /**
+     * This signal is emitted when an item is selected; @param text indicates
+     * the item selected.
+     */
+    void activated( const QString& text );
+
+protected:
+    virtual void updateCurrentItem( int id );
+
+    virtual void updateComboWidth( int id );
+
+    virtual void updateItems( int id );
+
+    virtual void updateClear( int id );
+
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    void setupMenu() const;
+    class KSelectActionPrivate;
+    KSelectActionPrivate *d;
+
+};
+
+/// Remove this class in KDE-4.0. It doesn't add _anything_ to KSelectAction
+/**
+ * @deprecated Use KSelectAction instead.
+ */
+class KDEUI_EXPORT_DEPRECATED KListAction : public KSelectAction
+{
+    Q_OBJECT
+public:
+    /**
+     * Constructs a list action with text and potential keyboard
+     * accelerator but nothing else. Use this only if you really
+     * know what you are doing.
+     *
+     * @param text The text that will be displayed.
+     * @param cut The corresponding keyboard accelerator (shortcut).
+     * @param parent This action's parent.
+     * @param name An internal name for this action.
+     */
+    KListAction( const QString& text, const KShortcut& cut = KShortcut(), QObject* parent = 0,
+                  const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KListAction( const QString& text, const KShortcut& cut, const QObject* receiver,
+                  const char* slot, QObject* parent, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The icons that go with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KListAction( const QString& text, const QIconSet& pix, const KShortcut& cut = KShortcut(),
+                      QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The dynamically loaded icon that goes with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KListAction( const QString& text, const QString& pix, const KShortcut& cut = KShortcut(),
+                      QObject* parent = 0, const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The icons that go with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KListAction( const QString& text, const QIconSet& pix, const KShortcut& cut,
+                          const QObject* receiver, const char* slot, QObject* parent,
+                  const char* name = 0 );
+
+    /**
+     *  @param text The text that will be displayed.
+     *  @param pix The dynamically loaded icon that goes with this action.
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KListAction( const QString& text, const QString& pix, const KShortcut& cut,
+                 const QObject* receiver, const char* slot, QObject* parent,
+                 const char* name = 0 );
+
+    /**
+     *  @param parent This action's parent.
+     *  @param name An internal name for this action.
+     */
+    KListAction( QObject* parent = 0, const char* name = 0 );
+
+    /**
+     * Destructor
+     */
+    virtual ~KListAction();
+
+
+    virtual QString currentText() const;
+    virtual int currentItem() const;
+
+
+public slots:
+    /**
+     *  Sets the currently checked item.
+     *
+     *  @param index Index of the item (remember the first item is zero).
+     */
+    virtual void setCurrentItem( int index );
+
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KListActionPrivate;
+    KListActionPrivate *d;
+};
+
+/**
+ *  @short Recent files action
+ *
+ *  This class is an action to handle a recent files submenu.
+ *  The best way to create the action is to use KStdAction::openRecent.
+ *  Then you simply need to call loadEntries on startup, saveEntries
+ *  on shutdown, addURL when your application loads/saves a file.
+ *
+ *  @author Michael Koch
+ */
+class KDEUI_EXPORT KRecentFilesAction : public KListAction  // TODO public KSelectAction
+{
+  Q_OBJECT
+  Q_PROPERTY( uint maxItems READ maxItems WRITE setMaxItems )
+public:
+  /**
+   *  @param text The text that will be displayed.
+   *  @param cut The corresponding keyboard accelerator (shortcut).
+   *  @param parent This action's parent.
+   *  @param name An internal name for this action.
+   *  @param maxItems The maximum number of files to display
+   */
+  KRecentFilesAction( const QString& text, const KShortcut& cut,
+                      QObject* parent, const char* name = 0,
+                      uint maxItems = 10 );
+
+  /**
+   *  @param text The text that will be displayed.
+   *  @param cut The corresponding keyboard accelerator (shortcut).
+   *  @param receiver The SLOT's parent.
+   *  @param slot The SLOT to invoke when a URL is selected.
+   *  Its signature is of the form slotURLSelected( const KURL & ).
+   *  @param parent This action's parent.
+   *  @param name An internal name for this action.
+   *  @param maxItems The maximum number of files to display
+   */
+  KRecentFilesAction( const QString& text, const KShortcut& cut,
+                      const QObject* receiver, const char* slot,
+                      QObject* parent, const char* name = 0,
+                      uint maxItems = 10 );
+
+  /**
+   *  @param text The text that will be displayed.
+   *  @param pix The icons that go with this action.
+   *  @param cut The corresponding keyboard accelerator (shortcut).
+   *  @param parent This action's parent.
+   *  @param name An internal name for this action.
+   *  @param maxItems The maximum number of files to display
+   */
+  KRecentFilesAction( const QString& text, const QIconSet& pix, const KShortcut& cut,
+                      QObject* parent, const char* name = 0,
+                      uint maxItems = 10 );
+
+  /**
+   *  @param text The text that will be displayed.
+   *  @param pix The dynamically loaded icon that goes with this action.
+   *  @param cut The corresponding keyboard accelerator (shortcut).
+   *  @param parent This action's parent.
+   *  @param name An internal name for this action.
+   *  @param maxItems The maximum number of files to display
+   */
+  KRecentFilesAction( const QString& text, const QString& pix, const KShortcut& cut,
+                      QObject* parent, const char* name = 0,
+                      uint maxItems = 10 );
+
+  /**
+   *  @param text The text that will be displayed.
+   *  @param pix The icons that go with this action.
+   *  @param cut The corresponding keyboard accelerator (shortcut).
+   *  @param receiver The SLOT's parent.
+   *  @param slot The SLOT to invoke when a URL is selected.
+   *  Its signature is of the form slotURLSelected( const KURL & ).
+   *  @param parent This action's parent.
+   *  @param name An internal name for this action.
+   *  @param maxItems The maximum number of files to display
+   */
+  KRecentFilesAction( const QString& text, const QIconSet& pix, const KShortcut& cut,
+                      const QObject* receiver, const char* slot,
+                      QObject* parent, const char* name = 0,
+                      uint maxItems = 10 );
+
+  /**
+   *  @param text The text that will be displayed.
+   *  @param pix The dynamically loaded icon that goes with this action.
+   *  @param cut The corresponding keyboard accelerator (shortcut).
+   *  @param receiver The SLOT's parent.
+   *  @param slot The SLOT to invoke when a URL is selected.
+   *  Its signature is of the form slotURLSelected( const KURL & ).
+   *  @param parent This action's parent.
+   *  @param name An internal name for this action.
+   *  @param maxItems The maximum number of files to display
+   */
+  KRecentFilesAction( const QString& text, const QString& pix, const KShortcut& cut,
+                      const QObject* receiver, const char* slot,
+                      QObject* parent, const char* name = 0,
+                      uint maxItems = 10 );
+
+  /**
+   *  @param parent This action's parent.
+   *  @param name An internal name for this action.
+   *  @param maxItems The maximum number of files to display
+   */
+  KRecentFilesAction( QObject* parent = 0, const char* name = 0,
+                      uint maxItems = 10 );
+
+  /**
+   *  Destructor.
+   */
+  virtual ~KRecentFilesAction();
+
+  virtual int plug( QWidget *widget, int index = -1 );
+
+  /**
+   *  Returns the maximum of items in the recent files list.
+   */
+  uint maxItems() const;
+
+//KDE4: remove completeItems() and rename items() to urls(), to get the list of URLs added to
+//      the action.
+  /**
+    * @return the items that can be selected with this action.
+    * The returned items do not contain the pretty name that can be set by addURL,
+    * matching the pre-3.5 behavior.
+    */
+
+  virtual QStringList items() const;
+
+  /**
+    * @return the items that can be selected with this action.
+    * The returned items contain the pretty name that can be set by addURL.
+    * @since 3.5
+    */
+  QStringList completeItems() const;
+
+public slots:
+  /**
+   *  Sets the maximum of items in the recent files list.
+   *  The default for this value is 10 set in the constructor.
+   *
+   *  If this value is lesser than the number of items currently
+   *  in the recent files list the last items are deleted until
+   *  the number of items are equal to the new maximum.
+   */
+  void setMaxItems( uint maxItems );
+
+  /**
+   *  Loads the recent files entries from a given KConfig object.
+   *  You can provide the name of the group used to load the entries.
+   *  If the groupname is empty, entries are load from a group called 'RecentFiles'
+   *
+   *  This method does not effect the active group of KConfig.
+   */
+  void loadEntries( KConfig* config, QString groupname=QString::null );
+
+  /**
+   *  Saves the current recent files entries to a given KConfig object.
+   *  You can provide the name of the group used to load the entries.
+   *  If the groupname is empty, entries are saved to a group called 'RecentFiles'
+   *
+   *  This method does not effect the active group of KConfig.
+   */
+  void saveEntries( KConfig* config, QString groupname=QString::null );
+
+  /**
+   *  Add URL to recent files list.
+   *
+   *  @param url The URL of the file
+   */
+  void addURL( const KURL& url );
+
+  /**
+   *  Add URL to recent files list.
+   *
+   *  @param url The URL of the file
+   *  @param name The user visible pretty name that appears before the URL
+   *  @since 3.5
+   */
+  void addURL( const KURL& url, const QString& name ); //KDE4: Combine the above two methods
+
+  /**
+   *  Remove an URL from the recent files list.
+   *
+   *  @param url The URL of the file
+   */
+  void removeURL( const KURL& url );
+
+  /**
+   *  Removes all entries from the recent files list.
+   */
+  void clearURLList();
+
+signals:
+
+  /**
+   *  This signal gets emited when the user selects an URL.
+   *
+   *  @param url The URL thats the user selected.
+   */
+  void urlSelected( const KURL& url );
+
+protected slots:
+  void itemSelected( const QString& string );
+  void menuAboutToShow();
+  void menuItemActivated( int id );
+  void slotClicked();
+  virtual void slotActivated(int);
+  virtual void slotActivated(const QString& );
+  virtual void slotActivated();
+
+protected:
+  virtual void virtual_hook( int id, void* data );
+
+private:
+  void init();
+
+  class KRecentFilesActionPrivate;
+  KRecentFilesActionPrivate *d;
+};
+
+class KDEUI_EXPORT KFontAction : public KSelectAction
+{
+    Q_OBJECT
+    Q_PROPERTY( QString font READ font WRITE setFont )
+public:
+    KFontAction( const QString& text, const KShortcut& cut = KShortcut(), QObject* parent = 0,
+                 const char* name = 0 );
+    KFontAction( const QString& text, const KShortcut& cut,
+                 const QObject* receiver, const char* slot, QObject* parent,
+                 const char* name = 0 );
+    KFontAction( const QString& text, const QIconSet& pix, const KShortcut& cut = KShortcut(),
+                 QObject* parent = 0, const char* name = 0 );
+    KFontAction( const QString& text, const QString& pix, const KShortcut& cut = KShortcut(),
+                 QObject* parent = 0, const char* name = 0 );
+    KFontAction( const QString& text, const QIconSet& pix, const KShortcut& cut,
+                 const QObject* receiver, const char* slot, QObject* parent,
+                 const char* name = 0 );
+    KFontAction( const QString& text, const QString& pix, const KShortcut& cut,
+                 const QObject* receiver, const char* slot, QObject* parent,
+                 const char* name = 0 );
+
+// The ctors with fontListCriteria were added after 3.3-beta1.
+// This define is used in koffice. Remove when koffice has a dependency on kdelibs-3.3 or more.
+#define KFONTACTION_HAS_CRITERIA_ARG
+    KFontAction( uint fontListCriteria, const QString& text,
+                 const KShortcut& cut = KShortcut(), QObject* parent = 0,
+                 const char* name = 0 );
+    KFontAction( uint fontListCriteria, const QString& text, const QString& pix,
+                 const KShortcut& cut = KShortcut(),
+                 QObject* parent = 0, const char* name = 0 );
+
+    KFontAction( QObject* parent = 0, const char* name = 0 );
+    ~KFontAction();
+
+    QString font() const {
+        return currentText();
+    }
+
+    int plug( QWidget*widget, int index = -1 );
+
+public slots:
+    void setFont( const QString &family );
+
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KFontActionPrivate;
+    KFontActionPrivate *d;
+};
+
+class KDEUI_EXPORT KFontSizeAction : public KSelectAction
+{
+    Q_OBJECT
+    Q_PROPERTY( int fontSize READ fontSize WRITE setFontSize )
+public:
+    KFontSizeAction( const QString& text, const KShortcut& cut = KShortcut(), QObject* parent = 0,
+                     const char* name = 0 );
+    KFontSizeAction( const QString& text, const KShortcut& cut, const QObject* receiver,
+                     const char* slot, QObject* parent, const char* name = 0 );
+    KFontSizeAction( const QString& text, const QIconSet& pix, const KShortcut& cut = KShortcut(),
+                     QObject* parent = 0, const char* name = 0 );
+    KFontSizeAction( const QString& text, const QString& pix, const KShortcut& cut = KShortcut(),
+                     QObject* parent = 0, const char* name = 0 );
+    KFontSizeAction( const QString& text, const QIconSet& pix, const KShortcut& cut,
+                     const QObject* receiver, const char* slot,
+                     QObject* parent, const char* name = 0 );
+    KFontSizeAction( const QString& text, const QString& pix, const KShortcut& cut,
+                     const QObject* receiver, const char* slot,
+                     QObject* parent, const char* name = 0 );
+    KFontSizeAction( QObject* parent = 0, const char* name = 0 );
+
+    virtual ~KFontSizeAction();
+
+    virtual int fontSize() const;
+
+public slots:
+    virtual void setFontSize( int size );
+
+protected slots:
+    virtual void slotActivated( int );
+    virtual void slotActivated( const QString& );
+    virtual void slotActivated() { KAction::slotActivated(); }
+
+signals:
+    void fontSizeChanged( int );
+
+private:
+    void init();
+
+
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KFontSizeActionPrivate;
+    KFontSizeActionPrivate *d;
+};
+
+
+/**
+ * A KActionMenu is an action that holds a sub-menu of other actions.
+ * insert() and remove() allow to insert and remove actions into this action-menu.
+ * Plugged in a popupmenu, it will create a submenu.
+ * Plugged in a toolbar, it will create a button with a popup menu.
+ *
+ * This is the action used by the XMLGUI since it holds other actions.
+ * If you want a submenu for selecting one tool among many (without icons), see KSelectAction.
+ * See also setDelayed about the main action.
+ */
+class KDEUI_EXPORT KActionMenu : public KAction
+{
+  Q_OBJECT
+  Q_PROPERTY( bool delayed READ delayed WRITE setDelayed )
+  Q_PROPERTY( bool stickyMenu READ stickyMenu WRITE setStickyMenu )
+
+public:
+    KActionMenu( const QString& text, QObject* parent = 0,
+                 const char* name = 0 );
+    KActionMenu( const QString& text, const QIconSet& icon,
+                 QObject* parent = 0, const char* name = 0 );
+    KActionMenu( const QString& text, const QString& icon,
+                 QObject* parent = 0, const char* name = 0 );
+    KActionMenu( QObject* parent = 0, const char* name = 0 );
+    virtual ~KActionMenu();
+
+    virtual void insert( KAction*, int index = -1 );
+    virtual void remove( KAction* );
+
+    KPopupMenu* popupMenu() const;
+    void popup( const QPoint& global );
+
+    /**
+     * Returns true if this action creates a delayed popup menu
+     * when plugged in a KToolbar.
+     */
+    bool delayed() const;
+    /**
+     * If set to true, this action will create a delayed popup menu
+     * when plugged in a KToolbar. Otherwise it creates a normal popup.
+     * Default: delayed
+     *
+     * Remember that if the "main" action (the toolbar button itself)
+     * cannot be clicked, then you should call setDelayed(false).
+     *
+     * On the opposite, if the main action can be clicked, it can only happen
+     * in a toolbar: in a menu, the parent of a submenu can't be activated.
+     * To get a "normal" menu item when plugged a menu (and no submenu)
+     * use KToolBarPopupAction.
+     */
+    void setDelayed(bool _delayed);
+
+    /**
+     * Returns true if this action creates a sticky popup menu.
+     * See setStickyMenu().
+     */
+    bool stickyMenu() const;
+    /**
+     * If set to true, this action will create a sticky popup menu
+     * when plugged in a KToolbar.
+     * "Sticky", means it's visible until a selection is made or the mouse is
+     * clicked elsewhere. This feature allows you to make a selection without
+     * having to press and hold down the mouse while making a selection.
+     * Default: sticky.
+     */
+    void setStickyMenu(bool sticky);
+
+    virtual int plug( QWidget* widget, int index = -1 );
+
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KActionMenuPrivate;
+    KActionMenuPrivate *d;
+};
+
+/**
+ * This action is a normal action everywhere, except in a toolbar
+ * where it also has a popupmenu (optionnally delayed). This action is designed
+ * for history actions (back/forward, undo/redo) and for any other action
+ * that has more detail in a toolbar than in a menu (e.g. tool chooser
+ * with "Other" leading to a dialog...).
+ */
+class KDEUI_EXPORT KToolBarPopupAction : public KAction
+{
+  Q_OBJECT
+  Q_PROPERTY( bool delayed READ delayed WRITE setDelayed )
+  Q_PROPERTY( bool stickyMenu READ stickyMenu WRITE setStickyMenu )
+
+public:
+    //Not all constructors - because we need an icon, since this action only makes
+    // sense when being plugged at least in a toolbar.
+    /**
+     * Create a KToolBarPopupAction, with a text, an icon, an optional accelerator,
+     * parent and name.
+     *
+     * @param text The text that will be displayed.
+     * @param icon The icon to display.
+     * @param cut The corresponding keyboard accelerator (shortcut).
+     * @param parent This action's parent.
+     * @param name An internal name for this action.
+     */
+    KToolBarPopupAction( const QString& text, const QString& icon, const KShortcut& cut = KShortcut(),
+                         QObject* parent = 0, const char* name = 0 );
+
+    /**
+     * Create a KToolBarPopupAction, with a text, an icon, an accelerator,
+     * a slot connected to the action, parent and name.
+     *
+     * If you do not want or have a keyboard accelerator, set the
+     * @p cut param to 0.
+     *
+     * @param text The text that will be displayed.
+     * @param icon The icon to display.
+     * @param cut The corresponding keyboard accelerator (shortcut).
+     * @param receiver The SLOT's owner.
+     * @param slot The SLOT to invoke to execute this action.
+     * @param parent This action's parent.
+     * @param name An internal name for this action.
+     */
+    KToolBarPopupAction( const QString& text, const QString& icon, const KShortcut& cut,
+                         const QObject* receiver, const char* slot,
+                         QObject* parent = 0, const char* name = 0 );
+
+    /**
+     * Create a KToolBarPopupAction, with a KGuiItem, an accelerator,
+     * a slot connected to the action, parent and name. The text and the
+     * icon are taken from the KGuiItem.
+     *
+     * If you do not want or have a keyboard accelerator, set the
+     * @p cut param to 0.
+     *
+     * @param item The text and icon that will be displayed.
+     * @param cut The corresponding keyboard accelerator (shortcut).
+     * @param receiver The SLOT's owner.
+     * @param slot The SLOT to invoke to execute this action.
+     * @param parent This action's parent.
+     * @param name An internal name for this action.
+     */
+    KToolBarPopupAction( const KGuiItem& item, const KShortcut& cut,
+                         const QObject* receiver, const char* slot,
+                         KActionCollection* parent, const char* name );
+
+    virtual ~KToolBarPopupAction();
+
+    virtual int plug( QWidget *widget, int index = -1 );
+
+    /**
+     * The popup menu that is shown when clicking (some time) on the toolbar
+     * button. You may want to plug items into it on creation, or connect to
+     * aboutToShow for a more dynamic menu.
+     */
+    KPopupMenu *popupMenu() const;
+
+    /**
+     * Returns true if this action creates a delayed popup menu
+     * when plugged in a KToolbar.
+     */
+    bool delayed() const;
+    /**
+     * If set to true, this action will create a delayed popup menu
+     * when plugged in a KToolbar. Otherwise it creates a normal popup.
+     * Default: delayed.
+     */
+    void setDelayed(bool delayed);
+    /**
+     * Returns true if this action creates a sticky popup menu.
+     * See setStickyMenu().
+     */
+    bool stickyMenu() const;
+    /**
+     * If set to true, this action will create a sticky popup menu
+     * when plugged in a KToolbar.
+     * "Sticky", means it's visible until a selection is made or the mouse is
+     * clicked elsewhere. This feature allows you to make a selection without
+     * having to press and hold down the mouse while making a selection.
+     * Only available if delayed() is true.
+     * Default: sticky.
+     */
+    void setStickyMenu(bool sticky);
+
+private:
+    KPopupMenu *m_popup;
+    bool m_delayed:1;
+    bool m_stickyMenu:1;
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KToolBarPopupActionPrivate;
+    KToolBarPopupActionPrivate *d;
+};
+
+/**
+ * An action that takes care of everything associated with
+ * showing or hiding a toolbar by a menu action. It will
+ * show or hide the toolbar with the given name when
+ * activated, and check or uncheck itself if the toolbar
+ * is manually shown or hidden.
+ *
+ * If you need to perfom some additional action when the
+ * toolbar is shown or hidden, connect to the toggled(bool)
+ * signal. It will be emitted after the toolbar's
+ * visibility has changed, whenever it changes.
+ * @since 3.1
+ */
+class KDEUI_EXPORT KToggleToolBarAction : public KToggleAction
+{
+    Q_OBJECT
+public:
+    /**
+     * Create a KToggleToolbarAction that manages the toolbar
+     * named toolBarName. This can be either the name of a
+     * toolbar in an xml ui file, or a toolbar programmatically
+     * created with that name.
+     */
+    KToggleToolBarAction( const char* toolBarName, const QString& text,
+                          KActionCollection* parent, const char* name );
+    KToggleToolBarAction( KToolBar *toolBar, const QString &text,
+                          KActionCollection *parent, const char *name );
+    virtual ~KToggleToolBarAction();
+
+    virtual int plug( QWidget * widget, int index = -1 );
+
+    KToolBar *toolBar() { return m_toolBar; }
+
+public slots:
+    virtual void setChecked( bool );
+
+private:
+    QCString               m_toolBarName;
+    QGuardedPtr<KToolBar>  m_toolBar;
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KToggleToolBarActionPrivate;
+    KToggleToolBarActionPrivate *d;
+};
+
+/**
+ * An action for switching between to/from full screen mode. Note that
+ * QWidget::isFullScreen() may reflect the new or the old state
+ * depending on how the action was triggered (by the application or
+ * from the window manager). Also don't try to track the window state
+ * yourself. Rely on this action's state (isChecked()) instead.
+ *
+ * Important: If you need to set/change the fullscreen state manually,
+ * use the relevant QWidget function (showFullScreen etc.), do not
+ * call directly the slot connected to the toggled() signal. The slot
+ * still needs to explicitly set the window state though.
+ * @since 3.2
+ */
+class KDEUI_EXPORT KToggleFullScreenAction : public KToggleAction
+{
+    Q_OBJECT
+public:
+    /**
+     * Create a KToggleFullScreenAction
+     *  @param cut The corresponding keyboard accelerator (shortcut).
+     *  @param receiver The SLOT's parent.
+     *  @param slot The SLOT to invoke to execute this action.
+     *  @param parent This action's parent.
+     *  @param window the window that will switch to/from full screen mode
+     *  @param name An internal name for this action.
+     */
+    KToggleFullScreenAction( const KShortcut &cut,
+                             const QObject* receiver, const char* slot,
+                             QObject* parent, QWidget* window,
+                             const char* name );
+    virtual ~KToggleFullScreenAction();
+
+    /**
+     * Sets the window that will be related to this action.
+     */
+    void setWindow( QWidget* window );
+public slots:
+    virtual void setChecked( bool );
+protected:
+    /**
+     * @internal
+     */
+    virtual bool eventFilter( QObject* o, QEvent* e );
+private:
+    QWidget* window;
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KToggleFullScreenActionPrivate;
+    KToggleFullScreenActionPrivate *d;
+};
+
+
+/**
+ * An action that automatically embeds a widget into a
+ * toolbar.
+ */
+class KDEUI_EXPORT KWidgetAction : public KAction
+{
+    Q_OBJECT
+public:
+    /**
+     * Create an action that will embed widget into a toolbar
+     * when plugged. This action may only be plugged into
+     * a toolbar.
+     */
+    KWidgetAction( QWidget* widget, const QString& text,
+                   const KShortcut& cut,
+                   const QObject* receiver, const char* slot,
+                   KActionCollection* parent, const char* name );
+    virtual ~KWidgetAction();
+
+    /**
+     * Returns the widget associated with this action.
+     */
+    QWidget* widget() { return m_widget; }
+
+    void setAutoSized( bool );
+
+    /**
+     * Plug the action. The widget passed to the constructor
+     * will be reparented to w, which must inherit KToolBar.
+     */
+    virtual int plug( QWidget* widget, int index = -1 );
+    /**
+     * Unplug the action. Ensures that the action is not
+     * destroyed. It will be hidden and reparented to 0L instead.
+     */
+    virtual void unplug( QWidget *w );
+protected slots:
+    void slotToolbarDestroyed();
+private:
+    QGuardedPtr<QWidget> m_widget;
+    bool                 m_autoSized;
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KWidgetActionPrivate;
+    KWidgetActionPrivate *d;
+};
+
+class KDEUI_EXPORT KActionSeparator : public KAction
+{
+    Q_OBJECT
+public:
+    KActionSeparator( QObject* parent = 0, const char* name = 0 );
+    virtual ~KActionSeparator();
+
+    virtual int plug( QWidget *widget, int index = -1 );
+
+protected:
+    virtual void virtual_hook( int id, void* data );
+private:
+    class KActionSeparatorPrivate;
+    KActionSeparatorPrivate *d;
+};
+
+/**
+ * An action for pasting text from the clipboard.
+ * It's useful for text handling applications as
+ * when plugged into a toolbar it provides a menu
+ * with the clipboard history if klipper is running.
+ * If klipper is not running, the menu has only one
+ * item: the current clipboard content.
+ *
+ * @since 3.2
+ */
+class KDEUI_EXPORT KPasteTextAction: public KAction
+{
+    Q_OBJECT
+public:
+    /**
+     * Create a KPasteTextAction, with a text, an icon, an accelerator,
+     * a slot connected to the action, parent and name.
+     *
+     * If you do not want or have a keyboard accelerator, set the
+     * @p cut param to 0.
+     *
+     * @param text The text that will be displayed.
+     * @param icon The icon to display.
+     * @param cut The corresponding keyboard accelerator (shortcut).
+     * @param receiver The SLOT's owner.
+     * @param slot The SLOT to invoke to execute this action.
+     * @param parent This action's parent.
+     * @param name An internal name for this action.
+     */
+    KPasteTextAction( const QString& text, const QString& icon, const KShortcut& cut,
+                  const QObject* receiver, const char* slot,
+                  QObject* parent = 0, const char* name = 0 );
+
+    virtual ~KPasteTextAction();
+
+    /**
+    * Controls the behavior of the clipboard history menu popup.
+    *
+    * @param mode If false and the clipboard contains a non-text object
+    *             the popup menu with the clipboard history will appear
+    *             immediately as the user clicks the toolbar action; if
+    *             true, the action works like the standard paste action
+    *             even if the current clipboard object is not text.
+    *             Default value is true.
+    */
+    void setMixedMode(bool mode);
+
+    virtual int plug( QWidget *widget, int index = -1 );
+
+protected slots:
+    void menuAboutToShow();
+    void menuItemActivated( int id);
+    virtual void slotActivated();
+
+protected:
+    virtual void virtual_hook( int id, void* data );
+
+private:
+    KPopupMenu *m_popup;
+    bool m_mixedMode;
+    class KPasteTextActionPrivate;
+    KPasteTextActionPrivate *d;
+};
+
+#endif