Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us