leftwm(1)

📦
version 0.5.5 · 2 versions
, in nixpkgs unstable

💖 leftwm(1) — tiling window manager for adventurers 💖

okay so bestie, this is the manual page for leftwm(1), and it is literally giving main character energy for your desktop. no cap. 💅

🌸 NAME 🌸

LeftWM - A tiling window manager for adventurers. For more comprehensive documentation of leftwm please see: https://github.com/leftwm/leftwm/wiki

✨ SYNOPSIS ✨

leftwm [SUBCOMMAND]

💖 DESCRIPTION 💖

leftwm starts the left window manager on $DISPLAY. this will depend on your session manager, though it is recommended to start leftwm using exec-dbus-launch leftwm . — yes, that command also launches leftwm-worker and logs for errors to the console. the list of available subcommands available for leftwm is listed below:

🎀 SUBCOMMANDS 🎀

  • -h, --help — prints help information for this subcommand. This flag can also be used with other subcommands to display their own help message.
  • -v, --version — prints the version information.
  • -b, --backend — Specify the backend to use when starting LeftWM. Available backends depends on which feature flag was enables at compile time. You can check which backends are available on your LeftWM installation by using leftwm help backend.

Currently implemented backends: "xlib" (default), "x11rb"

  • check — This command will run several actions to ensure leftwm is configured properly. It will report the current leftwm version and git commit, it will also check if configuration is loaded correctly, check for syntax errors in your config.ron file, check your environment and theme files for errors as well.
NOTE: This subcommand will check for basic / common mistakes made in the directory structure or permissions, however it will not check or report if any mistakes were made in any extra scripts, bar configurations, liquid templates and anything that isn't the up or down executables.
  • command — This subcommand sends commands directly to leftwm. It can also be used to concat commands for a keybind in config.ron. For a list of available commands use the -l, --list flag.
  • state — Prints the current state of leftwm (in JSON format). You can also use flags and liqud-like syntax for a more refined output of this command. iykyk ✨
  • theme — Manage leftwm themes (This is part of an external package found in: https://GitHub.com/leftwm/leftwm-theme).
  • config — Manage leftwm configuration (This is part of an external package found in: https://GitHub.com/leftwm/leftwm-config).

🦋 CONFIGURING LEFTWM 🦋

NOTE: From 0.6.0, support for TOML was dropped in favor of RON as config language. Please use leftwm-config with the migrate command to convert your config. For more info please refer to the wiki.

🍓 Configuration file 🍓

The settings file of leftwm can be found at: $HOME/.config/leftwm/config.ron

With this file you can configure the modkey for leftwm, available keybinds, tag names, workspace layouts and more.

NOTE: This file is automatically generated when leftwm or leftwm-check is run for the first time.

🌈 Default keybinds 🌈

⭐ Movement ⭐

up, down, left or right refer to the arrow keys in your keyboard.

  • Mod + (1-9) — Switch to a desktop/tag
  • Mod + Shift + (1-9) — Move the focused window to desktop/tag
  • Mod + W — Switch the desktops for each screen. Desktops [1][2] changes to [2][1]
  • Mod + Shift + W — Move window to the other desktop
  • Mod + (up or down) — Focus on the different windows in the current workspace
  • Mod + Shift + (up or down) — Move the different windows in the current workspace
  • Mod + Enter — Move selected window to the top of the stack in the current workspace
  • Mod + Ctrl + (up or down) — Switch between different layouts
  • Mod + Shift + (left or right) — Switch between different workspaces
  • Mod + Shift + Enter — Open a terminal
  • Mod + Ctrl + L — Lock the screen
  • Mod + Shift + X — Exit LeftWM
  • Mod + Shift + Q — Close the current window
  • Mod + Shift + R — Reload LeftWM and its config
  • Mod + p — Use dmenu to start application

Note: Although we encourage you to use Alacritty, LeftWM will set your default terminal to the first terminal it finds in this list (in the order presented):

  • Alacritty
  • Termite
  • Kitty
  • URXVT
  • RXVT
  • ST
  • ROXTerm
  • Eterm
  • XTerm
  • Terminator
  • Terminology
  • Gnome Terminal
  • XFCE4 Terminal
  • Konsole
  • UXTerm
  • Guake

💅 About Keybind Modifiers 💅

Note: All entries require a modifier, even if blank: modifier: [] see your config.ron file for more information.

🧚 Floating Windows 🧚

You can optionally switch between tiling or floating mode for any window.

  • Mod + MouseDrag — Switch a tiled window to floating mode
  • Mod + RightMouseDrag — Resize a window
  • Drag window to a workspace edge — Switch a floating window to tiling mode

🔥 FloatingToTile 🔥

This behaviour snaps the currenly focused window into the workspace below.

👑 TileToFloating 👑

This behaviour switches the currently focused window to floating mode when it's tiled.

🎀 ToggleFloating 🎀

This behaviour switches the currenly focused window between floating and tiled mode. periodt. 💅

IMPORTANT: bestie, you literally have to reload before any of the changes you write into config.ron do anything. No reload, no slay. 😭
NOTE: as of 0.6.0, support for TOML got dropped in favour of RON as the config language. Please use leftwm-config with the migrate command to convert your config. For more info please refer to the wiki. 💖

🎀 Modkey

The modkey is the most important setting, full stop. Lots of the other settings use it and it controls how key bindings work:

Default: modkey = "Mod4" (windows key) 👑

🐭 Mousekey

The mousekey is similarly quite important. This value decides which key, when held, can assist a mouse drag in resizing or moving a floating window — or in making a window float or tile. It's giving co-pilot energy, honestly.

Default: mousekey = "Mod4" (windows key)

👀 Focus Behaviour

LeftWM has 3 focusing behaviours (Sloppy, ClickTo, and Driven) and 2 options (focus_new_windows, sloppy_mouse_follows_focus), which alter the way focus is handled. Together these encompass 5 different patterns:

  1. Sloppy Focus. Focus follows the mouse — hovering over a window brings it to focus. This behaviour has a variant, toggled with the sloppy_mouse_follows_focus option:
    • When true, the cursor will follow the focus and teleport to the window that takes focus. ✨
    • When false, the cursor isn't moved by LeftWM at all.
  2. Click-to-Focus. Focus follows the mouse, but only clicks change focus.
  3. Driven Focus. Focus disregards the mouse entirely; only keyboard actions drive the focus. keyboard main character energy fr.

Default:

focus_behaviour = "Sloppy" # Can be Sloppy, ClickTo, or Driven
focus_new_windows = true
sloppy_mouse_follows_focus = true # Only active with the Sloppy behaviour

🖱️ Cursor Behaviour on Resize

LeftWM automatically snaps the mouse to the nearest corner (or lower right on default) when a window is being resized. This behaviour is controlled by the disable_cursor_reposition_on_resize setting. When true, the cursor will not be repositioned on resize start. When false or unspecified, the cursor will be snapped to the nearest corner of the window which is being resized — or lower right if the nearest is multiple corners. 💅

Default: disable_cursor_reposition_on_resize = false

🪟 Dialog Position

LeftWM centers dialog windows by default while retaining the dimensions requested by the client. Set respect_dialog_position to true to also retain the position requested by dialog-like windows.

Default: respect_dialog_position = false

🌸 Window Creation and Cursor Focus

In multi-workspace layouts (such as with multiple monitors), LeftWM will, by default, create the new window on the workspace where the cursor is currently located — even if that workspace is not the workspace which is focused. In Click-to-Focus and Driven Focus modes, though, it is often desirable to create the window in the focused workspace, not the one wherein the mouse is located. The create_follows_cursor feature lets you change this behavior. New windows will be created in the workspace:

  • Containing the cursor when unset (None), Some(true), or when the cursor is in Sloppy mode 🖱️
  • Which is focused when set to Some(false)

Default: create_follows_cursor = None

🙈 Per-window New-window Mouse Warping

When Sloppy focus, focus_new_windows, and sloppy_mouse_follows_focus would normally move the pointer into a new window, a window rule can suppress that creation-time movement with disable_mouse_grab. This option controls pointer movement; it does not disable keyboard focus or mouse-button handling. important distinction, bestie 🫶

Example:

window_rules: [
    (window_class: "^pavucontrol$", disable_mouse_grab: true),
],

Windows of type _NET_WM_WINDOW_TYPE_UTILITY suppress the movement by default. A matching rule with disable_mouse_grab: false explicitly restores the normal behavior for a utility window.

🧚 Layouts

Leftwm supports a variety of user definable layouts. Layouts define the way that windows are tiled in the workspace. iconic behaviour, truly.

The layouts considered by leftwm can be customized in the config.ron file by editing the layouts and the layout_definitions entries.

The layouts in the layouts list are those accessible when switching layouts. For an example with a single layout:

layouts = [ "MyMainAndVertStack" ]

Each list in the layouts list must have a corresponding definition in the layout_definitions entry. For example:

layout_definitions = [(
  name: "MyMainAndVertStack",
  flip: None,
  rotate: North,
  reserve: ReserveAndCenter,
  columns: (
    flip: None,
    rotate: North,
    main: (count: 1, size: 0.8, flip: None, rotate: North, split: None),
    stack: (flip: None, rotate: North, split: Horizontal),
    second_stack: None,
  ),
)]

The size of the main area can be controlled with the IncreaseMainSize and DecreaseMainSize commands. 🎛️

There are various possiblities for the other parameters, and the user is referred to the default configuration file to see a large selection of examples. (go look, it's a whole mood board of layouts 💖)

🖥️ Workspaces

Workspaces are how you view tags (desktops). A workspace is an area on a screen — or most likely the whole screen. In these areas you can view a given tag.

Default: workspaces: [] (one workspace per screen)

Example (two workspaces on a single ultrawide):

workspaces: [
    ( y: 0, x: 0, height: 1440, width: 1720 ),
    ( y: 0, x: 1720, height: 1440, width: 1720 ),
],

Workspaces can also be applied to a specific screen by using the output field. If this field is used, all size-related fields get relative to the output's position. You can set multiple workspaces per screen. 🫶

If you only set per-screen workspaces, unassigned screens will be automatically given a workspace.

You can get the output names by running xrandr in your terminal.

Again the example for an ultra-wide screen, splitting workspaces by substracting half the width:

workspaces: [
    ( output: "HDMI-1", y: 0, x: 0, height: 1440, width: -1720 ),
    ( output: "HDMI-1", y: 0, x: 1720, height: 1440, width: -1720 ),
],

Workspaces can also be given their own list of layouts, which will override the global layouts list for that workspace only. 💫

Example:

workspaces: [
    ( output: "HDMI-1", y: 0, x: 0, height: 1440, width: 1720, layouts: [ "CenterMain", "MainAndVertStack", "MainAndDeck" ] ),
],

You can also set the default layout for a workspace by using the default_layout field — this sets the layout the workspace will start with.

Example (setting the default layout of workspace 1 to MainAndVertStack):

workspaces: [
    ( output: "HDMI-1", y: 0, x: 0, height: 1440, width: 1720, default_layout: "MainAndVertStack" ),
],

🏷️ Tags

Tags are the names of the virtual desktops where windows live. In other window managers these are sometimes just called desktops. You can rename them to any unicode string — including symbols/icons from popular icon libraries such as font-awesome. 🌈 go feral with the emoji tags, I support you.

Default: tags: ["1", "2", "3", "4", "5", "6", "7", "8", "9"]

🍓 Scratchpads

A scratchpad is a set of windows which you can call to any tag and hide when not needed. These windows can be any set of application which can be run from a terminal. To call a scratchpad you will require a keybind for ToggleScratchPad. When you want to manipulate the currently focused scratchpad, other commands like ReleaseScratchPad, AttachScratchPad and NextScratchPadWindow/PrevScratchPadWindow are available. 💅 it's giving secret stash energy.

Example:

scratchpad: [
    ( name: "Alacritty", // This is the name which is referenced when calling (case-sensitive)
      value: "alacritty", // The command to load the application if it isn't started (first application to start)
      args: ["-e", "python"], // Any arguments to pass to the command
      // x, y, width, height are in pixels when an integer is inputted or a percentage when a float is inputted.
      // These values are relative to the size of the workspace, and will be restricted depending on the workspace size.
      x: 860, y: 390, height: 300, width: 200
    ),
],

📚 WIKI

You can find more documentation in the LefrWM Wiki: https://github.com/leftwm/leftwm/wiki 🦋

🐛 BUGS

If you find any bugs or functionality issues please report them on Github: https://github.com/leftwm/leftwm/issues 🔥 (be nice, they're doing their best)

👑 AUTHORS

The LeftWM Development Team.

2021 - LeftWM

and that's the whole page bestie!! this cutie came out of the User Manuals corner of Gnu/Linux, filed as leftwm(1) — go forth and tile something iconic 💜✨

📦 where this page comes from