AddFreeTextAnnotation(Single,Single,Single,Single,Boolean,String,String,String,String,Single,Byte,Byte,Byte,Byte,Byte,Byte,Byte,Byte,Single) Method

In This Topic

Adds a free text annotation object to the currently selected page of the loaded PDF document. The subtype attribute of this annotation is "FreeText". This annotation displays text directly on the page according to what you have specified. This text is always visible, as this annotation doesn't have a pop-up window and can't be opened or closed.

This method uses the CMYK color space for specifying the required colors.

Syntax

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

'Declaration

 

Public Overloads Function AddFreeTextAnnotation( _

   ByVal Left As Single, _

   ByVal Top As Single, _

   ByVal Width As Single, _

   ByVal Height As Single, _

   ByVal Borders As Boolean, _

   ByVal Title As String, _

   ByVal Subject As String, _

   ByVal Contents As String, _

   ByVal FontResName As String, _

   ByVal FontSize As Single, _

   ByVal FontColorCyan As Byte, _

   ByVal FontColorMagenta As Byte, _

   ByVal FontColorYellow As Byte, _

   ByVal FontColorBlack As Byte, _

   ByVal FillColorCyan As Byte, _

   ByVal FillColorMagenta As Byte, _

   ByVal FillColorYellow As Byte, _

   ByVal FillColorBlack As Byte, _

   ByVal Opacity As Single _

) As Integer

public int AddFreeTextAnnotation( 

   float Left,

   float Top,

   float Width,

   float Height,

   bool Borders,

   string Title,

   string Subject,

   string Contents,

   string FontResName,

   float FontSize,

   byte FontColorCyan,

   byte FontColorMagenta,

   byte FontColorYellow,

   byte FontColorBlack,

   byte FillColorCyan,

   byte FillColorMagenta,

   byte FillColorYellow,

   byte FillColorBlack,

   float Opacity

)

public function AddFreeTextAnnotation( 

    Left: Single;

    Top: Single;

    Width: Single;

    Height: Single;

    Borders: Boolean;

    Title: String;

    Subject: String;

    Contents: String;

    FontResName: String;

    FontSize: Single;

    FontColorCyan: Byte;

    FontColorMagenta: Byte;

    FontColorYellow: Byte;

    FontColorBlack: Byte;

    FillColorCyan: Byte;

    FillColorMagenta: Byte;

    FillColorYellow: Byte;

    FillColorBlack: Byte;

    Opacity: Single

): Integer;

public function AddFreeTextAnnotation( 

   Left : float,

   Top : float,

   Width : float,

   Height : float,

   Borders : boolean,

   Title : String,

   Subject : String,

   Contents : String,

   FontResName : String,

   FontSize : float,

   FontColorCyan : byte,

   FontColorMagenta : byte,

   FontColorYellow : byte,

   FontColorBlack : byte,

   FillColorCyan : byte,

   FillColorMagenta : byte,

   FillColorYellow : byte,

   FillColorBlack : byte,

   Opacity : float

) : int;

public: int AddFreeTextAnnotation( 

   float Left,

   float Top,

   float Width,

   float Height,

   bool Borders,

   string* Title,

   string* Subject,

   string* Contents,

   string* FontResName,

   float FontSize,

   byte FontColorCyan,

   byte FontColorMagenta,

   byte FontColorYellow,

   byte FontColorBlack,

   byte FillColorCyan,

   byte FillColorMagenta,

   byte FillColorYellow,

   byte FillColorBlack,

   float Opacity

)

public:

int AddFreeTextAnnotation( 

   float Left,

   float Top,

   float Width,

   float Height,

   bool Borders,

   String^ Title,

   String^ Subject,

   String^ Contents,

   String^ FontResName,

   float FontSize,

   byte FontColorCyan,

   byte FontColorMagenta,

   byte FontColorYellow,

   byte FontColorBlack,

   byte FillColorCyan,

   byte FillColorMagenta,

   byte FillColorYellow,

   byte FillColorBlack,

   float Opacity

)

Parameters

Left: The horizontal (X) coordinate of the closest point to the currently defined origin, where the annotation's bounding box is to be located. The value is expressed in the current units specified by the SetMeasurementUnit method and it is related to the current page. For further assistance, please see the Remarks section below.
Top: The vertical (Y) coordinate of the closest point to the currently defined origin, where the annotation's bounding box is to be located. The value is expressed in the current units specified by the SetMeasurementUnit method and it is related to the current page. For further assistance, please see the Remarks section below.
Width: The width of the annotation's bounding box, expressed in the current units specified by the SetMeasurementUnit method.
Height: The height of the annotation's bounding box, expressed in the current units specified by the SetMeasurementUnit method.
Borders: Set this parameter to true, if you want to display borders around annotation's text, otherwise set it to false. These borders are inscribed within the annotation's bounding box and they are drawn with the same color as it is specified for annotation's text.
Title: The title of the newly added annotation object, by convention it represents the author of the annotation.
Subject: The subject of the newly added annotation object.
Contents: The content of the newly added annotation object, that means annotation's text to be displayed.
FontResName: The resource name of the font you prefer for drawing the annotation's content. You can 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.
FontSize: A text (font) size, in points, for drawing the annotation's content. Please note that 1 point = 1/72 inch.
FontColorCyan: The amount of cyan color to be used for the resulting color when displaying annotation's text. Use the value between 0 and 255.
FontColorMagenta: The amount of cyan color to be used for the resulting color when displaying annotation's text. Use the value between 0 and 255.
FontColorYellow: The amount of yellow color to be used for the resulting color when displaying annotation's text. Use the value between 0 and 255.
FontColorBlack: The amount of black color to be used for the resulting color when displaying annotation's text. Use the value between 0 and 255.
FillColorCyan: The amount of cyan color to be used for the resulting color when displaying the annotation's background. Use the value between 0 and 255.
FillColorMagenta: The amount of magenta color to be used for the resulting color when displaying the annotation's background. Use the value between 0 and 255.
FillColorYellow: The amount of yellow color to be used for the resulting color when displaying the annotation's background. Use the value between 0 and 255.
FillColorBlack: The amount of black color to be used for the resulting color when displaying the annotation's background. Use the value between 0 and 255.
Opacity: The opacity value of the newly added annotation object, from 0 (full transparency) to 1 (full opacity).

Return Value

The unique annotation index from 0 to GetAnnotationCount-1 related to the currently selected page. The GetStat method can be subsequently used to determine if this method has been successful.

Remarks

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

It is recommend to use the GetStat method to identify the specific reason for the method's failure, if any.

Please always ensure that you have selected the correct page using the SelectPage method before adding a required annotation.

You also need to 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 create a free text annotation on a new page of the PDF document.

VB.NET
C#

Dim caption As String = "Example: AddFreeTextAnnotation"

Dim gdpicturePDF As GdPicturePDF = New GdPicturePDF()

If (gdpicturePDF.NewPDF() = GdPictureStatus.OK) AndAlso

   (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) = GdPictureStatus.OK) Then

    gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft)

    gdpicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter)

    'Please always select the required page before adding an annotation.

    If gdpicturePDF.SelectPage(1) = GdPictureStatus.OK Then

        Dim textSize As Single = 20

        Dim text As String = "GdPicture freetext annot."

        Dim fontResName As String = gdpicturePDF.AddStandardFont(PdfStandardFont.PdfStandardFontHelvetica)

        If gdpicturePDF.GetStat() = GdPictureStatus.OK Then

            Dim textW As Single = gdpicturePDF.GetTextWidth(fontResName, textSize, text)

            Dim status1 As GdPictureStatus = gdpicturePDF.GetStat()

            Dim textH As Single = gdpicturePDF.GetTextHeight(fontResName, textSize, False)

            Dim status2 As GdPictureStatus = gdpicturePDF.GetStat()

            If (status1 = GdPictureStatus.OK) AndAlso (status2 = GdPictureStatus.OK) Then

                Dim annotID As Integer = gdpicturePDF.AddFreeTextAnnotation(5, 5, textW, textH, False, "GdPicture", "Review", text,

                                                                             fontResName, textSize, 90, 213, 213, 90, 0, 90, 255, 0, 0.75F)

                'Each valid annotID should be >= 0, but it is recommended to check the error status, not the returned ID.

                If gdpicturePDF.GetStat() = GdPictureStatus.OK Then

                    Dim annotType As String = gdpicturePDF.GetAnnotationType(annotID)

                    status1 = gdpicturePDF.GetStat()

                    Dim annotSubtype As String = gdpicturePDF.GetAnnotationSubType(annotID)

                    status2 = gdpicturePDF.GetStat()

                    Dim message As String = "The annotation has been created with the ID = " + annotID.ToString() + "." + vbCrLf + "type: "

                    If status1 = GdPictureStatus.OK Then message = message + annotType Else message = message + status1.ToString()

                    message = message + "    subtype: "

                    If status2 = GdPictureStatus.OK Then message = message + annotSubtype Else message = message + status2.ToString()

                    If gdpicturePDF.SaveToFile("freetext.pdf") = GdPictureStatus.OK Then

                        message = message + vbCrLf + "The file has been saved."

                    Else

                        message = message + vbCrLf + "The file can't be saved. Status: " + gdpicturePDF.GetStat().ToString()

                    End If

                    MessageBox.Show(message, caption)

                Else

                    MessageBox.Show("The AddFreeTextAnnotation() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption)

                End If

            Else

                MessageBox.Show("The GetTextWidth()/GetTextHeight() method has failed with the status: " + status1.ToString() + "/" + status2.ToString(), caption)

            End If

        Else

            MessageBox.Show("The AddStandardFont() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption)

        End If

    Else

        MessageBox.Show("The SelectPage() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption)

    End If

Else

    MessageBox.Show("The file can't be created.", caption)

End If

gdpicturePDF.Dispose()

string caption = "Example: AddFreeTextAnnotation";

GdPicturePDF gdpicturePDF = new GdPicturePDF();

if ((gdpicturePDF.NewPDF() == GdPictureStatus.OK) &&

    (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) == GdPictureStatus.OK))

{

    gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft);

    gdpicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter);

    //Please always select the required page before adding an annotation.

    if (gdpicturePDF.SelectPage(1) == GdPictureStatus.OK)

    {

        float textSize = 20;

        string text = "GdPicture freetext annot.";

        string fontResName = gdpicturePDF.AddStandardFont(PdfStandardFont.PdfStandardFontHelvetica);

        if (gdpicturePDF.GetStat() == GdPictureStatus.OK)

        {

            float textW = gdpicturePDF.GetTextWidth(fontResName, textSize, text);

            GdPictureStatus status1 = gdpicturePDF.GetStat();

            float textH = gdpicturePDF.GetTextHeight(fontResName, textSize, false);

            GdPictureStatus status2 = gdpicturePDF.GetStat();

            if ((status1 == GdPictureStatus.OK) && (status2 == GdPictureStatus.OK))

            {

                int annotID = gdpicturePDF.AddFreeTextAnnotation(5, 5, textW, textH, false, "GdPicture", "Review", text,

                                                                  fontResName, textSize, 90, 213, 213, 90, 0, 90, 255, 0, 0.75f);

                //Each valid annotID should be >= 0, but it is recommended to check the error status, not the returned ID.

                if (gdpicturePDF.GetStat() == GdPictureStatus.OK)

                {

                    string annotType = gdpicturePDF.GetAnnotationType(annotID);

                    status1 = gdpicturePDF.GetStat();

                    string annotSubtype = gdpicturePDF.GetAnnotationSubType(annotID);

                    status2 = gdpicturePDF.GetStat();

                    string message = "The annotation has been created with the ID = " + annotID.ToString() + ".\ntype: ";

                    if (status1 == GdPictureStatus.OK) message = message + annotType; else message = message + status1.ToString();

                    message = message + "    subtype: ";

                    if (status2 == GdPictureStatus.OK) message = message + annotSubtype; else message = message + status2.ToString();

                    if (gdpicturePDF.SaveToFile("freetext.pdf") == GdPictureStatus.OK)

                        message = message + "\nThe file has been saved.";

                    else

                        message = message + "\nThe file can't be saved. Status: " + gdpicturePDF.GetStat().ToString();

                    MessageBox.Show(message, caption);

                }

                else

                    MessageBox.Show("The AddFreeTextAnnotation() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption);

            }

            else

                MessageBox.Show("The GetTextWidth()/GetTextHeight() method has failed with the status: " + status1.ToString() + "/" + status2.ToString(), caption);

        }

        else

            MessageBox.Show("The AddStandardFont() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption);

    }

    else

        MessageBox.Show("The SelectPage() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption);

}

else

    MessageBox.Show("The file can't be created.", caption);

gdpicturePDF.Dispose();

Example

How to create a free text annotation on a new page of the PDF document. Dim caption As String = "Example: AddFreeTextAnnotation" Dim gdpicturePDF As GdPicturePDF = New GdPicturePDF() If (gdpicturePDF.NewPDF() = GdPictureStatus.OK) AndAlso (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) = GdPictureStatus.OK) Then gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft) gdpicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter) 'Please always select the required page before adding an annotation. If gdpicturePDF.SelectPage(1) = GdPictureStatus.OK Then Dim textSize As Single = 20 Dim text As String = "GdPicture freetext annot." Dim fontResName As String = gdpicturePDF.AddStandardFont(PdfStandardFont.PdfStandardFontHelvetica) If gdpicturePDF.GetStat() = GdPictureStatus.OK Then Dim textW As Single = gdpicturePDF.GetTextWidth(fontResName, textSize, text) Dim status1 As GdPictureStatus = gdpicturePDF.GetStat() Dim textH As Single = gdpicturePDF.GetTextHeight(fontResName, textSize, False) Dim status2 As GdPictureStatus = gdpicturePDF.GetStat() If (status1 = GdPictureStatus.OK) AndAlso (status2 = GdPictureStatus.OK) Then Dim annotID As Integer = gdpicturePDF.AddFreeTextAnnotation(5, 5, textW, textH, False, "GdPicture", "Review", text, fontResName, textSize, 90, 213, 213, 90, 0, 90, 255, 0, 0.75F) 'Each valid annotID should be >= 0, but it is recommended to check the error status, not the returned ID. If gdpicturePDF.GetStat() = GdPictureStatus.OK Then Dim annotType As String = gdpicturePDF.GetAnnotationType(annotID) status1 = gdpicturePDF.GetStat() Dim annotSubtype As String = gdpicturePDF.GetAnnotationSubType(annotID) status2 = gdpicturePDF.GetStat() Dim message As String = "The annotation has been created with the ID = " + annotID.ToString() + "." + vbCrLf + "type: " If status1 = GdPictureStatus.OK Then message = message + annotType Else message = message + status1.ToString() message = message + " subtype: " If status2 = GdPictureStatus.OK Then message = message + annotSubtype Else message = message + status2.ToString() If gdpicturePDF.SaveToFile("freetext.pdf") = GdPictureStatus.OK Then message = message + vbCrLf + "The file has been saved." Else message = message + vbCrLf + "The file can't be saved. Status: " + gdpicturePDF.GetStat().ToString() End If MessageBox.Show(message, caption) Else MessageBox.Show("The AddFreeTextAnnotation() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption) End If Else MessageBox.Show("The GetTextWidth()/GetTextHeight() method has failed with the status: " + status1.ToString() + "/" + status2.ToString(), caption) End If Else MessageBox.Show("The AddStandardFont() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption) End If Else MessageBox.Show("The SelectPage() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption) End If Else MessageBox.Show("The file can't be created.", caption) End If gdpicturePDF.Dispose() string caption = "Example: AddFreeTextAnnotation"; GdPicturePDF gdpicturePDF = new GdPicturePDF(); if ((gdpicturePDF.NewPDF() == GdPictureStatus.OK) && (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) == GdPictureStatus.OK)) { gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft); gdpicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter); //Please always select the required page before adding an annotation. if (gdpicturePDF.SelectPage(1) == GdPictureStatus.OK) { float textSize = 20; string text = "GdPicture freetext annot."; string fontResName = gdpicturePDF.AddStandardFont(PdfStandardFont.PdfStandardFontHelvetica); if (gdpicturePDF.GetStat() == GdPictureStatus.OK) { float textW = gdpicturePDF.GetTextWidth(fontResName, textSize, text); GdPictureStatus status1 = gdpicturePDF.GetStat(); float textH = gdpicturePDF.GetTextHeight(fontResName, textSize, false); GdPictureStatus status2 = gdpicturePDF.GetStat(); if ((status1 == GdPictureStatus.OK) && (status2 == GdPictureStatus.OK)) { int annotID = gdpicturePDF.AddFreeTextAnnotation(5, 5, textW, textH, false, "GdPicture", "Review", text, fontResName, textSize, 90, 213, 213, 90, 0, 90, 255, 0, 0.75f); //Each valid annotID should be >= 0, but it is recommended to check the error status, not the returned ID. if (gdpicturePDF.GetStat() == GdPictureStatus.OK) { string annotType = gdpicturePDF.GetAnnotationType(annotID); status1 = gdpicturePDF.GetStat(); string annotSubtype = gdpicturePDF.GetAnnotationSubType(annotID); status2 = gdpicturePDF.GetStat(); string message = "The annotation has been created with the ID = " + annotID.ToString() + ".\ntype: "; if (status1 == GdPictureStatus.OK) message = message + annotType; else message = message + status1.ToString(); message = message + " subtype: "; if (status2 == GdPictureStatus.OK) message = message + annotSubtype; else message = message + status2.ToString(); if (gdpicturePDF.SaveToFile("freetext.pdf") == GdPictureStatus.OK) message = message + "\nThe file has been saved."; else message = message + "\nThe file can't be saved. Status: " + gdpicturePDF.GetStat().ToString(); MessageBox.Show(message, caption); } else MessageBox.Show("The AddFreeTextAnnotation() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption); } else MessageBox.Show("The GetTextWidth()/GetTextHeight() method has failed with the status: " + status1.ToString() + "/" + status2.ToString(), caption); } else MessageBox.Show("The AddStandardFont() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption); } else MessageBox.Show("The SelectPage() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption); } else MessageBox.Show("The file can't be created.", caption); gdpicturePDF.Dispose();

Reference

GdPicturePDF Class
GdPicturePDF Members
Overload List
AddStandardFont Method
GetStat Method
SelectPage Method
SetMeasurementUnit Method
SetOrigin Method
GetAnnotationCount Method
GetStat Method
SelectPage Method
GetAnnotationCount Method
GetAnnotationType Method
GetAnnotationSubType Method
AddStickyNoteAnnotation Method