2023-07-22 02:58:51 -07:00
< img align = "right" style = "width: 256px" src = "assets/logo.svg" >
2023-07-31 22:04:53 -07:00
# hy3
< a href = "https://matrix.to/ #/#hy3:outfoxxed .me" >< img src = "https://img.shields.io/badge/Join%20the%20matrix%20room-%23hy3:outfoxxed.me-0dbd8b?logo=matrix&style=flat-square" ></ a >
2023-07-22 02:58:51 -07:00
2023-04-19 02:56:11 -07:00
i3 / sway like layout for [hyprland ](https://github.com/hyprwm/hyprland ).
2023-07-31 22:04:53 -07:00
[Installation ](#installation ), [Configuration ](#configuration )
2023-04-19 02:56:11 -07:00
### Features
- [x] i3 like tiling
2023-07-31 22:04:53 -07:00
- [x] Node based window manipulation (you can interact with multiple windows at once)
- [x] Greatly improved tabbed node groups over base hyprland
2023-08-01 01:00:56 -07:00
- [x] Optional autotiling
2023-07-31 22:04:53 -07:00
Additional features may be suggested in the repo issues or the [matrix room ](https://matrix.to/#/#hy3:outfoxxed.me ).
2023-04-19 02:56:11 -07:00
2023-07-22 02:58:51 -07:00
### Demo
< video width = "640" height = "360" controls = "controls" src = "https://user-images.githubusercontent.com/83010835/255322916-85ae8196-8b12-4e15-b060-9872db10839f.mp4" > < / video >
2023-04-19 02:56:11 -07:00
### Stability
2023-09-23 00:43:21 -07:00
hy3 has a tagged release for each hyprland update, and master tracks hyprland's main branch.
If you are running a release version of hyprland then use the matching tagged hy3 version.
If you are running an untagged hyprland release then use the `master` branch of hy3.
2023-07-31 22:04:53 -07:00
2023-09-23 00:43:21 -07:00
Commits are tested before pushing and will build against the hyprland release **in the flake.lock file** .
There may be a mismatch with hyprland's main branch. If hy3 fails to build against hyprland's main branch
please make an issue or ping me in the [hy3 matrix room ](https://matrix.to/#/#hy3-support:outfoxxed.me ).
Tagged hy3 versions are always checked against the corrosponding hyprland tag.
2023-07-31 22:04:53 -07:00
If you encounter any bugs, please report them in the issue tracker.
2023-04-19 02:56:11 -07:00
When reporting bugs, please include:
- Commit hash of the version you are running.
2023-07-31 22:04:53 -07:00
- Steps to reproduce the bug (if you can figure them out)
- backtrace of the crash (if applicable)
If you are too lazy to use the issue tracker, please at least ping `@outfoxxed:outfoxxed.me`
in the [matrix room ](https://matrix.to/#/#hy3-support:outfoxxed.me ) with your bug information.
## Installation
2023-09-23 00:43:21 -07:00
> [!IMPORTANT]
> The master branch of hy3 follows the master branch of hyprland.
> Attempting to use a mismatched hyprland release will result in failure when building or loading hy3.
>
> To use hy3 against a release version of hyprland,
> check out the matching hy3 tag for the hyprland version.
> hy3 tags are formatted as `hl{version}` where `{version}` matches the release version of hyprland.
2023-07-31 22:04:53 -07:00
### Nix
#### Hyprland home manager module
Assuming you use hyprland's home manager module, you can easily integrate hy3 by adding it to the plugins array.
```nix
# flake.nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
home-manager = {
url = "github:nix-community/home-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
hyprland.url = "github:hyprwm/Hyprland";
2023-09-23 00:43:21 -07:00
# or "github:hyprwm/Hyprland?ref=v{version}" for a release version of hyprland
2023-07-31 22:04:53 -07:00
hy3 = {
url = "github:outfoxxed/hy3";
2023-09-23 00:43:21 -07:00
# or "github:outfoxxed/hy3?ref=hl{version}" for a release version of hyprland
2023-07-31 22:04:53 -07:00
inputs.hyprland.follows = "hyprland";
};
};
outputs = { nixpkgs, home-manager, hyprland, hy3, ... }: {
homeConfigurations."user@hostname " = home-manager.lib.homeManagerConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
2023-04-19 02:56:11 -07:00
2023-07-31 22:04:53 -07:00
modules = [
hyprland.homeManagerModules.default
{
wayland.windowManager.hyprland = {
enable = true;
plugins = [ hy3.packages.x86_64-linux.hy3 ];
};
}
];
};
};
}
```
#### Manual (Nix)
hy3's binary is availible as `${hy3.packages.<system>.hy3}/lib/libhy3.so` , so you can also
directly use it in your hyprland config like so:
```nix
# ...
wayland.windowManager.hyprland = {
# ...
extraConfig = ''
plugin = ${hy3.packages.x86_64-linux.hy3}/lib/libhy3.so
'';
};
```
### Arch (AUR)
2023-09-30 01:00:35 -07:00
> [!IMPORTANT]
> Pacman is not very reliable when it comes to building packages in the correct order.
> If hy3 fails to load or build, crashes randomly or behaves oddly (commonly dispatchers stop working)
> then your packages likely updated in the wrong order, or you have hyprland headers in `/usr/local`.
>
> To fix this, remove `/usr/include/hyprland`, `/usr/local/include/hyprland`, `/usr/share/pkgconfig/hyprland.pc` and `/usr/local/share/pkgconfig/hyprland.pc`,
> then reinstall hyprland and hy3.
>
> If you know how to fix this please open an issue or pr, or message `@outfoxxed:outfoxxed.me` in the [matrix room](https://matrix.to/#/#hy3-support:outfoxxed.me).
hy3 stable (for arch's `hyprland` package) is availible on the AUR as [hy3 ](https://aur.archlinux.org/packages/hy3 ).
hy3-git (for `hyprland-git` on the AUR, unofficial package) is availible on the AUR as [hy3-git ](https://aur.archlinux.org/packages/hy3-git ).
Both packages install hy3 as `/usr/lib/libhy3.so` .
You can enable it in your hyprland configuration by adding the following line anywhere in your `hyprland.conf`
```conf
plugin = /usr/lib/libhy3.so
```
2023-07-31 22:04:53 -07:00
### Manual
Install hyprland, including its headers and pkg-config file, then run the following commands:
```sh
cmake -DCMAKE_BUILD_TYPE=Debug -B build
cmake --build build
```
The plugin will be located at `build/libhy3.so` , and you can load it normally
(See [the hyprland wiki ](https://wiki.hyprland.org/Plugins/Using-Plugins/#installing--using-plugins ) for details.)
Note that the hyprland headers and pkg-config file **MUST be installed correctly, for the target version of hyprland** .
2023-04-19 02:56:11 -07:00
## Configuration
2023-09-23 00:43:21 -07:00
> [!IMPORTANT]
> The configuration listed below is for the current hy3 commit.
> If you are using a release version of hy3 then make sure you are
> reading the tagged revision of this readme.
2023-04-19 03:07:05 -07:00
Set your `general:layout` to `hy3` in hyprland.conf.
2023-04-19 02:56:11 -07:00
hy3 requires using a few custom dispatchers for normal operation.
In your hyprland config replace the following dispatchers:
- `movefocus` -> `hy3:movefocus`
- `movewindow` -> `hy3:movewindow`
You can use `hy3:makegroup` to create a new split.
2023-07-31 22:04:53 -07:00
The [dispatcher list ](#dispatcher-list ) and [config fields ](#config-fields ) sections have all the
configuration options, and some explanation as to what they do.
2023-08-01 01:45:19 -07:00
[The hyprland config in my dots ](https://git.outfoxxed.me/outfoxxed/nixnew/src/branch/master/modules/hyprland/hyprland.conf ) can also be used as a reference.
2023-07-31 22:04:53 -07:00
2023-05-26 20:13:32 -07:00
### Config fields
```conf
plugin {
hy3 {
# disable gaps when only one window is onscreen
2023-08-01 01:45:19 -07:00
no_gaps_when_only = < bool > # default: false
2023-06-02 01:32:24 -07:00
2023-07-31 21:28:21 -07:00
# policy controlling what happens when a node is removed from a group,
# leaving only a group
# 0 = remove the nested group
# 1 = keep the nested group
2023-08-01 01:45:19 -07:00
# 2 = keep the nested group only if its parent is a tab group
node_collapse_policy = < int > # default: 2
2023-07-31 21:28:21 -07:00
2023-06-04 22:05:21 -07:00
# offset from group split direction when only one window is in a group
2023-08-01 01:45:19 -07:00
group_inset = < int > # default: 10
2023-06-04 22:05:21 -07:00
2023-12-02 12:52:00 +01:00
# scale factor of windows on the special workspace
special_scale_factor = < float > # default: 0.8
2023-10-23 02:47:55 -07:00
# if a tab group will automatically be created for the first window spawned in a workspace
tab_first_window = < bool >
2023-06-04 17:37:27 -07:00
# tab group settings
tabs {
# height of the tab bar
2023-08-01 01:45:19 -07:00
height = < int > # default: 15
2023-06-02 01:32:24 -07:00
2023-06-04 17:37:27 -07:00
# padding between the tab bar and its focused node
2023-08-01 01:45:19 -07:00
padding = < int > # default: 5
2023-06-02 01:32:24 -07:00
2023-06-04 17:37:27 -07:00
# the tab bar should animate in/out from the top instead of below the window
2023-08-01 01:45:19 -07:00
from_top = < bool > # default: false
2023-06-03 02:00:50 -07:00
2023-06-04 17:37:27 -07:00
# rounding of tab bar corners
2023-08-01 01:45:19 -07:00
rounding = < int > # default: 3
# render the window title on the bar
render_text = < bool > # default: true
2023-06-02 01:32:24 -07:00
2023-06-04 17:37:27 -07:00
# font to render the window title with
2023-08-01 01:45:19 -07:00
text_font = < string > # default: Sans
2023-06-02 01:32:24 -07:00
2023-06-04 17:37:27 -07:00
# height of the window title
2023-08-01 01:45:19 -07:00
text_height = < int > # default: 8
2023-06-04 17:37:27 -07:00
# left padding of the window title
2023-08-01 01:45:19 -07:00
text_padding = < int > # default: 3
2023-06-04 17:37:27 -07:00
# active tab bar segment color
2023-08-01 01:45:19 -07:00
col.active = < color > # default: 0xff32b4ff
2023-06-04 17:37:27 -07:00
# urgent tab bar segment color
2023-08-01 01:45:19 -07:00
col.urgent = < color > # default: 0xffff4f4f
2023-06-04 17:37:27 -07:00
# inactive tab bar segment color
2023-08-01 01:45:19 -07:00
col.inactive = < color > # default: 0x80808080
2023-06-04 17:37:27 -07:00
# active tab bar text color
2023-08-01 01:45:19 -07:00
col.text.active = < color > # default: 0xff000000
2023-06-04 17:37:27 -07:00
# urgent tab bar text color
2023-08-01 01:45:19 -07:00
col.text.urgent = < color > # default: 0xff000000
2023-06-04 17:37:27 -07:00
# inactive tab bar text color
2023-08-01 01:45:19 -07:00
col.text.inactive = < color > # default: 0xff000000
2023-06-04 17:37:27 -07:00
}
2023-08-01 01:00:56 -07:00
# autotiling settings
autotile {
# enable autotile
2023-08-01 01:45:19 -07:00
enable = < bool > # default: false
2023-08-01 01:00:56 -07:00
# make autotile-created groups ephemeral
2023-08-01 01:45:19 -07:00
ephemeral_groups = < bool > # default: true
2023-08-01 01:00:56 -07:00
# if a window would be squished smaller than this width, a vertical split will be created
# -1 = never automatically split vertically
# 0 = always automatically split vertically
# < number > = pixel height to split at
2023-08-01 01:45:19 -07:00
trigger_width = < int > # default: 0
2023-08-01 01:00:56 -07:00
# if a window would be squished smaller than this height, a horizontal split will be created
# -1 = never automatically split horizontally
# 0 = always automatically split horizontally
# < number > = pixel height to split at
2023-08-01 01:45:19 -07:00
trigger_height = < int > # default: 0
2023-09-13 11:47:08 +01:00
# a space or comma separated list of workspace ids where autotile should be enabled
2023-09-14 11:29:10 +01:00
# it's possible to create an exception rule by prefixing the definition with "not:"
# workspaces = 1,2 # autotiling will only be enabled on workspaces 1 and 2
# workspaces = not:1,2 # autotiling will be enabled on all workspaces except 1 and 2
2023-09-13 11:47:08 +01:00
workspaces = < string > # default: all
2023-08-01 01:00:56 -07:00
}
2023-05-26 20:13:32 -07:00
}
}
```
2023-04-19 02:56:11 -07:00
### Dispatcher list
2023-07-19 03:53:23 -07:00
- `hy3:makegroup, <h | v | opposite | tab>, [ephemeral | force_ephemeral]` - make a vertical / horizontal split or tab group
- `ephemeral` - the group will be removed once it contains only one node. does not affect existing groups.
- `force_ephemeral` - same as ephemeral, but converts existing single windows groups.
2023-08-19 10:44:52 -04:00
- `hy3:changegroup, <h | v | tab | untab | toggletab | opposite>` - change the group the node belongs to, to a different layout
2023-08-16 08:39:58 +01:00
- `untab` will untab the group if it was previously tabbed
2023-08-19 10:44:52 -04:00
- `toggletab` will untab if group is tabbed, and tab if group is untabbed
2023-08-17 07:46:14 +01:00
- `opposite` will toggle between horizontal and vertical layouts if the group is not tabbed.
2023-08-18 08:07:38 +01:00
- `hy3:setephemeral, <true | false>` - change the ephemerality of the group the node belongs to
2023-06-15 00:27:02 -07:00
- `hy3:movefocus, <l | u | d | r | left | down | up | right>, [visible]` - move the focus left, up, down, or right
2023-06-11 23:00:24 -07:00
- `visible` - only move between visible nodes, not hidden tabs
2023-08-20 03:13:08 -07:00
- `hy3:movewindow, <l | u | d | r | left | down | up | right>, [once], [visible]` - move a window left, up, down, or right
2023-05-10 00:42:53 -07:00
- `once` - only move directly to the neighboring group, without moving into any of its subgroups
2023-08-20 03:13:08 -07:00
- `visible` - only move between visible nodes, not hidden tabs
2023-06-25 15:29:02 -07:00
- `hy3:killactive` - close all windows in the focused node
2023-06-11 23:00:24 -07:00
- `hy3:changefocus, <top | bottom | raise | lower | tab | tabnode>`
2023-06-11 22:19:43 -07:00
- `top` - focus all nodes in the workspace
- `bottom` - focus the single root selection window
- `raise` - raise focus one level
- `lower` - lower focus one level
- `tab` - raise focus to the nearest tab
- `tabnode` - raise focus to the nearest node under the tab
2023-06-28 21:38:51 -07:00
- `hy3:focustab <mouse | [l | r | left | right | index, <index>], [prioritize_hovered | require_hovered], [wrap]>`
2023-06-15 00:27:02 -07:00
- `mouse` - focus the tab under the mouse, works well with a non consuming bind, e.g.
```conf
# binds hy3:focustab to lmb and still allows windows to receive clicks
bindn = , mouse:272, hy3:focustab, mouse
```
2023-06-28 21:38:51 -07:00
- `l | r | left | right` - direction to change focus towards
- `index, <index>` - select the `index` th tab
2023-06-15 00:27:02 -07:00
- `prioritize_hovered` - prioritize the tab group under the mouse when multiple are stacked. use the lowest group if none is under the mouse.
- `require_hovered` - affect the tab group under the mouse. do nothing if none are hovered.
- `wrap` - wrap to the opposite size of the tab bar if moving off the end
2023-04-19 02:56:11 -07:00
- `hy3:debugnodes` - print the node tree into the hyprland log
2023-08-09 02:21:18 -07:00
- :warning: **ALPHA QUALITY** `hy3:setswallow, <true | false | toggle>` - set the containing node's window swallow state
- :warning: **ALPHA QUALITY** `hy3:expand, <expand | shrink | base>` - expand the current node to cover other nodes
- `expand` - expand by one node
- `shrink` - shrink by one node
- `base` - undo all expansions