Leahnaya/libnotifications
1
0
Fork 0
mirror of https://github.com/wiiu-env/libnotifications.git synced 2026-03-21 18:04:09 -05:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update documentation
Some checks failed
Publish Docker Image / build-and-push-image (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Maschell 2026-01-22 13:15:21 +01:00
parent b52b7ae80a
commit aa093106b3
2 changed files with 357 additions and 225 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

160
README.md
View File

@ -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 `<notifications/notifications.h>` 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 <notifications/notifications.h>
```
### 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
```

422
include/notifications/notifications.h
View File

@ -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.<br>
* NOTIFICATION_MODULE_RESULT_MODULE_NOT_FOUND: The module could not be found. Make sure the module is loaded.<br>
* NOTIFICATION_MODULE_RESULT_MODULE_MISSING_EXPORT: The module is missing an expected export.<br>
* 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. <br>
* <br>
* 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.<br>
* NOTIFICATION_MODULE_RESULT_MODULE_NOT_FOUND: The module could not be found. Make sure the module is loaded.<br>
* NOTIFICATION_MODULE_RESULT_MODULE_MISSING_EXPORT: The module is missing an expected export.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: Invalid version pointer.<br>
* 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. <br>
* Notifications can only be added if the overlay is ready. <br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* Requires NotificationModule API version 1 or higher. <br>
* <br>
* @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.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: Invalid version pointer.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* @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.<br>
* See the NotificationModuleNotificationType and NotificationModuleNotificationOption enums for more information. <br>
* <br>
* These default values will be use when calling <br>
* These default values will be use when calling: <br>
* - NotificationModule_AddInfoNotification/NotificationModule_AddInfoNotificationWithCallback (type = NOTIFICATION_MODULE_NOTIFICATION_TYPE_INFO) <br>
* - NotificationModule_AddErrorNotification/NotificationModule_AddErrorNotificationWithCallback (type = NOTIFICATION_MODULE_NOTIFICATION_TYPE_ERROR) <br>
* - NotificationModule_AddDynamicNotification/NotificationModule_AddDynamicNotificationWithCallback (type = NOTIFICATION_MODULE_NOTIFICATION_TYPE_DYNAMIC) <br>
* <br>
* <br>
* The "WithCallback" function will NOT take the default callback + context. <br>
*
* @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.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: The given notification or option type was invalid <br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized<br>
* @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. <br>
* The newest notification will always be at the top, the oldest at the bottom. Notifications will fade out to the left side. <br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* Requires NotificationModule API version 1 or higher. <br>
* <br>
* @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.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.<br>
* NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* @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. <br>
* Similar to NotificationModule_AddInfoNotificationEx, but uses default values for all parameters except "text". <br>
* The default values are NotificationModule_AddInfoNotificationEx(text, 2.0f, {255, 255, 255, 255}, {100, 100, 100, 255}, nullptr, nullptr); but can be <br>
* overridden via NotificationModule_SetDefaultValue(NOTIFICATION_MODULE_NOTIFICATION_TYPE_INFO, xxx, yyy); <br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* <br>
* @param text Content of the Notification
* @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.<br>
* NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* 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<br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* <br>
* @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.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.<br>
* NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* 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. <br>
* The newest notification will always be at the top, the oldest at the bottom. Notifications will fade out to the left side. <br>
* The Notification will at first shake for "shakeDurationInSeconds" seconds, then fades out after "durationBeforeFadeOutInSeconds" <br>
* have been passed (since displaying the Notification, this include the shake duration)
* have been passed (since displaying the Notification, this include the shake duration).
* <br>
* Requires NotificationModule API version 1 or higher <br>
* Requires NotificationModule API version 1 or higher. <br>
* <br>
* @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.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.<br>
* NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* @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. <br>
* Similar to NotificationModule_AddErrorNotificationEx, but uses default values for all parameters except "text". <br>
* The default values are NotificationModule_AddErrorNotificationEx(text, 2.0f, 0.5f, {255, 255, 255, 255}, {237, 28, 36, 255}, nullptr, nullptr); but can be <br>
* overridden via NotificationModule_SetDefaultValue(NOTIFICATION_MODULE_NOTIFICATION_TYPE_ERROR, xxx, yyy); <br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* <br>
* @param text Content of the notification.
* @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.<br>
* NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* 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<br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* <br>
* @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.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text was NULL.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.<br>
* NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* 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. <br>
* <br>
* 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.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text or outHandle was NULL <br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.<br>
* NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
*
* @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. <br>
* Similar to NotificationModule_AddDynamicNotificationEx, but uses default values for all parameters except "text". <br>
* The default values are NotificationModule_AddDynamicNotificationEx(text, outHandle, {255, 255, 255, 255}, {100, 100, 100, 255}, nullptr, nullptr); but can be <br>
* overridden via NotificationModule_SetDefaultValue(NOTIFICATION_MODULE_NOTIFICATION_TYPE_DYNAMIC, xxx, yyy); <br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* @param text Content of the notification
* @param outHandle Pointer where the resulting
* @return NOTIFICATION_MODULE_RESULT_SUCCESS: The default value has been set.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text or outHandle was NULL <br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.<br>
* NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* 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. <br>
* Similar to NotificationModule_AddDynamicNotificationEx, but uses default values for all parameters except "text", callback and callbackContext. <br>
* The default values are NotificationModule_AddDynamicNotificationEx(text, outHandle, {255, 255, 255, 255}, {100, 100, 100, 255}, callback, callbackContext); but can be <br>
* overridden via NotificationModule_SetDefaultValue(NOTIFICATION_MODULE_NOTIFICATION_TYPE_DYNAMIC, xxx, yyy); <br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* 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.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: text or outHandle was NULL <br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_OVERLAY_NOT_READY: The overlay is not ready. See NotificationModule_IsOverlayReady.<br>
* NOTIFICATION_MODULE_RESULT_ALLOCATION_FAILED: Allocation of the Notification has failed.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* 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.
* <br>
* Requires NotificationModule API version 1 or higher <br>
* Requires NotificationModule API version 1 or higher. <br>
* <br>
* @param handle Handle of the notification
* @param textColor New background color
* @return NOTIFICATION_MODULE_RESULT_SUCCESS: The text has been updated.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: handle was NULL.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_HANDLE: handle was not found.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* @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.
* <br>
* Requires NotificationModule API version 1 or higher <br>
* Requires NotificationModule API version 1 or higher. <br>
* <br>
* @param handle Handle of the notification
* @param textColor New background color
* @return NOTIFICATION_MODULE_RESULT_SUCCESS: The background color has been updated.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: handle was NULL.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_HANDLE: handle was not found.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* @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. <br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* Requires NotificationModule API version 1 or higher. <br>
* <br>
* @param handle Handle of the notification
* @param textColor New text color
* @return NOTIFICATION_MODULE_RESULT_SUCCESS: The text color has been updated.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: handle was NULL.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_HANDLE: handle was not found.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* @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. <br>
* Calls the callback of the notification before fading out. <br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* <br>
* @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.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: handle was NULL.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_HANDLE: handle was not found.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* Fades out a existing dynamic notification.
*
* Calls the callback of the notification afters fading out.
*
* Requires NotificationModule API version 1 or higher. <br>
*
* @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. <br>
* Calls the callback of the notification before fading out. <br>
* <br>
* Requires NotificationModule API version 1 or higher <br>
* <br>
* @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.<br>
* NOTIFICATION_MODULE_RESULT_UNSUPPORTED_COMMAND: The loaded module version doesn't not support this function.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_ARGUMENT: handle was NULL.<br>
* NOTIFICATION_MODULE_RESULT_INVALID_HANDLE: handle was not found.<br>
* NOTIFICATION_MODULE_RESULT_LIB_UNINITIALIZED: The library is not initialized.<br>
* 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. <br>
*
* @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 */