VCF::AcceleratorKey Class Reference

An AcceleratorKey represents a link between a specific keyboard keystroke combination and an event handler to be invoked when the combination takes place. More...

#include <vcf/ApplicationKit/AcceleratorKey.h>

Inheritance diagram for VCF::AcceleratorKey:

List of all members.


Public Member Functions
	AcceleratorKey (Control associatedControl, const VirtualKeyCode &keyCode, const uint32 &modifierMask, EventHandler eventHandler, const bool &isMnemonic=false)
	AcceleratorKey (MenuItem associatedMenuItem, const VirtualKeyCode &keyCode, const uint32 &modifierMask, EventHandler eventHandler, const bool &isMnemonic=false)
	AcceleratorKey (Object associatedObject, const VirtualKeyCode &keyCode, const uint32 &modifierMask, EventHandler eventHandler, const bool &isMnemonic=false)
virtual	~AcceleratorKey ()
bool	hasShiftKey ()
	does the AcceleratorKey have the shift key in it's keyboard combination.
bool	hasCtrlKey ()
	does the AcceleratorKey have the Ctrl key in it's keyboard combination.
bool	hasAltKey ()
	does the AcceleratorKey have the Alt key in it's keyboard combination.
uint32	getKeyCode () const
	gets the virtual key code that represents the specific alpha numeric key, like "V", or "1" or "F1"
uint32	getModifierMask () const
	gets the modifier mask for the AcceleratorKey.
Control *	getAssociatedControl ()
	returns the associated control.
MenuItem *	getAssociatedMenuItem ()
	returns the associated menu item.
Object *	getAssociatedObject ()
	returns the associated object instance.
EventHandler *	getEventHandler ()
	The event handler that will be invoked by the AcceleratorKey when it becomes activated by the framework.
void	invoke (Event *event)
	call this method to invoke the event handler for this AcceleratorKey.
bool	isMnemonic ()
	returns whether or not the AcceleratorKey is triggered by a keyboard mnemonic.
bool	isEnabled ()
void	setEnabled (const bool &val)
virtual Object *	clone (bool deep=false)
	Makes a complete clone of this object.
Protected Member Functions
	AcceleratorKey (const AcceleratorKey &rhs)
Protected Attributes
VirtualKeyCode	keyCode_
uint32	modifierMask_
Control *	associatedControl_
MenuItem *	associatedMenuItem_
Object *	associatedObject_
EventHandler *	eventHandler_
bool	isMnemonic_
bool	enabled_
Classes
class	Value
	This class is used to hold the values of both the keyboard modifier(s), such as Ctrl, Shift, or Alt, and the virtual key value, such as vkLetterV. More...

Detailed Description

An AcceleratorKey represents a link between a specific keyboard keystroke combination and an event handler to be invoked when the combination takes place.

There may be more than one intance of a AcceleratorKey that is linked to the same keystroke combination. AcceleratorKey objects may associated with a control, a menu item or a some other generic Object instance.

AcceleratorKey objects may also be linked to Action objects which allows the action and accelerator to be linked together and reused among more than one target, such as a button, and menu item.

Certain classes may have multiple accelerators associated with them, while others may have only one. A Control may 0 or more accelerators associated with it. A MenuItem or Action may have only one accelerator associated with it at any given moment.

The UIToolkit is used to store all the various accelerators, as well as implemententing the exact logic for how accelerators get called. The toolkit will release any accelerators, so once assigned, you no longer have to worry about cleaning up the memory for the object.

When toolkit receives notification from the underlying window system that a keystroke has taken place, it attempts to see if the keystroke maps to any registered accelerators, and if it finds one, then the accelerator's event handler is invoked. This logic thus allows you to have multiple accelerators mapped to both a control and to a menu item. Precedence is given to the control, then the menu item, and then anything else. The logic for determining the proper accelerator to use is this:

The toolkit attempts to find the current focused control.
It then attemps to match an accelerator, based on the keystroke and the current focused control
If no accelerator is found that has a matching control (see Accelerator::getAssociatedControl() ), then a search is made to find an accelerator with the keystroke.
The first accelerator found with the matching keystroke, and a non NULL menu associated with it (see Accelerator::getAssociatedMenuItem() ) is then used.
If no match is found then a similar search is made for any accelerators that match the keystroke and have a non NULL object associated with it.

An example of how you might use an accelerator is this: Let's say you have a text editor and you want the "Ctrl" and "V" key combination to call an event handler whenever it is pressed to paste in some text from the clipboard. You can register an AcceleratorKey with the keyboard combination and you event handler, and voila! the VCF will take care of the rest.

In addition to this, menu items also work with accelerators to enable the accelerator information to be displayed in the menu item caption/text. This will work for any menu item that has an accelerator set "directly", or a menu item that is associated with an Action that itself has an accelerator assigned to it. This means that instead of having to manually set the text for your menu item to hold the key combo associated with it, the framework will do it for you. For example:

MenuItem* fileOpen = new DefaultMenuItem( "Open", file, menuBar );
fileOpen->setAcceleratorKey( vkLetterO, kmCtrl );

That's it! The fileOpen menu item will be adjusted when it's displayed, and instead of just displaying "Open", it will display "Open Ctrl+O". This works with actions as well:

MenuItem* fileOpen = new DefaultMenuItem( "Open", file, menuBar );
Action* fileOpenAction = new Action();
addComponent( fileOpenAction );
fileOpenAction->addTarget( fileOpen );
fileOpenAction->setAcceleratorKey( vkLetterO, kmCtrl );

The same thing will now happen, the menu will still display "Open Ctrl+O", despite the accelerator being set on the action instead of the menu item directly.

See also:

Control::addAcceleratorKey

MenuItem::setAcceleratorKey

Action::setAcceleratorKey

UIToolkit::addAcceleratorKey()

Constructor & Destructor Documentation

VCF::AcceleratorKey::AcceleratorKey ( Control * associatedControl,

const VirtualKeyCode & keyCode,

const uint32 & modifierMask,

EventHandler * eventHandler,

const bool & isMnemonic = false

)

VCF::AcceleratorKey::AcceleratorKey ( MenuItem * associatedMenuItem,

const VirtualKeyCode & keyCode,

const uint32 & modifierMask,

EventHandler * eventHandler,

const bool & isMnemonic = false

)

VCF::AcceleratorKey::AcceleratorKey ( Object * associatedObject,

const VirtualKeyCode & keyCode,

const uint32 & modifierMask,

EventHandler * eventHandler,

const bool & isMnemonic = false

)

virtual VCF::AcceleratorKey::~AcceleratorKey ( ) [virtual]

VCF::AcceleratorKey::AcceleratorKey ( const AcceleratorKey & rhs ) [protected]

Member Function Documentation

virtual Object* VCF::AcceleratorKey::clone ( bool deep = false ) [virtual]

Makes a complete clone of this object.
A typical implementation might be:
virtual Object* clone( bool deep ) { return new MyObject( this ); }
In which the implementer simply creates a new instance on the heap and calls the copy constructor. Objects which support cloning should also have a copy constructor defined as well.

Parameters:

bool deep if deep is true then any object instances that this object owns should probably be cloned as well, with full new copies made. Otherwise it would be acceptable to simply copy the pointer values. The default value is for deep cloning to be false.

Returns:
Object a new instance that should be an copy of this. If the object doesn't support cloning the return will value will be NULL.

Reimplemented from VCF::Object.

Control* VCF::AcceleratorKey::getAssociatedControl ( ) [inline]

returns the associated control.
An AcceleratorKey can have a control instance associated with it.
Returns:
Control the associated control

MenuItem* VCF::AcceleratorKey::getAssociatedMenuItem ( ) [inline]

returns the associated menu item.
An AcceleratorKey can have a menu item instance associated with it.
Returns:
MenuItem the associated menu item

Object* VCF::AcceleratorKey::getAssociatedObject ( ) [inline]

returns the associated object instance.
An AcceleratorKey can have an object instance associated with it.
Returns:
Object the associated object

EventHandler* VCF::AcceleratorKey::getEventHandler ( ) [inline]

The event handler that will be invoked by the AcceleratorKey when it becomes activated by the framework.

Returns:
EventHandler the AcceleratorKey's event handler

uint32 VCF::AcceleratorKey::getKeyCode ( ) const [inline]

gets the virtual key code that represents the specific alpha numeric key, like "V", or "1" or "F1"

Returns:
uint32 the keycode for this AcceleratorKey

uint32 VCF::AcceleratorKey::getModifierMask ( ) const [inline]

gets the modifier mask for the AcceleratorKey.
The modifier mask may be made up of any combination of the Ctrl, Shift, and Alt keys.

bool VCF::AcceleratorKey::hasAltKey ( )

does the AcceleratorKey have the Alt key in it's keyboard combination.

Returns:
bool returns true if it does, false if it doesn't

bool VCF::AcceleratorKey::hasCtrlKey ( )

does the AcceleratorKey have the Ctrl key in it's keyboard combination.

Returns:
bool returns true if it does, false if it doesn't

bool VCF::AcceleratorKey::hasShiftKey ( )

does the AcceleratorKey have the shift key in it's keyboard combination.

Returns:
bool returns true if it does, false if it doesn't

void VCF::AcceleratorKey::invoke ( Event * event )

call this method to invoke the event handler for this AcceleratorKey.
The implementation simply passes the event to the invoke() method on the event handler.
Parameters:

Event* the event to pass to the event handler

See also:
EventHandler::invoke()

bool VCF::AcceleratorKey::isEnabled ( ) [inline]

bool VCF::AcceleratorKey::isMnemonic ( ) [inline]

returns whether or not the AcceleratorKey is triggered by a keyboard mnemonic.
A keyboard mnemonic is a single alpha-numeric key plus the "Alt" key that trigger an action on a control. For example a button might have a caption "Erase" and the mnemonic was the "Alt" + "E" keys (this is usually displayed on controls as a character with an underline). Pressing the "Alt" + "E" key combination would cause the button's mnemonicActivate() method to be called.
Returns:
bool returns true if the AcceleratorKey is a mnemonic false otherwise

See also:
Control::mnemonicActivate()