# ImageView

> कॉन्फ़िगर करने योग्य स्केल मोड (ImageSize) और संरेखण के साथ एक Image प्रदर्शित करता है।

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

# ImageView

`ImageView` कॉम्पोनेंट की सीमाओं के भीतर एक [`Image`](/docs/ui/images-and-graphics) रेंडर करता है, स्केल मोड को enum [`ImageSize`](/docs/reference) द्वारा और क्षैतिज/ऊर्ध्वाधर संरेखण को `Position` के माध्यम से नियंत्रित करते हुए। यह एक लेआउट में एक निश्चित इमेज (फ़ोटो, कवर, लोगो) दिखाने का घोषणात्मक तरीका है।

आंतरिक रूप से यह एक **कैश्ड स्केल की गई** प्रति (`ResizeMode.STRETCH`, `ResizeQuality.FAST`) रखता है ताकि हर फ़्रेम पर आकार न बदलना पड़े; इमेज, स्केल मोड या आकार बदलने पर कैश अमान्य हो जाता है।

> 🟢 · **पैकेज:** `dev.crossfly.ui` · **विस्तारित करता है:** `Component` · **स्टाइल:** `ComponentStyle` (आंतरिक margin के लिए `ingap` का उपयोग करता है)

## कब उपयोग करें
- एक लेआउट में एक निश्चित इमेज प्रदर्शित करना: फ़ोटो, कवर, लोगो, अवतार।
- समायोजित करना कि इमेज स्थान को कैसे भरती है (aspect ratio, cover, stretch)।

## कब उपयोग न करें
- प्रति-फ़्रेम एनिमेशन, परिवर्तनशील निरंतर स्केल या मिश्रित ड्रॉइंग → सीधे `paint.image(...)` कॉल करते हुए `onPaint` के साथ एक अपना `Component` बनाएं (देखें [`images-and-graphics/`](/docs/ui/images-and-graphics))।
- किसी अन्य कॉम्पोनेंट की **पृष्ठभूमि** इमेज → स्वयं `Component` के `BackgroundImage` का उपयोग करें (अध्याय 18)।

## दिखावट
इमेज डिफ़ॉल्ट रूप से आंतरिक क्षेत्र (`ingap` के बाद) के भीतर केंद्रित होती है और `ImageSize` के अनुसार स्केल की जाती है:

| `ImageSize` | व्यवहार |
|---|---|
| `ORIGINAL` | प्राकृतिक आकार, बिना स्केल के |
| `RATIO` | सीमाओं के भीतर **समाने** के लिए समान स्केल (letter-box) — **डिफ़ॉल्ट** |
| `FIT` | सीमाओं को **ढकने** के लिए समान स्केल (काट सकता है) |
| `STRETCH` | ठीक-ठीक भरने के लिए खींचता है (aspect ratio को अनदेखा करता है) |
| `FIT_WIDTH` / `FIT_HEIGHT` | चौड़ाई / ऊंचाई के अनुसार समायोजित करता है, अनुपात बनाए रखते हुए |
| `FIT_HALF_WIDTH` / `FIT_HALF_HEIGHT` | आधी चौड़ाई / ऊंचाई के अनुसार समायोजित करता है |

``

## पूर्ण उदाहरण (कॉपी, पेस्ट और रन करें)
```java
package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;
import dev.crossfly.ui.image.*;   // Image, ImageException

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

      // एक Image लोड करने पर ImageException/IOException आ सकता है — स्क्रीन न टूटे इसलिए संभालें।
      ImageView iv = new ImageView();          // खाली (placeholder: कुछ भी नहीं बनाया जाता)
      try {
         Image capa = new Image("cf/samples/api/ui/books/book1.png");
         iv.image(capa).imageSize(ImageSize.RATIO);
      } catch (ImageException e) {
         System.out.println("Imagem não encontrada, usando placeholder vazio: " + e.getMessage());
      }

      add(LAY_FILL, iv);
   }
}
```

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

## बुनियादी उपयोग
```java
Image capa = new Image("cf/samples/api/ui/books/book1.png");
ImageView iv = new ImageView(capa, ImageSize.RATIO);
container.add(LAY_FILL, iv);
```

## कंस्ट्रक्टर
| कंस्ट्रक्टर | विवरण |
|---|---|
| `ImageView()` | खाली (`image = null`, `ImageSize.RATIO`) |
| `ImageView(Image image)` | `RATIO` मोड वाली इमेज |
| `ImageView(Image image, ImageSize imageSize)` | इमेज + स्केल मोड |

## गुण और अनुकूलन
| गुण / मेथड | प्रकार | डिफ़ॉल्ट | क्या करता है |
|---|---|---|---|
| `image(Image)` | `ImageView` (फ्लुएंट) | `null` | इमेज बदलता है (कैश/लेआउट अमान्य करता है) |
| `imageSize(ImageSize)` | `ImageView` (फ्लुएंट) | `RATIO` | स्केल मोड परिभाषित करता है |
| `alignX(Position)` | `ImageView` (फ्लुएंट) | `CENTER` | क्षैतिज संरेखण (`START`/`CENTER`/`END`) |
| `alignY(Position)` | `ImageView` (फ्लुएंट) | `CENTER` | ऊर्ध्वाधर संरेखण |
| `getImage()` | `Image` | — | वर्तमान इमेज (या `null`) |
| `getImageSize()` | `ImageSize` | — | वर्तमान मोड |
| `getAutoWidth()` / `getAutoHeight()` | `int` | — | इमेज का आकार + `ingap` (यदि इमेज नहीं तो 0) |

## कॉलबैक और इवेंट
कोई नहीं। `ImageView` गैर-इंटरैक्टिव है।

## अवस्थाएं
कोई इंटरैक्शन अवस्था नहीं। यदि `image == null`, तो कुछ भी नहीं बनाया जाता।

### शीर्ष पर संरेखण के साथ Cover (क्रॉप)
```java
Image foto = new Image(caminhoFoto);
ImageView avatar = new ImageView(foto, ImageSize.FIT)
   .alignY(Position.START);      // काटते समय ऊपरी हिस्सा दृश्यमान रखता है
container.add(0.4f, avatar);
```

### रनटाइम में इमेज बदलना (फ्लुएंट)
```java
ImageView iv = new ImageView();          // खाली
container.add(LAY_FILL, iv);
// बाद में, लोड करते समय:
iv.image(new Image(novoCaminho))
  .imageSize(ImageSize.STRETCH);
```

## सर्वोत्तम प्रथाएं
- `ImageView` को एक परिभाषित लेआउट स्थान दें (`LAY_FILL` या भिन्न) — स्केल मोड केवल ज्ञात सीमाओं के साथ ही सार्थक है।
- जब `Image` का उपयोग न हो तो उसे `dispose()` से मुक्त करें (नेटिव संसाधन — अध्याय 18 देखें)।
- Web में, `ResizeQuality.FAST` को प्राथमिकता दें; `ImageView` का आंतरिक स्केल पहले ही इस पथ का उपयोग करता है।

## सामान्य गलतियां
- **`FIT` को `RATIO` के साथ भ्रमित करना:** `RATIO` letter-box करता है (पूरी समाती है); `FIT` ढकता है और काट सकता है। `STRETCH` विकृत करता है।
- **इमेज रहित `ImageView` से स्वचालित आकार की अपेक्षा करना:** `getAutoWidth/Height()` `image == null` होने पर `0` लौटाते हैं।

## यह भी देखें
- क्षेत्र गाइड: [`ui/`](/docs/ui) · रेसिपीज़: [`cookbook/`](/docs/cookbook)
- अवधारणा (इमेज, `Paint.image`): [`concepts/`](/docs/concepts)
- संबंधित कॉम्पोनेंट: [`Label`](/docs/ui/widgets/label) · [`Button`](/docs/ui/widgets/button)