Further header documentation improvements

This commit is contained in:
Robin Jones 2024-11-05 23:34:14 +00:00
parent 527e27525d
commit 0d2deaa4f4

View File

@ -1,109 +1,261 @@
/** /**
* @file components.h * @file components.h
* @brief Menu Components * @brief Menu Graphical User Interface Components
* @ingroup menu * @ingroup menu
*/ */
#ifndef COMPONENTS_H__ #ifndef COMPONENTS_H__
#define COMPONENTS_H__ #define COMPONENTS_H__
#include <libdragon.h> #include <libdragon.h>
#include "menu_state.h" #include "menu_state.h"
/** @brief File image Enumeration. */
typedef enum {
/** @brief Boxart image from the front */
IMAGE_BOXART_FRONT,
/** @brief Boxart image from the back */
IMAGE_BOXART_BACK,
/** @brief Boxart image from the top */
IMAGE_BOXART_TOP,
/** @brief Boxart image from the bottom */
IMAGE_BOXART_BOTTOM,
/** @brief Boxart image from the left side */
IMAGE_BOXART_LEFT,
/** @brief Boxart image from the right side */
IMAGE_BOXART_RIGHT,
/** @brief GamePak image from the front */
IMAGE_GAMEPAK_FRONT,
/** @brief GamePak image from the back */
IMAGE_GAMEPAK_BACK,
/** @brief File image thumbnail */
IMAGE_THUMBNAIL,
/** @brief List end marker */
IMAGE_TYPE_END
} file_image_type_t;
/** /**
* @addtogroup * @addtogroup menu_ui_components
* @{ menu_components * @{
*/ */
/**
* @brief File image Enumeration.
*
* Enumeration for different types of file images used in the GUI.
*/
typedef enum {
IMAGE_BOXART_FRONT, /**< Boxart image from the front */
IMAGE_BOXART_BACK, /**< Boxart image from the back */
IMAGE_BOXART_TOP, /**< Boxart image from the top */
IMAGE_BOXART_BOTTOM, /**< Boxart image from the bottom */
IMAGE_BOXART_LEFT, /**< Boxart image from the left side */
IMAGE_BOXART_RIGHT, /**< Boxart image from the right side */
IMAGE_GAMEPAK_FRONT, /**< GamePak image from the front */
IMAGE_GAMEPAK_BACK, /**< GamePak image from the back */
IMAGE_THUMBNAIL, /**< File image thumbnail */
IMAGE_TYPE_END /**< List end marker */
} file_image_type_t;
/**
* @brief Draw a box component.
*
* @param x0 Starting x-coordinate.
* @param y0 Starting y-coordinate.
* @param x1 Ending x-coordinate.
* @param y1 Ending y-coordinate.
* @param color Color of the box.
*/
void component_box_draw(int x0, int y0, int x1, int y1, color_t color); void component_box_draw(int x0, int y0, int x1, int y1, color_t color);
/**
* @brief Draw a border component.
*
* @param x0 Starting x-coordinate.
* @param y0 Starting y-coordinate.
* @param x1 Ending x-coordinate.
* @param y1 Ending y-coordinate.
*/
void component_border_draw(int x0, int y0, int x1, int y1); void component_border_draw(int x0, int y0, int x1, int y1);
/**
* @brief Draw the layout component.
*/
void component_layout_draw(void); void component_layout_draw(void);
/**
* @brief Draw a progress bar component.
*
* @param x0 Starting x-coordinate.
* @param y0 Starting y-coordinate.
* @param x1 Ending x-coordinate.
* @param y1 Ending y-coordinate.
* @param progress Progress value (0.0 to 1.0).
*/
void component_progressbar_draw(int x0, int y0, int x1, int y1, float progress); void component_progressbar_draw(int x0, int y0, int x1, int y1, float progress);
/**
* @brief Draw a seek bar component.
*
* @param progress Progress value (0.0 to 1.0).
*/
void component_seekbar_draw(float progress); void component_seekbar_draw(float progress);
/**
* @brief Draw a loader component.
*
* @param position Position value (0.0 to 1.0).
*/
void component_loader_draw(float position); void component_loader_draw(float position);
/**
* @brief Draw a scrollbar component.
*
* @param x Starting x-coordinate.
* @param y Starting y-coordinate.
* @param width Width of the scrollbar.
* @param height Height of the scrollbar.
* @param position Current position.
* @param items Total number of items.
* @param visible_items Number of visible items.
*/
void component_scrollbar_draw(int x, int y, int width, int height, int position, int items, int visible_items); void component_scrollbar_draw(int x, int y, int width, int height, int position, int items, int visible_items);
/**
* @brief Draw a list scrollbar component.
*
* @param position Current position.
* @param items Total number of items.
* @param visible_items Number of visible items.
*/
void component_list_scrollbar_draw(int position, int items, int visible_items); void component_list_scrollbar_draw(int position, int items, int visible_items);
/**
* @brief Draw a dialog component.
*
* @param width Width of the dialog.
* @param height Height of the dialog.
*/
void component_dialog_draw(int width, int height); void component_dialog_draw(int width, int height);
/**
* @brief Draw a message box component.
*
* @param fmt Format string for the message.
* @param ... Additional arguments for the format string.
*/
void component_messagebox_draw(char *fmt, ...); void component_messagebox_draw(char *fmt, ...);
/**
* @brief Draw the main text component.
*
* @param align Horizontal alignment.
* @param valign Vertical alignment.
* @param fmt Format string for the text.
* @param ... Additional arguments for the format string.
*/
void component_main_text_draw(rdpq_align_t align, rdpq_valign_t valign, char *fmt, ...); void component_main_text_draw(rdpq_align_t align, rdpq_valign_t valign, char *fmt, ...);
/**
* @brief Draw the actions bar text component.
*
* @param align Horizontal alignment.
* @param valign Vertical alignment.
* @param fmt Format string for the text.
* @param ... Additional arguments for the format string.
*/
void component_actions_bar_text_draw(rdpq_align_t align, rdpq_valign_t valign, char *fmt, ...); void component_actions_bar_text_draw(rdpq_align_t align, rdpq_valign_t valign, char *fmt, ...);
/**
* @brief Initialize the background component.
*
* @param cache_location Location of the cache.
*/
void component_background_init(char *cache_location); void component_background_init(char *cache_location);
/**
* @brief Free the background component resources.
*/
void component_background_free(void); void component_background_free(void);
/**
* @brief Replace the background image.
*
* @param image New background image.
*/
void component_background_replace_image(surface_t *image); void component_background_replace_image(surface_t *image);
/**
* @brief Draw the background component.
*/
void component_background_draw(void); void component_background_draw(void);
/**
* @brief Draw the file list component.
*
* @param list List of entries.
* @param entries Number of entries.
* @param selected Index of the selected entry.
*/
void component_file_list_draw(entry_t *list, int entries, int selected); void component_file_list_draw(entry_t *list, int entries, int selected);
/**
* @brief Context menu structure.
*/
typedef struct component_context_menu { typedef struct component_context_menu {
int row_count; int row_count; /**< Number of rows in the context menu */
int row_selected; int row_selected; /**< Index of the selected row */
bool hide_pending; bool hide_pending; /**< Flag to indicate if hiding is pending */
struct component_context_menu *parent; struct component_context_menu *parent; /**< Pointer to the parent context menu */
struct component_context_menu *submenu; struct component_context_menu *submenu; /**< Pointer to the submenu */
struct { struct {
const char *text; const char *text; /**< Text of the menu item */
void (*action) (menu_t *menu, void *arg); void (*action)(menu_t *menu, void *arg); /**< Action function for the menu item */
void *arg; void *arg; /**< Argument for the action function */
struct component_context_menu *submenu; struct component_context_menu *submenu; /**< Pointer to the submenu */
} list[]; } list[]; /**< List of menu items */
} component_context_menu_t; } component_context_menu_t;
#define COMPONENT_CONTEXT_MENU_LIST_END { .text = NULL } #define COMPONENT_CONTEXT_MENU_LIST_END { .text = NULL } /**< End marker for the context menu list */
/**
* @brief Initialize the context menu component.
*
* @param cm Pointer to the context menu structure.
*/
void component_context_menu_init(component_context_menu_t *cm); void component_context_menu_init(component_context_menu_t *cm);
/**
* @brief Show the context menu component.
*
* @param cm Pointer to the context menu structure.
*/
void component_context_menu_show(component_context_menu_t *cm); void component_context_menu_show(component_context_menu_t *cm);
/**
* @brief Process the context menu component.
*
* @param menu Pointer to the menu structure.
* @param cm Pointer to the context menu structure.
* @return True if the context menu was processed, false otherwise.
*/
bool component_context_menu_process(menu_t *menu, component_context_menu_t *cm); bool component_context_menu_process(menu_t *menu, component_context_menu_t *cm);
/**
* @brief Draw the context menu component.
*
* @param cm Pointer to the context menu structure.
*/
void component_context_menu_draw(component_context_menu_t *cm); void component_context_menu_draw(component_context_menu_t *cm);
/** @brief Box Art Structure. */ /**
* @brief Box Art Structure.
*/
typedef struct { typedef struct {
bool loading; bool loading; /**< Flag to indicate if the box art is loading */
surface_t *image; surface_t *image; /**< Pointer to the box art image */
} component_boxart_t; } component_boxart_t;
/**
* @brief Initialize the box art component.
*
* @param storage_prefix Prefix for the storage location.
* @param game_code Game code for the box art.
* @param current_image_view Current image view type.
* @return Pointer to the initialized box art component.
*/
component_boxart_t *component_boxart_init(const char *storage_prefix, char *game_code, file_image_type_t current_image_view); component_boxart_t *component_boxart_init(const char *storage_prefix, char *game_code, file_image_type_t current_image_view);
/**
* @brief Free the box art component resources.
*
* @param b Pointer to the box art component.
*/
void component_boxart_free(component_boxart_t *b); void component_boxart_free(component_boxart_t *b);
/**
* @brief Draw the box art component.
*
* @param b Pointer to the box art component.
*/
void component_boxart_draw(component_boxart_t *b); void component_boxart_draw(component_boxart_t *b);
/** @} */ /* menu_components */ /** @} */ /* menu_ui_components */
#endif /* COMPONENTS_H__ */
#endif