# HG changeset patch
# User David Demelier <markand@malikania.fr>
# Date 1693056273 -7200
# Node ID 29a121241485932e3dbae2ec560417f014c2bc40
# Parent  2c551492716611fe33cdbf509014bd65cb061d26
ui: improve documentation (notify.h)

diff -r 2c5514927166 -r 29a121241485 examples/example-notify/example-notify.c
--- a/examples/example-notify/example-notify.c	Sat Aug 26 10:35:53 2023 +0200
+++ b/examples/example-notify/example-notify.c	Sat Aug 26 15:24:33 2023 +0200
@@ -37,7 +37,7 @@
 #include <mlk/example/registry.h>
 
 static struct mlk_label help = {
-	.text = "Keys: <Space> to generate a notification.",
+	.text = "Keys: <Space> to generate a notification, <Escape> to clear.",
 	.x = 10,
 	.y = 10
 };
@@ -62,8 +62,16 @@
 		mlk_game_quit();
 		break;
 	case MLK_EVENT_KEYDOWN:
-		if (ev->key.key == MLK_KEY_SPACE)
+		switch (ev->key.key) {
+		case MLK_KEY_ESCAPE:
+			mlk_notify_clear();
+			break;
+		case MLK_KEY_SPACE:
 			mlk_notify(icon, "Quest", "Quest finished.");
+			break;
+		default:
+			break;
+		}
 		break;
 	default:
 		break;
diff -r 2c5514927166 -r 29a121241485 libmlk-ui/mlk/ui/notify.c
--- a/libmlk-ui/mlk/ui/notify.c	Sat Aug 26 10:35:53 2023 +0200
+++ b/libmlk-ui/mlk/ui/notify.c	Sat Aug 26 15:24:33 2023 +0200
@@ -98,9 +98,9 @@
 static void
 draw_frame(const struct geo *geo)
 {
-	mlk_painter_set_color(mlk_notify_style.border_color);
+	mlk_painter_set_color(mlk_notify_style.border);
 	mlk_painter_draw_rectangle(geo->frame_x, geo->frame_y, geo->frame_w, geo->frame_h);
-	mlk_painter_set_color(mlk_notify_style.bg_color);
+	mlk_painter_set_color(mlk_notify_style.background);
 	mlk_painter_draw_rectangle(
 		geo->frame_x +  mlk_notify_style.border_size,
 		geo->frame_y +  mlk_notify_style.border_size,
@@ -120,8 +120,8 @@
 {
 	mlk_ui_draw_text(
 		MLK_ALIGN_NONE,
-		FONT,
-		mlk_notify_style.text_color,
+		MLK__STYLE_FONT(mlk_notify_style.font, MLK_UI_FONT_INTERFACE),
+		mlk_notify_style.color,
 		n->title,
 		geo->title_x,
 		geo->title_y,
@@ -135,8 +135,8 @@
 {
 	mlk_ui_draw_text(
 		MLK_ALIGN_NONE,
-		FONT,
-		mlk_notify_style.text_color,
+		MLK__STYLE_FONT(mlk_notify_style.font, MLK_UI_FONT_INTERFACE),
+		mlk_notify_style.color,
 		n->body,
 		geo->body_x,
 		geo->body_y,
@@ -146,7 +146,7 @@
 }
 
 static void
-delegate_draw(const struct mlk_notify *n, size_t index)
+draw(const struct mlk_notify *n, size_t index)
 {
 	struct geo geo;
 
@@ -160,35 +160,30 @@
 }
 
 struct mlk_notify_style mlk_notify_style = {
-	.bg_color       = MLK_UI_COLOR_BG,
-	.border_color   = MLK_UI_COLOR_BORDER,
+	.background     = MLK_UI_COLOR_BG,
+	.border         = MLK_UI_COLOR_BORDER,
 	.border_size    = 2,
-	.delay          = 5000,
-	.padding        = 10
-};
-
-struct mlk_notify_delegate mlk_notify_delegate = {
+	.timeout        = 5000,
+	.padding        = 10,
 	.stack          = stack,
 	.stacksz        = MLK_UTIL_SIZE(stack),
-	.draw           = delegate_draw
+	.draw           = draw
 };
 
 void
 mlk_notify(const struct mlk_texture *icon, const char *title, const char *body)
 {
-	assert(icon);
-	assert(title);
 	assert(body);
 
 	struct mlk_notify *n;
 
-	if (mlk_notify_delegate.length >= mlk_notify_delegate.stacksz) {
-		memmove(&mlk_notify_delegate.stack[0],
-			&mlk_notify_delegate.stack[1],
-			sizeof (mlk_notify_delegate.stack[0]) - mlk_notify_delegate.stacksz - 1);
-		n = &mlk_notify_delegate.stack[mlk_notify_delegate.length - 1];
+	if (mlk_notify_style.length >= mlk_notify_style.stacksz) {
+		memmove(&mlk_notify_style.stack[0],
+			&mlk_notify_style.stack[1],
+			sizeof (mlk_notify_style.stack[0]) - mlk_notify_style.stacksz - 1);
+		n = &mlk_notify_style.stack[mlk_notify_style.length - 1];
 	} else
-		n = &mlk_notify_delegate.stack[mlk_notify_delegate.length++];
+		n = &mlk_notify_style.stack[mlk_notify_style.length++];
 
 	memset(n, 0, sizeof (*n));
 	n->icon = icon;
@@ -197,23 +192,31 @@
 }
 
 void
+mlk_notify_clear(void)
+{
+	mlk_notify_style.length = 0;
+}
+
+void
 mlk_notify_update(unsigned int ticks)
 {
 	struct mlk_notify *n;
 
-	for (size_t i = 0; i < mlk_notify_delegate.length; ++i) {
-		n = &mlk_notify_delegate.stack[i];
+	for (size_t i = 0; i < mlk_notify_style.length; ++i) {
+		n = &mlk_notify_style.stack[i];
 		n->elapsed += ticks;
 
-		if (n->elapsed >= mlk_notify_style.delay)
-			memmove(n, n + 1, sizeof (*n) * (--mlk_notify_delegate.length - i));
+		if (n->elapsed >= mlk_notify_style.timeout)
+			memmove(n, n + 1, sizeof (*n) * (--mlk_notify_style.length - i));
 	}
 }
 
 void
 mlk_notify_draw(void)
 {
-	for (size_t i = 0; i < mlk_notify_delegate.length; ++i)
-		if (mlk_notify_delegate.draw)
-			mlk_notify_delegate.draw(&mlk_notify_delegate.stack[i], i);
+	if (!mlk_notify_style.draw)
+		return;
+
+	for (size_t i = 0; i < mlk_notify_style.length; ++i)
+		mlk_notify_style.draw(&mlk_notify_style.stack[i], i);
 }
diff -r 2c5514927166 -r 29a121241485 libmlk-ui/mlk/ui/notify.h
--- a/libmlk-ui/mlk/ui/notify.h	Sat Aug 26 10:35:53 2023 +0200
+++ b/libmlk-ui/mlk/ui/notify.h	Sat Aug 26 15:24:33 2023 +0200
@@ -19,49 +19,180 @@
 #ifndef MLK_UI_NOTIFY_H
 #define MLK_UI_NOTIFY_H
 
+/**
+ * \file mlk/ui/notify.h
+ * \brief In game notifications.
+ */
+
 #include <stddef.h>
 
 struct mlk_font;
 struct mlk_texture;
 
+/**
+ * \struct mlk_notify
+ * \brief Structure describing a unique notification.
+ */
 struct mlk_notify {
+	/**
+	 * (read-only, borrowed, optional)
+	 *
+	 * An associated icon.
+	 */
 	const struct mlk_texture *icon;
+
+	/**
+	 * (read-only, borrowed, optional)
+	 *
+	 * Notification title.
+	 */
 	const char *title;
+
+	/**
+	 * (read-only, borrowed, optional)
+	 *
+	 * Notification content.
+	 */
 	const char *body;
+
+	/** \cond MLK_PRIVATE_DECLS */
 	unsigned int elapsed;
+	/** \endcond MLK_PRIVATE_DECLS */
 };
 
+/**
+ * \struct mlk_notify_style
+ * \brief Notification system style.
+ */
 struct mlk_notify_style {
-	unsigned long bg_color;
-	unsigned long text_color;
-	struct mlk_font *text_font;
-	unsigned long border_color;
+	/**
+	 * (read-write, borrowed, optional)
+	 *
+	 * Font to use to draw title and body.
+	 *
+	 * If NULL, uses ::MLK_UI_FONT_INTERFACE.
+	 */
+	struct mlk_font *font;
+
+	/**
+	 * (read-write)
+	 *
+	 * Background color.
+	 */
+	unsigned long background;
+
+	/**
+	 * (read-write)
+	 *
+	 * Border color.
+	 */
+	unsigned long border;
+
+	/**
+	 * (read-write)
+	 *
+	 * Border size.
+	 */
 	unsigned int border_size;
-	unsigned int delay;
+
+	/**
+	 * (read-write)
+	 *
+	 * Text color.
+	 */
+	unsigned long color;
+
+	/**
+	 * (read-write)
+	 *
+	 * Notification lifetime in milliseconds.
+	 */
+	unsigned int timeout;
+
+	/**
+	 * (read-write)
+	 *
+	 * Padding between top corner and notification elements.
+	 */
 	unsigned int padding;
-};
 
-struct mlk_notify_delegate {
+	/**
+	 * (read-write, borrowed, optional)
+	 *
+	 * Array where to store notifications.
+	 *
+	 * If NULL, a static array is used with a limited numbers of
+	 * notifications.
+	 */
 	struct mlk_notify *stack;
+
+	/**
+	 * (read-write)
+	 *
+	 * Number of available notifications in ::mlk_notify_style::stack.
+	 */
 	size_t stacksz;
+
+	/**
+	 * (read-write)
+	 *
+	 * Current number of notifications in the ::mlk_notify_style::stack.
+	 */
 	size_t length;
+
+	/**
+	 * (read-write, optional)
+	 *
+	 * Update the notifications and remove outdated ones.
+	 *
+	 * \param ticks frame ticks
+	 */
 	void (*update)(unsigned int ticks);
+
+	/**
+	 * (read-write, optional)
+	 *
+	 * \param n the notification to draw
+	 * \param index notification number
+	 */
 	void (*draw)(const struct mlk_notify *notif, size_t index);
 };
 
+/**
+ * \brief Global notification style.
+ */
 extern struct mlk_notify_style mlk_notify_style;
-extern struct mlk_notify_delegate mlk_notify_delegate;
 
 #if defined(__cplusplus)
 extern "C" {
 #endif
 
+/**
+ * Push a new notification in the queue.
+ *
+ * \pre body != NULL
+ * \param icon an optional icon to show (borrowed)
+ * \param title an optional title to show (borrowed)
+ * \param body notification text content (borrowed)
+ */
 void
-mlk_notify(const struct mlk_texture *, const char *, const char *);
+mlk_notify(const struct mlk_texture *icon, const char *title, const char *body);
 
+/**
+ * Clear up every notifications.
+ */
+void
+mlk_notify_clear(void);
+
+/**
+ * Invoke ::mlk_notify_style::update
+ */
 void
 mlk_notify_update(unsigned int ticks);
 
+/**
+ * Invoke ::mlk_notify_style::draw
+ */
 void
 mlk_notify_draw(void);