The-Homebrew-Cloud/WiiUPluginSystem
2
0
Fork 0
mirror of https://github.com/wiiu-env/WiiUPluginSystem.git synced 2025-02-02 19:02:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation of button combo API

Browse Source
This commit is contained in:
Maschell 2025-01-24 17:51:06 +01:00
parent 27926a8c1e
commit ac02414904
6 changed files with 574 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
include/wups/button_combo/WUPSButtonCombo.h
View File

@ -13,6 +13,7 @@ namespace WUPSButtonComboAPI {
struct MetaOptions {
std::string label;
};
static std::optional<ButtonCombo> Create(const WUPSButtonCombo_ComboOptions &options,
WUPSButtonCombo_ComboStatus &outStatus,
WUPSButtonCombo_Error &outError) noexcept;

484
include/wups/button_combo/api.h
View File

@ -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 <string_view>
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<ButtonCombo> 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<ButtonCombo> 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<ButtonCombo> 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<ButtonCombo> 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<ButtonCombo> 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<ButtonCombo> 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<ButtonCombo> 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);

76
include/wups/button_combo/defines.h
View File

@ -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 {

165
libraries/libwups/button_combo.cpp
View File

@ -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 "<UNKNOWN OR MORE THAN ONE CONTROLLER>";
}
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;

19
libraries/libwups/button_comboCPP.cpp
View File

@ -3,14 +3,24 @@
#include <wups/button_combo/defines.h>
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<ButtonCombo> CreateComboEx(const WUPSButtonCombo_ComboOptions &options,
WUPSButtonCombo_ComboStatus &outStatus,
WUPSButtonCombo_Error &outError) noexcept {
return ButtonCombo::Create(options, outStatus, outError);
}
std::optional<ButtonCombo> 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,

10
plugins/example_plugin_cpp/src/main.cpp
View File

@ -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,