aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorDaniel Eklöf <daniel@ekloef.se>2024-07-25 16:32:57 +0000
committerDaniel Eklöf <daniel@ekloef.se>2024-07-25 16:32:57 +0000
commita213e14ca35e73a1f353ae97f2e398d145e19f69 (patch)
treefb1624e20a7380b18621259d3c9d5913083176ac /doc
parentinput: allow mouse selections to start inside the margins (diff)
parentosc+notify: strcmp() -> streq() (diff)
Merge branch 'kitty-notifications'
Diffstat (limited to 'doc')
-rw-r--r--doc/foot-ctlseqs.7.scd7
-rw-r--r--doc/foot.ini.5.scd133
2 files changed, 110 insertions, 30 deletions
diff --git a/doc/foot-ctlseqs.7.scd b/doc/foot-ctlseqs.7.scd
index 5c611c92..998b6843 100644
--- a/doc/foot-ctlseqs.7.scd
+++ b/doc/foot-ctlseqs.7.scd
@@ -718,6 +718,10 @@ All _OSC_ sequences begin with *\\E]*, sometimes abbreviated _OSC_.
: Copy _Pd_ (base64 encoded text) to the clipboard. _Pc_ denotes the
target: *c* targets the clipboard and *s* and *p* the primary
selection.
+| \\E] 99 ; _params_ ; _payload_ \\E\\
+: kitty
+: Desktop notification; uses *desktop-notifications.command* in
+ *foot.ini*(5).
| \\E] 104 ; _c_ \\E\\
: xterm
: Reset color number _c_ (multiple semicolon separated _c_ values may
@@ -757,7 +761,8 @@ All _OSC_ sequences begin with *\\E]*, sometimes abbreviated _OSC_.
: Flash the entire terminal (foot extension)
| \\E] 777;notify;_title_;_msg_ \\E\\
: urxvt
-: Desktop notification, uses *notify* in *foot.ini*(5).
+: Desktop notification, uses *desktop-notifications.command* in
+ *foot.ini*(5).
# DCS
diff --git a/doc/foot.ini.5.scd b/doc/foot.ini.5.scd
index 680768e0..72e6d052 100644
--- a/doc/foot.ini.5.scd
+++ b/doc/foot.ini.5.scd
@@ -342,32 +342,6 @@ empty string to be set, but it must be quoted: *KEY=""*)
text. Note that whitespace characters are _always_ word
delimiters, regardless of this setting. Default: _,│`|:"'()[]{}<>_
-*notify*
- Command to execute to display a notification. _${title}_ and
- _${body}_ will be replaced with the notification's actual _title_
- and _body_ (message content).
-
- _${app-id}_ is replaced with the value of the command line option
- _--app-id_, and defaults to *foot* (normal mode), or
- *footclient* (server mode).
-
- _${window-title}_ is replaced with the current window title.
-
- Applications can trigger notifications in the following ways:
-
- - OSC 777: *\\e]777;notify;<title>;<body>\\e\\\\*
-
- By default, notifications are *inhibited* if the foot window
- has keyboard focus. See _notify-focus-inhibit_.
-
- Default: _notify-send -a ${app-id} -i ${app-id} ${title} ${body}_.
-
-*notify-focus-inhibit*
- Boolean. If enabled, foot will not display notifications if the
- terminal window has keyboard focus.
-
- Default: _yes_
-
*selection-target*
Clipboard target to automatically copy selected text to. One of
*none*, *primary*, *clipboard* or *both*. Default: _primary_.
@@ -426,10 +400,11 @@ Note: do not set *TERM* here; use the *term* option in the main
Default: _no_
*notify*
- When set to _yes_, foot will emit a desktop notification using
- the command specified in the *notify* option whenever *BEL* is
+ When set to _yes_, foot will emit a desktop notification using the
+ command specified in the *notify* option whenever *BEL* is
received. By default, bell notifications are shown only when the
- window does *not* have keyboard focus. See _notify-focus-inhibit_.
+ window does *not* have keyboard focus. See
+ _desktop-notifications.inhibit-when-focused_.
Default: _no_
@@ -445,6 +420,106 @@ Note: do not set *TERM* here; use the *term* option in the main
Whether to run the command on *BEL* even while focused. Default:
_no_
+# SECTION: desktop-notifications
+
+*command*
+ Command to execute to display a notification.
+
+ Template arguments
+ _${title}_ and _${body}_ will be replaced with the
+ notification's actual _title_ and _body_ (message content).
+
+ _${app-id}_ is replaced with the value of the command line
+ option _--app-id_, and defaults to *foot* (normal mode), or
+ *footclient* (server mode).
+
+ _${window-title}_ is replaced with the current window title.
+
+ _${icon}_ is replaced by the icon specified in the
+ notification request, or _${app_id}_ if the notification did
+ not set an icon. Note that only symbolic icon names are
+ supported, not filenames.
+
+ _${urgency}_ is replaced with the notifications urgency;
+ *low*, *normal* or *critical*.
+
+ Ways to trigger notifications
+ Applications can trigger notifications in the following ways:
+
+ - OSC 777: *\\e]777;notify;<title>;<body>\\e\\\\*
+ - OSC 99: *\\e]99;;<title>\\e\\\\* (this is just a bare bones
+ example; this protocol has lots of features, see
+ https://sw.kovidgoyal.net/kitty/desktop-notifications)
+
+ By default, notifications are *inhibited* if the foot window
+ has keyboard focus. See
+ _desktop-notifications.inhibit-when-focused_.
+
+ Window activation (focusing)
+ Foot can focus the window when the notification is
+ 'activated'. It can also send an event back to the client
+ application, notifying it that the notification has been
+ 'activated', This typically happens when the default action is
+ invoked, and/or when the notification is clicked, but exact
+ behavior depends on the notification daemon in use, and how it
+ has been configured.
+
+ For this to work, foot needs to know when the notification was
+ activated (as opposed to just dismissed), and it needs an XDG
+ activation token.
+
+ There are two parts to handle this. First, the notification
+ must define an action. For this purpose, foot definse the
+ template parameters *${action-name}* and
+ *${action-label}*. They are intended to be used with
+ e.g. notify-send's *-A,--action* option.
+
+ Second, foot needs to know when the notification activated,
+ and it needs to get hold of the XDG activation token.
+
+ Both are expected to be printed on stdout.
+
+ Foot expects the action name (not label) to be printed on a
+ single line. No prefix, no postfix.
+
+ Foot expects the activation token to be printed on a single
+ line, prefixed with *xdgtoken=*.
+
+ Example:
+ default
+ xdgtoken=18179adf579a7a904ce73754964b1ec3
+
+ The expected format of stdout may change at any time. Please
+ read the changelog when upgrading foot.
+
+ *Note*: notify-send does not, out of the box, support
+ reporting the XDG activation token in any way. This means
+ window activation will not work by default.
+
+ Stdout
+ Foot recognizes the following things from the notification
+ helper's stdout:
+
+ - _nnn_: integer in base 10, daemon assigned notification ID
+ - _id=nnn_: same as plain _nnn_.
+ - _default_: the 'default' action was triggered
+ - _action=default_: same as _default_
+ - _xdgtoken=xyz_: XDG activation token.
+
+ Example:
+ 17++
+action=default++
+xdgtoken=95ebdfe56e4f47ddb5bba9d7dc3a2c35
+
+ Default: _notify-send --wait --app-name ${app-id} --icon ${icon} --urgency ${urgency} --action ${action-name}=${action-label} --print-id -- ${title} ${body}_.
+
+
+*inhibit-when-focused*
+ Boolean. If enabled, foot will not display notifications if the
+ terminal window has keyboard focus.
+
+ Default: _yes_
+
# SECTION: scrollback
*lines*