Manages and edits a list of keypresses, which it uses to invoke the appropriate command in an ApplicationCommandManager. More...

#include <juce_KeyPressMappingSet.h>

Inheritance diagram for KeyPressMappingSet:

[legend]

Collaboration diagram for KeyPressMappingSet:

[legend]

Classes
struct	CommandMapping

struct	KeyPressTime

Public Member Functions
	KeyPressMappingSet (ApplicationCommandManager &)
	Creates a KeyPressMappingSet for a given command manager. More...

	KeyPressMappingSet (const KeyPressMappingSet &)
	Creates an copy of a KeyPressMappingSet. More...

	~KeyPressMappingSet ()
	Destructor. More...

void	addChangeListener (ChangeListener *listener)
	Registers a listener to receive change callbacks from this broadcaster. More...

void	addKeyPress (CommandID commandID, const KeyPress &newKeyPress, int insertIndex=-1)
	Assigns a keypress to a command. More...

void	clearAllKeyPresses ()
	Removes all keypresses that are assigned to any commands. More...

void	clearAllKeyPresses (CommandID commandID)
	Removes all keypresses that are assigned to a particular command. More...

bool	containsMapping (CommandID commandID, const KeyPress &keyPress) const noexcept
	Returns true if the given command is linked to this key. More...

XmlElement *	createXml (bool saveDifferencesFromDefaultSet) const
	Creates an XML representation of the current mappings. More...

void	dispatchPendingMessages ()
	If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately. More...

CommandID	findCommandForKeyPress (const KeyPress &keyPress) const noexcept
	Looks for a command that corresponds to a keypress. More...

ApplicationCommandManager &	getCommandManager () const noexcept

Array< KeyPress >	getKeyPressesAssignedToCommand (CommandID commandID) const
	Returns a list of keypresses that are assigned to a particular command. More...

void	globalFocusChanged (Component *) override

bool	keyPressed (const KeyPress &, Component *) override

bool	keyStateChanged (bool isKeyDown, Component *) override

void	removeAllChangeListeners ()
	Removes all listeners from the list. More...

void	removeChangeListener (ChangeListener *listener)
	Unregisters a listener from the list. More...

void	removeKeyPress (CommandID commandID, int keyPressIndex)
	Removes one of the keypresses that are assigned to a command. More...

void	removeKeyPress (const KeyPress &keypress)
	Removes a keypress from any command that it may be assigned to. More...

void	resetToDefaultMapping (CommandID commandID)
	Resets all key-mappings to the defaults for a particular command. More...

void	resetToDefaultMappings ()
	Reset all mappings to the defaults, as dictated by the ApplicationCommandManager. More...

bool	restoreFromXml (const XmlElement &xmlVersion)
	Tries to recreate the mappings from a previously stored state. More...

void	sendChangeMessage ()
	Causes an asynchronous change message to be sent to all the registered listeners. More...

void	sendSynchronousChangeMessage ()
	Sends a synchronous change message to all the registered listeners. More...

Private Member Functions
void	invokeCommand (const CommandID, const KeyPress &, const bool isKeyDown, const int millisecsSinceKeyPressed, Component *originator) const

KeyPressMappingSet &	operator= (const KeyPressMappingSet &)

Private Attributes
ApplicationCommandManager &	commandManager

OwnedArray< KeyPressTime >	keysDown

OwnedArray< CommandMapping >	mappings

Detailed Description

Manages and edits a list of keypresses, which it uses to invoke the appropriate command in an ApplicationCommandManager.

Normally, you won't actually create a KeyPressMappingSet directly, because each ApplicationCommandManager contains its own KeyPressMappingSet, so typically you'd create yourself an ApplicationCommandManager, and call its ApplicationCommandManager::getKeyMappings() method to get a pointer to its KeyPressMappingSet.

For one of these to actually use keypresses, you'll need to add it as a KeyListener to the top-level component for which you want to handle keystrokes. So for example:

class MyMainWindow  : public Component
{
    ApplicationCommandManager* myCommandManager;
public:
    MyMainWindow()
    {
        myCommandManager = new ApplicationCommandManager();
        // first, make sure the command manager has registered all the commands that its
        // targets can perform..
        myCommandManager->registerAllCommandsForTarget (myCommandTarget1);
        myCommandManager->registerAllCommandsForTarget (myCommandTarget2);
        // this will use the command manager to initialise the KeyPressMappingSet with
        // the default keypresses that were specified when the targets added their commands
        // to the manager.
        myCommandManager->getKeyMappings()->resetToDefaultMappings();
        // having set up the default key-mappings, you might now want to load the last set
        // of mappings that the user configured.
        myCommandManager->getKeyMappings()->restoreFromXml (lastSavedKeyMappingsXML);
        // Now tell our top-level window to send any keypresses that arrive to the
        // KeyPressMappingSet, which will use them to invoke the appropriate commands.
        addKeyListener (myCommandManager->getKeyMappings());
    }
    ...
}

KeyPressMappingSet derives from ChangeBroadcaster so that interested parties can register to be told when a command or mapping is added, removed, etc.

There's also a UI component called KeyMappingEditorComponent that can be used to easily edit the key mappings.

See also: Component::addKeyListener(), KeyMappingEditorComponent, ApplicationCommandManager

Constructor & Destructor Documentation

◆ KeyPressMappingSet() [1/2]

KeyPressMappingSet::KeyPressMappingSet ( ApplicationCommandManager & )

explicit

Creates a KeyPressMappingSet for a given command manager.

Normally, you won't actually create a KeyPressMappingSet directly, because each ApplicationCommandManager contains its own KeyPressMappingSet, so the best thing to do is to create your ApplicationCommandManager, and use the ApplicationCommandManager::getKeyMappings() method to access its mappings.

When a suitable keypress happens, the manager's invoke() method will be used to invoke the appropriate command.

See also: ApplicationCommandManager

◆ KeyPressMappingSet() [2/2]

KeyPressMappingSet::KeyPressMappingSet ( const KeyPressMappingSet & )

Creates an copy of a KeyPressMappingSet.

◆ ~KeyPressMappingSet()

KeyPressMappingSet::~KeyPressMappingSet ( )

Destructor.

Member Function Documentation

◆ addChangeListener()

void ChangeBroadcaster::addChangeListener ( ChangeListener * listener )

inherited

Registers a listener to receive change callbacks from this broadcaster.

Trying to add a listener that's already on the list will have no effect.

◆ addKeyPress()

void KeyPressMappingSet::addKeyPress	(	CommandID	commandID,
		const KeyPress &	newKeyPress,
		int	insertIndex = `-1`
	)

Assigns a keypress to a command.

If the keypress is already assigned to a different command, it will first be removed from that command, to avoid it triggering multiple functions.

Parameters

commandID	the ID of the command that you want to add a keypress to. If this is 0, the keypress will be removed from anything that it was previously assigned to, but not re-assigned
newKeyPress	the new key-press
insertIndex	if this is less than zero, the key will be appended to the end of the list of keypresses; otherwise the new keypress will be inserted into the existing list at this index

◆ clearAllKeyPresses() [1/2]

void KeyPressMappingSet::clearAllKeyPresses ( )

Removes all keypresses that are assigned to any commands.

◆ clearAllKeyPresses() [2/2]

void KeyPressMappingSet::clearAllKeyPresses ( CommandID commandID )

Removes all keypresses that are assigned to a particular command.

◆ containsMapping()

bool KeyPressMappingSet::containsMapping	(	CommandID	commandID,
		const KeyPress &	keyPress
	)		const

noexcept

Returns true if the given command is linked to this key.

◆ createXml()

XmlElement* KeyPressMappingSet::createXml ( bool saveDifferencesFromDefaultSet ) const

Creates an XML representation of the current mappings.

This will produce a lump of XML that can be later reloaded using restoreFromXml() to recreate the current mapping state.

The object that is returned must be deleted by the caller.

Parameters

saveDifferencesFromDefaultSet if this is false, then all keypresses will be saved into the XML. If it's true, then the XML will only store the differences between the current mappings and the default mappings you'd get from calling resetToDefaultMappings(). The advantage of saving a set of differences from the default is that if you change the default mappings (in a new version of your app, for example), then these will be merged into a user's saved preferences.

See also: restoreFromXml

◆ dispatchPendingMessages()

void ChangeBroadcaster::dispatchPendingMessages ( )

inherited

If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.

For thread-safety reasons, you must only call this method on the main message thread.

◆ findCommandForKeyPress()

CommandID KeyPressMappingSet::findCommandForKeyPress ( const KeyPress & keyPress ) const

noexcept

Looks for a command that corresponds to a keypress.

Returns: the UID of the command or 0 if none was found

◆ getCommandManager()

ApplicationCommandManager& KeyPressMappingSet::getCommandManager ( ) const

inlinenoexcept

References FocusChangeListener::globalFocusChanged(), KeyListener::keyPressed(), and KeyListener::keyStateChanged().

◆ getKeyPressesAssignedToCommand()

Array<KeyPress> KeyPressMappingSet::getKeyPressesAssignedToCommand ( CommandID commandID ) const

Returns a list of keypresses that are assigned to a particular command.

Parameters

commandID the command's ID

◆ globalFocusChanged()

void KeyPressMappingSet::globalFocusChanged ( Component * )

overridevirtual

Implements FocusChangeListener.

◆ invokeCommand()

void KeyPressMappingSet::invokeCommand	(	const CommandID	,
		const KeyPress &	,
		const bool	isKeyDown,
		const int	millisecsSinceKeyPressed,
		Component *	originator
	)		const

private

◆ keyPressed()

bool KeyPressMappingSet::keyPressed	(	const KeyPress &	,
		Component *
	)

overridevirtual

Implements KeyListener.

◆ keyStateChanged()

bool KeyPressMappingSet::keyStateChanged	(	bool	isKeyDown,
		Component *
	)

overridevirtual

Reimplemented from KeyListener.

◆ operator=()

KeyPressMappingSet& KeyPressMappingSet::operator= ( const KeyPressMappingSet & )

private

◆ removeAllChangeListeners()

void ChangeBroadcaster::removeAllChangeListeners ( )

inherited

Removes all listeners from the list.

◆ removeChangeListener()

void ChangeBroadcaster::removeChangeListener ( ChangeListener * listener )

inherited

Unregisters a listener from the list.

If the listener isn't on the list, this won't have any effect.

◆ removeKeyPress() [1/2]

void KeyPressMappingSet::removeKeyPress	(	CommandID	commandID,
		int	keyPressIndex
	)

Removes one of the keypresses that are assigned to a command.

See the getKeyPressesAssignedToCommand() for the list of keypresses to which the keyPressIndex refers.

◆ removeKeyPress() [2/2]

void KeyPressMappingSet::removeKeyPress ( const KeyPress & keypress )

Removes a keypress from any command that it may be assigned to.

◆ resetToDefaultMapping()

void KeyPressMappingSet::resetToDefaultMapping ( CommandID commandID )

Resets all key-mappings to the defaults for a particular command.

See also: resetToDefaultMappings

◆ resetToDefaultMappings()

void KeyPressMappingSet::resetToDefaultMappings ( )

Reset all mappings to the defaults, as dictated by the ApplicationCommandManager.

See also: resetToDefaultMapping

◆ restoreFromXml()

bool KeyPressMappingSet::restoreFromXml ( const XmlElement & xmlVersion )

Tries to recreate the mappings from a previously stored state.

The XML passed in must have been created by the createXml() method.

If the stored state makes any reference to commands that aren't currently available, these will be ignored.

If the set of mappings being loaded was a set of differences (using createXml (true)), then this will call resetToDefaultMappings() and then merge the saved mappings on top. If the saved set was created with createXml (false), then this method will first clear all existing mappings and load the saved ones as a complete set.

Returns: true if it manages to load the XML correctly

See also: createXml

◆ sendChangeMessage()

void ChangeBroadcaster::sendChangeMessage ( )

inherited

Causes an asynchronous change message to be sent to all the registered listeners.

The message will be delivered asynchronously by the main message thread, so this method will return immediately. To call the listeners synchronously use sendSynchronousChangeMessage().

Referenced by SelectedItemSet< SelectableItemType >::changed().

◆ sendSynchronousChangeMessage()

void ChangeBroadcaster::sendSynchronousChangeMessage ( )

inherited

Sends a synchronous change message to all the registered listeners.

This will immediately call all the listeners that are registered. For thread-safety reasons, you must only call this method on the main message thread.

See also: dispatchPendingMessages

Referenced by SelectedItemSet< SelectableItemType >::changed().

Member Data Documentation

◆ commandManager

ApplicationCommandManager& KeyPressMappingSet::commandManager

private

◆ keysDown

OwnedArray<KeyPressTime> KeyPressMappingSet::keysDown

private

◆ mappings

OwnedArray<CommandMapping> KeyPressMappingSet::mappings

private

The documentation for this class was generated from the following file:

juce_KeyPressMappingSet.h

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ KeyPressMappingSet() [1/2]

◆ KeyPressMappingSet() [2/2]

◆ ~KeyPressMappingSet()

Member Function Documentation

◆ addChangeListener()

◆ addKeyPress()

◆ clearAllKeyPresses() [1/2]

◆ clearAllKeyPresses() [2/2]

◆ containsMapping()

◆ createXml()

◆ dispatchPendingMessages()

◆ findCommandForKeyPress()

◆ getCommandManager()

◆ getKeyPressesAssignedToCommand()

◆ globalFocusChanged()

◆ invokeCommand()

◆ keyPressed()

◆ keyStateChanged()

◆ operator=()

◆ removeAllChangeListeners()

◆ removeChangeListener()

◆ removeKeyPress() [1/2]

◆ removeKeyPress() [2/2]

◆ resetToDefaultMapping()

◆ resetToDefaultMappings()

◆ restoreFromXml()

◆ sendChangeMessage()

◆ sendSynchronousChangeMessage()

Member Data Documentation

◆ commandManager

◆ keysDown

◆ mappings