UserTheme

public class UserTheme: NSObject, Theme

A Theme class wrapping a user provided theme file (.theme).

To enable user themes, set theme folder on ThemeManager.userThemesFolderURL.

Notes about .theme files:

  • lines starting with # or // will be treated as comments, thus, ignored;
  • non-comment lines consists on simple variable/value assignments (eg, variable = value);
  • variable name can contain characters [a-zA-Z0-9_-.]+;
  • custom variables can be specified (eg, myBackgroundColor = ...);
  • theming properties match the class methods of ThemeColor, ThemeGradient and ThemeImage (eg, labelColor);
  • variables can be referenced by prefixing them with $ (eg, mainBorderColor = $commonBorderColor);
  • colors are defined using rgb(255, 255, 255) or rgba(255, 255, 255, 1.0) (case insensitive);
  • gradients are defined using linear-gradient(color1, color2) (where colors are defined as above; case insensitive);
  • pattern images are defined using pattern(named:xxxx) (named images) or pattern(file:../dddd/xxxx.yyy) (filesystem images);
  • images are defined using image(named:xxxx) (named images) or image(file:../dddd/xxxx.yyy) (filesystem images);
  • ThemeManager.themes property is automatically updated when there are changes on the user themes folder;
  • file changes are applied on-the-fly, if it corresponds to the currently applied theme.

Example .theme file:

// ************************* Theme Info ************************* //
displayName = My Theme 1
identifier = com.luckymarmot.ThemeKit.MyTheme1
darkTheme = true

// ********************* Colors & Gradients ********************* //
# define color for `ThemeColor.brandColor`
brandColor = $blue
# define a new color for `NSColor.labelColor` (overriding)
labelColor = rgb(11, 220, 111)
# define gradient for `ThemeGradient.brandGradient`
brandGradient = linear-gradient($orange.sky, rgba(200, 140, 60, 1.0))

// ********************* Images & Patterns ********************** //
# define pattern image from named image "paper" for color `ThemeColor.contentBackgroundColor`
contentBackgroundColor = pattern(named:paper)
# define pattern image from filesystem (relative to user themes folder) for color `ThemeColor.bottomBackgroundColor`
bottomBackgroundColor = pattern(file:../some/path/some-file.png)
# use named image "apple"
namedImage = image(named:apple)
# use image from filesystem (relative to user themes folder)
fileImage = image(file:../some/path/some-file.jpg)

// *********************** Common Colors ************************ //
blue = rgb(0, 170, 255)
orange.sky = rgb(160, 90, 45, .5)

// ********************** Fallback Assets *********************** //
fallbackForegroundColor = rgb(255, 10, 90, 1.0)
fallbackBackgroundColor = rgb(255, 200, 190)
fallbackGradient = linear-gradient($blue, rgba(200, 140, 60, 1.0))

With the exception of system overrided named colors (e.g., labelColor), which defaults to the original system provided named color, unimplemented properties on theme file will default to -fallbackForegroundColor, -fallbackBackgroundColor, -fallbackGradient and -fallbackImage, for foreground color, background color, gradients and images, respectively.

  • Theme asset for the specified key. Supported assets are NSColor, NSGradient, NSImage and NSString.

    Declaration

    Swift

    @objc public func themeAsset(_ key: String) -> Any?

    Parameters

    key

    A color name, gradient name, image name or a theme string

    Return Value

    The theme value for the specified key.

  • Checks if a theme asset is provided for the given key.

    Do not check for theme asset availability with themeAsset(_:), use this method instead, which is much faster.

    Declaration

    Swift

    @objc public func hasThemeAsset(_ key: String) -> Bool

    Parameters

    key

    A color name, gradient name, image name or a theme string

    Return Value

    true if theme provides an asset for the given key; false otherwise.