Customize CarUiRecyclerView

This page describes the process of customizingCarUiRecyclerView and the scroll bar.

Prerequisites

This page presumes knowledge of a runtime resource overlay (RRO) target APK. To learn more, see Customize apps.

About CarUiRecyclerView

When car_ui_scrollbar_enable is set to false in bools.xml, CarUiRecyclerView doesn't inflate the scrollbar. That said, only the androidx.recyclerview is inflated with customizable styles as defined below. When car_ui_scrollbar_enable is set to true, CarUiRecyclerView inflates the container with the scrollbar installed within it. Later androidx.recyclerview is also added within the same container.

CarUiRecyclerView can take any adapter to display the data. But the recommendation is to use CarUiListItemAdapter where the chassis lib defines the layout for listItems and hence can be customized by OEMs. The customization for ListItems are defined in Customization options for CarUiListItem.

By default, car_ui_scrollbar_margin is used as the width of the scrollbar view. This margin is also added as android:endMargin of the CarUiRecyclerView so there is equal margin at the start and end of the data. If the developer had used enableDivider=true then the OEM can control how the dividers should appear. Dimensions that can be adjusted for CarUiRecyclerView are:

  <dimen name="car_ui_recyclerview_divider_height">0dp</dimen>
  <dimen name="car_ui_recyclerview_divider_start_margin">0dp</dimen>
  <dimen name="car_ui_recyclerview_divider_end_margin">0dp</dimen>
  <dimen name="car_ui_recyclerview_divider_top_margin">0dp</dimen>
  <dimen name="car_ui_recyclerview_divider_bottom_margin">0dp</dimen>

Scrollbar

The layout file for CarUiRV scrollbar is defined in car_ui_recyclerview_scrollbar.xml. In total, these four views are defined within the view:

Views
Car_ui_scrollbar_page_up Defines the up button of the scrollbar.
Car_ui_scrollbar_page_down defines the down button of the scrollbar.
Car_ui_scrollbar_thumb Height is calculated dynamically depending on the number of list items in the Recycler View (RV).
Car_ui_scrollbar_track Total height that defines the bounds in which the thumb will move.

OEMs should overlay this layout file to customize the scrollbar. Track view should be placed carefully as that would define the bounds in which the thumb will move. Thumb height is calculated dynamically based on the list items in the RV and the height of the viewholders.

This layout is included in the CarUiRV container car_ui_recycler_view.xml only if car_ui_scrollbar_enable is true.

Other dimensions that can be adjusted for scrollbar are:

  <dimen name="car_ui_scrollbar_container_width">@dimen/car_ui_margin</dimen>
  <dimen name="car_ui_scrollbar_button_size">@dimen/car_ui_touch_target_width</dimen>
  <dimen name="car_ui_scrollbar_thumb_width">7dp</dimen>
  <dimen name="car_ui_scrollbar_separator_margin">16dp</dimen>
  <dimen name="car_ui_scrollbar_margin">@dimen/car_ui_margin</dimen>
  <dimen name="car_ui_scrollbar_thumb_radius">100dp</dimen>

  <item name="car_ui_button_disabled_alpha" format="float" type="dimen">0.2</item>
  <item name="car_ui_scrollbar_milliseconds_per_inch" format="float" type="dimen">150.0</item>
  <item name="car_ui_scrollbar_deceleration_times_divisor" format="float" type="dimen">0.45</item>
  <item name="car_ui_scrollbar_decelerate_interpolator_factor" format="float" type="dimen">1.8</item>

  <dimen name="car_ui_scrollbar_padding_start">0dp</dimen>
  <dimen name="car_ui_scrollbar_padding_end">0dp</dimen>

Example

For example, to bring both the Up and Down arrow together at the bottom of the screen:

  1. Overlay car_ui_recyclerview_scrollbar.xml: 
    <?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="@dimen/car_ui_margin"
    android:layout_height="match_parent"
    android:id="@+id/car_ui_scroll_bar">

    <!-- View height is dynamically calculated during layout. -->
    <View
        android:id="@+id/car_ui_scrollbar_thumb"
        android:layout_width="7dp"
        android:layout_height="20dp"
        android:layout_alignParentTop="true"
        android:layout_centerHorizontal="true"
        android:background="@drawable/car_ui_recyclerview_scrollbar_thumb"/>

    <View
        android:id="@+id/car_ui_scrollbar_track"
        android:layout_width="10dp"
        android:layout_height="match_parent"
        android:layout_marginTop="10dp"
        android:layout_centerHorizontal="true"
        android:layout_above="@+id/car_ui_scrollbar_page_up"/>

    <ImageView
        android:id="@+id/car_ui_scrollbar_page_up"
        android:layout_width="76dp"
        android:layout_height="76dp"
        android:focusable="false"
        android:hapticFeedbackEnabled="false"
        android:src="@drawable/car_ui_recyclerview_ic_up"
        android:scaleType="centerInside"
        android:layout_centerHorizontal="true"
        android:layout_above="@+id/car_ui_scrollbar_page_down"/>

    <ImageView
        android:id="@+id/car_ui_scrollbar_page_down"
        android:layout_width="76dp"
        android:layout_height="76dp"
        android:focusable="false"
        android:hapticFeedbackEnabled="false"
        android:src="@drawable/car_ui_recyclerview_ic_down"
        android:scaleType="centerInside"
        android:layout_centerHorizontal="true"
      android:layout_alignParentBottom="true"/>
</RelativeLayout>
  2. To define the resources to be overlaid by the RRO, add Overlays.xml: 
    <overlay>
    <item target="id/car_ui_scroll_bar" value="@id/car_ui_scroll_bar"/>
    <item target="id/car_ui_scrollbar_thumb" value="@id/car_ui_scrollbar_thumb"/>
    <item target="id/car_ui_scrollbar_track" value="@id/car_ui_scrollbar_track"/>
    <item target="id/car_ui_scrollbar_page_up" value="@id/car_ui_scrollbar_page_up"/>
    <item target="id/car_ui_scrollbar_page_down" value="@id/car_ui_scrollbar_page_down"/>
    <item target="layout/car_ui_recyclerview_scrollbar" value="@layout/car_ui_recyclerview_scrollbar"/>
</overlay>
  3. If an Up, Down, or thumb drawable must be updated, they should also be overlaid.
  4. If any new resources are used in the RRO package that do not already exist, then these resources should also be defined in the RRO APK you create.