CarUxRestrictions

public final class CarUxRestrictions
extends Object implements Parcelable

java.lang.Object
   ↳ android.car.drivingstate.CarUxRestrictions


Car UX Restrictions event. This contains information on the set of UX restrictions that is in place due to the car's driving state.

The restriction information is organized as follows:

  • When there are no restrictions in place, for example when the car is parked,
  • When the driving state changes, causing the UX restrictions to come in effect,
    • isRequiresDistractionOptimization() returns true. Apps can only display activities that are distraction optimized. Distraction optimized activities must follow the base design guidelines to ensure a distraction free driving experience for the user.
    • When isRequiresDistractionOptimization() returns true, apps must call getActiveRestrictions(), to get the currently active UX restrictions to adhere to. getActiveRestrictions() provides additional information on the set of UX restrictions that are in place for the current driving state.

      The UX restrictions returned by getActiveRestrictions(), for the same driving state of the vehicle, could vary depending on the OEM and the market. For example, when the car is idling, the set of active UX restrictions will depend on the car maker and the safety standards of the market that the vehicle is deployed in.

Apps that intend to be run when the car is being driven need to

  • Comply with the general distraction optimization guidelines.
  • Listen and react to the UX restrictions changes as detailed above. Since the restrictions could vary depending on the market, apps are expected to react to the restriction information and not to the absolute driving state.

Summary

Nested classes

class CarUxRestrictions.Builder

Builder class for CarUxRestrictions 

@interface CarUxRestrictions.CarUxRestrictionsInfo

Value is either 0 or a combination of CarUxRestrictions.UX_RESTRICTIONS_BASELINE, CarUxRestrictions.UX_RESTRICTIONS_NO_DIALPAD, CarUxRestrictions.UX_RESTRICTIONS_NO_FILTERING, CarUxRestrictions.UX_RESTRICTIONS_LIMIT_STRING_LENGTH, CarUxRestrictions.UX_RESTRICTIONS_NO_KEYBOARD, CarUxRestrictions.UX_RESTRICTIONS_NO_VIDEO, CarUxRestrictions.UX_RESTRICTIONS_LIMIT_CONTENT, CarUxRestrictions.UX_RESTRICTIONS_NO_SETUP, CarUxRestrictions.UX_RESTRICTIONS_NO_TEXT_MESSAGE, and CarUxRestrictions.UX_RESTRICTIONS_NO_VOICE_TRANSCRIPTION 

Constants

int UX_RESTRICTIONS_BASELINE

No specific restrictions in place, but baseline distraction optimization guidelines need to be adhered to when isRequiresDistractionOptimization() is true.

int UX_RESTRICTIONS_FULLY_RESTRICTED

All restrictions are in effect.

int UX_RESTRICTIONS_LIMIT_CONTENT

Limit the number of items user can browse through in total in a single task.

int UX_RESTRICTIONS_LIMIT_STRING_LENGTH

General purpose strings length cannot exceed the character limit provided by getMaxRestrictedStringLength()

int UX_RESTRICTIONS_NO_DIALPAD

No dialpad for the purpose of initiating a phone call.

int UX_RESTRICTIONS_NO_FILTERING

No filtering a list with alpha-numeric character via the use of a character entry method.

int UX_RESTRICTIONS_NO_KEYBOARD

No text entry for the purpose of searching or other manual text string entry actvities.

int UX_RESTRICTIONS_NO_SETUP

No setup that requires form entry or interaction with external devices.

int UX_RESTRICTIONS_NO_TEXT_MESSAGE

No Text Message (SMS, email, conversational, etc.)

int UX_RESTRICTIONS_NO_VIDEO

No video - no animated frames > 1fps.

int UX_RESTRICTIONS_NO_VOICE_TRANSCRIPTION

No text transcription (live or leave behind) of voice can be shown.

Inherited constants

Fields

public static final Creator<CarUxRestrictions> CREATOR

Public constructors

CarUxRestrictions(CarUxRestrictions uxRestrictions)

Public methods

int describeContents()
int getActiveRestrictions()

A combination of the Car UX Restrictions that is active for the current state of driving.

int getMaxContentDepth()

Get the maximum allowable number of content depth levels or view traversals through any one path in a single task.

int getMaxCumulativeContentItems()

Get the maximum allowable number of content items that can be displayed to a user during traversal through any one path in a single task, when CarUxRestrictions#UX_RESTRICTIONS_LIMIT_CONTENT is imposed.

int getMaxRestrictedStringLength()

Get the maximum length of general purpose strings that can be displayed when CarUxRestrictions#UX_RESTRICTIONS_LIMIT_STRING_LENGTH is imposed.

boolean isRequiresDistractionOptimization()

Conveys if the foreground activity needs to be distraction optimized.

boolean isSameRestrictions(CarUxRestrictions other)

Compares if the restrictions are the same.

String toString()
void writeToParcel(Parcel dest, int flags)

Inherited methods

Constants

UX_RESTRICTIONS_BASELINE

Added in API level 29
public static final int UX_RESTRICTIONS_BASELINE

No specific restrictions in place, but baseline distraction optimization guidelines need to be adhered to when isRequiresDistractionOptimization() is true.

Constant Value: 0 (0x00000000)

UX_RESTRICTIONS_FULLY_RESTRICTED

Added in API level 29
public static final int UX_RESTRICTIONS_FULLY_RESTRICTED

All restrictions are in effect.

Constant Value: 511 (0x000001ff)

UX_RESTRICTIONS_LIMIT_CONTENT

Added in API level 29
public static final int UX_RESTRICTIONS_LIMIT_CONTENT

Limit the number of items user can browse through in total in a single task.

Refer to getMaxCumulativeContentItems() and getMaxContentDepth() for the upper bounds on content serving.

Constant Value: 32 (0x00000020)

UX_RESTRICTIONS_LIMIT_STRING_LENGTH

Added in API level 29
public static final int UX_RESTRICTIONS_LIMIT_STRING_LENGTH

General purpose strings length cannot exceed the character limit provided by getMaxRestrictedStringLength()

Constant Value: 4 (0x00000004)

UX_RESTRICTIONS_NO_DIALPAD

Added in API level 29
public static final int UX_RESTRICTIONS_NO_DIALPAD

No dialpad for the purpose of initiating a phone call.

Constant Value: 1 (0x00000001)

UX_RESTRICTIONS_NO_FILTERING

Added in API level 29
public static final int UX_RESTRICTIONS_NO_FILTERING

No filtering a list with alpha-numeric character via the use of a character entry method. For example, do not allow entering a letter to filter the content of a list down to items only containing that letter.

Constant Value: 2 (0x00000002)

UX_RESTRICTIONS_NO_KEYBOARD

Added in API level 29
public static final int UX_RESTRICTIONS_NO_KEYBOARD

No text entry for the purpose of searching or other manual text string entry actvities.

Constant Value: 8 (0x00000008)

UX_RESTRICTIONS_NO_SETUP

Added in API level 29
public static final int UX_RESTRICTIONS_NO_SETUP

No setup that requires form entry or interaction with external devices.

Constant Value: 64 (0x00000040)

UX_RESTRICTIONS_NO_TEXT_MESSAGE

Added in API level 29
public static final int UX_RESTRICTIONS_NO_TEXT_MESSAGE

No Text Message (SMS, email, conversational, etc.)

Constant Value: 128 (0x00000080)

UX_RESTRICTIONS_NO_VIDEO

Added in API level 29
public static final int UX_RESTRICTIONS_NO_VIDEO

No video - no animated frames > 1fps.

Constant Value: 16 (0x00000010)

UX_RESTRICTIONS_NO_VOICE_TRANSCRIPTION

Added in API level 29
public static final int UX_RESTRICTIONS_NO_VOICE_TRANSCRIPTION

No text transcription (live or leave behind) of voice can be shown.

Constant Value: 256 (0x00000100)

Fields

CREATOR

Added in API level 29
public static final Creator<CarUxRestrictions> CREATOR

Public constructors

CarUxRestrictions

Added in API level 29
public CarUxRestrictions (CarUxRestrictions uxRestrictions)

Parameters
uxRestrictions CarUxRestrictions

Public methods

describeContents

Added in API level 29
public int describeContents ()

Returns
int

getActiveRestrictions

Added in API level 29
public int getActiveRestrictions ()

A combination of the Car UX Restrictions that is active for the current state of driving.

Returns
int A combination of the above @CarUxRestrictionsInfo Value is either 0 or a combination of UX_RESTRICTIONS_BASELINE, UX_RESTRICTIONS_NO_DIALPAD, UX_RESTRICTIONS_NO_FILTERING, UX_RESTRICTIONS_LIMIT_STRING_LENGTH, UX_RESTRICTIONS_NO_KEYBOARD, UX_RESTRICTIONS_NO_VIDEO, UX_RESTRICTIONS_LIMIT_CONTENT, UX_RESTRICTIONS_NO_SETUP, UX_RESTRICTIONS_NO_TEXT_MESSAGE, and UX_RESTRICTIONS_NO_VOICE_TRANSCRIPTION

getMaxContentDepth

Added in API level 29
public int getMaxContentDepth ()

Get the maximum allowable number of content depth levels or view traversals through any one path in a single task. This is applicable when CarUxRestrictions#UX_RESTRICTIONS_LIMIT_CONTENT is imposed.

For example, if a task involves only selecting an item from a single list on one view, the task's content depth would be considered 1.

However, if the task involves selection of a content item in an originating view that then surfaces a secondary view to the user, the task's content depth would be considered 2.

Specifically, if a task involved browsing a list of countries, selecting a genre within the country, and then viewing the top songs within a country, the task's content depth would be considered 3.

Please refer to this and getMaxCumulativeContentItems() to know the upper bounds on the content display when the restriction is in place.

Returns
int maximum number of cumulative items that can be displayed

getMaxCumulativeContentItems

Added in API level 29
public int getMaxCumulativeContentItems ()

Get the maximum allowable number of content items that can be displayed to a user during traversal through any one path in a single task, when CarUxRestrictions#UX_RESTRICTIONS_LIMIT_CONTENT is imposed.

For example, if a task involving only one view, this represents the maximum allowable number of content items in this single view.

However, if the task involves selection of a content item in an originating view that then surfaces a secondary view to the user, then this value represents the maximum allowable number of content items between the originating and secondary views combined.

Specifically, if the maximum allowable value was 60 and a task involved browsing a list of countries and then viewing the top songs within a country, it would be acceptable to do either of the following:

  • list 10 countries, and then display the top 50 songs after country selection, or
  • list 20 countries, and then display the top 40 songs after country selection.

Please refer to this and getMaxContentDepth() to know the upper bounds on the content display when the restriction is in place.

Returns
int maximum number of cumulative items that can be displayed

getMaxRestrictedStringLength

Added in API level 29
public int getMaxRestrictedStringLength ()

Get the maximum length of general purpose strings that can be displayed when CarUxRestrictions#UX_RESTRICTIONS_LIMIT_STRING_LENGTH is imposed.

Returns
int the maximum length of string that can be displayed

isRequiresDistractionOptimization

Added in API level 29
public boolean isRequiresDistractionOptimization ()

Conveys if the foreground activity needs to be distraction optimized. Activities that can handle distraction optimization need to be tagged as a distraction optimized in the app's manifest.

If the app has a foreground activity that has not been distraction optimized, the app has to switch to another activity that is distraction optimized. Failing that, the system will stop the foreground activity.

Returns
boolean true if distraction optimization is required, false if not

isSameRestrictions

Added in API level 29
public boolean isSameRestrictions (CarUxRestrictions other)

Compares if the restrictions are the same. Doesn't compare the timestamps.

Parameters
other CarUxRestrictions: the other CarUxRestrictions object

Returns
boolean true if the restrictions are same, false otherwise

toString

Added in API level 29
public String toString ()

Returns
String

writeToParcel

Added in API level 29
public void writeToParcel (Parcel dest, 
                int flags)

Parameters
dest Parcel

flags int