CarUxRestrictions

class CarUxRestrictions
kotlin.Any
   ↳ androidx.car.uxrestrictions.CarUxRestrictions

Car UX Restrictions event. A shim for android.car.drivingstate.CarUxRestrictions to be used with OnUxRestrictionsChangedListener.

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,
    • isDistractionOptimizationRequired() 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 isDistractionOptimizationRequired() 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

Builder class for CarUxRestrictions

Constants

static Int

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

static Int

All the above restrictions are in effect.

static Int

Limit the number of items displayed on the screen.

static Int

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

static Int

No dialpad for the purpose of initiating a phone call.

static Int

No filtering a list.

static Int

No text entry for the purpose of searching etc.

static Int

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

static Int

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

static Int

No video - no animated frames > 1fps.

static Int

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

Public constructors

<init>(uxRestrictions: CarUxRestrictions!)

Public methods

Boolean
equals(other: Any?)

Int

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

Int

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

Int

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

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

Long

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

Boolean

Compares if the restrictions are the same.

Int

Boolean

Conveys if the foreground activity needs to be distraction optimized.

String

Constants

UX_RESTRICTIONS_BASELINE

static val UX_RESTRICTIONS_BASELINE: Int

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

Value: 0

UX_RESTRICTIONS_FULLY_RESTRICTED

static val UX_RESTRICTIONS_FULLY_RESTRICTED: Int

All the above restrictions are in effect.

Value: 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
                    | UX_RESTRICTIONS_NO_VOICE_TRANSCRIPTION

UX_RESTRICTIONS_LIMIT_CONTENT

static val UX_RESTRICTIONS_LIMIT_CONTENT: Int

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

Value: 0x1 << 5

UX_RESTRICTIONS_LIMIT_STRING_LENGTH

static val UX_RESTRICTIONS_LIMIT_STRING_LENGTH: Int

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

Value: 0x1 << 2

UX_RESTRICTIONS_NO_DIALPAD

static val UX_RESTRICTIONS_NO_DIALPAD: Int

No dialpad for the purpose of initiating a phone call.

Value: 1

UX_RESTRICTIONS_NO_FILTERING

static val UX_RESTRICTIONS_NO_FILTERING: Int

No filtering a list.

Value: 0x1 << 1

UX_RESTRICTIONS_NO_KEYBOARD

static val UX_RESTRICTIONS_NO_KEYBOARD: Int

No text entry for the purpose of searching etc.

Value: 0x1 << 3

UX_RESTRICTIONS_NO_SETUP

static val UX_RESTRICTIONS_NO_SETUP: Int

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

Value: 0x1 << 6

UX_RESTRICTIONS_NO_TEXT_MESSAGE

static val UX_RESTRICTIONS_NO_TEXT_MESSAGE: Int

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

Value: 0x1 << 7

UX_RESTRICTIONS_NO_VIDEO

static val UX_RESTRICTIONS_NO_VIDEO: Int

No video - no animated frames > 1fps.

Value: 0x1 << 4

UX_RESTRICTIONS_NO_VOICE_TRANSCRIPTION

static val UX_RESTRICTIONS_NO_VOICE_TRANSCRIPTION: Int

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

Value: 0x1 << 8

Public constructors

<init>

CarUxRestrictions(uxRestrictions: CarUxRestrictions!)

Public methods

equals

fun equals(other: Any?): Boolean

getActiveRestrictions

fun getActiveRestrictions(): Int

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

Return
Int: A combination of the above @CarUxRestrictionsInfo

getMaxContentDepth

fun getMaxContentDepth(): Int

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.

Return
Int: maximum number of cumulative items that can be displayed

getMaxCumulativeContentItems

fun getMaxCumulativeContentItems(): Int

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.

Return
Int: maximum number of cumulative items that can be displayed

getMaxRestrictedStringLength

fun getMaxRestrictedStringLength(): Int

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

Return
Int: the maximum length of string that can be displayed

getTimestamp

fun getTimestamp(): Long

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

Return
Long: Elapsed time in nanoseconds since system boot.

hasSameRestrictionsAs

fun hasSameRestrictionsAs(other: CarUxRestrictions!): Boolean

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

Parameters
other CarUxRestrictions!: the other CarUxRestrictions object
Return
Boolean: true if the restrictions are same, false otherwise

hashCode

fun hashCode(): Int

isDistractionOptimizationRequired

fun isDistractionOptimizationRequired(): Boolean

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.

Return
Boolean: true if distraction optimization is required, false if not

toString

fun toString(): String