dusk/archive/dusk/ui/focus/uifocus.h

/**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

#pragma once
#include "uifocusitem.h"
#include "input/inputaction.h"

/** Maximum depth of the focus stack. */
#define UI_FOCUS_STACK_MAX 8

/**
 * How long a direction must be held before repeating begins, in seconds.
 */
#define UI_FOCUS_HOLD_DELAY 0.5f

/**
 * Interval between repeated moves while a direction is held, in seconds.
 */
#define UI_FOCUS_HOLD_REPEAT 0.1f

typedef struct {
  inputbind_t action;
  uifocusdirection_t direction;
  int8_t dx;
  int8_t dy;
} uifocusdirmap_t;

/**
 * Mapping of input actions to focus directions, terminated by an
 * entry with action == INPUT_BIND_NULL.
 */
extern const uifocusdirmap_t UI_FOCUS_DIR_MAP[];

/**
 * A stack of focused UI items. Push an item when a widget captures
 * focus; pop it when focus is released. The topmost item is always
 * the active focus context.
 */
typedef struct {
  uifocusitem_t items[UI_FOCUS_STACK_MAX];
  uint8_t count;
  uifocusdirection_t direction;
  float_t timeHeld;
  bool_t pushedThisTick;
} uifocus_t;

extern uifocus_t UI_FOCUS;

/**
 * Initializes the focus system, zeroing all state.
 */
void uiFocusInit(void);

/**
 * Pushes a new focus item onto the stack with the given grid dimensions
 * and callbacks. x and y are initialized to 0.
 *
 * @param cols      Number of columns in the focus grid.
 * @param rows      Number of rows in the focus grid.
 * @param selected  Called when the user selects the focused cell.
 * @param changed   Called when the focused cell position changes.
 * @param closed    Called when this focus item is popped.
 * @param direction Called on a direction press/hold before the default
 *                  cell-to-cell movement is applied; may be NULL.
 * @param user      Arbitrary pointer stored on the item before changed fires.
 * @returns Pointer to the newly pushed focus item.
 */
uifocusitem_t * uiFocusPush(
  const uint8_t cols,
  const uint8_t rows,
  uifocusitemcallback_t selected,
  uifocusitemcallback_t changed,
  uifocusitemcallback_t closed,
  uifocusitemdirectioncallback_t direction,
  void *user
);

/**
 * Pops the topmost focus item from the stack, invoking its closed
 * callback if one is set.
 */
void uiFocusPop(void);

/**
 * Pops an item and anything that was pushed after it from the focus stack.
 * 
 * @param item The focus item to pop to. Must be on the stack.
 */
void uiFocusPopItem(uifocusitem_t *item);

/**
 * Manually sets the cursor position of the topmost focus item and
 * fires its changed callback.
 *
 * @param x Column to move to.
 * @param y Row to move to.
 */
void uiFocusSetPosition(uifocusitem_t *item, const uint8_t x, const uint8_t y);

/**
 * Moves the topmost focus item one step in the given direction,
 * wrapping at the grid edges, and fires its changed callback.
 *
 * @param item The focus item to move.
 * @param dir Direction to move.
 */
void uiFocusMoveDirection(
  uifocusitem_t *item,
  const uifocusdirection_t dir
);

/**
 * Handles a direction press/hold for the given item: gives the item's
 * direction callback (if any) first refusal, falling back to the
 * default cell-to-cell movement if it's unset or returns false.
 *
 * @param item The focus item to move.
 * @param dir Direction that was pressed or held.
 */
void uiFocusHandleDirection(
  uifocusitem_t *item,
  const uifocusdirection_t dir
);

/**
 * Updates the focus system. Handles first-press movement and
 * held-direction repeating. Called once per game tick.
 */
void uiFocusUpdate(void);