मैप बनाएं

नेविगेशन, लोकप्रिय जगह (पीओआई), और मौसम की जानकारी देने वाले ऐप्लिकेशन, इन टेंप्लेट का इस्तेमाल करके मैप बना सकते हैं. इसके लिए, उन्हें 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 में, onSurfaceAvailable() और onSurfaceDestroyed() कॉलबैक के SurfaceContainer पैरामीटर में पास किया जाता है.

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

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

कॉन्टेंट रेंडर करने के लिए वर्चुअल डिसप्ले का इस्तेमाल करना

Canvas API का इस्तेमाल करके, सीधे Surface में रेंडर करने के अलावा, VirtualDisplay और Presentation एपीआई का इस्तेमाल करके भी Surface में व्यू रेंडर किए जा सकते हैं. इस उदाहरण में दिखाया गया है:

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()
  }
}

वर्चुअल डिसप्ले पर रेंडर करने के लिए, कंपोज़ का इस्तेमाल करना

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 ऐप्लिकेशन की क्वालिटी में बताया गया है.

गहरे रंग वाला मैप ड्रॉ करने के लिए, CarContext.isDarkMode तरीके का इस्तेमाल करें. डार्क थीम का स्टेटस बदलने पर, आपको Session.onCarConfigurationChanged पर कॉल मिलता है.

क्लस्टर डिसप्ले पर मैप ड्रॉ करना

नेविगेशन ऐप्लिकेशन, मुख्य डिसप्ले पर मैप बनाने के साथ-साथ स्टीयरिंग व्हील के पीछे मौजूद क्लस्टर डिसप्ले पर भी मैप बना सकते हैं. ज़्यादा जानने के लिए, क्लस्टर डिसप्ले पर ड्राइंग लेख पढ़ें.