ThemeImage

open class ThemeImage: NSImage

ThemeImage is a NSImage subclass that dynamically changes its colors whenever a new theme is make current.

Theme-aware means you don’t need to check any conditions when choosing which image to draw. E.g.:

ThemeImage.logoImage.draw(in: bounds)

The drawing code will draw with different image depending on the selected theme. Unless some drawing cache is being done, there’s no need to refresh the UI after changing the current theme.

Defining theme-aware images

The recommended way of adding your own dynamic images is as follows:

1. Add a ThemeImage class extension (or TKThemeImage category on Objective-C) to add class methods for your images. E.g.:

   In Swift:

   extension ThemeImage {
   
       static var logoImage: ThemeImage {
           return ThemeImage.image(with: #function)
       }
   
   }
   

   In Objective-C:

   @interface TKThemeImage (Demo)
   
   + (TKThemeImage*)logoImage;
   
   @end
   
   @implementation TKThemeImage (Demo)
   
   + (TKThemeImage*)logoImage {
       return [TKThemeImage imageWithSelector:_cmd];
   }
   
   @end
   

2. Add Class Extensions on any Theme you want to support (e.g., LightTheme and DarkTheme - TKLightTheme and TKDarkTheme on Objective-C) to provide instance methods for each theme image class method defined on (1). E.g.:

   In Swift:

   extension LightTheme {
   
       var logoImage: NSImage? {
           return NSImage(named: "MyLightLogo")
       }
   
   }
   
   extension DarkTheme {
   
       var logoImage: NSImage? {
           return NSImage(contentsOfFile: "somewhere/MyDarkLogo.png")
       }
   
   }
   

   In Objective-C:

   @interface TKLightTheme (Demo) @end
   
   @implementation TKLightTheme (Demo)
   
   - (NSImage*)logoImage
   {
       return [NSImage imageNamed:@"MyLightLogo"];
   }
   
   @end
   
   @interface TKDarkTheme (Demo) @end
   
   @implementation TKDarkTheme (Demo)
   
   - (NSImage*)logoImage
   {
       return [NSImage alloc] initWithContentsOfFile:@"somewhere/MyDarkLogo.png"];
   }
   
   @end
   

3. If supporting UserTheme‘s, define properties on user theme files (.theme) for each theme image class method defined on (1). E.g.:

   displayName = Sample User Theme
   identifier = com.luckymarmot.ThemeKit.SampleUserTheme
   darkTheme = false
   
   logoImage = image(named:MyLogo)
   //logoImage = image(file:../some/path/MyLogo.png)
   

Fallback images

Unimplemented properties/methods on target theme class will default to fallbackImage. This too, can be customized per theme.

Please check ThemeColor for theme-aware colors and ThemeGradient for theme-aware gradients.