DrawTextBox(String,Single,Single,Single,Single,TextAlignment,TextAlignment,String,Boolean) Method

In This Topic

Draws an aligned text, supporting multiline text as well, using the specified font to fit the defined text box located on the currently selected page of the loaded PDF document. You need to set the text box coordinates in the current units with respect to the currently located origin defined in the PDF document, at the same all coordinates are related to the actual page, where the text is to be drawn. You are also allowed to specify both horizontal and vertical text alignment within the text box, as well as use of the font boundary box attribute when drawing. If the part of your text is not drawn, it may be because the text box is too small to hold entire text.

You can use the GetMeasurementUnit method to determine the currently defined units together with the GetOrigin method to determine the current origin location and you can also use the SetMeasurementUnit method to reset the units together with the SetOrigin method to reset the origin location according to your preference.

Syntax

Visual Basic
C#
Delphi
JScript
Managed Extensions for C++
C++/CLI

'Declaration
 
Public Overloads Function DrawTextBox( _
   ByVal FontResName As String, _
   ByVal Left As Single, _
   ByVal Top As Single, _
   ByVal Right As Single, _
   ByVal Bottom As Single, _
   ByVal HorizontalAlignment As TextAlignment, _
   ByVal VerticalAlignment As TextAlignment, _
   ByVal Text As String, _
   ByVal UseFontBBox As Boolean _
) As GdPictureStatus

public GdPictureStatus DrawTextBox( 
   string FontResName,
   float Left,
   float Top,
   float Right,
   float Bottom,
   TextAlignment HorizontalAlignment,
   TextAlignment VerticalAlignment,
   string Text,
   bool UseFontBBox
)

public function DrawTextBox( 
    FontResName: String;
    Left: Single;
    Top: Single;
    Right: Single;
    Bottom: Single;
    HorizontalAlignment: TextAlignment;
    VerticalAlignment: TextAlignment;
    Text: String;
    UseFontBBox: Boolean
): GdPictureStatus;

public function DrawTextBox( 
   FontResName : String,
   Left : float,
   Top : float,
   Right : float,
   Bottom : float,
   HorizontalAlignment : TextAlignment,
   VerticalAlignment : TextAlignment,
   Text : String,
   UseFontBBox : boolean
) : GdPictureStatus;

public: GdPictureStatus DrawTextBox( 
   string* FontResName,
   float Left,
   float Top,
   float Right,
   float Bottom,
   TextAlignment HorizontalAlignment,
   TextAlignment VerticalAlignment,
   string* Text,
   bool UseFontBBox
)

public:
GdPictureStatus DrawTextBox( 
   String^ FontResName,
   float Left,
   float Top,
   float Right,
   float Bottom,
   TextAlignment HorizontalAlignment,
   TextAlignment VerticalAlignment,
   String^ Text,
   bool UseFontBBox
)

Parameters

FontResName: The resource name of the font you prefer for drawing your text.
You can easily obtain this name using the AddStandardFont method or any of the AddTrueTypeFont...() methods. For further assistance, please see the Fonts section of the GdPicturePDF class in the Reference Guide.
Left: The horizontal (X) coordinate of the closest point to the currently defined origin, where the text box is located, in the current units used in the PDF document, related to the currently selected page.
Top: The vertical (Y) coordinate of the closest point to the currently defined origin, where the text box is located, in the current units used in the PDF document, related to the currently selected page.
Right: The horizontal (X) coordinate of the furthest point to the currently defined origin, where the text box is located, in the current units used in the PDF document, related to the currently selected page.
Bottom: The vertical (Y) coordinate of the furthest point to the currently defined origin, where the text box is located, in the current units used in the PDF document, related to the currently selected page.
HorizontalAlignment: The required horizontal text alignment mode, that is used to draw text within the specified text box.
VerticalAlignment: The required vertical text alignment mode, that is used to draw text within the specified text box.
Text: The required text to draw. It can be multiline text as well.
UseFontBBox: Set this parameter to false (generally used as the default value) if you want to calculate the text height by using the font's ascent and descent properties. The ascent property is the distance from the baseline to the highest grid coordinate used to place an outline point, the descent property to the lowest grid coordinate.
Set this parameter to true if you want to calculate the text height by using the font boundary box. It is an imaginary box that encloses all glyphs from the font, usually as tightly as possible. This helps to increase the line spacing in drawn text.

Return Value

A member of the GdPictureStatus enumeration. If the method has been successfully followed, then the return value is GdPictureStatus.OK.

We strongly recommend always checking this status first.

Remarks

This method is only allowed for use with non-encrypted documents.

Be aware that the values of coordinates and dimensions are expressed in the current units defined by the SetMeasurementUnit method according to the current coordinate space defined by the SetOrigin method.

Example

How to draw multiline text to fit the specified text box. The example shows you differences in drawing when using the font boundary box attribute.

VB.NET
C#

Dim caption As String = "Example: DrawTextBox"
Dim message As String = ""
Dim gdpicturePDF As New GdPicturePDF()
Dim status As GdPictureStatus = gdpicturePDF.NewPDF()
If status = GdPictureStatus.OK Then
    gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft)
    gdpicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter)
    Dim fontName As String = gdpicturePDF.AddStandardFont(PdfStandardFont.PdfStandardFontCourierOblique)
    If gdpicturePDF.GetStat() = GdPictureStatus.OK Then
        Dim multiText As String = "A friend is a need, a friend is indeed." + vbCrLf +
                                  "Whether there is a thunderstorm or strong wind blowing," + vbCrLf +
                                  "Friendship is like a tree that keeps glowing." + vbCrLf +
                                  "A friend is ray of hope in darkness," + vbCrLf + "as no less than treasure of happiness."
        If (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) = GdPictureStatus.OK) AndAlso
           (gdpicturePDF.SetFillColor(Color.DarkOrchid) = GdPictureStatus.OK) AndAlso
           (gdpicturePDF.SetTextSize(20) = GdPictureStatus.OK) AndAlso
           (gdpicturePDF.SetLineWidth(0.05F) = GdPictureStatus.OK) AndAlso
           (gdpicturePDF.DrawRectangle(2, 2, 17, 6, False, True) = GdPictureStatus.OK) AndAlso
           (gdpicturePDF.DrawTextBox(fontName, 2, 2, 19, 8, TextAlignment.TextAlignmentCenter, TextAlignment.TextAlignmentCenter, multiText, False) = GdPictureStatus.OK) AndAlso
           (gdpicturePDF.DrawRectangle(2, 10, 17, 6, False, True) = GdPictureStatus.OK) AndAlso
           (gdpicturePDF.DrawTextBox(fontName, 2, 10, 19, 16, TextAlignment.TextAlignmentCenter, TextAlignment.TextAlignmentCenter, multiText, True) = GdPictureStatus.OK) Then
            status = gdpicturePDF.SaveToFile("test_DrawTextBox.pdf")
            If status = GdPictureStatus.OK Then
                message = "The example has been followed successfully and the file has been saved."
            Else
                message = "The example has been followed successfully, but the file can't be saved. Status: " + status.ToString()
            End If
        Else
            message = "The example has not been followed successfully." + vbCrLf + "The last known status is " + gdpicturePDF.GetStat().ToString()
        End If
    Else
        message = "The AddStandardFont() method has failed with the status: " + status.ToString()
    End If
Else
    message = "The NewPDF() method has failed with the status: " + status.ToString()
End If
MessageBox.Show(message, caption)
gdpicturePDF.Dispose()

string caption = "Example: DrawTextBox";
string message = "";
GdPicturePDF gdpicturePDF = new GdPicturePDF();
GdPictureStatus status = gdpicturePDF.NewPDF();
if (status == GdPictureStatus.OK)
{
    gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft);
    gdpicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter);
    string fontName = gdpicturePDF.AddStandardFont(PdfStandardFont.PdfStandardFontCourierOblique);
    if (gdpicturePDF.GetStat() == GdPictureStatus.OK)
    {
        string multiText = "A friend is a need, a friend is indeed.\nWhether there is a thunderstorm or strong wind blowing,\nFriendship is like a tree that keeps glowing." +
                           "\nA friend is ray of hope in darkness,\nas no less than treasure of happiness.";
        if ((gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) == GdPictureStatus.OK) &&
            (gdpicturePDF.SetFillColor(Color.DarkOrchid) == GdPictureStatus.OK) &&
            (gdpicturePDF.SetTextSize(20) == GdPictureStatus.OK) &&
            (gdpicturePDF.SetLineWidth(0.05f) == GdPictureStatus.OK) &&
            (gdpicturePDF.DrawRectangle(2, 2, 17, 6, false, true) == GdPictureStatus.OK) &&
            (gdpicturePDF.DrawTextBox(fontName, 2, 2, 19, 8, TextAlignment.TextAlignmentCenter, TextAlignment.TextAlignmentCenter, multiText, false) == GdPictureStatus.OK) &&
            (gdpicturePDF.DrawRectangle(2, 10, 17, 6, false, true) == GdPictureStatus.OK) &&
            (gdpicturePDF.DrawTextBox(fontName, 2, 10, 19, 16, TextAlignment.TextAlignmentCenter, TextAlignment.TextAlignmentCenter, multiText, true) == GdPictureStatus.OK))
        {
            status = gdpicturePDF.SaveToFile("test_DrawTextBox.pdf");
            if (status == GdPictureStatus.OK)
                message = "The example has been followed successfully and the file has been saved.";
            else
                message = "The example has been followed successfully, but the file can't be saved. Status: " + status.ToString();
        }
        else
            message = "The example has not been followed successfully.\nThe last known status is " + gdpicturePDF.GetStat().ToString();
    }
    else
        message = "The AddStandardFont() method has failed with the status: " + status.ToString();
}
else
    message = "The NewPDF() method has failed with the status: " + status.ToString();
MessageBox.Show(message, caption);
gdpicturePDF.Dispose();

Reference

GdPicturePDF Class
GdPicturePDF Members
Overload List
GetMeasurementUnit Method
GetOrigin Method
SetMeasurementUnit Method
SetOrigin Method
DrawText Method
GetTextHeight(String,Single) Method
GetTextWidth Method
AddStandardFont Method
AddTrueTypeFont Method