AWindow#

Represents a window in the underlying windowing system.

Header:	`#include <AUI/Platform/AWindow.h>`
CMake:	`aui_link(my_target PUBLIC aui::views)`

Detailed Description#

This document covers AUI's window management system, which provides cross‑platform window creation, lifecycle management, and event handling. The system abstracts native windowing APIs across Windows, Linux, macOS, Android, and iOS platforms while maintaining a unified interface for application developers.

AWindow is the concrete implementation of a UI surface that is backed by a native window. It inherits from ASurface – the generic surface API that can be used by other windowing API implementations (i.e., SDL3 or a game engine).

AWindow owns an IRenderingContext instance. The context bridges the window to the shared IRenderer – the actual rendering engine. The renderer performs all drawing primitives and is shared across all windows. The context handles platform‑specific tasks such as buffer swapping, resizing, and screenshot capture.

graph TD
%%{init: {'theme': 'default'}}%%
classDef platformSpec fill:none,stroke:#888,stroke-width:2,stroke-dasharray:5,5;

%% Sub‑graph definition (use an ID without spaces)
subgraph PlatformSpecifics
    AWindow1(AWindow) -->|has| IRenderingContext1(IRenderingContext)
    AWindow2(AWindow) -->|has| IRenderingContext2(IRenderingContext)
    AWindow3(AWindow) -->|has| IRenderingContext3(IRenderingContext)
end

%% Apply the class to the sub‑graph
class PlatformSpecifics platformSpec

%% Connections to the renderer
IRenderingContext1 -->|uses| IRenderer
IRenderingContext2 -->|uses| IRenderer
IRenderingContext3 -->|uses| IRenderer

For more details on the rendering, see Rendering Engine.

Examples#

examples/7guis/cells/src/main.cpp

7GUIs Cells — Spreadsheet processor (Excel).

private:
    _<State> mState;
};

class CellsWindow : public AWindow {
public:
    CellsWindow() : AWindow("AUI - 7GUIs - Cells", 500_dp, 400_dp) {
        setContents(Centered {
          AScrollArea::Builder()
                  .withContents(Horizontal { _new<CellsView>(_new<State>()) })

examples/7guis/flight_booker/src/main.cpp

7GUIs Flight Booker — Flight Booker.

    // Create state instance
    _<State> state = _new<State>();

    // Create window
    auto window = _new<AWindow>("AUI - 7GUIs - Book Flight", 150_dp, 50_dp);

    // Set contents
    window->setContents(Centered {
      Vertical {
        _new<ADropdownList>(AListModel<AString>::make({ "one-way flight", "return flight" })) AUI_LET {

examples/7guis/circle_drawer/src/main.cpp

7GUIs Circle Drawer — Undo, redo, dialog control.

            {
              .name = "Adjust radius...",
              .onAction =
                  [this, circle] {
                      auto radiusPopup = _new<AWindow>(
                          "", 200_dp, 50_dp, dynamic_cast<AWindow*>(ASurface::current()), WindowStyle::MODAL);
                      radiusPopup->setContents(Vertical {
                        Label { "Adjust diameter of circle at {}."_format(circle->position) },
                        Slider {
                          .value = AUI_REACT(circle->radius / MAX_RADIUS),

examples/7guis/timer/src/main.cpp

7GUIs Timer — Timer example.

static constexpr high_resolution_clock::duration MAX_DURATION = 60s;

/// [example]
class TimerWindow : public AWindow {
public:
    TimerWindow() : AWindow("AUI - 7GUIs - Timer", 300_dp, 50_dp) {
        setContents(Centered {
          Vertical::Expanding {
            Horizontal {

examples/7guis/crud/src/main.cpp

7GUIs CRUD — Create/Read/Update/Delete example.

    AProperty<AString> surname;
    APropertyPrecomputed<AString> displayName = [this] { return "{}, {}"_format(name, surname); };
};

class CRUDWindow: public AWindow {
public:
    CRUDWindow(): AWindow("AUI - 7GUIs - CRUD", 300_dp, 200_dp) {
        setExtraStylesheet(AStylesheet {
          {
            c("selected"),

examples/7guis/counter/src/main.cpp

7GUIs Counter — Simple counter.

using namespace declarative;

/// [counter]
class CounterWindow : public AWindow {
public:
    CounterWindow() : AWindow("AUI - 7GUIs - Counter", 200_dp, 100_dp) {
        setContents(Centered {
          Horizontal {
            Label { AUI_REACT("Count: {}"_format(mCounter)) },

examples/7guis/temperature_converter/src/main.cpp

7GUIs Temperature Converter — Fahrenheit to Celsius and vice versa.

    };
}

/// [window]
class TemperatureConverterWindow : public AWindow {
public:
    TemperatureConverterWindow() : AWindow("AUI - 7GUIs - TempConv", 300_dp, 50_dp) {
        setContents(Centered {
          Horizontal {
            myPicker() AUI_LET {

examples/app/minesweeper/src/MinesweeperWindow.cpp

Minesweeper Game — Minesweeper game implementation driven by ass.

#include "AUI/Util/ARandom.h"

using namespace declarative;

MinesweeperWindow::MinesweeperWindow() : AWindow("Minesweeper", 100_dp, 100_dp) {
    setContents(Vertical {
      Horizontal {
        Centered::Expanding {
          _new<AButton>("New game...").connect(&AButton::clicked, me::newGame),
        },

examples/app/fractal/src/JumpToCoordsWindow.h

Fractal Example — Fractal viewer application demonstrating usage of custom shaders.

#include <AUI/Platform/AWindow.h>
#include "FractalView.h"

class JumpToCoordsWindow : public AWindow {
public:
    explicit JumpToCoordsWindow(_<FractalView> fractalView, AWindow* parent);
};

examples/app/game_of_life/src/main.cpp

Game of Life — Game of Life implementation that uses advanced large dynamic data rendering techniques such as ITexture, AImage to be GPU friendly. The computation is performed in AThreadPool.

        redraw();
    }
}; /// end

class GameOfLifeWindow : public AWindow {
public:
    GameOfLifeWindow() : AWindow("Game of Life") {
        setContents(Vertical {
          Centered {
            Horizontal {

examples/app/notes/src/main.cpp

Notes App — Note taking app that demonstrates usage of AListModel, AProperty, user data saving and loading.

        });
}
/// [noteEditor]

class MainWindow : public AWindow {
public:
    MainWindow() : AWindow("Notes") {
        setExtraStylesheet(AStylesheet {
          {
            c(".plain_bg"),

examples/ui/minimal_ui_assets_xmake/src/MainWindow.h

Minimal UI Template XMake with Assets — Minimal UI boilerplate template XMake with AUI Assets.

#pragma once

#include <AUI/Platform/AWindow.h>

class MainWindow: public AWindow {
public:
    MainWindow();
};

examples/ui/minimal_ui_xmake/src/MainWindow.h

Minimal UI Template XMake — Minimal UI boilerplate template XMake.

#pragma once

#include <AUI/Platform/AWindow.h>

class MainWindow: public AWindow {
public:
    MainWindow();
};

examples/ui/contacts/src/main.cpp

AUI Contacts — Usage of AUI_DECLARATIVE_FOR to make a contacts-like application.

static AChar groupLetter(const AString& s) {
    return s.empty() ? AChar(U'_') : s.utf8().first();
}

class ContactsWindow : public AWindow {
public:
    ContactsWindow() : AWindow("AUI Contacts", 600_dp, 300_dp) {
        setContents(
            Horizontal {
              AScrollArea::Builder()

examples/ui/backdrop/src/main.cpp

Backdrop — Backdrop effects demo.

    return result;
}

AUI_ENTRY {
    auto window = _new<AWindow>("Backdrop test", 600_dp, 300_dp);

    window->setContents(headerWithContents(
        Centered {
          Vertical::Expanding {
            Centered {

examples/ui/opengl_simple/src/main.cpp

OpenGL Example — Demonstrates how to integrate custom OpenGL rendering with AUI Framework.

        },
        .flags = ARenderContextFlags::NO_SMOOTH | ARenderContextFlags::NO_VSYNC,
    });

    auto window = _new<AWindow>("OpenGL Demo", 600_dp, 300_dp);
    auto state = _new<State>();
    window->setContents(
        Stacked {
          _new<MyRenderer>(state) AUI_OVERRIDE_STYLE { Expanding() },
          Horizontal::Expanding {

examples/ui/infinite_lazy_list/src/main.cpp

Infinite Lazy List — Usage of AUI_DECLARATIVE_FOR to make an infinite lazy list.

    };
}

AUI_ENTRY {
    auto window = _new<AWindow>("Infinite Lazy List", 200_dp, 300_dp);
    window->setContents(Stacked { AScrollArea::Builder().withContents(myLazyList(_new<State>())) });
    window->show();

    return 0;
}

examples/ui/embedded_sdl/src/main.cpp

SDL3 — This code demonstrates how to integrate the AUI Framework with SDL3 to create a window with OpenGL rendering.

        return SDL_GetClipboardText();
    }

    AMessageBox::ResultButton messageBoxShow(
        AWindow* parent, const AString& title, const AString& message, AMessageBox::Icon icon,
        AMessageBox::Button b) override {}
};

/// [EmbedRenderingContext]
struct EmbedRenderingContext : IRenderingContext {

examples/app/minesweeper/src/NewGameWindow.h

Minesweeper Game — Minesweeper game implementation driven by ass.

#include "AUI/Platform/AWindow.h"
#include "AUI/View/ANumberPicker.h"
#include "AUI/View/ALabel.h"

class NewGameWindow : public AWindow {
public:
    NewGameWindow(MinesweeperWindow* minesweeper);

private:
    MinesweeperWindow* mMinesweeper;

examples/app/minesweeper/src/NewGameWindow.cpp

Minesweeper Game — Minesweeper game implementation driven by ass.

    mDifficultyLabel->setText(text);
}

NewGameWindow::NewGameWindow(MinesweeperWindow* minesweeper)
  : AWindow("New game", 100, 100, minesweeper), mMinesweeper(minesweeper) {
    setWindowStyle(WindowStyle::MODAL);

    setLayout(std::make_unique<AVerticalLayout>());
    setContents(Vertical {
      _form({

examples/app/fractal/src/FractalWindow.cpp

Fractal Example — Fractal viewer application demonstrating usage of custom shaders.

using namespace ass;
using namespace declarative;

FractalWindow::FractalWindow() : AWindow("Mandelbrot set") {
    setLayout(std::make_unique<AHorizontalLayout>());

    auto centerPosDisplay = _new<ALabel>("-");
    {
        centerPosDisplay->setCustomStyle({

examples/app/fractal/src/JumpToCoordsWindow.cpp

Fractal Example — Fractal viewer application demonstrating usage of custom shaders.

#include <AUI/Platform/AMessageBox.h>

using namespace declarative;

JumpToCoordsWindow::JumpToCoordsWindow(_<FractalView> fractalView, AWindow* parent)
  : AWindow("Jump to coords", 854_dp, 500_dp, parent, WindowStyle::NO_RESIZE) {
    auto re = _new<ATextField>();
    auto im = _new<ATextField>();
    auto scale = _new<ATextField>();

examples/app/fractal/src/FractalWindow.h

Fractal Example — Fractal viewer application demonstrating usage of custom shaders.

#pragma once

#include <AUI/Platform/AWindow.h>

class FractalWindow : public AWindow {
public:
    FractalWindow();
};

examples/ui/minimal_ui_assets_xmake/src/MainWindow.cpp

Minimal UI Template XMake with Assets — Minimal UI boilerplate template XMake with AUI Assets.

#include <AUI/View/ADrawableView.h>

using namespace declarative;

MainWindow::MainWindow(): AWindow("Project template app", 300_dp, 200_dp) {
    setContents(
        Centered{
            Vertical{
                Centered { Icon { ":img/logo.svg" } AUI_OVERRIDE_STYLE { FixedSize(64_dp) } },
                Centered { Label { "Hello world from AUI!" } },

examples/ui/minimal_ui_xmake/src/MainWindow.cpp

Minimal UI Template XMake — Minimal UI boilerplate template XMake.

#include <AUI/Platform/APlatform.h>

using namespace declarative;

MainWindow::MainWindow(): AWindow("Project template app", 300_dp, 200_dp) {
    setContents(
        Centered{
            Vertical{
                Centered { Label { "Hello world from AUI!" } },
                _new<AButton>("Visit GitHub repo").connect(&AView::clicked, this, [] {

examples/ui/contacts/src/view/ContactDetailsView.cpp

AUI Contacts — Usage of AUI_DECLARATIVE_FOR to make a contacts-like application.

        return;
    }

    // discard
    if (AMessageBox::show(dynamic_cast<AWindow*>(ASurface::current()), "Do you really want to discard?", "This action is irreversible!", AMessageBox::Icon::NONE, AMessageBox::Button::YES_NO) != AMessageBox::ResultButton::YES) {
        return;
    }
    mContact = mOriginalContact;
    mEditorMode = false;
}

examples/ui/views/src/ExampleWindow.cpp

Views Example — All-in-one views building example.

    t->setLayout(std::make_unique<AStackedLayout>());
    t->addView(_new<ALabel>("Window contents"));
}

class AllViewsWindow : public AWindow {
public:
    AllViewsWindow() : AWindow("All views", 300_dp, 500_dp, nullptr, WindowStyle::MODAL) {
        setContents(Centered {
          AScrollArea::Builder()
              .withContents(

Public fields and Signals#

mFocusNextViewOnTab#

bool mFocusNextViewOnTab

defines if the next view must be focused on tab button pressed

maximized#

emits<> maximized

Window is maximized.

minimized#

emits<> minimized

Window is minimized (hidden to the taskbar, iconified).

moving#

emits<glm::vec2> moving

Window is moving.

client area position.

restored#

emits<> restored

Window is restored (shown from the taskbar, deiconified).

Public Methods#

constructor#

AWindow::AWindow(std::nullptr_t)

Constructor for custom initialization logic

Please call windowNativePreInit

Examples:

examples/ui/views/src/ExampleWindow.h

Views Example — All-in-one views building example.

#include "AUI/Thread/AAsyncHolder.h"

class API_AUI_AUDIO IAudioPlayer;

class ExampleWindow: public AWindow {
public:
    ExampleWindow();

    void onDragDrop(const ADragNDrop::DropEvent& event) override;

examples/app/minesweeper/src/MinesweeperWindow.h

Minesweeper Game — Minesweeper game implementation driven by ass.

#include "FieldCell.h"
#include "AUI/Platform/ACustomCaptionWindow.h"
#include "CellView.h"

class MinesweeperWindow : public AWindow {
public:
    void beginGame(int columns, int rows, int bombs);
    MinesweeperWindow();

    [[nodiscard]]

activate#

void AWindow::activate(const AString& activationToken = { })

Shows the window, restores it if minimized and brings it to foreground.

Arguments: activationToken
platform-specific focus stealing permission token (see AActivation::activationToken).

Typical usage is handling AApplication::activated:

connect(AApplication::inst().activated, [window](const AActivation& a) { window->activate(a.activationToken); });

allowDragNDrop#

void AWindow::allowDragNDrop()

Enables drag-n-drop for this window.

Examples:

getMinimumSize#

glm::ivec2 AWindow::getMinimumSize()

The smallest size this window can be resized to.

In contrast to AView::getMinSize, which is the explicitly styled minimum, this one is measured from the window's contents: a window is never smaller than the space its contents need at their narrowest, so its layout is never squeezed into nothing. The styled minimum is respected as well, and the result is capped by AWindow::MAX_MIN_SIZE.

hide#

void AWindow::hide()

Hides the window without closing it.

A hidden window is still alive: it is counted as an open window, so it keeps the application running (see AApplication::quitOnLastWindowClosed). Use AWindow::close to destroy it.

A hidden window is not visible anywhere, including the taskbar.

isMaximized#

bool AWindow::isMaximized()

Returns: true if window maximized (fullscreen)

isMinimized#

bool AWindow::isMinimized()

Returns: true if window minimized (hidden in taskbar, iconified)

isRedrawWillBeEfficient#

static bool AWindow::isRedrawWillBeEfficient()

Checks whether last monitor frame is displayed and redraw will be efficient. If some object often updates UI thread for displaying some data it may cause extra CPU and GPU overload. AUI throttles window redraws and FPS does not go above 60 FPS but UI views may also cause extra CPU and GPU overload that does not have visual difference.

Returns: true if 16 milliseconds elapsed since last frame

mapPosition#

glm::ivec2 AWindow::mapPosition(const glm::ivec2& position)

Translates coordinates from the monitor's coordinate space to the coordinate space of this window.

Arguments: position
the coordinate in screen space
Returns: coordinates in the space of this window

mapPositionTo#

glm::ivec2 AWindow::mapPositionTo(const glm::ivec2& position, _<AWindow> other)

Translates coordinates from the coordinate space of this window to the coordinate space of another window.

Arguments: position
coordinates in the space of this window

other
other window
Returns: coordinates in the space of the other window

maximize#

void AWindow::maximize()

Maximizes window (makes window fullscreen)

minimize#

void AWindow::minimize()

Minimizes window (hide window to the taskbar, iconifies)

moveToCenter#

void AWindow::moveToCenter()

Moves the window to the center of monitor.

When using in series with setSize(), do the setSize() first, when moveToCenter().

quit#

void AWindow::quit()

Removes window from AWindowManager.

restore#

void AWindow::restore()

Restores window (shows window from taskbar)

setMobileScreenOrientation#

void AWindow::setMobileScreenOrientation(AScreenOrientation screenOrientation)

Controls mobile device's screen orientation when this window is on the foreground.

Affects only mobile OSes. On window-based interfaces (desktop) does nothing.

show#

void AWindow::show()

Shows the window.

Behavior under UI tests: Does not actually shows the window and don't even needed in graphics environment.

Examples:

examples/app/minesweeper/src/main.cpp

Minesweeper Game — Minesweeper game implementation driven by ass.

#include <AUI/Platform/Entry.h>
#include "MinesweeperWindow.h"

AUI_ENTRY {
    _new<MinesweeperWindow>()->show();

    return 0;
}

examples/app/fractal/src/main.cpp

Fractal Example — Fractal viewer application demonstrating usage of custom shaders.

#include <AUI/Platform/Entry.h>
#include "FractalWindow.h"

AUI_ENTRY {
    _new<FractalWindow>()->show();
    return 0;
}

examples/ui/minimal_ui_assets_xmake/src/main.cpp

Minimal UI Template XMake with Assets — Minimal UI boilerplate template XMake with AUI Assets.

#include <AUI/Platform/Entry.h>
#include "MainWindow.h"

AUI_ENTRY {
    _new<MainWindow>()->show();
    return 0;
};

examples/ui/minimal_ui_xmake/src/main.cpp

Minimal UI Template XMake — Minimal UI boilerplate template XMake.

#include <AUI/Platform/Entry.h>
#include "MainWindow.h"

AUI_ENTRY {
    _new<MainWindow>()->show();
    return 0;
};

examples/ui/views/tests/LayoutManagerTest.cpp

Views Example — All-in-one views building example.

public:
protected:
    void SetUp() override {
        UITest::SetUp();
        _new<ExampleWindow>()->show();
    }

    void TearDown() override {
        UITest::TearDown();
    }

examples/ui/views/src/main.cpp

Views Example — All-in-one views building example.

#include "ExampleWindow.h"
#include <AUI/Platform/Entry.h>

AUI_ENTRY {
    _new<ExampleWindow>()->show();
    return 0;
}

unmapPosition#

glm::ivec2 AWindow::unmapPosition(const glm::ivec2& position)

Translates coordinates from the coordinate space of this window to the coordinate space of the monitor.

Arguments: position
coordinates in the space of this window
Returns: the coordinates in space of the monitor

wrapViewToWindow#

static _<AWindow> AWindow::wrapViewToWindow(const _<AView>& view, const AString& title, int width = 854 _dp, int height = 500 _dp, AWindow* parent = nullptr, WindowStyle ws = WindowStyle::DEFAULT)

Wraps your AView to window.

Arguments: view
view to wrap

title
window title

width
window width

height
window height

parent
parent window

ws
window style flags
Returns: created window, AWindow::show() is not called