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.
The following functions are notable.
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
setTitle
- Sets the title of the windowsetIcon
- Sets the icon of the windowaspectRatio
- Returns the aspect ratio of the windowgetCurrentWindowPosition
- Returns the position of the windowgetLastWindowPosition
- Returns the last window positiongetWindowPositionChange
- The delta of the current and last window positionswindowSize
- Returns the window sizeclose
- Closes the window and therefore the application.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.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.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.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 supportedPlatform::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.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 supportedThe 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.
setWindowResizeable
- Changes resize-ability of the window, not the settinggetWindowResizeableSetting
- Returns a reference to the setting that can be editedgetWindowCurrentlyResizeable
- Returns the current resize-ability of the windowgetWindowDecorationFrameDistances
- 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
hideWindow
/showWindow
- Hides/Shows the window, but doesn’t change the settinggetWindowHiddenSetting
- Returns a reference to the setting value that can be changed and later savedgetWindowCurrentlyHidden
- Returns the current hidden state of the windowwindowSurfaceTransparent
- Returns a reference to the setting for window transparencyrequestWindowAttention
- Flashes the window to request the attention of the user in a non-disruptive way. This might not be supported on all platformsfocusWindow
- 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.getWindowFocusedSetting
- Returns a reference to the focused settinggetWindowCurrentlyFocused
- Returns the current focused state of the windowgetWindowContentScale
- returns the content scale of the window, which can be used to scale things like UI elements correctly on the screen depending on the DPIgetCurrentWindowDecoratedState
- Returns the current decoration state of the window, not the settinggetWindowDecoratedSetting
- Returns a reference to the decorated settingsetWindowDecorated
- Sets the window decoration statewindowSurfaceTransparent
- Returns a reference to the surface transparency setting of the windowiconifyWindow
- Iconifies/Minimizes the windowrestoreWindowState
- Restores a window from iconification or maximisationgetWindowIconified
- Gets the current iconified state of the windowmaximiseWindow
- Maximises the windowgetWindowMaximisedSetting
- Returns the window maximisation settinggetWindowCurrentlyMaximised
- Returns the current window maximisation statesetSizeLimits
- Sets min and max size limits of the window, -1
for no limitsetSizeLimitByAspectRatio
- Sets the size limit by aspect ratio, can coexist with the other size limits setting. -1
for no limitgetSizeLimits
- Returns the min and max size limits as a vec4
where x
= min x
, y
= min y
, z
= max x
and w
= max w
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)pushWindowOSDragDropCallback
- Adds a callback function to be called when the window receives an OS drag drop eventThe 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:
getWindowMonitor
- Returns the monitor of the current windowgetMonitors
- Returns a list of all available monitors. The first monitor is the primary monitor, i.e. the monitor where global UI elements like taskbars spawnThese 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:
getPhysicalSize
- Returns the approximate physical size of the monitorgetContentScale
- Returns the content scale parameter of the monitorgetVirtualPosition
- Returns the OS virtual position of the monitorgetWorkArea
- Returns the work area of the monitor in vec4
format where x
= x pos
, y
= y pos
, z
= width
and w
= height
getName
- Returns the OS name of the monitor, may not be uniquepushEvent
- Pushes an event local to this monitor, global events covered below. This event will be called when the monitor is connected or disconnectedThe 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
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
layout-location
- Sets the location of the UI layout config file, set to DefaultLayout
by default. Prepends ../Config/
and appends .ini
internallyicon
- The window icon file name. Prepends ../Config/
internallywidth
, height
- Width and height of the window as an integer of pixelsfullscreen
- Whether the window should be full screened or notwindow-name
- The title of the windowresizeable
- Toggles the ability to resize the windowtransparent-surface
- Toggles the transparent properties of the surface. Platform dependant, controlled by ImGuiCol_WindowBg.w
hidden
- Whether the window should open in hidden statefocused
- Whether the window should automatically appear focusedsize-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
aspect-ratio-size-limit
- Limits the size of the window using aspect ratio x
/y
. -1
= no limit
decorated
- Whether to start the window with window decorations, i.e. the top bar containing the window title, close, minimize, iconify buttons, etc.maximised
- Whether to start the window maximisedThe entire module is flagged as event safe at Begin
.