60 Android Hacks: Handling Lights-Out Mode

Since the early beginnings of Android, the whole system has had a status bar on top. In Android Honeycomb, the status bar was moved to the bottom of the screen. Applications such as games or image viewers need the full attention of the user, and most of them take the whole screen to display. For instance, in the default Gallery application, when you click on an image, it’s shown full screen without anything else.

Originally Authored by Carlos Sessa

Imagine you need to provide this feature in your application and it needs to be compatible with every Android version. In this hack, we’ll build a simple application that will have a red background and, when we press it, the app will enter lights-out mode. We’ll first take care of Android 2.x and 3.x separately, but afterward we’ll merge them into a single implementation.

60 Android Hacks

By Carlos Sessa
Most games or image viewers take the whole screen to display.  In this article, based on a technique presented in 60 Android Hacks, the author shows you how to build a simple application that enters lights-out mode when the background is pressed.  The best of all, it is cross-compatible between Android 2.x and 3.x.

Android 2.x

We’ll first take care of the Android 2.x code. In Android 2.x, we have the concept of full-screen mode. The idea behind full-screen mode is allowing the application’s window to use the entire display space.
We’re also interested in another concept: the application’s title. The application’s title is the gray bar we get on the upper part of the screen. Here’s he code to create the effect:

Listing 1 Removing the application title in Android 2.x

public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    requestWindowFeature(Window.FEATURE_NO_TITLE);                     #1

    setContentView(R.layout.main);
    mContentView = findViewById(R.id.content);
    mContentView.setOnClickListener(new OnClickListener() {            #2
        @Override
        public void onClick(View v) {

            Window w = getWindow();
            if(mUseFullscreen) {                                       #3
             w.addFlags(
             WindowManager.LayoutParams.FLAG_FULLSCREEN);

             w.clearFlags(
             WindowManager.LayoutParams.FLAG_FORCE_NOT_FULLSCREEN);

            } else {
             w.addFlags(
             WindowManager.LayoutParams.FLAG_FORCE_NOT_FULLSCREEN);

             w.clearFlags(
             WindowManager.LayoutParams.FLAG_FULLSCREEN);
            }

            mUseFullscreen = !mUseFullscreen;
       }
    });
}

The code is self-explanatory. In #1, we ask to remove the title bar. This needs to be done before the setContentView() call is made and, unfortunately, it can’t be done dynamically. In #2, we make the common setContentView() call and we ask for a reference to the root element of our view. This element will work as an on-off switch for the full-screen mode.

The last part of the code states how the full-screen mode should work. You can see in #3 how a field variable is used to toggle the status.

Android 3.x

In Android 3.x, the concepts explained for Android 2.x vary a little. The title bar ends up being the Action Bar on the upper part of the screen, and the status bar is at the bottom of the screen.

An important change in Android 3.x is that there are no physical buttons; they’re all placed in the status bar. Because of that, the status bar can’t be dismissed but it can be dimmed. Here’s the code:

Listing 2 Dimming the status bar in Android 3.x

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    mContentView = findViewById(R.id.content);                         #1

    mContentView.setOnSystemUiVisibilityChangeListener(                #2
            new OnSystemUiVisibilityChangeListener() {

                public void onSystemUiVisibilityChange(int visibility) {

                    ActionBar actionBar = getActionBar();

                    if (actionBar != null) {
                        mContentView.setSystemUiVisibility(visibility);

                        if (visibility == View.STATUS_BAR_VISIBLE) {   #3
                            actionBar.show();
                        } else {
                            actionBar.hide();
                        }
                    }
                }
            });

    mContentView.setOnClickListener(new OnClickListener() {            #4
        public void onClick(View v) {

            if (mContentView.getSystemUiVisibility() ==
                View.STATUS_BAR_VISIBLE) {

                mContentView.setSystemUiVisibility(
                    View.STATUS_BAR_HIDDEN);

            } else {
                mContentView.setSystemUiVisibility(
                    View.STATUS_BAR_VISIBLE);
            }
        }
    });
}

In a similar way to what we did before, we get a reference to the root element of our view in #1. In Honeycomb, views have a new method called setOnSystemUiVisibilityChangeListener(). This was created to have a place to receive callbacks when the system bar visibility changes. In #2, I used this method to hide or show the Action Bar depending on the visibility parameter, as you can see in #3. In #4, we set a click listener to the root view where we toggle the system UI visibility, which basically means turning on and off the lights-out mode.

Merging both worlds in a single Activity

We showed how to handle both scenarios in the different Android versions, but it’d be nice if it were cross-compatible. We can create an Activity that handles both cases but we need to do it using an if statement that checks the Android version.

Listing 3 Checking the Android version

if ( Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB ) {        #1
    configure3x();
} else {
  configure2x();
}

To create the if statement, I used the Build class. As you can see in #1, the Build class also has a VERSION_CODES inner class that can be used to check which version the device is running.

Summary

You’ll find out that everything I did here can be done using styles. Doing it with styles is okay if you’re not willing to support this feature dynamically. You should be aware that hiding the status bar will forbid the user for seeing notifications and might cause the user to close your app just to see what’s going on. On the other hand, using lights-out mode in Android is a cool way of immersing the user in your application experience.

   

Here are some other Manning titles you might be interested in:

Android in Action, Third Edition
W. Frank Ableson, Robi Sen, Chris King, and C. Enrique Ortiz




Android in Practice
Charlie Collins, Michael D. Galpin, and Matthias Kaeppler




Objective-C Fundamentals
Christopher K. Fairbairn, Johannes Fahrenkrug, and Collin Ruffenach