Clarify usage of compose.swing.render.on.graphics flag

[MatkovIvan]

More clear KDoc + warning based on misusage and questions from community

Release Notes

N/A

[m-sasha]

I'm not sure about printing this. The flag is for the entire process, but you can have both ComposePanel and ComposeWindow in a single app...

[MatkovIvan]

True. The intention here is to notify already wrong configured applications. Ideas are welcome

[m-sasha]

Why is this a global flag, though? Can we not make it an argument to ComposePanel instead?

[MatkovIvan]

Already thought about it, so yes we can. But I don't really won't to remove global flag because despite "experimental" status it's widely adopted

[MatkovIvan]

Why is this a global flag, though?

It was introduced in #601, so for now it's "historically" I guess

[MatkovIvan]

Exposed as another optional/experimental parameter in ComposePanel's constructor

[m-sasha]

Great!

As for this print, I think I personally would prefer not to pollute the output, but I'd leave the decision to @igordmn .
If we do add it, probably better to print to System.err, though (we're in desktopMain here).

[igordmn]

It is valid to open a ComposeWindow inside IntelliJ that can use a global useSwingGraphics for ComposePanel's. Because it is valid, we shouldn't print anything. A better name, something like composePanelUseSwingGraphics, wouldn't cause the issue.

As for a flag, I prefer an argument over it. For historical reasons we can either keep it, or deprecate it.

[m-sasha]

Maybe it should go into RenderSettings below?
Regardless, the documentation of RenderSettings needs updating.

[MatkovIvan]

Probably no.

1. It will be a parameter not only for ComposePanel that I'm trying to avoid in this PR
2. I see a place where it's used only if useSwingGraphics == false

[igordmn]

If we look at the API from user perspective, it might be better to have these parameters under 1 thing, just from ComposePanel user perspective.

The points are valid, but we can fix them by creating something like:

sealed class ComposePanelRenderSettings {
  class LightweightLayer: ComposePanelRenderSettings()
  class HeavyweightLayer(val renderSettings: RenderSettings): ComposePanelRenderSettings 
}

Lightweight, heavyweight - Swing terms.

I think it is better to figure out the shape now rather than trying to avoid big changes. Because we will stuck with it forever, and it looks not consistent to have 2 params that affect rendering separately.

[igordmn]

It is valid to open a ComposeWindow inside IntelliJ that can use a global useSwingGraphics for ComposePanel's. Because it is valid, we shouldn't print anything. A better name, something like composePanelUseSwingGraphics, wouldn't cause the issue.

As for a flag, I prefer an argument over it. For historical reasons we can either keep it, or deprecate it.

[igordmn]

If we look at the API from user perspective, it might be better to have these parameters under 1 thing, just from ComposePanel user perspective.

The points are valid, but we can fix them by creating something like:

sealed class ComposePanelRenderSettings {
  class LightweightLayer: ComposePanelRenderSettings()
  class HeavyweightLayer(val renderSettings: RenderSettings): ComposePanelRenderSettings 
}

Lightweight, heavyweight - Swing terms.

I think it is better to figure out the shape now rather than trying to avoid big changes. Because we will stuck with it forever, and it looks not consistent to have 2 params that affect rendering separately.