# listhelp -- Shared List/Dropdown Helper Library

Shared infrastructure for list and dropdown widgets, built as
`listhelp.lib` (DXE3 module). Provides dropdown arrow drawing, item
measurement, keyboard navigation, popup rectangle calculation, and
popup list painting.

Used by: Dropdown, ComboBox, ListBox, ListView, TreeView.


## API Reference

### Dropdown Arrow Glyph

```c
void widgetDrawDropdownArrow(DisplayT *d, const BlitOpsT *ops,
    int32_t centerX, int32_t centerY, uint32_t color);
```

Draws the small downward-pointing triangle glyph used on dropdown
buttons.

### Item Measurement

```c
int32_t widgetMaxItemLen(const char **items, int32_t count);
```

Scans an array of item strings and returns the length of the longest
one. Used to size dropdown popups and list columns to fit their
content.

### Keyboard Navigation

```c
int32_t widgetNavigateIndex(int32_t key, int32_t current,
    int32_t count, int32_t pageSize);
```

Maps arrow key presses to index changes for list navigation. Handles
Up, Down, Home, End, PageUp, and PageDown. Returns the new selected
index, clamped to valid range.

### Popup Rectangle Calculation

```c
void widgetDropdownPopupRect(WidgetT *w, const BitmapFontT *font,
    int32_t contentH, int32_t itemCount,
    int32_t *popX, int32_t *popY,
    int32_t *popW, int32_t *popH);
```

Computes the screen rectangle for a dropdown popup overlay. Positions
the popup below the widget (or above if there is not enough room
below). Limits height to `DROPDOWN_MAX_VISIBLE` items.

### Popup List Painting

```c
void widgetPaintPopupList(DisplayT *d, const BlitOpsT *ops,
    const BitmapFontT *font, const ColorSchemeT *colors,
    int32_t popX, int32_t popY, int32_t popW, int32_t popH,
    const char **items, int32_t itemCount,
    int32_t hoverIdx, int32_t scrollPos);
```

Renders the popup overlay list with items, selection highlight, scroll
position, and beveled border. Used by Dropdown and ComboBox for their
popup overlays.

### Constants

| Name | Value | Description |
|------|-------|-------------|
| `DROPDOWN_BTN_WIDTH` | 16 | Width of dropdown arrow button area |
| `DROPDOWN_MAX_VISIBLE` | 8 | Maximum visible items in popup list |


## Exported Symbols

Matches prefixes: `_widgetDraw*`, `_widgetDropdown*`, `_widgetMax*`,
`_widgetNavigate*`, `_widgetPaint*`.


## Files

| File | Description |
|------|-------------|
| `listHelp.h` | Public API header |
| `listHelp.c` | Complete implementation |
| `Makefile` | Builds `bin/libs/listhelp.lib` + dep file |


## Build

```
make            # builds bin/libs/listhelp.lib + listhelp.dep
make clean      # removes objects, library, and dep file
```

Depends on: `libtasks.lib`, `libdvx.lib` (via listhelp.dep).