hyprwm/hyprland-plugins
1
0
Fork 0
mirror of https://github.com/hyprwm/hyprland-plugins.git synced 2026-05-07 11:18:01 +02:00
Code Issues Projects Releases Packages Wiki Activity

enhance: Conslidate README.md and consistent formatting

Browse source
This commit is contained in:
sandwich 2025-10-11 11:27:33 +02:00
parent 32f309cadc
commit 774e2c4d33
1 changed files with 78 additions and 96 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

174
hyprexpo/README.md
View file

@ -80,21 +80,21 @@ plugin {
}
```
### Configuration
## Configuration
#### Layout & Display
### Layout & Display
| key | type | description | default |
| --- | --- | --- | --- |
| `plugin:hyprexpo:columns` | int | how many desktops per row | `3` |
| `plugin:hyprexpo:gaps_in` | int | inner gaps between tiles (px) | `5` |
| `plugin:hyprexpo:gaps_out` | int | outer margin around the grid (px) | `0` |
| `plugin:hyprexpo:gaps_in` | int | inner spacing between tiles (px) | `5` |
| `plugin:hyprexpo:gaps_out` | int | outer margin around grid (px), animated during open/close | `0` |
| `plugin:hyprexpo:bg_col` | color | grid background color | `rgb(111111)` |
| `plugin:hyprexpo:workspace_method` | string | placement: `center current` or `first <ws>` | `center current` |
| `plugin:hyprexpo:skip_empty` | bool (int) | skip empty workspaces (`1`) or not (`0`) | `0` |
| `plugin:hyprexpo:skip_empty` | bool (int) | skip empty workspaces using selector `m` (`1`) or show all with `r` (`0`) | `0` |
| `plugin:hyprexpo:gesture_distance` | int | swipe distance considered "max" (px) | `200` |
#### Tile Appearance
### Tile Appearance
| key | type | description | default |
| --- | --- | --- | --- |
@ -102,55 +102,55 @@ plugin {
| `plugin:hyprexpo:tile_rounding_power` | float | rounding power (curve exponent) | `2.0` |
| `plugin:hyprexpo:tile_rounding_focus` | int | focus tile radius (`-1` = inherit) | `-1` |
| `plugin:hyprexpo:tile_rounding_current` | int | current tile radius (`-1` = inherit) | `-1` |
| `plugin:hyprexpo:border_style` | string | `simple` \| `hypr` \| `hyprland` | `simple` |
| `plugin:hyprexpo:border_style` | string | border rendering: `simple` (solid), `hypr` (3-layer), `hyprland` (2-color gradient) | `simple` |
| `plugin:hyprexpo:border_width` | int | border thickness (px) | `2` |
| `plugin:hyprexpo:border_color_current` | color | color for current tile border (fallback) | `rgb(66ccff)` |
| `plugin:hyprexpo:border_color_focus` | color | color for focus tile border (fallback) | `rgb(ffcc66)` |
| `plugin:hyprexpo:border_grad_current` | string | hyprland gradient for current, e.g. `rgba(33ccffee) rgba(00ff99ee) 45deg` | empty |
| `plugin:hyprexpo:border_grad_focus` | string | hyprland gradient for focus | empty |
| `plugin:hyprexpo:border_color_current` | color | current tile border color | `rgb(66ccff)` |
| `plugin:hyprexpo:border_color_focus` | color | focused tile border color | `rgb(ffcc66)` |
| `plugin:hyprexpo:border_grad_current` | string | gradient for current tile (hyprland style only), e.g. `rgba(33ccffee) rgba(00ff99ee) 45deg` | empty |
| `plugin:hyprexpo:border_grad_focus` | string | gradient for focused tile (hyprland style only) | empty |
#### Labels
### Workspace Labels
| key | type | description | default |
| --- | --- | --- | --- |
| `plugin:hyprexpo:label_enable` | bool (int) | enable labels | `1` |
| `plugin:hyprexpo:label_text_mode` | string | `token` | `index` | `id` | `token` |
| `plugin:hyprexpo:label_token_map` | string | override up to 50 tokens (comma‑sep). Empty entries skip | empty |
| `plugin:hyprexpo:label_font_size` | int | base font size (px) | `16` |
| `plugin:hyprexpo:label_position` | string | `top-left` | `top-right` | `bottom-left` | `bottom-right` | `center` | `center` |
| `plugin:hyprexpo:label_offset_x` | int | offset from position anchor (px) | `0` |
| `plugin:hyprexpo:label_offset_y` | int | offset from position anchor (px) | `0` |
| `plugin:hyprexpo:label_show` | string | `always` | `hover` | `focus` | `hover+focus` | `current+focus` | `never` | `always` |
| `plugin:hyprexpo:label_color_default` | color | default label color | `rgb(ffffff)` |
| `plugin:hyprexpo:label_color_hover` | color | hover label color | `rgb(eeeeee)` |
| `plugin:hyprexpo:label_color_focus` | color | focus label color | `rgb(ffcc66)` |
| `plugin:hyprexpo:label_color_current` | color | current label color | `rgb(66ccff)` |
| `plugin:hyprexpo:label_enable` | bool (int) | enable workspace labels | `1` |
| `plugin:hyprexpo:label_text_mode` | string | content: `token` (1,2..9,0,a-z), `index` (visual order), `id` (workspace ID) | `token` |
| `plugin:hyprexpo:label_token_map` | string | override up to 50 tokens (comma-sep), e.g. `1,2,3,,,6` (empty entries skip) | empty |
| `plugin:hyprexpo:label_position` | string | anchor: `top-left` \| `top-right` \| `bottom-left` \| `bottom-right` \| `center` | `center` |
| `plugin:hyprexpo:label_offset_x` | int | horizontal offset from anchor (px) | `0` |
| `plugin:hyprexpo:label_offset_y` | int | vertical offset from anchor (px) | `0` |
| `plugin:hyprexpo:label_show` | string | visibility: `always` \| `hover` \| `focus` \| `hover+focus` \| `current+focus` \| `never` | `always` |
| `plugin:hyprexpo:label_color_default` | color | default state text color | `rgb(ffffff)` |
| `plugin:hyprexpo:label_color_hover` | color | hover state text color | `rgb(eeeeee)` |
| `plugin:hyprexpo:label_color_focus` | color | focus state text color | `rgb(ffcc66)` |
| `plugin:hyprexpo:label_color_current` | color | current workspace text color | `rgb(66ccff)` |
| `plugin:hyprexpo:label_scale_hover` | float | scale multiplier on hover | `1.0` |
| `plugin:hyprexpo:label_scale_focus` | float | scale multiplier on focus | `1.0` |
| `plugin:hyprexpo:label_bg_enable` | bool (int) | draw background “bubble” | `1` |
| `plugin:hyprexpo:label_bg_shape` | string | `circle` | `square` | `rounded` | `circle` |
| `plugin:hyprexpo:label_bg_rounding` | int | radius for `rounded` shape (px) | `8` |
| `plugin:hyprexpo:label_bg_color` | color | bubble color | `rgba(00000088)` |
| `plugin:hyprexpo:label_padding` | int | bubble padding (px) | `8` |
| `plugin:hyprexpo:label_font_size` | int | base font size (px) | `16` |
| `plugin:hyprexpo:label_font_family` | string | Pango font family | `Sans` |
| `plugin:hyprexpo:label_font_bold` | bool (int) | bold | `0` |
| `plugin:hyprexpo:label_font_italic` | bool (int) | italic | `0` |
| `plugin:hyprexpo:label_text_underline` | bool (int) | underline | `0` |
| `plugin:hyprexpo:label_text_strikethrough` | bool (int) | strikethrough | `0` |
| `plugin:hyprexpo:label_pixel_snap` | bool (int) | snap to integer pixels | `1` |
| `plugin:hyprexpo:label_font_bold` | bool (int) | bold text | `0` |
| `plugin:hyprexpo:label_font_italic` | bool (int) | italic text | `0` |
| `plugin:hyprexpo:label_text_underline` | bool (int) | underline text | `0` |
| `plugin:hyprexpo:label_text_strikethrough` | bool (int) | strikethrough text | `0` |
| `plugin:hyprexpo:label_pixel_snap` | bool (int) | snap positions to integer pixels for sharper text | `1` |
| `plugin:hyprexpo:label_center_adjust_x` | int | manual center nudge X (px) | `0` |
| `plugin:hyprexpo:label_center_adjust_y` | int | manual center nudge Y (px) | `0` |
| `plugin:hyprexpo:label_bg_enable` | bool (int) | draw background bubble behind text | `1` |
| `plugin:hyprexpo:label_bg_shape` | string | bubble shape: `circle` \| `square` \| `rounded` | `circle` |
| `plugin:hyprexpo:label_bg_rounding` | int | radius for `rounded` shape (px) | `8` |
| `plugin:hyprexpo:label_bg_color` | color | bubble background color | `rgba(00000088)` |
| `plugin:hyprexpo:label_padding` | int | bubble padding around text (px) | `8` |
#### Keyboard Navigation
### Keyboard Navigation
| key | type | description | default |
| --- | --- | --- | --- |
| `plugin:hyprexpo:keynav_enable` | bool (int) | enable keynav + auto submap | `1` |
| `plugin:hyprexpo:keynav_wrap_h` | bool (int) | wrap horizontally | `1` |
| `plugin:hyprexpo:keynav_wrap_v` | bool (int) | wrap vertically | `1` |
| `plugin:hyprexpo:keynav_reading_order` | bool (int) | use row‑major for horizontal moves | `0` |
| `plugin:hyprexpo:keynav_enable` | bool (int) | enable keyboard navigation + auto submap | `1` |
| `plugin:hyprexpo:keynav_wrap_h` | bool (int) | wrap horizontally at row edges | `1` |
| `plugin:hyprexpo:keynav_wrap_v` | bool (int) | wrap vertically at column edges | `1` |
| `plugin:hyprexpo:keynav_reading_order` | bool (int) | row-major horizontal moves (wrap at ends if both h+v wrap enabled) | `0` |
#### Scrolling Overview (Layout-Specific)
### Scrolling Overview (Layout-Specific)
When using Hyprland's scrolling layout, HyprExpo automatically switches to a vertical scrolling overview mode.
@ -159,34 +159,51 @@ When using Hyprland's scrolling layout, HyprExpo automatically switches to a ver
| `plugin:hyprexpo:scrolling:scroll_moves_up_down` | bool (int) | if enabled, mouse wheel scrolls through workspaces; if disabled, mouse wheel zooms | `1` |
| `plugin:hyprexpo:scrolling:default_zoom` | float | default zoom level on overview open (0.1 - 0.9) | `0.5` |
**Note:** Scrolling overview mode does not support keyboard navigation. Mouse/trackpad interaction is the primary input method.
**Note:** Scrolling overview mode does not support keyboard navigation. Mouse/trackpad interaction is the primary input method for this layout.
### Keywords
## Usage
| name | description | arguments |
| -- | -- | -- |
| hyprexpo-gesture | same as gesture, but for hyprexpo gestures. Supports: `expo`. | Same as gesture |
### Dispatchers
**Main expo dispatcher:**
### Binding
```bash
# hyprland.conf
bind = MODIFIER, KEY, hyprexpo:expo, OPTION
bind = SUPER, g, hyprexpo:expo, <option>
```
Example:
| option | description |
| --- | --- |
| `toggle` | show overview if hidden, hide if shown |
| `on` / `enable` | show overview |
| `off` / `disable` | hide overview |
| `select` | select the hovered workspace |
**Keyboard navigation dispatchers** (active during overview):
| dispatcher | argument | description |
| --- | --- | --- |
| `hyprexpo:kb_focus` | `left` \| `right` \| `up` \| `down` | move focus across tiles |
| `hyprexpo:kb_confirm` | none | select the focused tile |
| `hyprexpo:kb_selecti` | `<index>` | select by 1-based visual index (1-46) |
| `hyprexpo:kb_selectn` | `<id>` | select by workspace ID (legacy, 0→10) |
| `hyprexpo:kb_select` | `<token>` | select by single token (1-9, 0, a-z) |
### Example Bindings
```bash
# This will toggle HyprExpo when SUPER+g is pressed
# Toggle overview
bind = SUPER, g, hyprexpo:expo, toggle
# Optional submap for keyboard selection when Hyprexpo is active (index-based, 1..46)
# Keyboard navigation submap (optional)
submap = hyprexpo
# Arrow key navigation
bind = , left, hyprexpo:kb_focus, left
bind = , right, hyprexpo:kb_focus, right
bind = , up, hyprexpo:kb_focus, up
bind = , down, hyprexpo:kb_focus, down
bind = , return, hyprexpo:kb_confirm
# 1..10 via digits (0 -> 10)
# Direct selection via numbers (1-10)
bind = , 1, hyprexpo:kb_selecti, 1
bind = , 2, hyprexpo:kb_selecti, 2
bind = , 3, hyprexpo:kb_selecti, 3
@ -198,7 +215,7 @@ submap = hyprexpo
bind = , 9, hyprexpo:kb_selecti, 9
bind = , 0, hyprexpo:kb_selecti, 10
# 11..20 via SHIFT+digits
# Extended selection via SHIFT+numbers (11-20)
bind = SHIFT, 1, hyprexpo:kb_selecti, 11
bind = SHIFT, 2, hyprexpo:kb_selecti, 12
bind = SHIFT, 3, hyprexpo:kb_selecti, 13
@ -210,7 +227,7 @@ submap = hyprexpo
bind = SHIFT, 9, hyprexpo:kb_selecti, 19
bind = SHIFT, 0, hyprexpo:kb_selecti, 20
# 21..46 via alpha
# Alphabetic selection (21-46)
bind = , a, hyprexpo:kb_selecti, 21
bind = , b, hyprexpo:kb_selecti, 22
bind = , c, hyprexpo:kb_selecti, 23
@ -240,48 +257,13 @@ submap = hyprexpo
submap = reset
```
Here are a list of options you can use:
| option | description |
| --- | --- |
toggle | displays if hidden, hide if displayed
select | selects the hovered desktop
off | hides the overview
disable | same as `off`
on | displays the overview
enable | same as `on`
### Gestures
Keyboard navigation dispatchers (when overview is active):
- `hyprexpo:kb_focus, <left|right|up|down>`: moves focus across tiles (skips invalid).
- Wrapping can be configured with `keynav_wrap_h` and `keynav_wrap_v`.
- Reading order (row-major) for horizontal movement can be enabled with `keynav_reading_order`. At grid ends it will wrap to start/end only if both `keynav_wrap_h` and `keynav_wrap_v` are enabled.
- `hyprexpo:kb_confirm`: selects the focused tile.
- `hyprexpo:kb_selectn, <id>`: selects by workspace id (legacy; `0` → `10`).
- `hyprexpo:kb_selecti, <index>`: selects by 1‑based visual index (recommended for single‑keystroke mapping).
- `hyprexpo:kb_select, <token>`: selects by a single token (1..9, 0, a..z), mainly for symbol‑based configs.
Custom gesture keyword for HyprExpo-specific gestures:
Border styles:
- `simple`: single-color border using `border_width`, `border_color_current`, `border_color_focus`.
- `hypr`: layered border approximating Hyprland’s gradient borders by drawing 3 layers (lightened, base, and darkened). Uses the same base colors and splits the width across layers.
- `hyprland`: 2-color gradient with angle. Provide gradients:
- `plugin:hyprexpo:border_grad_current = rgba(33ccffee) rgba(00ff99ee) 45deg`
- `plugin:hyprexpo:border_grad_focus = rgba(ffdd44ee) rgba(22aaffee) 30deg`
```ini
# Swipe up with 4 fingers to toggle overview
hyprexpo-gesture = swipe:4:up, hyprexpo:expo, toggle
```
Gaps:
- `gaps_in` controls the inner spacing between tiles.
- `gaps_out` adds an outer margin (px) around the grid (animated during open/close).
Labels (numbers):
- `label_position`, `label_offset_x`, `label_offset_y` control placement per tile.
- `label_show` controls when labels are drawn (always/hover/focus/etc.).
- Per-state colors: `label_color_default|hover|focus|current`.
- Per-state scale multipliers: `label_scale_hover|focus`.
- Optional background bubble behind text: `label_bg_*`, `label_padding`.
- Content:
- `label_text_mode = token` (default) uses the token sequence (1..9,0,!,@,#,…,a..z) or `label_token_map` if provided.
- `label_text_mode = index` shows the 1-based visual index.
- `label_text_mode = id` shows the workspace ID.
- Token overrides:
- `label_token_map` accepts up to 50 comma-separated entries to override tokens. Empty entries allowed (skip rendering).
- Font & precision:
- `label_font_family`, `label_font_bold`, `label_font_italic`, `label_text_underline`, `label_text_strikethrough`
- `label_pixel_snap` (default 1) rounds positions to integer pixels for crisper text.
Uses the same syntax as Hyprland's `gesture` keyword.