From 546113d4c290f36bf21b1e9c7b93d1592df17fce Mon Sep 17 00:00:00 2001 From: Tom O'Neill Date: Fri, 30 Aug 2013 10:09:39 -0700 Subject: Improve constant names for settings injection API - Add timing for getStatus() call to encourage implementors to be fast - Affects b/10461474 Change-Id: I503cbae5cf27008c587a39ab4e60d8e09daedecc --- .../android/location/SettingInjectorService.java | 94 +++++++++++++--------- 1 file changed, 56 insertions(+), 38 deletions(-) (limited to 'location/java') diff --git a/location/java/android/location/SettingInjectorService.java b/location/java/android/location/SettingInjectorService.java index 0b0f05d43639..8181f4eaa4f3 100644 --- a/location/java/android/location/SettingInjectorService.java +++ b/location/java/android/location/SettingInjectorService.java @@ -22,12 +22,11 @@ import android.os.Bundle; import android.os.Message; import android.os.Messenger; import android.os.RemoteException; -import android.preference.Preference; import android.util.Log; /** - * Dynamically specifies the summary (subtile) and enabled status of a preference injected into - * the "Settings > Location > Location services" list. + * Dynamically specifies the summary (subtitle) and enabled status of a preference injected into + * the list of location services displayed by the system settings app. * * The location services list is intended for use only by preferences that affect multiple apps from * the same developer. Location settings that apply only to one app should be shown within that app, @@ -39,52 +38,47 @@ import android.util.Log; * 
  *     <service android:name="com.example.android.injector.MyInjectorService" >
  *         <intent-filter>
- *             <action android:name="com.android.settings.InjectedLocationSetting" />
+ *             <action android:name="android.location.SettingInjectorService" />
  *         </intent-filter>
  *
  *         <meta-data
- *             android:name="com.android.settings.InjectedLocationSetting"
+ *             android:name="android.location.SettingInjectorService"
  *             android:resource="@xml/my_injected_location_setting" />
  *     </service>
  *
* The resource file specifies the static data for the setting: * 
  *     <injected-location-setting xmlns:android="http://schemas.android.com/apk/res/android"
- *         android:label="@string/injected_setting_label"
- *         android:icon="@drawable/ic_launcher"
+ *         android:title="@string/injected_setting_title"
+ *         android:icon="@drawable/ic_acme_corp"
  *         android:settingsActivity="com.example.android.injector.MySettingActivity"
  *     />
  *
* Here: * * - * To ensure a good user experience, your {@link #onHandleIntent(Intent)} must complete within - * 200 msec even if your app is not already running. This means that both - * {@link android.app.Application#onCreate()} and {@link #getStatus()} must be fast. If you exceed - * this time, then this can delay the retrieval of settings status for other apps as well. - * - * For consistency, the label and {@link #getStatus()} values should be provided in all of the - * locales supported by the system settings app. The text should not contain offensive language. + * To ensure a good user experience, the average time from the start of + * {@link #startService(Intent)} to the end of {@link #onHandleIntent(Intent)} should be less + * than 300 msec even if your app is not already in memory. This means that both your + * {@link android.app.Application#onCreate()} and your {@link #getStatus()} must be fast. If + * either is slow, it can delay the display of settings values for other apps as well. * * For compactness, only one copy of a given setting should be injected. If each account has a * distinct value for the setting, then the {@link #getStatus()} value should represent a summary of * the state across all of the accounts and {@code settingsActivity} should display the value for * each account. - * - * Apps that violate these guidelines will be taken down from the Google Play Store and/or flagged - * as malware. */ // TODO: is there a public list of supported locales? // TODO: is there a public list of guidelines for settings text? @@ -93,6 +87,30 @@ public abstract class SettingInjectorService extends IntentService { private static final String TAG = "SettingInjectorService"; + /** + * Intent action that must be declared in the manifest for the subclass. Used to start the + * service to read the dynamic status for the setting. + */ + public static final String ACTION_SERVICE_INTENT = "android.location.SettingInjectorService"; + + /** + * Name of the meta-data tag used to specify the resource file that includes the settings + * attributes. + */ + public static final String META_DATA_NAME = "android.location.SettingInjectorService"; + + /** + * Name of the XML tag that includes the attributes for the setting. + */ + public static final String ATTRIBUTES_NAME = "injected-location-setting"; + + /** + * Intent action a client should broadcast when the value of one of its injected settings has + * changed, so that the setting can be updated in the UI. + */ + public static final String ACTION_INJECTED_SETTING_CHANGED = + "android.location.InjectedSettingChanged"; + /** * Name of the bundle key for the string specifying the summary for the setting (e.g., "ON" or * "OFF"). @@ -115,13 +133,6 @@ public abstract class SettingInjectorService extends IntentService { */ public static final String MESSENGER_KEY = "messenger"; - /** - * Intent action a client should broadcast when the value of one of its injected settings has - * changed, so that the setting can be updated in the UI. - */ - public static final String ACTION_INJECTED_SETTING_CHANGED = - "com.android.location.InjectedSettingChanged"; - private final String mName; /** @@ -169,7 +180,10 @@ public abstract class SettingInjectorService extends IntentService { } /** - * Reads the status of the setting. + * Reads the status of the setting. Should not perform unpredictably-long operations such as + * network access--see the running-time comments in the class-level javadoc. + * + * @return the status of the setting value */ protected abstract Status getStatus(); @@ -179,12 +193,16 @@ public abstract class SettingInjectorService extends IntentService { public static final class Status { /** - * The {@link Preference#getSummary()} value + * The {@link android.preference.Preference#getSummary()} value. + * + * @hide */ public final String summary; /** - * The {@link Preference#isEnabled()} value + * The {@link android.preference.Preference#isEnabled()} value. + * + * @hide */ public final boolean enabled; @@ -193,9 +211,8 @@ public abstract class SettingInjectorService extends IntentService { *

* Note that to prevent churn in the settings list, there is no support for dynamically * choosing to hide a setting. Instead you should provide a {@code enabled} value of false, - * which will gray the setting out and disable the link from "Settings > Location" - * to your setting activity. One reason why you might choose to do this is if - * {@link android.provider.Settings.Secure#LOCATION_MODE} + * which will disable the setting and its link to your setting activity. One reason why you + * might choose to do this is if {@link android.provider.Settings.Secure#LOCATION_MODE} * is {@link android.provider.Settings.Secure#LOCATION_MODE_OFF}. * * It is possible that the user may click on the setting before you return a false value for @@ -203,8 +220,9 @@ public abstract class SettingInjectorService extends IntentService { * though the setting is disabled. The simplest approach may be to simply call * {@link android.app.Activity#finish()} when disabled. * - * @param summary the {@link Preference#getSummary()} value (allowed to be null or empty) - * @param enabled the {@link Preference#isEnabled()} value + * @param summary the {@link android.preference.Preference#getSummary()} value (allowed to + * be null or empty) + * @param enabled the {@link android.preference.Preference#isEnabled()} value */ public Status(String summary, boolean enabled) { this.summary = summary; -- cgit v1.2.3-59-g8ed1b