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

class Window
{
public:
    static void setTitle(String name) noexcept;

    static void setIcon(String name) noexcept;

    static float aspectRatio() noexcept;

    static FVector2 getCurrentWindowPosition() noexcept;
    static FVector2 getLastWindowPosition() noexcept;
    static FVector2 getWindowPositionChange() noexcept;

    static void setCurrentWindowPosition(FVector2 pos) noexcept;
    static void pushWindowPositionChangeCallback(const std::function<void(FVector2)>& f) noexcept;

    static FVector2& windowSize() noexcept;
    static bool& fullscreen() noexcept;

    static FString& name() noexcept;
    static FString& iconLocation() noexcept;
    static FString& layoutLocation() noexcept;

    static void saveSettings(bool bSaveKeybinds) noexcept;

    static void refreshSettings() noexcept;

    static void close() noexcept;

    static void pushWindowCloseCallback(const std::function<void(void)>& f) noexcept;

    class Platform
    {
    public:
        Platform() = delete;
        Platform(const Platform&) = delete;
        void operator=(Platform const&) = delete;

        static void setWindowAlwaysOnTop() noexcept;
        static void setWindowAlwaysOnBottom(bool bShowInPager = false, bool bShowOnTaskbar = false) noexcept;
        static void disableWindowMovement() noexcept;

        static void setWindowShowingOnPager() noexcept;
        static bool getWindowShowingOnPager() noexcept;

        static void setWindowShowingOnTaskbar(bool bShowOnTaskbar) noexcept;
        static bool getWindowShowingOnTaskbar() noexcept;

        static void setWindowType(const char* type) noexcept;
    };

    static void setWindowSizeInScreenCoords(FVector2 sz) noexcept;
    static FVector2& getWindowSizeInScreenCoords() noexcept;
    static void pushWindowResizedInScreenCoordsCallback(const std::function<void(int, int)>& f) noexcept;
    static void setWindowResizeable(bool bResizeable) noexcept;
    static bool& getWindowResizeableSetting() noexcept;
    static bool getWindowCurrentlyResizeable() noexcept;

    static void pushWindowResizeCallback(const std::function<void(int, int)>& f) noexcept;

    static FVector4 getWindowDecorationFrameDistances() noexcept;

    static void requestWindowAttention() noexcept;

    static void hideWindow() noexcept;
    static void showWindow() noexcept;
    static bool& getWindowHiddenSetting() noexcept;
    static bool getWindowCurrentlyHidden() noexcept;

    static bool& windowSurfaceTransparent() noexcept;

    static void focusWindow() noexcept;
    static bool& getWindowFocusedSetting() noexcept;
    static bool getWindowCurrentlyFocused() noexcept;
    static void pushWindowFocusCallback(const std::function<void(bool)>& f) noexcept;

    static void iconifyWindow() noexcept;
    static void restoreWindowState() noexcept;
    static void pushWindowIconifyCallback(const std::function<void(bool)>& f) noexcept;
    static bool getWindowIconified() noexcept;

    static FVector2 getWindowContentScale() noexcept;
    static void pushWindowContentScaleCallback(const std::function<void(FVector2)>& f) noexcept;

    static void setSizeLimits(FVector2 min = { -1, -1 }, FVector2 max = { -1, -1 }) noexcept;
    static void setSizeLimitByAspectRatio(FVector2 ratio = { -1, -1 }) noexcept;
    static FVector4& getSizeLimits() noexcept;
    static FVector2& getAspectRatioSizeLimits() noexcept;

    static bool getCurrentWindowDecoratedState() noexcept;
    static bool& getWindowDecoratedSetting() noexcept;
    static void setWindowDecorated(bool bDecorated) noexcept;

    static void pushWindowRefreshCallback(const std::function<void(void)>& f) noexcept;

    static void maximiseWindow() noexcept;
    static bool& getWindowMaximisedSetting() noexcept;
    static void pushWindowMaximiseCallback(const std::function<void(bool)>& f) noexcept;
    static bool getWindowCurrentlyMaximised() noexcept;

    static Monitor getWindowMonitor() noexcept;
    static void setWindowMonitor(const Monitor& monitor) noexcept;
    static std::vector<Monitor>& getMonitors() noexcept;

    static std::vector<FString>& getOSDragDropStrings() noexcept;
    static void pushWindowOSDragDropCallback(const std::function<void(std::vector<FString>&)>& f) noexcept;

    static void pushWindowErrorCallback(const std::function<void(int, const char*)>& f) noexcept;
};

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

Notable functions

The following functions are notable.

Error handling:

By default errors are printed using the logger. To add additional handling use the pushWindowErrorCallback function with a callback of type std::function<void(int, const char*)>, where the first argument is the error code and the second is the UTF-8 error string

Window settings:

1. setTitle - Sets the title of the window
2. setIcon - Sets the icon of the window
3. aspectRatio - Returns the aspect ratio of the window
4. getCurrentWindowPosition - Returns the position of the window
5. getLastWindowPosition - Returns the last window position
6. getWindowPositionChange - The delta of the current and last window positions
7. windowSize - Returns the window size
8. close - Closes the window and therefore the application.

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. Wayland and Win32 support is coming soon.
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. Wayland and Win32 is coming soon.
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. Wayland and Win32 support is coming soon.
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. Wayland and Win32 support is coming soon.
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

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 Core/Defines.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
4. getWindowDecorationFrameDistances - Returns the distance between the surface and the outside of the window decorations in vec4 format, where x = left, y = top, z = right, w = bottom

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
4. windowSurfaceTransparent - 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. windowSurfaceTransparent - Returns a reference to the surface transparency setting of the window

Window iconification/minimisation:

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

Window size:

1. maximiseWindow - Maximises the window
2. getWindowMaximisedSetting - Returns the window maximisation setting
3. getWindowCurrentlyMaximised - Returns the current window maximisation state
4. setSizeLimits - Sets min and max size limits of the window, -1 for no limit
5. setSizeLimitByAspectRatio - Sets the size limit by aspect ratio, can coexist with the other size limits setting. -1 for no limit
6. 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

OS drag drop API:

1. getOSDragDropStrings - Returns an array of strings returned by the OS when the drag drop event was executed(volatile, storing for a long time is not recommended)
2. 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. 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 2 functions return a Monitor struct and an array of Monitor structs, respectively. The Monitor struct looks like this:

struct Monitor
{
public:
    FVector2 getPhysicalSize() noexcept;
    FVector2 getContentScale() noexcept;
    FVector2 getVirtualPosition() noexcept;

    FVector4 getWorkArea() noexcept;

    FString getName() noexcept;

    void pushEvent(const std::function<void(Monitor&, MonitorState)>& f) noexcept;

    void* additionalData = nullptr;
    size_t additionalDataSize = 0;
};

The member functions are like this:

1. getPhysicalSize - Returns the approximate physical size of the monitor
2. getContentScale - Returns the content scale parameter of the monitor
3. getVirtualPosition - Returns the OS virtual position of the monitor
4. getWorkArea - Returns the work area of the monitor in vec4 format where x = x pos, y = y pos, z = width and w = height
5. getName - Returns the OS name of the monitor, may not be unique
6. pushEvent - Pushes an event local to this monitor, global events covered below. This event will be called when the monitor is connected or disconnected

The member variables additionalData and additionalDataSize are there to provide additional data to be used by events.

To push a global event, use Window::pushGlobalMonitorCallback. All events take a function of type std::function<void(Monitor&, MonitorState)>. The first argument is the Monitor struct itself and the second is the state of the monitor as defined in the MonitorState enum, which looks like this:

enum MonitorState
{
    UIMGUI_MONITOR_STATE_CONNECTED = 0x00040001,
    UIMGUI_MONITOR_STATE_DISCONNECTED = 0x00040002
};

---

Once a monitor is retrieved, the Window::setWindowMonitor function can be used to move the window to another monitor. The underlying behaviour of this function moves the window to coordinates (0;0) of the new monitor, preserves the old width and height and uses the new monitor’s refresh rate

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 ../Config/ and appends .ini internally
2. icon - The window icon file name. Prepends ../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.

This site is open source. Improve this page.