Chapter 4:Note Pad Example

Note Pad Example

The Note Pad sample application enables users to browse through a list of notes, view details about individual items in the list, edit the items, and add a new item to the list. This section looks at the intent filters declared in its manifest file. (If you're working offline in the SDK, you can find all the source files for this sample application, including its manifest file, at <sdk>/samples/NotePad/index.html. If you're viewing the documentation online, the source files are in the Tutorials and Sample Code section here.)
In its manifest file, the Note Pad application declares three activities, each with at least one intent filter. It also declares a content provider that manages the note data. Here is the manifest file in its entirety:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.android.notepad">
    <application android:icon="@drawable/app_notes"
                 android:label="@string/app_name" >
        <provider android:name="NotePadProvider"
                  android:authorities="com.google.provider.NotePad" />
        <activity android:name="NotesList" android:label="@string/title_notes_list">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <action android:name="android.intent.action.EDIT" />
                <action android:name="android.intent.action.PICK" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.GET_CONTENT" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:mimeType="vnd.android.cursor.item/vnd.google.note" />
            </intent-filter>
        </activity>
        
        <activity android:name="NoteEditor"
                  android:theme="@android:style/Theme.Light"
                  android:label="@string/title_note" >
            <intent-filter android:label="@string/resolve_edit">
                <action android:name="android.intent.action.VIEW" />
                <action android:name="android.intent.action.EDIT" />
                <action android:name="com.android.notepad.action.EDIT_NOTE" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:mimeType="vnd.android.cursor.item/vnd.google.note" />
            </intent-filter>
            <intent-filter>
                <action android:name="android.intent.action.INSERT" />
                <category android:name="android.intent.category.DEFAULT" />
                <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" />
            </intent-filter>
        </activity>
        
        <activity android:name="TitleEditor" 
                  android:label="@string/title_edit_title"
                  android:theme="@android:style/Theme.Dialog">
            <intent-filter android:label="@string/resolve_title">
                <action android:name="com.android.notepad.action.EDIT_TITLE" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.ALTERNATIVE" />
                <category android:name="android.intent.category.SELECTED_ALTERNATIVE" />
                <data android:mimeType="vnd.android.cursor.item/vnd.google.note" />
            </intent-filter>
        </activity>
        
    </application>
</manifest>

The first activity, NotesList, is distinguished from the other activities by the fact that it operates on a directory of notes (the note list) rather than on a single note. It would generally serve as the initial user interface into the application. It can do three things as described by its three intent filters:

1. <intent-filter>
       <action android:name="android.intent.action.MAIN" />
       <category android:name="android.intent.category.LAUNCHER" />
   </intent-filter>

   This filter declares the main entry point into the Note Pad application. The standard MAIN action is an entry point that does not require any other information in the Intent (no data specification, for example), and the LAUNCHER category says that this entry point should be listed in the application launcher.
   

2. <intent-filter>
       <action android:name="android.intent.action.VIEW" />
       <action android:name="android.intent.action.EDIT" />
       <action android:name="android.intent.action.PICK" />
       <category android:name="android.intent.category.DEFAULT" />
       <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" />
   </intent-filter>

   This filter declares the things that the activity can do on a directory of notes. It can allow the user to view or edit the directory (via the VIEW and EDIT actions), or to pick a particular note from the directory (via the PICK action).
   The mimeType attribute of the <data> element specifies the kind of data that these actions operate on. It indicates that the activity can get a Cursor over zero or more items (vnd.android.cursor.dir) from a content provider that holds Note Pad data (vnd.google.note). The Intent object that launches the activity would include a content: URI specifying the exact data of this type that the activity should open.
   Note also the DEFAULT category supplied in this filter. It's there because the Context.startActivity() and Activity.startActivityForResult() methods treat all intents as if they contained the DEFAULT category — with just two exceptions:
   
   • Intents that explicitly name the target activity
   • Intents consisting of the MAIN action and LAUNCHER category
     
   Therefore, the DEFAULT category is required for all filters — except for those with the MAIN action and LAUNCHER category. (Intent filters are not consulted for explicit intents.)
   

3. <intent-filter>
       <action android:name="android.intent.action.GET_CONTENT" />
       <category android:name="android.intent.category.DEFAULT" />
       <data android:mimeType="vnd.android.cursor.item/vnd.google.note" />
   </intent-filter>

   This filter describes the activity's ability to return a note selected by the user without requiring any specification of the directory the user should choose from. The GET_CONTENT action is similar to the PICK action. In both cases, the activity returns the URI for a note selected by the user. (In each case, it's returned to the activity that called startActivityForResult() to start the NoteList activity.) Here, however, the caller specifies the type of data desired instead of the directory of data the user will be picking from.
   The data type, vnd.android.cursor.item/vnd.google.note, indicates the type of data the activity can return — a URI for a single note. From the returned URI, the caller can get a Cursor for exactly one item (vnd.android.cursor.item) from the content provider that holds Note Pad data (vnd.google.note).
   In other words, for the PICK action in the previous filter, the data type indicates the type of data the activity could display to the user. For the GET_CONTENT filter, it indicates the type of data the activity can return to the caller.
   

Given these capabilities, the following intents will resolve to the NotesList activity:

action: android.intent.action.MAIN

Launches the activity with no data specified.

action: android.intent.action.MAIN
category: android.intent.category.LAUNCHER

Launches the activity with no data selected specified. This is the actual intent used by the Launcher to populate its top-level list. All activities with filters that match this action and category are added to the list.

action: android.intent.action.VIEW
data: content://com.google.provider.NotePad/notes

Asks the activity to display a list of all the notes under content://com.google.provider.NotePad/notes. The user can then browse through the list and get information about the items in it.

action: android.intent.action.PICK
data: content://com.google.provider.NotePad/notes

Asks the activity to display a list of the notes under content://com.google.provider.NotePad/notes. The user can then pick a note from the list, and the activity will return the URI for that item back to the activity that started the NoteList activity.

action: android.intent.action.GET_CONTENT
data type: vnd.android.cursor.item/vnd.google.note

Asks the activity to supply a single item of Note Pad data.

The second activity, NoteEditor, shows users a single note entry and allows them to edit it. It can do two things as described by its two intent filters:

1. <intent-filter android:label="@string/resolve_edit">
       <action android:name="android.intent.action.VIEW" />
       <action android:name="android.intent.action.EDIT" />
       <action android:name="com.android.notepad.action.EDIT_NOTE" />
       <category android:name="android.intent.category.DEFAULT" />
       <data android:mimeType="vnd.android.cursor.item/vnd.google.note" />
   </intent-filter>

   The first, primary, purpose of this activity is to enable the user to interact with a single note — to either VIEW the note or EDIT it. (The EDIT_NOTE category is a synonym for EDIT.) The intent would contain the URI for data matching the MIME type vnd.android.cursor.item/vnd.google.note — that is, the URI for a single, specific note. It would typically be a URI that was returned by the PICK or GET_CONTENT actions of the NoteList activity.
   As before, this filter lists the DEFAULT category so that the activity can be launched by intents that don't explicitly specify the NoteEditor class.
   

2. <intent-filter>
       <action android:name="android.intent.action.INSERT" />
       <category android:name="android.intent.category.DEFAULT" />
       <data android:mimeType="vnd.android.cursor.dir/vnd.google.note" />
   </intent-filter>

   The secondary purpose of this activity is to enable the user to create a new note, which it will INSERT into an existing directory of notes. The intent would contain the URI for data matching the MIME type vnd.android.cursor.dir/vnd.google.note — that is, the URI for the directory where the note should be placed.
   

Given these capabilities, the following intents will resolve to the NoteEditor activity:

action: android.intent.action.VIEW
data: content://com.google.provider.NotePad/notes/ID

Asks the activity to display the content of the note identified by ID. (For details on how content: URIs specify individual members of a group, see Content Providers.)

action: android.intent.action.EDIT
data: content://com.google.provider.NotePad/notes/ID

Asks the activity to display the content of the note identified by ID, and to let the user edit it. If the user saves the changes, the activity updates the data for the note in the content provider.

action: android.intent.action.INSERT
data: content://com.google.provider.NotePad/notes

Asks the activity to create a new, empty note in the notes list at content://com.google.provider.NotePad/notes and allow the user to edit it. If the user saves the note, its URI is returned to the caller.

The last activity, TitleEditor, enables the user to edit the title of a note. This could be implemented by directly invoking the activity (by explicitly setting its component name in the Intent), without using an intent filter. But here we take the opportunity to show how to publish alternative operations on existing data:

<intent-filter android:label="@string/resolve_title">
    <action android:name="com.android.notepad.action.EDIT_TITLE" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.ALTERNATIVE" />
    <category android:name="android.intent.category.SELECTED_ALTERNATIVE" />
    <data android:mimeType="vnd.android.cursor.item/vnd.google.note" />
</intent-filter>

The single intent filter for this activity uses a custom action called "com.android.notepad.action.EDIT_TITLE". It must be invoked on a specific note (data type vnd.android.cursor.item/vnd.google.note), like the previous VIEW and EDIT actions. However, here the activity displays the title contained in the note data, not the content of the note itself.
In addition to supporting the usual DEFAULT category, the title editor also supports two other standard categories: ALTERNATIVE and SELECTED_ALTERNATIVE. These categories identify activities that can be presented to users in a menu of options (much as the LAUNCHER category identifies activities that should be presented to user in the application launcher). Note that the filter also supplies an explicit label (via android:label="@string/resolve_title") to better control what users see when presented with this activity as an alternative action to the data they are currently viewing. (For more information on these categories and building options menus, see the PackageManager.queryIntentActivityOptions() and Menu.addIntentOptions() methods.)
Given these capabilities, the following intent will resolve to the TitleEditor activity:

action: com.android.notepad.action.EDIT_TITLE
data: content://com.google.provider.NotePad/notes/ID

Asks the activity to display the title associated with note ID, and allow the user to edit the title.

[http://developer.android.com/guide/developing/devices/emulator.html]

http://mobile.tutsplus.com/tutorials/android/introduction-to-android-development/

http://developer.android.com/guide/topics/intents/intents-filters.html

http://www.vogella.de/articles/AndroidIntent/article.html