Dynamic Theme

A text (JSON) based theme engine for Android 4.0 (API 14) and above.

It uses AndroidX so, first migrate your project to AndroidX.
Since v3.1.0, it is dependent on Java 8 due to the dependency on Dynamic Utils.
Since v4.5.1, it is targeting Java 17 to provide maximum compatibility.
Since v4.6.0, the minimum SDK is Android 4.4 (API 19) to comply with the latest policies.

{
  "backgroundColor": "#455A64",
  "tintBackgroundColor": "auto",
  "surfaceColor": "auto",
  "tintSurfaceColor": "auto",
  "primaryColor": "#FF455A64",
  "tintPrimaryColor": "auto",
  "primaryColorDark": "auto",
  "tintPrimaryColorDark": "auto",
  "accentColor": "#FFE6EE9C",
  "tintAccentColor": "auto",
  "accentColorDark": "auto",
  "tintAccentColorDark": "auto",
  "errorColor": "auto",
  "tintErrorColor": "auto",
  "textPrimaryColor": "auto",
  "textPrimaryColorInverse": "auto",
  "textSecondaryColor": "auto",
  "textSecondaryColorInverse": "auto",
  "fontScale": "auto",
  "cornerRadius": "auto",
  "backgroundAware": "auto",
  "contrast": "auto",
  "opacity": "auto",
  "elevation": "auto",
  "style": "auto"
}

Format
Installation
Usage
- Dependency
- Proguard
Palettes
License

Format

A dynamic theme can be represented as a JSON, URL or a File with .theme extension containing the JSON text. Use the Palettes app for Android to create or share dynamic themes in various formats. However, the most suitable way is to share it via a URL that can be imported easily on various platforms.

JSON

A JSON is the original format for the dynamic theme that provides cross-app functionality.

{
  "backgroundColor": "auto|color",
  "tintBackgroundColor": "auto|color",
  "surfaceColor": "auto|color",
  "tintSurfaceColor": "auto|color",
  "primaryColor": "auto|color",
  "tintPrimaryColor": "auto|color",
  "primaryColorDark": "auto|color",
  "tintPrimaryColorDark": "auto|color",
  "accentColor": "auto|color",
  "tintAccentColor": "auto|color",
  "accentColorDark": "auto|color",
  "tintAccentColorDark": "auto|color",
  "errorColor": "auto|color",
  "tintErrorColor": "auto|color",
  "textPrimaryColor": "auto|color",
  "textPrimaryColorInverse": "auto|color",
  "textSecondaryColor": "auto|color",
  "textSecondaryColorInverse": "auto|color",
  "fontScale": "auto|integer",
  "cornerRadius": "auto|system|integer",
  "backgroundAware": "auto|disable|enable",
  "contrast": "auto|integer",
  "opacity": "auto|integer",
  "elevation": "auto|disable|enable",
  "style": "auto|custom",
  "header": "auto|hide|show"
}

URL

A URL is the short representation of the theme JSON that can be shared on the platforms having a character limit like Twitter. This is the most suitable way to share a dynamic theme that can be imported easily in various apps or platforms.

Mappings

JSON	URL	JSON	URL
{,}		""
Split (Key)	-	Dark \| Inverse	Z
backgroundColor	0	tintBackgroundColor	1
surfaceColor	2	tintSurfaceColor	3
primaryColor	4	tintPrimaryColor	5
primaryColorDark	4Z	tintPrimaryColorDark	7
accentColor	8	tintAccentColor	9
accentColorDark	8Z	tintAccentColorDark	11
errorColor	21	tintErrorColor	22
textPrimaryColor	12	textPrimaryColorInverse	12Z
textSecondaryColor	14	textSecondaryColorInverse	14Z
fontScale	16	cornerRadius	17
backgroundAware	18	contrast	25
opacity	20	elevation	26
style	23	header	19

Values

JSON	URL	JSON	URL
Split (Value)	v	#	X
auto	A	system	M
disable	D	enable	E
hide	H	show	S

Code

A QR code representation of the theme URL to easily share themes across various platforms and devices.

File

A File with .theme extension containing the JSON text. Currently, it is possible to export or import a dynamic theme file on the Android (Java) platform.

Installation

It can be installed by adding the following dependency to your build.gradle file:

dependencies {
    // For AndroidX enabled projects.
    implementation 'com.pranavpandey.android:dynamic-theme:4.6.0'
}

Usage

It can be used in raw JSON format or can be implemented on the Android (Java) platform.

For a complete reference, please read the documentation.

Android (Java)

Just implement the AppTheme or AppWidgetTheme to create a dynamic theme. A possible implementation can be found here.

public class DynamicAppTheme implements AppTheme<DynamicAppTheme> {
    
    ...
    
    @Override
    public @StyleRes int getThemeRes() {
        return themeRes;
    }

    @Override
    public @NonNull DynamicAppTheme setThemeRes(@StyleRes int themeRes) {
        this.themeRes = themeRes;

        return this;
    }

    ...

    @Override
    public @NonNull String toJsonString() {
        return new Gson().toJson(new DynamicAppTheme(this));
    }

    @Override
    public @NonNull String toDynamicString() {
        return new GsonBuilder().setExclusionStrategies(new ExcludeStrategy())
                .registerTypeAdapter(DynamicAppTheme.class, new DynamicThemeTypeAdapter<>())
                .setPrettyPrinting().create().toJson(new DynamicAppTheme(this));
    }
}

Dependency

It depends on the dynamic-utils to perform various internal operations. So, its functions can also be used to perform other useful operations.

Proguard

This library uses Gson and has custom strategy to process the theme data. It will automatically apply the appropriate rules if proguard is enabled in the project.

The following rules will be applied by this library:

# Gson uses generic type information stored in a class file when working with fields.
# Proguard removes such information by default, so configure it to keep all of it.
-keepattributes Signature

# For using Gson annotation.
-keepattributes *Annotation*

# Gson specific classes.
-keep class sun.misc.Unsafe { *; }
-keep class com.google.gson.** { *; }

Palettes

Palettes is a universal manager for apps supporting the dynamic theme on Android. It provides some default configurations that can be extended to create custom ones. Let's give it a try to explore its other useful features.

A collection of theme presets that can be applied in the supported apps.
Extend them to create custom ones according to the requirement.
Preview them natively in the supported apps and widgets.
Experimental option to enable dark mode in devices that don't have a system setting.

Author

Pranav Pandey

License

Copyright 2019-2024 Pranav Pandey

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

pranavpandey/dynamic-theme