Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ocornut/imgui/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
See also: