From 81e99f46f1a97eba36ad5d42166f116ff5f34529 Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Wed, 24 Jul 2024 06:39:28 +0530 Subject: [PATCH] Clarify the semantics of close notification responses Also, simplify the escape code, not requiring an extra p value. Default to not responding. --- docs/desktop-notifications.rst | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/desktop-notifications.rst b/docs/desktop-notifications.rst index 3345fba4c..a94808f1f 100644 --- a/docs/desktop-notifications.rst +++ b/docs/desktop-notifications.rst @@ -103,17 +103,26 @@ To close a previous notification, send:: i= : p=close ; -This will close a previous notification with the specified id. If closing -succeeds, or the notification was already closed, -the terminal will send an escape code of the form:: +This will close a previous notification with the specified id. If you want a +notification when closing succeeds, send the following instead:: + + i= : p=close ; notify + +Then, the terminal will respond with:: i= : p=close ; -Closing is done on a best effort basis so applications must not rely on the -delivery of the closed escape code. If you do not want to receive an escape -code notifying you of closure, use:: +This escape code is sent by the terminal if the notification is closed +or was already closed when the close request arrives, or a notification +with the specified identifier does not exist. If the notification is activated, +before it can be closed, then the close response is sent only if the there is no +activation response. In other words, if you close a response and request +notification, you will get either of the following two responses:: + + i= : p=close ; # closed + + i= ; # activated - i= : p=close_simple ; Querying for support ------------------------- @@ -190,8 +199,7 @@ Key Value Default Description ``p`` One of ``title``, ``title`` Whether the payload is the notification title or body or query. If a ``body``, notification has no title, the body will be used as title. Terminal ``close``, emulators should ignore payloads of unknown type to allow for future - ``close_simple``, expansion of this protocol. - ``?`` + ``?`` expansion of this protocol. ``o`` One of ``always``, ``always`` When to honor the notification request. ``unfocused`` means when the window