Styles API

Overview

The styles API allows applications to both change and get changed colors. This has been introduced in LineageSDK API 9 (March 2018).

Tune the app style basing on system

Changing the app style basing on the system configuration only requires the appcompat-v7 library. The LineageSDK is not needed to customize the app basing on the system style, because the styles API hooks itself into standard android APIs.

Match the global style

In order for your app to match the global style, you need to make your application theme a child of Theme.AppCompat.DayNight. This theme allows to create a dark mode using the -night resources modifier. In day/light mode it inherits from the Theme.AppCompat.Light theme, in night/dark mode it inherits from the Theme.AppCompat theme. The LineageSDK library is not needed in order to make the app follow the system global style.

Here’s an example of how to make your app follow the OkcarOS global style:

res/values/styles.xml

<style name="AppTheme" parent="Theme.AppCompat.DayNight">
    <!-- Use the light statusbar only when in day/light mode -->
    <item name="android:windowLightStatusBar">@bool/is_theme_light</item>
</style>

res/values/bools.xml

<bool name="is_theme_light">true</bool>

res/values-night/bools.xml

<bool name="is_theme_light">false</bool>

Get the current system default accent color

There’s no way to reference this value in a xml resource, but it’s possible to get the system’s accent color using this method:

Kotlin

@ColorInt
private fun getAccentColor(): Int {
    val attr = intArrayOf(android.R.attr.colorAccent)
    val typedArray = obtainStyledAttributes(android.R.style.Theme_DeviceDefault, attr)
    return typedArray.getColor(0, Color.BLACK)
            .also { typedArray.recycle() }
}

Java

@ColorInt
private int getAccentColor() {
    int[] attr = { android.R.attr.colorAccent };
    TypedArray typedArray = obtainStyledAttributes(android.R.style.Theme_DeviceDefault, attr);
    int color = typedArray.getColor(0, Color.BLACK);
    typedArray.recycle();
    return color;
}

Handling non-OkcarOS devices cases

When your app is running on non-OkcarOS devices it will use the light style unless you change it using the AppCompatDelegate’s setDefaultNightMode(Int) method at runtime passing one of those as argument:

Checking if MODE_NIGHT_FOLLOW_SYSTEM is supported

You can find out whether the app can follow the system style by checking the installed LineageSDK version (if any) is at least 9. On the LineageSDK API versions page you can find out how to get the current SDK API level, even without importing the Lineage SDK library itself.

Tune the system style from an app

By importing the LineageSDK library you can access the StyleInterface API that will allow you to set the system global style and accent.

Requesting the permission

In order to be able to use this API you need to get your app granted the lineageos.permission.CHANGE_STYLE permission. This is marked as a dangerous permission so you’ll have to both declare it in the manifest and request it at runtime.

<uses-permission android:name="lineageos.permission.CHANGE_STYLE" />

Changing the global style

In order to change the global style you need to get the StyleInterface instance by using StyleInterface.getInstance(Context). Once you’ve got an instance and you made sure the app has been granted the permission to change styles, you can set the global style choosing one of the 4 possible configurations using the setGlobalStyle(Int, String) method passing one of those as the first argument (the second one is your app’s packageName):

Kotlin

private fun setGlobalStyle(context: Context, turnDark: Boolean) {
    val styleInterface = StyleInterface.getInstance(context)
    // [...] check for permission
    styleInterface.setGlobalStyle(
            if (turnDark) StyleInterface.STYLE_GLOBAL_DARK
            else StyleInterface.STYLE_GLOBAL_LIGHT,
            context.packageName)
}

Java

private void setGlobalStyle(Context context, boolean turnDark) {
    StyleInterface styleInterface = StyleInterface.getInstance(context);
    // [...] check for permission
    styleInterface.setGlobalStyle(turnDark ?
            StyleInterface.STYLE_GLOBAL_DARK : StyleInterface.STYLE_GLOBAL_LIGHT,
            context.getPackageName());
}

Changing the accent style

In order to change the global style you need to get the StyleInterface instance by using StyleInterface.getInstance(Context). Once you’ve got an instance and you made sure the app has been granted the permission to change styles, you can set the global accent choosing one of the 4 possible configurations using the setAccent(String) method passing the accent overlay package name as argument.

You can get a list of trusted accent packages names with the StyleInterface’s getTrustedAccents() method.

Get assistance

If you have any questions or get stuck on any of the steps, feel free to ask on our subreddit or in #OkcarOS on Libera.Chat.

You can also find more information in the LineageSDK javadoc.