# छवियाँ

> ImageView के साथ छवियाँ लोड और प्रदर्शित करना, स्केल मोड (ImageSize) और पृष्ठभूमि छवियाँ।

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

# छवियाँ (`ImageView`)

`ImageView` किसी कॉम्पोनेंट के भीतर एक `Image` प्रदर्शित करता है, **स्केल** (`ImageSize`) और
**संरेखण** के नियंत्रण के साथ।

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

import java.io.*;                     // IOException

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

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

      // फॉलबैक के साथ लोड करें: new Image(path) ImageException/IOException फेंकता है (चेक्ड)।
      Image logo;
      try
      {
         logo = new Image("images/logo.png");   // ऐप का रिसोर्स पथ
      }
      catch (ImageException | IOException e)
      {
         Debug.log("falha ao carregar: " + e);
         return;   // अगर इमेज न मिले तो असेंबली रोक देता है
      }

      // ImageView के साथ दिखाएं, अनुपात (RATIO) बनाए रखते हुए और केंद्रित।
      ImageView foto = new ImageView(logo, ImageSize.RATIO)
         .alignX(Position.CENTER)
         .alignY(Position.CENTER);
      add(0.4f, foto);   // ऊंचाई का 40% (VerticalLayout)

      // खुद विंडो की पृष्ठभूमि इमेज (Component का मेथड, ImageView नहीं)।
      addBackgroundImage(logo, ImageSize.FIT, 0.5f, 0.5f);   // केंद्रित, ढंकते हुए
   }
}
```
> नीचे दिए गए स्निपेट **सिर्फ़ मूल भाग** दिखाते हैं (जो `onShow()` के अंदर जाता है)। चलाने के लिए, इन्हें ऊपर वाले `MainWindow` कंकाल में रखें।

## एक `Image` लोड करना
```java
Image logo;
try {
   logo = new Image("images/logo.png");   // ऐप का रिसोर्स पथ
} catch (ImageException | IOException e) {
   Debug.log("falha ao carregar: " + e);
   return;
}
```
उपयोगी कंस्ट्रक्टर: `new Image(String path)`, `new Image(byte[] bytes)`, `new Image(InputStream)`,
`new Image(int w, int h)` (बनाने के लिए खाली बिटमैप)। **सभी `ImageException` फेंक सकते हैं** (और
path/stream वाला `IOException` भी)।

## प्रदर्शित करना
```java
ImageView foto = new ImageView(logo, ImageSize.RATIO)
   .alignX(Position.CENTER)
   .alignY(Position.CENTER);
painel.add(0.4f, foto);   // ऊंचाई का 40% (VerticalLayout)
```
कंस्ट्रक्टर: `ImageView()`, `ImageView(Image)`, `ImageView(Image, ImageSize)`। फ़्लुएंट: `.image(Image)`,
`.imageSize(ImageSize)`, `.alignX(Position)`, `.alignY(Position)`।

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

> व्यावहारिक नियम: **`RATIO`** = "पूरी दिखे" (letterbox); **`FIT`** = "बिना विकृति के भरे"
> (अतिरिक्त को काटता है); **`STRETCH`** = विकृत करते हुए भरे (फ़ोटो में इससे बचें)।

## पृष्ठभूमि छवि (किसी कॉम्पोनेंट/स्क्रीन की)
यह एक `ImageView` नहीं है — यह स्वयं `Component` की एक विधि है:
```java
janela.addBackgroundImage(fundo, ImageSize.FIT, 0.5f, 0.5f);   // केंद्रित, ढंकते हुए
// या Relative द्वारा आकारित:
janela.addBackgroundImage(marca, Relative.ofScreen(0.3f), null, 0.5f, 0.9f);
```
`centerX`/`centerY` 0–1 हैं (छवि के केंद्र की सापेक्ष स्थिति)।

## सर्वोत्तम अभ्यास
- लोड करते समय **हमेशा `ImageException`/`IOException` को संभालें** — ये checked हैं।
- फ़ोटो: `RATIO` (सब कुछ दिखाएँ) या `FIT` (काटते हुए भरें)। `STRETCH` से बचें (विकृत करता है)।
- बड़ी छवियों को paint थ्रेड के बाहर लोड करें और `Component.onUI(...)` के साथ वापस आएँ।

## आम गलतियाँ
- `new Image(...)` के अपवादों को न पकड़ना → कम्पाइल नहीं होता।
- किसी व्यक्ति की फ़ोटो में `STRETCH` का उपयोग करना (विकृति); `FIT` का उपयोग करें।
- `RATIO` (भीतर फ़िट) को `FIT` (ढँकता और काटता है) के साथ भ्रमित करना।

## यह भी देखें
- [कस्टम ड्राइंग](/docs/ui/images-and-graphics/custom-drawing) · [Whiteboard](/docs/ui/images-and-graphics/whiteboard)
- कैटलॉग: [ImageView](/docs/ui/widgets/imageview) · संदर्भ: अध्याय 18 — छवियाँ