.topic lib.listhelp
.title List Helper Library
.toc 1 List Helper Library
.index listhelp
.index widgetDrawDropdownArrow
.index widgetMaxItemLen
.index widgetNavigateIndex
.index widgetDropdownPopupRect
.index widgetPaintPopupList

.h1 List Helper Library

Shared helper routines for dropdown and list-based widget DXEs (ListBox, Dropdown, ComboBox, ListView, TreeView). Provides dropdown arrow rendering, item measurement, keyboard navigation, popup geometry calculation, and popup list painting.

Header: listhelp/listHelp.h

.h2 Constants

.table
  Constant               Value   Description
  --------               -----   -----------
  DROPDOWN_BTN_WIDTH     16      Width of the dropdown arrow button in pixels.
  DROPDOWN_MAX_VISIBLE   8       Maximum number of items visible in a popup list.
.endtable

.h2 widgetDrawDropdownArrow

Draw the triangular dropdown arrow glyph centered at a given position.

.code
void widgetDrawDropdownArrow(DisplayT *d, const BlitOpsT *ops,
    int32_t centerX, int32_t centerY, uint32_t color);
.endcode

.table
  Parameter   Description
  ---------   -----------
  d           Display context.
  ops         Blit operations vtable for the active pixel depth.
  centerX     Horizontal center of the arrow in backbuffer coordinates.
  centerY     Vertical center of the arrow in backbuffer coordinates.
  color       Pre-packed pixel color for the arrow.
.endtable

.h2 widgetMaxItemLen

Scan an array of strings and return the length (in characters) of the longest item.

.code
int32_t widgetMaxItemLen(const char **items, int32_t count);
.endcode

.table
  Parameter   Description
  ---------   -----------
  items       Array of null-terminated string pointers.
  count       Number of items in the array.
.endtable

Returns the character length of the longest item, or 0 if count is zero.

.h2 widgetNavigateIndex

Compute a new selected index from a navigation key press. Handles Up, Down, Home, End, Page Up, and Page Down.

.code
int32_t widgetNavigateIndex(int32_t key, int32_t current,
    int32_t count, int32_t pageSize);
.endcode

.table
  Parameter   Description
  ---------   -----------
  key         Keyboard scancode (Up, Down, Home, End, PgUp, PgDn).
  current     Currently selected index.
  count       Total number of items in the list.
  pageSize    Number of visible items (used for PgUp/PgDn step size).
.endtable

Returns the new index, clamped to [0, count-1].

.h2 widgetDropdownPopupRect

Calculate the screen rectangle for a dropdown popup list, positioning it below the owning widget and clamping to screen bounds.

.code
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);
.endcode

.table
  Parameter   Description
  ---------   -----------
  w           The widget that owns the popup (Dropdown, ComboBox, etc.).
  font        Bitmap font used for item text (determines row height).
  contentH    Height of the widget's content area in pixels.
  itemCount   Total number of items in the list.
  popX        Output: popup X position (screen coordinates).
  popY        Output: popup Y position (screen coordinates).
  popW        Output: popup width in pixels.
  popH        Output: popup height in pixels.
.endtable

The popup is sized to show up to DROPDOWN_MAX_VISIBLE items.

.h2 widgetPaintPopupList

Render a popup item list with highlight, scrolling, and beveled border.

.code
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);
.endcode

.table
  Parameter   Description
  ---------   -----------
  d           Display context.
  ops         Blit operations vtable.
  font        Bitmap font for rendering item text.
  colors      Color scheme for background, text, and highlight colors.
  popX        Popup X position (from widgetDropdownPopupRect).
  popY        Popup Y position.
  popW        Popup width.
  popH        Popup height.
  items       Array of null-terminated item strings.
  itemCount   Total number of items.
  hoverIdx    Index of the highlighted (hovered/selected) item, or -1 for none.
  scrollPos   Index of the first visible item (scroll offset).
.endtable