Theming and Customization

Knowledge of the design system and the design tokens will help you to understand this guide. If you are not yet familiar with them, feel free to take a look at the Design system overview and Design tokens.

Introduction

TomTom Digital Cockpit supports theming of the UI. This enables IVI systems built on top of TomTom Digital Cockpit to have a customized look and feel which is aligned with the branding, make or model of the vehicle and which is consistent across the entire system. It also allows the system to support runtime theme switching, enabling the possibility of allowing the end-user to change the look of their UI while they are using their IVI system.

A theme is composed of styles which are divided into theme categories. Each category focuses on an aspect of the visual user interface such as colors or spacing between UI components. This page describes how to add themable UI controls and the theming system in detail.

How to Implement a Themable UI

TomTom's Digital Cockpit's theming mechanism makes use of Android's stylable XML attributes and Android styles. The rest of this guide assumes a basic understanding of these concepts.

A theme is divided into theme categories, each of which consists of a list of Android XML attributes which can be used to set the styling of a specific aspect of the UI, such as the color of some text. When implementing the UI, the developer can select attributes from the appropriate category instead of hardcoding a value into their layout XML.

Examples of the built-in theme categories include:

• TtIviThemeCategoryColors contains the possible common theme colors. This can be used to ensure similar parts of the UI such as the backgrounds of all panels of a certain type are the same color.
• TtIviThemeCategoryDimensSpacing contains the common spacing values in the theme. This can be used to ensure that all of the margin and padding values around similar UI controls such as the padding inside OK buttons is always the same.
• TtIviThemeCategoryDimensTextSize contains the common text sizes in the theme. This can be used to ensure that for example, all titles have the same size.

For example, inside TtIviThemeCategoryColors, there is

1...
2<!-- Used inside UI elements which require the most attention. -->
3<attr name="tt_surface_content_color_emphasis_high" format="color" />
4...
5<!-- Used to indicate something is wrong. E.g., an error message in a text field. -->
6<attr name="tt_surface_content_color_critical" format="color" />

As described by its documentation, the tt_surface_content_color_emphasis_high attribute should be used when styling a UI content whose color should indicate to the user that it is important. This attribute, for example, can be used as the value of android:textColor when styling a TtTextView.

1<com.tomtom.tools.android.api.uicontrols.textview.TtTextView
2    android:id="@+id/importantTitle"
3    android:layout_width="wrap_content"
4    android:layout_height="wrap_content"
5    android:text="Important Title"
6    android:textAppearance="?attr/tt_title_text_style_l"
7    android:textColor="?attr/tt_surface_content_color_emphasis_high" />

Alternatively, to style multiple buttons in the same way, the attribute can be used in an Android style:

1<style name="ImportantTextViewStyle">
2    <item name="android:textColor">?attr/tt_surface_content_color_emphasis_high</item>
3</style>
4
5<style name="ImportantButtonStyle">
6    <item name="android:textColor">?attr/tt_surface_content_color_emphasis_high</item>
7</style>

The use of these attributes is core to ensuring that the entire UI of the IVI system is consistent and changes consistently when the end-user changes the UI theme at runtime.

To change the actual values of these attributes (and hence the look of the UI), see the section Customization

TomTom Digital Cockpit also provides a UI controls library consisting of a number of UI controls that extend what is available by default in Android. These also help with producing a themable UI and it is advised to use them where possible.

The Theming System

TomTom Digital Cockpit's theming mechanism is heavily based on Android's theming approach, while additionally providing a means to switch themes at runtime through a service. The Android styles within the theme are applied to the context of the system UI. All the fragments hosted in the system UI will get that context with the correct styles applied. Similarly, when a theme changes at run-time, like when switching between light and dark mode themes, all views are created with a new context that has the new styles applied.

The theme is provided by the ThemingService. This service is responsible for deciding which theme should be used by the system UI. It loads the styles that themes can use from all IviThemeRegistrySources. The styles must provide values for all attributes within their respective categories. Failing to do so will result in unexpected behavior as the views are missing some of their attributes.

If you want a customized theme, you must add your own IviThemeRegistrySources to provide the extra styles for the ThemingService. In that implementation you can provide styles to suit your look. You can also create your styles by inherit from TomTom Digital Cockpit stock styles and only change the necessary theme attributes.

Theme Categories

The appearance of the UI is determined by colors, margins, font types, etc. A theme is divided into categories for each of these aspects of the UI. To reduce duplication when creating a new theme and to be able to apply styles independently, these attributes are defined in categories like color, spacing, and font. Each category represents a set of attributes for the theme.

By having categories of theming attributes, you can create a slightly different theme based on any other theme. For example, you can create a new look by keeping all categories unchanged, except the color category. This way you do not need to duplicate all the attributes, but only attributes that you want to change.

The theme attributes are defined using the standard Android declare-styleable. Some examples of how categories are defined, and which categories attributes belong to, are:

1<!-- attrs_dimens_spacing.xml -->
2<resources>
3    <declare-styleable name="TtiviThemeCategoryDimensSpacing">
4        <attr name="ttivi_tile_item_spacing" format="dimension" />
5    </declare-styleable>
6</resources>
7
8<!-- attrs.xml -->
9<resources>
10    <declare-styleable name="TtiviThemeCategoryStyles">
11        <attr name="ttivi_apptileview_style" format="reference" />
12    </declare-styleable>
13</resources>
14
15<!-- attrs_colors.xml -->
16<resources>
17    <declare-styleable name="TtiviThemeCategoryColors">
18        <attr name="ttivi_apptileview_background_gradient_drawable" format="color" />
19    </declare-styleable>
20</resources>

TomTom Digital Cockpit defines below categories for the entire system:

• animatorThemeCategory
• colorThemeCategory
• durationThemeCategory
• fontThemeCategory
• iconThemeCategory
• iconSizeThemeCategory
• radiusThemeCategory
• responsiveHorizontalSpacingThemeCategory
• responsiveVerticalSpacingThemeCategory
• sizeThemeCategory
• spacingThemeCategory
• stylesThemeCategory
• textAppearanceThemeCategory
• textSizeThemeCategory

For the navigation component(NavApp), it also defines below categories:

• navAppDrivingUiStyleThemeCategory
• navAppDrivingUiHorizonPanelStyleThemeCategory
• navAppMapStyleThemeCategory
• navAppResponsiveSpacingThemeCategory
• navAppShortcutStripStyleThemeCategory
• navAppSearchUiStyleThemeCategory

Customization

Here we'll dive deeper into the way you can customize your product using the tools that theming provides.

• An IviTheme is a collection of IviThemeComponents.
• And an IviThemeComponent contains the necessary styles information and each style belongs to a single IviThemeCategory. The theme component styles are defined as Android style resources. For example, a Noto Sans font style is defined as:

1<resources>
2    <style name="TtiviThemeFontNotoSans">
3        <item name="tt_font_thin">@font/noto_sans_regular</item>
4        <item name="tt_font_medium">@font/noto_sans_semi_bold</item>
5        <item name="tt_font_bold">@font/noto_sans_bold</item>
6    </style>
7</resource>

• A theme category, like color or font, is represented by an IviThemeCategory. They may contain multiple IviThemeComponents. For example, a font IviThemeCategory can have several font IviThemeComponents, each for a different font.

TomTom Digital Cockpit comes with some pre-defined themes including a dark and a light mode for the color category. The theme can be customized by deriving a new theme from the existing one and overriding the existing values of these attributes in the new theme.

For example, to create new light and dark modes which are based on the build-in TomTom Digital Cockpit themes, the following XML can be used:

1<resources>
2    <style name="CustomLightTheme" parent="TtiviThemeColorLight">
3        <!-- Define a new high emphasis content color for the light theme -->
4        <item name="tt_surface_content_color_emphasis_high">@color/product_palette_blue</item>
5    </style>
6
7    <style name="CustomDarkTheme" parent="TtiviThemeColorDark">
8        <!-- Define a new high emphasis content color for the dark theme -->
9        <item name="tt_surface_content_color_emphasis_high">@color/product_palette_red</item>
10    </style>

With these new themes, all UI elements which use these attributes will get the defined value when the theme is changed. Once you create new theme styles, new IviThemeRegistrySources are also required. IviThemeComponents are provided by IviThemeRegistrySources, and are collected to form an IviTheme.

To understand how to create IviThemeRegistrySources to provide new IviThemeComponents including custom styles like the examples mentioned above, see the Custom theme tutorial.