Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Add docs to Controls API" into rvc-dev am: 0b66590fbf

Browse Source 
Change-Id: If040ebd16b746cc6c2308aff70e783757b8fdc96
This commit is contained in:
Automerger Merge Worker
2020-02-26 20:25:33 +00:00
parent a0945729c8 0b66590fbf
commit ec88375968
11 changed files with 225 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
core/java/android/service/controls/Control.java
View File

@@ -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,

3
core/java/android/service/controls/DeviceTypes.java
View File

@@ -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

14
core/java/android/service/controls/actions/BooleanAction.java
View File

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

20
core/java/android/service/controls/actions/CommandAction.java
View File

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

18
core/java/android/service/controls/actions/ControlAction.java
View File

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

24
core/java/android/service/controls/actions/ModeAction.java
View File

@@ -19,7 +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.TemperatureControlTemplate;
/**
* Action sent by the user to indicate a change of mode.
*
* This action is available when the {@link Control} was created with a
* {@link TemperatureControlTemplate}.
*/
public final class ModeAction extends ControlAction {
private static final @ActionType int TYPE = TYPE_MODE;
@@ -27,16 +35,32 @@ public final class ModeAction extends ControlAction {
private final int mNewMode;
/**
* @return {@link ControlAction#TYPE_MODE}.
*/
@Override
public int getActionType() {
return TYPE;
}
/**
* @param templateId the identifier of the {@link TemperatureControlTemplate} that originated
* this action.
* @param newMode new value for the mode.
* @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 ModeAction(@NonNull String templateId, int newMode, @Nullable String challengeValue) {
super(templateId, challengeValue);
mNewMode = newMode;
}
/**
* @param templateId the identifier of the {@link TemperatureControlTemplate} that originated
* this action.
* @param newMode new value for the mode.
*/
public ModeAction(@NonNull String templateId, int newMode) {
this(templateId, newMode, null);
}

15
core/java/android/service/controls/templates/ControlTemplate.java
View File

@@ -57,6 +57,9 @@ public abstract class ControlTemplate {
}
};
/**
* Object returned when there is an unparcelling error.
*/
public static final @NonNull ControlTemplate ERROR_TEMPLATE = new ControlTemplate("") {
@Override
public int getTemplateType() {
@@ -80,6 +83,9 @@ public abstract class ControlTemplate {
})
public @interface TemplateType {}
/**
* Type identifier of {@link #ERROR_TEMPLATE}.
*/
public static final @TemplateType int TYPE_ERROR = -1;
/**
@@ -102,10 +108,19 @@ public abstract class ControlTemplate {
*/
public static final @TemplateType int TYPE_THUMBNAIL = 3;
/**
* Type identifier of {@link ToggleRangeTemplate}.
*/
public static final @TemplateType int TYPE_TOGGLE_RANGE = 6;
/**
* Type identifier of {@link TemperatureControlTemplate}.
*/
public static final @TemplateType int TYPE_TEMPERATURE = 7;
/**
* Type identifier of {@link StatelessTemplate}.
*/
public static final @TemplateType int TYPE_STATELESS = 8;
private @NonNull final String mTemplateId;

3
core/java/android/service/controls/templates/RangeTemplate.java
View File

@@ -19,7 +19,6 @@ package android.service.controls.templates;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.os.Bundle;
import android.os.Parcel;
import android.service.controls.Control;
import android.service.controls.actions.FloatAction;
@@ -85,7 +84,7 @@ public final class RangeTemplate extends ControlTemplate {
}
/**
* Construct a new {@link RangeTemplate} from a {@link Parcel}.
* Construct a new {@link RangeTemplate} from a {@link Bundle}.
*
* @throws IllegalArgumentException if the parameters passed do not make a valid range
* @see RangeTemplate#RangeTemplate(String, float, float, float, float, CharSequence)

16
core/java/android/service/controls/templates/StatelessTemplate.java
View File

@@ -18,22 +18,36 @@ package android.service.controls.templates;
import android.annotation.NonNull;
import android.os.Bundle;
import android.service.controls.Control;
import android.service.controls.actions.CommandAction;
/**
* A template for a {@link Control} which has no state.
*
* @see CommandAction
*/
public final class StatelessTemplate extends ControlTemplate {
/**
* @return {@link ControlTemplate#TYPE_STATELESS}
*/
@Override
public int getTemplateType() {
return TYPE_STATELESS;
}
/**
* @param b
* Construct a new {@link StatelessTemplate} from a {@link Bundle}
* @hide
*/
StatelessTemplate(@NonNull Bundle b) {
super(b);
}
/**
* Construct a new {@link StatelessTemplate}
* @param templateId the identifier for this template
*/
public StatelessTemplate(@NonNull String templateId) {
super(templateId);
}

24
core/java/android/service/controls/templates/TemperatureControlTemplate.java
View File

@@ -19,6 +19,7 @@ package android.service.controls.templates;
import android.annotation.IntDef;
import android.annotation.NonNull;
import android.os.Bundle;
import android.service.controls.Control;
import android.util.Log;
import com.android.internal.util.Preconditions;
@@ -26,6 +27,13 @@ import com.android.internal.util.Preconditions;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* A template for a temperature related {@link Control} that supports multiple modes.
*
* Both the current mode and the active mode for the control can be specified. The combination of
* the {@link Control#getDeviceType} and the current and active mode will determine colors and
* transitions for the UI element.
*/
public final class TemperatureControlTemplate extends ControlTemplate {
private static final String TAG = "ThermostatTemplate";
@@ -51,6 +59,7 @@ public final class TemperatureControlTemplate extends ControlTemplate {
public @interface Mode {}
private static final int NUM_MODES = 6;
public static final @Mode int MODE_UNKNOWN = 0;
public static final @Mode int MODE_OFF = 1;
@@ -102,6 +111,18 @@ public final class TemperatureControlTemplate extends ControlTemplate {
private final @Mode int mCurrentActiveMode;
private final @ModeFlag int mModes;
/**
* Construct a new {@link TemperatureControlTemplate}.
*
* The current and active mode have to be among the ones supported by the flags.
*
* @param templateId the identifier for this template object
* @param controlTemplate a template to use for interaction with the user
* @param currentMode the current mode for the {@link Control}
* @param currentActiveMode the current active mode for the {@link Control}
* @param modesFlag a flag representing the available modes for the {@link Control}
* @throws IllegalArgumentException if the parameters passed do not make a valid template.
*/
public TemperatureControlTemplate(@NonNull String templateId,
@NonNull ControlTemplate controlTemplate,
@Mode int currentMode,
@@ -179,6 +200,9 @@ public final class TemperatureControlTemplate extends ControlTemplate {
return mModes;
}
/**
* @return {@link ControlTemplate#TYPE_TEMPERATURE}
*/
@Override
public int getTemplateType() {
return TYPE;

24
core/java/android/service/controls/templates/ToggleRangeTemplate.java
View File

@@ -18,9 +18,16 @@ package android.service.controls.templates;
import android.annotation.NonNull;
import android.os.Bundle;
import android.service.controls.Control;
import com.android.internal.util.Preconditions;
/**
* A template for a {@link Control} supporting toggling and a range.
*
* @see ToggleTemplate
* @see RangeTemplate
*/
public final class ToggleRangeTemplate extends ControlTemplate {
private static final @TemplateType int TYPE = TYPE_TOGGLE_RANGE;
@@ -40,6 +47,12 @@ public final class ToggleRangeTemplate extends ControlTemplate {
mRangeTemplate = new RangeTemplate(b.getBundle(KEY_RANGE));
}
/**
* Constructs a new {@link ToggleRangeTemplate}.
* @param templateId the identifier for this template.
* @param button a {@link ControlButton} to use for the toggle interface
* @param range a {@link RangeTemplate} to use for the range interface
*/
public ToggleRangeTemplate(@NonNull String templateId,
@NonNull ControlButton button,
@NonNull RangeTemplate range) {
@@ -50,6 +63,14 @@ public final class ToggleRangeTemplate extends ControlTemplate {
mRangeTemplate = range;
}
/**
* Constructs a new {@link ToggleRangeTemplate}.
* @param templateId the identifier for this template.
* @param checked true if the toggle should be rendered as active.
* @param actionDescription action description for the button.
* @param range {@link RangeTemplate} to use for the range interface
* @see ControlButton
*/
public ToggleRangeTemplate(@NonNull String templateId,
boolean checked,
@NonNull CharSequence actionDescription,
@@ -86,6 +107,9 @@ public final class ToggleRangeTemplate extends ControlTemplate {
return mControlButton.getActionDescription();
}
/**
* @return {@link ControlTemplate#TYPE_TOGGLE_RANGE}
*/
@Override
public int getTemplateType() {
return TYPE;