SplashScreen

class SplashScreen

Provides control over the splash screen once the application is started.

On API 31+ (Android 12+) this class calls the platform methods.

Prior API 31, the platform behavior is replicated with the exception of the Animated Vector Drawable support on the launch screen.

Usage of the core-splashscreen library:

To replicate the splash screen behavior from Android 12 on older APIs the following steps need to be taken:

  1. Create a new Theme (e.g Theme.App.Starting) and set its parent to Theme.SplashScreen or Theme.SplashScreen.IconBackground

  2. In your manifest, set the theme attribute of the whole <application> or just the starting <activity> to Theme.App.Starting

  3. In the onCreate method the starting activity, call installSplashScreen just before super.onCreate(). You also need to make sure that postSplashScreenTheme is set to the application's theme. Alternatively, this call can be replaced by Activity#setTheme if a SplashScreen instance isn't needed.

Themes

The library provides two themes: R.style.Theme_SplashScreen and R.style.Theme_SplashScreen_IconBackground. If you wish to display a background right under your icon, the later needs to be used. This ensure that the scale and masking of the icon are similar to the Android 12 Splash Screen.

windowSplashScreenAnimatedIcon: The splash screen icon. On API 31+ it can be an animated vector drawable.

windowSplashScreenAnimationDuration: Duration of the Animated Icon Animation. The value needs to be 0 if the icon is animated.

Note: This has no impact on the time during which the splash screen is displayed and is only used in SplashScreenViewProvider.iconAnimationDurationMillis. If you need to display the splash screen for a longer time, you can use SplashScreen.setKeepOnScreenCondition

windowSplashScreenIconBackgroundColor: To be used in with Theme.SplashScreen.IconBackground. Sets a background color under the splash screen icon.

windowSplashScreenBackground: Background color of the splash screen. Defaults to the theme's ?attr/colorBackground.

postSplashScreenTheme* Theme to apply to the Activity when installSplashScreen is called.

Known incompatibilities:

  • On API < 31, windowSplashScreenAnimatedIcon cannot be animated. If you want to provide an animated icon for API 31+ and a still icon for API <31, you can do so by overriding the still icon with an animated vector drawable in res/drawable-v31.

  • On API < 31, if the value of windowSplashScreenAnimatedIcon is an adaptive icon , it will be cropped and scaled. The workaround is to respectively assign windowSplashScreenAnimatedIcon and windowSplashScreenIconBackgroundColor to the values of the adaptive icon foreground and background.

  • On API 21-22, The icon isn't displayed until the application starts, only the background is visible.

Design

The splash screen icon uses the same specifications as Adaptive Icons . This means that the icon needs to fit within a circle whose diameter is 2/3 the size of the icon. The actual values don't really matter if you use a vector icon.

Specs

  • With icon background (Theme.SplashScreen.IconBackground)

    • Image Size: 240x240 dp

    • Inner Circle diameter: 160 dp

  • Without icon background (Theme.SplashScreen)

    • Image size: 288x288 dp

    • Inner circle diameter: 192 dp

Example: if the full size of the image is 300dp*300dp, the icon needs to fit within a circle with a diameter of 200dp. Everything outside the circle will be invisible (masked).

Summary

Nested types

Condition evaluated to check if the splash screen should remain on screen

Listener to be passed in SplashScreen.setOnExitAnimationListener.

Public companion functions
SplashScreen

Creates a SplashScreen instance associated with this Activity and handles setting the theme to R.attr.postSplashScreenTheme.

Public functions
Unit

Sets the condition to keep the splash screen visible.
Unit

Sets a listener that will be called when the splashscreen is ready to be removed.

Public companion functions

installSplashScreen

fun Activity.installSplashScreen(): SplashScreen

Creates a SplashScreen instance associated with this Activity and handles setting the theme to R.attr.postSplashScreenTheme.

This needs to be called before Activity.setContentView or other view operations on the root view (e.g setting flags).

Alternatively, if a SplashScreen instance is not required, the theme can manually be set using Activity.setTheme.

Public functions

setKeepOnScreenCondition

Added in 1.0.0
fun setKeepOnScreenCondition(condition: SplashScreen.KeepOnScreenCondition): Unit

Sets the condition to keep the splash screen visible.

The splash will stay visible until the condition isn't met anymore. The condition is evaluated before each request to draw the application, so it needs to be fast to avoid blocking the UI.

Parameters
condition: SplashScreen.KeepOnScreenCondition

The condition evaluated to decide whether to keep the splash screen on screen

setOnExitAnimationListener

Added in 1.0.0
fun setOnExitAnimationListener(
    listener: SplashScreen.OnExitAnimationListener
): Unit

Sets a listener that will be called when the splashscreen is ready to be removed.

If a listener is set, the splashscreen won't be automatically removed and the application needs to manually call SplashScreenViewProvider.remove.

IF no listener is set, the splashscreen will be automatically removed once the app is ready to draw.

The listener will be called on the ui thread.

Parameters
listener: SplashScreen.OnExitAnimationListener

The OnExitAnimationListener that will be called when the splash screen is ready to be dismissed.
See also
setKeepOnScreenCondition
SplashScreen.OnExitAnimationListener
SplashScreenViewProvider