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"
}
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.
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"
}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.
| 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 |
| JSON | URL | JSON | URL |
|---|---|---|---|
| Split (Value) | v | # | X |
| auto | A | system | M |
| disable | D | enable | E |
| hide | H | show | S |
A QR code representation of the theme URL to easily share themes across various platforms
and devices.
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.
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'
}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.
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));
}
}It depends on the dynamic-utils to perform various internal operations. So, its functions can also be used to perform other useful operations.
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 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.
Pranav Pandey
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.
