kglobalaccel.h

一种效率高

/* This file is part of the KDE libraries
   Copyright (C) 1997 Mark Donohoe <[e-mail]>
   Copyright (C) 1997 Nicolas Hadacek <[e-mail]>
   Copyright (C) 1998 Matthias Ettrich <[e-mail]>

	This library is free software; you can redistribute it and/or
	modify it under the terms of the GNU Library General Public
	License as published by the Free Software Foundation; either
	version 2 of the License, or (at your option) any later version.

	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., 59 Temple Place - Suite 330,
	Boston, MA 02111-1307, USA.
*/

#ifndef _KGLOBALACCEL_H_
#define _KGLOBALACCEL_H_

#include <kapp.h>
#include <qobject.h>
#include "kaccel.h"

/**
 * Returns the X key modifier for the key code keyCode.
 */	
uint keyToXMod( uint keyCode );

/**
 * Returns the X key sym for the key code keyCode.
 */	
uint keyToXSym( uint keyCode );

/**
 * The KGlobalAccel class handles global keyboard accelerators, allowing a
 * user to configure key bindings through application configuration files or
 * through the KKeyChooser GUI.
 *
 * A KGlobalAccel contains a list of accelerator items. Each accelerator item
 * consists of an action name and a keyboard code combined with modifiers
 * (SHIFT, CTRL and ALT.)
 *
 * For example, "CTRL+SHIFT+M" could be a shortcut for popping-up a menu of
 * monitor setting choices anywhere on the desktop. The key codes are listed
 * in ckey.h. "Monitor settings" could be the action name for this
 * accelerator. The action name indentifies the key binding in configuration
 * files and the KKeyChooser GUI.
 *
 * When pressed,an accelerator key calls the slot to which it has been
 * connected. Accelerator items can be connected so that a key will activate
 * two different slots.
 *
 * KApplication::x11EventFilter must be re-implemented to call
 * KAccel::x11EventFilter so that a KAccel object can handle all key events.
 *
 * Key binding configuration during run time can be prevented by specifying
 * that an accelerator item is not configurable when it is inserted.
 *
 * It is possible for a user to choose to have no key associated with an action.
 *
 *
 * The translated first argument for insertItem is only used in the
 * configuration dialog.
 *
 * MyApp::x11EventFilter( XEvent *ev ) {
 * if ( myObject->ga->x11EventFilter( ev ) )
 *		return true;
 * }
 *
 * ...
 *
 * ga = new KGlobalAccel();
 * ga->insertItem( i18n("Monitor settings"), "Monitor settings", "CTRL+SHIFT+M" );
 * ga->connectItem( "Monitor settings", myObject, SLOT( popupMenu() ) );
 *
 * ga->readSettings();
 *
 */
class KGlobalAccel : public QObject
{
	Q_OBJECT
	
 public:
	/**
	 * Creates a KGlobalAccel object.
	 */
	KGlobalAccel( bool _do_not_grab = false);
			
	/**
	   Creates a KGlobalAccel object with a parent and a name. The
	   parent has the only effect that the KGlobalAccel object
	   will be automatically destroyed in the parent's destructor,
	   thus releaseing the keys.
	*/
	KGlobalAccel(QWidget * parent, const char * name = 0, bool _do_not_grab = false);

    
	/**
	 * Destroys the accelerator object.and ungrabs any allocated key bindings.
	 */
	~KGlobalAccel();
	
	/**
	 * Removes all accelerator items.
	 */
	void clear();
	
	/**
	 * Connect an accelerator item to a slot/signal in another object.
	 *
	 * Arguments:
	 *
	 *  @param action is the accelerator item action name.
	 *  @param receiver is the object to receive a signal
	 *  @param member is a slot or signal in the receiver
	 *  @param activate indicates whether the accelrator item should be
	 *  enabled immediately
	 */
	void connectItem( const char * action,
						  const QObject* receiver, const char* member,
						  bool activate = TRUE );
						
	/**
	* Returns the number of accelerator items.
	*/					
	uint count() const;
	
	/**
	* Returns the key code of the accelerator item with the action name
	* action, or zero if either the action name cannot be found or the current
	* key is set to no key.
	*/
	uint currentKey( const char * action );

	/**
	* Returns the default key code of the accelerator item with the action name
	* action, or zero if the action name cannot be found.
	*/
	uint defaultKey( const char * action);
	
	/**
	 * Disconnects an accelerator item from a function in another object.
	 */
	void disconnectItem( const char * action,
							const QObject* receiver, const char* member );
	
	/**
	 * Returns that identifier of the accelerator item with the keycode key,
	 * or zero if the item cannot be found.
	 */
	const char *findKey( int key ) const;
	
	/**
	 * Attempts to make a passive X server grab of the key specified by key symbol
	 * keysym and modifier mod. Returns false if unsuccessful.
	 *
	 * Modifications with num lock and caps lock are also grabbed.
	 *
	 */
	bool grabKey(uint keysym, uint mod);
	
	/**
	 * Inserts an accelerator item and returns false if the key code
	 * 	defaultKeyCode is not valid.
	 *	
	 * Arguments:
	 *
	 *  @param action is the accelerator item action name.
	 *  @param defaultKeyCode is a key code to be used as the default for the action.
	 *  @param configurable indicates whether a user can configure the key
	 *	binding using the KKeyChooser GUI and whether the key will be written
	 *	back to configuration files on calling writeSettings.
	 *
	 * If an action already exists the old association and connections will be
	 * removed..
	 * 	
	 */
	bool insertItem( const char* descr, const char * action, uint defaultKeyCode,
				 bool configurable = TRUE );
	
	 /**
	 * Inserts an accelerator item and returns false if the key code
	 * 	defaultKeyCode is not valid.
	 *	
	 * Arguments:
	 *
	 *  @param action is the accelerator item action name.
	 *  @param defaultKeyCode is a key plus a combination of SHIFT, CTRL
	 *	and ALT to be used as the default for the action.
	 *  @param configurable indicates whether a user can configure
	 *  the key
	 *	binding using the KKeyChooser GUI and whether the key
	 *	will be written back to configuration files on calling
	 *	writeSettings.
	 *
	 * If an action already exists the old association and connections
	 * will be removed..

	 */
	bool insertItem( const char* descr, const char * action, const char * defaultKeyCode,
				 bool configurable = TRUE );
	
	bool isEnabled();
	bool isItemEnabled( const char *action );
	
	/**
	* Returns the dictionary of accelerator action names and KKeyEntry
	* objects. Note that only a shallow copy is returned so that
	* items will be lost when the KKeyEntry objects are deleted.
	*/	
	QDict<KKeyEntry> keyDict();
				
	/**
	 * Reads all key associations from the application's configuration
	 * files.
	 */
	void readSettings();
		
 	/**
	 * Removes the accelerator item with the action name action.
	 */
    void removeItem( const char * action );
	
	void setConfigGroup( const char *group );
	
	const char * configGroup();
	
	/**
	 * Enables the accelerator if activate is TRUE, or disables it if
	 * activate is FALSE..
	 *
	 * Individual keys can also be enabled or disabled.
	 */
	void setEnabled( bool activate );
	
	/**
	 * Enables or disables an accelerator item.
	 *
	 * Arguments:
	 *
	 *  @param action is the accelerator item action name.
	 *	@param activate specifies whether the item should be enabled or
	 *	disabled.
	 */
	void setItemEnabled( const char * action, bool activate );
	
	/**
	* Sets the dictionary of accelerator action names and KKeyEntry
	* objects to nKeyDict.. Note that only a shallow copy is made so that items will be
	* lost when the KKeyEntry objects are deleted.
	*/	
	bool setKeyDict( QDict<KKeyEntry> nKeyDict );
	
	/**
	 * Ungrabs the key specified by key symbol
	 * keysym and modifier mod. Returns false if unsuccessful.
	 *
	 * Modifications with num lock and caps lock are also ungrabbed.
	 *
	 */
	bool ungrabKey(uint keysym, uint mod);

	/**
	 * Writes the current configurable associations to the application's
	 * configuration files
	 */	
	void writeSettings();
	
	/**
	 * Filters X11 events ev for key bindings in the accelerator dictionary.
	 * If a match is found the activated activated is emitted and the function
	 * returns true. Return false if the event is not processed.
	 */
	bool x11EventFilter(const XEvent *);
	
signals:
	void activated();	

protected:
	int aAvailableId;
	QDict<KKeyEntry> aKeyDict;
	bool bEnabled;
	QString aGroup;
	bool do_not_grab;

 protected:
};

#endif // _KGLOBALACCEL_H_