Drawing Formatted Text

When drawing a text you may need to apply some special effects to its part, e.g. to highlight a phrase or a separate word. It would be inconvenient to use GdiGraphics.DrawString or GdiGraphics.DrawText methods for this task. This is because of the necessity to break text into the chunks that have the same font settings and output them separately calling the GdiGraphics.DrawString or GdiGraphics.DrawText methods. Therefore, Graphics Mill for .NET provides the GdiGraphics.DrawFormattedText method which allows for solving such kind of tasks with ease. This method is quite similar to GdiGraphics.DrawText and accepts the same arguments:

• Text string to draw.
• Font settings.
• SolidBrush that specifies the color of the text.
• The rectangle to draw text in.
• Boolean value specifying whether to clip the text when it does not fit the bounding rectangle.
• Number of whitespaces to replace one tabulation character in the text with.

There is only one difference between these methods: the text you want to draw using the GdiGraphics.DrawFormattedText method must be marked up in XML-like style. The following tags and document structure are allowed:

<root>
    <para [style="..."]>
        [some text]
        <span [style="..."]>
            [some text]
            <span [style="..."]>
                [some text]
            </span>
        </span>
        ...
        <span [style="..."]></span>
    </para>
    ...
    <para [style="..."]></para>    
</root>

Let us consider it more detailed:

root is the root tag. There should be one root tag in the text argument which incorporates all parts of text along with their settings. If you place some text ouside the <root></root> tags, the GdiGraphics.DrawFormattedText will throw the ArgumentException.

para is a paragraph tag. All the text you want to draw should be divided into paragraphs (at least one) and each of them should be enclosed between <para> and </para> tags. Otherwise, the text will not be parsed and drawn. It supports the style attribute (see below) to specify some font and color settings of this paragraph.

span is a tag intended to define a new inline area. You can use it to highlight some text inside a paragraph. These tags can be embedded in the existing <span></span> tags. It supports the style attribute too.

The text layout mechanism used in the GdiGraphics.DrawFormattedText method is based on CSS and uses style attributes to attach font settings, and text parameters to paragraphs and theirs portions. This attribute accepts the settings as formatted string. Its common syntax is shown below:

style="style-parameter1:value1; style-parameter2:value2; ...; style-parameterN:valueN"

All supported parameters are described in the following table:

The GdiGraphics.DrawFormattedText supports the following XML predeclared entities:

• & - & ampersand;
• < - < less than;
• > - > greater than.

Also this method process service characters in the specific way. It parses the tabulation character (\t in C# and vbTab in VB) as a sequence of whitespaces. Number of whitespaces to replace one tabulation character with can be specified using the tabSize parameter.

How to Use Formatted Text Feature in the Application

Let us examine a simple application which uses the GdiGraphics.DrawFormattedText method to create birthday postcards with user specified text. A user just fills in three text boxes and the application draws each part on a background image with predefined styles.

Here is the code which implements the application described above:

Visual Basic

If _headerTextBox.Text = "" AndAlso _bodyTextBox.Text = "" AndAlso _footerTextBox.Text = "" Then
    MessageBox.Show("Postcard is empty")
Else
    ' XML string to draw
    Dim resultXml As String
    ' Default font
    Dim font As Aurigma.GraphicsMill.Drawing.Font = _
        New Aurigma.GraphicsMill.Drawing.Font("Tahoma", 14)
    ' Default font color
    Dim brush As Aurigma.GraphicsMill.Drawing.SolidBrush = _
            New Aurigma.GraphicsMill.Drawing.SolidBrush(Aurigma.GraphicsMill.RgbColor.Black)
    ' Background bitmap
    Dim bitmap As Aurigma.GraphicsMill.Bitmap = New Aurigma.GraphicsMill.Bitmap( _
                Aurigma.GraphicsMill.RgbColor.White, _pictureBox.Width, _pictureBox.Height, _
                Aurigma.GraphicsMill.PixelFormat.Format24bppRgb)
    bitmap.Load("..\..\balloons.jpg")

    ' Get GDI graphics for the background bitmap
    Dim graphics As Aurigma.GraphicsMill.Drawing.GdiGraphics = bitmap.GetGdiGraphics()

    ' Mark up the text 
    resultXml = "<root>" & vbNewLine & _
                 "    <para style=""font-size:40;text-align:center;color:rgb(220,0,0);_line-spacing:40px"">" & _
                 vbNewLine & "    " & _headerTextBox.Text & vbNewLine & "    </para>" & vbNewLine & _
                 "    <para style=""font-size:20;text-align:justify;font-weight:bold;color:rgb(5,70,150);_line-spacing:20px"">" & _
                 vbNewLine & "    " & _bodyTextBox.Text & vbNewLine & "    </para>" & vbNewLine & _
                 "    <para style=""font-size:18;text-align:right;font-style:italic;color:rgb(220,235,250)"">" & _
                 vbNewLine & "    " & _footerTextBox.Text & vbNewLine & "    </para>" & vbNewLine & "</root>"

    ' Draw text on the background
    graphics.DrawFormattedText(resultXml, font, brush, 40, 40, bitmap.Width - 80, _
            bitmap.Height - 80, True, 4)

    ' Load the result bitmap to the PictureBox
    _pictureBox.Image = bitmap.ToGdiplusBitmap()

    ' Load the XML string to the RichTextBox
    _xmlTextBox.Text = resultXml
End If

C#

if (_headerTextBox.Text == "" && _bodyTextBox.Text == "" && _footerTextBox.Text == "")
{
    MessageBox.Show("Postcard is empty");
}
else
{
    // XML string to draw
    string resultXml;
    // Default font
    Aurigma.GraphicsMill.Drawing.Font font = 
        new Aurigma.GraphicsMill.Drawing.Font("Tahoma", 14);
    // Default font color
    Aurigma.GraphicsMill.Drawing.SolidBrush brush = 
        new Aurigma.GraphicsMill.Drawing.SolidBrush(Aurigma.GraphicsMill.RgbColor.Black);
    // Background bitmap
    Aurigma.GraphicsMill.Bitmap bitmap = new Aurigma.GraphicsMill.Bitmap(
            Aurigma.GraphicsMill.RgbColor.White, _pictureBox.Width, _pictureBox.Height,
            Aurigma.GraphicsMill.PixelFormat.Format24bppRgb);
    bitmap.Load(@"..\..\balloons.jpg");

    // Get GDI graphics for the background bitmap
    Aurigma.GraphicsMill.Drawing.GdiGraphics graphics = bitmap.GetGdiGraphics();

    // Mark up the text 
    resultXml = "\n" + 
                 "    <para style=\"font-size:40;text-align:center;color:rgb(220,0,0);_line-spacing:40px\">\n    " + 
                 _headerTextBox.Text + "\n    </para>\n" +
                 "    <para style=\"font-size:20;text-align:justify;font-weight:bold;color:rgb(5,70,150);_line-spacing:20px\">\n    " + 
                 _bodyTextBox.Text + "\n    </para>\n" +
                 "    <para style=\"font-size:18;text-align:right;font-style:italic;color:rgb(220,235,250)\">\n    " + 
                 _footerTextBox.Text + "\n    </para>\n</root>";

    // Draw text on the background
    graphics.DrawFormattedText(resultXml, font, brush, 40, 40, bitmap.Width - 80,
        bitmap.Height - 80, true, 4);

    // Load the result bitmap to the PictureBox
    _pictureBox.Image = bitmap.ToGdiplusBitmap();
    
    // Load the XML string to the RichTextBox
    _xmlTextBox.Text = resultXml;
}