Cursor & Layout Positioning

Functions for controlling cursor position and layout flow in Dear ImGui

Overview

Dear ImGui uses a cursor-based layout system. The cursor represents the current output position where the next widget will be placed. Understanding cursor positioning is fundamental to creating custom layouts.

YOU CAN DO 99% OF WHAT YOU NEED WITH ONLY GetCursorScreenPos() and GetContentRegionAvail().

Coordinate Systems

Dear ImGui uses two coordinate systems:

• Absolute coordinates: GetCursorScreenPos(), SetCursorScreenPos(), all ImDrawList functions
• Window-local coordinates: GetCursorPos(), SetCursorPos(), GetCursorStartPos()

We currently have inconsistencies between window-local and absolute positions that will be addressed in future API updates. Prefer using absolute coordinates via GetCursorScreenPos().

Primary Cursor Functions

GetCursorScreenPos

ImVec2 GetCursorScreenPos();

Get cursor position in absolute screen coordinates. This is your best friend.

Returns · ImVec2

Current cursor position in absolute screen coordinates

Example:

ImVec2 pos = ImGui::GetCursorScreenPos();
ImGui::GetWindowDrawList()->AddCircleFilled(pos, 10.0f, IM_COL32(255, 0, 0, 255));

SetCursorScreenPos

void SetCursorScreenPos(const ImVec2& pos);

Set cursor position using absolute screen coordinates. This is your best friend.

pos · const ImVec2&

New cursor position in absolute screen coordinates

Example:

ImVec2 pos = ImGui::GetCursorScreenPos();
ImGui::SetCursorScreenPos(ImVec2(pos.x + 100, pos.y + 50));
ImGui::Text("Offset text");

GetContentRegionAvail

ImVec2 GetContentRegionAvail();

Get available space from current cursor position. This is your best friend.

Returns · ImVec2

Available space in current region

Example:

ImVec2 avail = ImGui::GetContentRegionAvail();
ImGui::Button("Full Width", ImVec2(avail.x, 0));

Window-Local Cursor Functions

These functions use window-local coordinates. Prefer using GetCursorScreenPos() instead.

GetCursorPos

ImVec2 GetCursorPos();

Get cursor position in window-local coordinates.

Returns · ImVec2

Cursor position in window-local coordinates

GetCursorPosX / GetCursorPosY

float GetCursorPosX();
float GetCursorPosY();

Get X or Y component of cursor position in window-local coordinates.

SetCursorPos

void SetCursorPos(const ImVec2& local_pos);

Set cursor position in window-local coordinates.

local_pos · const ImVec2&

New cursor position in window-local coordinates

SetCursorPosX / SetCursorPosY

void SetCursorPosX(float local_x);
void SetCursorPosY(float local_y);

Set X or Y component of cursor position in window-local coordinates.

local_x · float

New X position in window-local coordinates

local_y · float

New Y position in window-local coordinates

GetCursorStartPos

ImVec2 GetCursorStartPos();

Get initial cursor position in window-local coordinates. Call GetCursorScreenPos() after Begin() to get the absolute coordinates version.

Returns · ImVec2

Initial cursor position in window-local coordinates

Conversion

To convert between coordinate systems:

// Window-local to absolute
ImVec2 absolute = GetCursorPos() + GetWindowPos();

// Absolute to window-local
ImVec2 local = absolute - GetWindowPos();

GetWindowPos() is almost only ever useful to convert from window-local to absolute coordinates. Try not to use it.

Related Functions

See also:

• Spacing & Alignment for Indent(), Unindent(), Spacing(), Dummy()
• Columns & Groups for BeginGroup(), EndGroup()