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();
Current cursor position in absolute screen coordinates
ImVec2 pos = ImGui::GetCursorScreenPos();
ImGui::GetWindowDrawList()->AddCircleFilled(pos, 10.0f, IM_COL32(255, 0, 0, 255));
SetCursorScreenPos
void SetCursorScreenPos(const ImVec2& pos);
New cursor position in absolute screen coordinates
ImVec2 pos = ImGui::GetCursorScreenPos();
ImGui::SetCursorScreenPos(ImVec2(pos.x + 100, pos.y + 50));
ImGui::Text("Offset text");
GetContentRegionAvail
ImVec2 GetContentRegionAvail();
Available space in current region
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
Get cursor position in window-local coordinates.
Cursor position in window-local coordinates
GetCursorPosX / GetCursorPosY
float GetCursorPosX();
float GetCursorPosY();
SetCursorPos
void SetCursorPos(const ImVec2& local_pos);
New cursor position in window-local coordinates
SetCursorPosX / SetCursorPosY
void SetCursorPosX(float local_x);
void SetCursorPosY(float local_y);
New X position in window-local coordinates
New Y position in window-local coordinates
GetCursorStartPos
ImVec2 GetCursorStartPos();
GetCursorScreenPos() after Begin() to get the absolute coordinates version.
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.