You are right. It is not well documented. The information a developer
needs is scattered in various different places in the documentation,
such as
file:///home/mejohnsn/android-sdk-linux_x86-1.6_r1/docs/guide/topics/fundamentals.html#lcycles,
file:///home/mejohnsn/android-sdk-linux_x86-1.6_r1/docs/guide/topics/fundamentals.html#procthread
and
file:///home/mejohnsn/android-sdk-linux_x86-1.6_r1/docs/reference/android/app/Activity.html
(and perhaps others I never found:()
As if that was not bad enough, words that in English, even in the
technical English of computer science, are used as synonyms (e.g.
'kill', 'terminate', 'destroy', 'bind'), are used in substantially
distinct senses in these documents. And these differences are
themselves not clearly documented.
In order to try to clarify these issues in my own mind, I once did a
dummy Activity I call "ExampleActivity.java", which gathers into one
place what I found at all the above three places and here in the
android developers group. I will include it in this post and see what
you guys think of it: by no means is it the definitive word, I am sure
there are many here who can make improvements via constructive
criticism (please refrain from the other kind;)
In fact, you will recognize in the comments one of the contributors to
this thread, one whose knowledge of the topic is hard to match.
/**
* Copied from online docs on Activity Lifecycle: I am double-checking
* that the comments completely describe Activity programmers'
responsibilities
* for each state transition.
*
* '//R' documents a responsibility.
*/
/**
* ExampleActivity overrides each of the major lifecycle callbacks --
* and a few of the not so major. But no new code is added.
*/
public class ExampleActivity extends Activity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState); //R obligatory
// The activity is being created. 'Entire lifetime' begins
here
//R setup of "global state", e.g View, data<->list bindings,
//R restore activity state saved in Bundle.
//R "initialize essential components of activity", e.g.,
//R database cursors, View.
}
@Override
protected void onStart() {
super.onStart();
// The activity is about to become visible, i.e. 'visible
lifetime' starts here.
//R set up resources needed only for visible lifetime (tr4 not
'global state')
}
/**
* Not in original ExampleActivity.java: included for completeness.
Called
* immediately before onStart() if Activity was still on Activity
stack, user nav.
* back to it instead of starting new activity. Always followed by
onStart()
* and onResume().
*/
@Override
protected void onRestart() {
super.onRestart(); // as usual, call super: obligatory.
//R requery any 'raw' cursors in use here,
//R since they should have been relinquished in onStop().
}
@Override
protected void onResume() {
super.onResume();
// The activity has become visible (it is now "resumed").
// Always called after onStart().
// foreground lifetime starts here, i.e. this Activity is not
// only visible, but has input focus, too. But Dianne
// H. points out it might not actually get focus,"Thus if your
// activity is resumed, it is at the top of the stack, and if
// it asks for input focus it will take it from all other
// activities since those are below it. However windows can
// still be on top of it, which can take input focus away from
// it."
//R open exclusive access devices (e.g. camera), start any
//R animation here
}
@Override
protected void onPause() {
super.onPause(); //R obligatory
// Another activity is taking focus (this activity is
about to be "paused") OR
// the phone is going to sleep.
// foreground lifetime over: hosting process now killable
//R commit unsaved user edits/changes to persistent datastore,
stop
animation,
//R stop any threads/services consuming CPU, i.e. save any state
that should
//R be persisted for user to see "edit in place" model.
//R stop animation here, close "exclusive access" resources
(e.g.
camera)
//
//R "Android in Action" says to save state information here to
be
restored
//R when Activity restarted, but this is rather vague. Yet
//R saving here is much better than waiting for on Stop or
//R onDestroy(), since hosting process killable after returning
//R from onPause().
}
@Override
protected void onStop() {
super.onStop();
// The activity is no longer visible (it is now "stopped"):
// called when another Activity starts. But we are NOT
// guaranteed to get this far.
//R release resources acquired in onStart and not already
//R released in onPause() (sometimes we can wait till now
//R to do database commit, if next Activity does not need
//R the data. In particular, any network/database resources
@Override
protected void onDestroy() {
super.onDestroy();
// The activity is about to be destroyed: entire lifetime is
over
// we are NOT guaranteed to get to this state: hosting process
// might be killed before this.
//R release all remaining resources (database/file handles,
//R threads...)
/**
* Not in original ExampleActivity: added for clarity, since
* this ability IS often forgotten.
* Rationale: when paused or merely stopped, Activity state
* is saved by the system and automatically restored when
* the user navigates back to it: but NOT when the hosting
* process is killed. So to present the same appearance to the
* user, the programmer can use onSaveInstanceState() to
* save and restore it even in this case.
*
* Called on orientation change (or any config change), which
* makes an easy test.
*/
@Override
protected void onSaveInstanceState() {
super.onSaveInstanceState(); // calls
onSaveInstanceState() for
each View in the layout
//R save Activity state here via putString() ktl. for
this
Activity's data members
//R only use for 'transient state' of the UI;
persistent should be
saved in onPause()
//
//R restore during onCreate() or
onRestoreInstanceState().
}
}
}
On Jun 4, 10:20 am, DulcetTone <[email protected]> wrote:
> I feel that the lifecycle (of apps and activities) is not well
> documented. I wish the Javadocs were somehow wikified so the vague
> portions could be collaboratively identified and remedied. I only
> feel I am able to identify places where questions arise, so having the
> ability through OSP (I suppose) to edit these is not such a boon.
>
> My app has longstanding bugs that some phones see and others do not,
> and they tie into lifecycle issues.
> Here are some of the questions I find I still have.
>
> The Activity documentation does not clearly indicate the difference
> between an activity being paused versus being stopped. Is a paused
> activity one which has 1 or more pixels obscured by another, and a
> stopped activity one that has zero visible pixels?
>
> I have never found just where the the interrelationships between
> finish() and state diagram paths toward pause/stop and the use of the
> back button or home button are detailed.
>
> Shouldn't "finish()" have been called "destroy()" so it is consistent
> with the state diagram? If so, the documentation should spell out how
> finish()ing an activity will start it through the path to onDestroy().
>
> There seems to be no direct means by which my app (or do I mean my
> task?) can know when one of its activities is active versus not. This
> has confused me for one and a half years (it matters when you make an
> app that has a voice user interface and want the recognition to be
> stopped when the user presses home, but not when he presses "back" on
> an activity that returns another of your app's activities to the
> fore). It gets worse in that starting a new activity does not deliver
> you an Activity instance immediately, making instance counting
> difficult.
>
> I have resisted using the manifest flags for "singletop" et al
> entirely, as several readings of their description have not conveyed a
> clear understanding.
>
> tone
--
You received this message because you are subscribed to the Google
Groups "Android Developers" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/android-developers?hl=en
