home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kglobalaccel.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-10-01  |  7.7 KB  |  240 lines
  1. /* This file is part of the KDE libraries
  2.     Copyright (C) 2001,2002 Ellis Whitehead <ellis@kde.org>
  3.  
  4.     This library is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU Library General Public
  6.     License as published by the Free Software Foundation; either
  7.     version 2 of the License, or (at your option) any later version.
  8.  
  9.     This library is distributed in the hope that it will be useful,
  10.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.     Library General Public License for more details.
  13.  
  14.     You should have received a copy of the GNU Library General Public License
  15.     along with this library; see the file COPYING.LIB.  If not, write to
  16.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.     Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef _KGLOBALACCEL_H_
  21. #define _KGLOBALACCEL_H_
  22.  
  23. #include <qobject.h>
  24. #include <kshortcut.h>
  25.  
  26. class QPopupMenu;
  27. class QWidget;
  28. class KAccelAction;
  29. class KAccelActions;
  30. class KConfigBase;
  31.  
  32. class KGlobalAccelPrivate;
  33.  
  34. /**
  35. * KGlobalAccel allows you to have global accelerators that are independent of
  36. * the focused window. Unlike KAccel it does not matter which window is 
  37. * currently active.
  38. *
  39. * @see KAccel
  40. * @see KAccelShortcutList
  41. * @see KKeyChooser
  42. * @see KKeyDialog
  43. * @short Configurable global shortcut support
  44. */
  45. class KDECORE_EXPORT KGlobalAccel : public QObject
  46. {
  47.     Q_OBJECT
  48.  public:
  49.     /**
  50.      * Creates a new KGlobalAccel object with the given pParent and
  51.      * psName.
  52.      * @param pParent the parent of the QObject
  53.      * @param psName the name of the QObject
  54.      */
  55.     KGlobalAccel( QObject* pParent, const char* psName = 0 );
  56.     virtual ~KGlobalAccel();
  57.  
  58.     /**
  59.      * Checks whether the accelerators are enabled.
  60.      * @return true if the KGlobalAccel is enabled
  61.      */
  62.     bool isEnabled();
  63.     
  64.     /**
  65.      * Enables or disables the KGlobalAccel
  66.      * @param bEnabled true if the KGlobalAccel should be enabled, false if it
  67.      *  should be disabled.
  68.      */
  69.     void setEnabled( bool bEnabled );
  70.  
  71.     /**
  72.      * Create an accelerator action.
  73.      *
  74.      * Usage:
  75.      *\code
  76.      * insert( "Do Something", i18n("Do Something"),
  77.      *   i18n("This action allows you to do something really great with this program to "
  78.      *        "the currently open document."),
  79.      *   ALT+CTRL+Key_Q, KKey::QtWIN+CTRL+Key_Q, this, SLOT(slotDoSomething()) );
  80.      *\endcode
  81.      *
  82.      * @param sAction The internal name of the action.
  83.      * @param sLabel An i18n'ized short description of the action displayed when
  84.      *  using KKeyChooser to reconfigure the shortcuts.
  85.      * @param sWhatsThis An extended description of the action.
  86.      * @param cutDef3 The default 3 modifier scheme shortcut.
  87.      * @param cutDef4 The default 4 modifier scheme shortcut.
  88.      * @param pObjSlot Pointer to the slot object.
  89.      * @param psMethodSlot Pointer to the slot method.
  90.      * @param bConfigurable Allow the user to change this shortcut if set to 'true'.
  91.      * @param bEnabled The action will be activated by the shortcut if set to 'true'.
  92.      */
  93.     KAccelAction* insert( const QString& sAction, const QString& sLabel, const QString& sWhatsThis,
  94.                      const KShortcut& cutDef3, const KShortcut& cutDef4,
  95.                      const QObject* pObjSlot, const char* psMethodSlot,
  96.                      bool bConfigurable = true, bool bEnabled = true );
  97.  
  98.     /**
  99.      * Removes the accelerator action identified by the name.
  100.      * Remember to also call updateConnections().
  101.      * @param sAction the name of the action to remove
  102.      * @since 3.1
  103.      */
  104.     bool remove( const QString& sAction );
  105.  
  106.     /**
  107.      * Use this to insert a label into the action list.  This will be
  108.      * displayed when the user configures shortcuts.
  109.      * @param sName of the of the action to insert
  110.      * @param sLabel a user-readable (i18n!) name for the action
  111.      * @return the KAccelAction of the action
  112.      */
  113.     KAccelAction* insert( const QString& sName, const QString& sLabel );
  114.  
  115.     /**
  116.      * Updates the connections of the accelerations after changing them. 
  117.      * @return true if successful, false otherwise
  118.      */
  119.     bool updateConnections();
  120.  
  121.     /**
  122.      * Return the shortcut associated with the action named by @p sAction.
  123.      * @param sAction the name of the action
  124.      * @return the shortcut. If the action does not exist a null shortcut will be returned.
  125.      */
  126.     const KShortcut& shortcut( const QString& sAction ) const;
  127.     /**
  128.      * Set the shortcut to be associated with the action named by @p sAction.
  129.      * @param sAction the name of the action
  130.      * @param shortcut the shortcut for the action
  131.      * @return true if successful, false otherwise
  132.      */
  133.     bool setShortcut( const QString& sAction, const KShortcut &shortcut );
  134.     /**
  135.      * Set the slot to be called when the shortcut of the action named
  136.      * by @p sAction is pressed.
  137.      * @param sAction the name of the action
  138.      * @param pObjSlot the receiver of the signal
  139.      * @param psMethodSlot the slot to receive the signal
  140.      * @return true if successful, false otherwise
  141.      */
  142.     bool setSlot( const QString& sAction, const QObject* pObjSlot, const char* psMethodSlot );
  143.  
  144.         /**
  145.          * Enables or disables action @p sAction.
  146.          * @since 3.4
  147.          */ 
  148.     bool setActionEnabled( const QString& sAction, bool bEnable );
  149.     /**
  150.      * Return the label (i18n'ized short description) associated with the action named by @p sAction.
  151.      * @param sAction the name of the action
  152.      * @return the label
  153.      * @since 3.3
  154.      */
  155.     QString label( const QString& sAction ) const;
  156.  
  157.     /**
  158.      * Returns the configuration group that is used to save the accelerators.
  159.      * @return the configuration group
  160.      * @see KConfig
  161.      */
  162.     const QString& configGroup() const;
  163.  
  164.     /**
  165.      * Sets the configuration group that is used to save the accelerators.
  166.      * @param cg the configuration group
  167.      * @see KConfig
  168.      */
  169.     void setConfigGroup( const QString &cg );
  170.  
  171.     /**
  172.      * Read all shortcuts from @p pConfig, or (if @p pConfig
  173.      * is zero) from the application's configuration file
  174.      * KGlobal::config().
  175.      * @param pConfig the configuration file to read from, or 0 for the application
  176.      *                 configuration file
  177.      * @return true if successful, false otherwise
  178.      */
  179.     bool readSettings( KConfigBase* pConfig = 0 );
  180.  
  181.     /**
  182.      * Write the current shortcuts to @p pConfig,
  183.      * or (if @p pConfig is zero) to the application's
  184.      * configuration file.
  185.      * @param pConfig the configuration file to read from, or 0 for the application
  186.      *                 configuration file
  187.      * @return true if successful, false otherwise
  188.      * @since 3.1
  189.      */
  190.     bool writeSettings( KConfigBase* pConfig = 0 ) const;
  191.     // BCI: merge these two writeSettings methods in KDE 4.0
  192.     /**
  193.      * Write the current shortcuts to @p pConfig,
  194.      * or (if @p pConfig is zero) to the application's
  195.      * configuration file.  Alternatively, if bGlobal is true, then write
  196.      * to kdeglobals.
  197.      * @param pConfig the configuration file to read from, or 0 for the application
  198.      *                 configuration file
  199.      * @param bGlobal if true write the configuration to the kde global settings
  200.      * @return true if successful, false otherwise
  201.      */
  202.     bool writeSettings( KConfigBase* pConfig, bool bGlobal ) const;
  203.  
  204.     /**
  205.      * @internal -- this a wrapper function to
  206.      * KAccelActions::useFourModifierKeys().
  207.      */
  208.     static bool useFourModifierKeys();
  209.         
  210.         /**
  211.          * @internal
  212.          */
  213.         static void blockShortcuts( bool block );
  214.         /**
  215.          * @internal
  216.          */
  217.         void disableBlocking( bool disable );
  218.         
  219.         /**
  220.          * @internal
  221.          */
  222.         // like setEnabled(), but doesn't ungrab (see in KGlobalAccelPrivate)
  223.         void suspend( bool s );
  224.  
  225. private:
  226.  
  227.     KAccelActions& actions();
  228.     const KAccelActions& actions() const;
  229.  
  230.     friend class KGlobalAccelPrivate;
  231.     friend class KAccelShortcutList;
  232. protected:
  233.     /** \internal */
  234.     virtual void virtual_hook( int id, void* data );
  235. private:
  236.     class KGlobalAccelPrivate* d;
  237. };
  238.  
  239. #endif // _KGLOBALACCEL_H_
  240.