871fc7c8de
This protocol involves far too much accidental complexity. The original motivating use-case was to provide a convenient way to send arbitrary data to layout clients at runtime in order to avoid layout clients needing to implement their own IPC and do this over a side-channel. Instead of implementing a quite complex but still rigid options protocol and storing this state in the compositor, instead we will simply add events to the layout protocol to support this use case. Consider the status quo event sequence: 1. send get_option_handle request (riverctl) 2. roundtrip waiting for first event (riverctl) 3. send set_foo_value request (riverctl) 4. receive set_foo_value request (river) 5. send foo_value event to all current handles (river) 6. receive foo_value event (rivertile) 7. send parameters_changed request (rivertile) 8. receive parameters_changed request (river) 9. send layout_demand (river) And compare with the event sequence after the proposed change: 1. send set_foo_value request (riverctl) 2. receive set_foo_value request (river) 3. send set_foo_value event (river) 4. send layout_demand (river) This requires *much* less back and forth between the server and clients and is clearly much simpler.
278 lines
9.1 KiB
Markdown
278 lines
9.1 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 utility used to control and configure river
|
|
over the Wayland protocol.
|
|
|
|
# COMMANDS
|
|
|
|
## ACTIONS
|
|
|
|
*close*
|
|
Close the focused view.
|
|
|
|
*csd-filter-add* _app-id_
|
|
Add _app-id_ to the CSD filter list. Views with this _app-id_ are
|
|
told 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 _app-id_ to the float filter list. Views with this _app-id_
|
|
will start floating.
|
|
|
|
*focus-output* *next*|*previous*
|
|
Focus the next or previous output.
|
|
|
|
*focus-view* *next*|*previous*
|
|
Focus the next or previous view in the stack.
|
|
|
|
*move* *up*|*down*|*left*|*right* _delta_
|
|
Move the focused view in the specified direction by _delta_ logical
|
|
pixels. The view will be set to floating.
|
|
|
|
*resize* *horizontal*|*vertical* _delta_
|
|
Resize the focused view along the given axis by _delta_ logical
|
|
pixels. The view will be set to floating.
|
|
|
|
*snap* *up*|*down*|*left*|*right*
|
|
Snap the focused 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 view with the next/previous visible non-floating
|
|
view. If the first/last view in the stack is focused, wrap.
|
|
|
|
*toggle-float*
|
|
Toggle the floating state of the focused view.
|
|
|
|
*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.
|
|
|
|
*default-layout* _namespace_
|
|
Set the layout namespace to be used by all outputs by default.
|
|
|
|
*output-layout* _namespace_
|
|
Set the layout namespace of currently focused output, overriding
|
|
the value set with *default-layout* if any.
|
|
|
|
## 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.
|
|
|
|
When a view spawns it is assigned the currently focused tags of the output.
|
|
|
|
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_.
|
|
|
|
*spawn-tagmask* _tagmask_
|
|
Set a _tagmask_ to filter the tags assigned to newly spawned views
|
|
on the focused output. This mask will be applied to the tags of
|
|
new views with a bitwise and. If, for example, the tags 000011111
|
|
are focused on an output with a _tagmask_ of 111110001, a new view
|
|
will be assigned the tags 000010001. If no tags would remain after
|
|
filtering, the _tagmask_ is ignored.
|
|
|
|
## MAPPINGS
|
|
|
|
Mappings are modal in river. Each mapping is associated with a mode and is
|
|
only active while in that mode. There are two special modes: "default" and
|
|
"locked". The default mode is the initial mode for every seat. The locked
|
|
mode is automatically entered while an input inhibitor (such as a lockscreen)
|
|
is active. It cannot be left or entered manually.
|
|
|
|
The following modifiers are available for use in mappings:
|
|
|
|
- Shift
|
|
- Lock (Caps lock)
|
|
- Control (Ctrl)
|
|
- Mod1 (Alt)
|
|
- Mod2
|
|
- Mod3
|
|
- Mod4 (Super, Logo, Windows)
|
|
- Mod5
|
|
- None (Create a mapping without modifiers)
|
|
|
|
Keys are specified by their XKB keysym name. See
|
|
_/usr/include/xkbcommon/xkbcommon-keysyms.h_ for the complete list.
|
|
|
|
Mouse buttons are specified by linux input event code names. 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_
|
|
|
|
*declare-mode* _name_
|
|
Create a new mode called _name_.
|
|
|
|
*enter-mode* _name_
|
|
Switch to given mode if it exists.
|
|
|
|
*map* [_-release_] _mode_ _modifiers_ _key_ _command_
|
|
Run _command_ when _key_ is pressed while _modifiers_ are held down
|
|
and in the specified _mode_.
|
|
|
|
- _-release_: if passed activate on key release instead of key press
|
|
- _mode_: name of the mode for which to create the mapping
|
|
- _modifiers_: one or more of the modifiers listed above, separated
|
|
by a plus sign (+).
|
|
- _key_: an XKB keysym name as described above
|
|
- _command_: any command that may be run with riverctl
|
|
|
|
*map-pointer* _mode_ _modifiers_ _button_ _action_
|
|
Move or resize views when _button_ and _modifiers_ are held down
|
|
while in the specified _mode_.
|
|
|
|
- _mode_: name of the mode for which to create the mapping
|
|
- _modifiers_: one or more of the modifiers listed above, separated
|
|
by a plus sign (+).
|
|
- _button_: the name of a linux input event code as described above
|
|
- _action_: one of the following values:
|
|
- move-view
|
|
- resize-view
|
|
|
|
*unmap* [_-release_] _mode_ _modifiers_ _key_
|
|
Remove the mapping defined by the arguments:
|
|
|
|
- _-release_: if passed unmap the key release instead of the key press
|
|
- _mode_: name of the mode for which to remove the mapping
|
|
- _modifiers_: one or more of the modifiers listed above, separated
|
|
by a plus sign (+).
|
|
- _key_: an XKB keysym name as described above
|
|
|
|
*unmap-pointer* _mode_ _modifiers_ _button_
|
|
Remove the pointer mapping defined by the arguments:
|
|
|
|
- _mode_: name of the mode for which to remove the mapping
|
|
- _modifiers_: one or more of the modifiers listed above, separated
|
|
by a plus sign (+).
|
|
- _button_: the name of a linux input event code as described above
|
|
|
|
## CONFIGURATION
|
|
|
|
*attach-mode* *top*|*bottom*
|
|
Configure where new views should attach to 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_.
|
|
|
|
*focus-follows-cursor* *disabled*|*normal*|*strict*
|
|
There are three available modes:
|
|
|
|
- _disabled_: Moving the cursor does not affect focus. This is
|
|
the default
|
|
- _normal_: Moving the cursor over a view will focus that view.
|
|
Moving the cursor within a view will not re-focus that view if
|
|
focus has moved elsewhere.
|
|
- _strict_: Moving the cursor over a view or within a view will
|
|
focus that view.
|
|
|
|
If the view to be focused is on an output that does not have focus,
|
|
focus is switched to that output.
|
|
|
|
*opacity* _focused_ _unfocused_ _initial_ _step-size_ _delta-t_
|
|
Configure server-side opacity of views, including transition
|
|
animations. A value of 0.0 is fully transparent while 1.0 is fully
|
|
opaque. By default all views are fully opaque and there are no
|
|
animations.
|
|
|
|
- _focused_: opacity of focused views [0.0, 1.0]
|
|
- _unfocused_: opacity of unfocused views [0.0, 1.0]
|
|
- _initial_: opacity of views when they are created before immediately
|
|
transitioning to either _focused_ or _unfocused_ [0.0, 1.0]
|
|
- _step-size_: opacity change per step [0.05, 1.0]
|
|
- _delta-t_: step time in milliseconds
|
|
|
|
A transition animation may occur when changing between states with
|
|
different opacity values configured. Instead of setting the view's
|
|
opacity to the value for the new state immediately, it is changed
|
|
incrementally in steps of _step-size_ every _delta-t_ milliseconds.
|
|
Setting _step-size_ to 1.0 disables transitions fully regardless of
|
|
the value of _delta-t_.
|
|
|
|
*set-repeat* _rate_ _delay_
|
|
Set the keyboard repeat rate to _rate_ key repeats per second and
|
|
repeat delay to _delay_ milliseconds.
|
|
|
|
*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 is made available through the _XCURSOR_THEME_ and _XCURSOR_SIZE_
|
|
environment variables.
|
|
|
|
# EXAMPLES
|
|
|
|
Bind bemenu-run to Super+P in normal mode:
|
|
|
|
riverctl map normal Mod4 P spawn bemenu-run
|
|
|
|
See also the example init script at /etc/river/init.
|
|
|
|
# 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), *rivertile*(1)
|