How windows are determined to be eligible for management

[koekeishiya]

The following is an attempt to describe how exactly yabai determines that a window is eligible for management. "Management" entails that the window is allowed to have its properties modfied. If a window is not eligible for management, yabai has not touched a single property of said window; it is only tracked for debug purposes (e.g: we only read information about the window).

The situation is a bit messy because a lot of the elements that are visible on the screen on macOS is reported as "a window". There are multiple attributes reported through APIs that we can use to determine which type of window it is, but very often these attributes are not set correctly by the application/window. This applies to both Apple and third-party software, and makes this seemingly simple job of distinguishing between an application window, dialog window, popup window, autocomplete window, language input-switcher window, etc. quite difficult.

TODO: write stuff

• Windows with subrole kAXUnknown are fully ignored (not managed, not tracked for debug purposes).
• Detect if root-window. if no; window is not eligible for management (tracked for debug purposes -- read only).
• A real window has AXRole = AXWindow and AXSubrole = AXStandardWindow, AXDialog, or AXFloatingWindow.
• If window DOES NOT have a level of 0 (kCGNormalWindowLevelKey) it will be treated as a floating window permanently (unless a window rule has been created that sets manage=on)
• If window has AXRole and AXSubrole identifying it as a real window OR a window rule has been created that sets manage=on, this window is eligible for management.
• If window does not have AXRole and AXSubrole identifting as a real window AND no window rule with manage=on, window is not eligible and only tracked for debug purposes.
• Even if a window is eligible for management, only standard windows (subset of a real window -- e.g not dialogs) can be tiled unless a rule specifies the AXRole and AXSubrole filter with the manage=on property.
• Only windows eligible for management is reported through window_created and window_destroyed signals.

[localauthor]

Just FYI, for anyone interested/searching, this change broke management of Emacs frames for me. Adding this rule seems to have fixed it:

yabai -m rule --add app="Emacs" role="AXTextField" subrole="AXStandardWindow" manage=on

[rcorre]

I've found that about 50% of the time when I open a wezterm window, it has an empty role/subrole, which results in the window being unmanaged.

These are two terminals I opened one after the other: manage.json unmanage.json

I tried yabai -m rule --add app="wezterm-gui" manage=on but it does not seem to do anything (I confirmed wezterm-gui is the app string from yabai -m query).

Any yabai -m window commands issued to that window print "could not locate the window to act on!".