Requirement: Support for Truly Flat Look in Eclipse Forms UI

[vogella]

1. Objective
   Enable a "truly flat" visual appearance for Form and Section widgets within the org.eclipse.ui.forms bundle. Currently, even when the CSS engine provides identical start and end colors to simulate a flat look, the underlying rendering engine produces a "small starting gradient" or subtle rendering artifacts.

2. Problem Description
   The Eclipse Forms UI framework was originally designed with a strong emphasis on gradients (popular in the early 2000s). Consequently, the drawing logic for form headers and section title bars is hardcoded to use gradient-painting primitives.

When a flat look is requested via CSS (e.g., text-background-color: #f0f0f0 #f0f0f0 100% true), the following issues occur:

1. Primitive Overhead: GC.fillGradientRectangle is still invoked. Depending on the OS/SWT implementation and rounding logic, this can result in a 1-pixel offset or a slight color shift at the start/end of the area.

2. Section Artifacts: The Section widget has hardcoded 1-pixel wide vertical gradients on the edges and a 5-pixel high gradient at the top of the body when expanded, which remain visible even if the main title bar is "flat."

3. Image Cache Noise: FormImages generates and caches Image objects for these "gradients" even when they are just solid colors, leading to unnecessary memory usage.

4. Technical Analysis
   The investigation identified several key areas where gradient logic is forced:

• FormHeading.java / Form.java: The setTextBackground method always triggers updateGradientImage(), which uses FormImages to create a background image.
• FormImages.java: The drawTextGradient method in ComplexImageDescriptor iterates through percentages and calls gc.fillGradientRectangle for every segment, even if the color array contains identical values.
• Section.java:
  • The onPaint method uses iGc.fillGradientRectangle(marginWidth, marginHeight + 2, 1, theight + 2, true) for vertical edges.
  • In the "expanded" state (without TITLE_BAR style), it paints a 5-pixel high top gradient: gc.fillGradientRectangle(..., 5, true).
• CSSPropertyFormHandler.java: This handler converts CSS gradient strings into color arrays and passes them to the widgets. Even for single colors, it may pass an array that triggers the gradient logic in the widget.

4. Proposed Solution

4.1. Level 1: Widget Logic Optimization (Flat Detection)
Modify FormHeading.setTextBackground(Color[] colors, int[] percents, boolean vertical) to detect flat requests:

• Action: If colors.length == 1 or if all colors in the array are identical, the widget should not generate a gradient image.
• Implementation: It should instead call setBackground(colors[0]) and setBackgroundImage(null). This leverages SWT's native background handling, which is perfectly flat and more efficient.

4.2. Level 2: Image Utility Refinement
Update FormImages.java to handle identical colors gracefully during image generation.

• Action: In ComplexImageDescriptor.drawTextGradient, add a check:

1 if (lastColor.equals(nextColor)) {
2 gc.fillRectangle(pos, 0, width, height); // Flat fill
3 } else {
4 gc.fillGradientRectangle(pos, 0, width, height, vertical);
5 }

• Benefit: This ensures that even if an image is generated (e.g., due to complex multi-stop gradients where some stops are the same), the specific segments are painted flat.

4.3. Level 3: Section Painting Cleanup
Update Section.onPaint to respect the flat look.

• Action:
  • For the 1-pixel edge gradients: Use iGc.fillRectangle if the titleBarGradientBackground is the same as the titleBarBackground.
  • For the 5-pixel expanded gradient: If a flat look is desired (which can be determined by checking if the start/end colors of the toolkit are identical), use a solid fill or omit the gradient to avoid the "starting line" artifact.

4.4. Level 4: CSS Handler Intelligence
Enhance CSSPropertyFormHandler to be more surgical.

• Action: If a Gradient object is received but its values are identical, call a (to-be-created) Form.setTextBackground(Color) method or pass a null gradient array to reset it to a solid background.

5. Success Criteria

• The "starting line" artifact at the top of Form and Section headers is eliminated when identical colors are used.
• Memory usage is reduced by avoiding Image objects for solid color backgrounds in form headings.
• The transition from a gradient look to a flat look is seamless and respects the colors defined in the CSS theme.

[vogella]

Level 2 │ FormImages use fillRectangle for identical colors │ Done in PR #3807
Level 3 │ Section.onPaint skip legacy decorations for flat look │ Done in PR #3807