From bd78d1448e1eaa0b133dcc0bdd0ab7389e9e0395 Mon Sep 17 00:00:00 2001 From: Yuxuan Shui Date: Thu, 1 Aug 2024 04:58:12 +0100 Subject: [PATCH] docs: rewrite the "FORMAT OF CONDITIONS" section Signed-off-by: Yuxuan Shui --- man/picom.1.adoc | 91 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 61 insertions(+), 30 deletions(-) diff --git a/man/picom.1.adoc b/man/picom.1.adoc index c171c2ea31..fab930b95e 100644 --- a/man/picom.1.adoc +++ b/man/picom.1.adoc @@ -363,35 +363,78 @@ FORMAT OF CONDITIONS -------------------- Some options accept a condition string to match certain windows. A condition string is formed by one or more conditions, joined by logical operators. -A condition with "exists" operator looks like this: +Formal grammar for a condition looks like this: - [] + Condition <- Term ('||' Term)* + Term <- Item ('&&' Item)* + Item <- '!'? Target '@'? ('[' Index ']')? (Operator Pattern)? | '(' Condition ')' -With equals operator it looks like: +Concretely speaking, a condition is a sequence of one or more simple pattern matching __Item__s, joined by logical operators `&&` (and) and `||` (or). `&&` has higher precedence than `||`. Both operators are left-associative. Parentheses can be used to raise precedence. If an _Item_ has a leading negation operator (`!`), the result of the item is negated. - [] = +Inside an _Item_: -With greater-than/less-than operators it looks like: +_Target_:: is either a predefined target name, or the name of a window property to match. - [] +Supported predefined targets are: ::: -_NEGATION_ (optional) is one or more exclamation marks; + `x`, `y`, `x2`, `y2`:::: + Window coordinates, from the top-left corner of the window (`(x, y)`) to the bottom-right corner (`(x2, y2)`). -_TARGET_ is either a predefined target name, or the name of a window property to match. Supported predefined targets are `x`, `y`, `x2` (`x` + `widthb`), `y2` (like `x2`), `width`, `height`, `widthb` (`width` + 2 * `border_width`), `heightb` (like `widthb`), `border_width`, `fullscreen`, `override_redirect`, `argb` (whether the window has an ARGB visual), `focused`, `group_focused` (whether the window belongs to the focused window group), `wmwin` (whether the window looks like a WM window, i.e. has no child window with `WM_STATE` and is not override-redirected), `bounding_shaped`, `rounded_corners` (requires *--detect-rounded-corners*, note this has no relation to *--corner-radius*), `window_type` (window type in string), `name`, `class_g` (= `WM_CLASS[1]`), `class_i` (= `WM_CLASS[0]`), and `role`. + `width`, `height`:::: + Size of the window. -_CLIENT/FRAME_ is a single `@` if the window attribute should be be looked up on client window, nothing if on frame window; + `widthb`, `heightb`:::: + Like `width` and `height`, but including the window border. -_INDEX_ (optional) is the index number of the property to look up. For example, `[2]` means look at the third value in the property. If not specified, the first value (index `[0]`) is used implicitly. Use the special value `[*]` to perform matching against all available property values using logical OR. Do not specify it for predefined targets. + `border_width`:::: + Width of the window border. -'OP QUALIFIER' (optional), applicable only for equals operator, could be `?` (ignore-case). + `fullscreen`:::: + Whether the window is fullscreen. If *--no-ewmh-fullscreen* is set, this is determined by the window size and position; otherwise, it is determined by the _pass:[_]NET_WM_STATE_FULLSCREEN_ property. -'MATCH TYPE' (optional), applicable only for equals operator, could be nothing (exact match), `*` (match anywhere), `^` (match from start), `%` (wildcard), or `~` (PCRE regular expression). + `override_redirect`:::: + Whether the window is override-redirect. -_OPERATOR_ is one of `=` (equals), `<`, `>`, `<=`, `=>`, or nothing (exists). Exists operator checks whether a property exists on a window (but for predefined targets, exists means != 0 then). + `argb`:::: + Whether the window has an ARGB visual. -_PATTERN_ is either an integer or a string enclosed by single or double quotes. Python-3-style escape sequences are supported in the string format. + `focused`:::: + Whether the window is focused. -Supported logical operators are `&&` (and) and `||` (or). `&&` has higher precedence than `||`, left-to-right associativity. Use parentheses to change precedence. + `group_focused`:::: + Whether the window is in the same window group as the focused window. This requires *--detect-transient* or *--detect-client-leader*. + + `wmwin`:::: + Whether the window looks like a WM window, i.e. has no client window and is not override-redirected. + + `bounding_shaped`:::: + Whether the window has a bounding shape. + + `rounded_corners`:::: + Whether the window bounding shape only has rounded corners, and is otherwise rectangular. This implies `bounding_shaped`. Requires *--detect-rounded-corners*. This has no relation to *--corner-radius*. + + `window_type`:::: + Window type, as defined by _pass:[_]NET_WM_WINDOW_TYPE_. Name only, e.g. _normal_ means _pass:[_]NET_WM_WINDOW_TYPE_NORMAL_. + + `name`:::: + Name of the window. This is either _pass:[_]NET_WM_NAME_ or _pass:[_]WM_NAME_. + + `class_i`, class_g`:::: + Instance and general class of the window. This is the first and second value of _pass:[_]WM_CLASS_, respectively. + + `role`:::: + Window role. This is the value of _pass:[_]WM_WINDOW_ROLE_. + ++ +_Target_ can be followed by an optional `@` if the window attribute should be be looked up on client window. Otherwise the frame window will be used. + +_Index_:: is the index number of the property to look up. For example, `[2]` returns the third value of the property. If not specified, the first value (index `[0]`) is used implicitly. Use the special value `[*]` to perform matching against all available property values using logical OR. None of the predefined targets have multiple values, so do not use this with them. + +_Operator_ and _Pattern_:: define how the _Target_ will be matched. They can be omitted together, in which case the existence of the window property is checked if the _Target_ is not a predefined target; for a predefined _Target_, omitting _Operator_ and _Pattern_ is equivalent to writing `!= 0`. ++ +Available operators change depends on the type of _Target_ being matched. If the target is a number, the operators are `=`, `>`, `<`, `>=`, `pass:[<=]`, as well as their negation, obtained by prefixing the operator with `!` (e.g. `!=`, `!>`, etc.). If the target is a string, the operators are `=` (strict equal), `pass:[*]=` (substring match), `^=` (starts with), `%=` (match with glob), `~=` (match with regex), as well as their case insensitive variants `?=`, `pass:[*]?=`, `^?=`, `%?=`, `~?=`. String operators can be negated by prefixing the operator with `!` as well (e.g. `!=`, `!pass:[*]=`, etc.). ++ +_Pattern_ is either an integer or a string enclosed by single or double quotes. Python-3-style escape sequences are supported for strings. Boolean values are interpreted as integers, i.e. writing `true` is equivalent to `1`, and `false` `0`. Examples: @@ -425,23 +468,11 @@ Examples: _NET_FRAME_EXTENTS@[2] < 20 || !_NET_FRAME_EXTENTS@ # The pattern here will be parsed as "dd4" name = "\x64\x64\o64" + # These two are equivalent + name = 'Firefox' || name = 'Chromium' && class_i = 'Navigator' + name = 'Firefox' || (name = 'Chromium' && class_i = 'Navigator') -LEGACY FORMAT OF CONDITIONS ---------------------------- - -This is the old condition format we once used. Support of this format might be removed in the future. - - condition = TARGET:TYPE[FLAGS]:PATTERN - -_TARGET_ is one of "n" (window name), "i" (window class instance), "g" (window general class), and "r" (window role). - -_TYPE_ is one of "e" (exact match), "a" (match anywhere), "s" (match from start), "w" (wildcard), and "p" (PCRE regular expressions, if compiled with the support). - -_FLAGS_ could be a series of flags. Currently the only defined flag is "i" (ignore case). - -_PATTERN_ is the actual pattern string. - SHADER INTERFACE ----------------