ba9df86472
main is a better term to use here for several reasons: 1. It is more accurate: "master" implies that the designated views have some kind of control over the other views, which is not the case. "main" better expresses that the difference between the "main" view and others is one of importance/focus. 2. It is a shorter word. 2 whole characters saved! 3. It reduces the chance of future development time being lost to good-intentioned people complaining about usage of the word master as has recently happened with regards to the default git branch name.
264 lines
8.8 KiB
Markdown
264 lines
8.8 KiB
Markdown
RIVERCTL(1) "github.com/ifreund/river" "General Commands Manual"
|
|
|
|
# NAME
|
|
|
|
riverctl - Command-line interface for controlling river
|
|
|
|
# SYNOPSIS
|
|
|
|
*riverctl* _command_ [_command specific arguments_]
|
|
|
|
# DESCRIPTION
|
|
|
|
*riverctl* is a command-line interface inspired by bspc from bspwm used to
|
|
control and configure river.
|
|
|
|
# COMMANDS
|
|
|
|
## ACTIONS
|
|
|
|
*close*
|
|
Close the focused view.
|
|
|
|
*csd-filter-add* _app-id_
|
|
Add an app-id to the CSD filter list. Windows with this app-id are
|
|
allowed to use client side decoration instead of the default server
|
|
side decoration.
|
|
|
|
*exit*
|
|
Exit the compositor, terminating the Wayland session.
|
|
|
|
*float-filter-add* _app-id_
|
|
Add an app-id to the float filter list. Windows with this app-id will
|
|
start floating.
|
|
|
|
*focus-output* *next*|*previous*
|
|
Focus next or previous output.
|
|
|
|
*focus-view* *next*|*previous*
|
|
Focus next or previous view in the stack.
|
|
|
|
*layout* *full*|_command_
|
|
Provide a command which river will use for generating the layout of
|
|
non-floating windows on the currently focused output. See
|
|
*river-layouts*(7) for details on the expected formatting of the output
|
|
of layout commands. Alternatively, “full” can be given instead of a
|
|
command to cause river to use its single internal layout, in which
|
|
windows span the entire width and height of the output.
|
|
|
|
*mod-main-count* _integer_
|
|
Increase or decrease the number of "main" views which is relayed to
|
|
the layout generator. _integer_ can be positive or negative. Exactly
|
|
how "main" views are display, or if they are even displayed differently
|
|
from other views, is left to the layout generator.
|
|
|
|
*mod-main-factor* _float_
|
|
Increase or decrease the "main factor" relayed to layout
|
|
generators. _float_ is a positive or negative floating point number
|
|
(such as 0.05). This value is added to the current main factor which
|
|
is then clamped to the range [0.0, 1.0]. The layout generator is
|
|
free to interpret this value as it sees fit, or ignore it entirely.
|
|
*rivertile*(1) uses this to determine what percentage of the screen
|
|
the "main" area will occupy.
|
|
|
|
*move* *up*|*down*|*left*|*right* _delta_
|
|
Move the focused view in the specified direction by _delta_. The view
|
|
will be set to floating.
|
|
|
|
*resize* *horizontal*|*vertical* _delta_
|
|
Resize the view in the given orientation by _delta_. The view will be
|
|
set to floating.
|
|
|
|
*snap* *up*|*down*|*left*|*right*
|
|
Snap the view to the specified screen edge. The view will be set to
|
|
floating.
|
|
|
|
*send-to-output* *next*|*previous*
|
|
Send the focused view to the next or the previous output.
|
|
|
|
*spawn* _shell_command_
|
|
Run _shell_command_ using _/bin/sh -c_. Put single quotes around
|
|
_shell_command_ if you do not want special characters to get
|
|
interpreted by your shell before the command gets passed to _/bin/sh_.
|
|
|
|
*swap* *next*|*previous*
|
|
Swap the focused window with the next/previous visible non-floating
|
|
window. When the focused view is the first view there is no previous
|
|
view. In this case *previous* swaps with the last view. *next* behaves
|
|
analogous.
|
|
|
|
*toggle-float*
|
|
If the focused view is floating, make it tiled. If it is tiled, make it
|
|
floating.
|
|
|
|
*toggle-fullscreen*
|
|
Toggle the fullscreen state of the focused view.
|
|
|
|
*zoom*
|
|
Bump the focused view to the top of the layout stack. If the top view
|
|
in the stack is already focused, bump the second view.
|
|
|
|
## TAG MANAGEMENT
|
|
|
|
Tags are similar to workspaces but more flexible. You can assign views multiple
|
|
tags and focus multiple tags simultaneously. Bitfields are used to describe
|
|
sets of tags when interfacing with river. As such, the following commands
|
|
take a normal base 10 number as their argument but the semantics are best
|
|
understood in binary. The binary number 000000001 represents a set containing
|
|
only tag 1 while 100001101 represents a set containing tags 1, 3, 4, and 9.
|
|
|
|
At least one tag must always be focused and each view must be assigned at
|
|
least one tag. Operations that would violate either of these requirements
|
|
are ignored by river.
|
|
|
|
*set-focused-tags* _tags_
|
|
Show views with tags corresponding to the set bits of _tags_ on the
|
|
currently focused output.
|
|
|
|
*set-view-tags* _tags_
|
|
Assign the currently focused view the tags corresponding to the set
|
|
bits of _tags_.
|
|
|
|
*toggle-focused-tags* _tags_
|
|
Toggle visibility of views with tags corresponding to the set bits
|
|
of _tags_ on the currently focused output.
|
|
|
|
*toggle-view-tags* _tags_
|
|
Toggle the tags of the currently focused view corresponding to the
|
|
set bits of _tags_.
|
|
|
|
## CONFIGURATION COMMANDS
|
|
|
|
*attach-mode* *top*|*bottom*
|
|
Configure where new views should attach in the view stack for the
|
|
currently focused output.
|
|
|
|
*background-color* _#RRGGBB_|_#RRGGBBAA_
|
|
Set the background color.
|
|
|
|
*border-color-focused* _#RRGGBB_|_#RRGGBBAA_
|
|
Set the border color of focused views.
|
|
|
|
*border-color-unfocused* _#RRGGBB_|_#RRGGBBAA_
|
|
Set the border color of unfocused views.
|
|
|
|
*border-width* _pixels_
|
|
Set the border width to _pixels_.
|
|
|
|
*declare-mode* _name_
|
|
Create a new mode called _name_ for use in mappings.
|
|
|
|
*enter-mode* _name_
|
|
Switch to given mode if it exits.
|
|
|
|
*focus-follows-cursor* *disabled*|*normal*|*strict*
|
|
When _disabled_ moving the cursor will not influence the focus. This is
|
|
the default setting. If set to _normal_ moving the cursor over a window
|
|
will focus that window. The focus still can be changed and moving the
|
|
cursor within the (now unfocused) window will not change the focus to
|
|
that window but let the currently focused window in focus. When set to
|
|
_strict_ this is not the case. The focus will be updated on every
|
|
cursor movement.
|
|
|
|
When the to be focused view is on another output than the currently
|
|
focused output the view's output is focused.
|
|
|
|
*map* [-release] _mode_ _modifiers_ _key_ _command_
|
|
_mode_ is either "normal" (the default mode), "locked" (the mode
|
|
entered when an input inhibitor such as a lock screen is active) or a
|
|
mode created with *declare-mode*. If _-release_ is specified the
|
|
mapping is executed on key release rather than key press. _modifiers_
|
|
is a list of one or more of the following modifiers separated with a
|
|
plus sign:
|
|
|
|
- Shift
|
|
- Lock (Caps lock)
|
|
- Control (Ctrl)
|
|
- Mod1 (Alt)
|
|
- Mod2
|
|
- Mod3
|
|
- Mod4 (Super, Logo, Windows)
|
|
- Mod5
|
|
|
|
_key_ is an XKB key name. See
|
|
_/usr/include/xkbcommon/xkbcommon-keysyms.h_ for a list of special key
|
|
names. _command_ can be any of the above commands.
|
|
|
|
A mapping without modifiers can be created by using "None" as sole
|
|
modifier.
|
|
|
|
*map-pointer* _mode_ _modifiers_ _button_ _action_
|
|
_mode_ and _modifiers_ are the same as for *map*.
|
|
|
|
_button_ is the name of a linux input event code. The most commonly
|
|
used values are:
|
|
|
|
- BTN_LEFT - left mouse button
|
|
- BTN_RIGHT - right mouse button
|
|
- BTN_MIDDLE - middle mouse button
|
|
|
|
A complete list may be found in _/usr/include/linux/input-event-codes.h_
|
|
|
|
_action_ is one of the following values:
|
|
|
|
- move-view
|
|
- resize-view
|
|
|
|
*opacity* _focused-opacity_ _unfocused-opacity_ _starting-opacity_ _opacity-step_ _opacity-delta-t_
|
|
Set the server side opacity of views.
|
|
|
|
_focused-opacity_ sets the opacity of the focused window,
|
|
_unfocused-opacity_ the opacity of every unfocused window while
|
|
_starting-opacity_ sets the opacity a window will have at startup
|
|
before immediately transitioning to either the focused or unfocused
|
|
opacity. These settings require a floating point number from 0.0 (fully
|
|
transparent) to 1.0 (fully opaque).
|
|
|
|
Opacity transitions can be animated. _opacity-step_ sets the amount the
|
|
opacity should be increased or decreased per step of the transition. It
|
|
requires a floating point number from 0.05 to 1.0. If set to 1.0,
|
|
animations are disabled. _opacity-delta-t_ sets the time between the
|
|
transition steps in milliseconds.
|
|
|
|
*outer-padding* _pixels_
|
|
Set the padding around the edge of the screen to _pixels_.
|
|
|
|
*set-repeat* _rate_ _delay_
|
|
Set the keyboard repeat rate to _rate_ key repeats per second and
|
|
repeat delay to _delay_ milliseconds.
|
|
|
|
*unmap* [-release] _mode_ _modifiers_ _key_
|
|
Removes the mapping defined by the arguments *-release*, *modifiers*
|
|
and *key* from *mode*. See *map* for an explanation of the arguments.
|
|
|
|
*unmap-pointer* _mode_ _modifiers_ _button_
|
|
Removes the mapping defined by the arguments *modifiers* and *button*
|
|
from *mode*. See *map-pointer* for an explanation of the arguments.
|
|
|
|
*view-padding* _pixels_
|
|
Set the padding around the edge of each view to _pixels_.
|
|
|
|
*xcursor-theme* _theme_name_ [_size_]
|
|
Set the xcursor theme to _theme_name_ and optionally set the _size_.
|
|
The theme of the default seat determines the default for XWayland and
|
|
made available through the _XCURSOR_THEME_ and _XCURSOR_SIZE_
|
|
environment variables.
|
|
|
|
# EXAMPLES
|
|
|
|
Bind bemenu-run to Super+P:
|
|
|
|
riverctl map normal Mod4 P spawn bemenu-run
|
|
|
|
See _contrib/config.sh_ for some basic keybindings.
|
|
|
|
# AUTHORS
|
|
|
|
Maintained by Isaac Freund <ifreund@ifreund.xyz> who is assisted by open
|
|
source contributors. For more information about river's development, see
|
|
<https://github.com/ifreund/river>.
|
|
|
|
# SEE ALSO
|
|
|
|
*river*(1), *river-layouts*(7), *rivertile*(1)
|