QWindowKit Documentation

To use QWindowKit in QML, you must first register the QWindowKit types in your C++ main.cpp and ensure the window supports transparency.

Setup Steps:

1. In main.cpp, call QQuickWindow::setDefaultAlphaBuffer(true) before creating any windows. This is required for transparency and platform effects like Mica or Acrylic.
2. Call QWK::registerTypes(&engine) after creating your QQmlApplicationEngine.
3. In QML, import QWindowKit 1.0 and use the WindowAgent component.

Usage Pattern: Inside a Component.onCompleted block in your QML file, initialize the agent:

WindowAgent {
    id: windowAgent
}

Component.onCompleted: {
    windowAgent.setup(window)
    windowAgent.setTitleBar(titleBar)
    windowAgent.setSystemButton(WindowAgent.Minimize, minButton)
    windowAgent.setSystemButton(WindowAgent.Maximize, maxButton)
    windowAgent.setSystemButton(WindowAgent.Close, closeButton)
}

Interaction: Just like in Widgets, if a control in the title bar (like a Button) needs mouse input, you must call windowAgent.setHitTestVisible(controlId, true) within Component.onCompleted or a similar lifecycle event.

// main.cpp setup
QQuickWindow::setDefaultAlphaBuffer(true);
QQmlApplicationEngine engine;
QWK::registerTypes(&engine);

// Main.qml usage
import QWindowKit 1.0

Window {
    id: window
    WindowAgent {
        id: windowAgent
    }
    
    Rectangle {
        id: titleBar
        // ...
    }

    Component.onCompleted: {
        windowAgent.setup(window)
        windowAgent.setTitleBar(titleBar)
    }
}

To ensure stability and correct behavior, follow these guidelines:

• Setup Timing: Call setup() as early as possible, typically in the first half of the top-level window's constructor. Set size constraints (min/max/fixed) after QWindowKit initialization.
• Do Not Modify Flags: Once WidgetWindowAgent::setup() is called, do not modify the window flags using QWidget::setWindowFlags().
• Avoid Runtime Border Switching: Do not attempt to switch between custom and native system borders at runtime. If switching is required, destroy and recreate the window.
• Native Sub-widgets: If a child widget uses Qt::WA_NativeWindow, enable Qt::WA_DontCreateNativeAncestors before creating the native ancestor window.
• Size Constraints: Avoid setting maximum width or height constraints on windows that are also set to be maximized, as this can interfere with Qt's reporting of native maximized geometry.
• Qt Quick (Windows 10/D3D): For Qt Quick using D3D11/D3D12 on Windows 10, a white line may appear at the top. In Qt 6.7+, you can try setting the environment variable QT_QPA_DISABLE_REDIRECTION_SURFACE=1 before creating QCoreApplication (do not use this with OpenGL or Vulkan).

To use custom title bars in a QWidget or QMainWindow application, follow these requirements:

1. Global Attribute: You MUST set QCoreApplication::setAttribute(Qt::AA_DontCreateNativeWidgetSiblings) before creating the QApplication instance.
2. Agent Lifecycle: Every top-level window requires its own QWK::WidgetWindowAgent. Call m_windowAgent->setup(this) as early as possible in the window's lifecycle.
3. Title Bar Definition: Use setTitleBar(widget) to designate the area that handles window dragging.
4. Hit Testing: By default, the title bar area intercepts mouse events for dragging. If you place interactive controls (like QMenuBar, QPushButton, or QLineEdit) inside the title bar, you MUST call setHitTestVisible(widget, true) on them so they can receive clicks.
5. System Buttons: Use setSystemButton(role, widget) to associate your custom buttons with system actions (Minimize, Maximize, Close, etc.). Note that QWindowKit only identifies the role; you must still manually connect the button's clicked signal to the window's corresponding slot (e.g., showMinimized()).

// In your MainWindow setup
m_windowAgent = new QWK::WidgetWindowAgent(this);
m_windowAgent->setup(this);

// Define title bar and buttons
m_windowAgent->setTitleBar(titleBar);
m_windowAgent->setSystemButton(QWK::WindowAgentBase::Minimize, minButton);

// IMPORTANT: Make interactive controls clickable
m_windowAgent->setHitTestVisible(menuBar, true);

To use custom title bars in a Qt Quick application:

1. Register Types: In your C++ main function, call QWK::registerTypes(&engine) after creating the QQmlApplicationEngine.
2. Set Alpha Buffer: Call QQuickWindow::setDefaultAlphaBuffer(true) before creating the QGuiApplication.
3. Use WindowAgent in QML: Import QWindowKit 1.0 and use the WindowAgent component inside your Window.
4. Initialize Agent: In the Component.onCompleted handler of your QML window, call windowAgent.setup(window) and windowAgent.setTitleBar(titleBar).

// C++ Setup
QQuickWindow::setDefaultAlphaBuffer(true);
QGuiApplication app(argc, argv);
QQmlApplicationEngine engine;
QWK::registerTypes(&engine);
engine.load(QUrl(QStringLiteral("qrc:/Main.qml")));
app.exec();

// QML Usage
import QtQuick
import QtQuick.Window
import QWindowKit 1.0

Window {
    id: window
    visible: false

    WindowAgent {
        id: windowAgent
    }

    Rectangle {
        id: titleBar
        height: 40
        width: parent.width
    }

    Component.onCompleted: {
        windowAgent.setup(window)
        windowAgent.setTitleBar(titleBar)
        window.visible = true
    }
}

To build QWindowKit, clone the repository recursively and use CMake. You must provide the path to your Qt installation via CMAKE_PREFIX_PATH.

On Windows:

git clone --recursive https://github.com/stdware/qwindowkit
cd qwindowkit

cmake -S . -B build ^
  -DCMAKE_PREFIX_PATH=C:/Qt/6.7.3/msvc2019_64 ^
  -DCMAKE_INSTALL_PREFIX=C:/Libraries/QWindowKit ^
  -DQWINDOWKIT_BUILD_WIDGETS=ON ^
  -DQWINDOWKIT_BUILD_QUICK=ON ^
  -DQWINDOWKIT_BUILD_EXAMPLES=OFF

cmake --build build --config Release
cmake --install build --config Release

On Linux or macOS:

git clone --recursive https://github.com/stdware/qwindowkit
cd qwindowkit

cmake -S . -B build \
  -DCMAKE_PREFIX_PATH=/path/to/Qt \
  -DCMAKE_INSTALL_PREFIX=/opt/qwindowkit \
  -DQWINDOWKIT_BUILD_WIDGETS=ON \
  -DQWINDOWKIT_BUILD_QUICK=ON

cmake --build build --config Release
cmake --install build --config Release

# Windows example
cmake -S . -B build \
  -DCMAKE_PREFIX_PATH=C:/Qt/6.7.3/msvc2019_64 \
  -DCMAKE_INSTALL_PREFIX=C:/Libraries/QWindowKit \
  -DQWINDOWKIT_BUILD_WIDGETS=ON \
  -DQWINDOWKIT_BUILD_QUICK=ON \
  -DQWINDOWKIT_BUILD_EXAMPLES=OFF

cmake --build build --config Release
cmake --install build --config Release