This library simulates
onResume() life cycle events. But, what does that actually mean? For the purposes of this library, the following definitions apply:
An app is considered to be paused when the app is no longer visible to the user. By definition, this means that when an app is paused, none of the
Activitys that belong to the app are visible to the user.
Along similar lines,
An app is considered to be resumed when at least one
Activityfrom the app is visible to the user.
For more details about why these definitions were chosen, take a look at this blog post.
Note that when a user is using your app, if the device orientation is changed, the user can be considered to be continuing viewing your app. Thus, in general, device orientation changes should not be treated as app pause events.
Please see CHANGELOG.md file in the project root for a detailed change log
New in v2.0
v1.0 of this library did not take into account the device rotations. Hence, when you rotated the device,
onStop() would be called on all the activities, all clients would "un-bind", and your
onAppPause() would be called followed by
v2.0 takes device rotations into account. By default, device rotations do not trigger app pause events. This behavior can be altered using the
See the Appendices at the end of this document for more details regarding the API and implementation changes.
How to Use
android-app-pause is provided as an Android Library project. To use it, follow these steps:
android-app-pauseas a dependent library to your Android Application Project.
AbstractAppPauseApplicationand override the methods
- For every Activity in your app:
AbstractAppPauseActivity, instead of
- (Optional): If you want device rotations to trigger app pauses, call
setTreatRotationAsAppPausewith a value of
Check out the sample project to see how it is used.
In some cases, it may not possible for you to extend
AbstractAppPauseActivity. This could happen if you are already inheriting from some other base Activity like one of the Sherlock* Activities from ActionBar Sherlock. In such cases, you can replicate the functionality of
AbstractAppPauseActivity in your Activities. Take a look at the source for
Just remember that you need to perform these steps in every
Activity in your app.
When to Use
This library is useful when your app has several
Activitys and you wish to stop or pause certain "app-wide" background tasks when your app as a whole "goes into the background". There are some background tasks that you would want to keep running as long as user is interacting with your app. However, when user is no longer actively interacting with your app, you would wish to stop/pause these background tasks.
Typical actions you might want to perform when you app "pauses" are:
- Clearing scheduled Alarms,.
- Stopping HTTP communication.
- Unregistering from broadcasts.
- Stop monitoring the battery
- ... and the like
Similarly, you would want to reverse these actions as soon as your app "returns to the foreground".
Note that this library is not useful if your app has just a single
Activity or two. In such cases, you could use the
Activity life-cycle methods
onResume() to start/stop background tasks.
If you want to improve this library, fork away. Pull requests are welcome. The appendices at the end of this document contain information for library developers.
Why is this a Library Project?
Well, it doesn't have to be. The library could just as well have been made into a .jar file that you can include in the libs/ folder of your app. I decided to make it an Android Library project to keep room for future enhancements. Also, I really don't like the idea of making a regular Java project and adding
android.jar as a dependency in order to make it compile.
Appendix 1: API Changes
AbstractAppActiveServiceclass has been removed.
AbstractAppPauseApplicationhas been introduced.
AbstractAppPauseActivityno longer has a
setTreatRotationAsAppPausemethod has been added to
Please note that the removals above are not deprecations. I decided not to maintain the old procedure of using
Service. See the section on Implementation Changes below to know more about the reason.
Appendix 2: Implementation changes
The high-level functioning of v1.0 of this library was as follows:
- Create a bound
Activity, bind the above
Activity, unbind the above
onBind()method of the
Servicerepresents an App resume.
onDestroy()method of the
Servicerepresents an App pause.
As you can see, this approach does not take device rotations into account. Basically, what you want to do is this:
onStop()is being called because the device orientation is being changed, then do not perform the unbind.
However, if you bind a Service to an Activity but do not unbind it before the Activity is destroyed, then you get a
ServiceConnectionLeaked error at runtime.
To work around this, v2.0 of this library discards the
Service altogether. Instead, it uses a simple counter mechanism in the custom
Application class (
AbstractAppPauseApplication). The functioning is now as follows:
- In the
Applicationclass, maintain an integer counter.
- in every Activity, if
onStart()is not being called as result of an orientation change, increment this counter.
- In every
onStop()is not being called as result of an orientation change, decrement the counter.
- When the count gets incremented from 0 to 1, the app has resumed.
- When the count gets decremented from 1 to 0, the app has paused.
Copyright 2013 Kiran Rao 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.