100 lines
2.6 KiB
Markdown
100 lines
2.6 KiB
Markdown
# 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 *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).
|