שרטוט מפות

אפליקציות ניווט, אפליקציות של נקודות עניין (POI) ואפליקציות מזג אוויר שמשתמשות בתבניות הבאות יכולות לצייר מפות על ידי גישה אל Surface.

כדי להשתמש בתבניות הבאות, האפליקציה צריכה להצהיר על אחת מההרשאות התואמות האלה ברכיב <uses-permission> בקובץ AndroidManifest.xml.

הצגת הטמעה לדוגמה

כדי לראות הטמעה מלאה לדוגמה, אפשר לעיין בדוגמה לניווט.

הצהרה על הרשאת המשטח

בנוסף להרשאה שנדרשת לתבנית שבה האפליקציה משתמשת, האפליקציה צריכה להצהיר על ההרשאה androidx.car.app.ACCESS_SURFACE בקובץ AndroidManifest.xml שלה כדי לקבל גישה לממשק:

<manifest ...>
  ...
  <uses-permission android:name="androidx.car.app.ACCESS_SURFACE" />
  ...
</manifest>

גישה לפלטפורמה

כדי לגשת אל Surface שהמארח מספק, צריך להטמיע את SurfaceCallback ולספק את ההטמעה הזו לשירות המכוניות AppManager. הערך הנוכחי של Surface מועבר אל SurfaceCallback בפרמטר SurfaceContainer של קריאות החזרה (callback) onSurfaceAvailable() ו-onSurfaceDestroyed().

carContext.getCarService(AppManager::class.java).setSurfaceCallback(surfaceCallback)

carContext.getCarService(AppManager.class).setSurfaceCallback(surfaceCallback);

שימוש במסך וירטואלי כדי לעבד תוכן

בנוסף להצגה ישירות ב-Surface באמצעות Canvas API, אפשר גם להציג תצוגות ב-Surface באמצעות VirtualDisplay ו-Presentation API, כמו בדוגמה הזו:

class HelloWorldSurfaceCallback(context: Context) : SurfaceCallback {
  lateinit var virtualDisplay: VirtualDisplay
  lateinit var presentation: Presentation

  override fun onSurfaceAvailable(surfaceContainer: SurfaceContainer) {
      virtualDisplay = context
          .getSystemService(DisplayManager::class.java)
          .createVirtualDisplay(
              VIRTUAL_DISPLAY_NAME ,
              surfaceContainer.width,
              surfaceContainer.height,
              surfaceContainer.dpi,
              surfaceContainer.surface,
              0
          )

      presentation = Presentation(context, virtualDisplay.display)

      // Instantiate the view to be used as the content view
      val view = ...

      presentation.setContentView(view)
      presentation.show()
  }

  override fun onSurfaceDestroyed(surfaceContainer: SurfaceContainer) {
    presentation.dismiss()
    // This handles releasing the Surface provided when creating the VirtualDisplay
    virtualDisplay.release()
  }
}

שימוש בפיתוח נייטיב כדי לבצע רינדור לתצוגה הווירטואלית

אפשר להשתמש ב-ComposeView כתצוגת התוכן של Presentation. כי נעשה שימוש ב-ComposeView מחוץ לפעילות. צריך לוודא ש-LifecycleOwner ו-SavedStateRegistryOwner מועברים דרך ComposeView או דרך תצוגת אב. כדי לעשות את זה, משתמשים בפקודות setViewTreeLifecycleOwner ו-setViewTreeSavedStateRegistryOwner.

ב-Session כבר מיושם LifecycleOwner. כדי להשתמש בשני התפקידים, אפשר להטמיע בנוסף את SavedStateRegistryOwner.

class HelloWorldSession() : Session(), SavedStateRegistryOwner { ... }

class HelloWorldSurfaceCallback(session: HelloWorldSession) : SurfaceCallback {
  ...

  override fun onSurfaceAvailable(surfaceContainer: SurfaceContainer) {
    ...
    val view = ComposeView(session.carContext)
    view.setViewTreeLifecycleOwner(session)
    view.setViewTreeSavedStateRegistryOwner(session)
    view.setContent {
      // Composable content
    }

    presentation.setContentView(view)
    presentation.show()
  }

  ...
}

הסבר על האזור הגלוי של פני השטח

המארח יכול לצייר רכיבים של ממשק המשתמש לתבניות מעל המפה. המארח קורא לשיטה SurfaceCallback.onVisibleAreaChanged כדי להעביר את האזור של המשטח שסביר להניח שהוא לא חסום וגלוי למשתמש.

כדי לצמצם את מספר השינויים, המארח קורא לשיטה SurfaceCallback.onStableAreaChanged עם המלבן הקטן ביותר, שתמיד גלוי לפי התבנית הנוכחית.

לדוגמה, כשמשתמשים בNavigationTemplate של אפליקציית ניווט עם סרגל פעולות בחלק העליון, כדי לפנות יותר מקום במסך אפשר להסתיר את סרגל הפעולות אם המשתמש לא מקיים אינטראקציה עם המסך. במקרה הזה, תתבצע קריאה חוזרת אל onStableAreaChanged ואל onVisibleAreaChanged עם אותו מלבן.

כשסרגל הפעולות מוסתר, רק onVisibleAreaChanged נקרא עם האזור הגדול יותר. אם המשתמש מקיים אינטראקציה עם המסך, מתבצעת קריאה רק ל-onVisibleAreaChanged עם המלבן הראשון.

תמיכה בעיצוב כהה

האפליקציות צריכות לצייר מחדש את המפה שלהן במופע Surface עם הצבעים הכהים המתאימים, כשהמארח קובע שהתנאים מצדיקים זאת, כפי שמתואר במאמר איכות אפליקציות ל-Android Auto.

כדי לשרטט מפה כהה, משתמשים בשיטה CarContext.isDarkMode. כשסטטוס הנושא הכהה משתנה, מתקבלת שיחה אל Session.onCarConfigurationChanged.

ציור מפות בלוח המחוונים

בנוסף לציור מפות במסך הראשי, אפליקציות ניווט יכולות גם לתמוך בציור מפות במסך של לוח המחוונים שמאחורי ההגה. מידע נוסף זמין במאמר בנושא ציור במסך של אשכול.