Meet us at PRINT 19. Chicago, IL. Oct. 3 - 5.
This documentation is for the old version. Go to the latest Graphics Mill docs

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:

XML
<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.

Note

All allowed tags are case insensitive, however, the name of every opening tag must have the same case as that of the corresponding closing tag. It means that <SpAn></SpAn> or <rOOt></rOOt> pairs will be parsed successfully, but pairs like <Para></parA> will cause an error.

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"

Note

The style attribute and its value are case insensitive, i.e. this style setting will be applied correctly: StyLe="fOnT-faMily: CoUriEr NeW; FoNt-siZe: 18; cOlOr:RgB(100,10,10)"

All supported parameters are described in the following table:

Name Description Examples
Font Parameters
font-family

Specifies a typeface name of the font.

If font with specified typeface name is not found, system uses a default font (as usual it is "Arial").

style="font-family:arial"
font-style

Selects between normal and italic faces within a font family.

style="font-style:normal"
style="font-style:italic"
font-weight

Selects the weight of the font. The values 100 to 900 form an ordered sequence, where each number indicates a weight that is at least as dark as its predecessor. The keyword normal is synonymous with 400, and bold is synonymous with 700.

style="font-weight:normal"
style="font-weight:bold"
style="font-weight:600"
font-size

Specifies the font size.

style="font-size:12"
Color Parameters
color

Specifies the text color. A numerical RGB specification is used. No keywords (like red, green, white and etc) are supported.

style="color:rgb(200, 0, 0)"
Text Parameters
text-align

Specifies the text alignment. The following alignment types are supported:

  • center aligns text along the center.
  • left aligns text along the left edge.
  • right aligns text along the right edge.
  • justify aligns text along the left and right edges.

If the justify alignment type is specified the last line of the text can be aligned using the textAlignLast parameter. This parameter can be one of the following values:

  • center aligns the last line of the text along the center.
  • left aligns the last line of the text along the left edge.
  • right aligns the last line of the text along the right edge.
  • justify aligns the last line of the text along the left and right edges.

If the textAlignLast parameter is not specified the last line of the text will be aligned along the left edge.

style="text-align:left"
style="text-align:justify; textAlignLast:right"
_line-spacing

Specifies the space between two adjacent lines of text.

style="_line-spacing:10px"
style="_line-spacing:-15px"

The GdiGraphics.DrawFormattedText supports the following XML predeclared entities:

  • &amp; - & ampersand;
  • &lt; - < less than;
  • &gt; - > 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.

Note

The GdiGraphics.DrawFormattedText, unlike the GdiGraphics.DrawText, does not support the newline character (\n in C# and vbNewLine in VB). To draw a chunk of text from a new line you need to enclose it in <para></para> tags.

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.

Postcard Editor

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;
}

See Also

Reference

Manual