+To show a first-time user how to get the most from your app, present +onboarding information at app startup. Here are some examples of onboarding +information: +
+ +The v17 Leanback +support library provides the +{@link android.support.v17.leanback.app.OnboardingFragment} class for +presenting first-time user information. This lesson describes how to use the +{@link android.support.v17.leanback.app.OnboardingFragment} class to present +introductory information that is shown when the app launches for the first +time. {@link android.support.v17.leanback.app.OnboardingFragment} uses TV UI +best practices to present the information in a way that matches TV UI styles, +and is easy to navigate on TV devices.
+ +
+Figure 1. An example +OnboardingFragment.
+ +Your {@link android.support.v17.leanback.app.OnboardingFragment} should +not contain UI elements that require user input, such as buttons and fields. +Similarly, it should not be used as a UI element for a task the user will do +regularly. If you need to present a multi-page UI that requires +user input, consider using a +{@link android.support.v17.leanback.app.GuidedStepFragment}.
+ +To add an {@link android.support.v17.leanback.app.OnboardingFragment} +to your app, implement a class that extends +the {@link android.support.v17.leanback.app.OnboardingFragment} class. Add +this fragment to an activity, either via the activity's layout XML, or +programmatically. Make sure the activity or +fragment is using a theme derived from +{@link android.support.v17.leanback.R.style#Theme_Leanback_Onboarding}, +as described in Customize Themes.
+ +In the {@link android.app.Activity#onCreate onCreate()} method of your +app's main activity, call +{@link android.app.Activity#startActivity startActivity()} +with an {@link android.content.Intent} that points to your +{@link android.support.v17.leanback.app.OnboardingFragment OnboardingFragment's} +parent activity. This ensures that your +{@link android.support.v17.leanback.app.OnboardingFragment} appears as +soon as your app starts.
+ +
To ensure that the +{@link android.support.v17.leanback.app.OnboardingFragment} only appears the +first time that the user starts your app, use a +{@link android.content.SharedPreferences} object +to track whether the user has already viewed the +{@link android.support.v17.leanback.app.OnboardingFragment}. Define a boolean +value that changes to true when the user finishes viewing the +{@link android.support.v17.leanback.app.OnboardingFragment}. Check +this value in your main activity’s +{@link android.app.Activity#onCreate onCreate()}, and only start the +{@link android.support.v17.leanback.app.OnboardingFragment} parent activity if +the value is false. The following example shows an override of +{@link android.app.Activity#onCreate onCreate()} that checks for a +{@link android.content.SharedPreferences} value and, if not set to true, calls +{@link android.app.Activity#startActivity startActivity()} to +show the {@link android.support.v17.leanback.app.OnboardingFragment}:
+ +
+@Override
+protected void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.activity_main);
+ SharedPreferences sharedPreferences =
+ PreferenceManager.getDefaultSharedPreferences(this);
+ // Check if we need to display our OnboardingFragment
+ if (!sharedPreferences.getBoolean(
+ MyOnboardingFragment.COMPLETED_ONBOARDING_PREF_NAME, false)) {
+ // The user hasn't seen the OnboardingFragment yet, so show it
+ startActivity(new Intent(this, OnboardingActivity.class));
+ }
+}
+
+
+After the user views the +{@link android.support.v17.leanback.app.OnboardingFragment}, mark it as viewed +using the {@link android.content.SharedPreferences} object. To do this, in your +{@link android.support.v17.leanback.app.OnboardingFragment}, override +{@link android.support.v17.leanback.app.OnboardingFragment#onFinishFragment +onFinishFragment()} and set your {@link android.content.SharedPreferences} value +to true, as shown in the following example: + +
+@Override
+protected void onFinishFragment() {
+ super.onFinishFragment();
+ // User has seen OnboardingFragment, so mark our SharedPreferences
+ // flag as completed so that we don't show our OnboardingFragment
+ // the next time the user launches the app.
+ SharedPreferences.Editor sharedPreferencesEditor =
+ PreferenceManager.getDefaultSharedPreferences(getContext()).edit();
+ sharedPreferencesEditor.putBoolean(
+ COMPLETED_ONBOARDING_PREF_NAME, true);
+ sharedPreferencesEditor.apply();
+}
+
+
+After you add your +{@link android.support.v17.leanback.app.OnboardingFragment}, you need to define +the onboarding pages. An +{@link android.support.v17.leanback.app.OnboardingFragment} displays content +in a series of ordered pages. Each page can have a title, description, and +several sub-views that can contain images or animations.
+ +
Figure 2. OnboardingFragment +page elements. +
+ +Figure 2 shows an example page with callouts marking customizable page +elements that your {@link android.support.v17.leanback.app.OnboardingFragment} +can provide. The page elements are:
+ +Initialize page information when your +{@link android.support.v17.leanback.app.OnboardingFragment} is first created +or attached to the parent activity, as the system requests page +information when it creates the fragment's view. You can initialize page +information in your class constructor or in an override of +{@link android.app.Fragment#onAttach onAttach()}.
+ +Override each of the following methods that provide page information +to the system:
+ +Override each of the following methods to provide optional sub-views used +to display images or animations:
+ +The system adds the {@link android.view.View} that you create to the page +layout. The following example overrides +{@link android.support.v17.leanback.app.OnboardingFragment#onCreateContentView +onCreateContentView()} and returns an {@link android.widget.ImageView}:
+ +
+private ImageView mContentView;
+...
+@Override
+protected View onCreateContentView(LayoutInflater inflater, ViewGroup container) {
+ mContentView = new ImageView(getContext());
+ mContentView.setScaleType(ImageView.ScaleType.CENTER_INSIDE);
+ mContentView.setImageResource(R.drawable.onboarding_content_view);
+ mContentView.setPadding(0, 32, 0, 32);
+ return mContentView;
+}
+
+
+Your {@link android.support.v17.leanback.app.OnboardingFragment} can start +with an optional logo screen that introduces your app. If you want to display +a {@link android.graphics.drawable.Drawable} as your logo screen, in your +{@link android.support.v17.leanback.app.OnboardingFragment OnboardingFragment's} +{@link android.app.Fragment#onCreate onCreate()} method, call +{@link android.support.v17.leanback.app.OnboardingFragment#setLogoResourceId +setLogoResourceId()} with the ID of your +{@link android.graphics.drawable.Drawable}. The +system will fade in and briefly display this +{@link android.graphics.drawable.Drawable}, and then fade out the +{@link android.graphics.drawable.Drawable} +before displaying the first page of your +{@link android.support.v17.leanback.app.OnboardingFragment}.
+ +If you want to provide a custom animation for your logo screen, instead of +calling +{@link android.support.v17.leanback.app.OnboardingFragment#setLogoResourceId +setLogoResourceId()}, override +{@link android.support.v17.leanback.app.OnboardingFragment#onCreateLogoAnimation +onCreateLogoAnimation()} and return an {@link android.animation.Animator} +object that renders your custom animation, as shown in the following example: +
+ +
+@Override
+public Animator onCreateLogoAnimation() {
+ return AnimatorInflater.loadAnimator(mContext,
+ R.animator.onboarding_logo_screen_animation);
+}
+
+
+The system uses default animations when displaying the first page of your +{@link android.support.v17.leanback.app.OnboardingFragment} and when the user +navigates to a different page. You can customize these animations by +overriding methods in your +{@link android.support.v17.leanback.app.OnboardingFragment}.
+ +To customize the animation that appears on your first page, +override +{@link android.support.v17.leanback.app.OnboardingFragment#onCreateEnterAnimation +onCreateEnterAnimation()} and return an {@link android.animation.Animator}. +The following example creates an +{@link android.animation.Animator} that scales the content view +horizontally:
+ +
+@Override
+protected Animator onCreateEnterAnimation() {
+ Animator startAnimator = ObjectAnimator.ofFloat(mContentView,
+ View.SCALE_X, 0.2f, 1.0f).setDuration(ANIMATION_DURATION);
+ return startAnimator;
+}
+
+
+To customize the animation used when the user navigates to a different page, +override +{@link android.support.v17.leanback.app.OnboardingFragment#onPageChanged +onPageChanged()}. In your +{@link android.support.v17.leanback.app.OnboardingFragment#onPageChanged +onPageChanged()} method, create {@link android.animation.Animator Animators} +that remove the previous page and display the next page, add these to an +{@link android.animation.AnimatorSet}, and play the set. The following +example uses a fade-out animation to remove the previous page, updates the +content view image, and uses a fade-in animation to display the next page:
+ +
+@Override
+protected void onPageChanged(final int newPage, int previousPage) {
+ // Create a fade-out animation used to fade out previousPage and, once
+ // done, swaps the contentView image with the next page's image.
+ Animator fadeOut = ObjectAnimator.ofFloat(mContentView,
+ View.ALPHA, 1.0f, 0.0f).setDuration(ANIMATION_DURATION);
+ fadeOut.addListener(new AnimatorListenerAdapter() {
+ @Override
+ public void onAnimationEnd(Animator animation) {
+ mContentView.setImageResource(pageImages[newPage]);
+ }
+ });
+ // Create a fade-in animation used to fade in nextPage
+ Animator fadeIn = ObjectAnimator.ofFloat(mContentView,
+ View.ALPHA, 0.0f, 1.0f).setDuration(ANIMATION_DURATION);
+ // Create AnimatorSet with our fade-out and fade-in animators, and start it
+ AnimatorSet set = new AnimatorSet();
+ set.playSequentially(fadeOut, fadeIn);
+ set.start();
+}
+
+
+For more details about how to create +{@link android.animation.Animator Animators} and +{@link android.animation.AnimatorSet AnimatorSets}, see + +Property Animations.
+ +Any {@link android.support.v17.leanback.app.OnboardingFragment} +implementation must use either the +{@link android.support.v17.leanback.R.style#Theme_Leanback_Onboarding} theme +or a theme that inherits from +{@link android.support.v17.leanback.R.style#Theme_Leanback_Onboarding}. Set the +theme for your {@link android.support.v17.leanback.app.OnboardingFragment} by +doing one of the following:
+ ++<activity + android:name=".OnboardingActivity" + android:enabled="true" + android:exported="true" + android:theme="@style/Theme.Leanback.Onboarding"> +</activity> ++
+@Override
+public int onProvideTheme() {
+ return R.style.Theme_Leanback_Onboarding;
+}
+
+