שרטוט מפות

אפליקציות ניווט, אפליקציות של נקודות עניין (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 של הקריאות החוזרות 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 מחוץ לפעילות. צריך לוודא ש-ComposeView או תצוגת אב מעבירים את LifecycleOwner ואת SavedStateRegistryOwner. כדי לעשות את זה, משתמשים בפקודות 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.

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

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