From e45a0bc355a2a650d7e48774b3a4df89fd0a5297 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leonardo=20Hern=C3=A1ndez=20Hern=C3=A1ndez?= Date: Wed, 31 Jul 2024 01:47:03 -0600 Subject: [PATCH] document status output --- README.md | 2 +- dwl.1 | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 103 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1bcc36e..4bd4458 100644 --- a/README.md +++ b/README.md @@ -102,7 +102,7 @@ automatically, you will need to configure it prior to launching `dwl`, e.g.: Information about selected layouts, current window title, app-id, and selected/occupied/urgent tags is written to the stdin of the `-s` command (see -the `printstatus()` function for details). This information can be used to +the `STATUS INFORMATION` section in `dwl(1)`). This information can be used to populate an external status bar with a script that parses the information. Failing to read this information will cause dwl to block, so if you do want to run a startup command that does not consume the status information, diff --git a/dwl.1 b/dwl.1 index a98e476..5c09ce3 100644 --- a/dwl.1 +++ b/dwl.1 @@ -37,7 +37,7 @@ starts a shell process running when starting. When stopping, it sends .Dv SIGTERM -to the child process and waits for it to exit. +to the child process group and waits for it to exit. .Pp Users are encouraged to customize .Nm @@ -55,10 +55,10 @@ Move window to a single tag. Toggle tag for window. .It Mod-p Spawn -.Nm wmenu-run . +.Xr wmenu-run 1 . .It Mod-Shift-Return Spawn -.Nm foot . +.Xr foot 1 . .It Mod-[jk] Move focus down/up the stack. .It Mod-[id] @@ -108,6 +108,105 @@ Move focused window while dragging. Tiled windows will be toggled to the floatin Toggles focused window between floating and tiled state. .It Mod-Button3 Resize focused window while dragging. Tiled windows will be toggled to the floating state. +.Sh STATUS INFORMATION +.Nm +prints its status information to standard output. When the -s option is +given then the status information is printed to the standard input of the child +process. +.Pp +Said information has the following format: +.Bd -ragged -offset indent +.Aq Em monitor +.Aq Em component +.Aq Em data +.Ed +.Pp +.Bl -tag -width 11n -offset 0 -compact +.It Aq Em monitor +is the name given to the output. +.It Aq Em component +is one of (in order) +.Em title +.Em appid +.Em fullscreen +.Em floating +.Em selmon +.Em tags +.Em layout +\&. +.It Aq Em data +changes depending of +.Aq Em component +.Bl -tag -width fullscreen -compact +.It Em title +The title of the focused window on +.Aq Em monitor +or nothing if there is no focused window. +.It Em appid +The app_id of the focused window on +.Aq Em monitor +or nothing if there is no focused window. +.It Em fullscreen +Prints 1 if the focused window on +.Aq Em monitor +is in fullscreen state, otherwise prints 0. If there is no focused +window it prints nothing. +.It Em floating +Prints 1 if the focused window on +.Aq Em monitor +is in floating state, otherwise prints 0. If there is no focused +window it prints nothing. +.It Em selmon +Prints 1 if +.Aq Em monitor +is the selected monitor, otherwise prints 0. +.It Em tags +Prints four bitmasks in the following order: +.Bl -bullet -width 2n -compact +.It +Occupied tags of +.Aq Em monitor +\&. +.It +Selected tags of +.Aq Em monitor +\&. +.It +Tags of the focused window on +.Aq Em monitor +\&. +.It +Tags where a where a window on +.Aq Em monitor +requested activation or has urgency hints. +.El +The bitmasks are a 32-bit unsigned integer. +.It Em layout +Prints the symbol of the current layout. +.El +.El +.Ss Examples +When there is a selected window: +.Bd -literal -offset indent +HDMI-A-1 title ~/source/repos/dwl > man -l dwl.1 +HDMI-A-1 appid footclient +HDMI-A-1 fullscreen 0 +HDMI-A-1 floating 0 +HDMI-A-1 selmon 1 +HDMI-A-1 tags 271 4 4 0 +HDMI-A-1 layout [T] +.Ed +.Pp +When there is no selected window: +.Bd -literal -offset indent +HDMI-A-1 title +HDMI-A-1 appid +HDMI-A-1 fullscreen +HDMI-A-1 floating +HDMI-A-1 selmon 1 +HDMI-A-1 tags 271 512 0 0 +HDMI-A-1 layout [T] +.Ed .Sh ENVIRONMENT These environment variables are used by .Nm :