Status & Roadmap
Authors & License
Funding U++
Search on this site

SourceForge.net Logo

SourceForge.net Logo

GitHub Logo

Discord Logo

Supporting UHD displays and Dark theme

Table of contents


1. GUI mode detection

2. Activating Dark mode support

3. Scaling GUI for actual GUI font and UHD resolution

4. Color adjustment

5. Iml files


1. GUI mode detection

UHD mode is activated when GUI font is larger than 24 pixels. Dark theme mode is activated if IsDark(SColorPaper()), which means that grayscale value of default background is less than 80. Note that both modes create 4 combinations in total - standard resolution with light theme, standard resolution with dark theme, UHD resolution with light theme, UHD resolution with dark theme.

IsUHDMode() and IsDarkTheme() functions return respective current GUI status.

2. Activating Dark mode support

On some platforms (Win32), application needs to call Ctrl::SetDarkThemeEnabled(); at the starth of GUI_APP_MAIN to actually allow dark mode. This is make sure that application behaves correctly with dark colors.

3. Scaling GUI for actual GUI font and UHD resolution

U++ coordinates in drawing operations are always in real pixels for screen targets. U++ provides various functions to adjust GUI elements metrics to host platform font size and UHD mode. Some of these function use 'font-ratio', which is the ratio of metrics of current default GUI font to 'design-font' (which is more or less defined as font where text "OK Cancel Exit Retry" has Size(99, 13), font ratio is then current GUI font Size vs this predefined size).

int Zx(int cx);

double Zxf(double cx);

Scales the value horizontally based on font ratio.

int Zy(int cy);

Scales the value vertically based on font ratio.

Size Zsz(int cx, int cy);

Size Zsz(Size sz);

Scales size based on font ratio.

Font FontZ(int face, int height = 0);

Font StdFontZ(int height = 0);

Font SansSerifZ(int height = 0);

Font SerifZ(int height = 0);

Font MonospaceZ(int height = 0);

Font RomanZ(int height = 0);

Font ArialZ(int height = 0);

Font CourierZ(int height = 0);

Creates the font while scaling its height based on current font ratio. If height is 0, the height is set to current GUI font height.

int DPI(int a);

double DPI(double a);

Size DPI(Size sz);

Size DPI(int cx, int cy);

If UHD mode is active, returns the input argument multiplied by 2, otherwise returns it unchanged.

Image DPI(const Image& a, const Image& b);

Returns b if UHD is active, a otherwise.

Usually DPI functions are used if the value is Image related, 'Z' functions if it is text size related.

4. Color adjustment

If application is specifying any colors, these colors need to be adjusted for dark theme. This can be often done by using predefined colors. Sometimes only the light theme color is available that needs to be converted to dark theme - this can be done using DarkTheme function. Alternatively AdjustIfDark converts the color with DarkTheme only if dark theme mode is currently active.

5. Iml files

Iml files most often contain images that are used in GUI interface. Obviously, these images must be usually different for any of 4 GUI modes.

.iml should always contain images for standard resolution / light theme. These images are used to define the set of icons.

U++ then uses smart algorithms to convert such images for the current GUI mode. These work acceptably well in most cases.

Developer might decide to provide dedicated variants for any image for any target mode which will be used instead of converted basic icon. Such variant can be either placed into the same .iml file or into separate .iml file.

The complete control of the process is available in image details in the icon designer:




Image is never scaled or darkened to match current mode.

Fixed colors

Image is never darkened to match current mode. Set this if the image looks better in the dark mode without actually converting it.

Fixed size

Image is never scaled to match current mode.

UHD variant

Image is variant for UHD mode.

Dark variant

Image is variant for Dark theme.


This is unrelated to UHD / Dark theme mode, but if this is checked, the Image is exported as .ico and .png files. This is intended for application icon (e.g. shown in host shell).


Alternatively, .iml dedicated for overrides for particular mode is used. This override is then used as parameter to "iml_source" part of .iml inclusion process:


#define IMAGECLASS MyImg

#define IMAGEFILE <MyApp/MyImg.iml>

#define IMAGEFILE_UHD <MyApp/MyImgHD.iml>


#include <Draw/iml_source.h>


The macro names for corresponding GUI modes are IMAGEFILE_DARK, IMAGEFILE_UHD, IMAGEFILE_DARK_UHD. Note that theide tool that creates .iml import code will automatically add reasonably named .iml files (like MyAppHD.iml, MyAppDK.iml, MyAppHDDK.iml) as variant .imls automatically.

Finally, it is also possible to disable automatic conversion for the while .iml file by #defining FIXED_COLORS and/or FIXED_SIZE macros:


#define IMAGECLASS MyImg

#define IMAGEFILE <MyApp/MyImg.iml>


#define FIXED_SIZE


#include <Draw/iml_source.h>


Do you want to contribute?