WebContainer

WebContainer एक विजेट है जो आपकी CrossFly UI के अंदर एक नेटिव webview को एम्बेड करता है (HTML/JavaScript सामग्री)। यह एक पतला wrapper है: यह अपना कुछ नहीं बनाता — सब कुछ उस IWebView को सौंप देता है जिसे प्लेटफ़ॉर्म PlatformUtils.instance.createWebView() के माध्यम से प्रदान करता है। यह एक पेज, एक HTML फ़ॉर्म या एक वेब पैनल को स्क्रीन के एक सामान्य घटक की तरह प्रदर्शित करने के लिए काम आता है।

⚠️ उपलब्धता के बारे में ईमानदारी: WebContainer केवल वहीं काम करता है जहाँ एक नेटिव IWebView मौजूद हो (Android, iOS, Desktop)। इस कोडबेस में और न ही Web/TeaVM लक्ष्य में IWebView का कोई ठोस कार्यान्वयन है — असमर्थित प्लेटफ़ॉर्म पर createWebView() null लौटाता है, और तब WebContainer का कंस्ट्रक्टर UnsupportedOperationException फेंकता है। Web/WebGL बिल्ड में, webview एम्बेड करने के बजाय एक बाहरी पेज खोलना (view(url)) पसंद करें।

🔴 · पैकेज: dev.crossfly.ui · विस्तार करता है: Component (Runnable लागू करता है) · इसे सौंपता है: IWebView

कब उपयोग करें

नेटिव webview वाले प्लेटफ़ॉर्म (Android/iOS/Desktop) पर ऐप के अंदर वेब सामग्री (HTML/JS) प्रदर्शित करना।
एक HTML फ़ॉर्म एकीकृत करना और setFormSubmitListener के माध्यम से सबमिशन कैप्चर करना।

कब उपयोग न करें

सरल स्थिर सामग्री (टेक्स्ट/छवि) के लिए → एक पेज लोड करने के बजाय नेटिव विजेट (chartview, लेबल, छवियाँ) का उपयोग करें।

दिखावट

WebContainer अपने पिक्सेल नहीं रंगता: सिस्टम की नेटिव webview घटक के क्षेत्र पर आरोपित की जाती है। दृश्यता onPaint में स्वचालित रूप से समन्वित होती है — webview केवल तभी दिखाई देती है जब मूल विंडो शीर्ष पर हो (isTopMost()) और अन्यथा गायब हो जाती है।

पूर्ण उदाहरण (कॉपी करें, पेस्ट करें और चलाएँ)

WebContainer केवल वहीं काम करता है जहाँ एक नेटिव IWebView हो। यह उदाहरण container बनाने से पहले PlatformUtils.instance.createWebView() != null के साथ समर्थन का पता लगाता है (कंस्ट्रक्टर के UnsupportedOperationException से बचते हुए) और, समर्थन न होने पर (जैसे: Web/TeaVM लक्ष्य), view(url) के साथ पेज को बाहरी रूप से खोलकर सुचारू रूप से गिरावट लाता है।

package com.exemplo;

import dev.crossfly.PlatformUtils;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** चलाने योग्य मुख्य स्क्रीन। launcher (classname) की ओर संकेत करें और चलाएँ: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      String url = "https://example.com";

      // WebContainer तभी बनाता है जब प्लेटफ़ॉर्म कोई नेटिव IWebView दे।
      if (PlatformUtils.instance.createWebView() != null)
      {
         WebContainer browser = new WebContainer();
         browser.show(url);
         add(LAY_FILL, browser);
      }
      else
      {
         // Web/TeaVM लक्ष्य (कोई एंबेडेड webview नहीं): पेज बाहरी रूप से खोलता है।
         add(LAY_AUTO, new Label("Sem webview nativa — abrindo externamente…"));
         PlatformUtils.instance.view(url);
      }
   }
}

नीचे दिए गए अंश केवल मुख्य भाग दिखाते हैं (जो onShow() के अंदर जाता है)। चलाने के लिए, उन्हें ऊपर दिए गए MainWindow ढाँचे में रखें।

बुनियादी उपयोग

WebContainer browser = new WebContainer();   // UnsupportedOperationException फेंक सकता है
browser.show("https://example.com");
container.add(LAY_FILL, browser);

कंस्ट्रक्टर

कंस्ट्रक्टर	विवरण
`WebContainer()`	`PlatformUtils.instance.createWebView()` के माध्यम से नेटिव webview प्राप्त करता है और अदृश्य रूप से शुरू होता है। यदि प्लेटफ़ॉर्म `IWebView` प्रदान नहीं करता तो `UnsupportedOperationException` फेंकता है।

गुण और अनुकूलन

मेथड	प्रकार	क्या करता है
`show(String url)`	`void`	webview में URL लोड और प्रदर्शित करता है।
`hide()`	`void`	पेज की स्थिति बनाए रखते हुए webview को छिपाता है।
`setVisible(boolean)`	`void`	`true` = `show(null)` (वर्तमान URL/स्थिति बनाए रखता है); `false` = `hide()`।
`isVisible()`	`boolean`	क्या webview दिखाई दे रही है।
`evaluateJavaScript(String script)`	`void`	पेज पर JavaScript निष्पादित करता है।
`setFormSubmitListener(IWebView.FormSubmitListener)`	`void`	HTML फ़ॉर्म सबमिशन कैप्चर करने के लिए कॉलबैक पंजीकृत करता है।

IWebView की आवश्यकता है कि ऑपरेशन render thread (paint thread) पर हों। यदि आप किसी अन्य thread से show/evaluateJavaScript कॉल कर रहे हैं तो Component.onUI(...) के साथ उस पर वापस जाएँ।

कॉलबैक और इवेंट

कॉलबैक	कब सक्रिय होता है
`IWebView.FormSubmitListener` (`setFormSubmitListener` के माध्यम से)	एम्बेडेड पेज के अंदर एक HTML फ़ॉर्म सबमिट करने पर।

WebContainer onAction/onClick का उपयोग नहीं करता — इंटरैक्शन वेब पेज के अंदर होता है। एकमात्र ऐप हुक फ़ॉर्म सबमिट लिसनर है।

स्थितियाँ

दृश्य / छिपा हुआ: show/hide/setVisible द्वारा और, स्वचालित रूप से, विंडो की स्थिति द्वारा प्रबंधित (जब मूल विंडो शीर्ष पर नहीं होती तो webview गायब हो जाती है)।
हटाया गया: onRemove में view.removeView() कॉल होता है और IWebView का पुनः उपयोग नहीं किया जा सकता — पुनः प्रदर्शित करने के लिए, एक नया WebContainer बनाएँ।

सबमिशन कैप्चर के साथ HTML फ़ॉर्म (webview वाला प्लेटफ़ॉर्म)

WebContainer form = new WebContainer();
form.setFormSubmitListener(dados -> processarEnvio(dados));  // IWebView.FormSubmitListener
form.show("https://meuservico/formulario.html");
container.add(LAY_FILL, form);

Web लक्ष्य पर सुरक्षित गिरावट

// Web/TeaVM बिल्ड में, createWebView() null लौटाता है और कंस्ट्रक्टर फेंकता है।
try {
   WebContainer c = new WebContainer();
   c.show("https://example.com");
   container.add(LAY_FILL, c);
} catch (UnsupportedOperationException e) {
   // कोई एंबेडेड webview नहीं: पेज बाहरी रूप से खोलें।
   PlatformUtils.instance.view("https://example.com");
}

अच्छी प्रथाएँ

Web लक्ष्य पर अच्छी तरह गिरावट लाने के लिए निर्माण को UnsupportedOperationException के try/catch में समेटें।

आम गलतियाँ

असमर्थित प्लेटफ़ॉर्म पर WebContainer बनाना: UnsupportedOperationException फेंकता है। पहले से इसे संभालें या पता लगाएँ।
onRemove के बाद पुनः उपयोग करना: IWebView को त्याग दिया गया (removeView()); एक नया इंस्टेंस बनाएँ।
Web/TeaVM लक्ष्य पर वेब एम्बेड करने की अपेक्षा करना: कोई कार्यान्वयन नहीं है; webview एम्बेड करना ≠ वेब ऐप होना। view(url) का उपयोग करें।

यह भी देखें

क्षेत्र गाइड: ui/ · रेसिपी: cookbook/
अवधारणा (प्लेटफ़ॉर्म, UI थ्रेडिंग): concepts/
संबंधित घटक: locationview