Supporting Dark Mode

Xojo supports Dark Mode on versions of iOS, Linux, macOS, Web and Windows that support it. To enable Dark Mode support for your app, turn the "Supports Dark Mode" property on the Shared Build Settings. For new projects, "Supports Dark Mode" defaults to ON. For existing projects, it defaults to "OFF".

../../_images/supporting_dark_mode_supports_dark_mode_shared_build_setting.png

Default colors

There are some subtle changes to how default colors work.

  • Controls whose text defaults to Solid Black (&c00000000) will automatically use the system's Text Color (except Label, see below), which changes depending on Light or Dark mode.

  • Controls whose background color defaults to Solid White (&cFFFFFF00) will automatically use the system's Text Background Color, which changes depending on Light or Dark Mode.

  • When painting to a Graphics context (such as in Canvas), Color returns the system Text Color, Color returns the system's Window Fill Color and Color now uses the system's Control Color.

  • The DesktopLabel control TextColor property defaults to Solid Black (&c000000) and as a result will automatically use the system's Label Color so they automatically match the captions on Checkboxes and Radio buttons and change depending on light/dark mode.

  • If you do not want Xojo to automatically swap these colors for you, instead choose an Off-White or Off-Black color, such as &c00000001 or &cFFFFFF01. These will be indistinguishable from Solid Black and Solid White and will be ignored by Xojo.

Methods and events

There is a new global method called Color which returns True if the system is running in Dark Mode and the app has Supports Dark Mode set to ON. It returns False when Supports Dark Mode is set to OFF. Use this to detect Dark Mode for situations when you have to manually adjust colors, graphics or icons yourself.

The DesktopApplication is called when the user switches between light and dark modes or when the accent color changes. You can use this to tell your UI to update or redraw as necessary.

Control differences

Due to changes made by Apple, controls in macOS dark mode are translucent. Because of this it is recommended you avoid overlapping controls in your layouts.

Because of the translucent controls you may find redrawing occurs differently in some situations. If you are not seeing redraws when you expect, try calling the Refresh method instead of Invalidate.

Window backgrounds

Windows with custom background colors do not automatically change the color for Dark Mode. You will have to adjust the color in your code when Color returns True.