swm

README (12948B)

---

 swm - Σ Window Manager
 ======================
 swm is [dwm](https://dwm.suckless.org) made less bare-boned and more
 customizable.
 
 
 Install & Run
 -------------
 libX11, libXft, and optionally libXinerama are required.  Edit config.mk
 to match your local setup, and then build and install swm with the
 following command (as root if necessary):
 
     make install
 
 The default installation directory is /usr/local/bin.
 
 You may add the following line to your .xinitrc to start swm using startx:
 
     exec swm
 
 But be warned that this new software might not yet be sufficiently
 crash-proof, so, for now, it's probably better to instead add something
 like this:
 
     swm || dwm
 
 This way a reliable window manager like dwm in this example can take
 over windows upon abnormal termination of swm.
 
 swm sends warnings and errors to stderr, so having its stderr logged
 might sometimes prove helpful.
 
 
 Quick Start
 -----------
 swm grabs any key with, by default, mod4 as a modifier, which is normally
 produced by the Super key.  This can be changed in config.h.  For the
 rest of the section Super is assumed to be the modifier key for swm.
 
 - Super+Enter: Spawn st, the suckless terminal.
 
 - Super+p: Launch other programs with dmenu.
 
 - Super+Backspace: Close the focused window.
 
 - Super+{j,k}: Focus the next/previous window.
 
 - Super+Shift+{j,k}: Shift the focused window.
 
 - Super+Space: Make the focused window the first.
 
 - Super+*n*: switch to the *n*th workspace.
 
 - Super+Shift+*n*: Tag the focused window with tag *n*; usually has the
   effect of sending the window to the *n*th workspace.
 
 - Super+{t,m}: Switch to the tiled (a.k.a. right stack) or monocle layout.
 
 - Super+y: Select from a list of layouts with dmenu; you can even make
   a new layout using this menu, but more on that later.
 
 - Super+{i,d}: Increase/Decrease the number of master area windows; if
   you don't already know the meaning, just try with a few windows in
   the default layout.
 
 - Super+{h,l}: Change the portion of master area.
 
 - Super+f: Toggle whether the focused window is fullscreen.
 
 - Super+Shift+{q,r}: Quit/Restart swm.
 
 If you use multiple monitors and don't disable Xinerama, these are
 also useful:
 
 - Super+], Super+[: Switch to the next/previous monitor.
 
 - Super+Shift+], Super+Shift+[: Send the focused window to the
   next/previous monitor.
 
 Using the mouse, you can press Super+Button1 to move a window and
 Super+Button3 to resize.  These will make the window floating.  You can
 press Super+Shift+Space to toggle the floating state of a window.
 
 More can be learnt from config.c.
 
 
 Configuration
 -------------
 config.c and config.h are provided for configuration.  Few options
 are contained in config.h, and everything else, including key bindings
 and colors etc. belong to config.c, a small separate compilation unit.
 This way rebuilding swm after changing key bindings etc. is much more
 efficient compared to dwm where changing any configuration requires
 recompilation of the whole program.
 
 Unlike dwm, key bindings are defined directly inside the key event
 handler, and mouse button bindings inside the button event handler,
 instead of arrays searched by the handlers.  This different approach is
 taken for greater flexibility.
 
 With keybindings defined directly in a function, it's complicated for swm
 to grab exactly the keys and buttons that are bound like dwm does, so,
 to be simple, swm grabs any key or button with the configured modifier,
 but this prevents the modifier from being shared with other graphical
 programs.  This issue is discussed next.
 
 
 Tips about Modifier Keys
 ------------------------
 The Alt key is probably the handiest modifier key on a typical keyboard,
 but using it with swm will prevent other graphical program from using it.
 You may do just that and live with the exclusiveness, or you may stick
 with using Super, which is generally not used by other graphical programs,
 if you don't mind the relative inconvenience; these are the two obvious
 options.  But here is a recommended third way: Turn Caps Lock into Super.
 
 You can turn Caps Lock into Super with this command:
 
     xmodmap -e 'remove Lock = Caps_Lock' \
             -e 'keysym Caps_Lock = Super_L Caps_Lock'
 
 This will still allow toggling all-caps by pressing Shift+Caps_Lock.
 Put the command in .xinitrc to automate it.
 
 If you also would like to use Caps Lock for Escape (sweet for vi users),
 do the two usages conflict?  They don't have to, with the help of
 [xcape](https://github.com/alols/xcape).  The following will make Caps
 Lock, now a surrogate Super key, function as Escape when pressed and
 released on its own:
 
     xcape -e Super_L=Escape
 
 xcape should be run after the xmodmap command.
 
 If xcape is used with xmodmap as described above, Shift+Caps_Lock will
 generate an Escape besides toggling all-caps.  You can fix that little
 problem by changing the xmodmap command above to this:
 
     xmodmap -e 'remove Lock = Caps_Lock' \
             -e 'keysym Caps_Lock = Super_L' \
             -e 'keysym Escape = Escape Caps_Lock'
 
 Be aware that there is a small issue with using Caps Lock as Super: Some
 keyboards have a problem with certain modifier combinations when using
 such a surrogate Super key.  So you might find it necessary to resort to
 the original Super key for, e.g., Super+Shift+2.  Modifier combinations
 are typically easier with the original Super key, anyway.
 
 
 Workspaces & Tags
 -----------------
 There are as many workspaces as there are tags.  You can select one
 workspace at a time, which contains a separate layout and a separate
 set of tags.  Every window can be assigned one or more tags just like
 in dwm, and a workspace's tag set is used to match windows by tags.
 Windows matched by the tag set of a workspace belong, non-exclusively,
 to the workspace.
 
 To compare, dwm has one layout and one tag set per (logical) monitor,
 and what feels sort of like switching between workspaces in dwm is
 actually setting the tag set to comprise only a specific tag.  You can
 put multiple tags in the tag set, but the selected tags are easily
 lost during switching between tags, making selecting multiple tags a
 less usable feature.  Besides, this design makes things like one layout
 "per tag" not quite well-defined.  So swm slightly enhanced the design to
 address these problems.  Initially, the tag set of each workspace contains
 a single tag that has the same index as the workspace, making selecting
 a workspace in swm works much like viewing a specific tag in dwm.
 
 The array of tags displayed on the status bar is dually used for tags
 and workspaces.  The current workspace is indicated by a bold underline,
 and the tag set of the workspace and tags of windows are indicated in
 the same way as indicated in dwm: Tags in the current tag set are colored
 differently, and tags that are applied to one or more windows are marked,
 in their upper left corner, by a little square, which is filled if the
 tag is applied to the focused window and empty otherwise.
 
 
 Restarting
 ----------
 Taking the dwm approach, you have to rebuild and restart swm for new
 configurations to take effect.  By default you can press Super+Shift+r
 to restart swm.  During restarting, swm executes the command that starts
 it and uses environment variables (later cleared by the new instance)
 to pass down certain runtime information, including:
 
 - The monitor each client belongs to
 - Order of clients in each monitor
 - Tags and state (floating/fullscreen/scratchpad) of each client
 - Tag set and layout in each workspace of each monitor
 - Whether gaps and bar are shown in each monitor
 - Each monitor's current workspace
 - The focused client
 
 These help provide a seamless transition and make reconfiguration like
 a breeze.
 
 
 Status Program
 --------------
 swm runs a status program configured in config.c and uses pipes to connect
 to the status program's input and output.  Every time the status program
 outputs a line, the line is taken as the new status text and displayed on
 the status bar.  swm talks to the status program by writing to its input.
 
 This is quite different from how dwm handles status.  dwm reads the
 WM_NAME property of the root window for status text.  This simplifies the
 window manager's main loop, but makes it uneasy for the window manager
 to talk to the status program, adds a little burden to the status program
 and is less efficient.
 
 swm recognizes status text as blocks separated by two or more consecutive
 spaces.  When a block displayed on the status bar is clicked, swm's
 button event handler by default writes to the status program a line
 indicating which block is clicked (1 for the rightmost, 2 for the second
 rightmost, etc.), which button is pressed, and which modifiers are on.
 Details of what gets written can be found or changed in config.c.
 
 The status program can be toggled on and off with Super+Shift+s by
 default.  Pressing the key twice has the effect of restarting the status
 program.  By turning the status program off, swm doesn't directly kill
 it but closes the pipe to its input, and the status program is expected
 to detect this condition.
 
 The status program that swm by default is configured to use is
 [infobar](https://wolog.xyz/repos/infobar).
 
 
 Scratchpads
 -----------
 Scratchpads are windows, typically floating and centered, that can be
 handily brought into and out of view.  In swm, any window can be marked
 a scratchpad.  Here are the related default key bindings:
 
 - `Super+'`: Toggle a scratchpad.  If visible scratchpads are present,
   the topmost is hidden; otherwise, the topmost hidden scratchpad
   (normally the most recently used) is brought into view.  If there is
   no scratchpad at all, a scratchpad terminal is launched.
 
 - `Super+.`: Cycle through all hidden scratchpads.  If the focused window
   is a scratchpad, it gets replaced by the next hidden scratchpad, if
   any; otherwise this just brings a hidden scratchpad, if there is one,
   into view.
 
 - Super+Shift+Enter: Launch the scratchpad terminal.
 
 - Super+<backtick>: Toggle whether a window is a scratchpad or not.
   A floating window gets centered when turned into a scratchpad.
 
 The basic usage is simply to toggle a scratchpad terminal on and off
 by pressing `Super+'`, but you're offered convenience to develop more
 sophisticated usages.
 
 
 Layout Description Language
 ---------------------------
 The layout description language is a tiny language invented for
 specification of layouts in swm.  Most layouts that can be found in
 dwm and its patches can be described quite well in this language. Here
 are examples:
 
 - Right stack (the default tiled layout):
 
     [*]:.55 []
 
 - Monocle:
 
     ()
 
 - Deck:
 
     [*]:.55 ()
 
 - Bottom stack:
 
     [{*}:.55 {}]
 
 - Fibonacci spiral:
 
     .62 [.62 -{.62 [.62 ()]}]
 
 - Fibonacci dwindle:
 
     .62 [.62 {.62 [.62 ()]}]
 
 (The last two examples are not actually exact, as the actual layouts
 described will tile the 5th and subsequent windows in the monocle manner.)
 
 dwm's notions of master number and master factor are defined more
 generically in swm.  Generally, changing them in swm works the way most
 dwm users would expect.
 
 The language is simple enough that you can probably gain intuition
 from the examples and then figure it out by experimenting (see the next
 section for an easy method).
 
 
 dmenu Integration
 -----------------
 First of all, in case you only think of dmenu as a fuzzy single-item
 selector: You can pick multiple items, and even pick an item multiple
 times, with Ctrl+Enter while navigating the menu using Ctrl+{n,p}; you
 can also use dmenu as an input box, where Tab can be used to copy an
 item, a bit of line editing capability is available, and the input can
 be confirmed by pressing Shift+Enter.
 
 In swm, by default, pressing Super+y runs dmenu to give you a menu of
 layout descriptions to choose from, where you may also write an ad-hoc
 layout or tweak an existing one.
 
 swm provides four types of gaps (internal/outer, horizontal/vertical) that
 are separately settable.  Pressing Super+g gives you a menu of options for
 setting or changing the values of them, where making good use of dmenu
 will enable you to easily tune them. (But if you just want to toggle
 gaps off, press Super+Shift+g, and if you want to increase or decrease
 all gaps, scroll up and down with your mouse while holding Super.)
 
 vanitygaps, a dwm patch, offers a number of layouts with gaps, but to
 fully utilize what it offers, a user would need to bind eight keys each for
 choosing one layout and bind eight keys for increasing and decreasing the
 four types of gaps.  This is a waste of spare keys given the infrequency
 of most of the actions, and even that doesn't provide as much freedom as
 swm does.  So swm's menus serve to help out such situations by combining
 many infrequent actions into few menus and allowing doing things more
 sophisticated in case of need.
 
 You can easily construct such menus in config.c using convenience
 functions provided; see config.c for examples.