plugin_key_routing.hpp

Go to the documentation of this file.

// plugin_key_routing.hpp — who consumes a key inside an embedded plugin editor.
//
// An embedded editor shares one keyboard with its DAW. The editor must consume
// the keys it genuinely handles (⌘Z, ⌘A, a typed character, an open menu's
// arrows) and hand back every key it does not, because the host owns transport
// (Space), Musical Typing, and its own accelerator table. Getting the first
// half right is easy and gets noticed immediately; getting the SECOND half
// wrong is what users report as "the plugin killed my spacebar".
//
// The answer must come from the view tree, not from a list of keys someone
// guessed at: `route_plugin_key` asks the overlay policy, then the focused
// view, then the root's global hook, and reports `forward_to_host` only when
// none of them claimed the key.
//
// This lives in core/view and takes no platform type, because the same
// question is asked from three different format seams that share no code:
// macOS `-keyDown:` / `-performKeyEquivalent:` (AU v2/v3 hosted NSView),
// `IPlugView::onKeyDown` (VST3), and CLAP's GUI extension. Each seam speaks a
// different consumed/not-consumed dialect; only the policy is shared.
 
#pragma once
 
#include <cstdint>
 
#include <pulp/view/input_events.hpp>
 
namespace pulp::view {
 
class View;

enum class PluginKeyDisposition : std::uint8_t {
    forward_to_host,
    consumed,
    insert_as_text,
};

struct PluginKeyOffer {
    KeyEvent key;
    bool is_function_key = false;
    bool offer_global_hook = false;
};

PluginKeyDisposition route_plugin_key(View& root, const PluginKeyOffer& offer);

View* plugin_key_focus(View& root);

bool is_plugin_navigation_key(KeyCode key, std::uint16_t modifiers);
 
} // namespace pulp::view