AddCircleAnnotation Method (GdPicturePDF)

In This Topic

Adds a circle or an ellipse annotation object to the currently selected page of the loaded PDF document. The subtype attribute of this annotation is "Circle". The required shape is inscribed within the annotation's bounding box. When the annotation is opened, it displays a pop-up window with the content according to what you have specified.

This method uses the RGB color space for specifying the required color of the annotation object, here it is the border color of the circle or ellipse.

Syntax

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

'Declaration
 
Public Function AddCircleAnnotation( _
   ByVal Left As Single, _
   ByVal Top As Single, _
   ByVal Width As Single, _
   ByVal Height As Single, _
   ByVal Title As String, _
   ByVal Contents As String, _
   ByVal LineWidth As Single, _
   ByVal LineStyle As PdfAnnotationBorderStyle, _
   ByVal LineDashOn As Single, _
   ByVal LineDashOff As Single, _
   ByVal Opacity As Single, _
   ByVal Red As Byte, _
   ByVal Green As Byte, _
   ByVal Blue As Byte _
) As Integer

public int AddCircleAnnotation( 
   float Left,
   float Top,
   float Width,
   float Height,
   string Title,
   string Contents,
   float LineWidth,
   PdfAnnotationBorderStyle LineStyle,
   float LineDashOn,
   float LineDashOff,
   float Opacity,
   byte Red,
   byte Green,
   byte Blue
)

public function AddCircleAnnotation( 
    Left: Single;
    Top: Single;
    Width: Single;
    Height: Single;
    Title: String;
    Contents: String;
    LineWidth: Single;
    LineStyle: PdfAnnotationBorderStyle;
    LineDashOn: Single;
    LineDashOff: Single;
    Opacity: Single;
    Red: Byte;
    Green: Byte;
    Blue: Byte
): Integer;

public function AddCircleAnnotation( 
   Left : float,
   Top : float,
   Width : float,
   Height : float,
   Title : String,
   Contents : String,
   LineWidth : float,
   LineStyle : PdfAnnotationBorderStyle,
   LineDashOn : float,
   LineDashOff : float,
   Opacity : float,
   Red : byte,
   Green : byte,
   Blue : byte
) : int;

public: int AddCircleAnnotation( 
   float Left,
   float Top,
   float Width,
   float Height,
   string* Title,
   string* Contents,
   float LineWidth,
   PdfAnnotationBorderStyle LineStyle,
   float LineDashOn,
   float LineDashOff,
   float Opacity,
   byte Red,
   byte Green,
   byte Blue
)

public:
int AddCircleAnnotation( 
   float Left,
   float Top,
   float Width,
   float Height,
   String^ Title,
   String^ Contents,
   float LineWidth,
   PdfAnnotationBorderStyle LineStyle,
   float LineDashOn,
   float LineDashOff,
   float Opacity,
   byte Red,
   byte Green,
   byte Blue
)

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.
Title: The title of the newly added annotation object, by convention it represents the author of the annotation.
Contents: The content of the newly added annotation object, that means the text displayed in the annotation's note and in its associated pop-up window.
LineWidth: The width of the line used to draw the required shape, expressed in the current units specified by the SetMeasurementUnit method.
LineStyle: A member of the PdfAnnotationBorderStyle enumeration. The style of the line used to draw the required shape.
LineDashOn: If the style of the line (the LineStyle parameter) is dashed, this value defines the width of the dashes in the dash pattern used to draw the required shape. Otherwise, this parameter is ignored. The value is expressed in the current units specified by the SetMeasurementUnit method.
LineDashOff: If the style of the line (the LineStyle parameter) is dashed, this value defines the width of the gaps in the dash pattern used to draw the required shape. Otherwise, this parameter is ignored. The value is expressed in the current units specified by the SetMeasurementUnit method.
Opacity: The opacity value of the newly added annotation object, from 0 (full transparency) to 1 (full opacity).
Red: The amount of red color to be used for the resulting border color. Use the value between 0 and 255.
Green: The amount of green color to be used for the resulting border color. Use the value between 0 and 255.
Blue: The amount of blue color to be used for the resulting border color. Use the value between 0 and 255.

Return Value

The unique annotation index from 0 to GdPicturePDF.GetAnnotationCount-1 related to the currently selected page. The GdPicturePDF.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 GdPicturePDF.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 GdPicturePDF.SelectPage method before adding a required annotation. Likewise, just to inform you, that the toolkit doesn't create (unlike other applications can) a standalone associated pop-up annotation object within the internal document structure when creating the new circle annotation.

You also need to be aware that the values of coordinates and dimensions are expressed in the current units defined by the GdPicturePDF.SetMeasurementUnit method according to the current coordinate space defined by the GdPicturePDF.SetOrigin method.

Example

How to create a blue circle annotation on a new page of the PDF document.

VB.NET
C#

Dim caption As String = "Example: AddCircleAnnotation"
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
        'Each valid annotID should be >= 0, but it is recommended to check the error status, not the returned ID.
        Dim annotID As Integer = gdpicturePDF.AddCircleAnnotation(5, 10, 10, 6, "GdPicture", "This is a circle annotation.",
                                                                   0.5F, PdfAnnotationBorderStyle.PdfAnnotationBorderStyleDashed, 0.4F, 0.2F,
                                                                   0.5F, 0, 0, 255)
        If gdpicturePDF.GetStat() = GdPictureStatus.OK Then
            Dim annotType As String = gdpicturePDF.GetAnnotationType(annotID)
            Dim status1 As GdPictureStatus = gdpicturePDF.GetStat()
            Dim annotSubtype As String = gdpicturePDF.GetAnnotationSubType(annotID)
            Dim status2 As GdPictureStatus = 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("circle.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 AddCircleAnnotation() 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: AddCircleAnnotation";
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)
    {
        int annotID = gdpicturePDF.AddCircleAnnotation(5, 10, 10, 6, "GdPicture", "This is a circle annotation.",
                                                        0.5f, PdfAnnotationBorderStyle.PdfAnnotationBorderStyleDashed, 0.4f, 0.2f,
                                                        0.5f, 0, 0, 255);
        //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);
            GdPictureStatus status1 = gdpicturePDF.GetStat();
            string annotSubtype = gdpicturePDF.GetAnnotationSubType(annotID);
            GdPictureStatus 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("circle.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 AddCircleAnnotation() 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
SelectPage Method
GetAnnotationCount Method
GetAnnotationType Method
GetAnnotationSubType Method
AddSquareAnnotation Method
AddLineAnnotation Method