Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 546113d4 authored by Tom O'Neill's avatar Tom O'Neill
Browse files

Improve constant names for settings injection API 

- Add timing for getStatus() call to encourage implementors to be fast

- Affects b/10461474

Change-Id: I503cbae5cf27008c587a39ab4e60d8e09daedecc
parent 81e0b1bd

api/current.txt

+4 −3
Original line number Diff line number Diff line
@@ -11959,13 +11959,14 @@ package android.location { 
    ctor public SettingInjectorService(java.lang.String);

    method protected abstract android.location.SettingInjectorService.Status getStatus();

    method protected final void onHandleIntent(android.content.Intent);

    field public static final java.lang.String ACTION_INJECTED_SETTING_CHANGED = "com.android.location.InjectedSettingChanged";

    field public static final java.lang.String ACTION_INJECTED_SETTING_CHANGED = "android.location.InjectedSettingChanged";

    field public static final java.lang.String ACTION_SERVICE_INTENT = "android.location.SettingInjectorService";

    field public static final java.lang.String ATTRIBUTES_NAME = "injected-location-setting";

    field public static final java.lang.String META_DATA_NAME = "android.location.SettingInjectorService";

  }















  public static final class SettingInjectorService.Status {















    ctor public SettingInjectorService.Status(java.lang.String, boolean);













    field public final boolean enabled;













    field public final java.lang.String summary;















  }





























}

























core/res/res/values/attrs.xml



+5
−5




























Original line number
Diff line number
Diff line








@@ -5743,11 +5743,11 @@













         describes an injected "Location services" setting. Note that the status value (subtitle)















         for the setting is specified dynamically by a subclass of SettingInjectorService.















     -->













    <declare-styleable name="InjectedLocationSetting">













        <!-- The user-visible name (title) of the setting. -->













        <attr name="label"/>













        <!-- The icon for the apps covered by the setting. Typically a generic icon for the













             developer. -->













    <declare-styleable name="SettingInjectorService">













        <!-- The title for the preference. -->













        <attr name="title"/>













        <!-- The icon for the preference, should refer to all apps covered by the setting. Typically













             a generic icon for the developer. -->















        <attr name="icon"/>















        <!-- The activity to launch when the setting is clicked on. -->















        <attr name="settingsActivity"/>

































location/java/android/location/SettingInjectorService.java



+56
−38




























Original line number
Diff line number
Diff line








@@ -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 &gt; Location &gt; 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;













 * <pre>















 *     &lt;service android:name="com.example.android.injector.MyInjectorService" &gt;















 *         &lt;intent-filter&gt;













 *             &lt;action android:name="com.android.settings.InjectedLocationSetting" /&gt;













 *             &lt;action android:name="android.location.SettingInjectorService" /&gt;















 *         &lt;/intent-filter&gt;















 *















 *         &lt;meta-data













 *             android:name="com.android.settings.InjectedLocationSetting"













 *             android:name="android.location.SettingInjectorService"















 *             android:resource="@xml/my_injected_location_setting" /&gt;















 *     &lt;/service&gt;















 * </pre>















 * The resource file specifies the static data for the setting:















 * <pre>















 *     &lt;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"















 *     /&gt;















 * </pre>















 * Here:















 * <ul>













 *     <li>label: The {@link Preference#getTitle()} value. The title should make it clear which apps













 *     are affected by the setting, typically by including the name of the developer. For example,













 *     "Acme Corp. ads preferences." </li>













 *     <li>title: The {@link android.preference.Preference#getTitle()} value. The title should make













 *     it clear which apps are affected by the setting, typically by including the name of the













 *     developer. For example, "Acme Corp. ads preferences." </li>















 *













 *     <li>icon: The {@link Preference#getIcon()} value. Typically this will be a generic icon for













 *     the developer rather than the icon for an individual app.</li>













 *     <li>icon: The {@link android.preference.Preference#getIcon()} value. Typically this will be a













 *     generic icon for the developer rather than the icon for an individual app.</li>















 *















 *     <li>settingsActivity: the activity which is launched to allow the user to modify the setting













 *     value  The activity must be in the same package as the subclass of













 *     value.  The activity must be in the same package as the subclass of















 *     {@link SettingInjectorService}. The activity should use your own branding to help emphasize















 *     to the user that it is not part of the system settings.</li>















 * </ul>















 *













 * 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 {













         * <p/>















         * 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;