The Window interface provides a bunch of utility functions to modify the state of your window. The class looks like this:

class Window
{
public:
    // Event Safety - begin, style, post-begin
    static void setTitle(String name) noexcept;

    // Event Safety - begin, style, post-begin
    static String getTitle() noexcept;

    // Event Safety - begin, style, post-begin
    static void setTitleSetting(String name) noexcept;

    // Event Safety - begin, style, post-begin
    static String getTitleSetting() noexcept;

    // Event Safety - begin, style, post-begin
    static void setIcon(String name) noexcept;

    // Event Safety - begin, style, post-begin
    static String getIconLocation() noexcept;

    // Event Safety - begin, style, post-begin
    static String getIconLocationSetting() noexcept;

    // Event Safety - begin, style, post-begin
    static void setIconLocationSetting(String location) noexcept;

    // Event Safety - begin, style, post-begin
    static float getAspectRatio() noexcept;

    // Event Safety - begin, style, post-begin
    static FVector2 getCurrentWindowPosition() noexcept;

    // Event Safety - begin, style, post-begin
    static FVector2 getLastWindowPosition() noexcept;

    // Event Safety - begin, style, post-begin
    static FVector2 getWindowPositionChange() noexcept;

    // Event Safety - begin, style, post-begin
    static void setCurrentWindowPosition(FVector2 pos) noexcept;

    // Event Safety - begin, style, post-begin
    static void pushWindowPositionChangeCallback(const TFunction<void(FVector2)>& f) noexcept;

    // Event Safety - begin, style, post-begin
    static FVector2 getWindowSize() noexcept;

    // Event Safety - begin, style, post-begin
    static FVector2& getWindowSizeSetting() noexcept;

    // Event Safety - begin, style, post-begin
    static bool getWindowFullscreen() noexcept;

    // Event Safety - begin, style, post-begin
    static bool& getWindowFullscreenSetting() noexcept;

    // Event Safety - begin, style, post-begin
    static void setWindowFullscreen(bool bFullscreen) noexcept;

    // Event Safety - begin, style, post-begin
    static void saveSettings(bool bSaveKeybinds) noexcept;

    // Event Safety - post-style, post-begin
    static void refreshSettings() noexcept;

    // Event Safety - begin, style, post-begin
    static void close() noexcept;
    
    // Event Safety - begin, style, post-begin
    static void pushWindowCloseCallback(const TFunction<void(void)>& f) noexcept;
    
    class Platform
    {
    public:
        // Event Safety - begin, style, post-begin
        // Available for GLFW platforms - X11, Win32, macOS
        static void setWindowAlwaysOnTop() noexcept;

        // Event Safety - begin, style, post-begin
        // Available for GLFW platforms - X11, Win32, macOS
        static void setWindowAlwaysOnBottom() noexcept;

        // Event Safety - begin, style, post-begin
        // GLFW Platform note: On Win32 "setWindowShowingOnPager" and "setWindowShowingOnTaskbar" run the same code,
        // as it is not possible to disable the window from showing on both the taskbar and window switcher
        // Available for GLFW platforms - X11, Win32
        static void setWindowShowingOnPager(bool bShowInPager) noexcept;

        // Event Safety - begin, style, post-begin
        // Available for GLFW platforms - X11, Win32
        static bool getWindowShowingOnPager() noexcept;

        // Event Safety - begin, style, post-begin
        // Available for GLFW platforms - X11, Win32
        static void setWindowShowingOnTaskbar(bool bShowOnTaskbar) noexcept;

        // Event Safety - begin, style, post-begin
        // Available for GLFW platforms - X11, Win32
        static bool getWindowShowingOnTaskbar() noexcept;

        // Event Safety - begin, style, post-begin
        // Available for GLFW platforms - X11
        // Sets the X11 window type
        static void setWindowType(String type) noexcept;

        // Event Safety - begin, style, post-begin
        // Available for GLFW platforms - X11, Win32, macOS
        // Returns the window ID as a size_t. On macOS this is the integer representation of the window pointer
        static size_t getWindowID() noexcept;

        // Event Safety - begin, style, post-begin
        // Available for GLFW platforms - Win32, macOS, Emscripten, X11 & Wayland
        // Returns the native window handle as a void*
        static void* getNativeWindowHandle() noexcept;

        // Event Safety - begin, style, post-begin
        // Available for GLFW platforms - Win32, macOS, Emscripten, X11 & Wayland
        // Returns the native window handle as a void*
        static WindowPlatform getCurrentWindowPlatform() noexcept;

        // Event Safety - begin, style, post-begin
        // Available for GLFW platforms - X11 & Wayland. The other platforms return null. Cross-platform libraries
        // should handle null values without any issues though.
        static void* getNativeDisplay() noexcept;
    };

    // Event safety - begin, style, post-begin
    static void setWindowSizeInScreenCoords(FVector2 sz) noexcept;

    // Event safety - begin, style, post-begin
    static FVector2 getWindowSizeInScreenCoords() noexcept;

    // Event safety - begin, style, post-begin
    // Pushes a new callback to the event list
    static void pushWindowResizedInScreenCoordsCallback(const TFunction<void(int, int)>& f) noexcept;

    // Event safety - begin, style, post-begin
    // Changes resize-ability of the window, not the setting
    static void setWindowResizeable(bool bResizeable) noexcept;

    // Event safety - begin, style, post-begin
    // Returns the setting, doesn't modify the window
    static bool& getWindowResizeableSetting() noexcept;

    // Event safety - begin, style, post-begin
    // Returns the current resize state of the window
    static bool getWindowCurrentlyResizeable() noexcept;

    // Event safety - begin, style, post-begin
    // Pushes a new callback to the event list
    static void pushWindowResizeCallback(const TFunction<void(int, int)>& f) noexcept;

    // Event safety - begin, style, post-begin
    // x = left; y = top; z = right; w = bottom
    static FVector4 getWindowDecorationFrameDistances() noexcept;

    // Event safety - begin, style, post-begin
    static void requestWindowAttention() noexcept;

    // Event safety - begin, style, post-begin
    // This doesn't change the "hidden" setting, use the `getWindowHidden` function to change it
    static void hideWindow() noexcept;

    // Event safety - begin, style, post-begin
    // This doesn't change the "hidden" setting, use the `getWindowHidden` function to change it
    static void showWindow() noexcept;

    // Event safety - begin, style, post-begin
    // Used to change the "hidden" setting, doesn't modify the current hidden state
    static bool& getWindowHiddenSetting() noexcept;

    // Event safety - begin, style, post-begin
    // Used to get the current window hidden state
    static bool getWindowCurrentlyHidden() noexcept;

    // Event safety - begin, style, post-begin
    static bool getWindowSurfaceTransparent() noexcept;

    // Event safety - begin, style, post-begin
    static void setWindowSurfaceTransparent(bool bTransparent) noexcept;

    // Event safety - begin, style, post-begin
    static bool& getWindowSurfaceTransparentSetting() noexcept;

    // Event safety - begin, style, post-begin
    // This doesn't change the "focused" setting, use the `getWindowFocused` function
    static void focusWindow() noexcept;

    // Event safety - begin, style, post-begin
    // Used to change the "focused" setting, doesn't modify the current focused state
    static bool& getWindowFocusedSetting() noexcept;

    // Event safety - begin, style, post-begin
    // Used to get the current window focus state
    static bool getWindowCurrentlyFocused() noexcept;

    // Event safety - begin, style, post-begin
    static void pushWindowFocusCallback(const TFunction<void(bool)>& f) noexcept;

    // Event safety - begin, style, post-begin
    static void iconifyWindow() noexcept;

    // Event safety - begin, style, post-begin
    // Restores window from iconification and maximisation
    static void restoreWindowState() noexcept;

    // Event safety - begin, style, post-begin
    static void pushWindowIconifyCallback(const TFunction<void(bool)>& f) noexcept;

    // Event safety - begin, style, post-begin
    static bool getWindowIconified() noexcept;

    // Event safety - begin, style, post-begin
    static FVector2 getWindowContentScale() noexcept;

    // Event safety - begin, style, post-begin
    static void pushWindowContentScaleCallback(const TFunction<void(FVector2)>& f) noexcept;

    // Event safety - begin, style, post-begin
    // Calling without arguments resets to the default state
    static void setSizeLimits(FVector2 min = { -1, -1 }, FVector2 max = { -1, -1 }) noexcept;

    // Event safety - begin, style, post-begin
    // Calling without an argument resets to the default state
    static void setSizeLimitByAspectRatio(FVector2 ratio = { -1, -1 }) noexcept;

    // Event safety = begin, style, post-begin
    // Returns the settings value for the size limits, doesn't edit them
    static FVector4& getSizeLimits() noexcept;

    // Event safety = begin, style, post-begin
    // Returns the settings value for the aspect ratio size limits, doesn't edit them
    static FVector2& getAspectRatioSizeLimits() noexcept;

    // Event safety - begin, style, post-begin
    // Returns the current state of the window, not the setting
    static bool getCurrentWindowDecoratedState() noexcept;

    // Event safety - begin, style, post-begin
    // Returns the setting, not the current state of the window
    static bool& getWindowDecoratedSetting() noexcept;

    // Event safety - begin, style, post-begin
    // Sets the decoration state of the window
    static void setWindowDecorated(bool bDecorated) noexcept;

    // Event safety - begin, style, post-begin
    static void pushWindowRefreshCallback(const TFunction<void(void)>& f) noexcept;

    // Event safety - begin, style, post-begin
    // This changes the current window maximisation state but doesn't change the setting
    static void maximiseWindow() noexcept;

    // Event Safety - begin, style, post-begin
    // This changes the setting but doesn't change the current window maximisation state
    static bool& getWindowMaximisedSetting() noexcept;

    // Event safety - begin, style, post-begin
    static void pushWindowMaximiseCallback(const TFunction<void(bool)>& f) noexcept;

    // Event safety - begin, style, post-begin
    static bool getWindowCurrentlyMaximised() noexcept;

    // Event safety - begin, style, post-begin
    // Returns the monitor of the current window.
    static Monitor getWindowMonitor() noexcept;

    // Event safety - begin, style, post-begin
    // Returns the primary monitor
    static Monitor getPrimaryMonitor() noexcept;

    // Event safety - begin, style, post-begin
    // Returns a list of monitors, first monitor is the primary monitor, i.e. the monitor where global UI elements
    // like the taskbar spawns.
    static const TVector<Monitor>& getMonitors() noexcept;

    // Event safety - begin, style, post-begin
    static void pushWindowOSDragDropCallback(const TFunction<void(const FString&)>& f) noexcept;

    // Event safety - begin, style, post-begin
    // This is the internal window instance, DO NOT TOUCH IT
    static void* getInternal() noexcept;

    // Event safety - begin, style, post-begin
    // Returns the current window instance
    static GenericWindow* get() noexcept;
};

The functions are self-explanatory in what they do. However, we have to make some distinctions.

Warning

Some functions, including the entirety of the platform-specific parts of the interface will not work on Wayland, and on WASM.

Notable functions

The following functions are notable.

Window settings:

Functions following the following pattern get*Setting() or set*Setting() are used to modify the window's settings instead of the current properties. These settings can be saved by calling the saveSettings(bool) function.

You can also refresh the current properties after modifying the window settings by calling refreshSettings().

More information on window configuration can be found below.

Platform:

  1. Platform::setWindowAlwaysOnTop - Makes the window be always at the top of the screen. Useful for applications acting like status bars, IBus GUIs, etc. Currently, this is only supported on X11, Win32 & macOS
  2. Platform::setWindowAlwaysOnBottom - Makes the window be always below all other windows. Useful for applications like desktop widgets and wallpaper managers. Currently, this is only supported on X11, Win32 & macOS
  3. Platform::setWindowShowingOnPager - Toggles whether the window is shown on the pager. The default settings for the window are always true. Currently, this is only supported on X11 & Win32
  4. Platform::getWindowShowingOnPager - Returns a bool used to check if the window is shown on the pager. The underlying boolean is toggled by setWindowShowingOnPager even if the platform is not supported
  5. Platform::setWindowShowingOnTaskbar - Toggles whether the window is shown on the taskbar. The default settings for the window are always true. Currently, this is only supported on X11 & Win32
  6. Platform::getWindowShowingOnTaskbar - Returns a bool used to check if the window is shown on the taskbar. The underlying boolean is toggled by setWindowShowingOnTaskbar even if the platform is not supported
  7. Platform::getWindowID - Returns the ID of the current window. Currently, this is only supported on X11, Win32 & macOS.
  8. Platform::getNativeWindowHandle - Returns the window handle in the native platform's API as a void*
  9. Platform::getCurrentWindowPlatform - Returns the current native window platform as defined in the WindowPlatform enum
  10. Platform::getNativeDisplay - Returns the native display handle as a void*. This is only needed on X11 or Wayland. All other platforms return nullptr. Cross-platform libraries should handle null values without problems

Caution

None of these functions currently work under Wayland, or WASM!

Setting the X11 window type:

The Platform::setWindowType function takes a C string that defines an X11 semantic window type as defined on the X11 docs. Each type is interpreted by the underlying window manager and handled with the correct features.

Types defined as preprocessor definitions can be found in CDefines.hpp and look like this:

#define X11_WINDOW_TYPE_DESKTOP "_NET_WM_WINDOW_TYPE_DESKTOP"
#define X11_WINDOW_TYPE_DOCK "_NET_WM_WINDOW_TYPE_DOCK"
#define X11_WINDOW_TYPE_TOOLBAR "_NET_WM_WINDOW_TYPE_TOOLBAR"
#define X11_WINDOW_TYPE_MENU "_NET_WM_WINDOW_TYPE_MENU"
#define X11_WINDOW_TYPE_UTILITY "_NET_WM_WINDOW_TYPE_UTILITY"
#define X11_WINDOW_TYPE_SPLASH "_NET_WM_WINDOW_TYPE_SPLASH"
#define X11_WINDOW_TYPE_DIALOG "_NET_WM_WINDOW_TYPE_DIALOG"
#define X11_WINDOW_TYPE_NORMAL "_NET_WM_WINDOW_TYPE_NORMAL"

Read the X11 documentation on this feature for more information on what is enabled/disabled with each window type.

Resize:

  1. setWindowResizeable - Changes resize-ability of the window, not the setting
  2. getWindowResizeableSetting - Returns a reference to the setting that can be edited
  3. getWindowCurrentlyResizeable - Returns the current resize-ability of the window

Visibility:

Window visibility:

  1. hideWindow/showWindow - Hides/Shows the window, but doesn't change the setting
  2. getWindowHiddenSetting - Returns a reference to the setting value that can be changed and later saved
  3. getWindowCurrentlyHidden - Returns the current hidden state of the window

Window transparency:

  1. getWindowSurfaceTransparent - Returns a boolean that can be used to check if the window surface is currently transparent
  2. setWindowSurfaceTransparent - Used to enable/disable surface transparency
  3. getWindowSurfaceTransparentSetting - Returns a reference to the setting for window transparency

Focus:

  1. requestWindowAttention - Flashes the window to request the attention of the user in a non-disruptive way. This might not be supported on all platforms
  2. focusWindow - Focuses on the window, but doesn't change the focused setting. In most cases, this is disruptive to the user, so consider using the requestWindowAttention function instead of this.
  3. getWindowFocusedSetting - Returns a reference to the focused setting
  4. getWindowCurrentlyFocused - Returns the current focused state of the window

Decorations:

  1. getWindowContentScale - returns the content scale of the window, which can be used to scale things like UI elements correctly on the screen depending on the DPI
  2. getCurrentWindowDecoratedState - Returns the current decoration state of the window, not the setting
  3. getWindowDecoratedSetting - Returns a reference to the decorated setting
  4. setWindowDecorated - Sets the window decoration state
  5. windowSurfaceTransparentSetting - Returns a reference to whether window surface transparency is enabled for this window
  6. getWindowDecorationFrameDistances - Returns the window decoration frame distrances as an FVector4 where x is left, y is to, z is right and w is bottom

Window iconification, maximisation and state restoration.

  1. iconifyWindow - Iconifies/Minimizes the window
  2. restoreWindowState - Restores a window from iconification or maximisation
  3. getWindowIconified - Gets the current iconified state of the window
  4. maximiseWindow - Maximises the window
  5. getWindowMaximisedSetting - Returns the window maximisation setting
  6. getWindowCurrentlyMaximised - Returns the current window maximisation state

Window size:

  1. setSizeLimits - Sets min and max size limits of the window, -1 for no limit
  2. setSizeLimitByAspectRatio - Sets the size limit by aspect ratio, can coexist with the other size limits setting. -1 for no limit
  3. getSizeLimits - Returns the min and max size limits as a vec4 where x = min x, y = min y, z = max x and w = max w
  4. getAspectRatioSizeLimits - Returns the aspect ration size limits.

OS drag drop API:

  1. pushWindowOSDragDropCallback - Adds a callback function to be called when the window receives an OS drag drop event

Monitor API

The monitor API allows the developer to control the monitor state and get data about monitors on the user's system. A monitor can be fetched using the following functions:

  1. getWindowMonitor - Returns the monitor of the current window
  2. getPrimaryMonitor - Returns the primary monitor on the given sysetm
  3. getMonitors - Returns a list of all available monitors. The first monitor is the primary monitor, i.e. the monitor where global UI elements like taskbars spawn

These 3 functions return a Monitor struct and an array of Monitor structs, respectively. The Monitor struct looks like this:

struct Monitor
{
public:
    FVector4 getWorkArea() noexcept;
    double getContentScale() noexcept;
    FVector2 getSize() noexcept;
    float getPixelDensity() noexcept;

    String getName() noexcept;

    void* getPlatformHandle() noexcept;

    MonitorData& get() noexcept;
};

The member functions are like this:

  1. getContentScale - Returns the content scale parameter of the monitor
  2. getWorkArea - Returns the work area of the monitor in vec4 format where x = x pos, y = y pos, z = width and w = height
  3. getName - Returns the OS name of the monitor, may not be unique
  4. getSize - Returns the size of the monitor
  5. getPixelDensity - Returns the pixel density of the monitor
  6. getPlatformHandle - Returns the monitor's native platform handle as a void*
  7. get - Returns the monitor's data in the form of a reference to a MonitorData struct.

The MonitorData struct looks like this:

struct MonitorData
{
    uintptr_t id;
    void* additionalData;
    size_t additionalDataSize;
};

Monitor C API

The Monitor C API is the same as the C++ one, except for the naming changes in functions and the need for the developer to manually store a monitor data struct. All member functions are prefixed with UImGui_Monitor_.

When fetching a monitor from the window, a struct of type UImGui_CMonitorData is returned. Passing this struct to UImGui_Monitor_* functions modifies this monitor. The struct itself has 3 fields, but only additionalData and additionalDataSize should be touched. These 2 fields are the same as the ones in the C++ API.

Settings

Window settings are saved to Config/Core/Window.yaml and look like this:

layout-location: "DefaultLayout"
icon: "example-icon.png"
width: 800
height: 600
fullscreen: false
window-name: UntitledImGuiFramework
resizeable: false
transparent-surface: true
hidden: false
focused: true
size-limits: [ -1, -1, -1, -1 ]
aspect-ratio-size-limit: [ -1, -1 ]
decorated: false
maximised: false
  1. layout-location - Sets the location of the UI layout config file, set to DefaultLayout by default. Prepends .https://madladsquad.com/Config/ and appends .ini internally
  2. icon - The window icon file name. Prepends .https://madladsquad.com/Config/ internally
  3. width, height - Width and height of the window as an integer of pixels
  4. fullscreen - Whether the window should be full screened or not
  5. window-name - The title of the window
  6. resizeable - Toggles the ability to resize the window
  7. transparent-surface - Toggles the transparent properties of the surface. Platform dependant, controlled by ImGuiCol_WindowBg.w
  8. hidden - Whether the window should open in hidden state
  9. focused - Whether the window should automatically appear focused
  10. size-limits - Limits for the size of the window in vec4 format: x = min x, y = min y, z = max x, w = max y. -1 = no limit
  11. aspect-ratio-size-limit - Limits the size of the window using aspect ratio x/y. -1 = no limit
  12. decorated - Whether to start the window with window decorations, i.e. the top bar containing the window title, close, minimize, iconify buttons, etc.
  13. maximised - Whether to start the window maximised

Event safety

The entire module is flagged as event safe at Begin.

C API

The C API is the same as the C++ API, except that all function names are prefixed with the following strings:

  1. UImGui_Window_ - For regular window interface functions
  2. UImGui_Window_Platform_ - For platform functions
  3. UImGui_Monitor_ - For functions and variables part of the Monitor API

Callbacks use the default C alternatives, as documented here.