From ac02414904f541de9335e51c2b15817d79aa1ce2 Mon Sep 17 00:00:00 2001 From: Maschell Date: Fri, 24 Jan 2025 17:51:06 +0100 Subject: [PATCH] Update documentation of button combo API --- include/wups/button_combo/WUPSButtonCombo.h | 1 + include/wups/button_combo/api.h | 484 ++++++++++++++++---- include/wups/button_combo/defines.h | 76 ++- libraries/libwups/button_combo.cpp | 165 ++++--- libraries/libwups/button_comboCPP.cpp | 19 +- plugins/example_plugin_cpp/src/main.cpp | 10 +- 6 files changed, 574 insertions(+), 181 deletions(-) diff --git a/include/wups/button_combo/WUPSButtonCombo.h b/include/wups/button_combo/WUPSButtonCombo.h index 76c4595..591a3a7 100644 --- a/include/wups/button_combo/WUPSButtonCombo.h +++ b/include/wups/button_combo/WUPSButtonCombo.h @@ -13,6 +13,7 @@ namespace WUPSButtonComboAPI { struct MetaOptions { std::string label; }; + static std::optional Create(const WUPSButtonCombo_ComboOptions &options, WUPSButtonCombo_ComboStatus &outStatus, WUPSButtonCombo_Error &outError) noexcept; diff --git a/include/wups/button_combo/api.h b/include/wups/button_combo/api.h index 8d97bd3..2053fe7 100644 --- a/include/wups/button_combo/api.h +++ b/include/wups/button_combo/api.h @@ -9,53 +9,98 @@ extern "C" { #endif /** - * @brief Get a string representation of the specified button_combo status. - * - * This function returns a string representation of the provided button_combo status. - * - * @param status The button_combo status to get the string representation for. - * @return A pointer to a string describing the provided button_combo status. + * This function returns a string representation of the provided WUPSButtonCombo_Error. + * + * @param status The status to get the string representation for. + * @return A pointer to a string describing the provided status. **/ const char *WUPSButtonComboAPI_GetStatusStr(WUPSButtonCombo_Error status); /** - * @brief Get a string representation of the specified controller type. - * - * This function returns a string representation of the provided controller type. - * - * @param controller The controller to get the string representation for. - * @return A pointer to a string describing the provided controller. + * This function returns a string representation of the provided WUPSButtonCombo_ControllerTypes. + * + * @param controller The controller to get the string representation for. + * @return A pointer to a string describing the provided controller. **/ const char *WUPSButtonComboAPI_GetControllerTypeStr(WUPSButtonCombo_ControllerTypes controller); /** - * @brief Adds a button combo which triggers a callback if a certain button combination is pressed on any controller. - * - * Registers a unique button combination which will trigger a callback if the combo is pressed down **on any connected controller** and the button combo is valid - * - * A press down is only detecting while pressing down buttons. Releasing a button will never trigger the callback. - * For example if the combo is "L+R+X" but you hold down "L+R+Y", press then "X" and release "Y" the combo won't be triggered. - * - * Conflict management: - * The button combination is only active if this function returns WUPS_BUTTON_COMBO_ERROR_SUCCESS and outStatus is WUPS_BUTTON_COMBO_COMBO_STATUS_VALID. - * - * If any other (valid) button combination overlaps with the button combo, the outStatus WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT and the callback will not be triggered - * even if the combination is pressed. - * - * Even if the button combination would be unique and valid (due to the change or removal of other combos), the status won't update itself. - * To resolve a WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT combo state you **always** have to the combo information via WUPSButtonComboAPI_UpdateButtonComboInfo or WUPSButtonComboAPI_UpdateButtonComboSimple. - * - * Conflict example: It's not possible to add any new valid button combo containing "L+R" (e.g. "X+L+R"), if there already is a button combination "L+R". - * Furthermore, it's also not possible to add a "L" or "R" combo if there already is a button combination "L+R". - * - * @param label Label of this button combo - * @param combo Combination which should be checked - * @param callback - * @param context - * @param outHandle The handle of the combo will be stored here. Must not be nullptr. - * @param outStatus The status of the combo will be stored here. Only if the status is WUPS_BUTTON_COMBO_COMBO_STATUS_VALID the combo is valid. Must not be nullptr. - * @return + * This function returns a string representation of the provided WUPSButtonCombo_ComboStatus. + * + * @param status The combo status to get the string representation for. + * @return A pointer to a string describing the provided combo status. **/ +const char *WUPSButtonComboAPI_GetComboStatusStr(WUPSButtonCombo_ComboStatus status); + + +/** + * Creates a button combo which triggers a callback if this combo is detected. + * + * This function takes a generic `WUPSButtonCombo_ComboOptions` which defines how the combo should be checked. + * + * Depending on the given type, the combo will either check for holding (for X ms) or pressing a button on for a given + * controller mask. The type also defines if it's an "observer" or not. Observers won't check for combo conflicts. + * + * If the given type is not an `observer` and any other (valid) button combination overlaps with new combo, then the + * `outStatus` will be set to `WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT` and the combo will be inactive. The original + * ButtonCombo which had the combo first won't be affected at all. + * In conflict state the callback will not be triggered even if the combination is pressed. If `observer` is set to + * "true", the combo won't check for conflicts. + * + * To resolve a WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT combo state you **always** have to update combo information + * via @WUPSButtonComboAPI_UpdateControllerMask or @WUPSButtonComboAPI_UpdateButtonCombo. The state won't update itself, + * even it the combo has no conflicts in a later point in time (e.g. due to other conflicting combos being removed in the meantime) + * + * Conflict example (only relevant if combo type is not an observer): + * It's not possible to add any new valid button combo containing "L+R" (e.g. "X+L+R"), if there already is a button + * combination "L+R". Furthermore, it's also not possible to add a "L" or "R" combo if there already is a button + * combination "L+R". + * + * See @WUPSButtonComboAPI_RemoveButtonCombo to remove an added button combo. + * + * Make sure to remove all button combos in DEINITIALIZE_PLUGIN! + * + * @param options options of this button combo + * @param outHandle The handle of the button combo will be stored here on success. Must not be nullptr. + * @param outStatus (optional) The status of the combo will be stored here. Only if the status is WUPS_BUTTON_COMBO_COMBO_STATUS_VALID the combo is valid. Can be NULL. + * @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. Please check the outStatus as well. +*/ +WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonCombo(const WUPSButtonCombo_ComboOptions *options, + WUPSButtonCombo_ComboHandle *outHandle, + WUPSButtonCombo_ComboStatus *outStatus); + +/** + * Creates a "PressDown" button combo which triggers a callback when given combo for a given controller has been pressed + * + * See @WUPSButtonComboAPI_AddButtonCombo for detailed information about button combos. + * See @WUPSButtonComboAPI_RemoveButtonCombo to remove the added button combo. + * + * @param label label of the button combo + * @param controllerMask Mask of controllers which should be checked. Must not be empty. + * @param combo Combo which should be checked. Must not be empty + * @param callback Callback that will be called if a button combo is detected. Must not be nullptr. + * @param context Context for the callback. Can be nullptr. + * @param observer Defines if this combo should check for conflicts. Set it to "true" to be an observer and ignore conflicts. + * @param outHandle The handle of the button combo will be stored here on success. Must not be nullptr. + * @param outStatus (optional) The status of the combo will be stored here. Only if the status is WUPS_BUTTON_COMBO_COMBO_STATUS_VALID the combo is valid. Can be NULL. + * @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. Please check the outStatus as well. +*/ +WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboPressEx(const char *label, + WUPSButtonCombo_ControllerTypes controllerMask, + WUPSButtonCombo_Buttons combo, + WUPSButtonCombo_ComboCallback callback, + void *context, + bool observer, + WUPSButtonCombo_ComboHandle *outHandle, + WUPSButtonCombo_ComboStatus *outStatus); + +/** + * Wrapper for `WUPSButtonComboAPI_AddButtonComboPressDown` with + * - `observer` set to "true" + * - `controllerMask` set to "WUPS_BUTTON_COMBO_CONTROLLER_ALL" + * + * See: @WUPSButtonComboAPI_AddButtonComboPressEx for more information. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboPressDown(const char *label, WUPSButtonCombo_Buttons combo, WUPSButtonCombo_ComboCallback callback, @@ -63,40 +108,54 @@ WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboPressDown(const char *lab WUPSButtonCombo_ComboHandle *outHandle, WUPSButtonCombo_ComboStatus *outStatus); +/** + * Wrapper for `WUPSButtonComboAPI_AddButtonComboPressDownObserver` with + * - `observer` set to "true" + * - `controllerMask` set to "WUPS_BUTTON_COMBO_CONTROLLER_ALL" + * + * See: @WUPSButtonComboAPI_AddButtonComboPressEx for more information. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboPressDownObserver(const char *label, WUPSButtonCombo_Buttons combo, WUPSButtonCombo_ComboCallback callback, void *context, WUPSButtonCombo_ComboHandle *outHandle, WUPSButtonCombo_ComboStatus *outStatus); + /** - * @brief Adds a button combo which triggers a callback if a certain button combination was hold for X ms on any controller. + * Creates a "Hold" button combo which triggers a callback when given combo for a given controller has been hold for X ms + * + * See @WUPSButtonComboAPI_AddButtonCombo for detailed information about button combos. + * See @WUPSButtonComboAPI_RemoveButtonCombo to remove the added button combo. + * + * @param label label of the button combo + * @param controllerMask Mask of controllers which should be checked. Must not be empty. + * @param combo Combo which should be checked. Must not be empty + * @param holdDurationInMs Defines how long the button combination need to be hold down. Must not be 0. + * @param callback Callback that will be called if a button combo is detected. Must not be nullptr. + * @param context Context for the callback. Can be nullptr. + * @param observer Defines if this combo should check for conflicts. Set it to "true" to be an observer and ignore conflicts. + * @param outHandle The handle of the button combo will be stored here on success. Must not be nullptr. + * @param outStatus (optional) The status of the combo will be stored here. Only if the status is WUPS_BUTTON_COMBO_COMBO_STATUS_VALID the combo is valid. Can be NULL. + * @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. Please check the outStatus as well. + */ +WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHoldEx(const char *label, + WUPSButtonCombo_ControllerTypes controllerMask, + WUPSButtonCombo_Buttons combo, + uint32_t holdDurationInMs, + WUPSButtonCombo_ComboCallback callback, + void *context, + bool observer, + WUPSButtonCombo_ComboHandle *outHandle, + WUPSButtonCombo_ComboStatus *outStatus); + +/** + * Wrapper for `WUPSButtonComboAPI_AddButtonComboPressDownObserver` with + * - `observer` set to "false" + * - `controllerMask` set to "WUPS_BUTTON_COMBO_CONTROLLER_ALL" * - * Registers a unique button combination which will trigger a callback if the combo is held for a certain amount of ms **on any connected controller** and the button combo is valid. - * - * The callback is triggered if the given button combination has been held down for at least X ms - * - * Conflict management: - * The button combination is only active if this function returns WUPS_BUTTON_COMBO_ERROR_SUCCESS and outStatus is WUPS_BUTTON_COMBO_COMBO_STATUS_VALID. - * - * If any other (valid) button combination overlaps with the button combo, the outStatus WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT and the callback will not be triggered - * even if the combination is pressed. - * - * Even if the button combination would be unique and valid (due to the change or removal of other combos), the status won't update itself. - * To resolve a WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT combo state you **always** have to the combo information via WUPSButtonComboAPI_UpdateButtonComboInfo or WUPSButtonComboAPI_UpdateButtonComboSimple. - * - * Conflict example: It's not possible to add any new valid button combo containing "L+R" (e.g. "X+L+R"), if there already is a button combination "L+R". - * Furthermore, it's also not possible to add a "L" or "R" combo if there already is a button combination "L+R". - * - * @param label Label of this button combo - * @param combo Combination which should be checked - * @param holdDurationInMs - * @param callback - * @param context - * @param outHandle The handle of the combo will be stored here. Must not be nullptr. - * @param outStatus The status of the combo will be stored here. Only if the status is WUPS_BUTTON_COMBO_COMBO_STATUS_VALID the combo is valid. Must not be nullptr. - * @return - **/ + * See: @WUPSButtonComboAPI_AddButtonComboPressEx for more information. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHold(const char *label, WUPSButtonCombo_Buttons combo, uint32_t holdDurationInMs, @@ -105,6 +164,14 @@ WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHold(const char *label, WUPSButtonCombo_ComboHandle *outHandle, WUPSButtonCombo_ComboStatus *outStatus); +/** + * Wrapper for `WUPSButtonComboAPI_AddButtonComboPressDownObserver` with + * - `observer` set to "true" + * - `controllerMask` set to "WUPS_BUTTON_COMBO_CONTROLLER_ALL" + * + * See: @WUPSButtonComboAPI_AddButtonComboPressEx for more information. + * +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHoldObserver(const char *label, WUPSButtonCombo_Buttons combo, uint32_t holdDurationInMs, @@ -113,50 +180,148 @@ WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHoldObserver(const char * WUPSButtonCombo_ComboHandle *outHandle, WUPSButtonCombo_ComboStatus *outStatus); -WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonCombo(const WUPSButtonCombo_ComboOptions *options, - WUPSButtonCombo_ComboHandle *outHandle, - WUPSButtonCombo_ComboStatus *outStatus); - /** * Removes a button combo for the given handle. +* +* @param handle handle of the button combo that should be removed. +* @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. */ WUPSButtonCombo_Error WUPSButtonComboAPI_RemoveButtonCombo(WUPSButtonCombo_ComboHandle handle); + /** -* Returns the combo status for the given handle -*/ + * Gets a button combo status for the given handle. + * + * @param handle Handle of the button combo + * @param outStatus The status of the combo will be stored here. + * @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. + */ WUPSButtonCombo_Error WUPSButtonComboAPI_GetButtonComboStatus(WUPSButtonCombo_ComboHandle handle, WUPSButtonCombo_ComboStatus *outStatus); - +/** +* Updates the meta options for the given handle +* +* @param handle Handle of the button +* @param metaOptions new meta options +* @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_UpdateButtonComboMeta(WUPSButtonCombo_ComboHandle handle, const WUPSButtonCombo_MetaOptions *metaOptions); +/** +* Updates the callback and context for the given handle +* +* @param handle Handle of the button combo +* @param callbackOptions new callback options +* @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_UpdateButtonComboCallback(WUPSButtonCombo_ComboHandle handle, const WUPSButtonCombo_CallbackOptions *callbackOptions); +/** +* Updates the controller mask for the given handle +* +* This will also re-check for conflicts and updates the combo status +* +* @param handle Handle of the button combo +* @param controllerMask new controller mask. must not be empty +* @param outStatus the new combo status after setting the mask will be written here. +* @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_UpdateControllerMask(WUPSButtonCombo_ComboHandle handle, WUPSButtonCombo_ControllerTypes controllerMask, WUPSButtonCombo_ComboStatus *outStatus); +/** +* Updates the combo for the given handle +* +* This will also re-check for conflicts and updates the combo status +* +* @param handle Handle of the button combo +* @param combo new combo. must not be empty. +* @param outStatus the new combo status after setting the mask will be written here. +* @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_UpdateButtonCombo(WUPSButtonCombo_ComboHandle handle, WUPSButtonCombo_Buttons combo, WUPSButtonCombo_ComboStatus *outStatus); +/** +* Updates hold duration for a given handle +* +* This only possible to "Hold"-button combos. +* +* @param handle Handle of the button combo +* @param holdDurationInMs the new hold duration in milliseconds +* @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_UpdateHoldDuration(WUPSButtonCombo_ComboHandle handle, uint32_t holdDurationInMs); +/** +* Returns the current metadata for the given handle +* +* @param handle Handle of the button combo +* @param outOptions struct where the result will be written to. Must not be nullptr. +* @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_GetButtonComboMeta(WUPSButtonCombo_ComboHandle handle, WUPSButtonCombo_MetaOptionsOut *outOptions); +/** +* Returns the current callback and context for the given handle +* +* @param handle Handle of the button combo +* @param outOptions struct where the result will be written to. Must not be nullptr. +* @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_GetButtonComboCallback(WUPSButtonCombo_ComboHandle handle, WUPSButtonCombo_CallbackOptions *outOptions); +/** +* Returns the information about the controller mask and combo for the given handle +* +* @param handle Handle of the button combo +* @param outOptions struct where the result will be written to. Must not be nullptr. +* @return Returns WUPS_BUTTON_COMBO_ERROR_SUCCESS on success. +*/ WUPSButtonCombo_Error WUPSButtonComboAPI_GetButtonComboInfoEx(WUPSButtonCombo_ComboHandle handle, WUPSButtonCombo_ButtonComboInfoEx *outOptions); + +/** +* Helper function to check the combo status for a given button combo option struct. +* +* This can be used to check if a certain button combination is still "free" and won't cause any conflicts. +* +* The input for this function is a "WUPSButtonCombo_ButtonComboOptions" struct ptr. Fill in the values like this: +* `controllerMask` - Mask of which controllers would be checked for the button combo. +* `combo` - The button combo that should be checked. +* +* @param options Holds information about how the button combo should be detected. +* @param outStatus On success this will store the status of provided combo options. +* @return Returns "WUPS_BUTTON_COMBO_ERROR_SUCCESS" on success +**/ WUPSButtonCombo_Error WUPSButtonComboAPI_CheckComboAvailable(const WUPSButtonCombo_ButtonComboOptions *options, WUPSButtonCombo_ComboStatus *outStatus); +/** +* Helper function to detect a pressed button combo. +* +* This function is blocking the current thread until it return, call it in an appropriate place. +* +* The input for this function is a "WUPSButtonCombo_DetectButtonComboOptions" struct ptr. Fill in the values like this: +* `controllerMask` - Mask of which controller should be checked for a button combo. Must not be empty +* `holdComboForInMs` - Defines how many ms a combo needs to be hold to be detected as a combo +* `holdAbortForInMs` - Defines how many ms the abort combo needs to be hold so the detection will be aborted. +* `abortButtonCombo` - Defines the combo that will trigger an abort. +* +* The abort button combo is checked on all controller, if they are not part of the `controllerMask` +* +* @param options Holds information about how the button combo should be detected. +* @param outButtons The detected button combo will be stored here if the functions returns WUPS_BUTTON_COMBO_ERROR_SUCCESS. +* @return Returns "WUPS_BUTTON_COMBO_ERROR_SUCCESS" on success, and "WUPS_BUTTON_COMBO_ERROR_ABORTED" if the detection was aborted. +**/ WUPSButtonCombo_Error WUPSButtonComboAPI_DetectButtonCombo_Blocking(const WUPSButtonCombo_DetectButtonComboOptions *options, WUPSButtonCombo_Buttons *outButtons); @@ -171,9 +336,85 @@ WUPSButtonCombo_Error WUPSButtonComboAPI_DetectButtonCombo_Blocking(const WUPSBu #include namespace WUPSButtonComboAPI { - std::string_view GetStatusStr(WUPSButtonCombo_Error status); - std::string_view GetControllerTypeStr(WUPSButtonCombo_ControllerTypes controller); + /** + * Wrapper for @WUPSButtonComboAPI_GetStatusStr + **/ + const char *GetStatusStr(WUPSButtonCombo_Error status); + /** + * + * This function returns a string representation of the provided WUPSButtonCombo_ControllerTypes. + * + * @param controller The controller to get the string representation for. + * @return A pointer to a string describing the provided controller. + **/ + const char *GetControllerTypeStr(WUPSButtonCombo_ControllerTypes controller); + + /** + * + * This function returns a string representation of the provided WUPSButtonCombo_ControllerTypes. + * + * @param status The controller to get the string representation for. + * @return A pointer to a string describing the provided controller. + **/ + const char *GetComboStatusStr(WUPSButtonCombo_ComboStatus status); + + /** + * Creates a button combo which triggers a callback if this combo is detected. + * + * This function takes a generic `WUPSButtonCombo_ComboOptions` which defines how the combo should be checked. + * + * Depending on the given type, the combo will either check for holding (for X ms) or pressing a button on for a given + * controller mask. The type also defines if it's an "observer" or not. Observers won't check for combo conflicts. + * + * If the given type is not an `observer` and any other (valid) button combination overlaps with new combo, then the + * `outStatus` will be set to `WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT` and the combo will be inactive. The original + * ButtonCombo which had the combo first won't be affected at all. + * In conflict state the callback will not be triggered even if the combination is pressed. If `observer` is set to + * "true", the combo won't check for conflicts. + * + * To resolve a WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT combo state you **always** have to update combo information + * via @ButtonCombo::UpdateControllerMask or @ButtonCombo::UpdateButtonCombo. The state won't update itself, + * even it the combo has no conflicts in a later point in time (e.g. due to other conflicting combos being removed in the meantime) + * + * Conflict example (only relevant if combo type is not an observer): + * It's not possible to add any new valid button combo containing "L+R" (e.g. "X+L+R"), if there already is a button + * combination "L+R". Furthermore, it's also not possible to add a "L" or "R" combo if there already is a button + * combination "L+R". + * + * @param options options of this button combo + * @param outStatus (optional) The status of the combo will be stored here. Only if the status is WUPS_BUTTON_COMBO_COMBO_STATUS_VALID the combo is valid. + * @param outError The error of this operation will be stored here. Only if the error is WUPS_BUTTON_COMBO_ERROR_SUCCESS creating the combo was successful. + * @return An optional `ButtonCombo` object if the combo registration succeeds; otherwise, an empty optional. + */ + std::optional CreateComboEx(const WUPSButtonCombo_ComboOptions &options, + WUPSButtonCombo_ComboStatus &outStatus, + WUPSButtonCombo_Error &outError) noexcept; + + /** + * Creates a button combo which triggers a callback if this combo is detected. + * + * This function creates a "PressDown"-combo. This means the callback is triggered once the combo is pressed down + * on one of the provided controllers. The provided controller mask can be a combination of any + * `WUPSButtonCombo_ControllerTypes` values. + * + * The "observer" parameter defines if this button combo should check for conflicts with other button combos. + * + * See @CreateComboEx for more information. + * + * The returned objected will automatically remove the button combo in the destructor. Make sure to keep it around + * along as the button combo should be valid! You have to use `std::move` to move it around. + * + * @param label Label of this button combo + * @param controllerMask Mask of controllers which should be checked. Must not be empty. + * @param combo Combination which should be checked. Must not be empty. + * @param callback Callback that will be called if a button combo is detected. Must not be nullptr. + * @param context Context for the callback. Can be nullptr. + * @param observer Defines if this combo should check for conflicts. Set to "true" to be an observer and ignore conflicts. + * @param outStatus The status of the combo will be stored here. Only if the status is WUPS_BUTTON_COMBO_COMBO_STATUS_VALID the combo is valid. + * @param outError The error of this operation will be stored here. Only if the error is WUPS_BUTTON_COMBO_ERROR_SUCCESS creating the combo was successful. + * @return An optional `ButtonCombo` object if the combo registration succeeds; otherwise, an empty optional. + */ std::optional CreateComboPressDownEx(std::string_view label, WUPSButtonCombo_ControllerTypes controllerMask, WUPSButtonCombo_Buttons combo, @@ -183,6 +424,15 @@ namespace WUPSButtonComboAPI { WUPSButtonCombo_ComboStatus &outStatus, WUPSButtonCombo_Error &outError) noexcept; + /** + * Wrapper for `CreateComboPressDownEx` with `observer` set to "false" and `controllerMask` set to + * "WUPS_BUTTON_COMBO_CONTROLLER_ALL" + * + * See: @CreateComboPressDownEx for more information. + * + * The returned objected will automatically remove the button combo in the destructor. Make sure to keep it around + * along as the button combo should be valid! You have to use `std::move` to move it around. + */ std::optional CreateComboPressDown(std::string_view label, WUPSButtonCombo_Buttons combo, WUPSButtonCombo_ComboCallback callback, @@ -190,6 +440,15 @@ namespace WUPSButtonComboAPI { WUPSButtonCombo_ComboStatus &outStatus, WUPSButtonCombo_Error &outError) noexcept; + /** + * Wrapper for `CreateComboPressDownEx` with `observer` set to "true" and `controllerMask` set to + * "WUPS_BUTTON_COMBO_CONTROLLER_ALL" + * + * See: @CreateComboPressDownEx for more information. + * + * The returned objected will automatically remove the button combo in the destructor. Make sure to keep it around + * along as the button combo should be valid! You have to use `std::move` to move it around. + */ std::optional CreateComboPressDownObserver(std::string_view label, WUPSButtonCombo_Buttons combo, WUPSButtonCombo_ComboCallback callback, @@ -197,6 +456,30 @@ namespace WUPSButtonComboAPI { WUPSButtonCombo_ComboStatus &outStatus, WUPSButtonCombo_Error &outError) noexcept; + /** + * Creates a button combo which triggers a callback if a given button Combination has been hold for given duration. + * + * This function creates a "Hold"-combo. This means the callback is triggered once the combo is hold for a given duration + * on one of the provided controllers. The provided controller mask can be a combination of any `WUPSButtonCombo_ControllerTypes` values. + * + * The "observer" parameter defines if this button combo should check for conflicts with other button combos. + * + * See: @CreateComboEx for more information about the details. + * + * The returned objected will automatically remove the button combo in the destructor. Make sure to keep it around + * along as the button combo should be valid! You have to use `std::move` to move it around. + * + * @param label Label of this button combo + * @param controllerMask Mask of controllers which should be checked. Must not be empty. + * @param combo Combination which should be checked. Must not be empty. + * @param holdDurationInMs Defines how long the button combination need to be hold down. Must not be 0. + * @param callback Callback that will be called if a button combo is detected. Must not be nullptr. + * @param context Context for the callback + * @param observer Defines if this combo should check for conflicts. Set to "true" to be an observer and ignore conflicts. + * @param outStatus The status of the combo will be stored here. Only if the status is WUPS_BUTTON_COMBO_COMBO_STATUS_VALID the combo is valid. Must not be nullptr. + * @param outError The error of this operation will be stored here. Only if the error is WUPS_BUTTON_COMBO_ERROR_SUCCESS creating the combo was successful. Must not be nullptr. + * @return An optional `ButtonCombo` object if the combo registration succeeds; otherwise, an empty optional. + */ std::optional CreateComboHoldEx(std::string_view label, WUPSButtonCombo_ControllerTypes controllerMask, WUPSButtonCombo_Buttons combo, @@ -207,6 +490,15 @@ namespace WUPSButtonComboAPI { WUPSButtonCombo_ComboStatus &outStatus, WUPSButtonCombo_Error &outError) noexcept; + /** + * Wrapper for `CreateComboHoldEx` with `observer` set to "false" and `controllerMask` set to + * "WUPS_BUTTON_COMBO_CONTROLLER_ALL" + * + * See: @CreateComboHoldEx for more information. + * + * The returned objected will automatically remove the button combo in the destructor. Make sure to keep it around + * along as the button combo should be valid! You have to use `std::move` to move it around. + */ std::optional CreateComboHold(std::string_view label, WUPSButtonCombo_Buttons combo, uint32_t holdDurationInMs, @@ -215,6 +507,15 @@ namespace WUPSButtonComboAPI { WUPSButtonCombo_ComboStatus &outStatus, WUPSButtonCombo_Error &outError) noexcept; + /** + * Wrapper for `CreateComboHoldEx` with `observer` set to "true" and `controllerMask` set to + * "WUPS_BUTTON_COMBO_CONTROLLER_ALL" + * + * See: @CreateComboHoldEx for more information. + * + * The returned objected will automatically remove the button combo in the destructor. Make sure to keep it around + * along as the button combo should be valid! You have to use `std::move` to move it around. + */ std::optional CreateComboHoldObserver(std::string_view label, WUPSButtonCombo_Buttons combo, uint32_t holdDurationInMs, @@ -224,6 +525,15 @@ namespace WUPSButtonComboAPI { WUPSButtonCombo_Error &outError) noexcept; + /** + * Same as @CreateComboEx, but throwing an exception on error instead of returning an optional. + */ + ButtonCombo CreateComboEx(const WUPSButtonCombo_ComboOptions &options, + WUPSButtonCombo_ComboStatus &outStatus); + + /** + * Same as @CreateComboPressDownEx, but throwing an exception on error instead of returning an optional. + */ ButtonCombo CreateComboPressDownEx(std::string_view label, WUPSButtonCombo_ControllerTypes controllerMask, WUPSButtonCombo_Buttons combo, @@ -231,19 +541,25 @@ namespace WUPSButtonComboAPI { void *context, bool observer, WUPSButtonCombo_ComboStatus &outStatus); - + /** + * Same as @CreateComboPressDown, but throwing an exception on error instead of returning an optional. + */ ButtonCombo CreateComboPressDown(std::string_view label, WUPSButtonCombo_Buttons combo, WUPSButtonCombo_ComboCallback callback, void *context, WUPSButtonCombo_ComboStatus &outStatus); - + /** + * Same as @CreateComboPressDownObserver, but throwing an exception on error instead of returning an optional. + */ ButtonCombo CreateComboPressDownObserver(std::string_view label, WUPSButtonCombo_Buttons combo, WUPSButtonCombo_ComboCallback callback, void *context, WUPSButtonCombo_ComboStatus &outStatus); - + /** + * Same as @CreateComboHoldEx, but throwing an exception on error instead of returning an optional. + */ ButtonCombo CreateComboHoldEx(std::string_view label, WUPSButtonCombo_ControllerTypes controllerMask, WUPSButtonCombo_Buttons combo, @@ -252,23 +568,35 @@ namespace WUPSButtonComboAPI { void *context, bool observer, WUPSButtonCombo_ComboStatus &outStatus); - + /** + * Same as @CreateComboHold, but throwing an exception on error instead of returning an optional. + */ ButtonCombo CreateComboHold(std::string_view label, WUPSButtonCombo_Buttons combo, uint32_t holdDurationInMs, WUPSButtonCombo_ComboCallback callback, void *context, WUPSButtonCombo_ComboStatus &outStatus); - + /** + * Same as @CreateComboHoldObserver, but throwing an exception on error instead of returning an optional. + */ ButtonCombo CreateComboHoldObserver(std::string_view label, WUPSButtonCombo_Buttons combo, uint32_t holdDurationInMs, WUPSButtonCombo_ComboCallback callback, void *context, WUPSButtonCombo_ComboStatus &outStatus); + + /** + * See @WUPSButtonComboAPI_CheckComboAvailable + **/ WUPSButtonCombo_Error CheckComboAvailable(const WUPSButtonCombo_ButtonComboOptions &options, WUPSButtonCombo_ComboStatus &outStatus); + + /** + * See @WUPSButtonComboAPI_DetectButtonCombo_Blocking + **/ WUPSButtonCombo_Error DetectButtonCombo_Blocking(const WUPSButtonCombo_DetectButtonComboOptions &options, WUPSButtonCombo_Buttons &outButtons); diff --git a/include/wups/button_combo/defines.h b/include/wups/button_combo/defines.h index e3dddb2..34900fb 100644 --- a/include/wups/button_combo/defines.h +++ b/include/wups/button_combo/defines.h @@ -43,13 +43,13 @@ typedef enum WUPSButtonCombo_Buttons { WUPS_BUTTON_COMBO_BUTTON_TV = 0x00010000, //! The reserved bit WUPS_BUTTON_COMBO_BUTTON_RESERVED_BIT = 0x80000, - //! The 1 button + //! The 1 button on the wiimote (exclusive to Wiimotes) WUPS_BUTTON_COMBO_BUTTON_1 = 0x0001, - //! The 2 button + //! The 2 button on the wiimote (exclusive to Wiimotes) WUPS_BUTTON_COMBO_BUTTON_2 = 0x0002, - //! The C button + //! The C button on the nunchuck (exclusive to Wiimotes) WUPS_BUTTON_COMBO_BUTTON_C = 0x100000, - //! The Z button + //! The Z button on the nunchuck (exclusive to Wiimotes) WUPS_BUTTON_COMBO_BUTTON_Z = 0x200000, } WUPSButtonCombo_Buttons; WUT_ENUM_BITMASK_TYPE(WUPSButtonCombo_Buttons); @@ -77,25 +77,33 @@ typedef enum WUPSButtonCombo_ControllerTypes { } WUPSButtonCombo_ControllerTypes; WUT_ENUM_BITMASK_TYPE(WUPSButtonCombo_ControllerTypes); +/** + * @enum WUPSButtonCombo_ComboType + * @brief Represents status the status of a combo + */ typedef enum WUPSButtonCombo_ComboType { WUPS_BUTTON_COMBO_COMBO_TYPE_INVALID = 0, - WUPS_BUTTON_COMBO_COMBO_TYPE_HOLD = 1, // Does check for conflicts - WUPS_BUTTON_COMBO_COMBO_TYPE_PRESS_DOWN = 2, // Does check for conflicts - WUPS_BUTTON_COMBO_COMBO_TYPE_HOLD_OBSERVER = 3, // Does not check for conflicts - WUPS_BUTTON_COMBO_COMBO_TYPE_PRESS_DOWN_OBSERVER = 4, // Does not check for conflicts + WUPS_BUTTON_COMBO_COMBO_TYPE_HOLD = 1, // Checks if a combo has been hold for X ms. Does check for conflicts + WUPS_BUTTON_COMBO_COMBO_TYPE_HOLD_OBSERVER = 2, // Checks if a combo has been hold for X ms. Does not check for conflicts + WUPS_BUTTON_COMBO_COMBO_TYPE_PRESS_DOWN = 3, // Checks if a combo has been pressed down on a controller. Does check for conflicts + WUPS_BUTTON_COMBO_COMBO_TYPE_PRESS_DOWN_OBSERVER = 4, // Checks if a combo has been pressed down on a controller. Does not check for conflicts } WUPSButtonCombo_ComboType; +/** + * @enum WUPSButtonCombo_ComboStatus + * @brief Represents status of a combo + */ typedef enum WUPSButtonCombo_ComboStatus { - WUPS_BUTTON_COMBO_COMBO_STATUS_INVALID_STATUS = 0, - WUPS_BUTTON_COMBO_COMBO_STATUS_VALID = 1, - WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT = 2, + WUPS_BUTTON_COMBO_COMBO_STATUS_INVALID_STATUS = 0, // Invalid status, this only happens on errors. + WUPS_BUTTON_COMBO_COMBO_STATUS_VALID = 1, // The Combo is valid and active + WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT = 2, // The Combo is already used by a different combo. Update to combo by updating the combo or controller mask. } WUPSButtonCombo_ComboStatus; /** * @enum WUPSButtonComboError * @brief Represents error codes returned by storage API functions. */ -typedef enum { +typedef enum WUPSButtonCombo_Error { WUPS_BUTTON_COMBO_ERROR_SUCCESS = 0, /**< Success. */ WUPS_BUTTON_COMBO_ERROR_INVALID_ARGS = -0x01, /**< Invalid arguments passed to the function. */ WUPS_BUTTON_COMBO_ERROR_MALLOC_FAILED = -0x02, /**< Memory allocation failed. */ @@ -106,6 +114,10 @@ typedef enum { WUPS_BUTTON_COMBO_ERROR_UNKNOWN_ERROR = -0x100 /**< Unknown error. */ } WUPSButtonCombo_Error; +/** + * @enum WUPSButtonCombo_ComboHandle + * @brief Represents the handle for a button combo + */ typedef struct WUPSButtonCombo_ComboHandle { void *handle; #ifdef __cplusplus @@ -122,10 +134,28 @@ typedef struct WUPSButtonCombo_ComboHandle { #endif } WUPSButtonCombo_ComboHandle; +/** + * @typedef WUPSButtonCombo_ComboCallback + * @brief Callback function type for handling button combo events. + * + * This callback is invoked when a button combo is triggered. + * + * @param triggeredBy + * The type of controller that triggered the button combination. + * See @ref WUPSButtonCombo_ControllerTypes for possible values. + * + * @param handle + * A handle representing the button combo that was triggered. + * This can be used to identify the specific combo that invoked the callback. + * + * @param context + * A user-defined context pointer passed during the setup of the callback. + * This can be used to provide additional information or state relevant to the callback. + */ typedef void (*WUPSButtonCombo_ComboCallback)(WUPSButtonCombo_ControllerTypes triggeredBy, WUPSButtonCombo_ComboHandle handle, void *context); typedef struct WUPSButtonCombo_MetaOptions { - const char *label; + const char *label; // Label that identifies a button combo, currently only used for debugging } WUPSButtonCombo_MetaOptions; typedef struct WUPSButtonCombo_MetaOptionsOut { @@ -134,25 +164,25 @@ typedef struct WUPSButtonCombo_MetaOptionsOut { } WUPSButtonCombo_MetaOptionsOut; typedef struct WUPSButtonCombo_CallbackOptions { - WUPSButtonCombo_ComboCallback callback; - void *context; + WUPSButtonCombo_ComboCallback callback; // Must not be NULL. Defines which callback should be called once a combo is detected + void *context; // Passed into the callback when it's triggered. Can be NULL } WUPSButtonCombo_CallbackOptions; typedef struct WUPSButtonCombo_ButtonComboOptions { - WUPSButtonCombo_ControllerTypes controllerMask; - WUPSButtonCombo_Buttons combo; + WUPSButtonCombo_ControllerTypes controllerMask; // Defines a mask for which controller should be checked. Must not be empty. + WUPSButtonCombo_Buttons combo; // Defines which combo should be detected. Note: Not all button are available on all controllers. Must not be empty. } WUPSButtonCombo_ButtonComboOptions; typedef struct WUPSButtonCombo_ButtonComboInfoEx { - WUPSButtonCombo_ComboType type; - WUPSButtonCombo_ButtonComboOptions basicCombo; - uint32_t optionalHoldForXMs; + WUPSButtonCombo_ComboType type; // Defines the type of the combo AND if it will check for conflicts. + WUPSButtonCombo_ButtonComboOptions basicCombo; // Defines which combo should be checked on which controller + uint32_t optionalHoldForXMs; // Only mandatory if the type is set to COMBO_TYPE_HOLD or COMBO_TYPE_HOLD_OBSERVER } WUPSButtonCombo_ButtonComboInfoEx; typedef struct WUPSButtonCombo_ComboOptions { - WUPSButtonCombo_MetaOptions metaOptions; - WUPSButtonCombo_CallbackOptions callbackOptions; - WUPSButtonCombo_ButtonComboInfoEx buttonComboOptions; + WUPSButtonCombo_MetaOptions metaOptions; // Defines the meta information about the combo e.g. the label + WUPSButtonCombo_CallbackOptions callbackOptions; // Defines the callback that should be called once the combo is detected + WUPSButtonCombo_ButtonComboInfoEx buttonComboOptions; // Defines how and when which combo should be detected } WUPSButtonCombo_ComboOptions; typedef struct WUPSButtonCombo_DetectButtonComboOptions { diff --git a/libraries/libwups/button_combo.cpp b/libraries/libwups/button_combo.cpp index 3cebe32..898cc06 100644 --- a/libraries/libwups/button_combo.cpp +++ b/libraries/libwups/button_combo.cpp @@ -86,83 +86,25 @@ const char *WUPSButtonComboAPI_GetControllerTypeStr(const WUPSButtonCombo_Contro return "WUPS_BUTTON_COMBO_CONTROLLER_WPAD_5"; case WUPS_BUTTON_COMBO_CONTROLLER_WPAD_6: return "WUPS_BUTTON_COMBO_CONTROLLER_WPAD_6"; - default:; + case WUPS_BUTTON_COMBO_CONTROLLER_NONE: + case WUPS_BUTTON_COMBO_CONTROLLER_VPAD: + case WUPS_BUTTON_COMBO_CONTROLLER_WPAD: + case WUPS_BUTTON_COMBO_CONTROLLER_ALL: + break; } return ""; } -static WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboPressEx(const char *label, - const WUPSButtonCombo_Buttons combo, - const WUPSButtonCombo_ComboCallback callback, - void *context, - const bool observer, - WUPSButtonCombo_ComboHandle *outHandle, - WUPSButtonCombo_ComboStatus *outStatus) { - WUPSButtonCombo_ComboOptions options = {}; - options.metaOptions.label = label; - options.callbackOptions = {.callback = callback, .context = context}; - options.buttonComboOptions.type = observer ? WUPS_BUTTON_COMBO_COMBO_TYPE_PRESS_DOWN_OBSERVER : WUPS_BUTTON_COMBO_COMBO_TYPE_PRESS_DOWN; - options.buttonComboOptions.basicCombo.combo = combo; - options.buttonComboOptions.basicCombo.controllerMask = WUPS_BUTTON_COMBO_CONTROLLER_ALL; - - return WUPSButtonComboAPI_AddButtonCombo(&options, outHandle, outStatus); -} - -WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboPressDown(const char *label, - const WUPSButtonCombo_Buttons combo, - const WUPSButtonCombo_ComboCallback callback, - void *context, - WUPSButtonCombo_ComboHandle *outHandle, - WUPSButtonCombo_ComboStatus *outStatus) { - return WUPSButtonComboAPI_AddButtonComboPressEx(label, combo, callback, context, false, outHandle, outStatus); -} - -WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboPressDownObserver(const char *label, - const WUPSButtonCombo_Buttons combo, - const WUPSButtonCombo_ComboCallback callback, - void *context, - WUPSButtonCombo_ComboHandle *outHandle, - WUPSButtonCombo_ComboStatus *outStatus) { - return WUPSButtonComboAPI_AddButtonComboPressEx(label, combo, callback, context, true, outHandle, outStatus); -} - -static WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHoldEx(const char *label, - const WUPSButtonCombo_Buttons combo, - const uint32_t holdDurationInMs, - const WUPSButtonCombo_ComboCallback callback, - void *context, - const bool observer, - WUPSButtonCombo_ComboHandle *outHandle, - WUPSButtonCombo_ComboStatus *outStatus) { - WUPSButtonCombo_ComboOptions options = {}; - options.metaOptions.label = label; - options.callbackOptions = {.callback = callback, .context = context}; - options.buttonComboOptions.type = observer ? WUPS_BUTTON_COMBO_COMBO_TYPE_HOLD_OBSERVER : WUPS_BUTTON_COMBO_COMBO_TYPE_HOLD; - options.buttonComboOptions.basicCombo.combo = combo; - options.buttonComboOptions.basicCombo.controllerMask = WUPS_BUTTON_COMBO_CONTROLLER_ALL; - options.buttonComboOptions.optionalHoldForXMs = holdDurationInMs; - - return WUPSButtonComboAPI_AddButtonCombo(&options, outHandle, outStatus); -} - -WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHold(const char *label, - const WUPSButtonCombo_Buttons combo, - const uint32_t holdDurationInMs, - const WUPSButtonCombo_ComboCallback callback, - void *context, - WUPSButtonCombo_ComboHandle *outHandle, - WUPSButtonCombo_ComboStatus *outStatus) { - return WUPSButtonComboAPI_AddButtonComboHoldEx(label, combo, holdDurationInMs, callback, context, false, outHandle, outStatus); -} - -WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHoldObserver(const char *label, - const WUPSButtonCombo_Buttons combo, - const uint32_t holdDurationInMs, - const WUPSButtonCombo_ComboCallback callback, - void *context, - WUPSButtonCombo_ComboHandle *outHandle, - WUPSButtonCombo_ComboStatus *outStatus) { - return WUPSButtonComboAPI_AddButtonComboHoldEx(label, combo, holdDurationInMs, callback, context, true, outHandle, outStatus); +const char *WUPSButtonComboAPI_GetComboStatusStr(const WUPSButtonCombo_ComboStatus status) { + switch (status) { + case WUPS_BUTTON_COMBO_COMBO_STATUS_INVALID_STATUS: + return "WUPS_BUTTON_COMBO_COMBO_STATUS_INVALID_STATUS"; + case WUPS_BUTTON_COMBO_COMBO_STATUS_VALID: + return "WUPS_BUTTON_COMBO_COMBO_STATUS_VALID"; + case WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT: + return "WUPS_BUTTON_COMBO_COMBO_STATUS_CONFLICT"; + } + return "WUPS_BUTTON_COMBO_COMBO_STATUS_INVALID_STATUS"; } WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonCombo(const WUPSButtonCombo_ComboOptions *options, @@ -181,6 +123,83 @@ WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonCombo(const WUPSButtonCombo_Co } +WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboPressEx(const char *label, + const WUPSButtonCombo_ControllerTypes controllerMask, + const WUPSButtonCombo_Buttons combo, + const WUPSButtonCombo_ComboCallback callback, + void *context, + const bool observer, + WUPSButtonCombo_ComboHandle *outHandle, + WUPSButtonCombo_ComboStatus *outStatus) { + WUPSButtonCombo_ComboOptions options = {}; + options.metaOptions.label = label; + options.callbackOptions = {.callback = callback, .context = context}; + options.buttonComboOptions.type = observer ? WUPS_BUTTON_COMBO_COMBO_TYPE_PRESS_DOWN_OBSERVER : WUPS_BUTTON_COMBO_COMBO_TYPE_PRESS_DOWN; + options.buttonComboOptions.basicCombo.combo = combo; + options.buttonComboOptions.basicCombo.controllerMask = controllerMask; + options.buttonComboOptions.optionalHoldForXMs = 0; + + return WUPSButtonComboAPI_AddButtonCombo(&options, outHandle, outStatus); +} + +WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboPressDown(const char *label, + const WUPSButtonCombo_Buttons combo, + const WUPSButtonCombo_ComboCallback callback, + void *context, + WUPSButtonCombo_ComboHandle *outHandle, + WUPSButtonCombo_ComboStatus *outStatus) { + return WUPSButtonComboAPI_AddButtonComboPressEx(label, WUPS_BUTTON_COMBO_CONTROLLER_ALL, combo, callback, context, false, outHandle, outStatus); +} + +WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboPressDownObserver(const char *label, + const WUPSButtonCombo_Buttons combo, + const WUPSButtonCombo_ComboCallback callback, + void *context, + WUPSButtonCombo_ComboHandle *outHandle, + WUPSButtonCombo_ComboStatus *outStatus) { + return WUPSButtonComboAPI_AddButtonComboPressEx(label, WUPS_BUTTON_COMBO_CONTROLLER_ALL, combo, callback, context, true, outHandle, outStatus); +} + +WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHoldEx(const char *label, + const WUPSButtonCombo_ControllerTypes controllerMask, + const WUPSButtonCombo_Buttons combo, + const uint32_t holdDurationInMs, + const WUPSButtonCombo_ComboCallback callback, + void *context, + const bool observer, + WUPSButtonCombo_ComboHandle *outHandle, + WUPSButtonCombo_ComboStatus *outStatus) { + WUPSButtonCombo_ComboOptions options = {}; + options.metaOptions.label = label; + options.callbackOptions = {.callback = callback, .context = context}; + options.buttonComboOptions.type = observer ? WUPS_BUTTON_COMBO_COMBO_TYPE_HOLD_OBSERVER : WUPS_BUTTON_COMBO_COMBO_TYPE_HOLD; + options.buttonComboOptions.basicCombo.combo = combo; + options.buttonComboOptions.basicCombo.controllerMask = controllerMask; + options.buttonComboOptions.optionalHoldForXMs = holdDurationInMs; + + return WUPSButtonComboAPI_AddButtonCombo(&options, outHandle, outStatus); +} + +WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHold(const char *label, + const WUPSButtonCombo_Buttons combo, + const uint32_t holdDurationInMs, + const WUPSButtonCombo_ComboCallback callback, + void *context, + WUPSButtonCombo_ComboHandle *outHandle, + WUPSButtonCombo_ComboStatus *outStatus) { + return WUPSButtonComboAPI_AddButtonComboHoldEx(label, WUPS_BUTTON_COMBO_CONTROLLER_ALL, combo, holdDurationInMs, callback, context, false, outHandle, outStatus); +} + +WUPSButtonCombo_Error WUPSButtonComboAPI_AddButtonComboHoldObserver(const char *label, + const WUPSButtonCombo_Buttons combo, + const uint32_t holdDurationInMs, + const WUPSButtonCombo_ComboCallback callback, + void *context, + WUPSButtonCombo_ComboHandle *outHandle, + WUPSButtonCombo_ComboStatus *outStatus) { + return WUPSButtonComboAPI_AddButtonComboHoldEx(label, WUPS_BUTTON_COMBO_CONTROLLER_ALL, combo, holdDurationInMs, callback, context, true, outHandle, outStatus); +} + WUPSButtonCombo_Error WUPSButtonComboAPI_RemoveButtonCombo(const WUPSButtonCombo_ComboHandle handle) { if (__internal_functions.remove_button_combo_function_ptr == nullptr) { return WUPS_BUTTON_COMBO_ERROR_INTERNAL_NOT_INITIALIZED; diff --git a/libraries/libwups/button_comboCPP.cpp b/libraries/libwups/button_comboCPP.cpp index 543e8e0..57dc7d5 100644 --- a/libraries/libwups/button_comboCPP.cpp +++ b/libraries/libwups/button_comboCPP.cpp @@ -3,14 +3,24 @@ #include namespace WUPSButtonComboAPI { - std::string_view GetStatusStr(const WUPSButtonCombo_Error status) { + const char *GetStatusStr(const WUPSButtonCombo_Error status) { return WUPSButtonComboAPI_GetStatusStr(status); } - std::string_view GetControllerTypeStr(const WUPSButtonCombo_ControllerTypes controller) { + const char *GetControllerTypeStr(const WUPSButtonCombo_ControllerTypes controller) { return WUPSButtonComboAPI_GetControllerTypeStr(controller); } + const char *GetComboStatusStr(WUPSButtonCombo_ComboStatus status) { + return WUPSButtonComboAPI_GetComboStatusStr(status); + } + + std::optional CreateComboEx(const WUPSButtonCombo_ComboOptions &options, + WUPSButtonCombo_ComboStatus &outStatus, + WUPSButtonCombo_Error &outError) noexcept { + return ButtonCombo::Create(options, outStatus, outError); + } + std::optional CreateComboPressDownEx(const std::string_view label, const WUPSButtonCombo_ControllerTypes controllerMask, const WUPSButtonCombo_Buttons combo, @@ -88,6 +98,11 @@ namespace WUPSButtonComboAPI { return CreateComboHoldEx(label, WUPS_BUTTON_COMBO_CONTROLLER_ALL, combo, holdDurationInMs, callback, context, true, outStatus, outError); } + ButtonCombo CreateComboEx(const WUPSButtonCombo_ComboOptions &options, + WUPSButtonCombo_ComboStatus &outStatus) { + return ButtonCombo::Create(options, outStatus); + } + ButtonCombo CreateComboPressDownEx(const std::string_view label, const WUPSButtonCombo_ControllerTypes controllerMask, const WUPSButtonCombo_Buttons combo, diff --git a/plugins/example_plugin_cpp/src/main.cpp b/plugins/example_plugin_cpp/src/main.cpp index 71b59c9..c9ec083 100644 --- a/plugins/example_plugin_cpp/src/main.cpp +++ b/plugins/example_plugin_cpp/src/main.cpp @@ -250,7 +250,7 @@ INITIALIZE_PLUGIN() { "Example Plugin: Press Down test", DEFAULT_PRESS_DOWN_BUTTON_COMBO, // L + R [](const WUPSButtonCombo_ControllerTypes triggeredBy, WUPSButtonCombo_ComboHandle, void *) { - DEBUG_FUNCTION_LINE_INFO("Button combo has been pressed down by controller %s", WUPSButtonComboAPI::GetControllerTypeStr(triggeredBy).data()); + DEBUG_FUNCTION_LINE_INFO("Button combo has been pressed down by controller %s", WUPSButtonComboAPI::GetControllerTypeStr(triggeredBy)); }, nullptr, comboStatus); @@ -283,7 +283,7 @@ INITIALIZE_PLUGIN() { "Example Plugin: Press Down observer test", DEFAULT_PRESS_DOWN_BUTTON_COMBO, // L + R Even though this is same combo as in buttonComboPressDown an observer will ignore conflicts. [](const WUPSButtonCombo_ControllerTypes triggeredBy, WUPSButtonCombo_ComboHandle, void *) { - DEBUG_FUNCTION_LINE_INFO("[OBSERVER] Button combo has been pressed down by controller %s", WUPSButtonComboAPI::GetControllerTypeStr(triggeredBy).data()); + DEBUG_FUNCTION_LINE_INFO("[OBSERVER] Button combo has been pressed down by controller %s", WUPSButtonComboAPI::GetControllerTypeStr(triggeredBy)); }, nullptr, comboStatus); // comboStatus will always be WUPS_BUTTON_COMBO_COMBO_STATUS_VALID for observers. @@ -302,7 +302,7 @@ INITIALIZE_PLUGIN() { DEFAULT_PRESS_HOLD_COMBO, // L+R+DPAD+DOWN. This combo includes the combo "L+R" of the buttonComboPressDown, so this will lead to a conflict. 500, // We need to hold that combo for 500ms [](const WUPSButtonCombo_ControllerTypes triggeredBy, WUPSButtonCombo_ComboHandle, void *) { - DEBUG_FUNCTION_LINE_INFO("Button combo has been hold for 500ms by controller %s", WUPSButtonComboAPI::GetControllerTypeStr(triggeredBy).data()); + DEBUG_FUNCTION_LINE_INFO("Button combo has been hold for 500ms by controller %s", WUPSButtonComboAPI::GetControllerTypeStr(triggeredBy)); }, nullptr, comboStatus); // comboStatus will always be WUPS_BUTTON_COMBO_COMBO_STATUS_VALID for observers. @@ -354,7 +354,7 @@ INITIALIZE_PLUGIN() { WUPS_BUTTON_COMBO_CONTROLLER_WPAD_0, // Define which controllers should be checked. Could be something (WUPS_BUTTON_COMBO_CONTROLLER_WPAD_0 | WUPS_BUTTON_COMBO_CONTROLLER_VPAD). DEFAULT_PRESS_DOWN_BUTTON_COMBO, // L + R Even though this is same combo as in buttonComboPressDown an observer will ignore conflicts. [](const WUPSButtonCombo_ControllerTypes triggeredBy, WUPSButtonCombo_ComboHandle, void *) { - DEBUG_FUNCTION_LINE_INFO("[OBSERVER WPAD_0] Button combo has been pressed down by controller %s", WUPSButtonComboAPI::GetControllerTypeStr(triggeredBy).data()); + DEBUG_FUNCTION_LINE_INFO("[OBSERVER WPAD_0] Button combo has been pressed down by controller %s", WUPSButtonComboAPI::GetControllerTypeStr(triggeredBy)); }, nullptr, true, // we want an observer @@ -377,7 +377,7 @@ INITIALIZE_PLUGIN() { "Example Plugin: Press Down test 2", WUPS_BUTTON_COMBO_BUTTON_X | WUPS_BUTTON_COMBO_BUTTON_Y, [](const WUPSButtonCombo_ControllerTypes triggeredBy, WUPSButtonCombo_ComboHandle, void *) { - DEBUG_FUNCTION_LINE_INFO("[OBSERVER] Other button combo has been pressed down by controller %s", WUPSButtonComboAPI::GetControllerTypeStr(triggeredBy).data()); + DEBUG_FUNCTION_LINE_INFO("[OBSERVER] Other button combo has been pressed down by controller %s", WUPSButtonComboAPI::GetControllerTypeStr(triggeredBy)); }, nullptr, comboStatus,