From d5efc54bec25d76eb82e3c984d7e761b2b93d074 Mon Sep 17 00:00:00 2001 From: Maurice Makaay Date: Tue, 10 May 2022 06:59:00 +0200 Subject: [PATCH] Documentation for number enhancement PR #3429 (#2049) Co-authored-by: Maurice Makaay Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/number/index.rst | 137 +++++++++++++++++++++++++++++++++++- guides/automations.rst | 2 +- 2 files changed, 136 insertions(+), 3 deletions(-) diff --git a/components/number/index.rst b/components/number/index.rst index aedf60267..d453ab706 100644 --- a/components/number/index.rst +++ b/components/number/index.rst @@ -164,6 +164,133 @@ Configuration variables: - **value** (**Required**, float, :ref:`templatable `): The value to set the number to. +.. _number-increment_action: + +``number.increment`` Action +*************************** + +This is an :ref:`Action ` for incrementing a number value by its +step size (default: 1). + +.. code-block:: yaml + + - number.increment: + id: my_number + cycle: false + + # Shorthand + - number.increment: my_number + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the number component to update. +- **cycle** (**Optional**, boolean): Whether or not to set the number to its minimum + value when the increment pushes the value beyond its maximum value. This will only + work when the number component uses a minimum and maximum value. + Defaults to ``true``. + +.. _number-decrement_action: + +``number.decrement`` Action +*************************** + +This is an :ref:`Action ` for decrementing a number value by its +step size (default: 1). + +.. code-block:: yaml + + - number.decrement: + id: my_number + cycle: false + + # Shorthand + - number.decrement: my_number + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the number component to update. +- **cycle** (**Optional**, boolean): Whether or not to set the number to its maximum + value when the decrement pushes the value below its minimum value. This will only + work when the number component uses a minimum and maximum value. + Defaults to ``true``. + +.. _number-to-min_action: + +``number.to_min`` Action +************************ + +This is an :ref:`Action ` seting a number to its minimum value, given +a number component that has a minimum value defined for it. + +.. code-block:: yaml + + - number.to_min: + id: my_number + + # Shorthand + - number.to_min: my_number + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the number component to update. + +.. _number-to-max_action: + +``number.to_max`` Action +************************ + +This is an :ref:`Action ` seting a number to its maximum value (given +a number component that has a maximum value defined for it. + +.. code-block:: yaml + + - number.to_max: + id: my_number + + # Shorthand + - number.to_max: my_number + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the number component to update. + +.. _number-operation_action: + +``number.operation`` Action +*************************** + +This is an :ref:`Action ` that can be used to perform an operation +on a number component (set to minimum or maximum value, decrement, increment), +using a generic templatable action call. + +.. code-block:: yaml + + # Using values + - number.operation: + id: my_number + operation: Increment + cycle: true + + # Or templated (lambda) + - number.operation: + id: my_number + operation: !lambda "return NUMBER_OP_INCREMENT;" + cycle: !lambda: "return true;" + +Configuration variables: + +- **id** (**Required**, :ref:`config-id`): The ID of the number to update. +- **operation** (**Required**, string, :ref:`templatable `): + What operation to perform on the number component. One of ``TO_MIN``, + ``TO_MAX``, ``DECREMENT`` or ``INCREMENT`` (case insensitive). When writing a + lambda for this field, then return one of the following enum values: + ``NUMBER_OP_TO_MIN``, ``NUMBER_OP_TO_MAX``, ``NUMBER_OP_DECREMENT`` or + ``NUMBER_OP_INCREMENT``. +- **cycle** (**Optional**, bool, :ref:`templatable `): + Can be used with ``DECREMENT`` or ``INCREMENT`` to specify whether or not to + wrap around the value when respectively the minimum or maximum value of the + number is exceeded. + .. _number-lambda_calls: lambda calls @@ -172,7 +299,7 @@ lambda calls From :ref:`lambdas `, you can call several methods on all numbers to do some advanced stuff (see the full API Reference for more info). -- ``make_call()``: Set the number value. +- ``.make_call()``: Make a call for updating the number value. .. code-block:: cpp @@ -181,6 +308,11 @@ advanced stuff (see the full API Reference for more info). call.set_value(42); call.perform(); + Check the API reference for information on the methods that are available for + the ``NumberCall`` object. You can for example also use ``call.to_min()`` + to set the number to its minimum value or ``call.increment(true)`` to increment + the number by its step size with the cycle feature enabled. + - ``.state``: Retrieve the current value of the number. Is ``NAN`` if no value has been read or set. .. code-block:: cpp @@ -191,7 +323,8 @@ advanced stuff (see the full API Reference for more info). See Also -------- -- :apiref:`number/number.h` +- :apiref:`Number ` +- :apiref:`NumberCall ` - :ghedit:`Edit` .. toctree:: diff --git a/guides/automations.rst b/guides/automations.rst index 58e96368b..b0d59a5cf 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -389,7 +389,7 @@ All Actions - :ref:`ds1307.read_time ` / :ref:`ds1307.write_time ` - :ref:`cs5460a.restart ` - :ref:`pzemac.reset_energy ` -- :ref:`number.set ` +- :ref:`number.set ` / :ref:`number.to_min ` / :ref:`number.to_max ` / :ref:`number.decrement ` / :ref:`number.increment ` / :ref:`number.operation ` - :ref:`select.set ` / :ref:`select.set_index ` / :ref:`select.first ` / :ref:`select.last ` / :ref:`select.previous ` / :ref:`select.next ` / :ref:`select.operation ` .. _config-condition: