From 22ad5f2139dd456ac31fb4691683678ca281de59 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Wed, 15 Jan 2014 18:43:15 -0800 Subject: update common intents guide to add calendar and alarms. Change-Id: I515c6c982104f37b04ef0eddfd0ba8a99e619077 --- docs/html/guide/components/intents-common.jd | 311 ++++++++++++++++++++++++++- 1 file changed, 305 insertions(+), 6 deletions(-) (limited to 'docs/html') diff --git a/docs/html/guide/components/intents-common.jd b/docs/html/guide/components/intents-common.jd index f09ef9f..b81fc98 100644 --- a/docs/html/guide/components/intents-common.jd +++ b/docs/html/guide/components/intents-common.jd @@ -11,6 +11,18 @@ page.tags="IntentFilter"
    +
  1. Alarm Clock +
      +
    1. Create an alarm
      2. +
    2. Create a timer
      3. +
    3. Show all alarms
      4. +
    +
    2. +
  2. Calendar +
      +
    1. Add a calendar event
      2. +
    +
  3. Camera
    1. Capture a picture or video and return it
      2. @@ -116,6 +128,292 @@ the intent.

      + + + + +

      Alarm Clock

      + + +

      Create an alarm

      + +

      To create a new alarm, use the {@link android.provider.AlarmClock#ACTION_SET_ALARM} +action and specify alarm details such as the time and message using extras defined below.

      + +

      Note: Only the hour, minutes, and message extras are available +since Android 2.3 (API level 9). The other extras were added in later versions of the platform.

      + +
      +
      Action
      +
      {@link android.provider.AlarmClock#ACTION_SET_ALARM}
      + +
      Data URI
      +
      None
      + +
      MIME Type
      +
      None +
      + +
      Extras
      +
      +
      +
      {@link android.provider.AlarmClock#EXTRA_HOUR}
      +
      The hour for the alarm.
      +
      {@link android.provider.AlarmClock#EXTRA_MINUTES}
      +
      The minutes for the alarm.
      +
      {@link android.provider.AlarmClock#EXTRA_MESSAGE}
      +
      A custom message to identify the alarm.
      +
      {@link android.provider.AlarmClock#EXTRA_DAYS}
      +
      An {@link java.util.ArrayList} including each week day on which this alarm should + be repeated. Each day must be declared with an integer from the {@link java.util.Calendar} + class such as {@link java.util.Calendar#MONDAY}. +

      For a one-time alarm, do not specify this extra.

      +
      {@link android.provider.AlarmClock#EXTRA_RINGTONE}
      +
      A {@code content:} URI specifying a ringtone to use with the alarm, or {@link + android.provider.AlarmClock#VALUE_RINGTONE_SILENT} for no ringtone. +

      To use the default ringtone, do not specify this extra.

      +
      {@link android.provider.AlarmClock#EXTRA_VIBRATE}
      +
      A boolean specifying whether to vibrate for this alarm.
      +
      {@link android.provider.AlarmClock#EXTRA_SKIP_UI}
      +
      A boolean specifying whether the responding app should skip its UI when setting the alarm. + If true, the app should bypass any confirmation UI and simply set the specified alarm.
      +
      +
      + + +
      + +

      Example intent:

      +
      +public void createAlarm(String message, int hour, int minutes) {
+    Intent intent = new Intent(AlarmClock.ACTION_SET_ALARM)
+            .putExtra(AlarmClock.EXTRA_MESSAGE, message)
+            .putExtra(AlarmClock.EXTRA_HOUR, hour)
+            .putExtra(AlarmClock.EXTRA_MINUTES, minutes);
+    if (intent.resolveActivity(getPackageManager()) != null) {
+        startActivity(intent);
+    }
+}
+
      + +
      Note: +

      In order to invoke the {@link +android.provider.AlarmClock#ACTION_SET_ALARM} intent, your app must have the +{@link android.Manifest.permission#SET_ALARM} permission:

      +
      +<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />
+
      +
      + + +

      Example intent filter:

      +
      +<activity ...>
+    <intent-filter>
+        <action android:name="android.intent.action.SET_ALARM" />
+        <category android:name="android.intent.category.DEFAULT" />
+    </intent-filter>
+</activity>
+
      + + + +

      Create a timer

      + +

      To create a countdown timer, use the {@link android.provider.AlarmClock#ACTION_SET_TIMER} +action and specify timer details such as the duration using extras defined below.

      + +

      Note: This intent was added +in Android 4.4 (API level 19).

      + +
      +
      Action
      +
      {@link android.provider.AlarmClock#ACTION_SET_TIMER}
      + +
      Data URI
      +
      None
      + +
      MIME Type
      +
      None +
      + +
      Extras
      +
      +
      +
      {@link android.provider.AlarmClock#EXTRA_LENGTH}
      +
      The length of the timer in seconds.
      +
      {@link android.provider.AlarmClock#EXTRA_MESSAGE}
      +
      A custom message to identify the timer.
      +
      {@link android.provider.AlarmClock#EXTRA_SKIP_UI}
      +
      A boolean specifying whether the responding app should skip its UI when setting the timer. + If true, the app should bypass any confirmation UI and simply start the specified timer.
      +
      +
      + + +
      + +

      Example intent:

      +
      +public void startTimer(String message, int seconds) {
+    Intent intent = new Intent(AlarmClock.ACTION_SET_TIMER)
+            .putExtra(AlarmClock.EXTRA_MESSAGE, message)
+            .putExtra(AlarmClock.EXTRA_LENGTH, seconds)
+            .putExtra(AlarmClock.EXTRA_SKIP_UI, true);
+    if (intent.resolveActivity(getPackageManager()) != null) {
+        startActivity(intent);
+    }
+}
+
      + +
      Note: +

      In order to invoke the {@link +android.provider.AlarmClock#ACTION_SET_TIMER} intent, your app must have the +{@link android.Manifest.permission#SET_ALARM} permission:

      +
      +<uses-permission android:name="com.android.alarm.permission.SET_ALARM" />
+
      +
      + + +

      Example intent filter:

      +
      +<activity ...>
+    <intent-filter>
+        <action android:name="android.intent.action.SET_TIMER" />
+        <category android:name="android.intent.category.DEFAULT" />
+    </intent-filter>
+</activity>
+
      + + + + + +

      Show all alarms

      + +

      To show the list of alarms, use the {@link android.provider.AlarmClock#ACTION_SHOW_ALARMS} +action.

      + +

      Although not many apps will invoke this intent (it's primarily used by system apps), +any app that behaves as an alarm clock should implement +this intent filter and respond by showing the list of current alarms.

      + +

      Note: This intent was added +in Android 4.4 (API level 19).

      + +
      +
      Action
      +
      {@link android.provider.AlarmClock#ACTION_SHOW_ALARMS}
      + +
      Data URI
      +
      None
      + +
      MIME Type
      +
      None +
      +
      + +

      Example intent filter:

      +
      +<activity ...>
+    <intent-filter>
+        <action android:name="android.intent.action.SHOW_ALARMS" />
+        <category android:name="android.intent.category.DEFAULT" />
+    </intent-filter>
+</activity>
+
      + + + + + + +

      Calendar

      + + +

      Add a calendar event

      + +

      To add a new event to the user's calendar, use the {@link android.content.Intent#ACTION_INSERT} +action and specify the data URI with {@link android.provider.CalendarContract.Events#CONTENT_URI +Events.CONTENT_URI}. You can then specify various event details using extras defined below.

      + +
      +
      Action
      +
      {@link android.content.Intent#ACTION_INSERT}
      + +
      Data URI
      +
      {@link android.provider.CalendarContract.Events#CONTENT_URI +Events.CONTENT_URI}
      + +
      MIME Type
      +
      {@code "vnd.android.cursor.dir/event"} +
      + +
      Extras
      +
      +
      +
      {@link android.provider.CalendarContract#EXTRA_EVENT_ALL_DAY}
      +
      A boolean specifying whether this is an all-day event.
      +
      {@link android.provider.CalendarContract#EXTRA_EVENT_BEGIN_TIME}
      +
      The start time of the event (milliseconds since epoch).
      +
      {@link android.provider.CalendarContract#EXTRA_EVENT_END_TIME}
      +
      The end time of the event (milliseconds since epoch).
      +
      {@link android.provider.CalendarContract.EventsColumns#TITLE}
      +
      The event title.
      +
      {@link android.provider.CalendarContract.EventsColumns#DESCRIPTION}
      +
      The event description.
      +
      {@link android.provider.CalendarContract.EventsColumns#EVENT_LOCATION}
      +
      The event location.
      +
      {@link android.content.Intent#EXTRA_EMAIL}
      +
      A comma-separated list of email addresses that specify the invitees.
      +
      +

      Many more event details can be specified using the constants defined in the + {@link android.provider.CalendarContract.EventsColumns} class.

      +
      + + +
      + +

      Example intent:

      +
      +public void addEvent(String title, String location, Calendar begin, Calendar end) {
+    Intent intent = new Intent(Intent.ACTION_INSERT)
+            .setData(Events.CONTENT_URI)
+            .putExtra(Events.TITLE, title)
+            .putExtra(Events.EVENT_LOCATION, location)
+            .putExtra(CalendarContract.EXTRA_EVENT_BEGIN_TIME, begin)
+            .putExtra(CalendarContract.EXTRA_EVENT_END_TIME, end);
+    if (intent.resolveActivity(getPackageManager()) != null) {
+        startActivity(intent);
+    }
+}
+
      + + +

      Example intent filter:

      +
      +<activity ...>
+    <intent-filter>
+        <action android:name="android.intent.action.INSERT" />
+        <data android:mimeType="vnd.android.cursor.dir/event" />
+        <category android:name="android.intent.category.DEFAULT" />
+    </intent-filter>
+</activity>
+
      + + + + + + + + + + + + +

      Camera

      @@ -211,6 +509,7 @@ in an extra named "data".

      +

      Contacts/People App

      @@ -427,7 +726,7 @@ constants in {@link android.provider.ContactsContract.Intents.Insert}.

      The type is inferred from contact URI.
      -
      Extras (optional)
      +
      Extras
      One or more of the extras defined in {@link android.provider.ContactsContract.Intents.Insert} so you can populate fields of the contact details.
      @@ -469,7 +768,7 @@ constants in {@link android.provider.ContactsContract.Intents.Insert}.
      MIME Type
      {@link android.provider.ContactsContract.Contacts#CONTENT_TYPE Contacts.CONTENT_TYPE}
      -
      Extras (optional)
      +
      Extras
      One or more of the extras defined in {@link android.provider.ContactsContract.Intents.Insert}.
      @@ -523,7 +822,7 @@ and include email details such as the recipient and subject using the extra keys -
      Extras (optional)
      +
      Extras
      {@link android.content.Intent#EXTRA_EMAIL Intent.EXTRA_EMAIL}
      @@ -648,7 +947,7 @@ object returned by {@link android.content.Intent#getClipData()}.

      The MIME type corresponding to the file type the user should select.
      -
      Extras (optional)
      +
      Extras
      {@link android.content.Intent#EXTRA_ALLOW_MULTIPLE} @@ -768,7 +1067,7 @@ primary MIME type in {@link android.content.Intent#setType setType()} to {@code
      The MIME type corresponding to the file type the user should select.
      -
      Extras (optional)
      +
      Extras
      {@link android.content.Intent#EXTRA_MIME_TYPES} @@ -1135,7 +1434,7 @@ details such as the phone number, subject, and message body using the extra keys
      -
      Extras (optional)
      +
      Extras
      "subject"
      -- cgit v1.1