/******************************************************************************
 * @file        key.h
 * @brief       按键驱动模块头文件
 * @details     本文件定义了按键驱动的接口和数据结构，包括按键类型枚举、
 *              按键回调函数类型定义以及外部接口函数声明。
 * @author      阜阳师范大学物电学院
 * @version     V0.1
 * @date        2026.1.19
 * @note        依赖库: MultiButton
 *              使用方式: 
 *              1. 调用 Key_Init() 初始化按键硬件
 *              2. 调用 Key_RegisterCallback() 注册按键回调函数
 *              3. 在定时器中调用 Button_Ticks() 进行按键扫描
 ******************************************************************************/

#ifndef __KEY_H__
#define __KEY_H__

#include "./SYSTEM/sys/sys.h"
#include "MultiButton.h"

/* ============================================================================
 * 按键类型枚举定义
 * ============================================================================ */
/**
 * @brief 按键类型枚举
 * @details 定义了系统中所有支持的按键类型
 */
typedef enum
{
    KEY_NONE = 0,         /**< 无按键按下 */
    KEY_ENTER,            /**< 确认键 */
    KEY_UP,               /**< 向上键 */
    KEY_DOWN,             /**< 向下键 */
    KEY_ESC,              /**< 取消键 */
    KEY_ADD,              /**< 加键 */
    KEY_DEC,              /**< 减键 */
    KEY_LEFT,             /**< 向左键 */
    KEY_RIGHT,            /**< 向右键 */
    KEY_RESET,            /**< 复位键 */
    KEY_FACTORY,          /**< 工厂模式键 */
} KEY_TYPE;

/* ============================================================================
 * 回调函数类型定义
 * ============================================================================ */
/**
 * @brief 按键回调函数类型定义
 * @param key_type 按键类型（KEY_TYPE 枚举值）
 * @note  业务逻辑层需要实现此类型的回调函数，用于处理按键事件
 *        当检测到按键按下时，会调用注册的回调函数
 * @retval 无
 */
typedef void (*KeyCallback)(KEY_TYPE key_type);

/* ============================================================================
 * 外部接口函数声明
 * ============================================================================ */

/**
 * @brief  按键硬件初始化函数
 * @note   初始化所有按键的 GPIO 配置和 MultiButton 库
 *          特殊处理：禁用 JTAG 以释放 PB3 等引脚
 *          必须在系统初始化时调用一次
 * @retval 无
 */
void Key_Init(void);

/**
 * @brief  注册按键回调函数（供业务逻辑层调用）
 * @param  callback 按键回调函数指针，当检测到按键事件时会调用此函数
 * @note   业务逻辑层通过此函数注册按键处理回调
 *          如果传入 NULL，则取消已注册的回调函数
 * @retval 无
 */
void Key_RegisterCallback(KeyCallback callback);

/**
 * @brief  MultiButton 库的按键扫描函数宏定义
 * @note   需要在定时器中周期性调用此函数（建议 5-10ms 调用一次）
 *          用于 MultiButton 库进行按键状态扫描和事件检测
 * @retval 无
 */
#define Button_Ticks()                 button_ticks()

#endif /* __KEY_H__ */