X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=README.md;h=f2472ae6de33cb23beb44208014fba0f32aad04a;hb=bd6877370cc7f50f33b7a49ccaea8c912f73ad73;hp=259b4ae3ab5d68475be8833b09be1dd682b60c57;hpb=42f50c36feb854a260c8a08e40affa043e81c6eb;p=bspwm.git diff --git a/README.md b/README.md index 259b4ae..f2472ae 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,26 @@ -![logo](https://github.com/baskerville/bspwm/raw/master/resources/bspwm_logo.png) +![logo](https://github.com/baskerville/bspwm/raw/master/logo/bspwm-logo.png) + +## Synopsis + + bspwm [-v|-s STATUS_FIFO] + + bspc MESSAGE [ARGUMENTS] [OPTIONS] ## Description -`bspwm` is a tiling window manager based on binary space partitioning. +`bspwm` is a tiling window manager where each window is represented as the leaf of a binary tree. -The windows are represented as the leaves of a binary tree. +It is controlled and configured via `bspc`. ## Configuration `bspwm` have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket. -Those messages are sent through the `bspc` program. +Its configuration file is `$XDG_CONFIG_HOME/bspwm/autostart`. -If the `BSPWM_SOCKET` environment variable is defined it will be used as the socket path, otherwise `/tmp/bspwm-socket` is used. +The recommended way of defining keyboard shortcuts is to use [sxhkd](https://github.com/baskerville/sxhkd). -The recommended way of defining keyboard shortcuts, is to use `xbindkeys`. - -Configuration files (`bspwmrc` and `autostart`) must be placed in `$XDG_CONFIG_HOME/bspwm/`. - -Example configurations: [bspwmrc](https://github.com/baskerville/dotfiles/blob/master/bspwmrc), [autostart](https://github.com/baskerville/bin/blob/master/bspwm_autostart) and [xbindkeysrc](https://github.com/baskerville/dotfiles/blob/master/xbindkeysrc) +Example configuration files can be found in the `examples` directory. ## Splitting Modes @@ -26,8 +28,8 @@ There is only two splitting modes: *automatic* and *manual*. The default mode is *automatic*. The *manual* mode is entered by sending a *presel* message. - Example: insertion of a new node (number 4) into the given tree in - *automatic* mode: +Example: insertion of a new node (number 4) into the given tree in +*automatic* mode: b c / \ / \ @@ -46,8 +48,8 @@ The default mode is *automatic*. The *manual* mode is entered by sending a *pres | | | | | | | +-------------------------+ +-------------------------+ - Same departure, but the mode is *manual*, a `presel up` message - was sent beforehand: +Same departure, but the mode is *manual*, and a `presel up` message +was sent beforehand: b b / \ / \ @@ -67,175 +69,192 @@ The default mode is *automatic*. The *manual* mode is entered by sending a *pres ## Messages -The syntax for the client is `bspc COMMAND ARGUMENTS...`. +The syntax for the client is `bspc MESSAGE [ARGUMENTS ...]`. The following messages are handled: - quit - Quit. +- `get SETTING` — Return the value of the given setting. + +- `set SETTING VALUE` — Set the value of the given setting. + +- `list [DESKTOP_NAME]` — Output the internal representation of the window tree. + +- `list_desktops [--quiet]` — Perform a dump of each desktop for the current monitor. + +- `list_monitors [--quiet]` — Perform a dump of each monitor. + +- `list_windows` — Return the list of managed windows (i.e. their identifiers). + +- `list_rules` — Return the list of rules. + +- `presel left|right|up|down [SPLIT_RATIO]` — Switch to manual mode and select the splitting direction. + +- `cancel` — Switch to automatic mode. + +- `ratio VALUE` — Set the splitting ratio of the focused window. + +- `pad MONITOR_NAME [TOP_PADDING [RIGHT_PADDING [BOTTOM_PADDING [LEFT_PADDING]]]]` — Set the padding of the given monitor. + +- `focus left|right|up|down` — Focus the neighbor window situated in the given direction. + +- `shift left|right|up|down` — Exchange the current window with the given neighbor. + +- `swap` — Swap the focused window with the last focused window. + +- `push left|right|up|down` — Push the fence located in the given direction. + +- `pull left|right|up|down` — Pull the fence located in the given direction. + +- `cycle next|prev [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]` — Focus the next or previous window matching the given constraints. - get SETTING - Return the value of the given setting. +- `nearest older|newer [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ]` — Focus the nearest window matching the given constraints. - set SETTING VALUE - Set the value of the given setting. +- `circulate forward|backward` — Circulate the leaves in the given direction. - dump - Output the internal representation of the window tree. +- `grab_pointer focus|move|resize_side|resize_corner` — Begin the specified pointer action. - list - Perform a dump of each desktop. +- `track_pointer ROOT_X ROOT_Y` — Pass the pointer root coordinates for the current pointer action. - windows - Return the list of managed windows (i.e. their identifiers). +- `ungrab_pointer` — End the current pointer action. - close - Close the focused window. +- `toggle_fullscreen` — Toggle the fullscreen state of the current window. - presel DIR - Switch to manual mode and select the splitting direction. +- `toggle_floating` — Toggle the floating state of the current window. - ratio VALUE - Set the splitting ratio of the focused window. +- `toggle_locked` — Toggle the locked state of the current window (locked windows will not respond to the `close` message). - cancel - Switch to automatic mode. +- `toggle_visibility` — Toggle the visibility of all the managed windows. - focus DIR - Focus the neighbor node situated in the given direction. +- `close` — Close the focused window. - shift DIR - Focus the neighbor node situated in the given direction. +- `kill` — Kill the focused window. - push DIR - Push the fence located in the given direction. +- `send_to DESKTOP_NAME [--follow]` — Send the focused window to the given desktop. - pull DIR - Pull the fence located in the given direction. +- `drop_to next|prev [--follow]` — Send the focused window to the next or previous desktop. - cycle CYC [--skip-floating|--skip-tiled|--skip-class-equal|--skip-class-differ] - Focus the next or previous window in the list of leaves. +- `send_to_monitor MONITOR_NAME [--follow]` — Send the focused window to the given monitor. - rotate ROT - Rotate the tree of the current desktop. +- `drop_to_monitor next|prev [--follow]` — Send the focused window to the next or previous monitor. - magnetise COR - Move all the fences toward the given corner. +- `use DESKTOP_NAME` — Select the given desktop. - send_to DESKTOP_NAME - Send the focused window to the given desktop. +- `use_monitor MONITOR_NAME` — Select the given monitor. - use DESKTOP_NAME - Select the given desktop. - - alternate - Alternate between the current and the last focused desktop. +- `alternate` — Alternate between the current and the last focused window. - add DESKTOP_NAME - Make a new desktop with the given name. +- `alternate_desktop` — Alternate between the current and the last focused desktop. - rename CURRENT_NAME NEW_NAME - Rename the desktop named CURRENT_NAME to NEW_NAME. +- `alternate_monitor` — Alternate between the current and the last focused monitor. - cycle_desktop CYC - Select the next or previous desktop. - - layout LYT - Set the layout of the current desktop to LYT. +- `add DESKTOP_NAME ...` — Make new desktops with the given names. - toggle_fullscreen - Toggle the fullscreen state of the current window. +- `add_in MONITOR_NAME DESKTOP_NAME ...` — Make new desktops with the given names in the given monitor. - toggle_floating - Toggle the floating state of the current window. +- `rename_monitor CURRENT_NAME NEW_NAME` — Rename the monitor named `CURRENT_NAME` to `NEW_NAME`. - toggle_locked - Toggle the locked state of the current window (locked windows will not respond to the 'close' command). +- `rename CURRENT_NAME NEW_NAME` — Rename the desktop named `CURRENT_NAME` to `NEW_NAME`. - rule PATTERN floating - Make a new rule that will floats the windows whose class name or instance name matches PATTERN. +- `cycle_monitor next|prev` — Select the next or previous monitor. - reload_autostart - Reload the autostart file. +- `cycle_desktop next|prev [--skip-free|--skip-occupied]` — Select the next or previous desktop. - reload_settings - Reload the settings file. +- `layout monocle|tiled [DESKTOP_NAME ...]` — Set the layout of the given desktops (current if none given). - reload - Reload the autostart and the settings file. +- `cycle_layout` — Cycle the layout of the current desktop. -Where +- `rotate clockwise|counter_clockwise|full_cycle` — Rotate the window tree. - DIR = left|right|up|down - CYC = next|prev - ROT = clockwise|counter_clockwise|full_cycle - COR = top_left|top_right|bottom_left|bottom_right - LYT = monocle|tiled +- `flip horizontal|vertical` — Flip the window tree. + +- `balance` — Adjust the split ratios so that all windows occupy the same area. + +- `rule PATTERN [DESKTOP_NAME] [floating] [follow]` — Create a new rule (`PATTERN` must match the class or instance name). + +- `remove_rule UID ...` — Remove the rules with the given UIDs. + +- `adopt_orphans` — Manage all the unmanaged windows remaining from a previous session. + +- `restore FILE_PATH` — Restore the layout of each desktop from the content of `FILE_PATH`. + +- `quit [EXIT_STATUS]` — Quit. ## Settings -Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or '#RRGGBB'. +Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names) or *#RRGGBB*, booleans are *true* or *false*. + +- `focused_border_color` — Color of the border of a focused window of a focused monitor. + +- `active_border_color` — Color of the border of a focused window of an unfocused monitor. + +- `normal_border_color` — Color of the border of an unfocused window. + +- `presel_border_color` — Color of the `presel` message feedback. - active_border_color - Color of the main border of a focused window. +- `focused_locked_border_color` — Color of the border of a focused locked window of a focused monitor. - normal_border_color - Color of the main border of an unfocused window. - - inner_border_color - Color of the inner border of a window. +- `active_locked_border_color` — Color of the border of a focused locked window of an unfocused monitor. - outer_border_color - Color of the outer border of a window. - - presel_border_color - Color of the *presel* message feedback. +- `normal_locked_border_color` — Color of the border of an unfocused locked window. - active_locked_border_color - Color of the main border of a focused locked window. +- `urgent_border_color` — Color of the border of an urgent window. - normal_locked_border_color - Color of the main border of an unfocused locked window. +- `border_width` — Window border width. - urgent_border_color - Color of the border of an urgent window. +- `window_gap` — Value of the gap that separates windows. - inner_border_width - main_border_width - outer_border_width - Width of the inner, main and outer borders. +- `{top,right,bottom,left}_padding` — Padding space added at the sides of the current monitor. - window_gap - Value of the gap that separates windows. +- `wm_name` — The value that shall be used for the `_NET_WM_NAME` property of the root window. - top_padding - bottom_padding - left_padding - right_padding - Padding space added at the sides of the screen. +- `borderless_monocle` — Whether to remove borders for tiled windows in monocle mode. - wm_name - The value that shall be used for the _NET_WM_NAME property of the root window. +- `gapless_monocle` — Whether to remove gaps for tiled windows in monocle mode. -## Mouse Bindings +- `focus_follows_pointer` — Wether to focus the window under the pointer. - M4 + Left Button - Move the window under the pointer. +- `adaptative_raise` — Prevent floating windows from being raised when they might cover other floating windows. - M4 + Middle Button - Focus the window under the pointer. +- `apply_shadow_property` — Enable shadows for floating windows via the `_COMPTON_SHADOW` property. - M4 + Middle Button - Resize the window under the pointer (by moving one of its four corners). +## Environment Variables -Where *M4* is the fourth modifier mask (generally bound to *Super*). +- `BSPWM_SOCKET` — The path of the socket used for the communication between `bspc` and `bspwm`. + +## Key Features + +- Configured and controlled through messages. +- Multiple monitors support (via *Xinerama*). +- EWMH support (`tint2` works). +- Automatic and manual modes. + +## Panels + +- Any EWMH compliant panel (e.g. `tint2`, `bmpanel2`, etc.). +- A custom panel if the `-s` flag is used (have a look at the files in `examples/panel`). +- `dzen2` fed with the output of `ewmhstatus`. Example: [launchpanel](https://github.com/baskerville/bin/blob/master/launchpanel). ## Required Libraries: -libxcb, xcb-util-wm, lua. +- libxcb +- xcb-util +- xcb-util-wm ## Installation make make install +## Contributors + +- [Ivan Kanakarakis](https://github.com/c00kiemon5ter) + +- [Thomas Adam](https://github.com/ThomasAdam) + +## Mailing List + +bspwm *at* librelist *dot* com. + +## License + +BSD.