Window Utilities - Dear ImGui

Window utility functions allow you to query window properties, check focus and hover states, and manipulate window positioning, sizing, and scrolling.

Window State Queries

IsWindowFocused

Checks if the current window is focused.

bool IsWindowFocused(ImGuiFocusedFlags flags = 0);

Parameters

flags

ImGuiFocusedFlags

default:"0"

Flags to modify the focus check behavior. Common flags:

ImGuiFocusedFlags_ChildWindows - Check child windows too
ImGuiFocusedFlags_RootWindow - Check root window instead
ImGuiFocusedFlags_AnyWindow - Return true if any window is focused

Returns

return

bool

True if the current window (or specified scope) is focused.

Example

ImGui::Begin("My Window");

if (ImGui::IsWindowFocused()) {
    ImGui::Text("This window has focus");
    // Handle keyboard shortcuts specific to this window
}

// Check if this window OR any of its children are focused
if (ImGui::IsWindowFocused(ImGuiFocusedFlags_ChildWindows)) {
    ImGui::Text("This window or a child has focus");
}

ImGui::End();

IsWindowHovered

Checks if the current window is hovered and hoverable.

bool IsWindowHovered(ImGuiHoveredFlags flags = 0);

Parameters

flags

ImGuiHoveredFlags

default:"0"

Flags to modify hover check behavior. Common flags:

ImGuiHoveredFlags_ChildWindows - Check child windows too
ImGuiHoveredFlags_RootWindow - Check root window instead
ImGuiHoveredFlags_AllowWhenBlockedByPopup - Return true even if blocked by popup
ImGuiHoveredFlags_AllowWhenBlockedByActiveItem - Return true even if blocked by active item

Returns

return

bool

True if the current window is hovered and hoverable (not blocked by popup/modal).

Example

ImGui::Begin("My Window");

if (ImGui::IsWindowHovered()) {
    ImGui::Text("Mouse is over this window");
    
    // Handle mouse wheel for custom scrolling
    float wheel = ImGui::GetIO().MouseWheel;
    if (wheel != 0.0f) {
        // Custom scroll handling
    }
}

ImGui::End();

If you want to check whether your mouse should be dispatched to ImGui or your application, do not use this function. Use io.WantCaptureMouse instead. See FAQ: “How can I tell whether to dispatch mouse/keyboard to Dear ImGui or my application?”

Window Position & Size Queries

GetWindowPos

Gets the current window position in screen space.

ImVec2 GetWindowPos();

Returns

return

ImVec2

Current window position in screen coordinates (pixels).

Example

ImGui::Begin("Window");

ImVec2 pos = ImGui::GetWindowPos();
ImGui::Text("Window at (%.0f, %.0f)", pos.x, pos.y);

ImGui::End();

It is unlikely you ever need to use this. Consider using GetCursorScreenPos() and GetContentRegionAvail() instead for layout purposes.

GetWindowSize

Gets the current window size.

ImVec2 GetWindowSize();

Returns

return

ImVec2

Current window size including decorations (title bar, borders, etc.).

Example

ImGui::Begin("Window");

ImVec2 size = ImGui::GetWindowSize();
ImGui::Text("Window size: %.0fx%.0f", size.x, size.y);

ImGui::End();

GetWindowWidth / GetWindowHeight

Gets the current window width or height.

float GetWindowWidth();
float GetWindowHeight();

Returns

return

float

Current window width or height in pixels.

Example

ImGui::Begin("Window");

float width = ImGui::GetWindowWidth();
float height = ImGui::GetWindowHeight();

ImGui::Text("Width: %.0f, Height: %.0f", width, height);

ImGui::End();

Window Manipulation

Prefer using SetNextXXX functions (before Begin()) rather than SetXXX functions (after Begin()). The SetNext functions are cleaner and avoid potential side effects.

SetNextWindowPos

Sets the next window position (call before Begin()).

void SetNextWindowPos(const ImVec2& pos, ImGuiCond cond = 0, const ImVec2& pivot = ImVec2(0, 0));

Parameters

pos

const ImVec2&

required

Position in screen coordinates.

cond

ImGuiCond

default:"0"

Condition for applying position:

0 or ImGuiCond_Always - Always apply
ImGuiCond_Once - Apply once per runtime session
ImGuiCond_FirstUseEver - Apply only on first use
ImGuiCond_Appearing - Apply when window appears

pivot

const ImVec2&

default:"ImVec2(0, 0)"

Pivot point: (0,0) = top-left, (0.5,0.5) = center, (1,1) = bottom-right.

Example

// Always position at top-left
ImGui::SetNextWindowPos(ImVec2(0, 0), ImGuiCond_Always);
ImGui::Begin("Fixed Position");

// Center on screen
ImGuiIO& io = ImGui::GetIO();
ImVec2 center(io.DisplaySize.x * 0.5f, io.DisplaySize.y * 0.5f);
ImGui::SetNextWindowPos(center, ImGuiCond_Appearing, ImVec2(0.5f, 0.5f));
ImGui::Begin("Centered");

// Bottom-right corner
ImVec2 br(io.DisplaySize.x, io.DisplaySize.y);
ImGui::SetNextWindowPos(br, ImGuiCond_Always, ImVec2(1.0f, 1.0f));
ImGui::Begin("Bottom Right");

SetNextWindowSize

Sets the next window size (call before Begin()).

void SetNextWindowSize(const ImVec2& size, ImGuiCond cond = 0);

Parameters

size

const ImVec2&

required

Window size. Set axis to 0.0f to force auto-fit on that axis.

cond

ImGuiCond

default:"0"

Condition for applying size.

Example

// Fixed size
ImGui::SetNextWindowSize(ImVec2(400, 300), ImGuiCond_Always);
ImGui::Begin("Fixed Size");

// Auto-fit width, fixed height
ImGui::SetNextWindowSize(ImVec2(0, 300));
ImGui::Begin("Auto Width");

SetNextWindowSizeConstraints

Sets the next window size constraints.

void SetNextWindowSizeConstraints(const ImVec2& size_min, const ImVec2& size_max, 
                                  ImGuiSizeCallback custom_callback = NULL, 
                                  void* custom_callback_data = NULL);

Parameters

size_min

const ImVec2&

required

Minimum size. Use 0.0f or FLT_MAX for no limit.

size_max

const ImVec2&

required

Maximum size. Use FLT_MAX for no limit. Use -1 for both min and max of same axis to preserve current size.

custom_callback

ImGuiSizeCallback

default:"NULL"

Optional callback for custom programmatic constraints.

custom_callback_data

void*

default:"NULL"

User data passed to the callback.

Example

// Minimum size 200x200, no maximum
ImGui::SetNextWindowSizeConstraints(ImVec2(200, 200), ImVec2(FLT_MAX, FLT_MAX));
ImGui::Begin("Constrained");

// Fixed aspect ratio (custom callback)
static auto AspectRatioCallback = [](ImGuiSizeCallbackData* data) {
    float aspect_ratio = *(float*)data->UserData;
    data->DesiredSize.y = data->DesiredSize.x / aspect_ratio;
};

static float aspect = 16.0f / 9.0f;
ImGui::SetNextWindowSizeConstraints(
    ImVec2(0, 0), ImVec2(FLT_MAX, FLT_MAX),
    AspectRatioCallback, &aspect);
ImGui::Begin("16:9 Aspect");

Window Scrolling

GetScrollX / GetScrollY

Gets the current scroll position.

float GetScrollX();
float GetScrollY();

Returns

return

float

Current scroll amount from 0 to GetScrollMaxX() or GetScrollMaxY().

Example

ImGui::Begin("Scrollable");

float scroll_y = ImGui::GetScrollY();
float scroll_max_y = ImGui::GetScrollMaxY();

ImGui::Text("Scroll: %.0f / %.0f", scroll_y, scroll_max_y);

// Show scroll percentage
if (scroll_max_y > 0) {
    float percent = (scroll_y / scroll_max_y) * 100.0f;
    ImGui::Text("%.0f%% scrolled", percent);
}

ImGui::End();

SetScrollX / SetScrollY

Sets the scroll position.

void SetScrollX(float scroll_x);
void SetScrollY(float scroll_y);

Parameters

scroll_x

float

required

Scroll amount from 0 to GetScrollMaxX().

scroll_y

float

required

Scroll amount from 0 to GetScrollMaxY().

Example

ImGui::Begin("Scrollable");

// Scroll to top button
if (ImGui::Button("Scroll to Top")) {
    ImGui::SetScrollY(0);
}

// Scroll to bottom button
if (ImGui::Button("Scroll to Bottom")) {
    ImGui::SetScrollY(ImGui::GetScrollMaxY());
}

// Scroll to middle
if (ImGui::Button("Scroll to Middle")) {
    ImGui::SetScrollY(ImGui::GetScrollMaxY() * 0.5f);
}

ImGui::End();

Changes to scroll will be applied at the beginning of the next frame in the first call to Begin(). You can use SetNextWindowScroll() before Begin() to avoid this one-frame delay.

SetScrollHereY

Adjusts scrolling to make the current cursor position visible.

void SetScrollHereY(float center_y_ratio = 0.5f);

Parameters

center_y_ratio

float

default:"0.5f"

Position ratio: 0.0 = top, 0.5 = center, 1.0 = bottom.

Example

ImGui::Begin("List");

static int selected = 0;

for (int i = 0; i < 100; i++) {
    if (ImGui::Selectable(fmt::format("Item {}", i).c_str(), selected == i)) {
        selected = i;
        // Scroll to make selected item visible in center
        ImGui::SetScrollHereY(0.5f);
    }
}

ImGui::End();

GetScrollMaxX / GetScrollMaxY

Gets the maximum scroll amount.

float GetScrollMaxX();
float GetScrollMaxY();

Returns

return

float

Maximum scroll amount ≈ ContentSize - WindowSize - DecorationsSize.

Example

ImGui::Begin("Window");

float max_scroll = ImGui::GetScrollMaxY();

if (max_scroll > 0) {
    ImGui::Text("Window is scrollable (max: %.0f)", max_scroll);
} else {
    ImGui::Text("Window content fits, no scrolling needed");
}

ImGui::End();

Complete Example: Scrollable Log

struct LogWindow {
    std::vector<std::string> lines;
    bool auto_scroll = true;
    
    void AddLog(const char* fmt, ...) {
        va_list args;
        va_start(args, fmt);
        char buf[1024];
        vsnprintf(buf, sizeof(buf), fmt, args);
        va_end(args);
        lines.push_back(buf);
    }
    
    void Draw(const char* title, bool* p_open = NULL) {
        ImGui::SetNextWindowSize(ImVec2(500, 400), ImGuiCond_FirstUseEver);
        if (!ImGui::Begin(title, p_open)) {
            ImGui::End();
            return;
        }
        
        // Options
        ImGui::Checkbox("Auto-scroll", &auto_scroll);
        ImGui::SameLine();
        if (ImGui::Button("Clear")) {
            lines.clear();
        }
        ImGui::SameLine();
        if (ImGui::Button("Add Test Line")) {
            AddLog("Test line %d", lines.size());
        }
        
        ImGui::Separator();
        
        // Log content
        ImGui::BeginChild("ScrollingRegion", ImVec2(0, 0), 
            ImGuiChildFlags_Borders, ImGuiWindowFlags_HorizontalScrollbar);
        
        for (const auto& line : lines) {
            ImGui::TextUnformatted(line.c_str());
        }
        
        // Auto-scroll to bottom
        if (auto_scroll && ImGui::GetScrollY() >= ImGui::GetScrollMaxY()) {
            ImGui::SetScrollHereY(1.0f);
        }
        
        ImGui::EndChild();
        ImGui::End();
    }
};

static LogWindow log_window;

// Usage
log_window.AddLog("Application started");
log_window.Draw("Log");

Core

Windows

Widgets

Layout

Drawing

Input & Navigation

Styling

Data Structures

​Window State Queries

​IsWindowFocused

​Parameters

​Returns

​Example

​IsWindowHovered

​Parameters

​Returns

​Example

​Window Position & Size Queries

​GetWindowPos

​Returns

​Example

​GetWindowSize

​Returns

​Example

​GetWindowWidth / GetWindowHeight

​Returns

​Example

​Window Manipulation

​SetNextWindowPos

​Parameters

​Example

​SetNextWindowSize

​Parameters

​Example

​SetNextWindowSizeConstraints

​Parameters

​Example

​Window Scrolling

​GetScrollX / GetScrollY

​Returns

​Example

​SetScrollX / SetScrollY

​Parameters

​Example

​SetScrollHereY

​Parameters

​Example

​GetScrollMaxX / GetScrollMaxY

​Returns

​Example

​Complete Example: Scrollable Log

Build docs developers (and LLMs) love

Window State Queries

IsWindowFocused

Parameters

Returns

Example

IsWindowHovered

Parameters

Returns

Example

Window Position & Size Queries

GetWindowPos

Returns

Example

GetWindowSize

Returns

Example

GetWindowWidth / GetWindowHeight

Returns

Example

Window Manipulation

SetNextWindowPos

Parameters

Example

SetNextWindowSize

Parameters

Example

SetNextWindowSizeConstraints

Parameters

Example

Window Scrolling

GetScrollX / GetScrollY

Returns

Example

SetScrollX / SetScrollY

Parameters

Example

SetScrollHereY

Parameters

Example

GetScrollMaxX / GetScrollMaxY

Returns

Example

Complete Example: Scrollable Log