Tab Stacker

Additional

Language
Java
Version
1.1.0 (Dec 7, 2018)
Created
Nov 30, 2016
Updated
Dec 7, 2018
Owner
Arnaud Guyon (smart-fun)
Contributor
Arnaud Guyon (smart-fun)
1
Activity
Badge
Generate
Download
Source code
APK file

Blurb

Tab Stacker

Tab Stacker is an Android library that handles Multiple Fragment History, like it is done on iOS Apps.

Each Tab has its own stack of Fragments, that can be added, replaced or removed using animations. When the user presses back, the top Fragment from the current Tab stack is dismissed.

When a complete stack is removed and restored (during a Tab change, or a system cleanup like when rotating the device), a save and restore mechanism allows you to keep your Fragments up-to-date.

Tab Stacker uses Support Fragments. It is recommended to always use Support Fragments as they are compatible with older devices, and the last bugs are fixed for all devices. See how to migrate to Support Fragment in the wiki.

How to use##

Like any Tabbed application, you need a placeholder where put the Fragments.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical" >

    <!-- This is the Fragment Holder -->
    <FrameLayout
        android:id="@+id/fragmentHolder"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:layout_weight="100" />

    <!-- Here you could include your bottom bar with tabs -->
    <include
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        layout="@layout/myCustomTabs" />

</LinearLayout>

At Activity creation, you need to create the TabStacker, and restore its state by calling restoreInstance.

When the activity is saving its state, you also need to save the TabStacker state. Call the TabStacker.saveInstance() before super.saveInstance() so that the TabStacker takes the hand in the save / restore process of the Fragments.

public class MainActivity extends FragmentActivity {

    private TabStacker mTabStacker;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setContentView(R.layout.main_activity);

        mTabStacker = new TabStacker(getSupportFragmentManager(), R.id.fragmentHolder);
        
        if (savedInstanceState != null) {
            mTabStacker.restoreInstance(savedInstanceState);
            String selectedTab = mTabStacker.getCurrentTabName();
            // do something like highlight the selected tab...
        }
    }
    
    @Override
    protected void onSaveInstanceState(Bundle outState) {
        // Keep this first
        if (mTabStacker != null) {
            mTabStacker.saveInstance(outState);
        }

        super.onSaveInstanceState(outState);
    }
    
    // will be called by the Fragments when they build their view, so that the View hierarchy will be retored.
    public void restoreView(Fragment fragment, View view) {
        mTabStacker.restoreView(fragment, view);
    }
    
}

To handle the Back button it is quite simple:

    @Override
    public void onBackPressed() {
        if (!mTabStacker.onBackPressed()) {
            super.onBackPressed();
        }
    }

Pushing Fragments

On Android there are 2 ways to push Fragments: Add or Replace (try the Sample App to better see the difference). When you Add a Fragment, the previous one stays in place and can be seen with transparency for example. When you Replace a Fragment, the previous one is removed from the screen and a new one is displayed instead. For both Add & Replace you can use animations.

    // optional animation
    AnimationSet animation = new AnimationSet(R.anim.slide_from_right, R.anim.slide_to_left, R.anim.slide_from_left, R.anim.slide_to_right);

    mTabStacker.addFragment(fragment, animation);
    // OR
    mTabStacker.replaceFragment(fragment, animation);

Tab Switch

When the user clicks on a tab, the TabStack will save the stack of Fragments of the current Tab, and then restore the stack of Fragment of the new Tab. If the new Tab is empty, you'll have to push the 1st Fragment.

    private void onClickOnTab(String tabName) {
        if (!mTabStacker.switchToTab(tabName)) {    // Try to switch to the TAB STACK
            // no fragment yet on this stack -> push the 1st fragment of the stack
            MyFragment fragment = MyFragment.createInstance(some parameters if necessary);
            mTabStacker.replaceFragment(fragment, null);  // no animation
        }
    }

I recommend to use the Fragment.createInstance pattern instead of new Fragment, so that all the logic for creating / saving / restoring the fragment parameters stays in the Fragment code.

Fragment Code

Your Fragment must inherit from Support Fragments and implement the TabStackInterface.

import android.support.v4.app.Fragment;

If your Fragment uses arguments, they will be automatically saved and restored.

The callbacks onSaveTabFragmentInstance and onRestoreTabFragmentInstance are replacing the Fragment.onSaveInstance() mechanism.

public class MyFragment extends Fragment implements TabStacker.TabStackInterface {

    @Override
    public void onTabFragmentPresented(TabStacker.PresentReason reason) {
    }

    @Override
    public void onTabFragmentDismissed(TabStacker.DismissReason reason) {
    }

    @Override
    public View onSaveTabFragmentInstance(Bundle outState) {
    }

    @Override
    public void onRestoreTabFragmentInstance(Bundle savedInstanceState) {
    }

}

Let's put a concrete example with a Fragment that has:

  • a title that is defined by arguments
  • a String that is changed dynamically but you want to save & restore when necessary
  • a View hierarchy that you want to save and restore when necessary

Note that for saving the View hierarchy you'll have to keep a reference to that view, because getView() is always null when a cleanup occurs.

public class MyFragment extends Fragment implements TabStacker.TabStackInterface {

    private static final String ARGUMENT_TITLE = "title";
    private static final String DYNAMIC_IMPORTANT = "important";
    
    private View mView;  // keep a reference to the inflated view

    // createInstance() pattern with arguments
    public static MyFragment createInstance(String title) {
        MyFragment fragment = new MyFragment();
        Bundle bundle = new Bundle();
        bundle.putString(ARGUMENT_TITLE, title);
        fragment.setArguments(bundle);
        return fragment;
    }
    
    @Override
    public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
        mView = inflater.inflate(R.layout.testfragment, container, false);
        return mView;
    }
    
    @Override
    public void onViewCreated(View view, @Nullable Bundle savedInstanceState) {
        super.onViewCreated(view, savedInstanceState);

        // retrieve the arguments to set the Title
        Bundle arguments = getArguments();
        String title = arguments.getString(ARGUMENT_TITLE);
        TextView titleView = (TextView) view.findViewById(R.id.titleView);
        titleView.setText(title);
        
        // Restore the View hierarchy (the Activity holds the TabStacker)
        MainActivity activity = (MainActivity) getActivity();
        activity.restoreView(this, view);
        
    }
    
        @Override
    public View onSaveTabFragmentInstance(Bundle outState) {
        outState.putString(DYNAMIC_IMPORTANT, "my important string to save");
        return mView; // so that the View hierarchy can be saved
    }

    @Override
    public void onRestoreTabFragmentInstance(Bundle savedInstanceState) {
        String importantString = savedInstanceState.getString(DYNAMIC_IMPORTANT);
    }

}

Okay that's it for a full implementation of Fragments with TabStacker.

See other potential tips in the wiki.

You can experiment and download the Tab Stacker Sample App on Google Play

Installation with gradle

Add the following maven{} line to your PROJECT build.gradle file

allprojects {
    repositories {
        jcenter()
        maven { url "https://jitpack.io" }    // add this line
    }
}

Add the libary dependency to your APP build.gradle file

dependencies {
    implement 'com.github.smart-fun:TabStacker:1.0.4'    // add this line
}

Troubeshooting

I can click on the Fragment behind the top Fragment

You have called addFragment() so the previous Fragment is still behind and is clickable. If you don't want the previous Fragment to stay behind, call replaceFragment() instead. If you just don't want it to be clickable, set clickable="true" in the top fragment layout, so that all clicks that are not intercepted by buttons will be stopped.

I got an IllegalStateException (aka State Loss Exception)

When you do asynchronous calls and then you want to change the Fragment (for example after a webservice call), the Fragment may have been removed or the Activity finished. In these cases you should not try to change the Fragments. Add these tests before trying to change the Fragments:

// code in Activity
if (isActive()) { // be sure that the Activity is still there
    mTabStacker.replaceFragment(...)
}

// or code in Fragment
Activity activity = getActivity();
if ((activity != null) && !isDetached()) { // be sure the fragment is still there
    activity.doSomethingWithTheFragment();
}

Note that there are known bugs in Android where this exception is thrown and should not.

Issue 207269

Issue 25517

A workaround to fix that is to catch the exception, but the Fragment won't be pushed anyway.

    try {
        mTabStacker.replaceFragment(...);
    } catch (IllegalStateException exception) {
        // too bad but it did not crash at least
    }

Library License

Copyright 2016-2018 Arnaud Guyon

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.