Create a Frontend Coordination Rule
Knowledge of the system UI will help you to understand this guide. If you are not yet familiar with it, feel free to take a look at the system UI overview.
A system UI in the TomTom Digital Cockpit can use frontend coordination rules to apply business logic that coordinates frontends.
Such rules commonly trigger a Panel
within a Frontend
to open,
close or update services with information derived from frontends and their panels. For example,
CloseModalPanelsOnTaskPanelChangeFrontendCoordinationRule
ensures
a ModalPanel
is closed when the active TaskPanel
changes;
ToggleTaskPanelsOnMenuItemClickFrontendCoordinationRule
responds to system UI menu items being clicked by opening or closing a TaskPanel
.
More examples can be found in
com.tomtom.ivi.platform.systemui.api.common.frontendcoordinator.frontendcoordination
.
These rules have a direct impact on the look and feel of the Digital Cockpit and it's possible
to create custom rules to customize the behavior of the system UI. The following section explains how
to create a custom FrontendCoordinationRule
to hide the
DebugPanel
when a main menu item is clicked. Code snippets only show
significant parts for this example, the full code is provided in the
examples/customization/frontendcoordinationrule
directory.
Create a frontend coordination rule
Create a
CloseDebugPanelOnMenuItemClickFrontendCoordinationRule.kt
.
1internal class CloseDebugPanelOnMenuItemClickFrontendCoordinationRule(2 private val debugPanelService: DebugPanelServiceApi?3) : FrontendCoordinationRule {4 override fun activate(5 lifecycleOwner: LifecycleOwner,6 iviServiceProvider: IviInstanceBoundIviServiceProvider,7 frontends: LiveData<out Collection<Frontend>>8 ) {910 SystemUiMenuItemsService.createApi(lifecycleOwner, iviServiceProvider)11 .addMenuItemEventListener(12 lifecycleOwner,13 object : SystemUiMenuItemsService.MenuItemEventListener {14 override fun onMenuItemClicked(id: MenuItem.Id) {15 debugPanelService?.showDebugPanelAsync(false)16 }17 }18 )19 }20}
Create a view model with the frontend coordination rule
Create a
CustomSystemUiViewModel
that includes the new rule. Note how the frontendCoordinator
property is used to provide a collection of
rules used by the system UI.
1internal class CustomSystemUiViewModel(2 coreViewModel: CoreSystemUiViewModel3) : LifecycleViewModel() {45 val frontendCoordinator = FrontendCoordinator.createDefault(6 lifecycleOwner = this,7 iviServiceProvider = coreViewModel.iviServiceProvider,8 frontendMetadata = coreViewModel.frontendMetadata,9 frontendContextFactory = coreViewModel.defaultFrontendContextFactory,10 frontendCoordinationRulesFactory = { frontendRegistry, panelRegistry ->11 val defaultRules = DefaultFrontendCoordinationRules.create(12 frontendRegistry,13 panelRegistry14 )15 defaultRules + CloseDebugPanelOnMenuItemClickFrontendCoordinationRule(debugPanelService)16 }17 )18}
Create a custom system UI host for the view model
Create a
CustomSystemUiHost
that uses the
CustomSystemUiViewModel
.
1internal class CustomSystemUiHost(systemUiHostContext: SystemUiHostContext) :2 SystemUiHost(systemUiHostContext) {34 private lateinit var viewModel: CustomSystemUiViewModel56 override fun onCreate() {7 viewModel = ViewModelProvider(8 viewModelStoreOwner,9 FixedConstructorFactory(coreViewModel)10 )[CustomSystemUiViewModel::class.java]11 }1213 override fun onSystemUiPresented() {14 viewModel.frontendCoordinator.onSystemUiPresented()15 }1617 private fun bindSystemUiView(binding: TtiviFrontendcoordinationruleCustomsystemuiBinding) {18 binding.viewModel = viewModel19 binding.panelRegistry = viewModel.panelRegistry2021 setIviOnBackPressedCallbacks(listOf(binding.exampleCustomizationTaskPanelStackContainer))22 }23}
Create a custom activity for the system UI host
Create a
CustomActivity
that uses the
CustomSystemUiHost
.
1class CustomActivity : DefaultActivity() {2 override fun createSystemUiHost(iviInstanceId: IviInstanceId): SystemUiHost =3 CustomSystemUiHost(getDefaultSystemUiHostContext(iviInstanceId))4}
Try the custom frontend coordination rule
After the application is built and deployed to a target device, follow these steps to see the new behavior of the system UI:
- Long press the 'volume down' hardware button.
- The debug menu appears on the right of the screen.
- Tap a main menu item.
- The debug menu is automatically closed.
Debug tabs are normally only included in debug builds. In this example debug tabs are explicitly included.