index.md - sites - public wiki contents of suckless.org
(HTM) git clone git://git.suckless.org/sites
(DIR) Log
(DIR) Files
(DIR) Refs
---
index.md (10038B)
---
1 # Dynamic, Command-Line Driven Window Swallowing for dwm
2
3 This patch introduces "dynamic" window swallowing to dwm. In contrast to the
4 mechanisms of the existing ("static") [swallow
5 patch](https://dwm.suckless.org/patches/swallow/), dynamic window swallowing is
6 run-time configurable and fully scriptable via `dwmswallow`, the command-line
7 tool included with this patch.
8
9 ## Download
10
11 - [dwm-dynamicswallow-20210221-61bb8b2.diff](dwm-dynamicswallow-20210221-61bb8b2.diff)
12 - [dwm-dynamicswallow-6.4.diff](dwm-dynamicswallow-6.4.diff)
13 - [dwm-dynamicswallow-20240320-061e9fe.diff](dwm-dynamicswallow-20240320-061e9fe.diff)
14
15 ## 1. Usage
16
17 Window swallowing is concerned with two scenarios: an existing window may
18 either swallow another existing window, or it may be registered to swallow
19 a future window.
20
21 ### 1.1 Swallowing Future Windows
22
23 Any window managed by dwm may be registered to swallow the next upcoming window
24 whose attributes match the class name, instance name and window title filters
25 using the command-line tool `dwmswallow`. Quoting from `dwmswallow -h`:
26
27 dwmswallow SWALLOWER [-c CLASS] [-i INSTANCE] [-t TITLE]
28 Register window SWALLOWER to swallow the next future window whose attributes
29 match the CLASS name, INSTANCE name and window TITLE filters using basic
30 string-matching. An omitted filter will match anything.
31
32 The next window whose filters match will be swallowed by SWALLOWER, taking its
33 place. See the following example in which a terminal launches the `surf`
34 browser and swallows its window, creating the impression of browsing the web
35 "inside" the terminal. Upon closing the browser the terminal reappears. Note
36 the symbol in the status bar next to the layout symbol while the swallow is
37 active.
38
39 
40
41 This example uses the WINDOWID environment variable to retrieve the terminal's
42 window id. Some terminals such as `st` or `kitty` export the variable, while
43 others such as `gnome-terminal` don't.
44
45 Note that swallowing is not at all restricted to terminals. Any two windows
46 managed by dwm may be involved. Also, window swallowing is agnostic towards
47 layouts, respects your usage of size hints and can be nested to arbitrary
48 depths.
49
50 ### 1.2 Swallowing Existing Windows
51
52 Swallowing of existing windows may be performed either from the command-line
53 (see `dwmswallow -h`) or using drag-and-drop via pointer (*mod+shift+button1*
54 by default).
55
56 See the following example in which a terminal is used to launch an application
57 whose stdout is considered important during its startup sequence. Once the
58 startup finishes without errors the stdout is of no interest anymore and the
59 terminal window is made to swallow the application window by drag-and-dropping
60 the latter onto the former.
61
62 
63
64 Afterwards, the terminal can be remapped at any time by stopping the swallow using
65 a hotkey (*mod+u* by default), which is not shown in the example.
66
67 ### 1.3 Shell Integration
68
69 When working in a terminal a shell alias can be used to express whether
70 a graphical application shall open in a separate window or "inside" the
71 terminal. Given `alias s='dwmswallow $WINDOWID;'` the command `s myguiprog`
72 will run the application and swallow its window. Note that this requires the
73 terminal to export the WINDOWID environment variable.
74
75 Alternatively, a shell hotkey may be configured to preface the execution of
76 a command with `dwmswallow $WINDOWID`. For example, the following zsh
77 configuration will cause an application to be swallowed by the terminal when
78 its command is submitted by pressing *CTRL-x + Enter* as opposed to pressing
79 only *Enter*.
80
81 # add to .zshrc
82 bindkey '^X^m' accept-line-swallow
83 zle -N accept-line-swallow acceptandswallow
84 acceptandswallow() {
85 dwmswallow $WINDOWID
86 zle accept-line
87 }
88
89 ## 2. Patching Instructions
90
91 Unless your fork of dwm is only slighly modified the adaptions to the patch
92 listed here may be necessary or appropriate to better fit in with your existing
93 build.
94
95 ### 2.1 Patch-Specific Geometry Parameters
96
97 When swallowing a window the swallowee copies the swallower's geometry
98 parameters to reposition itself to where the swallower used to be, creating the
99 impression of one window incorporating another. There exist patches which add
100 client-specific parameters that can modify a window's size or behavior. When
101 applying the dynamicswallow patch these parameters must be configured manually
102 in two places:
103
104 1. Inside `swal()`: during the swallowing of a window the swallowee shall
105 inherit a copy of the swallower's values of these parameters.
106 2. Inside `swalstop()`: when swallowing is stopped the swallower is remapped
107 and the parameters' defaults for its window have to be chosen.
108
109 As a representative example consider the
110 [cfacts](https://dwm.suckless.org/patches/cfacts/) patch which allows to
111 configure the relative sizes of windows in tiling mode using the
112 client-specific parameter `cfact` of type float. The two changes necessary to
113 accommodate this parameter are:
114
115 1. Inside `swal()`: `cfact` shall be copied from the swallower to the swallowee.
116
117 /* Configure geometry params obtained from patches (e.g. cfacts) here. */
118 swee->cfact = swer->cfact;
119
120 2. Inside `swalstop()`: the swallower's `cfact` shall be set to a sensible default.
121
122 /* Configure geometry params obtained from patches (e.g. cfacts) here. */
123 swer->cfact = 1.0;
124
125 The specific places of where to configure the parameters are marked with
126 comments included in the patch.
127
128 ### 2.2 Inter-Process Communication
129
130 In order for `dwmswallow` to communicate with dwm some means of inter-process
131 communication is required which dwm does not provide by default. To this end,
132 this patch includes an adaption of the
133 [fakesignal](https://dwm.suckless.org/patches/fsignal/) patch which allows
134 sending commands to dwm by concatenating the command and its parameters into
135 a specifically formatted string and making it the name of the root window.
136
137 The fakesignal patch is lightweight, non-intrusive, easy to use and easy to
138 extend to other commands. If your build does not include any IPC mechanisms
139 there's no reason to not use fakesignal as a starting point. Its only downside
140 is that the communication is unidirectional: one may send commands to dwm but
141 dwm cannot send a reply in return.
142
143 If your build of dwm does contain an IPC mechanism you may, of course, use your
144 existing communication pathways. While there's nothing wrong with using
145 fakesignal to try out the patch you will eventually want to seemlessly
146 integrate everything into your existing build. To achieve this you'll have to
147
148 1. relay the execution of `dwmswallow SWALLOWER SWALLOWEE` to a call to `swal()`.
149 2. relay the execution of `dwmswallow -c CLASS -i INSTANCE -t TITLE` to a call to `swalreg()`.
150 3. relay the execution of `dwmswallow -s` to a call to `swalstop()`.
151 4. relay the execution of `dwmswallow -d` to a call to `swalunreg()`.
152
153 using your IPC mechanism of choice.
154
155 ## 3. Assorted Notes and Implementation Details
156
157 Consult this section if you're interested in changing the default behavior or
158 if you're curious about the internals of the patch. The content herein is
159 presented in no particular order.
160
161 ### 3.1 Swallow Indicator in Status Bar
162
163 If the currently selected window on a monitor is being swallowed a
164 tongue-symbol 👅 (U+1F445) is drawn on the status bar next to the layout
165 symbol. If this is undesired remove the relevant commented section from
166 `drawbar()` or change the symbol in your *config.h*.
167
168 ### 3.2 Retroactive Swallowing
169
170 When registering the swallow of a future window using the window title as
171 filter the swallowing may fail for some applications if retroactive swallowing
172 is disabled (set by `swalretroactive`). This is due to the fact these
173 applications create their window using a default window title and only update
174 it later to the proper, usage-specific value. When dwm checks whether any
175 registed swallows match the window's title it finds that none do due to the
176 usage of the default window title when the window is mapped.
177
178 If retroactive swallowing is enabled each time a window changes its title dwm
179 checks whether a registered swallow instance matches the window and executes it
180 accordingly. If you find yourself wanting to filter by window title keep
181 retroactive swallowing enabled. While things are small, as they usually are,
182 the runtime costs are completely negligible.
183
184 An example of this is the PDF viewer zathura. Zathura's window title reflects
185 the currently viewed file and may be used to register swallows of PDF previews
186 filtered by filename. However, zathura's startup sequence exhibits the above
187 behavior and the window title is set to reflect the filename only after a
188 default window title has been used.
189
190 # This requires retroactive swallowing
191 dwmswallow $WINDOWID -c Zathura -t ~/books/xlib.pdf
192 zathura ~/books/xlib.pdf
193
194 ### 3.3 Decaying of Registered Swallows
195
196 It occasionally happens that swallows are registered but not consumed, either
197 due to misspelling the filters, causing them to never match or because the
198 user's intention has changed along the way. If `swaldecay` is set to a value
199 greater than zero any registered swallow instance is deleted if it hasn't been
200 consumed after so many new windows are mapped, i.e. after *swaldecay*
201 unsuccessful matches.
202
203 ### 3.4 `wintoclient()` vs `wintoclient2()`
204
205 Regular clients, swallowees and swallowers each require different handling by
206 dwm with respect to X request and notify events (map, unmap, delete, configure,
207 ...) for their respective windows.
208
209 In order to distinguish between the three classes of clients during runtime the
210 function `wintoclient2()` extends the functionality of the built-in
211 `wintoclient()`. In addition to retrieving the address of a window's client
212 from the window ID, it also returns the client type. It entails a change in
213 signature which is responsible for the majority of changes made by the patch
214 except for self-contained function definitions.
215
216 ## Author
217
218 - Stanislaw Hüll (hdstansen@gmail.com)
219