Editor: add gutter to preview and update inline colors in the script and shader editors

[poirierlouis]

This is an implementation of this GIP #6653.

• parses most Color constructors and static methods.
• shows a ColorPicker when clicking on color preview's gutter. Set picker's position around color preview's gutter such as editor's content can still be visualized (may need Right-To-Left support in the future).
• updates color in line with new picked color.
• adds the editor setting text_editor/appearance/gutters/show_color_previews.
• adds an SVG file, optimized with svgcleaner.
• declares two editor icons.
• updates documentation in doc/classes.
• adds two unit tests (code coverage is limited).

Implementation is essentially private. Therefore only setter / getter to draw gutter are bound with ClassDB.

Not compatible with v3.x. I'd be willing to create another PR to support v3.x if this one were accepted.

Edit:

• An archive of a Godot project ready to test this PR: gd_color_preview_editors.zip
• Screenshots with different picker's positions: #01, #02, #03

Production edit: Closes godotengine/godot-proposals#6653

[poirierlouis]

Fixed clang-format check failing, add missing new line to SVG file.

[poirierlouis]

Fixed clang-format check failing, remove reference syntax [] off a theme_item tag.

[RedMser]

This is a great feature, looking forward to it! :D

Though the color constructor parsing/rewriting seems a bit hacky to me:

• it assumes CodeEdit is only ever used for GDScript (it's not). I assume you want this feature to be supported by anyone using this UI element, not just the editor. Otherwise, look at modifying ScriptTextEditor.
• any changes to Color constructors / static methods would need to be reflected here as well. This increases the cost of maintenance.

---

Some ideas I've come up with to solve these issues, but feel free to think of your own:

Could the color parsing maybe be changed to work similarly to the "Evaluate Selection" feature, by parsing the Color\(.+?\) expression, and using the resulting variant as input for the color picker? I don't actually know if the Expression class is capable of this, but I'd assume it would work, since it's a built-in variant type - needs testing.
Possibly allow overriding this logic for different languages, by adding a virtual method, something like func _parse_color_editor_value(line: String) -> Color | null.

And as for storing the result, it might be enough to have a virtual method like func _save_color_editor_value(color: Color) -> String which by default would be implemented using a single constructor of Color (for example, have it always use the hexadecimal syntax).

Or if you want to go crazy, couple this with a "preferred color format" editor setting where you can choose RGBA, leave out the alpha component if it's 100% opaque, etc.
But I don't see a need to keep the color syntax the same from what it initially was - VSCode for example does not do it like this.

[MewPurPur]

Could you update the PR description with photos or videos of using it so we can take a quick cursory look?

I have some concerns regarding the implementation, mainly that having a whole gutter for this means a significant loss of horizontal space in the script editor. The info editor could be used for this, but then I feel like we'd also need some infrastructure around deciding what to show on that gutter and what to hide...

[poirierlouis]

Could you update the PR description with photos or videos of using it so we can take a quick cursory look?

Here three screenshots with different positioning of the picker:

• gd_color_preview_editor_screenshot_01
• gd_color_preview_editor_screenshot_02
• gd_color_preview_editor_screenshot_03

[Paulb23]

Not a fan of adding it to the gutter, I was thinking we'd add support for a "drawing API" of some form to TextEdit first. Part of that would allowing adding inline icons taking advantage of the text server. We can use that API to add this functionally.

[YuriSizov]

Fixed clang-format check failing, remove reference syntax [] off a theme_item tag.

You used formatting incorrectly. Only classes can be linked to with just [foo]. Members of classes need to use special tags, like [member foo], [method foo], [constant foo], or, in this case, [theme_item foo].

[poirierlouis]

@Paulb23

Not a fan of adding it to the gutter, I was thinking we'd add support for a "drawing API" of some form to TextEdit first. Part of that would allowing adding inline icons taking advantage of the text server. We can use that API to add this functionally.

I did mention such possibility in the GIP, which brings another question. However there is no such "drawing API" to my knowledge. It would need another GIP / PR to discuss about the use-cases of such feature (at least this one but I can think of another). I think more work and experience with the engine would be required as it gets closer to the engine's core.

---

@RedMser

it assumes CodeEdit is only ever used for GDScript (it's not). I assume you want this feature to be supported by anyone using this UI element, not just the editor. Otherwise, look at modifying ScriptTextEditor.

My first intent was to just target the editor. But as I was searching, it was not clear to me what was what in the engine. Thank you for explaining this, I'll refactor and move rules to ScriptTextEditor.

any changes to Color constructors / static methods would need to be reflected here as well. This increases the cost of maintenance.

In deed, I though about this and the maintenance cost it induces. I think such changes is unlikely as it would also require Godot's projects to be refactored to support a new syntax (big downside). Nonetheless, I didn't know the engine enough to provide a better approach.

Could the color parsing maybe be changed to work similarly to the "Evaluate Selection" feature, by parsing the Color(.+?) expression, and using the resulting variant as input for the color picker? I don't actually know if the Expression class is capable of this, but I'd assume it would work, since it's a built-in variant type - needs testing.

Oh, great! I'll check this and test it, thank you for the feature's name.

Possibly allow overriding this logic for different languages, by adding a virtual method, something like func _parse_color_editor_value(line: String) -> Color | null.

I guess this would also apply while using ScriptTextEditor?

But I don't see a need to keep the color syntax the same from what it initially was - VSCode for example does not do it like this.

I beg to differ on this, as I proposed in GIP. It's a bit like clang-format with its configuration file. It forces the project to follow a set of formatting rules. But it can be a different set of rules on another project... What if Godot's user want to always write colors in a specific format? Much like a clang-format rule. Forcing a syntax would break such rule.

Or if you want to go crazy, couple this with a "preferred color format" editor setting where you can choose RGBA, leave out the alpha component if it's 100% opaque, etc.

Thinking about it, I like your idea, it should be a good compromise. It would enforce the proposed rule above for all users of a Godot project. I'll investigate this as I work on ScriptTextEditor.

Many thanks!

[poirierlouis]

Improved documentation: format with special tag [theme_item tag].
Fixed read-only issue: prevent inline color update when text is not editable.

[poirierlouis]

@RedMser , I tried with the Expression class. It doesn't work with static methods (not implemented in Expression).
Would it be ok to implement a static method to parse color formats somewhere "globally", maybe on the Color class?
Or should I start a new GIP / PR to add static method support on the Expression class itself (if it is even possible)?

[RedMser]

@poirierlouis

It doesn't work with static methods

That's a shame.
I'm not sure what the next best approach would be that could avoid this additional code. I don't think there is an easy API to execute a GDScript snippet and get its result.

Would it be ok to implement a static method to parse color formats
Or should I start a new GIP / PR to add static method support on the Expression class itself

I'm not in a position to be able to decide or judge these things. But my recommendation would be, if you want this merged, to start out simple and have the chance to extend it later.

So maybe parsing just Color constructors via Expression is already enough for the MVP, and finding a nice solution to parse the static methods and named color properties could follow later. Same goes for the saving logic, which could start out by just using what the "Evaluate Selection" function uses internally to convert the result back into a String.

Maybe other more experienced contributors could chime in here and provide their thoughts.

[poirierlouis]

• refactor: move logic to ScriptTextEditor only for now.
• refactor: removed unit tests. There is no tests/editor/.
• docs: only add description for the new "Show Color Preview Gutter" property.
• feat: parse Color declaration using Expression, more limited than the "Pick Color" feature (see below).
• feat: format to Color(r, g, b, a). Now "Color Preview" and "Pick Color" use the same formatting function.
• feat: add function to compute the color panel's position with responsiveness.
• feat: use metadata from the "Gutter API" as a cache to improve performance.
• feat: only run this feature after the script is validated (like the "connection gutter").

Expression is limited for now. It does not support named color declarations. Which is a downside regarding the "Pick Color" feature. It parses float constructors and named colors manually within ScriptTextEditor.

Moreover, I figured there is an "issue" when parsing other syntaxes like @export var color := Color.hex(0xFFA800). It fallback to a black color in the "Inspector".
The idea of proposing a single endpoint to parse / format GDScript colors could be used in at least three use-cases:

• @export a Color
• Pick Color
• Color Preview (this)

[poirierlouis]

• feat: add logic to parse named colors.
• refactor: replace parser logic in "Pick Color" with a call to _parse_color_value method.
• fix: update metadata of a line's color preview gutter after color changed with "Color Picker".

Video of this current commit here, steps:

1. Use "Pick Color".
2. Use "Color Preview".
3. Cancel step 2 and step 1 with CTRL + Z, check color preview is refreshed (delay is due to script validation process).
4. Show responsiveness of Color Picker around color preview gutter.

[poirierlouis]

• feat: add color preview in ShaderTextEditor, it is a duplicate of the logic from ScriptTextEditor but it only parses the vec4() syntax with source_color hint.

@RedMser
I'm wondering if it is ok for now to have almost identical code between ShaderTextEditor and ScriptTextEditor? Or if it must be merged somehow, maybe within CodeEdit?

[KoBeWi]

'm wondering if it is ok for now to have almost identical code between ShaderTextEditor and ScriptTextEditor?

See #28607 Code editors already duplicate lots of code, so it's fine until they are refactored.

[poirierlouis]

• build: fix variable name in method shadowing a class member variable.