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:
-
Create a new Theme (e.g
Theme.App.Starting) and set its parent toTheme.SplashScreenorTheme.SplashScreen.IconBackground -
In your manifest, set the
themeattribute of the whole<application>or just the starting<activity>toTheme.App.Starting -
In the
onCreatemethod the starting activity, callinstallSplashScreenjust beforesuper.onCreate(). You also need to make sure thatpostSplashScreenThemeis set to the application's theme. Alternatively, this call can be replaced by Activity#setTheme if aSplashScreeninstance 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,
windowSplashScreenAnimatedIconcannot 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 inres/drawable-v31. -
On API < 31, if the value of
windowSplashScreenAnimatedIconis an adaptive icon , it will be cropped and scaled. The workaround is to respectively assignwindowSplashScreenAnimatedIconandwindowSplashScreenIconBackgroundColorto the values of the adaptive iconforegroundandbackground. -
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 |
|---|
fun interface SplashScreen.KeepOnScreenConditionCondition evaluated to check if the splash screen should remain on screen |
fun interface SplashScreen.OnExitAnimationListenerListener to be passed in |
Public companion functions |
|
|---|---|
SplashScreen |
Creates a |
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
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
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 |