Add warnings for nested Clip Children values in CanvasItems

[Meorge]

Describe the project you are working on

A game involving nested 2D and Control elements

Describe the problem or limitation you are having in your project

I was experiencing strange rendering issues with custom Controls, and was having a lot of trouble diagnosing them. Eventually, I determined that it was because I had nested CanvasItems that were clipping their children. I thought that this was a bug, but looked into it further and found that it is in the documentation for CanvasGroup:

Note: Since CanvasGroup and CanvasItem.clip_children both utilize the backbuffer, children of a CanvasGroup who have their CanvasItem.clip_children set to anything other than CanvasItem.CLIP_CHILDREN_DISABLED will not function correctly.

This is not discussed in the documentation for CanvasItem.clip_children or the ClipChildrenMode enum that it uses, which is what appears in the editor when you hover over "Clip Children":

As a result, the clipping behavior acting in an unexpected way, with no obvious cause, is frustrating to debug.

Note

As a more immediate solution, I think it'd be good to just add a note to clip_children specifying that it won't work when nested. I plan to file have filed a PR for this fix.

In the future, I think it'd be very good to overhaul the clipping system so it doesn't have this limitation, if possible, but I imagine that would be a much more complicated task to tackle. As such, this proposal just aims to make people more aware of it so they can avoid the confusion and debugging I had to go through.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

When an ancestor of a CanvasItem has a clip_children value of something other than CLIP_CHILDREN_DISABLED, and the CanvasItem itself has a clip_children of something other than CLIP_CHILDREN_DISABLED, a warning icon could be displayed next to the node in the Scene tab tree.

Additionally, the "Clip Children" field itself could display a warning box explaining that the clipping won't work correctly.

I was thinking, as a third thing, that the dropdown box for "Clip Children" could be disabled, but that may cause some usability issues.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

Warning in scene tree:

Warning in inspector:

Disabling dropdown in inspector (maybe should be paired with the warning box?):

If this enhancement will not be used often, can it be worked around with a few lines of script?

I'm not aware of how this would be implemented via scripts, much less a just "few lines".

Is there a reason why this should be core and not an add-on in the asset library?

This serves to help people recognize that there is a problem with the structure of their scene which they would not otherwise be aware of. If it was an add-on, they would have to know the limitation of the clipping system even exists to go and search for an add-on to notify them about it - and at that point, they already know about the limitation, so its usefulness is much more limited.

[Protoplanetary-Fish]

I tried using this in the past and the engine crashed when loading scenes with nested clipping needing me to dismantle the scenes from within the files to restore my project. Running on arch linux.