Shortcuts & Input Routing

Keyboard shortcuts with focus routing and key ownership

Overview

The shortcut system allows multiple widgets to register interest in a shortcut, but only one owner gets it based on focus routing. This makes shortcuts work correctly in complex hierarchies.

Use Shortcut() instead of IsKeyPressed()/IsKeyChordPressed() for better features and focus routing support.

Key Concepts

The general idea:

• Several callers may register interest in a shortcut
• Only one owner gets it based on focus routing
• The system is order independent

Parent   -> call Shortcut(Ctrl+S)  // When Parent is focused, Parent gets it
  Child1 -> call Shortcut(Ctrl+S)  // When Child1 is focused, Child1 gets it
  Child2 -> no call                // When Child2 is focused, Parent gets it

Shortcut Function

Shortcut

bool Shortcut(ImGuiKeyChord key_chord, ImGuiInputFlags flags = 0);

Test if a keyboard shortcut is pressed and routed to the calling code.

key_chord · ImGuiKeyChord

Key chord (e.g., ImGuiMod_Ctrl | ImGuiKey_S)

flags · ImGuiInputFlags · default: "0"

Input flags for routing and repeat behavior

Returns · bool

True if shortcut was pressed and routed to this code

Example:

if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_S))
{
    SaveDocument();
}

if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiMod_Shift | ImGuiKey_Z))
{
    Redo();
}

// With repeat
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_Z, ImGuiInputFlags_Repeat))
{
    Undo();
}

SetNextItemShortcut

void SetNextItemShortcut(ImGuiKeyChord key_chord, ImGuiInputFlags flags = 0);

Set a keyboard shortcut for the next item. The shortcut will be displayed in tooltips.

key_chord · ImGuiKeyChord

Key chord for the shortcut

flags · ImGuiInputFlags · default: "0"

Input flags

Example:

ImGui::SetNextItemShortcut(ImGuiMod_Ctrl | ImGuiKey_O, ImGuiInputFlags_Tooltip);
if (ImGui::MenuItem("Open"))
{
    OpenFile();
}

Key Chords

A key chord is a key optionally combined with modifiers:

// Simple key
ImGuiKey_C

// Key with single modifier
ImGuiMod_Ctrl | ImGuiKey_C

// Key with multiple modifiers  
ImGuiMod_Ctrl | ImGuiMod_Shift | ImGuiKey_Z

// Alt+F4
ImGuiMod_Alt | ImGuiKey_F4

Only ImGuiMod_XXX values are legal to combine with an ImGuiKey. You CANNOT combine two ImGuiKey values.

Input Flags

Repeat Flag

ImGuiInputFlags_Repeat  // Enable repeat (like holding down a key)

Example:

if (ImGui::Shortcut(ImGuiKey_Delete, ImGuiInputFlags_Repeat))
{
    DeleteSelectedItems();
}

Routing Policies

Default policy is ImGuiInputFlags_RouteFocused. Can select only 1 policy:

enum ImGuiInputFlags_
{
    ImGuiInputFlags_RouteActive      = 1 << 10,  // Route to active item only
    ImGuiInputFlags_RouteFocused     = 1 << 11,  // Route to focused window (default)
    ImGuiInputFlags_RouteGlobal      = 1 << 12,  // Global route
    ImGuiInputFlags_RouteAlways      = 1 << 13,  // Always poll directly
};

RouteActive · ImGuiInputFlags

Route to active item only.

RouteFocused · ImGuiInputFlags

Route to windows in the focus stack (DEFAULT). Deep-most focused window takes inputs.

RouteGlobal · ImGuiInputFlags

Global route (unless a focused window or active item registered the route).

RouteAlways · ImGuiInputFlags

Do not register route, poll keys directly.

Routing Options

ImGuiInputFlags_RouteOverFocused     // Global route: higher priority than focused
ImGuiInputFlags_RouteOverActive      // Global route: higher priority than active item
ImGuiInputFlags_RouteUnlessBgFocused // Global route: not applied if no windows focused
ImGuiInputFlags_RouteFromRootWindow  // Route from root window rather than current

Example with routing:

// Global shortcut, works even when no window is focused
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_Q, ImGuiInputFlags_RouteGlobal))
{
    QuitApplication();
}

// Only works when specific widget is active
if (ImGui::Shortcut(ImGuiKey_Escape, ImGuiInputFlags_RouteActive))
{
    CancelOperation();
}

Tooltip Flag

ImGuiInputFlags_Tooltip  // Automatically display tooltip when hovering item

Example:

ImGui::SetNextItemShortcut(ImGuiMod_Ctrl | ImGuiKey_S, ImGuiInputFlags_Tooltip);
if (ImGui::MenuItem("Save"))
{
    SaveDocument();
}
// Hovering "Save" will show "Ctrl+S" in tooltip

Routing Priority

Routing policies are resolved in this order:

1. RouteGlobal + OverActive
2. RouteActive or RouteFocused (if owner is active item)
3. RouteGlobal + OverFocused
4. RouteFocused (if in focused window stack)
5. RouteGlobal

Key Ownership

SetItemKeyOwner

void SetItemKeyOwner(ImGuiKey key);

Set key owner to last item ID if it is hovered or active. Equivalent to:

if (IsItemHovered() || IsItemActive())
    SetKeyOwner(key, GetItemID());

key · ImGuiKey

Key to claim ownership of

Use case: Disable standard input behaviors like mouse wheel scrolling.

Example:

// Make button disable mouse wheel for scrolling when hovered/active
ImGui::Button("My Button");
ImGui::SetItemKeyOwner(ImGuiKey_MouseWheelY);

Difference: IsKeyChordPressed vs Shortcut

IsKeyChordPressed

• Compares mods and calls IsKeyPressed()
• No side-effects
• No routing

Shortcut

• Submits a route
• Routes are resolved
• Calls IsKeyChordPressed() if routed
• Has side-effects (can prevent another call from getting the route)

Common Shortcut Patterns

Standard Editor Shortcuts

if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_Z))
    Undo();
    
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_Y) ||
    ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiMod_Shift | ImGuiKey_Z))
    Redo();
    
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_C))
    Copy();
    
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_X))
    Cut();
    
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_V))
    Paste();
    
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_A))
    SelectAll();

Application-Wide Shortcuts

// Use RouteGlobal for app-wide shortcuts
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_N, ImGuiInputFlags_RouteGlobal))
    NewDocument();
    
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_O, ImGuiInputFlags_RouteGlobal))
    OpenDocument();
    
if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_S, ImGuiInputFlags_RouteGlobal))
    SaveDocument();

Context-Sensitive Shortcuts

void DrawTextEditor()
{
    ImGui::BeginChild("Editor");
    
    // These shortcuts only work when editor is focused
    if (ImGui::Shortcut(ImGuiKey_F3))
        FindNext();
        
    if (ImGui::Shortcut(ImGuiMod_Ctrl | ImGuiKey_H))
        ShowFindReplace();
        
    // Editor content...
    
    ImGui::EndChild();
}

Debugging

Visualize registered routes in Metrics/Debugger -> Inputs.

Platform Considerations

On macOS, Dear ImGui automatically swaps Cmd(Super) and Ctrl keys:

• ImGuiMod_Ctrl = Cmd on macOS, Ctrl on other platforms
• ImGuiMod_Super = Ctrl on macOS, Windows/Super on other platforms

See Also

• Keyboard - Keyboard input functions
• Mouse - Mouse input functions
• Input - General input functions