Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pranavpandey/dynamic-theme
A text (JSON) based theme engine for Android apps.
https://github.com/pranavpandey/dynamic-theme
android engine library text theme
Last synced: 2 months ago
JSON representation
A text (JSON) based theme engine for Android apps.
- Host: GitHub
- URL: https://github.com/pranavpandey/dynamic-theme
- Owner: pranavpandey
- License: apache-2.0
- Created: 2019-10-12T02:47:42.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-12-07T15:07:22.000Z (about 1 year ago)
- Last Synced: 2024-04-13T13:01:53.352Z (9 months ago)
- Topics: android, engine, library, text, theme
- Language: Java
- Homepage: https://theme.pranavpandey.com
- Size: 2.11 MB
- Stars: 29
- Watchers: 5
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-android - Dynamic Theme - A text (JSON) based theme engine for Android apps. (Uncategorized / Uncategorized)
- awesome-list - pranavpandey/dynamic-theme - A text (JSON) based theme engine for Android apps. (Java)
README
# Dynamic Theme
[](https://www.apache.org/licenses/LICENSE-2.0.html)
[](https://travis-ci.org/pranavpandey/dynamic-theme)
[](https://search.maven.org/artifact/com.pranavpandey.android/dynamic-theme)
A text (JSON) based theme engine for Android 4.0 (API 14) and above.
> It uses [AndroidX][androidx] so, first [migrate][androidx-migrate] your project to AndroidX.
Since v3.1.0, it is dependent on Java 8 due to the dependency on
[Dynamic Utils][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"
}
```
---
## Contents
- [Format](#format)
- [Installation](#installation)
- [Usage](#usage)
- [Dependency](#dependency)
- [Proguard](#proguard)
- [Palettes](#palettes)
- [License](#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.
```json
{
"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:
```groovy
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][documentation].
### Android (Java)
Just implement the [AppTheme][app theme] or [AppWidgetTheme][app widget theme] to create a
dynamic theme. A possible implementation can be found [here][theme implementation].
```java
public class DynamicAppTheme implements AppTheme {
...
@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][dynamic-utils] to perform
various internal operations. So, its functions can also be used to perform other useful operations.
### Proguard
This library uses [Gson][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:
```yml
# 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][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
[](https://github.com/pranavpandey)
[](https://twitter.com/intent/follow?screen_name=pranavpandeydev)
[](https://paypal.me/pranavpandeydev)
---
## 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.
[androidx]: https://developer.android.com/jetpack/androidx
[androidx core]: https://developer.android.com/jetpack/androidx/releases/core
[androidx-migrate]: https://developer.android.com/jetpack/androidx/migrate
[documentation]: https://pranavpandey.github.io/dynamic-theme
[app theme]: ./dynamic-theme/src/main/java/com/pranavpandey/android/dynamic/theme/AppTheme.java
[app widget theme]: ./dynamic-theme/src/main/java/com/pranavpandey/android/dynamic/theme/AppWidgetTheme.java
[theme implementation]: https://github.com/pranavpandey/dynamic-support/blob/master/dynamic-support/src/main/java/com/pranavpandey/android/dynamic/support/model/DynamicAppTheme.java
[dynamic-utils]: https://github.com/pranavpandey/dynamic-utils
[gson]: https://github.com/google/gson
[palettes]: https://play.google.com/store/apps/details?id=com.pranavpandey.theme