ARU-gh-mirror/docs/source/river-setup.rst

.. ARU (c) 2018 - 2025, Pavel Priluckiy, Vasiliy Stelmachenok and contributors

   ARU is licensed under a
   Creative Commons Attribution-ShareAlike 4.0 International License.

   You should have received a copy of the license along with this
   work. If not, see <https://creativecommons.org/licenses/by-sa/4.0/>.

.. _river_setup:

.. index:: prog-settings, river, river wm
.. _river:

***********************
Оконный менеджер river
***********************

Некоторое программное обеспечение (ПО) на первый взгляд имеет
сложную документацию. Один из таких представителей оконный менеджер - river.

Данный менеджер окон (WM) - композитор для Wayland, в отличии от
других представителей данной области располагает довольно скудной
документацией с помощью которой сложно разобраться во многих тонкостях
его настройки. Часть информации о настройке river вы можете найти на
`вики river <https://codeberg.org/river/wiki>`__, но большая часть
расположена в мануалах для river, riverctl, rivertile, которые могут
быть доступны из системы командой, если у вас установлен **man**::

  man river
  man riverctl
  man rivertile

Однако в данных мануалах не все так очевидно с первого раза, как бы
хотелось, но их использование или ознакомление с ними рекомендуется.

.. warning:: Данное руководство основано на данных из мануалов и опыте
   взаимодействия с river. Руководство построено на основе примеров
   команд - адаптируйте их под свои нужды.

.. index:: config, river
.. _river_config:

=============
Конфиг river
=============

В отличие от многих других WM, river в качестве своего конфигурационного
файла использует исполняемый файл с именем **init**, поэтому
настраивать river можно как с помощью скрипта оболочки, так и с
помощью программ написанных на других языках программирования.
По умолчанию используется скрипт оболочки - в этом можно убедиться по
наличию надписи в первой строке **#!/bin/sh** файла **init**. Еще одной особенностью
подхода конфигурационного файла river является возможность изменения
его параметров непосредственно из работающей системы без необходимости
перезапуска WM или перечитывания данных из файла **init**. Данная
возможность полезна в случае, если вы хотите проверить некоторое
изменение быстро, например - новую комбинацию клавиш для вызова
терминала - достаточно ввести в терминале команду::

  riverctl map normal Super T spawn foot

Разберем представленную команду:

- *riverctl* - команда для определения параметров в river,
- *map* - параметр отвечающий за определения комбинаций клавиш,
- *normal* - параметр указывающий на режим работы (в river 2 режима:
  основной - *normal*, и режим на случай блокировки экрана - *locked*),
- *foot* - здесь отображает программу, которую нужно запустить, также
  можно задать команду для выполнения, например **'reboot'**. В случае
  определения команды одиночные кавычки обязательны,
- *spawn* - команда отвечающая за выполнение,
  *Super* и *T* - указывают на клавиши которые нужно нажать. Если
  используются несколько управляющих клавиш (*Super, Alt, Shift, Control* и т.п.) то
  между ними нужно добавлять знак **+**, например для команды в
  предыдущем примере это будет выглядеть следующим образом::

    riverctl map normal Super+Shift T spawn foot

.. warning:: Вероятно, что комбинации только из служебных клавиш обозначить нельзя! (Super
   Shift, Alt Shift и т.п.)

.. warning:: Не смотря на то что river позволяет вносить изменения в
   настройки в режиме "реального времени", для того чтобы
   изменения использовались на постоянной основе, а не только в данной
   сессии - изменения необходимо добавлять(производить) в файл(е) **init**!

.. index:: river, settings
.. _river_settings:

================
Настройка river
================

Приступим к настройке river. Для начала стоит отметить, что конфигурационный
файл **init** необходимо располагать в::

  $HOME/.config/river/

Пример конфигурационного файла в зависимости от вашей системы может
быть расположен::

  /etc/river/init
  /usr/share/river/example/init

Если по указанным путям его нет и вы не знаете где его найти, то можно
получить его из репозитория `river
<https://codeberg.org/river/river/src/branch/master/example/init>`__.
Если вы хотите использовать другой формат для файла **init**, то есть
примеры на `wiki river <https://codeberg.org/river/wiki#wait-the-configuration-is-a-shell-script>`__ - мы их пока не затрагиваем.

.. index:: keys, mouse
.. _keys_river:

------------------
Назначение клавиш
------------------

Чтобы определить комбинацию клавиш уже был представлен пример команды,
однако в случае если у вас используется несколько раскладок клавиатур,
например английская и русская, то на русской раскладке часть
комбинаций не будет работать. Это происходит потому что по умолчанию river
использует *keysym*, а не *keycode* (у англоязычных и русскоязычных букв
*keysym* - разный, а *keycode* - одинаковый) Чтобы решить данную проблему
необходимо использовать *-layuot*::

  riverctl map -layuot 0 normal Super T spawn foot
  #                    |
  #             номер раскладки

.. warning:: Данная комбинация не включает использование *keycode*,
   она просто говорит, что в качестве привязанных клавиш нужно
   использовать раскладку 0, т.е. первую указанную в "us, ru". Будьте
   внимательны!

Стоит отметить, что те клавиши, которые не зависят от *keysym*
(*Super, Alt, Control, Return* и прочие служебные клавиши) не
нуждаются в добавлении *-layuot*, например следующая команда будет
работать в любой раскладке::

  riverctl map normal Super Return spawn foot

В river, как и в других WM, можно привязывать к клавишам целые команды,
для этого нужно добавить одиночные кавычки::

  riverctl map normal Super Return spawn 'foot --app-id=foobar'

Для того чтобы убрать привязку клавиш в работающей системе, используйте *unmap*, например::

  riverctl unmap normal Super D

.. warning:: Данная команда введенная в терминале сработает только для текущей сессии, если
   вы хотите внести изменения на постоянной основе - редактируйте
   **init** для последующих запусков.

В river для определения взаимодействия с окнами с помощью мыши
используется *map-pointer*, например:

Для перемещения окна с помощью мыши::

  riverctl map-pointer -layuot 0 normal Super BTN_LEFT move-view

.. warning:: Окна в river определены как *виды* - **view**.
.. warning:: При перемещении не "плавающего" окна, т.е. из **rivertile**
   на 13.02.2025 заданные размеры окна игнорируются - берутся те
   размеры, что сейчас на экране!

Для изменения размера окна с помощью мыши::

  riverctl map-pointer -layuot 0 normal Super BTN_RIGHT resize-view

Для переключения режима "плавающего" окна с помощью мыши::

  riverctl map-pointer -layuot 0 normal Super BTN_MIDDLE toggle-float

Чтобы удалить привязку, например::

  riverctl unmap-pointer normal Super BTN_RIGHT
  #                       |       |        |
  #                    режим  Модификатор Кнопка мыши

.. index:: keyboard-layout
.. _keyboard-layout_river:

-------------------------------
Настройка раскладки клавиатуры
-------------------------------

Для настройки смены раскладок клавиатуры::

  riverctl keyboard-layout -model pc105 -variant qwerty -options "grp:win_space_toggle" "us, ru"
  # или
  riverctl keyboard-layout -options "grp:win_space_toggle" "us, ru"

Разберем допустимые параметры:

- *rules* - не присутствует в данном примере, не является
  обязательным, позволяет определять правила, на данный момент
  имейте в виду что такой параметр есть.
- *keyboard-layout* - определение слоев клавиатуры,
- *model* - здесь задается тип клавиатуры - сколько клавиш (указывать не
  обязательно данный параметр),
- *variant* - форматов раскладок несколько, но все привыкли к формату *qwerty* (указывать не обязательно данный параметр),
- *options* - тут указывается как переключать раскладку клавиатур,
  согласно *xkb*,
- *"us, ru"* - в кавычках указываются все нужные раскладки.

.. warning:: После обновления предположительно **setxkbmap**, вариант с указанием всех параметров
   может перестать работать, обращайте на это внимание! Что касается
   сокращенного варианта - похожих случаев не зафиксировано и
   позволяет решить описанную проблему с большим количеством
   параметров, но имейте в виду.

.. warning:: По умолчанию в river каждая клавиатура расценивается как индивидуальное
  устройство ввода и раскладка клавиатуры переключается для каждой клавиатуры в отдельности,
  конкретной клавиатурой.

Если вам нужно чтобы на всех клавиатурах раскладка переключалась
одновременно, то для этого есть *группы*, которые нужно создать и
добавить туда все нужные устройства ввода. Для работы с *группами*
устройств ввода есть несколько действий:

1. Создать группу::

    riverctl keyboard-group-create _имя_группы_

2. Добавить устройство в группу::

    riverctl keyboard-group-add _имя_группы_ _имя_устройства_

Для того чтобы узнать _имя_устройства_ ввода::

  riverctl list-inputs

3. Для удаления устройства из группы::

    riverctl keyboard-group-remove _имя_группы_ _имя_устройства_

4. Для удаления группы::

    riverctl keyboard-group-destroy _имя_группы_

Настроить раскладки для всех клавиатур можно через файл согласно
документации `XKB <https://xkbcommon.org/doc/current/keymap-text-format-v1.html>`__::

  riverctl keyboard-layout-file _путь_к_файлу_

.. index:: media-key, media-device-control
.. _media_river:

-------------------------------------
Настройка медиа-клавиш или устройств
-------------------------------------

Для настройки медиа клавиш и устройств в конфиге river есть подобный фрагмент::

  for mode in normal locked
  do
    # Eject the optical drive (well if you still have one that is)
    riverctl map $mode None XF86Eject spawn 'eject -T'

    riverctl map $mode None XF86AudioRaiseVolume  spawn 'wpctl set-volume @DEFAULT_SINK@ 2%+'
    riverctl map $mode None XF86AudioLowerVolume  spawn 'wpctl set-volume @DEFAULT_SINK@ 2%-'
    riverctl map $mode None XF86AudioMute         spawn 'wpctl set-mute @DEFAULT_SINK@ toggle'

    # Control MPRIS aware media players with playerctl (https://github.com/altdesktop/playerctl)
    riverctl map $mode None XF86AudioMedia spawn 'playerctl play-pause'
    riverctl map $mode None XF86AudioPlay  spawn 'playerctl play-pause'
    riverctl map $mode None XF86AudioPrev  spawn 'playerctl previous'
    riverctl map $mode None XF86AudioNext  spawn 'playerctl next'

    # Настройка яркости экрана через brightnessctl (https://github.com/Hummer12007/brightnessctl)
    riverctl map $mode None XF86MonBrightnessUp   spawn 'brightnessctl set +5%'
    riverctl map $mode None XF86MonBrightnessDown spawn 'brightnessctl set 5%-'
  done

Если вы не используете **pipewire** и **wireplumber**, то для регулировки звука замените **wpctl**  на
**pamixer** или **pactl** согласно `документации <https://wiki.archlinux.org/title/PulseAudio>`__ их использования. (По
умолчанию в конфиге river указан **pamixer**)

Как можно видеть из примера в случае специальных медиа клавиш или
крутилок или других спец. клавиш в обозначении появляется конструкция **$mode None XF86Audio...** - данный формат специально предназначен для подобных
настроек.

.. index:: tiling
.. _tiling_river:

------------------
"Тайлинг" в river
------------------

Для реализации "тайлинга", т.е. расположения окон на экране в river,
используется **rivertile** - это так называемый генератор слоев. По
умолчанию **rivertile** работает в стековом режиме, т.е. есть одна
главная область и вторая второстепенная, куда "складываются" остальные
окна в своеобразный "столбик".

Особенность river в том, что он позволяет заменить rivertile на
другой, тем самым позволяет с легкостью изменить формат разметки "тайлинга". На `wiki river <https://codeberg.org/river/wiki/src/branch/master/pages/Recommended-Software.md>`__
предлагаются следующие варианты:

- `riverguile <https://git.sr.ht/~leon_plickat/riverguile>`__
- `owm <https://github.com/justinlovinger/owm>`__
- `kile <https://gitlab.com/snakedye/kile>`__
- `stacktile <https://git.sr.ht/~leon_plickat/stacktile>`__
- `rivercarro <https://git.sr.ht/~novakane/rivercarro>`__
- `river-luatile <https://github.com/MaxVerevkin/river-luatile>`__
- `river-bsp-layout <https://github.com/areif-dev/river-bsp-layout>`__
- `river-dwindle <https://gitlab.com/thom-cameron/river-dwindle>`__
- `filtile <https://github.com/pkulak/filtile>`__
- `wideriver <https://github.com/alex-courtis/wideriver>`__
- `river-ultitile <https://sr.ht/~midgard/river-ultitile/>`__
- `river-spiral-extended <https://codeberg.org/ideasman42/riverwm-spiral-extended>`__

Чтобы указать какой генератор макетов использовать по умолчанию для всех экранов::

  riverctl default-layout rivertile   # rivertile используется по
  умолчанию в river - замените на другой

Чтобы указать другое размещение окон на активном экране
используйте::

  riverctl output-layout rivertile    # rivertile замените на любой
  другой

Для отправки команд генератору разметки есть подобный пример::

  # Команда с привязкой к "горячим" клавишам
  riverctl map -layout 0 normal Super K send-layout-cmd rivertile "main-count +1"

  # Для команды из терминала
  send-layout-cmd rivertile "main-count +1"

*rivertile* - тут в качестве примера генератора, а выражение в **""** команда
которую нужно обработать - должна соответствовать документации генератора

.. index:: rivertile
.. _rivertile:

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Настройка параметров rivertile
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

В **rivertile** можно изменить расстояние между окнами::

  rivertile -view-padding N     # N - количество пикселей

Для изменения расстояния до краев окна::

  rivertile -outer-padding N    # N - количество пикселей

Для выбора места - где будет располагаться основной сегмент::

  rivertile -main-location PAR   # PAR = [top | bottom | left | right] - указывается один из представленных

Чтобы изменить соотношение "полезного" пространство для основного
сегмента::

  rivertile -main-ratio N        # N - значение от 0.1 до 0.9

Определить количество видов в основном пространстве::

  rivertile -main-count N        # N - целое значение, по умолчанию 1

.. index:: views, window, windows, fullscreen, floating
.. _window_control:

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Взаимодействие с окнами
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Для переключения активного окна используются:

1. Выбрать следующее окно::

    riverctl map -layout 0 normal Super J focus-view next

2. Выбрать предыдущее окно::

    riverctl map -layout 0 normal Super K focus-view previous

Для переноса окна в стек и обратно::

  riverctl map -layout 0 normal Super+Shift Return zoom

Переключение режимов окна:

1. Переключение окна в "плавающий режим" и обратно::

    riverctl map -layout 0 normal Super Space toggle-float

2. Переключение окна в полноэкранный режим и обратно::

    riverctl map -layout 0 normal Super F toggle-fullscreen

Для перемещения окон:

1. Переместить окно следующую позицию::

    riverctl map -layout 0 normal Super+Shift J swap next

2. Переместить окно на предыдущую позицию::

    riverctl map -layout 0 normal Super+Shift K swap previous

.. warning:: Поддерживаются также значения *up, down, left, right*.

Для того чтобы перемещать "плавающее" окно::

  riverctl map -layout 0 normal Super+Alt H move left 100     # переместит окно влево
  riverctl map -layout 0 normal Super+Alt J move down 100     # переместит окно вниз
  riverctl map -layout 0 normal Super+Alt K move up 100       # переместит окно вверх
  riverctl map -layout 0 normal Super+Alt L move right 100    # переместит окно вправо

*100* - показывает шаг перемещения в пиксилях

.. warning:: Если окно не было "плавающим", то оно перейдет в данный
   режим!

"Плавающие" окна можно переместить к одной из сторон экрана например::

  riverctl map -layout 0 normal Super+Alt+Control H snap left     # левый край
  riverctl map -layout 0 normal Super+Alt+Control J snap down     # нижний край
  riverctl map -layout 0 normal Super+Alt+Control K snap up       # верхний край
  riverctl map -layout 0 normal Super+Alt+Control L snap right    # правый край

Для перемещения окна в угол экрана выполните две команды
последовательно, например для левого угла переместите окно к левой
границе экрана и вверх, либо наоборот. Также вы можете обозначить
данные действия на одну клавишу с помощью *&&*.

.. index:: resize
.. _resize_windows:

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Управление размерами окон
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Для изменения размеров окон используются следующие команды:

1. Уменьшение размера основного окна::

    riverctl map -layout 0 normal Super H send-layout-cmd rivertile "main-ratio -0.05"

2. Увеличение размера основного окна::

    riverctl map -layout 0 normal Super H send-layout-cmd rivertile "main-ratio +0.05"

.. warning:: Увеличение / уменьшение основного сектора приводит к
   уменьшению / увеличению размеров стека соответственно!

Для "плавающих" окон:

1. Уменьшение по горизонтали::

    riverctl map -layout 0 normal Super+Alt+Shift H resize horizontal -100

2. Увеличение по вертикали::

    riverctl map -layout 0 normal Super+Alt+Shift J resize vertical 100

3. Уменьшение по вертикали::

    riverctl map -layout 0 normal Super+Alt+Shift K resize vertical -100

4. Увеличение по горизонтали::

    riverctl map -layout 0 normal Super+Alt+Shift L resize horizontal 100

*100* - показывает шаг изменения размера в пиксилях

.. warning:: Изменение размеров "плавающих" окон происходит с двух
   сторон!

.. index:: tags, workspaces
.. _river_tags:

--------------------------------
Настройка tags (рабочих столов)
--------------------------------

В river как и в dwm рабочие столы определены не как **workspace**, а как
**tag**. Как утверждается **tags** более гибки в настройке и одному приложению
можно определять несколько **tags**. Также одновременно на экран можно
выводить несколько разных **tags**.

В конфиге river есть блок, который определяет клавиши для выбора и
управления **tags**, если вы хотите изменить клавиши, то вам поможет
следующий пример::

  # Определяем клавиши для переключения
  tg=('q' 'w' 'e' 'r' 't' 'y' 'u' 'i' 'o')

  # Определяем команды для каждого tag
  for i in $(seq 1 9)               # задается количество tags, по умолчанию до 9 штук на экран
  do
    tags=$((1 << ($i - 1)))         # определяются tags

    # Super+[q-o] выбор tag [0-8]
    riverctl map -layout 0 normal Super ${tg[$i-1]} set-focused-tags $tags

    # Super+Shift+[q-o] перемещение окна на tag [0-8]
    riverctl map -layout 0 normal Super+Shift ${tg[$i-1]} set-view-tags $tags

    # Super+Control+[q-o] выбор - окна какого tag [0-8] добавить для отображения на экране
    riverctl map -layout 0 normal Super+Control ${tg[$i-1]} toggle-focused-tags $tags

    # Super+Shift+Control+[1-9] дублировать окно на tag [0-8]
      riverctl map -layout 0 normal Super+Shift+Control ${tg[$i-1]} toggle-view-tags $tags
  done

.. warning:: Данный пример приведен, если вы хотите изменить клавиши
   для **tags** на буквы, в конфиге river по умолчанию используются числа от 1
   до 9.

В river есть команды для взаимодействия с окнами на всех **tags**::

  all_tags=$(((1 << 32) - 1))

  # Вывести на экран все окна со всех tags
  riverctl map -layout 0 normal Super 0 set-focused-tags $all_tags

  # Определить для активного окна все tags - окно будет перемещаться вместе с переходом на другой tag
  riverctl map -layout 0 normal Super+Shift 0 set-view-tags $all_tags

В river, в отличие от sway и части других WM, по умолчанию **tags** не переносятся на
другие мониторы, т.е. для каждого экрана создаются свои независимые
**tags**, взаимодействия с которыми требуют переключения на другой
монитор::

  riverctl map -layout 0 normal Super L focus-output next       # переключиться на следующий монитор
  riverctl map -layout 0 normal Super H focus-output previous   # переключиться на предыдущий монитор

Помимо предыдущего (*previous*) и следующего (*next*) мониторов доступны также - *up, right,
down, left* или имена выводов - *HDMI-1, DP-1 и т.п.*

Для переноса активных окон с одного монитора на другой используется
команда::

  riverctl map -layout 0 normal Super+Shift L send-to-output next      # перенести на следующий монитор активное окно

Поддерживаются также - *previous, up, down, right, left* и имена
мониторов - *HDMI-1, DP-1 и т.п.*.

.. warning:: По умолчанию при перемещении активных окон сохраняется
   *№* использованного *tag* и после перемещения на другой монитор активное
   окно будет на *tag* под тем же номером.

.. index:: monitor, setup, wlr-randr, wlopm, kanshi, way-displays
.. _monitor_river:

------------------------------
Настройка экранов(мониторов)
------------------------------

В river для управления экранами (мониторами) используется внешний
софт, на `wiki river <https://codeberg.org/river/wiki/src/branch/master/pages/Recommended-Software.md>`__
рекомендуются следующие:

- `wlopm <https://git.sr.ht/~leon_plickat/wlopm>`__
- `wlr-randr <https://sr.ht/~emersion/wlr-randr/>`__
- `kanshi <https://sr.ht/~emersion/kanshi/>`__
- `way-displays <https://github.com/alex-courtis/way-displays>`__

На данный момент будет описано использование **wlr-randr**.
Для начала необходимо знать какие выводы у вас используются. Для этого
достаточно запустить команду::

  wlr-randr

Данная команда покажет вам всю доступную информацию о подключенных
мониторах и настройках, например::

  DP-2 "AOC Q27G2WG4 0x0000DAB3 (DP-2)"
    Make: AOC
    Model: Q27G2WG4
    Serial: 0x0000DAB3
    Physical size: 600x340 mmSwayNotificationCenter
    Enabled: yes
    Modes:
      2560x1440 px, 59.951000 Hz (preferred)
      2560x1440 px, 143.912003 Hz (current)
      2560x1440 px, 119.998001 Hz
      2560x1440 px, 99.945999 Hz
      1920x1080 px, 119.878998 Hz
      1920x1080 px, 60.000000 Hz
      1920x1080 px, 59.938999 Hz
      1920x1080 px, 50.000000 Hz
      1280x1440 px, 59.912998 Hz
      1280x1024 px, 75.025002 Hz
      1280x1024 px, 60.020000 Hz
      1440x900 px, 59.901001 Hz
      1280x720 px, 59.943001 Hz
      1280x720 px, 50.000000 Hz
      1024x768 px, 119.988998 Hz
      1024x768 px, 99.972000 Hz
      1024x768 px, 75.028999 Hz
      1024x768 px, 70.069000 Hz
      1024x768 px, 60.004002 Hz
      800x600 px, 119.972000 Hz
      800x600 px, 99.662003 Hz
      800x600 px, 75.000000 Hz
      800x600 px, 72.188004 Hz
      800x600 px, 60.317001 Hz
      800x600 px, 56.250000 Hz
      720x576 px, 50.000000 Hz
      720x480 px, 59.939999 Hz
      640x480 px, 119.517998 Hz
      640x480 px, 99.768997 Hz
      640x480 px, 75.000000 Hz
      640x480 px, 72.808998 Hz
      640x480 px, 59.939999 Hz
      640x480 px, 59.929001 Hz
    Position: 0,0
    Transform: normal
    Scale: 1.000000
    Adaptive Sync: disabled
  DP-1 "AOC Q27G2SG4 XFXQ7HA001584 (DP-1)"
    Make: AOC
    Model: Q27G2SG4
    Serial: XFXQ7HA001584
    Physical size: 600x340 mm
    Enabled: yes
    Modes:
      2560x1440 px, 59.951000 Hz (preferred)
      2560x1440 px, 155.000000 Hz
      2560x1440 px, 143.912003 Hz (current)
      2560x1440 px, 119.998001 Hz
      1920x1080 px, 119.878998 Hz
      1920x1080 px, 60.000000 Hz
      1920x1080 px, 59.938999 Hz
      1920x1080 px, 50.000000 Hz
      1280x1440 px, 59.912998 Hz
      1280x1024 px, 75.025002 Hz
      1280x1024 px, 60.020000 Hz
      1280x720 px, 59.943001 Hz
      1280x720 px, 50.000000 Hz
      1024x768 px, 119.988998 Hz
      1024x768 px, 99.972000 Hz
      1024x768 px, 75.028999 Hz
      1024x768 px, 70.069000 Hz
      1024x768 px, 60.004002 Hz
      800x600 px, 119.972000 Hz
      800x600 px, 99.662003 Hz
      800x600 px, 75.000000 Hz
      800x600 px, 72.188004 Hz
      800x600 px, 60.317001 Hz
      800x600 px, 56.250000 Hz
      720x576 px, 50.000000 Hz
      720x480 px, 59.939999 Hz
      640x480 px, 119.517998 Hz
      640x480 px, 99.768997 Hz
      640x480 px, 75.000000 Hz
      640x480 px, 72.808998 Hz
      640x480 px, 59.939999 Hz
      640x480 px, 59.929001 Hz
    Position: 2560,0
    Transform: normal
    Scale: 1.000000
    Adaptive Sync: disabled

Для настройки экранов **wlr-randr** использует ряд параметров::

  --output name             # выбор экрана для настройки (name - HDMI, DP и т.п.)
  # Следующие параметры указываются после --output name для конкретного монитора
    --mode WxH@XHz          # определяет разрешение и частоту экрана (W - ширина, H - высота в px) и частоту (XHz - частота в Hz. Х - должен точно соответствовать имеющимся значениям)
    --pos X,Y               # расположение одного экрана относительно другого X - смещение по X, Y - смещение по Y
    --adaptive-sync X       # включение режима переменной частоты обновления монитора (X - enabled или disabled)
    --scale X               # масштабирование изображения (X - 1.0, 1.5 и т.п.)
    --transform X           # поворот изображения на экране (90, 180, normal, flipped, flipped-90 и т.п.)
    --on                    # включение
    --off                   # выключение
    --toggle                # переключение (вкл. / выкл.)

Пример настройки экранов через **wlr-randr**::

  wlr-randr --output DP-2 --mode 2560x1440@143.912003Hz --pos 0,0 --adaptive-sync enabled --output DP-1 --mode 2560x1440@143.912003Hz --pos 2560,0 --adaptive-sync disabled

В Wayland вывод изображения синхронизируется с частотой обновления
монитора, что может создавать задержку ввода. Для решения данной
проблемы был реализован протокол **tearing**. Для его включения в
полноэкранных программах::

  riverctl allow-tearing enabled

.. index:: apps, programs, rules
.. _river_progs:

-------------------------------------------------
Настройка управления программами / приложениями
-------------------------------------------------

Организация работы с программами / приложениями в river производится
через *правила (rules)*. Данный компонент позволяет определять: на
каком мониторе будет открываться программа, на какой *tag* будет
выводиться по умолчанию, будет ли использоваться *tearing* -
независимо от заданного глобального параметра, задавать размер окна
программы и его расположения, будет ли окно открываться как *плавающее*,
будет ли программа открываться в полноэкранном режиме - в общем
отвечает за все основные параметры.
Взаимодействовать с *rules* можно тремя способами:

.. index:: rule-add
.. _river_rules:

^^^^^^^^^^^^^^^^^
Добавить правило
^^^^^^^^^^^^^^^^^

.. warning:: В river добавлять правило можно только по одному. Не стоит пытаться
  объединять все в одну строку, если конечно вы не пишите несколько
  команд через *&&*.

.. index:: river, program, workspace, tag, rule-add
.. _river_prog_on_tag:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Правило определяющее *tag* для программы
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Чтобы *firefox* открывался на третьем *tag* нужно указать правило::

  riverctl rule-add -app-id "firefox" tags $((1 << 2))

.. warning:: Стоит отметить, что в river, как в части языков программирования,
   нумерация начинается с 0, а не с 1, поэтому в выражение **$((1 <<
   N))**, **N** - должно быть на 1 меньше чем номер *tag* на который вы
   хотите определить отображение программы по умолчанию. Зная данный
   факт можно заменить выражение на **$((1 << N - 1))** - это позволит
   указывать **N** согласно номеру *tag*.

Для того чтобы river понимал какую программу он должен обработать и
отобразить на определенном *tag* используются такие параметры как **app-id** или **title**.
Данные параметры можно задавать при запуске программы через *riverctl*::

  riverctl spawn 'foot -app-id=terminal'
  riverctl spawn 'foot -title=terminal'

.. warning:: Если **title** не задано пользователем, то оно не
   задается системой самостоятельно, поэтому лучше ориентироваться на **app-id**.

.. warning:: Во многих случаях **app-id** соответствует названию
   программы, но далеко не всегда так: например blender дополнительно
   в **app-id** требует указание версии, например **blender-4.3**,
   иначе на него правило работать не будут!

.. index:: output, river, rule-add, HDMI, DP
.. _river_output_progs:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Правило определяющее монитор для программы
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Чтобы указать монитор на котором стоит отображать программу по
умолчанию, можно использовать следующий пример::

  riverctl rule-add -app-id "steam" output DP-2

Для определения имени "вывода" (экрана) воспользуйтесь одной из программ, упомянутых в
**Настройка экранов (мониторов)**.

.. index:: fullscreen, rule-add, rules
.. _river_fullscreen_progs:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Правило регулирующее отображение программы в полноэкранном режиме
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Для отображения по умолчанию программы в полноэкранном режиме
достаточно использовать параметр *fullscreen*::

  riverctl rule-add -app-id "foot" fullscreen

Для того чтобы сделать исключение используется *no-fullscreen*::

  riverctl rule-add -app-id "foot" no-fullscreen

.. index:: float, floating, window, rule-add
.. _river_float_windows:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Правило для плавающего окна
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Для запуска программы в режиме "плавающего" окна по умолчанию -
используйте *float*::

  riverctl rule-add -app-id "firefox" float

Для отмены или исключения::

  riverctl rule-add -app-id "firefox" no-float

.. index:: position, dimensions, window
.. _river_pos_dim_win:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Правила размера и расположения
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Чтобы задать размер окна программы::

  riverctl rule-add -app-id "foot" dimensions W H   # W - ширина, H - высота

.. warning:: Стоит отметить, что размер окна работает в первую очередь
   для "плавающих" окон, поскольку "не плавающие" окна регулируются
   макетом **rivertile**.

Чтобы задать позицию окна программы::

  riverctl rule-add -app-id "foot" position W H     # W - координата по ширине, H - координата по высоте

.. warning:: Стоит отметить, что "начало координат" (точка X = 0, Y = 0) находится в верхнем
   левом углу. И в первую очередь указание размера необходимо для "плавающих" окон.

.. index:: tearing, window, rule-add
.. _river_tearing:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Правило отвечающее за tearing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Для того, чтобы задать конкретной программе использовать *tearing* вне
зависимости от глобального параметра::

   riverctl rule-add -app-id "firefox" tearing

Для отключения *tearing* для конкретной программы::

  riverctl rule-add -app-id "firefox" no-tearing

.. index:: server, client, csd, ssd, decoration
.. _river_window_decoration:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Правило указывающее на управляющего по декорациям окна
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

В Wayland многое в графике программ переложено на сами
клиенты, а не композиторы. В river есть два параметра которые
определяют кто должен отвечать за внешний вид окон программ:

1. Клиент сам занимается декорацией окна, заголовка и т.п.::

    riverctl rule-add -app-id "foot" csd

2. river занимается декорацией окна, заголовка и т.п.::

    riverctl rule-add -app-id "foot" ssd

.. warning:: river не отвечает за то что и как рисуется в самом окне, но
   может например скрыть заголовок окна терминала, если он является
   управляющим.
   По умолчанию используется режим ssd для многих программ.

.. index:: river, background, border, border-width
.. _river_base_decor:

``````````````````````````````````````
Настройка внешнего вида river
``````````````````````````````````````

В river настройка внешнего вида ограничена несколькими параметрами:

Чтобы задать цвет фона::

  riverctl background-color 0x000000ff

Для указания цвета в river используется один из двух вариантов обозначений:

1. 0xRRGGBBAA - данный формат описывает все цвета на основе комбинации трех цветов - красный (RR), зеленый (GG) и синий (BB) и также задает прозрачность (AA). Все четыре параметра могут изменяться от 00 до 99 и от aa до ff, где aa - является следующим за 99,т.е. ff - наибольшее значение, а 00 - наименьшее.
2. 0xRRGGBB - данный формат такой же как и первый, но без прозрачности, т.е. АА всегда равен ff

Задать цвет границ активного окна::

  riverctl border-color-focused 0xffffffff

Задать цвет границ неактивного окна::

  riverctl border-color-unfocused 0x555555ff

Задать цвет "срочных представлений"::

  riverctl border-color-urgent 0x660022ff

.. warning:: "Срочные предстваления" на данный момент не совсем понятны. Мы работаем над тем, чтобы дать более точную информацию.

Задать ширину рамки окна::

  riverctl border-width N                       # N - целое значение пикселей

Чтобы разместить обои на экраны необходимо использовать
сторонний софт, на `wiki river <https://codeberg.org/river/wiki/src/branch/master/pages/Recommended-Software.md>`__ рекомендуют:

- `swaybg <https://github.com/swaywm/swaybg>`__
- `wbg <https://codeberg.org/dnkl/wbg>`__
- `sww <https://github.com/Horus645/swww>`__

Стоит отметить, что в Wayland мониторы не объединяются в один единый
рабочий стол или виртуальный экран, поэтому для вывода разных
изображений на разные экраны нужно использовать программы, которые это
поддерживают, иначе изображение будет повторятся на всех экранах.
Также вероятно вам придется разрезать изображение под каждый экран,
если вы хотите разместить изображение размером с объединенные экраны.
Приведем пример использования *swaybg*::

  riverctl spawn 'swaybg -o DP-1 -i /path_to_image1/img1.jpg -o DP-2 -i /path_to_image2/img2.png'

  # или

  exec swaybg -o DP-1 -i /path_to_image1/img1.jpg -o DP-2 -i /path_to_image2/img2.png

.. index:: cursor, focus
.. _river_cursor:

......................................
Настройки для курсора
......................................

Изменение активного окна с помощью курсора мыши::

  riverctl focus-follow-cursor _параметр_

Допустимые значения _параметр_:

- *disabled* - не менять активное окно при перемещении курсора,
- *normal* - перемещение приводит к переключению активного окна, но не переключается на данное окно, если курсор перемещается внутри окна непокидая его,
- *always* - всегда переключать активное окно вслед за курсором мыши.

Способы скрыть курсор мыши:

1. Скрывать курсор мыши через T милисекунд::

    riverctl hide-cursor timeout T

2. Скрывать курсор мыши при нажатии не специальных клавиш::

    riverctl hide-cursor when-typing disabled     # enabled | disabled

Положение курсора при перемещении на другой экран или другое окно::

  riverctl set-cursor-warp disabled

Вместо *disabled* доступны:

- *on-output-change* - расположить курсор в центре экрана, при переключении с клавиатуры на другой экран
- *on-focus-change* - расположить курсор в центре активного окна, при переключении с клавиатуры на другой экран или окно

Задать тему и размер курсора::

  riverctl xcursor-theme _тема_курсора_ _размер_курсора_    # _размер_курсора указывать не обязательно

.. index:: rule-del, rules
.. _river_delete_rules:

^^^^^^^^^^^^^^^^
Удаление правил
^^^^^^^^^^^^^^^^

Любое правило можно удалить из запущенной системы::

  riverctl rule-del -app-id "foot" ssd # ssd для примера, параметры частично описаны выше, но также их получение описано далее.

Для указание на программу можно использовать **app-id** или **title**,
главное чтобы они были определены.

.. index:: list-rules, show
.. _river_show_rules:

^^^^^^^^^^^^^^^^^^^^^^^^^
Просмотр заданных правил
^^^^^^^^^^^^^^^^^^^^^^^^^

Если правила были заданы, то вполне логично что их нужно как-то
просмотреть и проверить. Для этого есть команда::

  riverctl list-rules _параметр_

*_параметр_* может принимать следующие значения - *dimensions, float, fullscreen, output, position, ssd, tags*

.. warning:: Параметры для *tearing* по какой-то причине проверить
   нельзя!

.. index:: lid, tabled, mode, enter-mode, declare-mode, map-switch
.. _river_modes:

--------------------------------
Особые режимы / события в river
--------------------------------

В river предусмотрены такие события как: *lid* - крышка и *tabled* - планшет. Для их
определения используется команды:

1. При закрытии крышки::

    riverctl map-switch normal lid close _любая команда через riverctl_

2. При открытии крышки::

    riverctl map-switch normal lid open _любая команда через riverctl_

3. При включении::

    riverctl map-switch normal tabled on _любая команда через riverctl_

4. При выключении::

    riverctl map-switch normal tabled off _любая команда через riverctl_

Для удаления заданных параметров, например::

  riverctl unmap-switch normal lid close

  riverctl unmap-switch normal tabled off

Не смотря на то, что в river по умолчанию только два режима: *normal*
и *locked*, есть возможность определять / создавать другие режимы и
переключаться между ними, например в конфиге river есть такой
фрагмент::

  # Объявления проходного режима. Этот режим имеет только одно отображение для возврата в обычный режим. Это делает его полезным для тестирования вложенного композитора wayland
  riverctl declare-mode passthrough

  # Super+F11 войти в режим passthrough
  riverctl map normal Super F11 enter-mode passthrough

  # Super+F11 вернутся в режим normal
  riverctl map passthrough Super F11 enter-mode normal

.. index:: scroll, touchpad, input
.. _river_input:

----------------------------------------
Параметры для настройки устройств ввода
----------------------------------------

В river есть ряд параметров которые предназначены для настройки
спецализированных значений или поведений устройств ввода (*input*).

Чтобы настроить будут ли "события" устройства ввода использоваться в
river::

  riverctl input _имя_устройства_ events enabled

Допустимые значения:

1. *enabled* - включить,
2. *disabled* - выключить,
3. *disabled-on-external-mouse* - выключить тачпад при подключении внешней мыши.

.. warning:: Для определения _имя_устройства_ используйте **list-inputs**. Пример
   использования был описан выше в **Настройка раскладки клавиатуры**.

Чтобы указать профиль ускорения указателя устройства ввода::

  riverctl input _имя_устройства_ accel-profile none

Допустимые значения:

1. *none* - нет профиля,
2. *flat* - плоский профиль - ко всем дельтам устройства ввода
   применяется постоянный коэффициент, независимо от скорости
   движения,
3. *adaptive* - адаптивный профиль - профиль, который
   учитывает текущую скорость устройства при определении ускорения.

Чтобы определить коэффициент ускорения указателя устройства ввода::

  riverctl input _имя_устройства_ pointer-accel 1.0

Возможные значения от -1.0 до 1.0.

Режим работы тачпада / кликпада::

  riverctl input _имя_устройства_ click-method none

Допустимые значения:

1. *none* - нет режима,
2. *button-areas* - нижняя область тачпада делится на область левой, средней и правой кнопок,
3. *clickfinger* - количество пальцев на тачпаде определяет тип кнопки.

Для активиции или отключения функции перетаскивания тачпадом::

  riverctl input _имя_устройства_ drag enabled

Допустимые значения:

1. *enabled* - включить,
2. *disabled* - выключить.

Для включения или отключения функции блокировки перетаскивания
тачпадом::

  riverctl input _имя_устройства_ drag-lock enabled

Допустимые значения:

1. *enabled* - включить,
2. *disabled* - выключить.

Для включения или отключения функции отключения тачпада во время набора текста::

  riverctl input _имя_устройства_ disable-while-typing enabled

Допустимые значения:

1. *enabled* - включить,
2. *disabled* - выключить.

Для включения или отключения функции отключения тачпада при
использовании трекпоинта::

  riverctl input _имя_устройства_ disable-while-trackpointing enabled

Допустимые значения:

1. *enabled* - включить,
2. *disabled* - выключить.

Для включения эмуляции средней кнопки мыши на тачпаде::

  riverctl input _имя_устройства_ middle-emulation enabled

Допустимые значения:

1. *enabled* - включить,
2. *disabled* - выключить.

Чтобы включить инверсию прокрутки::

  riverctl input _имя_устройства_ natural-scroll enabled

Допустимые значения:

1. *enabled* - включить,
2. *disabled* - выключить.

Чтобы определить скорость прокрутки::

  riverctl input _имя_устройства_ scroll-factor 2

Допускаются значения больше 0. Значения < 1 приведут к замедлению
скорости прокрутки, когда значения > 1 - к ускорению.

Режим работы "для левшей" для мыши, тачпада и т.п.::

  riverctl input _имя_устройства_ left_handed enabled

Допустимые значения:

1. *enabled* - включить,
2. *disabled* - выключить.

Включить или отключить функцию "тап" для тачпада::

  riverctl input _имя_устройства_ tap enabled

Допустимые значения:

1. *enabled* - включить,
2. *disabled* - выключить.

Настройка типов нажатий на тачпаде::

  riverctl input _имя_устройства_ tap-button-map left-right-middle

Допустимые значения:

1. left-right-middle - нажатие на тачпад одним пальцем - левая кнопка мыши,
   двумя - правая, тремя - средняя,
2. left-middle-right - нажатие на тачпад одним пальцем - левая кнопка мыши,
   двумя - средняя, тремя - правая.

Чтобы задать способ прокрутки на тачпаде::

  riverctl input _имя_устройства_ scroll-method none

Допустимые значения:

1. *none* - не использовать тачпад для прокрутки,
2. *two-finger* - прокрутка с помощью двух пальцев,
3. *edge* - пролистывание, используя край тачпада,
4. *button* - пролистывание с помощью движения указателя при нажатой
   кнопке.

Чтобы задать клавишу для пролистывания с помощью четвертого варианта::

  riverctl input _имя_устройства_ scroll-button _код_события_

Режим работы клавиши прокрутки::

  riverctl input _имя_устройства_ scroll-button-lock enabled

Допустимые значения:

1. *enabled* - клавишу не нужно удерживать. Первое нажатие войти в режим
   прокрутки, а второе нажатие - выйти,
2. *disabled* - клавишу нужно удерживать для прокрутки.

Чтобы указать устройству ввода работать только на определенном экране,
используйте::

  riverctl input _имя_устройства_ map-to-output HDMI-1

Допустимые значения:

1. *disabled* - отключить привязку устройства ввода к определенному
   экрану,
2. Все возможные варианты *output*, которые вы можете получить через
   тот же **wlr-randr** (DP-1, HDMI-1 и т.п.).

В river можно задать скорость обработки нажатий и задержку::

  riverctl set-repeat rate delay

О параметрах:

1. *rate* - скорость повторной обработки нажатия (зажатия) клавиши в милисекундах (50 - по умолчанию),
2. *delay* - задержка повторной обработки нажатия (зажатия) клавиши в милисекундах (300 - по умолчанию).

.. index:: notify, notify-daemon
.. _river_notification:

-----------------------
Настройка уведомлений
-----------------------

Как и во многих других WM в river используются сторонние средства для
отображения уведомлений. На `wiki river
<https://codeberg.org/river/wiki/src/branch/master/pages/Recommended-Software.md>`__
рекомендуются следующие:

- `mako <https://github.com/emersion/mako>`__
- `salut <https://gitlab.com/snakedye/salut>`__
- `fnott <https://codeberg.org/dnkl/fnott>`__
- `dunst <https://github.com/dunst-project/dunst>`__
- `wired <https://github.com/Toqozz/wired-notify>`__
- `SwayNotificationCenter <https://github.com/ErikReider/SwayNotificationCenter>`__

Для запуска вместе с river нужно в **init** указать команду::

  riverctl spawn fnott    # fnott тут в качестве примера, замените на любой другой

.. index:: bar, status, panel
.. _river_bar:

--------------------
Панель (status bar)
--------------------

В качестве панели (status bar) на `вики river <https://codeberg.org/river/wiki/src/branch/master/pages/Recommended-Software.md>`__ рекомендуют использовать:

- `waybar <https://github.com/Alexays/Waybar>`__
- `yambar <https://codeberg.org/dnkl/yambar>`__
- `levee <https://sr.ht/~andreafeletto/levee>`__
- `creek <https://github.com/nmeum/creek>`__
- `i3bar-river <https://github.com/MaxVerevkin/i3bar-river>`__
- `zelbar <https://sr.ht/~novakane/zelbar/>`__
- `dam <https://codeberg.org/sewn/dam>`__
- `sandbar <https://github.com/kolunmi/sandbar>`__

Для запуска панели достаточно указать команду в **init**::

  riverctl spawn waybar     # вместо waybar можете использовать любую другую панель.

.. warning:: Панели могут потребовать дополнительной настройки для отображения
  элементов river (tags, window, mode, layuot и т.п.).

.. warning:: На 11.02.2025 г. панели не имеют модуля вывода текущей
   раскладки языка в river!

Как можно заметить для запуска приложения "в фоне"
достаточно просто использовать *riverctl spawn _имя_программы_*, данная
команда просто запустит программу - работает как через файл
**init** так и из терминала.

.. index:: launcher
.. _launchers_for_river:

-------------------------
Меню запуска приложений
-------------------------

Для запуска программ нужен так называемый *launcher* (лаунчер). На `wiki river <https://codeberg.org/river/wiki/src/branch/master/pages/Recommended-Software.md>`__ рекомендуют:

- `fuzzel <https://codeberg.org/dnkl/fuzzel>`__
- `bemenu <https://github.com/Cloudef/bemenu>`__
- `mew <https://codeberg.org/sewn/mew>`__
- `wofi <https://hg.sr.ht/~scoopta/wofi>`__
- `LavaLauncher <https://git.sr.ht/~leon_plickat/lavalauncher>`__
- `nwg-drawer <https://github.com/nwg-piotr/nwg-drawer>`__
- `tofi <https://github.com/philj56/tofi>`__
- `wmenu <https://codeberg.org/adnano/wmenu>`__

Для использования достаточно определить комбинацию клавиш, что было
описано вначале на примере *foot*.

.. index:: waylock, swaylock, idle
.. _river_lock:

-------------------
Блокировка экрана
-------------------

Для блокировки экрана на `wiki river <https://codeberg.org/river/wiki/src/branch/master/pages/Recommended-Software.md>`__ рекомендуют использовать:

- `waylock <https://codeberg.org/ifreund/waylock>`__
- `swaylock <https://github.com/swaywm/swaylock>`__

Заблокировать экран можно назначив запуск программы на "горячую" клавишу или используя `swayidle <https://github.com/swaywm/swayidle>`__::

  riverctl spawn 'swayidle -w timeout 300 "swaylock --show-failed-attempts -e"'

Немного пояснения:

- *-w* - говорит о необходимости ожидания события,
- *timeout* - событие, которое ожидает swayidle - в данном случае ожидание бездействия в 300 секунд.

Через **swayidle** можно выполнять разные команды. Например выключать и
включать мониторы. В мануале **swayidle** есть подобное события::

  swayidle -w \
      timeout 300 ’swaylock -f -c 000000’ \
      timeout 600 ’swaymsg "output * dpms off"’ \
            resume ’swaymsg "output * dpms on"’ \
      before-sleep ’swaylock -f -c 000000’

.. warning:: Будьте внимательны при настройки отключения мониторов,
   поскольку после пробуждения могут часть настроек river "слететь",
   особенно в случае с несколькими мониторами, а в случае с
   видеокартами nvidia возможны проблемы с пробуждением!

.. vim:set textwidth=70: