commands.h
Named actions, and the keys that reach them.
#include <sonore/commands.h>- 3types
- Guides: Testing your plugin
On this page
Design notes
NOT part of the generated-interface protocol. A page the studio writes never calls these -- the protocol does not know them, and the review gate would reject a page that did. They exist for interfaces written by hand against this SDK, and for the fallback panel.
What it is for
Undo. Save preset. Next preset. Bypass. A plugin has a handful of things it can be asked to do that are not a parameter, and without something like this each one is a lambda hanging off a button, invisible to the keyboard and impossible to rebind.
The point of a COMMAND rather than a callback is that the action has a name, an identity and a state -- so one thing can be reached from a button, a menu item and a shortcut and be greyed out in all three at once, and a user who wants Ctrl+S somewhere else can move it.
This could not have existed until a week ago
Ctrl+A reached WM_CHAR as 0x01 and no shortcut in this SDK worked at all. A command manager on top of that would have been a table nothing ever consulted -- present, documented, and dead. The peers deliver the letter with the modifier now, and this is what that fix was for.
The rules that matter
A shortcut belongs to ONE command. Assigning it to a second takes it from the first, because two commands firing on one key is worse than either.
A disabled command does not fire and does NOT consume the key. That is the less obvious half: a swallowed key that does nothing is indistinguishable from a broken keyboard, where an unconsumed one falls through to whatever else wanted it.
The component tree gets the key FIRST. A text field must have Ctrl+A for select-all rather than a global command stealing it out from under the caret -- which is why this is consulted only for keys nothing else took.
Types 3
A key combination.
Either a CHARACTER -- lowercase, which is what all three peers deliver for a modifier combination -- or a named key code. Not both: a shortcut is one key and describing it twice invites the two halves to disagree.
What a command is called and where it is listed. id is the plugin's own number for it, non-zero (registerCommand ignores 0, which is also what "no command" means elsewhere), and it is what saved mappings refer to -- so it must stay the same from one version to the next.
The plugin's commands, their enabled and ticked state, and the shortcuts that reach them -- the part the reference's application command manager plays, with one onInvoke handler in place of command targets. See the file comment for the rules about shortcuts and disabled commands.
UI THREAD, all of it: keyPressed() is fed the keys the component tree did not take (MouseRouter::onUnhandledKey), and onInvoke runs on whichever thread called invoke() or keyPressed(). Commands are registered in code each time the plugin loads; only the user's mappings are saved (saveMappings / loadMappings). A pointer from commandInfo() lasts until the next registerCommand of a new id.