API Proposal: Add IDeviceContext overloads to ControlPaint

[JeremyKuhne]

Summary

Painting using System.Drawing (GDI+) has significant performance overhead over utilizing GDI. Internally WinForms has moved much of it's rendering to GDI (starting in .NET 2.0) and has provided some entry points with GDI via IDeviceContext. Adding overloads to ControlPaint methods will allow more performant rendering of custom controls. It allows direct use of paint event arguments in OnPaint as they now expose IDeviceContext (as opposed to e.Graphics, which has huge overhead).

API

    public sealed class ControlPaint
    {
        // Existing APIs that take Graphics
        public static void DrawBorder(Graphics graphics, Rectangle bounds, Color color, ButtonBorderStyle style);
        public static void DrawBorder(Graphics graphics, Rectangle bounds, Color leftColor, int leftWidth, ButtonBorderStyle leftStyle, Color topColor, int topWidth, ButtonBorderStyle topStyle, Color rightColor, int rightWidth, ButtonBorderStyle rightStyle, Color bottomColor, int bottomWidth, ButtonBorderStyle bottomStyle);
        public static void DrawBorder3D(Graphics graphics, int x, int y, int width, int height);
        public static void DrawBorder3D(Graphics graphics, int x, int y, int width, int height, Border3DStyle style);
        public static void DrawBorder3D(Graphics graphics, int x, int y, int width, int height, Border3DStyle style, Border3DSide sides);
        public static void DrawBorder3D(Graphics graphics, Rectangle rectangle);
        public static void DrawBorder3D(Graphics graphics, Rectangle rectangle, Border3DStyle style);
        public static void DrawBorder3D(Graphics graphics, Rectangle rectangle, Border3DStyle style, Border3DSide sides);
        public static void DrawButton(Graphics graphics, int x, int y, int width, int height, ButtonState state);
        public static void DrawButton(Graphics graphics, Rectangle rectangle, ButtonState state);
        public static void DrawCaptionButton(Graphics graphics, int x, int y, int width, int height, CaptionButton button, ButtonState state);
        public static void DrawCaptionButton(Graphics graphics, Rectangle rectangle, CaptionButton button, ButtonState state);
        public static void DrawCheckBox(Graphics graphics, int x, int y, int width, int height, ButtonState state);
        public static void DrawCheckBox(Graphics graphics, Rectangle rectangle, ButtonState state);
        public static void DrawComboButton(Graphics graphics, int x, int y, int width, int height, ButtonState state);
        public static void DrawComboButton(Graphics graphics, Rectangle rectangle, ButtonState state);
        public static void DrawContainerGrabHandle(Graphics graphics, Rectangle bounds);
        public static void DrawFocusRectangle(Graphics graphics, Rectangle rectangle);
        public static void DrawFocusRectangle(Graphics graphics, Rectangle rectangle, Color foreColor, Color backColor);
        public static void DrawGrabHandle(Graphics graphics, Rectangle rectangle, bool primary, bool enabled);
        public static void DrawGrid(Graphics graphics, Rectangle area, Size pixelsBetweenDots, Color backColor);
        public static void DrawLockedFrame(Graphics graphics, Rectangle rectangle, bool primary);
        public static void DrawMenuGlyph(Graphics graphics, int x, int y, int width, int height, MenuGlyph glyph);
        public static void DrawMenuGlyph(Graphics graphics, int x, int y, int width, int height, MenuGlyph glyph, Color foreColor, Color backColor);
        public static void DrawMenuGlyph(Graphics graphics, Rectangle rectangle, MenuGlyph glyph);
        public static void DrawMenuGlyph(Graphics graphics, Rectangle rectangle, MenuGlyph glyph, Color foreColor, Color backColor);
        public static void DrawMixedCheckBox(Graphics graphics, int x, int y, int width, int height, ButtonState state);
        public static void DrawMixedCheckBox(Graphics graphics, Rectangle rectangle, ButtonState state);
        public static void DrawRadioButton(Graphics graphics, int x, int y, int width, int height, ButtonState state);
        public static void DrawRadioButton(Graphics graphics, Rectangle rectangle, ButtonState state);
        public static void DrawScrollButton(Graphics graphics, int x, int y, int width, int height, ScrollButton button, ButtonState state);
        public static void DrawScrollButton(Graphics graphics, Rectangle rectangle, ScrollButton button, ButtonState state);
        public static void DrawSelectionFrame(Graphics graphics, bool active, Rectangle outsideRect, Rectangle insideRect, Color backColor);
        public static void DrawSizeGrip(Graphics graphics, Color backColor, int x, int y, int width, int height);
        public static void DrawSizeGrip(Graphics graphics, Color backColor, Rectangle bounds);
        public static void DrawVisualStyleBorder(Graphics graphics, Rectangle bounds);

        // Existing, IDeviceContext doesn't make sense as this also takes Image
        public static void DrawImageDisabled(Graphics graphics, Image image, int x, int y, Color background);

        // Existing, already has IDeviceContext overload
        public static void DrawStringDisabled(Graphics graphics, string s, Font font, Color color, RectangleF layoutRectangle, StringFormat format);

        // Proposed IDeviceContext overloads
        public static void DrawBorder(IDeviceContext deviceContext, Rectangle bounds, Color color, ButtonBorderStyle style);
        public static void DrawBorder(IDeviceContext deviceContext, Rectangle bounds, Color leftColor, int leftWidth, ButtonBorderStyle leftStyle, Color topColor, int topWidth, ButtonBorderStyle topStyle, Color rightColor, int rightWidth, ButtonBorderStyle rightStyle, Color bottomColor, int bottomWidth, ButtonBorderStyle bottomStyle);
        public static void DrawBorder3D(IDeviceContext deviceContext, int x, int y, int width, int height);
        public static void DrawBorder3D(IDeviceContext deviceContext, int x, int y, int width, int height, Border3DStyle style);
        public static void DrawBorder3D(IDeviceContext deviceContext, int x, int y, int width, int height, Border3DStyle style, Border3DSide sides);
        public static void DrawBorder3D(IDeviceContext deviceContext, Rectangle rectangle);
        public static void DrawBorder3D(IDeviceContext deviceContext, Rectangle rectangle, Border3DStyle style);
        public static void DrawBorder3D(IDeviceContext deviceContext, Rectangle rectangle, Border3DStyle style, Border3DSide sides);
        public static void DrawButton(IDeviceContext deviceContext, int x, int y, int width, int height, ButtonState state);
        public static void DrawButton(IDeviceContext deviceContext, Rectangle rectangle, ButtonState state);
        public static void DrawCaptionButton(IDeviceContext deviceContext, int x, int y, int width, int height, CaptionButton button, ButtonState state);
        public static void DrawCaptionButton(IDeviceContext deviceContext, Rectangle rectangle, CaptionButton button, ButtonState state);
        public static void DrawCheckBox(IDeviceContext deviceContext, int x, int y, int width, int height, ButtonState state);
        public static void DrawCheckBox(IDeviceContext deviceContext, Rectangle rectangle, ButtonState state);
        public static void DrawComboButton(IDeviceContext deviceContext, int x, int y, int width, int height, ButtonState state);
        public static void DrawComboButton(IDeviceContext deviceContext, Rectangle rectangle, ButtonState state);
        public static void DrawContainerGrabHandle(IDeviceContext deviceContext, Rectangle bounds);
        public static void DrawFocusRectangle(IDeviceContext deviceContext, Rectangle rectangle);
        public static void DrawFocusRectangle(IDeviceContext deviceContext, Rectangle rectangle, Color foreColor, Color backColor);
        public static void DrawGrabHandle(IDeviceContext deviceContext, Rectangle rectangle, bool primary, bool enabled);
        public static void DrawGrid(IDeviceContext deviceContext, Rectangle area, Size pixelsBetweenDots, Color backColor);
        public static void DrawLockedFrame(IDeviceContext deviceContext, Rectangle rectangle, bool primary);
        public static void DrawMenuGlyph(IDeviceContext deviceContext, int x, int y, int width, int height, MenuGlyph glyph);
        public static void DrawMenuGlyph(IDeviceContext deviceContext, int x, int y, int width, int height, MenuGlyph glyph, Color foreColor, Color backColor);
        public static void DrawMenuGlyph(IDeviceContext deviceContext, Rectangle rectangle, MenuGlyph glyph);
        public static void DrawMenuGlyph(IDeviceContext deviceContext, Rectangle rectangle, MenuGlyph glyph, Color foreColor, Color backColor);
        public static void DrawMixedCheckBox(IDeviceContext deviceContext, int x, int y, int width, int height, ButtonState state);
        public static void DrawMixedCheckBox(IDeviceContext deviceContext, Rectangle rectangle, ButtonState state);
        public static void DrawRadioButton(IDeviceContext deviceContext, int x, int y, int width, int height, ButtonState state);
        public static void DrawRadioButton(IDeviceContext deviceContext, Rectangle rectangle, ButtonState state);
        public static void DrawScrollButton(IDeviceContext deviceContext, int x, int y, int width, int height, ScrollButton button, ButtonState state);
        public static void DrawScrollButton(IDeviceContext deviceContext, Rectangle rectangle, ScrollButton button, ButtonState state);
        public static void DrawSelectionFrame(IDeviceContext deviceContext, bool active, Rectangle outsideRect, Rectangle insideRect, Color backColor);
        public static void DrawSizeGrip(IDeviceContext deviceContext, Color backColor, int x, int y, int width, int height);
        public static void DrawSizeGrip(IDeviceContext deviceContext, Color backColor, Rectangle bounds);
        public static void DrawVisualStyleBorder(IDeviceContext deviceContext, Rectangle bounds);
    }

Details

• Parameter validation will match existing methods
• Color alpha will be ignored, as that requires GDI+ (we could throw, but that wouldn't fit with other APIs we currently have)
• Drawing will always be done with GDI, even if the passed in IDeviceContext is a Graphics object
• As with other usages we will apply Graphics offset and clipping if IDeviceContext is a Graphics object
• Implementation will come in phases as some of these APIs are more straight-forward than others

[terrajobst]

Video

• Looks good as proposed

namespace System.Windows.Forms
{
    public partial class ControlPaint
    {
        public static void DrawBorder(IDeviceContext deviceContext, Rectangle bounds, Color color, ButtonBorderStyle style);
        public static void DrawBorder(IDeviceContext deviceContext, Rectangle bounds, Color leftColor, int leftWidth, ButtonBorderStyle leftStyle, Color topColor, int topWidth, ButtonBorderStyle topStyle, Color rightColor, int rightWidth, ButtonBorderStyle rightStyle, Color bottomColor, int bottomWidth, ButtonBorderStyle bottomStyle);
        public static void DrawBorder3D(IDeviceContext deviceContext, int x, int y, int width, int height);
        public static void DrawBorder3D(IDeviceContext deviceContext, int x, int y, int width, int height, Border3DStyle style);
        public static void DrawBorder3D(IDeviceContext deviceContext, int x, int y, int width, int height, Border3DStyle style, Border3DSide sides);
        public static void DrawBorder3D(IDeviceContext deviceContext, Rectangle rectangle);
        public static void DrawBorder3D(IDeviceContext deviceContext, Rectangle rectangle, Border3DStyle style);
        public static void DrawBorder3D(IDeviceContext deviceContext, Rectangle rectangle, Border3DStyle style, Border3DSide sides);
        public static void DrawButton(IDeviceContext deviceContext, int x, int y, int width, int height, ButtonState state);
        public static void DrawButton(IDeviceContext deviceContext, Rectangle rectangle, ButtonState state);
        public static void DrawCaptionButton(IDeviceContext deviceContext, int x, int y, int width, int height, CaptionButton button, ButtonState state);
        public static void DrawCaptionButton(IDeviceContext deviceContext, Rectangle rectangle, CaptionButton button, ButtonState state);
        public static void DrawCheckBox(IDeviceContext deviceContext, int x, int y, int width, int height, ButtonState state);
        public static void DrawCheckBox(IDeviceContext deviceContext, Rectangle rectangle, ButtonState state);
        public static void DrawComboButton(IDeviceContext deviceContext, int x, int y, int width, int height, ButtonState state);
        public static void DrawComboButton(IDeviceContext deviceContext, Rectangle rectangle, ButtonState state);
        public static void DrawContainerGrabHandle(IDeviceContext deviceContext, Rectangle bounds);
        public static void DrawFocusRectangle(IDeviceContext deviceContext, Rectangle rectangle);
        public static void DrawFocusRectangle(IDeviceContext deviceContext, Rectangle rectangle, Color foreColor, Color backColor);
        public static void DrawGrabHandle(IDeviceContext deviceContext, Rectangle rectangle, bool primary, bool enabled);
        public static void DrawGrid(IDeviceContext deviceContext, Rectangle area, Size pixelsBetweenDots, Color backColor);
        public static void DrawLockedFrame(IDeviceContext deviceContext, Rectangle rectangle, bool primary);
        public static void DrawMenuGlyph(IDeviceContext deviceContext, int x, int y, int width, int height, MenuGlyph glyph);
        public static void DrawMenuGlyph(IDeviceContext deviceContext, int x, int y, int width, int height, MenuGlyph glyph, Color foreColor, Color backColor);
        public static void DrawMenuGlyph(IDeviceContext deviceContext, Rectangle rectangle, MenuGlyph glyph);
        public static void DrawMenuGlyph(IDeviceContext deviceContext, Rectangle rectangle, MenuGlyph glyph, Color foreColor, Color backColor);
        public static void DrawMixedCheckBox(IDeviceContext deviceContext, int x, int y, int width, int height, ButtonState state);
        public static void DrawMixedCheckBox(IDeviceContext deviceContext, Rectangle rectangle, ButtonState state);
        public static void DrawRadioButton(IDeviceContext deviceContext, int x, int y, int width, int height, ButtonState state);
        public static void DrawRadioButton(IDeviceContext deviceContext, Rectangle rectangle, ButtonState state);
        public static void DrawScrollButton(IDeviceContext deviceContext, int x, int y, int width, int height, ScrollButton button, ButtonState state);
        public static void DrawScrollButton(IDeviceContext deviceContext, Rectangle rectangle, ScrollButton button, ButtonState state);
        public static void DrawSelectionFrame(IDeviceContext deviceContext, bool active, Rectangle outsideRect, Rectangle insideRect, Color backColor);
        public static void DrawSizeGrip(IDeviceContext deviceContext, Color backColor, int x, int y, int width, int height);
        public static void DrawSizeGrip(IDeviceContext deviceContext, Color backColor, Rectangle bounds);
        public static void DrawVisualStyleBorder(IDeviceContext deviceContext, Rectangle bounds);

        // Omitted, IDeviceContext doesn't make sense as this also takes Image
        // public static void DrawImageDisabled(Graphics graphics, Image image, int x, int y, Color background);

        // Already exists
        // public static void DrawStringDisabled(IDeviceContext deviceContext, string s, Font font, Color color, RectangleF layoutRectangle, StringFormat format);
    }
}

[elachlan]

@JeremyKuhne I imagine when implementing this we will need tests added to ControlPaintTests? How do we get a IDeviceContext similar to using Graphics graphics = Graphics.FromImage(image);?

[JeremyKuhne]

How do we get a IDeviceContext similar to using Graphics graphics = Graphics.FromImage(image);?

Graphics actually implements it, so you can just use it. :)

[elachlan]

Awesome, so we aren't changing the existing function signatures. We are adding new overloads?

I should be able to slowly put in some PRs and copy the existing tests.