Manages and edits a list of keypresses, which it uses to invoke the appropriate command in an ApplicationCommandManager. More...
#include <juce_KeyPressMappingSet.h>
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 () override | |
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... | |
std::unique_ptr< 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 | callListeners () |
void | invokeCommand (const CommandID, const KeyPress &, const bool isKeyDown, const int millisecsSinceKeyPressed, Component *originator) const |
KeyPressMappingSet & | operator= (const KeyPressMappingSet &) |
Private Attributes | |
std::atomic< bool > | anyListeners { false } |
ChangeBroadcasterCallback | broadcastCallback |
ListenerList< ChangeListener > | changeListeners |
ApplicationCommandManager & | commandManager |
OwnedArray< KeyPressTime > | keysDown |
OwnedArray< CommandMapping > | mappings |
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:
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.
@tags{GUI}
|
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.
juce::KeyPressMappingSet::KeyPressMappingSet | ( | const KeyPressMappingSet & | ) |
Creates an copy of a KeyPressMappingSet.
|
override |
Destructor.
|
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.
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.
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 |
|
privateinherited |
void juce::KeyPressMappingSet::clearAllKeyPresses | ( | ) |
Removes all keypresses that are assigned to any commands.
void juce::KeyPressMappingSet::clearAllKeyPresses | ( | CommandID | commandID | ) |
Removes all keypresses that are assigned to a particular command.
|
noexcept |
Returns true if the given command is linked to this key.
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.
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. |
|
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.
|
noexcept |
Looks for a command that corresponds to a keypress.
|
inlinenoexcept |
Array<KeyPress> juce::KeyPressMappingSet::getKeyPressesAssignedToCommand | ( | CommandID | commandID | ) | const |
Returns a list of keypresses that are assigned to a particular command.
commandID | the command's ID |
|
overridevirtual |
Implements juce::FocusChangeListener.
|
private |
Implements juce::KeyListener.
Reimplemented from juce::KeyListener.
|
private |
|
inherited |
Removes all listeners from the list.
|
inherited |
Unregisters a listener from the list.
If the listener isn't on the list, this won't have any effect.
Removes one of the keypresses that are assigned to a command.
See the getKeyPressesAssignedToCommand() for the list of keypresses to which the keyPressIndex refers.
void juce::KeyPressMappingSet::removeKeyPress | ( | const KeyPress & | keypress | ) |
Removes a keypress from any command that it may be assigned to.
void juce::KeyPressMappingSet::resetToDefaultMapping | ( | CommandID | commandID | ) |
Resets all key-mappings to the defaults for a particular command.
void juce::KeyPressMappingSet::resetToDefaultMappings | ( | ) |
Reset all mappings to the defaults, as dictated by the ApplicationCommandManager.
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.
|
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 juce::SelectedItemSet< SelectableItemType >::changed().
|
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.
Referenced by juce::SelectedItemSet< SelectableItemType >::changed().
|
privateinherited |
|
privateinherited |
|
privateinherited |
|
private |
|
private |
|
private |