# WebContainer

> UI के अंदर एक नेटिव webview (HTML/JS) को एम्बेड करता है — IWebView इंटरफ़ेस के माध्यम से, प्लेटफ़ॉर्म-निर्भर।

Source: https://crossfly.dev/hi/docs/ui/widgets/webcontainer — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 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`](/docs/ui/widgets/chartview), लेबल, छवियाँ) का उपयोग करें।

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

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

```java
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` ढाँचे में रखें।

## बुनियादी उपयोग
```java
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 वाला प्लेटफ़ॉर्म)
```java
WebContainer form = new WebContainer();
form.setFormSubmitListener(dados -> processarEnvio(dados));  // IWebView.FormSubmitListener
form.show("https://meuservico/formulario.html");
container.add(LAY_FILL, form);
```

### Web लक्ष्य पर सुरक्षित गिरावट
```java
// 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/`](/docs/ui) · रेसिपी: [`cookbook/`](/docs/cookbook)
- अवधारणा (प्लेटफ़ॉर्म, UI थ्रेडिंग): [`concepts/`](/docs/concepts)
- संबंधित घटक: [`locationview`](/docs/ui/widgets/locationview)