CarUxRestrictions

public 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

 

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 the above restrictions are in effect.

int UX_RESTRICTIONS_LIMIT_CONTENT

Limit the number of items displayed on the screen.

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.

int UX_RESTRICTIONS_NO_KEYBOARD

No text entry for the purpose of searching etc.

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 UX_RESTRICTIONS_LIMIT_CONTENT is imposed.

int getMaxRestrictedStringLength()

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

long getTimeStamp()

Time at which this UX restriction event was deduced based on the car's driving state.

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

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

public static final int UX_RESTRICTIONS_FULLY_RESTRICTED

All the above restrictions are in effect.

Constant Value: 511 (0x000001ff)

UX_RESTRICTIONS_LIMIT_CONTENT

public static final int UX_RESTRICTIONS_LIMIT_CONTENT

Limit the number of items displayed on the screen. Refer to getMaxCumulativeContentItems() and getMaxContentDepth() for the upper bounds on content serving.

Constant Value: 32 (0x00000020)

UX_RESTRICTIONS_LIMIT_STRING_LENGTH

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

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

public static final int UX_RESTRICTIONS_NO_FILTERING

No filtering a list.

Constant Value: 2 (0x00000002)

UX_RESTRICTIONS_NO_KEYBOARD

public static final int UX_RESTRICTIONS_NO_KEYBOARD

No text entry for the purpose of searching etc.

Constant Value: 8 (0x00000008)

UX_RESTRICTIONS_NO_SETUP

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

public static final int UX_RESTRICTIONS_NO_TEXT_MESSAGE

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

Constant Value: 128 (0x00000080)

UX_RESTRICTIONS_NO_VIDEO

public static final int UX_RESTRICTIONS_NO_VIDEO

No video - no animated frames > 1fps.

Constant Value: 16 (0x00000010)

UX_RESTRICTIONS_NO_VOICE_TRANSCRIPTION

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

public static final Creator<CarUxRestrictions> CREATOR

Public constructors

CarUxRestrictions

public CarUxRestrictions (CarUxRestrictions uxRestrictions)

Parameters
uxRestrictions CarUxRestrictions

Public methods

describeContents

public int describeContents ()

Returns
int

getActiveRestrictions

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

getMaxContentDepth

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

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

public int getMaxRestrictedStringLength ()

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

Returns
int the maximum length of string that can be displayed

getTimeStamp

public long getTimeStamp ()

Time at which this UX restriction event was deduced based on the car's driving state.

Returns
long Elapsed time in nanoseconds since system boot.

isRequiresDistractionOptimization

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

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

public String toString ()

Returns
String

writeToParcel

public void writeToParcel (Parcel dest, 
                int flags)

Parameters
dest Parcel

flags int