Loading...
Searching...
No Matches
juce::KeyPressMappingSet Class Reference

## 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());
}
...
}
juce::ApplicationCommandManager
One of these objects holds a list of all the commands your app can perform, and despatches these comm...
Definition juce_ApplicationCommandManager.h:97
juce::ApplicationCommandManager::getKeyMappings
KeyPressMappingSet * getKeyMappings() const noexcept
Returns the manager's internal set of key mappings.
Definition juce_ApplicationCommandManager.h:211
juce::ApplicationCommandManager::registerAllCommandsForTarget
void registerAllCommandsForTarget(ApplicationCommandTarget *target)
Adds all the commands that this target publishes to the manager's list.
juce::Component
The base class for all JUCE user-interface objects.
Definition juce_Component.h:45
juce::Component::addKeyListener
void addKeyListener(KeyListener *newListener)
Adds a listener that wants to hear about keypresses that this component receives.
juce::KeyPressMappingSet::resetToDefaultMappings
void resetToDefaultMappings()
Reset all mappings to the defaults, as dictated by the ApplicationCommandManager.
juce::KeyPressMappingSet::restoreFromXml
bool restoreFromXml(const XmlElement &xmlVersion)
Tries to recreate the mappings from a previously stored state.

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

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

- juce_gui_basics/commands/juce_KeyPressMappingSet.h

Inheritance diagram for juce::KeyPressMappingSet:

## Public Member Functions

| KeyPressMappingSet (ApplicationCommandManager &)
| Creates a KeyPressMappingSet for a given command manager.
| KeyPressMappingSet (const KeyPressMappingSet &)
| Creates an copy of a KeyPressMappingSet.
| ~KeyPressMappingSet () override
| Destructor.
ApplicationCommandManager & | getCommandManager () const noexcept
Array< KeyPress > | getKeyPressesAssignedToCommand (CommandID commandID) const
| Returns a list of keypresses that are assigned to a particular command.
void | addKeyPress (CommandID commandID, const KeyPress &newKeyPress, int insertIndex=-1)
| Assigns a keypress to a command.
void | resetToDefaultMappings ()
| Reset all mappings to the defaults, as dictated by the ApplicationCommandManager.
void | resetToDefaultMapping (CommandID commandID)
| Resets all key-mappings to the defaults for a particular command.
void | clearAllKeyPresses ()
| Removes all keypresses that are assigned to any commands.
void | clearAllKeyPresses (CommandID commandID)
| Removes all keypresses that are assigned to a particular command.
void | removeKeyPress (CommandID commandID, int keyPressIndex)
| Removes one of the keypresses that are assigned to a command.
void | removeKeyPress (const KeyPress &keypress)
| Removes a keypress from any command that it may be assigned to.
bool | containsMapping (CommandID commandID, const KeyPress &keyPress) const noexcept
| Returns true if the given command is linked to this key.
CommandID | findCommandForKeyPress (const KeyPress &keyPress) const noexcept
| Looks for a command that corresponds to a keypress.
bool | restoreFromXml (const XmlElement &xmlVersion)
| Tries to recreate the mappings from a previously stored state.
std::unique_ptr< XmlElement > | createXml (bool saveDifferencesFromDefaultSet) const
| Creates an XML representation of the current mappings.
bool | keyPressed (const KeyPress &, Component *) override
| Called to indicate that a key has been pressed.
bool | keyStateChanged (bool isKeyDown, Component *) override
| Called when any key is pressed or released.
void | globalFocusChanged (Component *) override
| Callback to indicate that the currently focused component has changed.
Public Member Functions inherited from juce::KeyListener
virtual | ~KeyListener ()=default
| Destructor.
Public Member Functions inherited from juce::ChangeBroadcaster
| ChangeBroadcaster () noexcept
| Creates an ChangeBroadcaster.
virtual | ~ChangeBroadcaster ()
| Destructor.
void | addChangeListener (ChangeListener *listener)
| Registers a listener to receive change callbacks from this broadcaster.
void | removeChangeListener (ChangeListener *listener)
| Unregisters a listener from the list.
void | removeAllChangeListeners ()
| Removes all listeners from the list.
void | sendChangeMessage ()
| Causes an asynchronous change message to be sent to all the registered listeners.
void | sendSynchronousChangeMessage ()
| Sends a synchronous change message to all the registered listeners.
void | dispatchPendingMessages ()
| If a change message has been sent but not yet dispatched, this will call sendSynchronousChangeMessage() to make the callback immediately.

## Constructors and Destructors

## KeyPressMappingSet() [1/2]

juce::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

Referenced by KeyPressMappingSet().

## KeyPressMappingSet() [2/2]

juce::KeyPressMappingSet::KeyPressMappingSet | ( | const KeyPressMappingSet & |  | ) |

Creates an copy of a KeyPressMappingSet.

References KeyPressMappingSet().

## ~KeyPressMappingSet()

juce::KeyPressMappingSet::~KeyPressMappingSet | ( |  | ) |

override

Destructor.

## Member Functions

## getCommandManager()

ApplicationCommandManager & juce::KeyPressMappingSet::getCommandManager | ( |  | ) | const

inline noexcept

## getKeyPressesAssignedToCommand()

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

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

Parameters

  commandID | the command's ID

## addKeyPress()

void juce::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

## resetToDefaultMappings()

void juce::KeyPressMappingSet::resetToDefaultMappings | ( |  | ) |

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

See also
  resetToDefaultMapping

## resetToDefaultMapping()

void juce::KeyPressMappingSet::resetToDefaultMapping | ( | CommandID | commandID | ) |

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

See also
  resetToDefaultMappings

## clearAllKeyPresses() [1/2]

void juce::KeyPressMappingSet::clearAllKeyPresses | ( |  | ) |

Removes all keypresses that are assigned to any commands.

## clearAllKeyPresses() [2/2]

void juce::KeyPressMappingSet::clearAllKeyPresses | ( | CommandID | commandID | ) |

Removes all keypresses that are assigned to a particular command.

## removeKeyPress() [1/2]

void juce::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 juce::KeyPressMappingSet::removeKeyPress | ( | const KeyPress & | keypress | ) |

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

## containsMapping()

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

noexcept

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

## findCommandForKeyPress()

CommandID juce::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

## restoreFromXml()

bool juce::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

## createXml()

std::unique_ptr< XmlElement > juce::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.

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

## keyPressed()

bool juce::KeyPressMappingSet::keyPressed | ( | const KeyPress & | key,
|  | Component * | originatingComponent )

override virtual

Called to indicate that a key has been pressed.

If your implementation returns true, then the key event is considered to have been consumed, and will not be passed on to any other components. If it returns false, then the key will be passed to other components that might want to use it.

Parameters

  key | the keystroke, including modifier keys
  originatingComponent | the component that received the key event

See also
  keyStateChanged, Component::keyPressed

Implements juce::KeyListener.

## keyStateChanged()

bool juce::KeyPressMappingSet::keyStateChanged | ( | bool | isKeyDown,
|  | Component * | originatingComponent )

override virtual

Called when any key is pressed or released.

When this is called, classes that might be interested in the state of one or more keys can use KeyPress::isKeyCurrentlyDown() to check whether their key has changed.

If your implementation returns true, then the key event is considered to have been consumed, and will not be passed on to any other components. If it returns false, then the key will be passed to other components that might want to use it.

Parameters

  originatingComponent | the component that received the key event
  isKeyDown | true if a key is being pressed, false if one is being released

See also
  KeyPress, Component::keyStateChanged

Reimplemented from juce::KeyListener.

## globalFocusChanged()

void juce::KeyPressMappingSet::globalFocusChanged | ( | Component * | focusedComponent | ) |

override virtual

Callback to indicate that the currently focused component has changed.

Implements juce::FocusChangeListener.

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited