From aa093106b3acbf4e9454cec75103a5c9d5c2a570 Mon Sep 17 00:00:00 2001 From: Maschell Date: Thu, 22 Jan 2026 13:15:21 +0100 Subject: [PATCH] Update documentation --- README.md | 160 ++++++++-- include/notifications/notifications.h | 422 +++++++++++++------------- 2 files changed, 357 insertions(+), 225 deletions(-) diff --git a/README.md b/README.md index 8607467..1eee530 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,154 @@ [![Publish Docker Image](https://github.com/wiiu-env/libnotifications/actions/workflows/push_image.yml/badge.svg)](https://github.com/wiiu-env/libnotifications/actions/workflows/push_image.yml) # libnotifications -Requires the [NotificationModule](https://github.com/wiiu-env/NotificationModule) to be running via [WUMSLoader](https://github.com/wiiu-env/WUMSLoader). -Requires [wut](https://github.com/devkitPro/wut) for building. -Install via `make install`. -## Usage -Make also sure to define +A Wii U homebrew library for displaying system-wide notifications. + +**Prerequisites:** +* **Runtime:** Requires the [NotificationModule](https://github.com/wiiu-env/NotificationModule) to be running via [WUMSLoader](https://github.com/wiiu-env/WUMSLoader). +* **Build:** Requires [wut](https://github.com/devkitPro/wut) for building. + +## Installation + +You can install the library via the Makefile: +``` +make install +``` +## Build Setup + +To use this library in your project, ensure your `Makefile` or build system is configured correctly. + +1. **Define WUMS_ROOT**: ``` WUMS_ROOT := $(DEVKITPRO)/wums ``` -and add `-lnotifications` to `LIBS` and `$(WUMS_ROOT)` to `LIBDIRS`. - -Include `` to get access to the NotificationModule functions, after calling `NotificationModule_InitLibrary()`. - -## Use this lib in Dockerfiles. -A prebuilt version of this lib can found on dockerhub. To use it for your projects, add this to your Dockerfile. +2. **Update Library Flags**: +Add `-lnotifications` to your `LIBS` and include the WUMS path in `LIBDIRS`. ``` -[...] +LIBS := ... -lnotifications +LIBDIRS := ... $(WUMS_ROOT) +``` +## Usage Examples + +Include the main header to access the API: +``` +#include +``` +### 1. Initialization +You **must** initialize the library before calling any notification functions. It is good practice to check the specific error code to diagnose issues (e.g., missing module). +``` +void setup() { + NotificationModuleStatus status = NotificationModule_InitLibrary(); + + if (status != NOTIFICATION_MODULE_RESULT_SUCCESS) { + if (status == NOTIFICATION_MODULE_RESULT_MODULE_NOT_FOUND) { + // Critical Error: WUMSLoader or NotificationModule is not running. + } else if (status == NOTIFICATION_MODULE_RESULT_UNSUPPORTED_VERSION) { + // The installed NotificationModule version is incompatible. + } + // Do not proceed with using the library. + return; + } +} + +void cleanup() { + NotificationModule_DeInitLibrary(); +} +``` +### 2. Simple Notifications +Even simple notifications can fail if the overlay isn't ready or memory is low. + +**Info Notification (Fades out automatically):** +``` +if (const auto status = NotificationModule_AddInfoNotification("File saved successfully!") != NOTIFICATION_MODULE_RESULT_SUCCESS) { + // Failed to display notification + OSReport("Failed to display notification: Error %s\n", NotificationModule_GetStatusStr(status)); +} +``` + + +**Error Notification (Shakes and fades out):** +``` +if (const auto status = NotificationModule_AddErrorNotification("Connection failed!") != NOTIFICATION_MODULE_RESULT_SUCCESS) { + // Failed to display notification + OSReport("Failed to display notification: Error %s\n", NotificationModule_GetStatusStr(status)); +} +``` +### 3. Dynamic Notifications +For dynamic notifications, it is critical to ensure the notification was successfully created before attempting to update or finish it. +``` +NotificationModuleHandle handle; +NotificationModuleStatus status = NotificationModule_AddDynamicNotification("Downloading... 0%", &handle); + +if (status == NOTIFICATION_MODULE_RESULT_SUCCESS) { + // 1. Update the text during your process + NotificationModule_UpdateDynamicNotificationText(handle, "Downloading... 50%"); + [...] + // 2. Finish it when done (fades out after 2 seconds) + NotificationModule_FinishDynamicNotification(handle, 2.0f); +} else { + // Handle failure (e.g., NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED) + // Note: 'handle' is undefined here and should not be used. +} +``` + +This example shows how to trigger a callback function when a dynamic notification finishes. +``` +// 1. Define the callback +void OnFinished(NotificationModuleHandle handle, void* context) { + // called when the notification finished fading out. +} + +// 2. Usage +void ShowProgress() { + NotificationModuleHandle handle; + int myData = 42; // Example context data + + NotificationModuleStatus status = NotificationModule_AddDynamicNotificationWithCallback( + "Loading... 0%", + &handle, + OnFinished, + (void *) &myData + ); + + if (status == NOTIFICATION_MODULE_RESULT_SUCCESS) { + // Update status... + NotificationModule_UpdateDynamicNotificationText(handle, "Loading... 100%"); + + // Finish (triggers callback after fade out) + NotificationModule_FinishDynamicNotification(handle, 1.5f); + } +} +``` +### 4. Customizing Defaults +Setting default values returns a status code which can indicate invalid arguments (e.g., passing a float when an int is expected). +``` +// Define a custom color +NMColor green = {0, 128, 0, 255}; + +NotificationModuleStatus status = NotificationModule_SetDefaultValue( + NOTIFICATION_MODULE_NOTIFICATION_TYPE_INFO, + NOTIFICATION_MODULE_DEFAULT_OPTION_BACKGROUND_COLOR, + green +); + +if (status != NOTIFICATION_MODULE_RESULT_SUCCESS) { + // This might happen if the type or option is invalid. +} +``` +## Docker Integration + +A prebuilt version of this lib can found on dockerhub. To use it for your projects, add this to your `Dockerfile`. +``` +# ... previous stages ... COPY --from=ghcr.io/wiiu-env/libnotifications:[tag] /artifacts $DEVKITPRO -[...] +# ... build stages ... ``` -Replace [tag] with a tag you want to use, a list of tags can be found [here](https://github.com/wiiu-env/libnotifications/pkgs/container/libnotifications/versions). -It's highly recommended to pin the version to the **latest date** instead of using `latest`. +> **Note:** It is highly recommended to pin the version to a specific date tag (e.g., `:20230101`) rather than using `:latest` to ensure build reproducibility. Available tags can be found [here](https://github.com/wiiu-env/libnotifications/pkgs/container/libnotifications/versions). -## Format the code via docker -`docker run --rm -v ${PWD}:/src ghcr.io/wiiu-env/clang-format:13.0.0-2 -r ./source ./include -i` +## Development + +**Format Code:** +``` +docker run --rm -v ${PWD}:/src ghcr.io/wiiu-env/clang-format:13.0.0-2 -r ./source ./include -i +``` \ No newline at end of file diff --git a/include/notifications/notifications.h b/include/notifications/notifications.h index f08f9e5..db6e057 100644 --- a/include/notifications/notifications.h +++ b/include/notifications/notifications.h @@ -9,39 +9,48 @@ extern "C" { #endif /** - * Returns a NotificationModuleStatus as a string - * @param status - * @return String representation of a given status + * Returns a NotificationModuleStatus as a string. + * + * @param[in] status The status code to convert. + * @return String representation of a given status. **/ const char *NotificationModule_GetStatusStr(NotificationModuleStatus status); /** - * This function has to be called before any other function of this lib (except NotificationModule_GetVersion) can be used. + * Initializes the library and connects to the NotificationModule. * - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The library has been initialized successfully. Other functions can now be used.
- * NOTIFICATION_MODULE_RESULT_MODULE_NOT_FOUND: The module could not be found. Make sure the module is loaded.
- * NOTIFICATION_MODULE_RESULT_MODULE_MISSING_EXPORT: The module is missing an expected export.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_API_VERSION: The version of the loaded module is not compatible with this version of the lib. + * This function has to be called before any other function of this lib (except NotificationModule_GetVersion) can be used. + * It attempts to acquire the `homebrew_notifications` module via OSDynLoad. + * + * @return The status of the initialization. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The library has been initialized successfully. Other functions can now be used. + * @retval NOTIFICATION_MODULE_RESULT_MODULE_NOT_FOUND The `homebrew_notifications` module could not be found. Ensure WUMSLoader is running and the module is installed. + * @retval NOTIFICATION_MODULE_RESULT_MODULE_MISSING_EXPORT The module is loaded but missing an expected export. + * @retval NOTIFICATION_MODULE_RESULT_UNSUPPORTED_VERSION The version of the loaded module is not compatible with this version of the lib. **/ NotificationModuleStatus NotificationModule_InitLibrary(); /** - * Deinitializes the NotificationModule lib - * @return NOTIFICATION_MODULE_RESULT_SUCCESS or NOTIFICATION_MODULE_RESULT_UNKNOWN_ERROR + * Deinitializes the NotificationModule lib and releases resources. + * + * @return The status of the deinitialization. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The library was deinitialized successfully. */ NotificationModuleStatus NotificationModule_DeInitLibrary(); /** * Retrieves the API Version of the loaded NotificationModule.
*
- * Requires NotificationModule API version 1 or higher - * @param outVersion pointer to the variable where the version will be stored. + * Requires NotificationModule API version 1 or higher. * - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The API version has been store in the version ptr.
- * NOTIFICATION_MODULE_RESULT_MODULE_NOT_FOUND: The module could not be found. Make sure the module is loaded.
- * NOTIFICATION_MODULE_RESULT_MODULE_MISSING_EXPORT: The module is missing an expected export.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: Invalid version pointer.
- * NOTIFICATION_MODULE_RESULT_UNKNOWN_ERROR: Retrieving the module version failed. + * @param[out] outVersion pointer to the variable where the version will be stored. + * + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The API version has been stored in the version ptr. + * @retval NOTIFICATION_MODULE_RESULT_MODULE_NOT_FOUND The module could not be found. Make sure the module is loaded. + * @retval NOTIFICATION_MODULE_RESULT_MODULE_MISSING_EXPORT The module is missing an expected export. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT Invalid version pointer. + * @retval NOTIFICATION_MODULE_RESULT_UNKNOWN_ERROR Retrieving the module version failed. **/ NotificationModuleStatus NotificationModule_GetVersion(NotificationModuleAPIVersion *outVersion); @@ -49,13 +58,14 @@ NotificationModuleStatus NotificationModule_GetVersion(NotificationModuleAPIVers * Checks if the Overlay for Notification is ready.
* Notifications can only be added if the overlay is ready.
*
- * Requires NotificationModule API version 1 or higher
+ * Requires NotificationModule API version 1 or higher.
*
- * @param outIsReady pointer to the variable where the result will be stored. - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The result has been stored in the outIsReady pointer.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: Invalid version pointer.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
+ * @param[out] outIsReady pointer to the variable where the result will be stored. + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The result has been stored in the outIsReady pointer. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT Invalid version pointer. + * @retval NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED The library is not initialized. + * @retval NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND The loaded module version doesn't not support this function. */ NotificationModuleStatus NotificationModule_IsOverlayReady(bool *outIsReady); @@ -63,19 +73,27 @@ NotificationModuleStatus NotificationModule_IsOverlayReady(bool *outIsReady); * Can be used to override the default settings for a certain Notification Type.
* See the NotificationModuleNotificationType and NotificationModuleNotificationOption enums for more information.
*
- * These default values will be use when calling
+ * These default values will be use when calling:
* - NotificationModule_AddInfoNotification/NotificationModule_AddInfoNotificationWithCallback (type = NOTIFICATION_MODULE_NOTIFICATION_TYPE_INFO)
* - NotificationModule_AddErrorNotification/NotificationModule_AddErrorNotificationWithCallback (type = NOTIFICATION_MODULE_NOTIFICATION_TYPE_ERROR)
* - NotificationModule_AddDynamicNotification/NotificationModule_AddDynamicNotificationWithCallback (type = NOTIFICATION_MODULE_NOTIFICATION_TYPE_DYNAMIC)
- *
+ *
* The "WithCallback" function will NOT take the default callback + context.
* - * @param type Type of Notification for which the default value will be set. - * @param optionType Defines which option will be set - * @param ... Expected to be a single value. Depends on the option type. See NotificationModuleNotificationOption enum for more information. - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: The given notification or option type was invalid
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized
+ * @param[in] type Type of Notification for which the default value will be set. + * @param[in] optionType Defines which option will be set. + * @param[in] ... Expected to be a single value matching the `optionType`: + * - **BACKGROUND_COLOR**: Expects `NMColor`. + * - **TEXT_COLOR**: Expects `NMColor`. + * - **DURATION_BEFORE_FADE_OUT**: Expects `double`. + * - **FINISH_FUNCTION**: Expects `NotificationModuleNotificationFinishedCallback`. + * - **FINISH_FUNCTION_CONTEXT**: Expects `void*`. + * - **KEEP_UNTIL_SHOWN**: Expects `bool`. + * + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The default value has been set. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT The given notification or option type was invalid. + * @retval NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED The library is not initialized. */ NotificationModuleStatus NotificationModule_SetDefaultValue(NotificationModuleNotificationType type, NotificationModuleNotificationOption optionType, @@ -86,21 +104,21 @@ NotificationModuleStatus NotificationModule_SetDefaultValue(NotificationModuleNo * Notification will appear in the top left corner. It's possible to display multiple notifications at the same time.
* The newest notification will always be at the top, the oldest at the bottom. Notifications will fade out to the left side.
*
- * Requires NotificationModule API version 1 or higher
+ * Requires NotificationModule API version 1 or higher.
*
- * @param text Content of the notification. - * @param durationBeforeFadeOutInSeconds Time in seconds before fading out - * @param textColor Text color of the Notification - * @param backgroundColor Background color of the Notification - * @param callback Function that will be called then the Notification fades out. - * @param callbackContext Context that will be passed to the callback. - * @param keepUntilShown The Notification will be stored in a queue until can be shown - even accross application starts - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.
- * NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * @param[in] text Content of the notification. + * @param[in] durationBeforeFadeOutInSeconds Time in seconds before fading out. + * @param[in] textColor Text color (RGBA) of the Notification. + * @param[in] backgroundColor Background color (RGBA) of the Notification. + * @param[in] callback Function that will be called then the Notification fades out. + * @param[in] callbackContext Context that will be passed to the callback. + * @param[in] keepUntilShown The Notification will be stored in a queue until it can be shown - even across application starts. + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The notification was successfully added or queued. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT text was NULL. + * @retval NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND The loaded module version doesn't not support this function. + * @retval NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED Allocation of the Notification has failed. + * @retval NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED The library is not initialized. */ NotificationModuleStatus NotificationModule_AddInfoNotificationEx(const char *text, float durationBeforeFadeOutInSeconds, @@ -111,37 +129,30 @@ NotificationModuleStatus NotificationModule_AddInfoNotificationEx(const char *te bool keepUntilShown); /** - * Displays a Notification that fade outs after a given time.
- * Similar to NotificationModule_AddInfoNotificationEx, but uses default values for all parameters except "text".
- * The default values are NotificationModule_AddInfoNotificationEx(text, 2.0f, {255, 255, 255, 255}, {100, 100, 100, 255}, nullptr, nullptr); but can be
- * overridden via NotificationModule_SetDefaultValue(NOTIFICATION_MODULE_NOTIFICATION_TYPE_INFO, xxx, yyy);
- *
- * Requires NotificationModule API version 1 or higher
- *
- * @param text Content of the Notification - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.
- * NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * Convenience wrapper for NotificationModule_AddInfoNotificationEx(). + * + * Uses default values for all parameters except `text`. + * Default values can be overridden via NotificationModule_SetDefaultValue(). + * + * @param[in] text Content of the Notification. + * @return See NotificationModule_AddInfoNotificationEx() for return values. + * @see NotificationModule_AddInfoNotificationEx + * @see NotificationModule_SetDefaultValue */ NotificationModuleStatus NotificationModule_AddInfoNotification(const char *text); /** - * Similar to NotificationModule_AddInfoNotification, but uses default values for all parameters except "text", callback, callbackContext
- *
- * Requires NotificationModule API version 1 or higher
- *
- * @param text Content of the Notification - * @param callback Function that will be called then the Notification fades out. - * @param callbackContext Context that will be passed to the callback. - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.
- * NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * Convenience wrapper for NotificationModule_AddInfoNotificationEx(). + * + * Uses default values for all parameters except `text`, `callback`, and `callbackContext`. + * Default values can be overridden via NotificationModule_SetDefaultValue(). + * + * @param[in] text Content of the Notification. + * @param[in] callback Function that will be called then the Notification fades out. + * @param[in] callbackContext Context that will be passed to the callback. + * @return See NotificationModule_AddInfoNotificationEx() for return values. + * @see NotificationModule_AddInfoNotificationEx + * @see NotificationModule_SetDefaultValue */ NotificationModuleStatus NotificationModule_AddInfoNotificationWithCallback(const char *text, NotificationModuleNotificationFinishedCallback callback, @@ -152,24 +163,24 @@ NotificationModuleStatus NotificationModule_AddInfoNotificationWithCallback(cons * Notification will appear in the top left corner. It's possible to display multiple notifications at the same time.
* The newest notification will always be at the top, the oldest at the bottom. Notifications will fade out to the left side.
* The Notification will at first shake for "shakeDurationInSeconds" seconds, then fades out after "durationBeforeFadeOutInSeconds"
- * have been passed (since displaying the Notification, this include the shake duration) + * have been passed (since displaying the Notification, this include the shake duration). *
- * Requires NotificationModule API version 1 or higher
+ * Requires NotificationModule API version 1 or higher.
*
- * @param text Content of the notification. - * @param durationBeforeFadeOutInSeconds Time in seconds before fading out - * @param shakeDurationInSeconds Time in seconds the notification will "shake" - * @param textColor Text color of the Notification - * @param backgroundColor Background color of the Notification - * @param callback Function that will be called then the Notification fades out. - * @param callbackContext Context that will be passed to the callback. - * @param keepUntilShown The Notification will be stored in a queue until can be shown - even accross application starts - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.
- * NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * @param[in] text Content of the notification. + * @param[in] durationBeforeFadeOutInSeconds Time in seconds before fading out. + * @param[in] shakeDurationInSeconds Time in seconds the notification will "shake". + * @param[in] textColor Text color (RGBA) of the Notification. + * @param[in] backgroundColor Background color (RGBA) of the Notification. + * @param[in] callback Function that will be called then the Notification fades out. + * @param[in] callbackContext Context that will be passed to the callback. + * @param[in] keepUntilShown The Notification will be stored in a queue until it can be shown - even across application starts. + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The notification was successfully added or queued. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT text was NULL. + * @retval NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND The loaded module version doesn't not support this function. + * @retval NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED Allocation of the Notification has failed. + * @retval NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED The library is not initialized. */ NotificationModuleStatus NotificationModule_AddErrorNotificationEx(const char *text, float durationBeforeFadeOutInSeconds, @@ -181,37 +192,30 @@ NotificationModuleStatus NotificationModule_AddErrorNotificationEx(const char *t bool keepUntilShown); /** - * Displays a (error) Notification (default background color: red) that shakes and fade outs after a given time.
- * Similar to NotificationModule_AddErrorNotificationEx, but uses default values for all parameters except "text".
- * The default values are NotificationModule_AddErrorNotificationEx(text, 2.0f, 0.5f, {255, 255, 255, 255}, {237, 28, 36, 255}, nullptr, nullptr); but can be
- * overridden via NotificationModule_SetDefaultValue(NOTIFICATION_MODULE_NOTIFICATION_TYPE_ERROR, xxx, yyy);
- *
- * Requires NotificationModule API version 1 or higher
- *
- * @param text Content of the notification. - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.
- * NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * Convenience wrapper for NotificationModule_AddErrorNotificationEx(). + * + * Uses default values for all parameters except `text`. + * Default values can be overridden via NotificationModule_SetDefaultValue(). + * + * @param[in] text Content of the notification. + * @return See NotificationModule_AddErrorNotificationEx() for return values. + * @see NotificationModule_AddErrorNotificationEx + * @see NotificationModule_SetDefaultValue */ NotificationModuleStatus NotificationModule_AddErrorNotification(const char *text); /** - * Similar to NotificationModule_AddErrorNotification, but uses default values for all parameters except "text", callback, callbackContext
- *
- * Requires NotificationModule API version 1 or higher
- *
- * @param text Content of the notification. - * @param callback Function that will be called then the Notification fades out. - * @param callbackContext Context that will be passed to the callback. - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The notification will show up.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.
- * NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * Convenience wrapper for NotificationModule_AddErrorNotificationEx(). + * + * Uses default values for all parameters except `text`, `callback`, and `callbackContext`. + * Default values can be overridden via NotificationModule_SetDefaultValue(). + * + * @param[in] text Content of the notification. + * @param[in] callback Function that will be called then the Notification fades out. + * @param[in] callbackContext Context that will be passed to the callback. + * @return See NotificationModule_AddErrorNotificationEx() for return values. + * @see NotificationModule_AddErrorNotificationEx + * @see NotificationModule_SetDefaultValue */ NotificationModuleStatus NotificationModule_AddErrorNotificationWithCallback(const char *text, NotificationModuleNotificationFinishedCallback callback, @@ -225,19 +229,20 @@ NotificationModuleStatus NotificationModule_AddErrorNotificationWithCallback(con * Use the `NotificationModule_UpdateDynamicNotificationText*` functions to update the notification after creating it.
*
* The Notification will be deleted automatically when the running application changes. - * @param text Content of the notification - * @param outHandle Pointer where the resulting - * @param textColor Text color of the notification - * @param backgroundColor Background color of the notification - * @param callback Function that will be called then the Notification fades out. - * @param callbackContext Context that will be passed to the callback. - * @param keepUntilShown The Notification will be stored in a queue until can be shown - even accross application starts - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text or outHandle was NULL
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.
- * NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * + * @param[in] text Content of the notification. + * @param[out] outHandle Pointer where the resulting handle will be stored. + * @param[in] textColor Text color (RGBA) of the notification. + * @param[in] backgroundColor Background color (RGBA) of the notification. + * @param[in] callback Function that will be called then the Notification fades out. + * @param[in] callbackContext Context that will be passed to the callback. + * @param[in] keepUntilShown The Notification will be stored in a queue until it can be shown - even across application starts. + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The notification was successfully created. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT text or outHandle was NULL. + * @retval NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND The loaded module version doesn't not support this function. + * @retval NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED Allocation of the Notification has failed. + * @retval NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED The library is not initialized. */ NotificationModuleStatus NotificationModule_AddDynamicNotificationEx(const char *text, NotificationModuleHandle *outHandle, @@ -248,42 +253,33 @@ NotificationModuleStatus NotificationModule_AddDynamicNotificationEx(const char bool keepUntilShown); /** - * Displays a Notification that can be updated and stays on the screen until `NotificationModule_FinishDynamicNotification*` has been called.
- * Similar to NotificationModule_AddDynamicNotificationEx, but uses default values for all parameters except "text".
- * The default values are NotificationModule_AddDynamicNotificationEx(text, outHandle, {255, 255, 255, 255}, {100, 100, 100, 255}, nullptr, nullptr); but can be
- * overridden via NotificationModule_SetDefaultValue(NOTIFICATION_MODULE_NOTIFICATION_TYPE_DYNAMIC, xxx, yyy);
- *
- * Requires NotificationModule API version 1 or higher
- * @param text Content of the notification - * @param outHandle Pointer where the resulting - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text or outHandle was NULL
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.
- * NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * Convenience wrapper for NotificationModule_AddDynamicNotificationEx(). + * + * Uses default values for all parameters except `text` and `outHandle`. + * Default values can be overridden via NotificationModule_SetDefaultValue(). + * + * @param[in] text Content of the notification. + * @param[out] outHandle Pointer where the resulting handle will be stored. + * @return See NotificationModule_AddDynamicNotificationEx() for return values. + * @see NotificationModule_AddDynamicNotificationEx + * @see NotificationModule_SetDefaultValue */ NotificationModuleStatus NotificationModule_AddDynamicNotification(const char *text, NotificationModuleHandle *outHandle); /** - * Displays a Notification that can be updated and stays on the screen until `NotificationModule_FinishDynamicNotification*` has been called.
- * Similar to NotificationModule_AddDynamicNotificationEx, but uses default values for all parameters except "text", callback and callbackContext.
- * The default values are NotificationModule_AddDynamicNotificationEx(text, outHandle, {255, 255, 255, 255}, {100, 100, 100, 255}, callback, callbackContext); but can be
- * overridden via NotificationModule_SetDefaultValue(NOTIFICATION_MODULE_NOTIFICATION_TYPE_DYNAMIC, xxx, yyy);
- *
- * Requires NotificationModule API version 1 or higher
+ * Convenience wrapper for NotificationModule_AddDynamicNotificationEx(). * - * @param text Content of the notification - * @param outHandle Pointer where the resulting - * @param callback Function that will be called then the Notification fades out. - * @param callbackContext Context that will be passed to the callback. - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text or outHandle was NULL
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.
- * NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * Uses default values for all parameters except `text`, `outHandle`, `callback`, and `callbackContext`. + * Default values can be overridden via NotificationModule_SetDefaultValue(). + * + * @param[in] text Content of the notification. + * @param[out] outHandle Pointer where the resulting handle will be stored. + * @param[in] callback Function that will be called then the Notification fades out. + * @param[in] callbackContext Context that will be passed to the callback. + * @return See NotificationModule_AddDynamicNotificationEx() for return values. + * @see NotificationModule_AddDynamicNotificationEx + * @see NotificationModule_SetDefaultValue */ NotificationModuleStatus NotificationModule_AddDynamicNotificationWithCallback(const char *text, NotificationModuleHandle *outHandle, @@ -293,15 +289,16 @@ NotificationModuleStatus NotificationModule_AddDynamicNotificationWithCallback(c /** * Updates the text of a dynamic notification. *
- * Requires NotificationModule API version 1 or higher
+ * Requires NotificationModule API version 1 or higher.
*
- * @param handle Handle of the notification - * @param textColor New background color - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The text has been updated.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: handle was NULL.
- * NOTIFICATION_MODULE_RESULT_INVALID_HANDLE: handle was not found.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * @param[in] handle Handle of the notification. + * @param[in] text New text content. + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The text has been updated. + * @retval NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND The loaded module version doesn't support this function. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT handle was NULL. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_HANDLE handle was not found. + * @retval NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED The library is not initialized. */ NotificationModuleStatus NotificationModule_UpdateDynamicNotificationText(NotificationModuleHandle handle, const char *text); @@ -309,15 +306,16 @@ NotificationModuleStatus NotificationModule_UpdateDynamicNotificationText(Notifi /** * Updates the background color of a dynamic notification. *
- * Requires NotificationModule API version 1 or higher
+ * Requires NotificationModule API version 1 or higher.
*
- * @param handle Handle of the notification - * @param textColor New background color - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The background color has been updated.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: handle was NULL.
- * NOTIFICATION_MODULE_RESULT_INVALID_HANDLE: handle was not found.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * @param[in] handle Handle of the notification. + * @param[in] backgroundColor New background color (RGBA). + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The background color has been updated. + * @retval NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND The loaded module version doesn't support this function. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT handle was NULL. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_HANDLE handle was not found. + * @retval NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED The library is not initialized. */ NotificationModuleStatus NotificationModule_UpdateDynamicNotificationBackgroundColor(NotificationModuleHandle handle, NMColor backgroundColor); @@ -325,50 +323,58 @@ NotificationModuleStatus NotificationModule_UpdateDynamicNotificationBackgroundC /** * Updates the text color of a dynamic notification.
*
- * Requires NotificationModule API version 1 or higher
+ * Requires NotificationModule API version 1 or higher.
*
- * @param handle Handle of the notification - * @param textColor New text color - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: The text color has been updated.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: handle was NULL.
- * NOTIFICATION_MODULE_RESULT_INVALID_HANDLE: handle was not found.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * @param[in] handle Handle of the notification. + * @param[in] textColor New text color (RGBA). + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS The text color has been updated. + * @retval NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND The loaded module version doesn't support this function. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT handle was NULL. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_HANDLE handle was not found. + * @retval NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED The library is not initialized. */ NotificationModuleStatus NotificationModule_UpdateDynamicNotificationTextColor(NotificationModuleHandle handle, NMColor textColor); /** - * Fades out a existing dynamic notification `durationBeforeFadeOutInSeconds` seconds after calling this funcion.
- * Calls the callback of the notification before fading out.
- *
- * Requires NotificationModule API version 1 or higher
- *
- * @param handle handle of the notification to fade out. - * @param durationBeforeFadeOutInSeconds duration before fading out in seconds. - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: Finish the given notification.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: handle was NULL.
- * NOTIFICATION_MODULE_RESULT_INVALID_HANDLE: handle was not found.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * Fades out a existing dynamic notification. + * + * Calls the callback of the notification afters fading out. + * + * Requires NotificationModule API version 1 or higher.
+ * + * @param[in] handle handle of the notification to fade out. + * @param[in] durationBeforeFadeOutInSeconds duration before fading out in seconds. + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS Finish the given notification. + * @retval NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND The loaded module version doesn't support this function. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT handle was NULL. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_HANDLE handle was not found. + * @retval NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED The library is not initialized. + * @see NotificationModule_FinishDynamicNotificationWithShake */ NotificationModuleStatus NotificationModule_FinishDynamicNotification(NotificationModuleHandle handle, float durationBeforeFadeOutInSeconds); /** - * Shakes an exiting notification for `shakeDuration` seconds and fades it out `durationBeforeFadeOutInSeconds` seconds after calling this function.
- * Calls the callback of the notification before fading out.
- *
- * Requires NotificationModule API version 1 or higher
- *
- * @param handle handle of the notification to fade out. - * @param durationBeforeFadeOutInSeconds duration before fading out in seconds. - * @param shakeDuration shake duration in seconds. - * @return NOTIFICATION_MODULE_RESULT_SUCCESS: Finish the given notification with a shake.
- * NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.
- * NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: handle was NULL.
- * NOTIFICATION_MODULE_RESULT_INVALID_HANDLE: handle was not found.
- * NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.
+ * Fades out a existing dynamic notification after shaking it. + * + * The Notification will at first shake for "shakeDuration" seconds, then fades out after "durationBeforeFadeOutInSeconds". + * Calls the callback of the notification after fading out. + * + * Requires NotificationModule API version 1 or higher.
+ * + * @param[in] handle handle of the notification to fade out. + * @param[in] durationBeforeFadeOutInSeconds duration before fading out in seconds. + * @param[in] shakeDuration shake duration in seconds. + * @return The status of the operation. + * @retval NOTIFICATION_MODULE_RESULT_SUCCESS Finish the given notification with a shake. + * @retval NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND The loaded module version doesn't support this function. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT handle was NULL. + * @retval NOTIFICATION_MODULE_RESULT_INVALID_HANDLE handle was not found. + * @retval NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED The library is not initialized. + * @see NotificationModule_FinishDynamicNotification */ NotificationModuleStatus NotificationModule_FinishDynamicNotificationWithShake(NotificationModuleHandle handle, float durationBeforeFadeOutInSeconds, @@ -390,4 +396,4 @@ NotificationModuleStatus NotificationModule_FinishDynamicNotificationWithShake(N #define NotificationModule_SetDefaultValue(type, valueType, param) NotificationModule_SetDefaultValue(type, valueType, param) #endif /* __STDC__ >= 1 */ -#endif /* gcc >= 4.3 */ +#endif /* gcc >= 4.3 */ \ No newline at end of file