feat(subject): add back subject increment events (#9057)

Co-authored-by: Victor Wheeler <vwheeler63@users.noreply.github.com>

docs/src/details/auxiliary-modules/observer/observer.rst

@@ -497,26 +497,33 @@ This will toggle `subject1` between 0 and 1 each time `button1` is clicked.
 Increment
 ~~~~~~~~~
 
-:cpp:expr:`lv_obj_add_subject_increment_event(obj, subject, trigger, step, rollover)`
+:cpp:expr:`lv_obj_add_subject_increment_event(obj, subject, trigger, step)`
-increments an integer subject's value by `step`.
+increments an integer subject's value by ``step``.
 
-It works on both integer and float subject.
+It returns a :cpp:type:`lv_subject_increment_dsc_t` pointer to configure the
+event further:
 
-``rollover`` can be ``true`` or ``false``. If ``true`` and the subject's minimum or maximum
+- :cpp:expr:`lv_obj_set_subject_increment_event_min_value(obj, dsc, min_value)`:
-value is exceeded, the other end value is set. That is, going beyond
+  Set a minimum value for the event. Default ``INT32_MIN``
-the maximum value sets the minimum value, and vice versa.
+- :cpp:expr:`lv_obj_set_subject_increment_event_max_value(obj, dsc, max_value)`:
+  Set a maximum value for the event. Default ``INT32_MAX``
+- :cpp:expr:`lv_obj_set_subject_increment_event_rollover(obj, dsc, rollover)`:
+  Set what to do when the min/max value is crossed. ``false``: stop at the min/max
+  value; ``true``: jump to the other end. Default ``false``
 
-Using a negative `step` will decrement the value instead.
+It works on both integer and float subjects, but the min/max value is an integer in both cases.
 
+If the subject also sets a min/max value the narrower range will be used.
+
+Using a negative ``step`` will decrement the value instead.
 
 For example:
 
-:cpp:expr:`lv_obj_add_subject_increment_event(button1, subject1, LV_EVENT_CLICKED, 5, false)`
+:cpp:expr:`lv_obj_add_subject_increment_event(button1, subject1, LV_EVENT_CLICKED, 5)`
-
-This will increment `subject1` by 5 when `button1` is clicked, stopping at the limits set by
-:cpp:expr:`lv_subject_set_min_value_int()` and :cpp:expr:`lv_subject_set_max_value_int()`
-(same for float subjects).
 
+This will increment ``subject1`` by 5 when ``button1`` is clicked, stopping at the limits
+set by the min/max values of the event or :cpp:expr:`lv_subject_set_min_value_int()`
+and :cpp:expr:`lv_subject_set_max_value_int()` (same for float subjects).
 
 Set to a Value
 ~~~~~~~~~~~~~~

docs/src/details/xml/features/subjects.rst

@@ -80,3 +80,12 @@ Explanation of complex bindings:
 - ``<lv_obj-bind_state_if_le>`` — Set a state if the subject's value is **less than or equal to** the reference value.
 
 Note: The ``lv_obj-`` prefix can be omitted. For example, you can simply write ``<bind_state_if_gt>`` instead.
+
+Subject Related Events
+**********************
+
+Besides binding properties to subjects, it's also possible to add events the change the value
+of a subject on pressed, release, etc.
+
+Learn more about these in :ref:`xml_events_set_subject_value` and
+:ref:`xml_events_increment_subject_value`.

docs/src/details/xml/ui_elements/events.rst

@@ -20,7 +20,7 @@ All LVGL event types are supported with straightforward mapping:
 - :cpp:enumerator:`LV_EVENT_PRESSED`: ``"pressed"``
 - etc.
 
-Call function
+Call Function
 *************
 
 User-defined functions can be called like this:
@@ -108,7 +108,9 @@ This is a simple example of both load and create:
     lv_obj_t * screen1 = lv_xml_create(NULL, "screen1", NULL);
     lv_screen_load(screen1);
 
-Set subject value
+.. _xml_events_set_subject_value:
+
+Set Subject Value
 *****************
 
 It's possible to set a :ref:`Subject <observer_subject>` value on user interaction by adding a special child to any widget:
@@ -126,7 +128,10 @@ It's possible to set a :ref:`Subject <observer_subject>` value on user interacti
 
 The usage is straightforward: the specified ``subject`` will be set to the given ``value`` when the ``trigger`` occurs.
 
-Increment subject value
+
+.. _xml_events_increment_subject_value:
+
+Increment Subject Value
 ***********************
 
 Incrementing or decrementing a :ref:`Subject <observer_subject>` value can be defined as follows:
@@ -136,18 +141,21 @@ Incrementing or decrementing a :ref:`Subject <observer_subject>` value can be de
     <view>
         <lv_button width="200" height="100">
             <subject_increment_event trigger="clicked" subject="subject_int1" step="10"/>
-            <subject_increment_event trigger="clicked" subject="subject_int2" step="-10" min="0" max="50"/>
+            <subject_increment_event trigger="clicked" subject="subject_int2" step="-10" min_value="0" max_value="50"/>
             <subject_increment_event trigger="clicked" subject="subject_float1" step="2"/>
         </lv_button>
     </view>
 
 The ``<subject_increment_event>`` element defines a ``step`` to be added to the subject's current value
-when the ``trigger`` occurs. Optionally, ``min`` and/or ``max`` can be set to limit the subject's value.
+when the ``trigger`` occurs.
 
 ``subject`` must be an ``int`` or ``float`` subject.
 
 If ``step`` is **negative**, the subject's value will be decremented.
 Only integer ``step`` values are supported now.
 
-**Note:** Only integer subjects are supported by ``<subject_increment>``.
+Optionally, ``min_value`` and/or ``max_value`` can be set to limit the subject's value.
+The default min/max values are ``INT32_MIN`` (-2B) and ``INT32_MAX`` (+2B) respectively.
 
+``rollover`` is also an optional property. If it's ``false`` (default) stop at the
+min/max value, if ``true`` jump to the other end.

src/misc/lv_types.h

@@ -282,6 +282,8 @@ typedef struct _lv_gltf_model_t lv_gltf_model_t;
 
 typedef struct _lv_observer_t lv_observer_t;
 
+typedef struct _lv_subject_increment_dsc_t lv_subject_increment_dsc_t;
+
 typedef struct _lv_monkey_config_t lv_monkey_config_t;
 
 typedef struct _lv_ime_pinyin_t lv_ime_pinyin_t;

src/others/observer/lv_observer.c

@@ -59,12 +59,6 @@ typedef struct {
     const char * value;
 } subject_set_string_user_data_t;
 
-typedef struct {
-    lv_subject_t * subject;
-    int32_t step;
-    bool rollover;
-} subject_increment_user_data_t;
-
 /**********************
  *  STATIC PROTOTYPES
  **********************/
@@ -576,26 +570,91 @@ void lv_subject_notify(lv_subject_t * subject)
     } while(subject->notify_restart_query);
 }
 
-void lv_obj_add_subject_increment_event(lv_obj_t * obj, lv_subject_t * subject, lv_event_code_t trigger, int32_t step,
+lv_subject_increment_dsc_t * lv_obj_add_subject_increment_event(lv_obj_t * obj, lv_subject_t * subject,
-                                        bool rollover)
+                                                                lv_event_code_t trigger, int32_t step)
 {
     if(subject->type != LV_SUBJECT_TYPE_INT && subject->type != LV_SUBJECT_TYPE_FLOAT) {
         LV_LOG_WARN("Subject type must be `int` or `float` (was %d)", subject->type);
-        return;
+        return NULL;
     }
 
-    subject_increment_user_data_t * user_data = lv_malloc(sizeof(subject_increment_user_data_t));
+    lv_subject_increment_dsc_t * user_data = lv_malloc(sizeof(lv_subject_increment_dsc_t));
     if(user_data == NULL) {
         LV_ASSERT_MALLOC(user_data);
         LV_LOG_WARN("Couldn't allocate user_data in in <lv_obj-subject_increment>");
-        return;
+        return NULL;
     }
 
     user_data->step = step;
     user_data->subject = subject;
-    user_data->rollover = rollover;
+    user_data->rollover = false;
+    user_data->min_value = INT32_MIN;
+    user_data->max_value = INT32_MAX;
     lv_obj_add_event_cb(obj, subject_increment_cb, trigger, user_data);
     lv_obj_add_event_cb(obj, lv_event_free_user_data_cb, LV_EVENT_DELETE, user_data);
+
+    return user_data;
+}
+
+void lv_obj_set_subject_increment_event_min_value(lv_obj_t * obj, lv_subject_increment_dsc_t * dsc, int32_t min_value)
+{
+    LV_UNUSED(obj);
+    LV_ASSERT_NULL(dsc);
+    if(dsc == NULL) {
+        LV_LOG_WARN("Invalid parameters");
+        return;
+    }
+
+    dsc->min_value = min_value;
+    if(dsc->subject->type == LV_SUBJECT_TYPE_INT) {
+        if(dsc->subject->value.num < min_value) {
+            lv_subject_set_int(dsc->subject, min_value);
+        }
+    }
+#if LV_USE_FLOAT
+    else if(dsc->subject->type == LV_SUBJECT_TYPE_FLOAT) {
+        if(dsc->subject->value.float_v < (float)min_value) {
+            lv_subject_set_float(dsc->subject, (float)min_value);
+        }
+    }
+#endif
+}
+
+void lv_obj_set_subject_increment_event_max_value(lv_obj_t * obj, lv_subject_increment_dsc_t * dsc, int32_t max_value)
+{
+    LV_UNUSED(obj);
+    LV_ASSERT_NULL(dsc);
+    if(dsc == NULL) {
+        LV_LOG_WARN("Invalid parameters");
+        return;
+    }
+
+
+    dsc->max_value = max_value;
+    if(dsc->subject->type == LV_SUBJECT_TYPE_INT) {
+        if(dsc->subject->value.num > max_value) {
+            lv_subject_set_int(dsc->subject, max_value);
+        }
+    }
+#if LV_USE_FLOAT
+    else if(dsc->subject->type == LV_SUBJECT_TYPE_FLOAT) {
+        if(dsc->subject->value.float_v > (float)max_value) {
+            lv_subject_set_float(dsc->subject, (float)max_value);
+        }
+    }
+#endif
+}
+
+void lv_obj_set_subject_increment_event_rollover(lv_obj_t * obj, lv_subject_increment_dsc_t * dsc, bool rollover)
+{
+    LV_UNUSED(obj);
+    LV_ASSERT_NULL(dsc);
+    if(dsc == NULL) {
+        LV_LOG_WARN("Invalid parameters");
+        return;
+    }
+
+    dsc->rollover = rollover;
 }
 
 void lv_obj_add_subject_toggle_event(lv_obj_t * obj, lv_subject_t * subject, lv_event_code_t trigger)
@@ -849,43 +908,57 @@ static void subject_set_string_cb(lv_event_t * e)
 
 static void subject_increment_cb(lv_event_t * e)
 {
-    subject_increment_user_data_t * user_data = lv_event_get_user_data(e);
+    lv_subject_increment_dsc_t * user_data = lv_event_get_user_data(e);
 
     if(user_data->subject->type == LV_SUBJECT_TYPE_INT) {
+        /*Use the smaller range*/
+        int32_t max_value = LV_MIN(user_data->max_value, user_data->subject->max_value.num);
+        int32_t min_value = LV_MAX(user_data->min_value, user_data->subject->min_value.num);
+
         int32_t value = lv_subject_get_int(user_data->subject);
         value += user_data->step;
 
         if(user_data->rollover) {
-            if(value > user_data->subject->max_value.num) {
+            if(value > max_value) {
-                value = user_data->subject->min_value.num;
+                value = min_value;
             }
-            else if(value < user_data->subject->min_value.num) {
+            else if(value < min_value) {
-                value = user_data->subject->max_value.num;
+                value = max_value;
             }
         }
+        else {
+            value = LV_CLAMP(min_value, value, max_value);
+        }
 
         lv_subject_set_int(user_data->subject, value);
     }
 #if LV_USE_FLOAT
     else if(user_data->subject->type == LV_SUBJECT_TYPE_FLOAT) {
+        /*Use the smaller range*/
+        float max_value = LV_MIN((float)user_data->max_value, user_data->subject->max_value.float_v);
+        float min_value = LV_MAX((float)user_data->min_value, user_data->subject->min_value.float_v);
+
+
         float value = lv_subject_get_float(user_data->subject);
+        value += (float)user_data->step;
 
         if(user_data->rollover) {
-            if(value > user_data->subject->max_value.float_v) {
+            if(value > max_value) {
-                value = user_data->subject->min_value.float_v;
+                value = min_value;
             }
-            else if(value < user_data->subject->min_value.float_v) {
+            else if(value < min_value) {
-                value = user_data->subject->max_value.float_v;
+                value = max_value;
             }
         }
+        else {
+            value = LV_CLAMP(min_value, value, max_value);
+        }
 
-        value += (float)user_data->step;
         lv_subject_set_float(user_data->subject, value);
     }
 #endif
 }
 
-
 static void group_notify_cb(lv_observer_t * observer, lv_subject_t * subject)
 {
     LV_UNUSED(subject);

src/others/observer/lv_observer.h

@@ -379,19 +379,43 @@ void lv_subject_notify(lv_subject_t * subject);
  * @param subject   pointer to a subject to change
  * @param trigger   the trigger on which the subject should be changed
  * @param step      value to add on trigger
- * @param rollover  if true and the subject's maximum value is exceeded the minimum value is set,
  *                  if the minimum value is reached, the maximum value will be set on rollover.
  */
-void lv_obj_add_subject_increment_event(lv_obj_t * obj, lv_subject_t * subject, lv_event_code_t trigger, int32_t step,
+lv_subject_increment_dsc_t * lv_obj_add_subject_increment_event(lv_obj_t * obj, lv_subject_t * subject,
-                                        bool rollover);
+                                                                lv_event_code_t trigger, int32_t step);
 
 /**
- * Toggle the value of an integer subject on an event. If it was != 0 it will be 0.
+ * Set the minimum subject value to set by the event
- * If it was 0, it will be 1.
+ * @param obj           pointer to the Widget to which the event is attached
- * @param obj       pointer to a widget
+ * @param dsc           pointer to the descriptor returned by `lv_obj_add_subject_increment_event()`
- * @param subject   pointer to a subject to toggle
+ * @param min_value     the minimum value to set
- * @param trigger   the trigger on which the subject should be changed
  */
+void lv_obj_set_subject_increment_event_min_value(lv_obj_t * obj, lv_subject_increment_dsc_t * dsc, int32_t min_value);
+
+/**
+ * Set the maximum subject value to set by the event
+ * @param obj           pointer to the Widget to which the event is attached
+ * @param dsc           pointer to the descriptor returned by `lv_obj_add_subject_increment_event()`
+ * @param max_value     the maximum value to set
+ */
+void lv_obj_set_subject_increment_event_max_value(lv_obj_t * obj, lv_subject_increment_dsc_t * dsc, int32_t max_value);
+
+/**
+ * Set what to do when the min/max value is crossed.
+ * @param obj           pointer to the Widget to which the event is attached
+ * @param dsc           pointer to the descriptor returned by `lv_obj_add_subject_increment_event()`
+ * @param rollover      false: stop at the min/max value; true: jump to the other end
+ * @note                the subject also can have min/max values and always the smaller range will be considered
+ */
+void lv_obj_set_subject_increment_event_rollover(lv_obj_t * obj, lv_subject_increment_dsc_t * dsc, bool rollover);
+
+/**
+* Toggle the value of an integer subject on an event. If it was != 0 it will be 0.
+* If it was 0, it will be 1.
+* @param obj       pointer to a widget
+* @param subject   pointer to a subject to toggle
+* @param trigger   the trigger on which the subject should be changed
+*/
 void lv_obj_add_subject_toggle_event(lv_obj_t * obj, lv_subject_t * subject, lv_event_code_t trigger);
 
 /**

src/others/observer/lv_observer_private.h

@@ -39,6 +39,16 @@ struct _lv_observer_t {
     uint32_t for_obj : 1;               /**< Is `target` a pointer to a Widget (`lv_obj_t *`)? */
 };
 
+/**
+ * Descriptor created by `lv_obj_add_subject_increment_event()`
+ */
+struct _lv_subject_increment_dsc_t {
+    lv_subject_t * subject; /**< The subject to adjust*/
+    int32_t step;           /**< The step add to the subject */
+    bool rollover;          /**< Where to start over from the other end when one end is exceeded*/
+    int32_t min_value;      /**< Don't set a value smaller than this */
+    int32_t max_value;      /**< Don't set a value larger than this */
+};
 
 /**********************
  * GLOBAL PROTOTYPES

src/others/xml/parsers/lv_xml_obj_parser.c

@@ -404,6 +404,8 @@ void lv_obj_xml_subject_increment_apply(lv_xml_parser_state_t * state, const cha
     const char * subject_str =  lv_xml_get_value_of(attrs, "subject");
     const char * trigger_str =  lv_xml_get_value_of(attrs, "trigger");
     const char * step_str =  lv_xml_get_value_of(attrs, "step");
+    const char * min_value_str =  lv_xml_get_value_of(attrs, "min_value");
+    const char * max_value_str =  lv_xml_get_value_of(attrs, "max_value");
     const char * rollover_str =  lv_xml_get_value_of(attrs, "rollover");
 
     if(subject_str == NULL) {
@@ -435,8 +437,11 @@ void lv_obj_xml_subject_increment_apply(lv_xml_parser_state_t * state, const cha
     void * item = lv_xml_state_get_item(state);
 
     int32_t step = lv_xml_atoi(step_str);
-    bool rollover = lv_xml_to_bool(rollover_str);
+    lv_subject_increment_dsc_t * dsc = lv_obj_add_subject_increment_event(item, subject, trigger, step);
-    lv_obj_add_subject_increment_event(item, subject, trigger, step, rollover);
+
+    if(min_value_str) lv_obj_set_subject_increment_event_min_value(item, dsc, lv_xml_atoi(min_value_str));
+    if(max_value_str) lv_obj_set_subject_increment_event_max_value(item, dsc, lv_xml_atoi(max_value_str));
+    if(rollover_str) lv_obj_set_subject_increment_event_rollover(item, dsc, lv_xml_to_bool(rollover_str));
 }
 
 void * lv_obj_xml_bind_style_create(lv_xml_parser_state_t * state, const char ** attrs)

xmls/lv_obj.xml

@@ -113,33 +113,35 @@ Example
             <arg name="value" type="string" help="Value to assign"/>
         </element>
 
-        <element name="subject_increment_event" access="add" type="void">
+        <element name="subject_increment_event" access="add" type="lv_subject_increment_dsc">
             <arg name="subject" type="subject"/>
             <arg name="trigger" type="lv_event" default="clicked"/>
             <arg name="step" type="int" default="1"/>
-            <arg name="rollover" type="bool" default="false"/>
+            <prop name="rollover" type="bool"/>
+            <prop name="min_value" type="int"/>
+            <prop name="max_value" type="int"/>
         </element>
 
         <!-- Bind widget flags to subject values -->
-        <element name="bind_flag_if_eq" access="custom" type="void" help="Enable flag if subject's value is is equal to a refrence value">
+        <element name="bind_flag_if_eq" access="custom" type="void" help="Enable flag if subject's value is is equal to a reference value">
             <arg name="subject" type="subject" help="Subject to monitor"/>
             <arg name="flag" type="enum:lv_obj_flag" help="Flag to set/clear"/>
             <arg name="ref_value" type="int" help="Reference value"/>
         </element>
 
-        <element name="bind_flag_if_not_eq" access="custom" type="void" help="Enable flag if subject's value is not equal to a refrence value">
+        <element name="bind_flag_if_not_eq" access="custom" type="void" help="Enable flag if subject's value is not equal to a reference value">
             <arg name="subject" type="subject"/>
             <arg name="flag" type="enum:lv_obj_flag"/>
             <arg name="ref_value" type="int"/>
         </element>
 
-        <element name="bind_flag_if_gt" access="custom" type="void" help="Enable flag if subject's value is graeter than a refrence value">
+        <element name="bind_flag_if_gt" access="custom" type="void" help="Enable flag if subject's value is graeter than a reference value">
             <arg name="subject" type="subject"/>
             <arg name="flag" type="enum:lv_obj_flag"/>
             <arg name="ref_value" type="int"/>
         </element>
 
-        <element name="bind_flag_if_ge" access="custom" type="void" help="Enable flag if subject's value is greater or equal to a refrence value">
+        <element name="bind_flag_if_ge" access="custom" type="void" help="Enable flag if subject's value is greater than or equal to a reference value">
             <arg name="subject" type="subject"/>
             <arg name="flag" type="enum:lv_obj_flag"/>
             <arg name="ref_value" type="int"/>
@@ -151,7 +153,7 @@ Example
             <arg name="ref_value" type="int"/>
         </element>
 
-        <element name="bind_flag_if_le" access="custom" type="void" help="Enable flag if subject's value is less or equalt to a refrence value">
+        <element name="bind_flag_if_le" access="custom" type="void" help="Enable flag if subject's value is less than or equal to a reference value">
             <arg name="subject" type="subject"/>
             <arg name="flag" type="enum:lv_obj_flag"/>
             <arg name="ref_value" type="int"/>