Update on_cleared event docs

Improve docs of the `ON_CLEARED` capability and update other docs to allow distinguishing between expired and programatically closed notifications in the future. Actually adding support for expiring notifications is out-of-scope here.

Author: PhrozenByte

README.md

@@ -82,18 +82,23 @@ async def main() -> None:
         buttons=[
             Button(
                 title="Mark as read",
-                on_pressed=lambda: print("Marked as read"),
-            )
+                on_pressed=lambda: print("Button 'Mark as read' was clicked"),
+            ),
+            Button(
+                title="Click me!!",
+                on_pressed=lambda: print("Button 'Click me!!' was clicked"),
+            ),
         ],
         reply_field=ReplyField(
-            on_replied=lambda text: print("Brutus replied:", text),
+            title="Reply",
+            button_title="Send",
+            on_replied=lambda text: print(f"Received reply '{text}'"),
         ),
-        on_dispatched=lambda: print("Notification showing"),
-        on_cleared=lambda: print("Notification timed out"),
-        on_clicked=lambda: print("Notification clicked"),
-        on_dismissed=lambda: print("Notification dismissed"),
+        on_dispatched=lambda: print("Notification is showing now"),
+        on_cleared=lambda: print("Notification was closed w/o user interaction"),
+        on_clicked=lambda: print("Notification was clicked"),
+        on_dismissed=lambda: print("Notification was dismissed by the user"),
         sound=DEFAULT_SOUND,
-        timeout=10,
     )
 
     # Run the event loop forever to respond to user interactions with the notification.

examples/eventloop.py

@@ -34,11 +34,10 @@ async def main() -> None:
             on_replied=lambda text: print(f"Received reply '{text}'"),
         ),
         on_dispatched=lambda: print("Notification is showing now"),
-        on_cleared=lambda: print("Notification timed out"),
+        on_cleared=lambda: print("Notification was closed w/o user interaction"),
         on_clicked=lambda: print("Notification was clicked"),
-        on_dismissed=lambda: print("Notification was dismissed"),
+        on_dismissed=lambda: print("Notification was dismissed by the user"),
         sound=DEFAULT_SOUND,
-        timeout=10,
     )
 
     # Run the event loop forever to respond to user interactions with the notification.

examples/eventloop_handlers.py

@@ -16,15 +16,15 @@ def on_dispatched(identifier: str) -> None:
 
 
 def on_cleared(identifier: str) -> None:
-    print(f"Notification '{identifier}' was cleared without user interaction")
+    print(f"Notification '{identifier}' was closed w/o user interaction")
 
 
 def on_clicked(identifier: str) -> None:
     print(f"Notification '{identifier}' was clicked")
 
 
 def on_dismissed(identifier: str) -> None:
-    print(f"Notification '{identifier}' was dismissed")
+    print(f"Notification '{identifier}' was dismissed by the user")
 
 
 def on_button_pressed(identifier: str, button_identifier: str) -> None:
@@ -57,7 +57,6 @@ async def main() -> None:
             button_title="Send",
         ),
         sound=DEFAULT_SOUND,
-        timeout=10,
     )
 
     # Run the event loop forever to respond to user interactions with the notification.

examples/synchronous.py

@@ -15,18 +15,21 @@
     buttons=[
         Button(
             title="Mark as read",
-            on_pressed=lambda: print("Marked as read"),
-        )
+            on_pressed=lambda: print("Button 'Mark as read' was clicked"),
+        ),
+        Button(
+            title="Click me!!",
+            on_pressed=lambda: print("Button 'Click me!!' was clicked"),
+        ),
     ],
     reply_field=ReplyField(
         title="Reply",
         button_title="Send",
-        on_replied=lambda text: print("Brutus replied:", text),
+        on_replied=lambda text: print(f"Received reply '{text}'"),
     ),
-    on_dispatched=lambda: print("Notification showing"),
-    on_cleared=lambda: print("Notification timed out"),
-    on_clicked=lambda: print("Notification clicked"),
-    on_dismissed=lambda: print("Notification dismissed"),
+    on_dispatched=lambda: print("Notification is showing now"),
+    on_cleared=lambda: print("Notification was closed w/o user interaction"),
+    on_clicked=lambda: print("Notification was clicked"),
+    on_dismissed=lambda: print("Notification was dismissed by the user"),
     sound=DEFAULT_SOUND,
-    timeout=10,
 )

src/desktop_notifier/common.py

@@ -304,8 +304,9 @@ class Capability(Enum):
     """Supports on-dispatched callbacks"""
 
     ON_CLEARED = auto()
-    """Supports distinguishing between an user closing a notification, and clearing a
-    notification programmatically, and consequently supports on-cleared callbacks"""
+    """Supports on-cleared callbacks, which are called if a notification wasn't
+    cleared by user interaction, but programmatically; platforms not supporting
+    this distinction will call on-dismissed callbacks instead"""
 
     ON_CLICKED = auto()
     """Supports on-clicked callbacks"""

src/desktop_notifier/main.py

@@ -300,7 +300,7 @@ def on_dispatched(self, handler: Callable[[str], Any] | None) -> None:
     def on_cleared(self) -> Callable[[str], Any] | None:
         """
         A method to call when a notification is cleared without user interaction
-        (e.g. after a timeout, or if cleared by another process)
+        (e.g. if cleared by another process)
 
         The method must take the notification identifier as a single argument.