#include <aurore/core/theme.hpp>

Public Member Functions
	Theme (ThemeValues *values)
	A handle on one variant's colours (not owned).

NVGcolor	operator[] (const std::string &name)
	The colour `name` (getColor()).

void	addColor (const std::string &, NVGcolor color)
	A colour of the base (see ThemeValues::addColor).

NVGcolor	getColor (const std::string &name)
	The colour `name` as drawn now; an unknown key is fatal (check with hasColor()).

bool	hasColor (const std::string &name)
	Whether the key exists.

ThemeValues *	getValues ()
	The colours behind the handle.

Static Public Member Functions
static Theme &	getLightTheme ()
	The light variant's colours.

static Theme &	getDarkTheme ()
	The dark variant's colours.

static Theme &	get (ThemeVariant variant)
	The colours of `variant`.

static bool	loadFile (const std::string &path, ThemeVariant *variant=nullptr)

static bool	load (const std::string &text, ThemeVariant *variant=nullptr, const std::string &directory="")

static void	reset ()

static void	followCalendar ()

static std::string	seasonalTheme (std::time_t when)

static const std::string &	getCurrentPath ()

static bool	styles (ThemeVariant variant)

static std::string	getBackgroundImage ()

static ThemeBackground	getBackground (ThemeVariant variant)

static ThemeDecor	getDecor (ThemeVariant variant)

static bool	resolveAsset (const std::string &name, const std::string &directory, const std::string &root, std::string path, std::string error)

static bool	recheckAsset (const std::string &path, std::string *error=nullptr)

static ThemePictures	getPictures (ThemeVariant variant)

static void	addIconNames (const std::vector< std::string > &names)

static void	addImageSlot (const std::string &key, const std::string &fallback="", int maxSide=0)

static std::vector< std::string >	getImageSlots ()

static std::shared_ptr< ThemeImage >	image (const std::string &key)

static std::shared_ptr< ThemeImage >	logo ()

static std::shared_ptr< ThemeImage >	icon (const std::string &name, bool *tint=nullptr)

static void	addSurfaceKey (const std::string &key)

static ThemeInfo	inspect (const std::string &path, bool decodePictures=false)

static std::vector< ThemeInfo >	listThemes (const std::string &directory, bool decodePictures=false)

static std::vector< ThemeInfo >	builtinThemes ()

static bool	parseColor (const std::string &text, NVGcolor *color)

static float	contrast (NVGcolor a, NVGcolor b)

static void	addContrastCheck (const std::string &ink, const std::string &surface, float minimum=4.5f)

static std::vector< std::string >	checkContrast (ThemeVariant variant)

static std::vector< std::string >	checkBackgroundContrast (ThemeVariant variant)

static uint64_t	getGeneration ()

Detailed Description

The colours views draw with, by key, for the light and the dark variant: Application::getTheme() is the variant in use. Every colour of the core views and of Cadran is a key (docs/themes.md lists them), so a theme file restyles all of them.

A view keeps a key rather than a colour with View::setThemeColor (XML: textColor="@theme/aurore/text"), and draws with its new value when the theme changes, at once: Application::getThemeChangedEvent() says so to what keeps colours of its own.

Constructor & Destructor Documentation

◆ Theme()

aurore::Theme::Theme ( ThemeValues * values )

A handle on one variant's colours (not owned).

Member Function Documentation

◆ addColor()

void aurore::Theme::addColor	(	const std::string &	,
		NVGcolor	color
	)

A colour of the base (see ThemeValues::addColor).

◆ addContrastCheck()

static void aurore::Theme::addContrastCheck	(	const std::string &	ink,
		const std::string &	surface,
		float	minimum = `4.5f`
	)

static

A pair checkContrast() looks at: ink drawn on surface (keys), at least minimum:1. A translucent colour is first blended over aurore/background. The core adds its own; Cadran its palette's.

◆ addIconNames()

static void aurore::Theme::addIconNames ( const std::vector< std::string > & names )

static

The icons a theme may draw as pictures (icon.<name> = file.png): any other name is a warning. Cadran adds its own (CadranIcon).

◆ addImageSlot()

static void aurore::Theme::addImageSlot	(	const std::string &	key,
		const std::string &	fallback = `""`,
		int	maxSide = `0`
	)

static

Declares an image slot: a picture of the app's that a theme may replace (image.<key> = file.png), "playguard/loading/art". fallback is the app's own picture ("@res/img/art.png", a file; "" for none), maxSide the largest side it is made at (0: 1920 x 1080). Before the theme file is loaded: a theme naming a slot not declared is warned about. Declared again, the new fallback replaces the old one.

◆ addSurfaceKey()

static void aurore::Theme::addSurfaceKey ( const std::string & key )

static

A key of a surface (a card, a panel) drawn over the screens' background: with a background image and surface_opacity under 1, its opacity is multiplied by it. The core's: aurore/sidebar/background, aurore/highlight/background, the default buttons' backgrounds; Cadran adds cadran/surf and cadran/surf2.

◆ builtinThemes()

static std::vector< ThemeInfo > aurore::Theme::builtinThemes ( )

static

The presets built into Aurore ("builtin:<id>" paths).

◆ checkBackgroundContrast()

static std::vector< std::string > aurore::Theme::checkBackgroundContrast ( ThemeVariant variant )

static

Only the pairs the background image changes (text on the screens' background, translucent surfaces), on its average colour under its veil; empty without an image, or while its colour is not known.

◆ checkContrast()

static std::vector< std::string > aurore::Theme::checkContrast ( ThemeVariant variant )

static

The pairs of variant under their minimum, as "aurore/text on aurore/background: 3.1:1, under 4.5:1". With a background image whose colour is known (ThemeImages), text on aurore/background is checked on the image's average colour under its veil, and translucent surfaces over it.

◆ contrast()

static float aurore::Theme::contrast	(	NVGcolor	a,
		NVGcolor	b
	)

static

WCAG's contrast ratio of two opaque colours (1 to 21).

◆ followCalendar()

static void aurore::Theme::followCalendar ( )

static

With "builtin:seasonal" in use, the preset of the day (by local date: Halloween, Christmas, the seasons... docs/themes.md), used as soon as the date enters another one. The main loop calls it at each iteration; it looks at the wall clock once a minute (a console resuming from sleep included).

◆ get()

static Theme & aurore::Theme::get ( ThemeVariant variant )

static

The colours of variant.

◆ getBackground()

static ThemeBackground aurore::Theme::getBackground ( ThemeVariant variant )

static

The background of variant with the file in use: its image (none without a file, or for a variant the file does not style), how it fits, its veil, the surfaces' opacity.

◆ getBackgroundImage()

static std::string aurore::Theme::getBackgroundImage ( )

static

The picture the file in use puts behind every screen in the variant in use (background_image = file.png, next to the theme file), "" without one: drawn over aurore/clear, under the screens.

◆ getColor()

NVGcolor aurore::Theme::getColor ( const std::string & name )

The colour name as drawn now; an unknown key is fatal (check with hasColor()).

◆ getCurrentPath()

static const std::string & aurore::Theme::getCurrentPath ( )

static

The file in use ("" without one), as given to loadFile.

◆ getDarkTheme()

static Theme & aurore::Theme::getDarkTheme ( )

static

The dark variant's colours.

◆ getDecor()

static ThemeDecor aurore::Theme::getDecor ( ThemeVariant variant )

static

The decorations of variant with the file in use (backdrop.*, decor.*, particles*): none without a file, or for a variant the file does not style. ThemeDecorations draws them.

◆ getGeneration()

static uint64_t aurore::Theme::getGeneration ( )

static

Changes each time a colour or a metric changes (a theme file used, a colour added): the main loop compares it at each iteration to tell the views and draw them again.

◆ getImageSlots()

static std::vector< std::string > aurore::Theme::getImageSlots ( )

static

The image slots declared, sorted.

◆ getLightTheme()

static Theme & aurore::Theme::getLightTheme ( )

static

The light variant's colours.

◆ getPictures()

static ThemePictures aurore::Theme::getPictures ( ThemeVariant variant )

static

The logo, icons, preview and image slots' pictures of variant with the file in use (none without a file, or for a variant it does not style): paths, nothing loaded.

◆ getValues()

ThemeValues * aurore::Theme::getValues ( )

inline

The colours behind the handle.

◆ hasColor()

bool aurore::Theme::hasColor ( const std::string & name )

Whether the key exists.

◆ icon()

static std::shared_ptr< ThemeImage > aurore::Theme::icon	(	const std::string &	name,
		bool *	tint = `nullptr`
	)

static

The theme's picture for the icon name in the variant in use (UI thread), nullptr without one; tint says whether it is a mask, drawn in the icon's colour. Made at most ThemeImages::ICON_SIZE.

◆ image()

static std::shared_ptr< ThemeImage > aurore::Theme::image ( const std::string & key )

static

The picture of the image slot key now (UI thread): the theme's for the variant in use, else the slot's fallback (also when the theme's cannot be read); nullptr for neither, or a slot not declared. Loaded on the decode thread (ThemeImages): it may still be LOADING, and ThemeImages::getLoadedEvent() says when it is ready. Kept while the theme and the variant stay; a view keeping it gets the new one on Application::getThemeChangedEvent() (aurore::Image::setThemeImage does).

◆ inspect()

static ThemeInfo aurore::Theme::inspect	(	const std::string &	path,
		bool	decodePictures = `false`
	)

static

Reads a theme file without using it: its metadata, a preview, what is wrong with it. Its pictures are only looked for (an error when one is not there), never decoded, unless decodePictures: then each is decoded on the calling thread, to tell a broken file and to check the text on it (for a check off the UI thread: –check-themes, a test).

◆ listThemes()

static std::vector< ThemeInfo > aurore::Theme::listThemes	(	const std::string &	directory,
		bool	decodePictures = `false`
	)

static

Every *.theme of directory (a folder, or a resource folder such as "@res/themes"), sorted by name: one entry per file, a broken one with its errors (never skipped, never fatal). Empty when the folder does not exist. From the main thread, as inspect(): the previews are made from the themes in use. Cheap: colours only, no picture decoded unless decodePictures (as inspect()).

◆ load()

static bool aurore::Theme::load	(	const std::string &	text,
		ThemeVariant *	variant = `nullptr`,
		const std::string &	directory = `""`
	)

static

As loadFile, from the file's text; directory is where its @include and inherit files are looked for.

◆ loadFile()

static bool aurore::Theme::loadFile	(	const std::string &	path,
		ThemeVariant *	variant = `nullptr`
	)

static

Uses a theme file (docs/themes.md), replacing the one used before:

name = Ocean
inherit = dark          # light, dark, another file or builtin:<id>
accent = #3fa7ff        # the palette: accent, background, surface,
                        # text, warning, danger; the rest derived
[colors]                # any key, for the variants it styles
aurore/sidebar/background = #0d1b2a
[light] / [dark]        # the same, for one variant only
[metrics]
aurore/highlight/stroke_width = 4

path is a file, a resource ("@res/themes/x.theme") or a preset ("builtin:high-contrast-dark", builtinThemes()). A line it cannot read is logged and skipped; false when the file cannot be read at all. The variant to show it in is put in variant when given (the one it styles, or the one in use when it styles both), for Platform::setThemeVariant. Text that reads badly on its background is logged as a warning (checkContrast). The screens take it at the next iteration of the main loop, which draws them again (redraw on demand or not).

◆ logo()

static std::shared_ptr< ThemeImage > aurore::Theme::logo ( )

static

The theme's logo for the variant in use (UI thread), nullptr without one: for an app that draws its logo itself (Cadran's mark draws it). Made at most ThemeImages::LOGO_SIZE; ThemeImage::draw with CONTAIN.

◆ operator[]()

NVGcolor aurore::Theme::operator[] ( const std::string & name )

The colour name (getColor()).

◆ parseColor()

static bool aurore::Theme::parseColor	(	const std::string &	text,
		NVGcolor *	color
	)

static

Reads a colour as theme files write it ("#2ec4b6", "#2ec4b680", "rgba(…)"); false if it is not one.

◆ recheckAsset()

static bool aurore::Theme::recheckAsset	(	const std::string &	path,
		std::string *	error = `nullptr`
	)

static

A path resolveAsset() made, looked at again just before the file is opened (from any thread): false, with the reason in error, when a link now takes it out of its theme's folder (put there after resolveAsset() looked). True for a path resolveAsset() did not check (a resource, a file named by the app). A hard link cannot be told from the file itself: a theme folder is only as safe as who can write in it.

◆ reset()

static void aurore::Theme::reset ( )

static

Back to the look without a theme file.

◆ resolveAsset()

static bool aurore::Theme::resolveAsset	(	const std::string &	name,
		const std::string &	directory,
		const std::string &	root,
		std::string *	path,
		std::string *	error
	)

static

A file a theme names (its background_image, and any picture a theme key names), as a path: name is read from directory, the folder of the theme file (or included file) that names it, and must stay in root, the folder of the theme (a theme folder, or the folder of a single .theme file). No absolute path, no "x:/", no ".." out of root, no link out of it; "@res/..." only for a preset (directory "builtin:") or a theme that is itself a resource. False, with the reason in error, when it is refused. The one place theme files' pictures are resolved.

◆ seasonalTheme()

static std::string aurore::Theme::seasonalTheme ( std::time_t when )

static

The preset "builtin:seasonal" uses at when (seconds since the epoch, read in local time): "builtin:halloween"...

◆ styles()

static bool aurore::Theme::styles ( ThemeVariant variant )

static

Whether the file in use styles variant (true without one): a file for one variant only leaves the other as it is without a file.

The documentation for this class was generated from the following file:

aurore/core/theme.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Theme()

Member Function Documentation

◆ addColor()

◆ addContrastCheck()

◆ addIconNames()

◆ addImageSlot()

◆ addSurfaceKey()

◆ builtinThemes()

◆ checkBackgroundContrast()

◆ checkContrast()

◆ contrast()

◆ followCalendar()

◆ get()

◆ getBackground()

◆ getBackgroundImage()

◆ getColor()

◆ getCurrentPath()

◆ getDarkTheme()

◆ getDecor()

◆ getGeneration()

◆ getImageSlots()

◆ getLightTheme()

◆ getPictures()

◆ getValues()

◆ hasColor()

◆ icon()

◆ image()

◆ inspect()

◆ listThemes()

◆ load()

◆ loadFile()

◆ logo()

◆ operator[]()

◆ parseColor()

◆ recheckAsset()

◆ reset()

◆ resolveAsset()

◆ seasonalTheme()

◆ styles()