Dark Mode

From Xojo Documentation

You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!

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

Supports Dark Mode Shared Build Setting

Default Colors

There are some subtle changes to how default colors work in Dark Mode.

  • 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.Paint), TextColor returns the system Text Color, FillColor returns the system's Window Fill Color and FrameColor now uses the system's Control Color.
  • The Label 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.IsDarkMode which returns True if the system is running in Dark Mode on macOS or Windows and the app has Supports Dark Mode set to ON. It returns False when Supports Dark Mode is set to OFF or when the app is running on Linux. Use this to detect Dark Mode for situations when you have to manually adjust colors, graphics or icons yourself.

The DesktopApplication.AppearanceChanged 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 IsDarkMode returns True.

See Also