Added in API level 19

SettingInjectorService


abstract class SettingInjectorService : Service
kotlin.Any
   ↳ android.content.Context
   ↳ android.content.ContextWrapper
   ↳ android.app.Service
   ↳ android.location.SettingInjectorService

Dynamically specifies the summary (subtitle) and enabled status of a preference injected into the list of app settings displayed by the system settings app

For use only by apps that are included in the system image, for preferences that affect multiple apps. Location settings that apply only to one app should be shown within that app, rather than in the system settings.

To add a preference to the list, a subclass of SettingInjectorService must be declared in the manifest as so:
<service android:name="com.example.android.injector.MyInjectorService" >
          <intent-filter>
              <action android:name="android.location.SettingInjectorService" />
          </intent-filter>
 
          <meta-data
              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:title="@string/injected_setting_title"
          android:icon="@drawable/ic_acme_corp"
          android:settingsActivity="com.example.android.injector.MySettingActivity"
      />
  
Here:
  • title: The 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."
  • icon: The android.preference.Preference#getIcon() value. Typically this will be a generic icon for the developer rather than the icon for an individual app.
  • 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 SettingInjectorService. The activity should use your own branding to help emphasize to the user that it is not part of the system settings.
To ensure a good user experience, your android.app.Application#onCreate(), onGetSummary(), and onGetEnabled() methods must all be fast. If any are slow, it can delay the display of settings values for other apps as well. Note further that all are called on your app's UI thread.

For compactness, only one copy of a given setting should be injected. If each account has a distinct value for the setting, then the onGetSummary() value should represent a summary of the state across all of the accounts and settingsActivity should display the value for each account.

Summary

Constants
static String

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.

static String

Intent action that must be declared in the manifest for the subclass.

static String

Name of the XML tag that includes the attributes for the setting.

static String

Name of the meta-data tag used to specify the resource file that includes the settings attributes.

Inherited constants
Public constructors

Constructor.

Public methods
IBinder?
onBind(intent: Intent!)

Unit
onStart(intent: Intent!, startId: Int)

Int
onStartCommand(intent: Intent!, flags: Int, startId: Int)

static Unit

Sends a broadcast to refresh the injected settings on location settings page.

Protected methods
abstract Boolean

Returns the android.preference.Preference#isEnabled() value.

abstract String!

Returns the android.preference.Preference#getSummary() value (allowed to be null or empty).

Inherited functions

Constants

ACTION_INJECTED_SETTING_CHANGED

Added in API level 19
static val ACTION_INJECTED_SETTING_CHANGED: String

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.

Value: "android.location.InjectedSettingChanged"

ACTION_SERVICE_INTENT

Added in API level 19
static val ACTION_SERVICE_INTENT: String

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.

Value: "android.location.SettingInjectorService"

ATTRIBUTES_NAME

Added in API level 19
static val ATTRIBUTES_NAME: String

Name of the XML tag that includes the attributes for the setting.

Value: "injected-location-setting"

META_DATA_NAME

Added in API level 19
static val META_DATA_NAME: String

Name of the meta-data tag used to specify the resource file that includes the settings attributes.

Value: "android.location.SettingInjectorService"

Public constructors

SettingInjectorService

Added in API level 19
SettingInjectorService(name: String!)

Constructor.

Parameters
name String!: used to identify your subclass in log messages

Public methods

onBind

Added in API level 19
fun onBind(intent: Intent!): IBinder?
Parameters
intent Intent!: The Intent that was used to bind to this service, as given to android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Return
IBinder? Return an IBinder through which clients can call on to the service.

onStart

Added in API level 19
fun onStart(
    intent: Intent!,
    startId: Int
): Unit

onStartCommand

Added in API level 19
fun onStartCommand(
    intent: Intent!,
    flags: Int,
    startId: Int
): Int
Parameters
intent Intent!: The Intent supplied to android.content.Context#startService, as given. This may be null if the service is being restarted after its process has gone away, and it had previously returned anything except START_STICKY_COMPATIBILITY.
flags Int: Additional data about this start request. Value is either 0 or a combination of android.app.Service#START_FLAG_REDELIVERY, and android.app.Service#START_FLAG_RETRY
startId Int: A unique integer representing this specific request to start. Use with stopSelfResult(int).
Return
Int The return value indicates what semantics the system should use for the service's current started state. It may be one of the constants associated with the START_CONTINUATION_MASK bits. Value is android.app.Service#START_STICKY_COMPATIBILITY, android.app.Service#START_STICKY, android.app.Service#START_NOT_STICKY, or android.app.Service#START_REDELIVER_INTENT

refreshSettings

Added in API level 29
static fun refreshSettings(context: Context): Unit

Sends a broadcast to refresh the injected settings on location settings page.

Parameters
context Context: This value cannot be null.

Protected methods

onGetEnabled

Added in API level 19
protected abstract fun onGetEnabled(): Boolean

Returns the android.preference.Preference#isEnabled() value. Should not perform unpredictably-long operations such as network access--see the running-time comments in the class-level javadoc.

Note that to prevent churn in the settings list, there is no support for dynamically choosing to hide a setting. Instead you should have this method return false, which will disable the setting and its link to your setting activity. One reason why you might choose to do this is if android.provider.Settings.Secure#LOCATION_MODE is android.provider.Settings.Secure#LOCATION_MODE_OFF.

It is possible that the user may click on the setting before this method returns, so your settings activity must handle the case where it is invoked even though the setting is disabled. The simplest approach may be to simply call android.app.Activity#finish() when disabled.
Return
Boolean the android.preference.Preference#isEnabled() value

onGetSummary

Added in API level 19
protected abstract fun onGetSummary(): String!

Returns the android.preference.Preference#getSummary() value (allowed to be null or empty). Should not perform unpredictably-long operations such as network access--see the running-time comments in the class-level javadoc.

This method is called on KitKat, and Q+ devices.
Return
String! the android.preference.Preference#getSummary() value