AndroidAutoSurfaceManager
Facade providing static access to AndroidAutoStateHolder.
This object exists solely for cross-module access from the androidauto module, which cannot use Hilt injection because its components (Session, SurfaceCallback) are created by the Android Auto framework, not our code.
All state and business logic is delegated to the injected AndroidAutoStateHolder. This facade provides a clean separation between:
State ownership: AndroidAutoStateHolder (injectable, testable)
Static access: AndroidAutoSurfaceManager (facade for system-created components)
Architecture
┌─────────────────────────────────────────────────────────────┐
│ App Module │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ AndroidAutoStateHolder (Hilt @Singleton) │ │
│ │ - All state and business logic │ │
│ │ - Injected into MainActivity, ViewModels │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ │ initialize() at app startup │
│ ↓ │
└─────────────────────────────────────────────────────────────┘
│
↓
┌─────────────────────────────────────────────────────────────┐
│ Android Auto MSDK Module │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ AndroidAutoSurfaceManager (object - THIS) │ │
│ │ - Thin facade providing static access │ │
│ │ - Delegates all operations to StateHolder │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
│ Static access
↓
┌─────────────────────────────────────────────────────────────┐
│ Android Auto Module │
│ - AndroidAutoSession.onCreateScreen() { getHolder() } │
│ - AndroidAutoSurfaceCallback { setLoadingState() } │
│ - AA Screens { phoneState.collect() } │
└─────────────────────────────────────────────────────────────┘Initialization
The facade supports two initialization paths to handle different launch scenarios:
Path 1: Phone app launches first (normal)
The Hilt module calls getOrCreateStateHolder which creates a new holder. When AA connects later, the facade is already initialized.
Path 2: Android Auto launches first (cold start from car)
The AA framework creates Session before Hilt runs. The facade auto-creates a default AndroidAutoStateHolder on first access. When the phone app's Hilt module starts later, getOrCreateStateHolder returns the existing instance, ensuring the same holder is used everywhere.
@Module
@InstallIn(SingletonComponent::class)
object AndroidAutoModule {
@Provides
@Singleton
fun provideAndroidAutoStateHolder(): AndroidAutoStateHolder {
// Reuses existing holder if AA auto-created one, otherwise creates new
return AndroidAutoSurfaceManager.getOrCreateStateHolder()
}
}Usage
Preferred: Direct holder access (new code should use this):
// Access focused sub-holders for type-safe, domain-scoped state management
val connectionState = AndroidAutoSurfaceManager.connectionState
connectionState.setAAConnected(true)
val screenState = AndroidAutoSurfaceManager.screenState
screenState.setLoadingState(AndroidAutoLoadingState.MAP_READY)
val mapState = AndroidAutoSurfaceManager.mapState
mapState.setCameraFollowingUser(false)Legacy: Flat method API (still works, delegates to sub-holders internally):
AndroidAutoSurfaceManager.setAAConnected(true)
AndroidAutoSurfaceManager.setLoadingState(AndroidAutoLoadingState.MAP_READY)In app module (prefer direct injection over facade):
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
@Inject
lateinit var stateHolder: AndroidAutoStateHolder
// Use stateHolder.connection / .screen / .map directly
stateHolder.connection.setPhoneState(PhoneAppState.READY)
}Thread Safety
Thread safety is handled by the underlying AndroidAutoStateHolder. This facade only delegates calls without additional synchronization.
See also
Properties
StateFlow representing the current Android Auto screen state.
Direct access to the connection state sub-holder.
StateFlow of the day/night mode the user chose for the Android Auto map.
Flag indicating whether Android Auto is currently connected.
Flag indicating that Android Auto is in the process of disconnecting.
StateFlow tracking whether the map camera is following the user's GPS position.
StateFlow tracking the car head unit's current dark mode state.
StateFlow tracking whether the Android Auto display is in split screen mode.
Direct access to the map state sub-holder.
Callback interface for phone app to receive events from Android Auto.
StateFlow representing what AA screen the phone's current state maps to.
StateFlow representing the current phone app state.
Callback interface for phone app to send commands to Android Auto.
Direct access to the screen state sub-holder.
StateFlow providing the horizontal center of the visible area as a fraction of the full MapView surface width.
Functions
Clears the current guidance session state.
Gets the current AA screen state.
Gets the current guidance destination title.
Gets the AndroidAutoSurfaceHolder instance.
Gets the current loading state.
Returns the existing state holder, or creates and registers a new one.
Gets the phone's equivalent AA screen state.
Gets the current phone app state.
Initializes the facade with the injected state holder.
Gets whether the current guidance session is in demo mode.
Checks if holder has been set.
Returns whether the facade has been initialized with a state holder.
Checks if the phone app is closing.
Requests the Android Auto MapView to be re-attached to Navigation.
Resets the AA screen state to DISCONNECTED.
Resets the loading state to IDLE.
Resets the phone state to UNKNOWN.
Sets the Android Auto connection state.
Sets the Android Auto disconnecting flag.
Sets the current Android Auto screen state.
Sets the camera following state.
Sets the car's dark mode state.
Sets the current guidance session state.
Sets the day/night mode the user chose for the Android Auto map.
Sets the AndroidAutoSurfaceHolder instance.
Sets the current loading state and notifies the listener.
Sets the callback to be invoked when the phone app is closing.
Registers the phone app callback to receive events from Android Auto.
Sets the phone app closing flag and triggers immediate Android Auto close.
Sets the phone's equivalent AA screen state.
Sets the current phone app state.
Registers the callback for phone-to-AA commands.
Sets the callback for MapView re-attachment.
Sets the split screen state.
Registers a listener to be notified of loading state changes.
Sets the horizontal center of the visible area as a fraction of the full surface.
Sets the callback for handling zoom operations on the AA MapView.
Sets the callback for fitting the AA MapView camera to a geographic bounding box.
Fits the AA MapView camera to a geographic bounding box within the visible screen area.