From f095bf70240a433f469b344d663d4b47f3f7975f Mon Sep 17 00:00:00 2001 From: MeirGavish Date: Tue, 16 Dec 2025 07:16:25 +0200 Subject: [PATCH] Added documentation for selection_grid.h (#309) * Added documentation for selection_grid.h * Fix clang-format * Update include/selection_grid.h Co-authored-by: Rickey * Added NULL-checks for selection_grid_move_selection_horz/vert() --------- Co-authored-by: Rickey --- include/selection_grid.h | 109 ++++++++++++++++++++++++++++++++++++--- source/selection_grid.c | 6 +++ 2 files changed, 109 insertions(+), 6 deletions(-) diff --git a/include/selection_grid.h b/include/selection_grid.h index 1ff7f44..1bfbd00 100644 --- a/include/selection_grid.h +++ b/include/selection_grid.h @@ -1,5 +1,18 @@ +/** + * @file selection_grid.h + * + * @brief An implementation for a selection grid that handles directional selection. + * + * The selection grid is not the same vertically and horizontally. + * It is divided into rows and each row defines its own callbacks for size, directional changes, + * and selection input. + * The idea is that it would be a more fitting simple solution for this game since it tends + * to be more dynamic horizontally than vertically with differing sizes of hands, jokers, etc. + */ + #ifndef SELECTION_GRID_H #define SELECTION_GRID_H + #include typedef POINT Selection; @@ -9,22 +22,60 @@ struct SelectionGrid; typedef struct SelectionGridRow SelectionGridRow; typedef struct SelectionGrid SelectionGrid; -// Called whenever there is a change in the selection cursor -// row_idx is the index of the row whose function is invoked - can be used to identify whether it is -// the previous or new selection row. +/** + * @brief Callback function type for handling selection changes in a SelectionGrid. + * + * This function is invoked whenever the selection cursor changes position within + * the grid. Used to perform custom actions based on selection changes, + * such as updating UI elements. + * + * @param selection_grid Pointer to the SelectionGrid instance where the change occurred + * @param row_idx Index of the row associated with this callback. This can be used to + * determine whether this is the previously selected row or the newly + * selected row + * @param prev_selection Pointer to the Selection state before the change occurred. + * Contains the previous cursor position + * @param new_selection Pointer to the Selection state after the change occurred. + * Contains the new cursor position + * + */ typedef void (*RowOnSelectionChangedFunc)( SelectionGrid* selection_grid, int row_idx, const Selection* prev_selection, const Selection* new_selection ); + +/** + * @brief Function pointer type for retrieving the size of a row in a selection grid. + * + * This is useful to allow generic row lengths e.g. when it can depend on the number of cards + * in hand, items in the shop, etc. + * + * @return int The number of elements in the row. + */ typedef int (*RowGetSizeFunc)(); -// Called for any non-directional key transit (either hit down or release up) -// The key itself and hit/release event will not be passed, -// the function will have to check key_hit(), key_released() etc. for the key it wants to check +/** + * @brief Callback function type for handling non-directional key presses in a selection grid row. + * + * This function is invoked whenever a non-directional key transitions + * (either hit down or release up). + * The specific key and the type of transition + * (press/release) are not passed as parameters to the callback. Instead, the implementation must + * query the key state using functions like key_hit(), key_released(), etc. to determine which key + * triggered the event and its current state. + * + * @param selection_grid Pointer to the SelectionGrid that contains the row receiving the key event + * @param selection Pointer to the Selection (row) that is handling the key transition. + */ typedef void (*RowOnKeyTransitFunc)(SelectionGrid* selection_grid, Selection* selection); +/** + * @brief A single row in the selection grid, defined by its callback functions. + * + * @var row_idx is used to easily identify the row within the callbacks. + */ struct SelectionGridRow { int row_idx; @@ -33,6 +84,12 @@ struct SelectionGridRow RowOnKeyTransitFunc on_key_transit; }; +/** + * @brief The core selection grid struct, represents the grid itself and its state. + * + * It can be statically defined with an array of @ref SelectionGridRow to define its + * contents. + */ struct SelectionGrid { const SelectionGridRow* rows; @@ -40,9 +97,49 @@ struct SelectionGrid Selection selection; }; +/** + * @brief Processes user input for the selection grid. + * + * This function handles input events (such as directional controls and button presses) + * and updates the selection grid's state accordingly. It should be called each frame + * to respond to user interactions with the grid. + * + * @param selection_grid Pointer to the SelectionGrid structure to process input for. + * Must not be NULL. NULL-checks are in place and will return early. + */ void selection_grid_process_input(SelectionGrid* selection_grid); +/** + * @brief Moves the selection horizontally within the selection grid. + * + * This function updates the current selection position by moving it horizontally + * based on the specified direction. This can be useful if some non-press event + * should update the selection grid. + * + * @param selection_grid Pointer to the SelectionGrid structure to operate on. + * Must not be NULL. NULL-checks are in place and will return early. + * @param direction_tribool Direction indicator for horizontal movement behaving like tonc's + * tribools: + * - Negative value: move left + * - Zero: no movement + * - Positive value: move right + */ void selection_grid_move_selection_horz(SelectionGrid* selection_grid, int direction_tribool); + +/** + * @brief Moves the selection vertically within the selection grid. + * + * This function updates the current selection position by moving it vertically + * based on the specified direction. This can be useful if some non-press event + * should update the selection grid. + * + * @param selection_grid Pointer to the SelectionGrid structure to operate on. + * Must not be NULL. NULL-checks are in place and will return early. + * @param direction_tribool Direction indicator for vertical movement behaving like tonc's tribools: + * - Negative value: move up + * - Zero: no movement + * - Positive value: move down + */ void selection_grid_move_selection_vert(SelectionGrid* selection_grid, int direction_tribool); #endif diff --git a/source/selection_grid.c b/source/selection_grid.c index 1a9d4bf..f42dd7b 100644 --- a/source/selection_grid.c +++ b/source/selection_grid.c @@ -23,6 +23,9 @@ static void selection_grid_process_directional_input(SelectionGrid* selection_gr void selection_grid_move_selection_horz(SelectionGrid* selection_grid, int direction_tribool) { + if (selection_grid == NULL) + return; + Selection new_selection = selection_grid->selection; new_selection.x += direction_tribool; if (selection_grid->selection.y >= 0 && @@ -41,6 +44,9 @@ void selection_grid_move_selection_horz(SelectionGrid* selection_grid, int direc void selection_grid_move_selection_vert(SelectionGrid* selection_grid, int direction_tribool) { + if (selection_grid == NULL) + return; + Selection selection = selection_grid->selection; Selection new_selection = selection; new_selection.y += direction_tribool;