diff options
Diffstat (limited to 'kdeui/kactionclasses.h')
| -rw-r--r-- | kdeui/kactionclasses.h | 1422 |
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 <reggie@kde.org> + (C) 1999 Simon Hausmann <hausmann@kde.org> + (C) 2000 Nicolas Hadacek <haadcek@kde.org> + (C) 2000 Kurt Granroth <granroth@kde.org> + (C) 2000 Michael Koch <koch@kde.org> + (C) 2001 Holger Freyther <freyther@kde.org> + (C) 2002 Ellis Whitehead <ellis@kde.org> + (C) 2003 Andras Mantia <amantia@kde.org> + + 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 ( & ) 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 |