# Dropdown

> ComboBox — तीर वाला बटन जो एकल चयन के लिए एक सूची खोलता है।

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

# Dropdown

`Dropdown` एक **ComboBox** प्रकार का कॉम्पोनेंट है: पाठ + तीर (`expand_more`) वाला एक बटन जो, छूने पर, आइटमों की सूची के साथ एक `ListViewWindow` खोलता है, जो उपलब्ध स्थान के अनुसार ऊपर या नीचे स्थित होती है। चयन के बाद, बटन का पाठ चुने गए आइटम को दिखाने लगता है। जब तक कुछ चयनित नहीं होता, यह **placeholder** प्रदर्शित करता है।

> 🟡 · **पैकेज:** `dev.crossfly.ui` · **विस्तारित करता है:** `Button` · **स्टाइल:** `DropdownStyle`

## कब उपयोग करें
- स्क्रीन पर जगह बचाते हुए, विकल्पों की एक मध्यम सूची में से **एकल** चयन।
- जब चयनित मान चुनाव के बाद दृश्यमान रहना चाहिए।

## कब उपयोग न करें
- 2–3 विकल्प जो हमेशा दिखते हैं → [`group`](/docs/ui/widgets/group) में [`option`](/docs/ui/widgets/option) का उपयोग करें।

## दिखावट
पाठ बाईं ओर; तीर `DropdownStyle.iconPosition` के अनुसार स्थित होता है: `START` (बाएं किनारे से सटा हुआ), `CENTER` (पाठ के बगल में, `Button` का डिफ़ॉल्ट लेआउट `TEXT_AT_LEFT`) या `END` (दाएं किनारे से सटा हुआ)। पॉपअप गोल किनारों वाली एक सफेद विंडो के रूप में खुलता है जो बाहर छूने पर बंद हो जाती है (`canMove(false).canHide(true)`)।

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

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

      Label saida = new Label("Nada selecionado");
      add(LAY_AUTO, saida);

      String[] itens = {"One", "Two", "Three", "Four", "Five"};
      Dropdown cb = new Dropdown("Selecione...", itens);
      // पॉपअप में चयन की पुष्टि के बाद onSelect ट्रिगर होता है
      cb.onSelect(e -> saida.setText("Escolhido: " + cb.getSelectedText()
                                     + " (idx " + cb.getSelectedIndex() + ")"));
      add(LAY_AUTO, cb);
   }
}
```

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

## बुनियादी उपयोग
```java
String[] itens = {"One", "Two", "Three", "Four", "Five"};
Dropdown cb = new Dropdown("Selecione...", itens);
cb.onSelect(e -> {
   String escolhido = cb.getSelectedText();
   System.out.println("escolhido: " + escolhido);
});
container.add(.95f, cb);
```

## कंस्ट्रक्टर
| कंस्ट्रक्टर | विवरण |
|---|---|
| `Dropdown(String placeholder, String[] items)` | Placeholder + आइटम। |
| `Dropdown(String[] items)` | डिफ़ॉल्ट placeholder `"Select..."` वाले आइटम। |

## गुण और अनुकूलन
| गुण / मेथड | प्रकार | डिफ़ॉल्ट | क्या करता है |
|---|---|---|---|
| `onSelect(Action)` | `Dropdown` (फ्लुएंट) | — | किसी चयन की पुष्टि पर कॉलबैक। |
| `popupHeightRatio(float)` | `Dropdown` (फ्लुएंट) | `0.4` | पॉपअप की ऊंचाई (स्क्रीन का 0..1), तब उपयोग होती है जब आदर्श ऊंचाई मापी नहीं जाती। |
| `popupWidthRatio(float)` | `Dropdown` (फ्लुएंट) | `-1` | पॉपअप की चौड़ाई (स्क्रीन का 0..1); ऋणात्मक = स्वयं Dropdown की चौड़ाई। |
| `getSelectedIndex()` | `int` | `-1` | वर्तमान आइटम का इंडेक्स (या `-1`)। |
| `getSelectedText()` | `String` | `null` | वर्तमान आइटम का पाठ (या `null`)। |
| `setSelectedIndex(int)` | `Dropdown` (फ्लुएंट) | — | प्रोग्रामैटिक रूप से चयन करता है; अमान्य इंडेक्स (जैसे `-1`) → placeholder पर वापस। |

## कॉलबैक और इवेंट
| कॉलबैक | कब चलता है |
|---|---|
| `onSelect(Action)` | पॉपअप में किसी चयन की पुष्टि **के बाद**। इसके अंदर `getSelectedText()`/`getSelectedIndex()` का उपयोग करें। |

`onTouchUp` `Button` से विरासत में मिलता है और `onUI(...)` के माध्यम से `openPopup()` शेड्यूल करता है।

## अवस्थाएं
- **placeholder**: कोई आइटम चयनित नहीं (`selectedIndex == -1`); placeholder पाठ प्रदर्शित करता है।
- **selecionado**: `selectedIndex >= 0`; आइटम का पाठ प्रदर्शित करता है।
- **pressed**: `Button` से विरासत में मिला (दबाने का fade)।

### प्रोग्रामैटिक चयन और placeholder पर वापस साफ़ करना
```java
String[] numeros = {"One", "Two", "Three"};
Dropdown cb = new Dropdown("", numeros);
cb.onSelect(e -> System.out.println("idx: " + cb.getSelectedIndex()));
container.add(.95f, cb);

cb.setSelectedIndex(1);   // "Two" को प्रोग्रामेटिक रूप से चुनता है
cb.setSelectedIndex(-1);  // साफ करता है: placeholder पर वापस जाता है
```

## सर्वोत्तम प्रथाएं
- चयन को `onSelect` के अंदर `getSelectedText()`/`getSelectedIndex()` के माध्यम से पढ़ें।
- फ़ील्ड को placeholder पर "रीसेट" करने के लिए `setSelectedIndex(-1)` का उपयोग करें (जैसे "Limpar" बटन में)।

## सामान्य गलतियां
- `items` को null पास करना: कंस्ट्रक्टर इसे संभालता है (`new String[0]`), लेकिन यदि सूची खाली है तो पॉपअप **नहीं खुलता**।
- बहु-चयन की अपेक्षा करना: `Dropdown` एकल चयन है; बहु के लिए, `ListView` `MULTIPLE` का उपयोग करें।

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