Mouse Input

Functions for checking mouse state, clicks, position, and dragging

Mouse Button State

IsMouseDown

bool IsMouseDown(ImGuiMouseButton button);

Check if mouse button is being held.

button · ImGuiMouseButton

Mouse button (0=left, 1=right, 2=middle)

Returns · bool

True if button is currently down

Example:

if (ImGui::IsMouseDown(ImGuiMouseButton_Left))
{
    ImGui::Text("Left mouse button is held");
}

IsMouseClicked

bool IsMouseClicked(ImGuiMouseButton button, bool repeat = false);

Check if mouse button was clicked (went from !Down to Down). Same as GetMouseClickedCount() == 1.

button · ImGuiMouseButton

Mouse button to check

repeat · bool · default: "false"

If true, returns true on repeat clicks

Returns · bool

True if button was just clicked

Example:

if (ImGui::IsMouseClicked(ImGuiMouseButton_Left))
{
    ProcessClick();
}

IsMouseReleased

bool IsMouseReleased(ImGuiMouseButton button);

Check if mouse button was released (went from Down to !Down).

button · ImGuiMouseButton

Mouse button to check

Returns · bool

True if button was just released

IsMouseDoubleClicked

bool IsMouseDoubleClicked(ImGuiMouseButton button);

Check if mouse button was double-clicked. Same as GetMouseClickedCount() == 2.

button · ImGuiMouseButton

Mouse button to check

Returns · bool

True if button was double-clicked

A double-click will also report IsMouseClicked() == true.

Example:

if (ImGui::IsMouseDoubleClicked(ImGuiMouseButton_Left))
{
    OpenItem();
}

GetMouseClickedCount

int GetMouseClickedCount(ImGuiMouseButton button);

Return the number of successive mouse clicks at the time where a click happened.

button · ImGuiMouseButton

Mouse button to check

Returns · int

Number of clicks (0=not clicked, 1=single click, 2=double click, 3=triple click, etc.)

Example:

int clicks = ImGui::GetMouseClickedCount(ImGuiMouseButton_Left);
if (clicks == 1) SingleClick();
else if (clicks == 2) DoubleClick();
else if (clicks == 3) TripleClick();

Mouse Position

GetMousePos

ImVec2 GetMousePos();

Get mouse position. Shortcut to ImGui::GetIO().MousePos.

Returns · ImVec2

Mouse position in screen coordinates

Example:

ImVec2 mouse_pos = ImGui::GetMousePos();
ImGui::Text("Mouse Position: (%.1f, %.1f)", mouse_pos.x, mouse_pos.y);

GetMousePosOnOpeningCurrentPopup

ImVec2 GetMousePosOnOpeningCurrentPopup();

Retrieve mouse position at the time of opening popup we have BeginPopup() into. Useful to avoid user backing that value themselves.

Returns · ImVec2

Mouse position when popup was opened

IsMousePosValid

bool IsMousePosValid(const ImVec2* mouse_pos = NULL);

Check if mouse position is valid. By convention, we use (-FLT_MAX, -FLT_MAX) to denote no mouse available.

mouse_pos · const ImVec2* · default: "NULL"

Mouse position to check (NULL = use current mouse position)

Returns · bool

True if position is valid

Mouse Dragging

IsMouseDragging

bool IsMouseDragging(ImGuiMouseButton button, float lock_threshold = -1.0f);

Check if mouse is dragging. Uses io.MouseDraggingThreshold if lock_threshold < 0.0f.

button · ImGuiMouseButton

Mouse button to check

lock_threshold · float · default: "-1.0f"

Distance threshold before considering dragging. Use -1.0f for default threshold.

Returns · bool

True if mouse is dragging

Example:

if (ImGui::IsMouseDragging(ImGuiMouseButton_Left))
{
    ImVec2 delta = ImGui::GetMouseDragDelta(ImGuiMouseButton_Left);
    ImGui::Text("Dragging: (%.1f, %.1f)", delta.x, delta.y);
}

GetMouseDragDelta

ImVec2 GetMouseDragDelta(ImGuiMouseButton button = 0, float lock_threshold = -1.0f);

Return the delta from the initial clicking position while the mouse button is pressed or was just released. This is locked and returns 0.0f until the mouse moves past a distance threshold at least once.

button · ImGuiMouseButton · default: "0"

Mouse button to check

lock_threshold · float · default: "-1.0f"

Distance threshold. Use -1.0f for io.MouseDraggingThreshold.

Returns · ImVec2

Drag delta in pixels

Example:

if (ImGui::IsMouseDragging(ImGuiMouseButton_Left))
{
    ImVec2 drag_delta = ImGui::GetMouseDragDelta(ImGuiMouseButton_Left);
    object_position.x += drag_delta.x;
    object_position.y += drag_delta.y;
    ImGui::ResetMouseDragDelta(ImGuiMouseButton_Left);
}

ResetMouseDragDelta

void ResetMouseDragDelta(ImGuiMouseButton button = 0);

Reset drag delta for a mouse button.

button · ImGuiMouseButton · default: "0"

Mouse button to reset

Mouse Hovering

IsMouseHoveringRect

bool IsMouseHoveringRect(const ImVec2& r_min, const ImVec2& r_max, bool clip = true);

Check if mouse is hovering given bounding rect in screen space. Clipped by current clipping settings, but disregarding of other consideration of focus/window ordering/popup-block.

r_min · const ImVec2&

Top-left corner of rectangle

r_max · const ImVec2&

Bottom-right corner of rectangle

clip · bool · default: "true"

Whether to respect current clipping rectangle

Returns · bool

True if mouse is within rectangle

Example:

ImVec2 min = ImVec2(100, 100);
ImVec2 max = ImVec2(200, 200);
if (ImGui::IsMouseHoveringRect(min, max))
{
    ImGui::GetWindowDrawList()->AddRectFilled(min, max, IM_COL32(255, 0, 0, 64));
}

Mouse Cursor

GetMouseCursor

ImGuiMouseCursor GetMouseCursor();

Get desired mouse cursor shape. Important: reset in ImGui::NewFrame(), updated during the frame. Valid before Render().

Returns · ImGuiMouseCursor

Cursor type

SetMouseCursor

void SetMouseCursor(ImGuiMouseCursor cursor_type);

Set desired mouse cursor shape.

cursor_type · ImGuiMouseCursor

Cursor type to set

Example:

if (IsItemHovered())
{
    ImGui::SetMouseCursor(ImGuiMouseCursor_Hand);
}

Mouse Cursor Types

enum ImGuiMouseCursor_
{
    ImGuiMouseCursor_None = -1,
    ImGuiMouseCursor_Arrow = 0,         // Standard arrow
    ImGuiMouseCursor_TextInput,         // When hovering over InputText, etc.
    ImGuiMouseCursor_ResizeAll,         // Unused by ImGui
    ImGuiMouseCursor_ResizeNS,          // When hovering horizontal border
    ImGuiMouseCursor_ResizeEW,          // When hovering vertical border
    ImGuiMouseCursor_ResizeNESW,        // When hovering bottom-left corner
    ImGuiMouseCursor_ResizeNWSE,        // When hovering bottom-right corner
    ImGuiMouseCursor_Hand,              // Unused by ImGui (e.g., for hyperlinks)
    ImGuiMouseCursor_Wait,              // When waiting for something to process/load
    ImGuiMouseCursor_Progress,          // When waiting but application still interactive
    ImGuiMouseCursor_NotAllowed,        // When hovering disallowed interaction
    ImGuiMouseCursor_COUNT
};

Mouse Button Enum

enum ImGuiMouseButton_
{
    ImGuiMouseButton_Left = 0,
    ImGuiMouseButton_Right = 1,
    ImGuiMouseButton_Middle = 2,
    ImGuiMouseButton_COUNT = 5
};

These values are guaranteed to be stable. You can use 0/1 directly.

Mouse Capture

SetNextFrameWantCaptureMouse

void SetNextFrameWantCaptureMouse(bool want_capture_mouse);

Override io.WantCaptureMouse flag next frame. Equivalent to setting io.WantCaptureMouse after the next NewFrame() call.

want_capture_mouse · bool

Whether to capture mouse

Common Patterns

Custom Drag Widget

ImGui::InvisibleButton("drag_area", ImVec2(200, 200));
if (ImGui::IsItemActive() && ImGui::IsMouseDragging(ImGuiMouseButton_Left))
{
    ImVec2 drag_delta = ImGui::GetMouseDragDelta(ImGuiMouseButton_Left);
    object_pos.x += drag_delta.x;
    object_pos.y += drag_delta.y;
    ImGui::ResetMouseDragDelta(ImGuiMouseButton_Left);
}

Click Detection with Double-Click

if (ImGui::IsItemClicked())
{
    if (ImGui::IsMouseDoubleClicked(ImGuiMouseButton_Left))
        OpenItem();
    else
        SelectItem();
}

Custom Context Menu

if (ImGui::IsMouseClicked(ImGuiMouseButton_Right) && 
    ImGui::IsMouseHoveringRect(item_min, item_max))
{
    ImGui::OpenPopup("context_menu");
}

See Also

• Keyboard - Keyboard input functions
• Input - General input and ImGuiIO functions
• Shortcuts - Keyboard shortcuts