From a0373702f0876c83a0ad8aac8344876027b926b7 Mon Sep 17 00:00:00 2001
From: Landon Buttars <17345308+Buttars@users.noreply.github.com>
Date: Tue, 3 Dec 2024 21:13:10 -0700
Subject: [PATCH] dispatchers: add documentation for fullscreenstate

This is a WIP and needs feedback to clarify a few things. Specifically whether fullscreen is planned for deprecation and the functionality of state 3 "maximize and fullscreen."
---
 pages/Configuring/Dispatchers.md | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/pages/Configuring/Dispatchers.md b/pages/Configuring/Dispatchers.md
index 053a01f..764cf84 100644
--- a/pages/Configuring/Dispatchers.md
+++ b/pages/Configuring/Dispatchers.md
@@ -37,7 +37,7 @@ layout pages (See the sidebar).
 | setfloating | sets the current window's floating state to true | left empty / `active` for current, or `window` for a specific window |
 | settiled | sets the current window's floating state to false | left empty / `active` for current, or `window` for a specific window |
 | fullscreen | toggles the focused window's fullscreen mode | 0 - fullscreen (takes your entire screen), 1 - maximize (keeps gaps and bar(s)) |
-| fullscreenstate | sets the focused window's fullscreen mode and the one sent to the client | `internal client`, where internal and client can be `-1` - current, `0` - none, `1` - maximize, `2` - fullscreen, `3` - maximize and fullscreen |
+| fullscreenstate | sets the focused window's fullscreen mode and the one sent to the client | `internal client`, where internal (the hyprland window) and client (the application) can be `-1` - current, `0` - none, `1` - maximize, `2` - fullscreen, `3` - maximize and fullscreen. |
 | dpms | sets all monitors' DPMS status. Do not use with a keybind directly. | `on`, `off`, or `toggle`. For specific monitor add monitor name after a space |
 | pin | pins a window (i.e. show it on all workspaces) _note: floating only_ | left empty / `active` for current, or `window` for a specific window |
 | movefocus | moves the focus in a direction | direction |
@@ -235,3 +235,31 @@ address:0x13371337 nomaxsize 0
 address:0x13371337 opaque toggle
 address:0x13371337 immediate unset
 ```
+
+### Fullscreenstate
+
+`fullscreenstate internal client`
+
+The `fullscreenstate` dispatcher decouples the state that Hyprland maintains for a window from the fullscreen state that is communicated to the client.  
+
+`internal` is a reference to the state maintained by Hyprland.
+
+`client` is a reference to the state that the application receives.
+
+| Value | State | Description |
+| --- | --- | --- |
+| -1 | Current | Maintains the current fullscreen state. |
+| 0 | None | Window allocates the space defined by the current layout. |
+| 1 | Maximize | Window takes up the entire working space, keeping the margins. |
+| 2 | Fullscreen | Window takes up the entire screen. |
+| 3 | Maximize and Fullscreen | ??? |
+
+For example:
+
+`fullscreenstate 2 0` Fullscreens the application and keeps the client in non-fullscreen mode.  
+
+This can be used to prevent Chromium-based browsers from going into presentation mode when they detect they have been fullscreened.  
+
+`fullscreenstate 0 2` Keeps the window non-fullscreen, but the client goes into fullscreen mode within the window.
+
+The `fullscreenstate` dispatcher is designed to replace the legacy `fullscreen`. The `fullscreen` dispatcher is planned for deprecation and will be removed in the future.