Google is committed to advancing racial equity for Black communities. See how.

Customizing CarUiRecyclerView

This article describes the process of customizing CarUiRecyclerView and the scroll bar.

Prerequisites

This article presumes knowledge of an Runtime Resource Overlay (RRO) target APK. To learn more, see Customizing Apps.

About CarUiRecyclerView

When car_ui_scrollbar_enable is set to false in bools.xml, CarUiRecyclerView will not 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 will inflate the container with the scrollbar installed within it. Later androidx.recyclerview will also be 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 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 will be 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 overlayed 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.