Merge "Add docs to Controls API" into rvc-dev am: 0b66590fbf am: ec88375968 (582b849e) · Commits · e / os / android_frameworks_base

core/java/android/service/controls/Control.java

+73 −2

Original line number	Diff line number	Diff line
		@@ -394,6 +394,11 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* @param deviceType the device type for the {@link Control}. Setting an invalid value not
		* in {@link DeviceTypes} will set it to {@link DeviceTypes#TYPE_UNKNOWN}.
		* @return {@code this}
		*/
		@NonNull
		public StatelessBuilder setDeviceType(@DeviceTypes.DeviceType int deviceType) {
		if (!DeviceTypes.validDeviceType(deviceType)) {
		@@ -416,6 +421,10 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* @param subtitle the user facing subtitle for the {@link Control}
		* @return {@code this}
		*/
		@NonNull
		public StatelessBuilder setSubtitle(@NonNull CharSequence subtitle) {
		Preconditions.checkNotNull(subtitle);
		@@ -423,12 +432,22 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* @param structure the user facing name of the structure for the {@link Control}.
		* {@code null} indicates that it's not associated with any structure.
		* @return {@code this}
		*/
		@NonNull
		public StatelessBuilder setStructure(@Nullable CharSequence structure) {
		mStructure = structure;
		return this;
		}

		/**
		* @param zone the user facing name of the zone for the {@link Control}. {@code null}
		* indicates that it's not associated with any zone.
		* @return {@code this}
		*/
		@NonNull
		public StatelessBuilder setZone(@Nullable CharSequence zone) {
		mZone = zone;
		@@ -446,12 +465,20 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* @param customIcon an {@link Icon} to override the one determined by the device type.
		* @return {@code this}
		*/
		@NonNull
		public StatelessBuilder setCustomIcon(@Nullable Icon customIcon) {
		mCustomIcon = customIcon;
		return this;
		}

		/**
		* @param customColor a list of colors to override the ones determined by the device type.
		* @return {@code this}
		*/
		@NonNull
		public StatelessBuilder setCustomColor(@Nullable ColorStateList customColor) {
		mCustomColor = customColor;
		@@ -459,7 +486,7 @@ public final class Control implements Parcelable {
		}

		/**
		* Build a {@link Control}
		* Build a stateless {@link Control}
		* @return a valid {@link Control}
		*/
		@NonNull
		@@ -482,7 +509,7 @@ public final class Control implements Parcelable {
		/**
		* Builder class for {@link Control}.
		*
		* This class facilitates the creation of {@link Control}.
		* This class facilitates the creation of {@link Control} with an associated state.
		* It provides the following defaults for non-optional parameters:
		* <ul>
		* <li> Device type: {@link DeviceTypes#TYPE_UNKNOWN}
		@@ -551,6 +578,11 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* @param deviceType the device type for the {@link Control}. Setting an invalid value not
		* in {@link DeviceTypes} will set it to {@link DeviceTypes#TYPE_UNKNOWN}.
		* @return {@code this}
		*/
		@NonNull
		public StatefulBuilder setDeviceType(@DeviceTypes.DeviceType int deviceType) {
		if (!DeviceTypes.validDeviceType(deviceType)) {
		@@ -573,6 +605,10 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* @param subtitle the user facing subtitle for the {@link Control}
		* @return {@code this}
		*/
		@NonNull
		public StatefulBuilder setSubtitle(@NonNull CharSequence subtitle) {
		Preconditions.checkNotNull(subtitle);
		@@ -580,12 +616,22 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* @param structure the user facing name of the structure for the {@link Control}.
		* {@code null} indicates that it's not associated with any structure.
		* @return {@code this}
		*/
		@NonNull
		public StatefulBuilder setStructure(@Nullable CharSequence structure) {
		mStructure = structure;
		return this;
		}

		/**
		* @param zone the user facing name of the zone for the {@link Control}. {@code null}
		* indicates that it's not associated with any zone.
		* @return {@code this}
		*/
		@NonNull
		public StatefulBuilder setZone(@Nullable CharSequence zone) {
		mZone = zone;
		@@ -603,18 +649,31 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* @param customIcon an {@link Icon} to override the one determined by the device type.
		* @return {@code this}
		*/
		@NonNull
		public StatefulBuilder setCustomIcon(@Nullable Icon customIcon) {
		mCustomIcon = customIcon;
		return this;
		}

		/**
		* @param customColor a list of colors to override the ones determined by the device type.
		* @return {@code this}
		*/
		@NonNull
		public StatefulBuilder setCustomColor(@Nullable ColorStateList customColor) {
		mCustomColor = customColor;
		return this;
		}

		/**
		* @param status the status of the {@link Control}. Setting an invalid value not in
		* {@link Control} will set it to {@link Control#STATUS_UNKNOWN}.
		* @return {@code this}
		*/
		@NonNull
		public StatefulBuilder setStatus(@Status int status) {
		if (status < 0 \|\| status >= NUM_STATUS) {
		@@ -626,6 +685,10 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* @param controlTemplate a template for the {@link Control}
		* @return {@code this}
		*/
		@NonNull
		public StatefulBuilder setControlTemplate(@NonNull ControlTemplate controlTemplate) {
		Preconditions.checkNotNull(controlTemplate);
		@@ -633,6 +696,10 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* @param statusText a user facing text representing the status of the {@link Control}.
		* @return {@code this}
		*/
		@NonNull
		public StatefulBuilder setStatusText(@NonNull CharSequence statusText) {
		Preconditions.checkNotNull(statusText);
		@@ -640,6 +707,10 @@ public final class Control implements Parcelable {
		return this;
		}

		/**
		* Build a stateless {@link Control}
		* @return a valid {@link Control}
		*/
		@NonNull
		public Control build() {
		return new Control(mControlId,

core/java/android/service/controls/DeviceTypes.java

+3 −0

Original line number	Diff line number	Diff line
		@@ -21,6 +21,9 @@ import android.annotation.IntDef;
		import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;

		/**
		* Device types for {@link Control}.
		*/
		public class DeviceTypes {

		// Update this when adding new concrete types. Does not count TYPE_UNKNOWN

core/java/android/service/controls/actions/BooleanAction.java

+9 −5

Original line number	Diff line number	Diff line
		@@ -19,10 +19,15 @@ package android.service.controls.actions;
		import android.annotation.NonNull;
		import android.annotation.Nullable;
		import android.os.Bundle;
		import android.service.controls.Control;
		import android.service.controls.templates.ToggleRangeTemplate;
		import android.service.controls.templates.ToggleTemplate;

		/**
		* Action sent by a {@link ToggleTemplate}
		* Action sent by user toggling a {@link Control} between checked/unchecked.
		*
		* This action is available when the {@link Control} was constructed with either a
		* {@link ToggleTemplate} or a {@link ToggleRangeTemplate}.
		*/
		public final class BooleanAction extends ControlAction {

		@@ -40,8 +45,8 @@ public final class BooleanAction extends ControlAction {
		}

		/**
		* @param templateId the identifier of the {@link ToggleTemplate} that originated this action.
		* @param newState new value for the state displayed by the {@link ToggleTemplate}.
		* @param templateId the identifier of the template that originated this action.
		* @param newState new value for the state displayed by the template.
		* @param challengeValue a value sent by the user along with the action to authenticate. {@code}
		* null is sent when no authentication is needed or has not been
		* requested.
		@@ -64,8 +69,7 @@ public final class BooleanAction extends ControlAction {
		/**
		* The new state set for the button in the corresponding {@link ToggleTemplate}.
		*
		* @return {@code true} if the button was toggled from an {@code off} state to an {@code on}
		* state.
		* @return {@code true} if the button was toggled from unchecked to checked.
		*/
		public boolean getNewState() {
		return mNewState;

core/java/android/service/controls/actions/CommandAction.java

+20 −0

Original line number	Diff line number	Diff line
		@@ -19,15 +19,32 @@ package android.service.controls.actions;
		import android.annotation.NonNull;
		import android.annotation.Nullable;
		import android.os.Bundle;
		import android.service.controls.Control;
		import android.service.controls.templates.StatelessTemplate;

		/**
		* A simple {@link ControlAction} indicating that the user has interacted with a {@link Control}
		* created using a {@link StatelessTemplate}.
		*/
		public final class CommandAction extends ControlAction {

		private static final @ActionType int TYPE = TYPE_COMMAND;

		/**
		* @param templateId the identifier of the {@link StatelessTemplate} that originated this
		* action.
		* @param challengeValue a value sent by the user along with the action to authenticate. {@code}
		* null is sent when no authentication is needed or has not been
		* requested.
		*/
		public CommandAction(@NonNull String templateId, @Nullable String challengeValue) {
		super(templateId, challengeValue);
		}

		/**
		* @param templateId the identifier of the {@link StatelessTemplate} that originated this
		* action.
		*/
		public CommandAction(@NonNull String templateId) {
		this(templateId, null);
		}
		@@ -40,6 +57,9 @@ public final class CommandAction extends ControlAction {
		super(b);
		}

		/**
		* @return {@link ControlAction#TYPE_COMMAND}
		*/
		@Override
		public int getActionType() {
		return TYPE;

core/java/android/service/controls/actions/ControlAction.java

+17 −1

Original line number	Diff line number	Diff line
		@@ -21,6 +21,7 @@ import android.annotation.IntDef;
		import android.annotation.NonNull;
		import android.annotation.Nullable;
		import android.os.Bundle;
		import android.service.controls.Control;
		import android.service.controls.IControlsActionCallback;
		import android.service.controls.templates.ControlTemplate;
		import android.util.Log;
		@@ -31,7 +32,7 @@ import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;

		/**
		* An abstract action that is executed from a {@link ControlTemplate}.
		* An abstract action indicating a user interaction with a {@link Control}.
		*
		* The action may have a value to authenticate the input, when the provider has requested it to
		* complete the action.
		@@ -58,6 +59,9 @@ public abstract class ControlAction {
		})
		public @interface ActionType {};

		/**
		* Object returned when there is an unparcelling error.
		*/
		public static final @NonNull ControlAction ERROR_ACTION = new ControlAction() {
		@Override
		public int getActionType() {
		@@ -65,6 +69,9 @@ public abstract class ControlAction {
		}
		};

		/**
		* The identifier of {@link #ERROR_ACTION}
		*/
		public static final @ActionType int TYPE_ERROR = -1;

		/**
		@@ -77,10 +84,19 @@ public abstract class ControlAction {
		*/
		public static final @ActionType int TYPE_FLOAT = 2;

		/**
		* The identifier of {@link MultiFloatAction}.
		*/
		public static final @ActionType int TYPE_MULTI_FLOAT = 3;

		/**
		* The identifier of {@link ModeAction}.
		*/
		public static final @ActionType int TYPE_MODE = 4;

		/**
		* The identifier of {@link CommandAction}.
		*/
		public static final @ActionType int TYPE_COMMAND = 5;