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:
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 & macOSPlatform::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 & macOSPlatform::setWindowShowingOnPager
- Toggles whether the window is shown on the pager. The default settings for the window are alwaystrue
. Currently, this is only supported on X11 & Win32Platform::getWindowShowingOnPager
- Returns a bool used to check if the window is shown on the pager. The underlying boolean is toggled bysetWindowShowingOnPager
even if the platform is not supportedPlatform::setWindowShowingOnTaskbar
- Toggles whether the window is shown on the taskbar. The default settings for the window are alwaystrue
. Currently, this is only supported on X11 & Win32Platform::getWindowShowingOnTaskbar
- Returns a bool used to check if the window is shown on the taskbar. The underlying boolean is toggled bysetWindowShowingOnTaskbar
even if the platform is not supportedPlatform::getWindowID
- Returns the ID of the current window. Currently, this is only supported on X11, Win32 & macOS.Platform::getNativeWindowHandle
- Returns the window handle in the native platform's API as avoid*
Platform::getCurrentWindowPlatform
- Returns the current native window platform as defined in theWindowPlatform
enumPlatform::getNativeDisplay
- Returns the native display handle as avoid*
. This is only needed on X11 or Wayland. All other platforms returnnullptr
. 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:
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 window
Visibility:
Window visibility:
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 window
Window transparency:
getWindowSurfaceTransparent
- Returns a boolean that can be used to check if the window surface is currently transparentsetWindowSurfaceTransparent
- Used to enable/disable surface transparencygetWindowSurfaceTransparentSetting
- Returns a reference to the setting for window transparency
Focus:
requestWindowAttention
- 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 therequestWindowAttention
function instead of this.getWindowFocusedSetting
- Returns a reference to the focused settinggetWindowCurrentlyFocused
- Returns the current focused state of the window
Decorations:
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 DPIgetCurrentWindowDecoratedState
- Returns the current decoration state of the window, not the settinggetWindowDecoratedSetting
- Returns a reference to the decorated settingsetWindowDecorated
- Sets the window decoration statewindowSurfaceTransparentSetting
- Returns a reference to whether window surface transparency is enabled for this windowgetWindowDecorationFrameDistances
- 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.
iconifyWindow
- 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 state
Window size:
setSizeLimits
- 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 avec4
wherex
=min x
,y
=min y
,z
=max x
andw
=max w
getAspectRatioSizeLimits
- Returns the aspect ration size limits.
OS drag drop API:
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:
getWindowMonitor
- Returns the monitor of the current windowgetPrimaryMonitor
- Returns the primary monitor on the given sysetmgetMonitors
- 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:
() noexcept;
FVector4 getWorkAreadouble getContentScale() noexcept;
() noexcept;
FVector2 getSizefloat getPixelDensity() noexcept;
() noexcept;
String getName
void* getPlatformHandle() noexcept;
& get() noexcept;
MonitorData};
The member functions are like this:
getContentScale
- Returns the content scale parameter of the monitorgetWorkArea
- Returns the work area of the monitor invec4
format wherex
=x pos
,y
=y pos
,z
=width
andw
=height
getName
- Returns the OS name of the monitor, may not be uniquegetSize
- Returns the size of the monitorgetPixelDensity
- Returns the pixel density of the monitorgetPlatformHandle
- Returns the monitor's native platform handle as avoid*
get
- Returns the monitor's data in the form of a reference to aMonitorData
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
layout-location
- Sets the location of the UI layout config file, set toDefaultLayout
by default. Prepends.https://madladsquad.com/Config/
and appends.ini
internallyicon
- The window icon file name. Prepends.https://madladsquad.com/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 byImGuiCol_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 invec4
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 ratiox
/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 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:
UImGui_Window_
- For regular window interface functionsUImGui_Window_Platform_
- For platform functionsUImGui_Monitor_
- For functions and variables part of the Monitor API
Callbacks use the default C alternatives, as documented here.
- Home
- Beginner content
- Install guide
- Creating and using the UI components
- The Instance
- The Init Info struct
- Building better titlebar menus
- Textures
- Logging
- Unicode support
- Additional features
- Client-side bar
- Custom type definitions
- Memory management
- C API development
- Config files and Folders
- Interfaces
- Internal Event safety
- Customising the build system
- Modules system
- Collaborating with others
- Advanced content
- Loading dynamic libraries at runtime
- Understanding the library layout
- Compilation mode modifiers
- Supporting plugins
- Production export and deployment
- OS integration tips
- Targeting WASM
- Using a custom rendering engine:
- Using a custom windowing backend:
- Developer and contributor resources
- Misc