From 365fefeaaff2cff8aca5d12eb57ffcfaf0170a49 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Costa?= <andre_miguel_costa@hotmail.com>
Date: Mon, 6 Oct 2025 09:37:49 +0200
Subject: [PATCH] docs(flags): add chapter explaining how to add/remove
 multiple flags (#9000)

---
 .../details/common-widget-features/flags.rst  | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/src/details/common-widget-features/flags.rst b/docs/src/details/common-widget-features/flags.rst
index 0dc3f95941..96ec497cdd 100644
--- a/docs/src/details/common-widget-features/flags.rst
+++ b/docs/src/details/common-widget-features/flags.rst
@@ -60,3 +60,28 @@ Some examples:
     /* Check if it is clickable */
     if(lv_obj_has_flag(widget, LV_OBJ_FLAG_CLICKABLE)) printf("Clickable\n");
 
+Adding and/or Removing Multiple Flags
+*************************************
+
+When adding or removing multiple flags, you have two options:
+
+**Option 1: Multiple calls (Recommended)**
+
+This approach is clearer and works seamlessly in both C and C++:
+
+.. code-block:: c
+
+    lv_obj_add_flag(widget, LV_OBJ_FLAG_CLICKABLE);
+    lv_obj_add_flag(widget, LV_OBJ_FLAG_EVENT_BUBBLE);
+
+**Option 2: Single call with bitwise OR**
+
+You can combine multiple flags in one call using the bitwise OR operator (``|``). When using a C++ compiler, you must cast the result:
+
+.. code-block:: c
+
+    lv_obj_add_flag(widget, (lv_obj_flag_t)(LV_OBJ_FLAG_CLICKABLE | LV_OBJ_FLAG_EVENT_BUBBLE));
+
+.. note::
+
+    The cast to ``lv_obj_flag_t`` is required in C++ due to stricter type checking, but is optional in C.