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

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

+73 −2

Original line number	Original line	Diff line number	Diff line
	@@ -394,6 +394,11 @@ public final class Control implements Parcelable {
	return this;		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		@NonNull
	public StatelessBuilder setDeviceType(@DeviceTypes.DeviceType int deviceType) {		public StatelessBuilder setDeviceType(@DeviceTypes.DeviceType int deviceType) {
	if (!DeviceTypes.validDeviceType(deviceType)) {		if (!DeviceTypes.validDeviceType(deviceType)) {
	@@ -416,6 +421,10 @@ public final class Control implements Parcelable {
	return this;		return this;
	}		}

			/**
			* @param subtitle the user facing subtitle for the {@link Control}
			* @return {@code this}
			*/
	@NonNull		@NonNull
	public StatelessBuilder setSubtitle(@NonNull CharSequence subtitle) {		public StatelessBuilder setSubtitle(@NonNull CharSequence subtitle) {
	Preconditions.checkNotNull(subtitle);		Preconditions.checkNotNull(subtitle);
	@@ -423,12 +432,22 @@ public final class Control implements Parcelable {
	return this;		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		@NonNull
	public StatelessBuilder setStructure(@Nullable CharSequence structure) {		public StatelessBuilder setStructure(@Nullable CharSequence structure) {
	mStructure = structure;		mStructure = structure;
	return this;		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		@NonNull
	public StatelessBuilder setZone(@Nullable CharSequence zone) {		public StatelessBuilder setZone(@Nullable CharSequence zone) {
	mZone = zone;		mZone = zone;
	@@ -446,12 +465,20 @@ public final class Control implements Parcelable {
	return this;		return this;
	}		}

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

			/**
			* @param customColor a list of colors to override the ones determined by the device type.
			* @return {@code this}
			*/
	@NonNull		@NonNull
	public StatelessBuilder setCustomColor(@Nullable ColorStateList customColor) {		public StatelessBuilder setCustomColor(@Nullable ColorStateList customColor) {
	mCustomColor = 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}		* @return a valid {@link Control}
	*/		*/
	@NonNull		@NonNull
	@@ -482,7 +509,7 @@ public final class Control implements Parcelable {
	/**		/**
	* Builder class for {@link Control}.		* 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:		* It provides the following defaults for non-optional parameters:
	* <ul>		* <ul>
	* <li> Device type: {@link DeviceTypes#TYPE_UNKNOWN}		* <li> Device type: {@link DeviceTypes#TYPE_UNKNOWN}
	@@ -551,6 +578,11 @@ public final class Control implements Parcelable {
	return this;		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		@NonNull
	public StatefulBuilder setDeviceType(@DeviceTypes.DeviceType int deviceType) {		public StatefulBuilder setDeviceType(@DeviceTypes.DeviceType int deviceType) {
	if (!DeviceTypes.validDeviceType(deviceType)) {		if (!DeviceTypes.validDeviceType(deviceType)) {
	@@ -573,6 +605,10 @@ public final class Control implements Parcelable {
	return this;		return this;
	}		}

			/**
			* @param subtitle the user facing subtitle for the {@link Control}
			* @return {@code this}
			*/
	@NonNull		@NonNull
	public StatefulBuilder setSubtitle(@NonNull CharSequence subtitle) {		public StatefulBuilder setSubtitle(@NonNull CharSequence subtitle) {
	Preconditions.checkNotNull(subtitle);		Preconditions.checkNotNull(subtitle);
	@@ -580,12 +616,22 @@ public final class Control implements Parcelable {
	return this;		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		@NonNull
	public StatefulBuilder setStructure(@Nullable CharSequence structure) {		public StatefulBuilder setStructure(@Nullable CharSequence structure) {
	mStructure = structure;		mStructure = structure;
	return this;		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		@NonNull
	public StatefulBuilder setZone(@Nullable CharSequence zone) {		public StatefulBuilder setZone(@Nullable CharSequence zone) {
	mZone = zone;		mZone = zone;
	@@ -603,18 +649,31 @@ public final class Control implements Parcelable {
	return this;		return this;
	}		}

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

			/**
			* @param customColor a list of colors to override the ones determined by the device type.
			* @return {@code this}
			*/
	@NonNull		@NonNull
	public StatefulBuilder setCustomColor(@Nullable ColorStateList customColor) {		public StatefulBuilder setCustomColor(@Nullable ColorStateList customColor) {
	mCustomColor = customColor;		mCustomColor = customColor;
	return this;		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		@NonNull
	public StatefulBuilder setStatus(@Status int status) {		public StatefulBuilder setStatus(@Status int status) {
	if (status < 0 \|\| status >= NUM_STATUS) {		if (status < 0 \|\| status >= NUM_STATUS) {
	@@ -626,6 +685,10 @@ public final class Control implements Parcelable {
	return this;		return this;
	}		}

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

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

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

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

+3 −0

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

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

	// Update this when adding new concrete types. Does not count TYPE_UNKNOWN		// 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	Original line	Diff line number	Diff line
	@@ -19,10 +19,15 @@ package android.service.controls.actions;
	import android.annotation.NonNull;		import android.annotation.NonNull;
	import android.annotation.Nullable;		import android.annotation.Nullable;
	import android.os.Bundle;		import android.os.Bundle;
			import android.service.controls.Control;
			import android.service.controls.templates.ToggleRangeTemplate;
	import android.service.controls.templates.ToggleTemplate;		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 {		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 templateId the identifier of the template that originated this action.
	* @param newState new value for the state displayed by the {@link ToggleTemplate}.		* @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}		* @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		* null is sent when no authentication is needed or has not been
	* requested.		* requested.
	@@ -64,8 +69,7 @@ public final class BooleanAction extends ControlAction {
	/**		/**
	* The new state set for the button in the corresponding {@link ToggleTemplate}.		* 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}		* @return {@code true} if the button was toggled from unchecked to checked.
	* state.
	*/		*/
	public boolean getNewState() {		public boolean getNewState() {
	return mNewState;		return mNewState;

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

+20 −0

Original line number	Original line	Diff line number	Diff line
	@@ -19,15 +19,32 @@ package android.service.controls.actions;
	import android.annotation.NonNull;		import android.annotation.NonNull;
	import android.annotation.Nullable;		import android.annotation.Nullable;
	import android.os.Bundle;		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 {		public final class CommandAction extends ControlAction {

	private static final @ActionType int TYPE = TYPE_COMMAND;		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) {		public CommandAction(@NonNull String templateId, @Nullable String challengeValue) {
	super(templateId, challengeValue);		super(templateId, challengeValue);
	}		}

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

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

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

+17 −1

Original line number	Original line	Diff line number	Diff line
	@@ -21,6 +21,7 @@ import android.annotation.IntDef;
	import android.annotation.NonNull;		import android.annotation.NonNull;
	import android.annotation.Nullable;		import android.annotation.Nullable;
	import android.os.Bundle;		import android.os.Bundle;
			import android.service.controls.Control;
	import android.service.controls.IControlsActionCallback;		import android.service.controls.IControlsActionCallback;
	import android.service.controls.templates.ControlTemplate;		import android.service.controls.templates.ControlTemplate;
	import android.util.Log;		import android.util.Log;
	@@ -31,7 +32,7 @@ import java.lang.annotation.Retention;
	import java.lang.annotation.RetentionPolicy;		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		* The action may have a value to authenticate the input, when the provider has requested it to
	* complete the action.		* complete the action.
	@@ -58,6 +59,9 @@ public abstract class ControlAction {
	})		})
	public @interface ActionType {};		public @interface ActionType {};

			/**
			* Object returned when there is an unparcelling error.
			*/
	public static final @NonNull ControlAction ERROR_ACTION = new ControlAction() {		public static final @NonNull ControlAction ERROR_ACTION = new ControlAction() {
	@Override		@Override
	public int getActionType() {		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;		public static final @ActionType int TYPE_ERROR = -1;

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

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

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

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