Nulo/river
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
river/doc/riverctl.1.scd

264 lines
8.8 KiB
Text
Raw Normal View History

docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
RIVERCTL(1) "github.com/ifreund/river" "General Commands Manual"
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
# NAME
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
riverctl - Command-line interface for controlling river
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
# SYNOPSIS
doc: shorten riverctl’s synopsis The set-option command got removed but was still present in SYNOPSIS, which confused me. It is not the first time, we forgot to update it.
2020-08-01 07:37:14 +00:00
*riverctl* _command_ [_command specific arguments_]
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
# DESCRIPTION
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
*riverctl* is a command-line interface inspired by bspc from bspwm used to
control and configure river.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
# COMMANDS
## ACTIONS
*close*
Close the focused view.
Implement csd-filter-add and float-filter-add commands
2020-07-16 17:45:45 +00:00
*csd-filter-add* _app-id_
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
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.
Implement csd-filter-add and float-filter-add commands
2020-07-16 17:45:45 +00:00
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
*exit*
Exit the compositor, terminating the Wayland session.
Implement csd-filter-add and float-filter-add commands
2020-07-16 17:45:45 +00:00
*float-filter-add* _app-id_
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
Add an app-id to the float filter list. Windows with this app-id will
start floating.
Implement csd-filter-add and float-filter-add commands
2020-07-16 17:45:45 +00:00
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
*focus-output* *next*|*previous*
Focus next or previous output.
*focus-view* *next*|*previous*
Focus next or previous view in the stack.
Doc: Add layout documentation
2020-06-13 12:43:12 +00:00
*layout* *full*|_command_
Provide a command which river will use for generating the layout of
non-floating windows on the currently focused output. See
docs: small man pages fixes and updates - Previous hard-coded settings can be now be changes with riverctl or via environment variables - Update "See also" - Mod → Mod1
2020-06-17 08:39:48 +00:00
*river-layouts*(7) for details on the expected formatting of the output
of layout commands. Alternatively, “full” can be given instead of a
Doc: Add layout documentation
2020-06-13 12:43:12 +00:00
command to cause river to use its single internal layout, in which
windows span the entire width and height of the output.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
command: s/master/main/g (breaking change) 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.
2020-12-30 17:15:47 +00:00
*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.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
Implement "move", "snap" and "resize" commands
2020-10-07 01:00:57 +00:00
*move* *up*|*down*|*left*|*right* _delta_
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
Move the focused view in the specified direction by _delta_. The view
will be set to floating.
Implement "move", "snap" and "resize" commands
2020-10-07 01:00:57 +00:00
*resize* *horizontal*|*vertical* _delta_
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
Resize the view in the given orientation by _delta_. The view will be
set to floating.
Implement "move", "snap" and "resize" commands
2020-10-07 01:00:57 +00:00
*snap* *up*|*down*|*left*|*right*
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
Snap the view to the specified screen edge. The view will be set to
floating.
Implement "move", "snap" and "resize" commands
2020-10-07 01:00:57 +00:00
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
*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_.
control: implement swap
2020-10-25 11:41:19 +00:00
*swap* *next*|*previous*
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
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.
control: implement swap
2020-10-25 11:41:19 +00:00
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
*toggle-float*
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
If the focused view is floating, make it tiled. If it is tiled, make it
floating.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
docs: add toggle-fullscreen
2020-06-28 23:50:26 +00:00
*toggle-fullscreen*
Toggle the fullscreen state of the focused view.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
*zoom*
command: s/master/main/g (breaking change) 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.
2020-12-30 17:15:47 +00:00
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.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
docs: improve explanation of tags "tagmask" is a misleading term as the arguments are used much more like a set of tags than a mask.
2020-12-30 13:25:37 +00:00
## TAG MANAGEMENT
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
docs: improve explanation of tags "tagmask" is a misleading term as the arguments are used much more like a set of tags than a mask.
2020-12-30 13:25:37 +00:00
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.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
docs: improve explanation of tags "tagmask" is a misleading term as the arguments are used much more like a set of tags than a mask.
2020-12-30 13:25:37 +00:00
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.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
docs: improve explanation of tags "tagmask" is a misleading term as the arguments are used much more like a set of tags than a mask.
2020-12-30 13:25:37 +00:00
*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_.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
docs: improve explanation of tags "tagmask" is a misleading term as the arguments are used much more like a set of tags than a mask.
2020-12-30 13:25:37 +00:00
*toggle-focused-tags* _tags_
Toggle visibility of views with tags corresponding to the set bits
of _tags_ on the currently focused output.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
docs: improve explanation of tags "tagmask" is a misleading term as the arguments are used much more like a set of tags than a mask.
2020-12-30 13:25:37 +00:00
*toggle-view-tags* _tags_
Toggle the tags of the currently focused view corresponding to the
set bits of _tags_.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
## CONFIGURATION COMMANDS
Implement "attach-mode"
2020-08-17 21:13:16 +00:00
*attach-mode* *top*|*bottom*
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
Configure where new views should attach in the view stack for the
currently focused output.
Implement "attach-mode"
2020-08-17 21:13:16 +00:00
command: split set-option into "toplevel" commands `riverctl set-option view_padding 10` becomes `riverctl view-padding 10` Having set-option doesn't really gain us anything and is more verbose as well as being slightly inaccurate as the changes instantly apply.
2020-07-15 10:42:20 +00:00
*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_.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
*declare-mode* _name_
Create a new mode called _name_ for use in mappings.
*enter-mode* _name_
Switch to given mode if it exits.
docs: focus-follows-cursor fix options to be bold
2020-09-15 15:29:34 +00:00
*focus-follows-cursor* *disabled*|*normal*|*strict*
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
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.
Implement focus-follows-cursor
2020-09-14 22:38:50 +00:00
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
When the to be focused view is on another output than the currently
focused output the view's output is focused.
focus-follow-cursor: Change output focus when needed
2020-12-07 12:51:06 +00:00
Implement map -release
2020-09-15 11:46:08 +00:00
*map* [-release] _mode_ _modifiers_ _key_ _command_
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
_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:
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
- Shift
- Lock (Caps lock)
- Control (Ctrl)
docs: small man pages fixes and updates - Previous hard-coded settings can be now be changes with riverctl or via environment variables - Update "See also" - Mod → Mod1
2020-06-17 08:39:48 +00:00
- Mod1 (Alt)
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
- Mod2
- Mod3
- Mod4 (Super, Logo, Windows)
- Mod5
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
_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.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
A mapping without modifiers can be created by using "None" as sole
modifier.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
config: implement map-pointer command This command takes a mode, modifiers, button/event name, and pointer action as arguments. It stores these in the config data structure. The currently available pointer actions are move-view and resize-view, which replace the previously hard-coded functionality. Closing the hovered view with middle click has temorarily been removed until it is decided if we wish to make this another special pointer action or perhaps allow running any arbitrary command (which would of course include close).
2020-08-24 12:52:47 +00:00
*map-pointer* _mode_ _modifiers_ _button_ _action_
_mode_ and _modifiers_ are the same as for *map*.
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
_button_ is the name of a linux input event code. The most commonly
used values are:
config: implement map-pointer command This command takes a mode, modifiers, button/event name, and pointer action as arguments. It stores these in the config data structure. The currently available pointer actions are move-view and resize-view, which replace the previously hard-coded functionality. Closing the hovered view with middle click has temorarily been removed until it is decided if we wish to make this another special pointer action or perhaps allow running any arbitrary command (which would of course include close).
2020-08-24 12:52:47 +00:00
- 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
Implement configurable view opacity with fade effect
2020-10-03 20:09:15 +00:00
*opacity* _focused-opacity_ _unfocused-opacity_ _starting-opacity_ _opacity-step_ _opacity-delta-t_
Set the server side opacity of views.
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
_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).
Implement configurable view opacity with fade effect
2020-10-03 20:09:15 +00:00
Opacity transitions can be animated. _opacity-step_ sets the amount the
opacity should be increased or decreased per step of the transition. It
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
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.
Implement configurable view opacity with fade effect
2020-10-03 20:09:15 +00:00
command: split set-option into "toplevel" commands `riverctl set-option view_padding 10` becomes `riverctl view-padding 10` Having set-option doesn't really gain us anything and is more verbose as well as being slightly inaccurate as the changes instantly apply.
2020-07-15 10:42:20 +00:00
*outer-padding* _pixels_
Set the padding around the edge of the screen to _pixels_.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
control: implement set-repeat
2020-11-18 14:28:33 +00:00
*set-repeat* _rate_ _delay_
Set the keyboard repeat rate to _rate_ key repeats per second and
repeat delay to _delay_ milliseconds.
Implement unmap
2020-10-23 22:59:40 +00:00
*unmap* [-release] _mode_ _modifiers_ _key_
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
Removes the mapping defined by the arguments *-release*, *modifiers*
and *key* from *mode*. See *map* for an explanation of the arguments.
Implement unmap
2020-10-23 22:59:40 +00:00
Implement unmap-pointer
2020-10-24 07:19:51 +00:00
*unmap-pointer* _mode_ _modifiers_ _button_
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
Removes the mapping defined by the arguments *modifiers* and *button*
from *mode*. See *map-pointer* for an explanation of the arguments.
Implement unmap-pointer
2020-10-24 07:19:51 +00:00
command: split set-option into "toplevel" commands `riverctl set-option view_padding 10` becomes `riverctl view-padding 10` Having set-option doesn't really gain us anything and is more verbose as well as being slightly inaccurate as the changes instantly apply.
2020-07-15 10:42:20 +00:00
*view-padding* _pixels_
Set the padding around the edge of each view to _pixels_.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
cursor: make xcursor theme configurable - add a new command to set the theme - export the theme of the default seat through environment variables
2020-07-14 15:34:29 +00:00
*xcursor-theme* _theme_name_ [_size_]
doc: unify scdoc style This unifies the style of the man page source files. Most noticable are the now consistent line endings at 80 chars (assuming a tabwidth of 8).
2020-12-12 23:51:51 +00:00
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.
cursor: make xcursor theme configurable - add a new command to set the theme - export the theme of the default seat through environment variables
2020-07-14 15:34:29 +00:00
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
# EXAMPLES
Bind bemenu-run to Super+P:
riverctl map normal Mod4 P spawn bemenu-run
See _contrib/config.sh_ for some basic keybindings.
doc: add AUTHORS section to man pages
2020-11-11 19:44:41 +00:00
# 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>.
docs: use scdoc instead of roff for man pages
2020-06-15 07:51:23 +00:00
# SEE ALSO
docs: small man pages fixes and updates - Previous hard-coded settings can be now be changes with riverctl or via environment variables - Update "See also" - Mod → Mod1
2020-06-17 08:39:48 +00:00
*river*(1), *river-layouts*(7), *rivertile*(1)
Reference in a new issue Copy permalink