[feature] [RFC] universal window rules

[yshui]

Problem

picom has many rules that allow the user to customize how each windows are rendered. The way it is implemented currently, we basically have one rule per point of customize. Such as blur-background-exclude for background blurring, fade-exclude for fading, etc. This does not scale well as we introduce more customization possibilities. Look at this:

picom/src/options.c

Lines 955 to 973 in 05c764c

	void options_postprocess_c2_lists(struct c2_state *state, struct x_connection *c,
	struct options *option) {
	if (!(c2_list_postprocess(state, c->c, option->unredir_if_possible_blacklist) &&
	c2_list_postprocess(state, c->c, option->paint_blacklist) &&
	c2_list_postprocess(state, c->c, option->shadow_blacklist) &&
	c2_list_postprocess(state, c->c, option->shadow_clip_list) &&
	c2_list_postprocess(state, c->c, option->fade_blacklist) &&
	c2_list_postprocess(state, c->c, option->blur_background_blacklist) &&
	c2_list_postprocess(state, c->c, option->invert_color_list) &&
	c2_list_postprocess(state, c->c, option->window_shader_fg_rules) &&
	c2_list_postprocess(state, c->c, option->opacity_rules) &&
	c2_list_postprocess(state, c->c, option->rounded_corners_blacklist) &&
	c2_list_postprocess(state, c->c, option->corner_radius_rules) &&
	c2_list_postprocess(state, c->c, option->focus_blacklist) &&
	c2_list_postprocess(state, c->c, option->transparent_clipping_blacklist))) {
	log_error("Post-processing of conditionals failed, some of your "
	"rules might not work");
	}
	}

This list will keep getting longer if we don't find a better approach. Besides that, it is also:

• difficult to implement rules for non-trivial options such as animations
• difficult to not repeating yourself, if you want to set multiple options for the same group of windows
• confusing to have both inclusion and exclusion rules for the same option
• confusing to have both rules, and the wintypes option

Proposal

Introducing a new rules option as the unified way to set per-window options. The design is simple:

rules = ({
    # you write a rule
    match = "class_i = 'firefox'";

    # ... and you set options
    blur-background = false;
},
{
    # ... any number of rules can be created
}, )

Supported options

All options that make sense as a per-window option will be supported. Such as fading, blur-background, shadow, shadow-color, shadow-radius, corner-radius, opacity, animations, full-shadow, redir-ignored, etc.

Multiple matching rules

This style of rules naturally comes with the question of what should happen if multiple rules match. Simply stopping at the first match doesn't really work for us, because that forces user to write very specific rules so they don't overlap. This is difficult and can be confusing.

So instead, picom will always try all of the rules, and combine the options. If the same options is set multiple times in different rule blocks, then the one encountered first in the order of how they appear in the configuration file will be used.

Deprecation plan

No deprecation is planned. All the old rule options, as well as wintypes, will continue to work. But users are encouraged to use the new rules option instead of the old ones. When both styles of rules are present in the configuration, the new rules will be matched first, and only when none of the new rules matches, will picom try any of the old rules.

[pijulius]

@yshui Love the idea!

[absolutelynothelix]

i don't like that "no deprecation is planned". it is "confusing to have both rules, and the wintypes option" and we add yet another way to configure windows.

[yshui]

we add yet another way to configure windows.

The point is rules is self sufficient and can replace all of the old rule options and wintypes.

If you use the old options then you also need to use wintypes, and it's unclear how they interact.

[absolutelynothelix]

@yshui, i'm not against this, my point is that if we won't deprecate the old ways to configure windows we'll end up with three different ways to do this and i doubt it'll be clear for an ordinary user which one to use. i have a feeling that an ordinary user has a mix of the first two and the third one will be added.

[yshui]

@absolutelynothelix that is a very good point. if we deprecate it, i am worried about people getting fatigued updating their config files. and this one is not trivial, unlike the ones before. this is not just changing a option name or something.

so i think it's ok if existing users keep using the old options, if they don't want to change. it's like the new rules option doesn't exist to them. on the other hand i agree we definitely want all new users to use the new option. so maybe we just remove the old options from man page without deprecating them?

[DeveloperGY]

@yshui I feel it would be better to mark the old options in the man pages with a noticeable message that states that they are no longer the intended way of configuring picom rather than removing them from the man page entirely. Many people go to youtube and other forums to learn how to configure picom (not to mention look at other people's configs) and if they find something that they want to look at in the man page they will likely get confused because they cant find it. By marking the option instead it lets them see what it does and how to use it but also lets them know that there is a better way of doing it and helps clear up the confusion when learning.

This approach allows users to keep their old configs, new users to make sense of those old configs, and teaches all users that there is a newer and better way of configuring picom should they wish to use it. It would also allow you to postpone the decision of deprecating the old options by having something like "this could be deprecated in the future" in the message as well. Postponing such a decision will give users time to switch over and learn to the new system, which means that there will be more feedback and not to mention a decrease in the amount of people using the legacy options. It would also allow more time to come up with alternatives to deprecation that could present better opportunities.

I would argue that deprecation would probably be a good idea because if you have too many different ways of doing the same thing, it can make it difficult not only for people to learn how to configure picom, but it would also make it more complicated to help those people because you'd need to be well versed in the way they want to configure it, which could be a little tedious if they use a mix of the different ways. By simplifying how picom is configured it makes it easier to learn, teach, and use, which is something I feel is important for any piece of software.