API Proposal: Add safe overloads to TextRenderer to get output strings.

[JeremyKuhne]

Proposal

We need to add new overloads that allow getting out the actual rendered string when using ellipses options (TextFormatFlags.PathEllipsis and TextFormatFlags.WordEllipsis). This is currently done with TextFormatFlags.ModifyString, which mutates the input string. We block this option in the newer span overloads and have obsoleted it.

This is a follow-up to #3651.

namespace System.Windows.Forms
{
    public sealed class TextRenderer
    {
        // Existing flags APIs:
        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, 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, Size proposedSize, TextFormatFlags flags);
        public static Size MeasureText(string text, Font font, Size proposedSize, TextFormatFlags flags);
        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, 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, Size proposedSize, TextFormatFlags flags);
        public static Size MeasureText(ReadOnlySpan<char> text, Font font, Size proposedSize, TextFormatFlags flags);

        // Proposed
        public static void DrawText(IDeviceContext dc, string text, Font font, Point pt, Color foreColor, Color backColor, TextFormatFlags flags, out string outputText);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Point pt, Color foreColor, Color backColor, TextFormatFlags flags, Span<char> outputTextBuffer, out int outputTextLength);
        public static void DrawText(IDeviceContext dc, string text, Font font, Rectangle bounds, Color foreColor, Color backColor, TextFormatFlags flags, out string outputText);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Rectangle bounds, Color foreColor, Color backColor, TextFormatFlags flags, Span<char> outputTextBuffer, out int outputTextLength);
        public static Size MeasureText(IDeviceContext dc, string text, Font font, Size proposedSize, TextFormatFlags flags, out string outputText);
        public static Size MeasureText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Size proposedSize, TextFormatFlags flags, Span<char> outputTextBuffer, out int outputTextLength);
        public static Size MeasureText(string text, Font font, Size proposedSize, TextFormatFlags flags, out string outputText);
        public static Size MeasureText(ReadOnlySpan<char> text, Font font, Size proposedSize, TextFormatFlags flags, Span<char> outputTextBuffer, out int outputTextLength);
    }
}

Justification

It is still a valid scenario to want to know what Windows actually outputs. Providing these overloads will let us fully block the mutation of the input strings, which is extremely dangerous.

The proposed surface area aligns with the existing API definitions and allows utilizing the same buffer for the Span APIs for advanced users.

Implementation Details

These APIs will presume you want the output string without requiring the obsoleted flag. When the ellipses flags are set we will get the actual output string from Windows and either create a new string or copy the output into the Span buffer provided and return the length. In all other scenarios we will pass back the input.

The Span overloads will require that the passed in Span<char> is at least as long as the input ReadOnlySpan<char>. If it is not, the API will throw.

We'll skip the overloads for just foreColor and document that Color.Empty is required for a transparent background as these APIs are not as common.

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

[weltkante]

Interesting proposal, I like it better than the usual mapping of mutable argument via ref string text and Span<char> text

Having separate input/output parameters

• caller can still pass the same variable for both input and output if he doesn't need two variables
• caller can still use out var syntax even in situations where he couldn't use ref-syntax (e.g. on a foreach loop variable)
• allows caller to input a string (viewed as readonly span) but write output into a span buffer, something which would not be possible with a mutable argument

(Just felt it worth to point out the advantages of separate input/output arguments over providing a single mutable argument because I had to think a bit before I noticed them. Also supporting passing the same span into both input and output may require special coding, so its worth mentioning early that this is a case that makes sense.)

[terrajobst]

Video

• Normally, output buffers go right after the input buffer, but we'll keep it last here to align with existing overloads and (more importantly) the out string

namespace System.Windows.Forms
{
    public sealed class TextRenderer
    {
        // Existing flags APIs:
        // 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, 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, Size proposedSize, TextFormatFlags flags);
        // public static Size MeasureText(string text, Font font, Size proposedSize, TextFormatFlags flags);
        // 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, 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, Size proposedSize, TextFormatFlags flags);
        // public static Size MeasureText(ReadOnlySpan<char> text, Font font, Size proposedSize, TextFormatFlags flags);

        public static void DrawText(IDeviceContext dc, string text, Font font, Point pt, Color foreColor, Color backColor, TextFormatFlags flags, out string outputText);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Point pt, Color foreColor, Color backColor, TextFormatFlags flags, Span<char> outputTextBuffer, out int outputTextLength);
        public static void DrawText(IDeviceContext dc, string text, Font font, Rectangle bounds, Color foreColor, Color backColor, TextFormatFlags flags, out string outputText);
        public static void DrawText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Rectangle bounds, Color foreColor, Color backColor, TextFormatFlags flags, Span<char> outputTextBuffer, out int outputTextLength);
        public static Size MeasureText(IDeviceContext dc, string text, Font font, Size proposedSize, TextFormatFlags flags, out string outputText);
        public static Size MeasureText(IDeviceContext dc, ReadOnlySpan<char> text, Font font, Size proposedSize, TextFormatFlags flags, Span<char> outputTextBuffer, out int outputTextLength);
        public static Size MeasureText(string text, Font font, Size proposedSize, TextFormatFlags flags, out string outputText);
        public static Size MeasureText(ReadOnlySpan<char> text, Font font, Size proposedSize, TextFormatFlags flags, Span<char> outputTextBuffer, out int outputTextLength);
    }
}

[IanKemp]

I don't understand why TextFormatFlags.ModifyString was EVER added, let alone implemented... it breaks pretty much every .NET convention. Glad to see this particular piece of cancer is finally being excised, my only question is when do you intend to make using this flag an error? .NET 6?

[RussKie]

my only question is when do you intend to make using this flag an error? .NET 6?

We have marked it as obsolete in 5.0 RC1 #3711. As to when this becomes an error - it hasn't been discussed yet.