Add docs for ShowMode, Toggle widget and some micro changes

docs/how_are_messages_updated/example.py

@@ -0,0 +1,10 @@
+async def open_next_window(event, widget, manager: DialogManager):
+    manager.show_mode = ShowMode.SEND
+    await manager.next()
+
+
+async def switch_to_another_window(event, widget, manager: DialogManager):
+    await manager.switch_to(
+        state=SomeStatesSG.SomeState,
+        show_mode=ShowMode.SEND,
+    )

docs/how_are_messages_updated/index.rst

@@ -0,0 +1,17 @@
+How are messages updated
+=====================
+
+ShowMode
+********************
+
+Currently, to manage the update of the dialog, we use the feature called ShowMode.
+
+When we need to change show mode we can just use show_mode setter on DialogManager or pass it in DialogManager methods (.start, .update, .switch_to, etc.)
+
+.. literalinclude:: ./example.py
+
+.. important::
+
+    ShowMode changes only for the next update and then returns to AUTO mode.
+
+.. autoclass:: aiogram_dialog.api.entities.modes.ShowMode(Enum)

docs/index.rst

@@ -2,15 +2,17 @@ aiogram-dialog
 =============================================
 
 .. toctree::
-   :caption: Contents:
+    :maxdepth: 3
+    :caption: Contents:
 
-   overview/index
-   quickstart/index
-   widgets/index
-   transitions/index
-   helper_tools/index
-   migration
-   faq
+    overview/index
+    quickstart/index
+    widgets/index
+    transitions/index
+    how_are_messages_updated/index
+    helper_tools/index
+    migration
+    faq
 
 .. toctree::
     :hidden:

docs/widgets/index.rst

@@ -30,6 +30,8 @@ Also there are 2 general types:
   * ``hello world``, ``my:item``, ``птичка`` - invalid ids
 
 .. toctree::
+    :maxdepth: 1
+
     passing_data/index
     text/index
     keyboard/index

docs/widgets/keyboard/index.rst

@@ -17,7 +17,7 @@ Each keyboard provides one or multiple inline buttons. Text on button is rendere
 * :ref:`Select<select>` - dynamic group of buttons intended for selection use.
 * :ref:`Radio<radio>` - switch between multiple items. Like select but stores chosen item and renders it differently.
 * :ref:`Multiselect<multiselect>` - selection of multiple items. Like select/radio but stores all chosen items and renders them differently.
-* ``Toggle`` - to switch between elements of the list
+* :ref:`Toggle<toggle>` - to switch between elements of the list
 * :ref:`Calendar<calendar>` - simulates a calendar in the form of a keyboard.
 * :ref:`Counter<counter>` - couple of buttons +/- to input a number
 * :ref:`SwitchTo<switch_to>` - switches window within a dialog using provided state
@@ -40,6 +40,7 @@ Each keyboard provides one or multiple inline buttons. Text on button is rendere
     select/index
     radio/index
     multiselect/index
+    toggle/index
     calendar/index
     counter/index
     switch_to/index

docs/widgets/keyboard/toggle/example.py

@@ -0,0 +1,31 @@
+@dataclass
+class Fruit:
+    id: str
+    name: str
+    emoji: str
+
+
+async def get_fruits(**kwargs):
+    return {
+        "fruits": [
+            Fruit("apple_a", "Apple", "🍏"),
+            Fruit("banana_b", "Banana", "🍌"),
+            Fruit("orange_o", "Orange", "🍊"),
+            Fruit("pear_p", "Pear", "🍐"),
+        ],
+    }
+
+
+dialog = Dialog(
+    Window(
+        Const("Toggle widget"),
+        Toggle(
+            Format("{item.emoji} {item.name}"),
+            id="radio",
+            items="fruits",
+            item_id_getter=lambda fruit: fruit.id,
+        ),
+        state=ToggleExampleSG.START,
+        getter=get_fruits,
+    ),
+)

docs/widgets/keyboard/toggle/index.rst

@@ -0,0 +1,29 @@
+.. _toggle:
+
+Toggle
+*************
+
+**Toggle** is a button that switches between elements when clicked. Works like a :ref:`Radio<radio>`.
+
+Code example:
+
+.. literalinclude:: ./example.py
+
+Result:
+
+.. image:: /resources/toggle.gif
+
+Classes
+===========
+
+.. autoclass:: aiogram_dialog.widgets.kbd.select.OnItemStateChanged
+   :special-members: __call__
+
+.. autoclass:: aiogram_dialog.widgets.kbd.select.OnItemClick
+   :special-members: __call__
+
+.. autoclass:: aiogram_dialog.widgets.kbd.select.Toggle
+   :special-members: __init__,
+
+.. autoclass:: aiogram_dialog.widgets.kbd.ManagedToggle
+   :members: is_checked, get_checked, set_checked

src/aiogram_dialog/api/entities/modes.py

@@ -2,6 +2,31 @@
 
 
 class ShowMode(Enum):
+    """
+    Modes of show dialog message when new update handled.
+
+    AUTO:
+        default show mode.
+
+        Uses `SEND mode` when new message from user handled or `EDIT mode`
+        when any other updated handled.
+
+    EDIT:
+        edit dialog message
+
+    SEND:
+        send new dialog message
+
+    DELETE_AND_SEND:
+        delete and send new dialog message
+
+        `Attention`: Telegram's restrictions will prevent the deletion of the
+        message when more than 2 days has elapsed.
+
+    NO_UPDATE:
+        will not update and rerender the dialog message
+    """
+
     AUTO = "auto"
     EDIT = "edit"
     SEND = "send"