API Proposal: Add span overloads to TextRenderer

[JeremyKuhne]

Proposal

We should add span overloads to TextRenderer to allow for efficient text rendering. Fortunately the Win32 APIs in play here take a length so we can use span data directly- we've already refactored internally to use ReadOnlySpan<char>.

namespace System.Windows.Forms
{
    public sealed class TextRenderer
    {
        // Existing:
        public static void DrawText(IDeviceContext dc, string text, Font font, Point pt, Color foreColor);
        public static void DrawText(IDeviceContext dc, string text, Font font, Point pt, Color foreColor, Color backColor);
        public static void DrawText(IDeviceContext dc, string text, Font font, Point pt, Color foreColor, Color backColor, TextFormatFlags flags);
        public static void DrawText(IDeviceContext dc, string text, Font font, Point pt, Color foreColor, TextFormatFlags flags);
        public static void DrawText(IDeviceContext dc, string text, Font font, Rectangle bounds, Color foreColor);
        public static void DrawText(IDeviceContext dc, string text, Font font, Rectangle bounds, Color foreColor, Color backColor);
        public static void DrawText(IDeviceContext dc, string text, Font font, Rectangle bounds, Color foreColor, Color backColor, TextFormatFlags flags);
        public static void DrawText(IDeviceContext dc, string text, Font font, Rectangle bounds, Color foreColor, TextFormatFlags flags);
        public static Size MeasureText(IDeviceContext dc, string text, Font font);
        public static Size MeasureText(IDeviceContext dc, string text, Font font, Size proposedSize);
        public static Size MeasureText(IDeviceContext dc, string text, Font font, Size proposedSize, TextFormatFlags flags);
        public static Size MeasureText(string text, Font font);
        public static Size MeasureText(string text, Font font, Size proposedSize);
        public static Size MeasureText(string text, Font font, Size proposedSize, TextFormatFlags flags);

        // 1-1 Proposal
        // Note that backColor and proposedSize can't be defaulted as they are Color.Empty and Size(int.MaxValue, intMaxValue).
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Point pt, Color foreColor);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Point pt, Color foreColor, Color backColor);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Point pt, Color foreColor, Color backColor, TextFormatFlags flags);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Point pt, Color foreColor, TextFormatFlags flags);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Rectangle bounds, Color foreColor);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Rectangle bounds, Color foreColor, Color backColor);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Rectangle bounds, Color foreColor, Color backColor, TextFormatFlags flags);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Rectangle bounds, Color foreColor, TextFormatFlags flags);
        public static Size MeasureText(IDeviceContext dc, ReadOnlySpan<char> text, Font font);
        public static Size MeasureText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Size proposedSize);
        public static Size MeasureText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Size proposedSize, TextFormatFlags flags);
        public static Size MeasureText(ReadOnlySpan<char> text, Font font);
        public static Size MeasureText(ReadOnlySpan<char> text, Font font, Size proposedSize);
        public static Size MeasureText(ReadOnlySpan<char> text, Font font, Size proposedSize, TextFormatFlags flags);
    }
}

Justification

Drawing and measuring text is a pretty common activity. This will allow significantly more efficient text rendering when new string allocations can be avoided (slicing other input, building off of a stack based character array, etc.). In conjunction with IDeviceContext on PaintEventArgs and other internal performance improvements, painting a string on a blank form can be done with < 15% of the allocations it used to take.

Implementation Details

We'll match throwing behavior of the original APIs. The original APIs did not throw for null or empty strings, they just no-op.

[weltkante]

Make sure you don't repeat the same mistake the existing interop does, namely allowing writing into immutable strings (this is probably still broken, see #1564). You should prevent calling native code writing into readonly spans by passing through the ModifyString flag unchecked.

Do we want to include fixing #1564 in this API design discussion or should this just be about readonly APIs?

[JeremyKuhne]

Make sure you don't repeat the same mistake

Thanks for the reminder! I'll make sure the original issue is fixed- we can always add a new API for those that want the truncated behavior. Corrupting strings could go horribly, horribly wrong.

[JeremyKuhne]

The Win32 API in play here is DrawTextExW. When drawing with ellipses it has the option to modify the input string to reflect what actually would be displayed. We didn't block this historically, but won't allow it going forward. In order to safely allow it we would have to have at least four new methods to match the full argument Measure and Draw methods.

[terrajobst]

Video

• Looks good as proposed

namespace System.Windows.Forms
{
    public sealed class TextRenderer
    {
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Point pt, Color foreColor);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Point pt, Color foreColor, Color backColor);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Point pt, Color foreColor, Color backColor, TextFormatFlags flags);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Point pt, Color foreColor, TextFormatFlags flags);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Rectangle bounds, Color foreColor);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Rectangle bounds, Color foreColor, Color backColor);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Rectangle bounds, Color foreColor, Color backColor, TextFormatFlags flags);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Rectangle bounds, Color foreColor, TextFormatFlags flags);
        public static Size MeasureText(IDeviceContext dc, ReadOnlySpan<char> text, Font font);
        public static Size MeasureText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Size proposedSize);
        public static Size MeasureText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Size proposedSize, TextFormatFlags flags);
        public static Size MeasureText(ReadOnlySpan<char> text, Font font);
        public static Size MeasureText(ReadOnlySpan<char> text, Font font, Size proposedSize);
        public static Size MeasureText(ReadOnlySpan<char> text, Font font, Size proposedSize, TextFormatFlags flags);
    }
}