When is it necessary to use singleTop launchMode in an android widget or application?

Question

I just got burned by a widget. I could see the cause of the problem, but I could not determine why or its solution. My widget was issuing a search (SearchManager) and the activity launched a search dialog, but when it called-back to my widget, it created another reference to the widget (i.e., the thread-id was the same, but the widget-id changed from 65 to 0).

This led me to believe that a new instance was getting created and I searched the documentation for settings that would apply to the problem. Eventually, I stumbled upon the android:launchMode="singleTop" and as soon as I set it in the AndroidManifest, viola! My widget worked.

This took me the better part of two days to debug.

Are there any other situations or is there a more technically-correct answer to my problem?

Zoogloea

I don't think the question title is useful for the contents. I'd hoped to see a question and answers about appropriate use cases for singleTop. This is a bit of development narrative and then a quote from the documentation. – Alaric

@Lot105 - fair enough. Go ahead and add some answers. It was a huge problem that I encountered so I did the "ask and answer your own question" as is suggested by SO. I am certain that your answer contribution(s) and others would improve this Q&A. It has had over 3000 views, so there is clearly interest. I doubt that my answer is the ONLY answer :) And of course, it is a reference and quote from the doc since that is where I got my answer. Personally, I find real value in this style issue / answer as it clarifies DOC. – Zoogloea

I should have been clearer. The question body and answer are useful and interesting in their own right, absolutely. – Alaric

Answer 1

I did more reading in Android Docs -- I could spend a lifetime reading their docs and find a new subtle detail that breaks my brain :) This explains my multiple-instances that I did not expect, however, I configured to occur.

Android Doc on Activity definition for AndroidManifest.xml

The "standard" and "singleTop" modes differ from each other in just one respect: Every time there's new intent for a "standard" activity, a new instance of the class is created to respond to that intent. Each instance handles a single intent. Similarly, a new instance of a "singleTop" activity may also be created to handle a new intent. However, if the target task already has an existing instance of the activity at the top of its stack, that instance will receive the new intent (in an onNewIntent() call); a new instance is not created. In other circumstances — for example, if an existing instance of the "singleTop" activity is in the target task, but not at the top of the stack, or if it's at the top of a stack, but not in the target task — a new instance would be created and pushed on the stack.

Zoogloea

"or if it's at the top of a stack, but not in the target task — a new instance would be created and pushed on the stack." Why? Can someone explain this quoted section further? – Photoengraving

@Photoengraving I believe this scenario is when you use FLAG_ACTIVITY_NEW_TASK. In this case, you don't care about existing task, and you are creating a new task, so your activity becomes the only one in the new task. Correct me if I'm wrong. – Headrick

@Gokhan Arik I don't think that's correct. This is the documentation for FLAG_ACTIVITY_NEW_TASK: "When using this flag, if a task is already running for the activity you are now starting, then a new activity will not be started; instead, the current task will simply be brought to the front of the screen with the state it was last in. See FLAG_ACTIVITY_MULTIPLE_TASK for a flag to disable this behavior." So you see that FLAG_ACTIVITY_NEW_TASK does not create necessarily create a new task - only if necessary. Otherwise it reuses the existing task. – Doornail

Answer 2

Means that if the activity/instance that's been flagged with "singleTop" is not on the top of the stack and you attempt to call it, a new instance will be created and put on top of the stack. In standard mode, you create instances all the time without looking at the stack.

Linalinacre