How to create Android AppWidget that can go into home screen folders and home row (dock)?

Question

I have found several examples of Android apps that have simple widgets that are droppable into home screen folders and the bottom, persistent row on the home screen. For instance, the Gmail label widget, or the Dropbox folder widget. In my attempts to make a similar widget - single cell with icon and text view underneath - the widget can only be by itself on the home screen.

How can I make the most simple widget that can be dropped into a home screen folder or home row just like a normal app icon?

Is it possible what I'm looking for is actually not a widget, but an app icon that would somehow be included in the widget list (but without adding a second app icon in the app list)?

EDIT:

Huge thanks to Kuffs for getting me in the right direction.

The key to this is in what Kuffs points to in the manifest:

...
<intent-filter>
    <action android:name="android.intent.action.CREATE_SHORTCUT" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>
...

As Kuffs mentions, that alone gets your app an entry in the widget list. Good work team.

Answer 1

Widgets can only be placed on the home screen. They cannot be added to the dock on the home screen. Only icons go here.

You need to add a shortcut.

Add the relevant permission to your manifest.

<uses-permission android:name="com.android.launcher.permission.INSTALL_SHORTCUT" />

Create an activity that will create the shortcut and add it to the manifest like the example below.

e.g

    <activity
        android:name=".ShortcutActivity"
        android:label="@string/app_name" android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.CREATE_SHORTCUT" />
            <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </activity>

If you run this app now, you will be offered the opportunity to add your shortcut like the Gmail/Dropbox apps do (The widget screen will list your new shortcut creating activity). Of course, your activity should actually add the shortcut to be useful.

The activity will be started by the OS with startActivityForResult() and therefore it will be expecting an intent inside the returned intent (to be used by the OS in an onActivityResult call). This info found here: https://stackoverflow.com/a/11449443/1399483

So, create an activity that creates a shortcut such as this:

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

    Intent i= new Intent();
    Intent shortcutActivity = new Intent(this, ActivityToLaunch.class);

    i.putExtra(Intent.EXTRA_SHORTCUT_INTENT, shortcutActivity);
    i.putExtra(Intent.EXTRA_SHORTCUT_NAME, "Shortcut Title");
    i.putExtra(Intent.EXTRA_SHORTCUT_ICON_RESOURCE,Intent.ShortcutIconResource.fromContext(this, R.drawable.shortcut_icon));
    setResult(RESULT_OK, i);
    finish();
 }

To use a custom icon rather than a drawable resource, replace the extra EXTRA_SHORTCUT_ICON_RESOURCE with the following:

Bitmap bm; // Set to the image you want to use
i.putExtra(Intent.EXTRA_SHORTCUT_ICON, bm);

Answer 2

Hmm, good question! It's certainly true that widgets, even though 1x1, can't be placed inside a folder or the dock.

Maybe it really isn't a widget that's created after selecting the label/folder, but instead a shortcut is made. The 'widget' is a shortcut and the way to put the shortcut on your homescreen is trough the (select label/folder) 'widget'.

With the right permission and code you can create a shortcut from your sourcecode.