DrawXObjectForm Method (GdPicturePDF)

In This Topic

Draws an existing form XObject, identified by its resource name within the loaded PDF document, onto the currently selected page according to what you have specified.

A form XObject is a structure within a PDF document, that describes objects (text, images, vectors, etc.) used repetitively in the document to avoid multiple referencing of these objects in the document's content. Each form XObject is identified by its unique resource name defined when creating the object.

Syntax

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

'Declaration
 
Public Function DrawXObjectForm( _
   ByVal ResourceName As String, _
   ByVal DstX As Single, _
   ByVal DstY As Single, _
   ByVal ScaleX As Single, _
   ByVal ScaleY As Single _
) As GdPictureStatus

public GdPictureStatus DrawXObjectForm( 
   string ResourceName,
   float DstX,
   float DstY,
   float ScaleX,
   float ScaleY
)

public function DrawXObjectForm( 
    ResourceName: String;
    DstX: Single;
    DstY: Single;
    ScaleX: Single;
    ScaleY: Single
): GdPictureStatus;

public function DrawXObjectForm( 
   ResourceName : String,
   DstX : float,
   DstY : float,
   ScaleX : float,
   ScaleY : float
) : GdPictureStatus;

public: GdPictureStatus DrawXObjectForm( 
   string* ResourceName,
   float DstX,
   float DstY,
   float ScaleX,
   float ScaleY
)

public:
GdPictureStatus DrawXObjectForm( 
   String^ ResourceName,
   float DstX,
   float DstY,
   float ScaleX,
   float ScaleY
)

Parameters

ResourceName: The form XObject resource name as a string. You can obtain this name using the GdPicturePDF.BeginXObjectForm method.
DstX: The horizontal (X) coordinate of the bottom left point, where the required XObject is to be drawn, expressed in the current units specified by the SetMeasurementUnit method with respect to the currently defined origin, related to the currently selected page.
DstY: The vertical (Y) coordinate of the bottom left point, where the required XObject is to be drawn, expressed in the current units specified by the SetMeasurementUnit method with respect to the currently defined origin, related to the currently selected page.
ScaleX: The horizontal scale factor for drawing, it corresponds to the XObject's width.
For example, if this parameter is set to 2.0, it multiplies the width of the specified form XObject by 2, and if it is set to 0.5, it divides the width by 2.
ScaleY: The vertical scale factor for drawing, it corresponds to the XObject's height.
For example, if this parameter is set to 2.0, it multiplies the height of the specified form XObject by 2, and if it is set to 0.5, it divides the height by 2.

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 GdPicturePDF.SetMeasurementUnit method according to the current coordinate space defined by the GdPicturePDF.SetOrigin method.

Example

How to define a form XObject and how to use it further.

VB.NET
C#

Dim caption As String = "Example: DrawXObjectForm"
Using gdpicturePDF As GdPicturePDF = New GdPicturePDF()
    If (gdpicturePDF.NewPDF(PdfConformance.PDF_UA_1) = GdPictureStatus.OK) AndAlso
       (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) = GdPictureStatus.OK) AndAlso
       (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) = GdPictureStatus.OK) AndAlso
       (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) = GdPictureStatus.OK) Then
        gdpicturePDF.SelectPage(1)
        Dim fontResName As String = gdpicturePDF.AddTrueTypeFontU("Arial", False, False, False)
        If gdpicturePDF.GetStat() = GdPictureStatus.OK Then
            gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft)
            Dim xObjResName As String = gdpicturePDF.BeginXObjectForm(120, 40)
            If gdpicturePDF.GetStat() = GdPictureStatus.OK Then
                If (gdpicturePDF.SetFillColor(Color.Red) = GdPictureStatus.OK) AndAlso
                   (gdpicturePDF.SetTextSize(12) = GdPictureStatus.OK) AndAlso
                   (gdpicturePDF.DrawText(fontResName, 15, 20, "GdPicture SDK") = GdPictureStatus.OK) AndAlso
                   (gdpicturePDF.SetTextSize(8) = GdPictureStatus.OK) AndAlso
                   (gdpicturePDF.DrawText(fontResName, 15, 30, "used as reusable stamp") = GdPictureStatus.OK) AndAlso
                   (gdpicturePDF.SetLineColor(Color.Red) = GdPictureStatus.OK) AndAlso
                   (gdpicturePDF.DrawRectangle(0, 0, 120, 40, False, True) = GdPictureStatus.OK) Then
                    If gdpicturePDF.EndXObjectForm() = GdPictureStatus.OK Then
                        If (gdpicturePDF.DrawXObjectForm(xObjResName, 50, 100, 1, 1) = GdPictureStatus.OK) AndAlso
                           (gdpicturePDF.SelectPage(2) = GdPictureStatus.OK) AndAlso
                           (gdpicturePDF.DrawXObjectForm(xObjResName, 50, 300, 2, 2) = GdPictureStatus.OK) AndAlso
                           (gdpicturePDF.SelectPage(3) = GdPictureStatus.OK) AndAlso
                           (gdpicturePDF.DrawXObjectForm(xObjResName, 50, 400, 0.5F, 0.5F) = GdPictureStatus.OK) Then
                            If gdpicturePDF.SaveToFile("XObject_test.pdf") = GdPictureStatus.OK Then
                                MessageBox.Show("Your PDF document with form XObject has been successfully created.", caption)
                            Else
                                MessageBox.Show("The file can't be saved. Status: " + gdpicturePDF.GetStat().ToString(), caption)
                            End If
                        Else
                            MessageBox.Show("Drawing a newly created XObject has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption)
                        End If
                    Else
                        MessageBox.Show("The EndXObjectForm() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption)
                    End If
                Else
                    MessageBox.Show("Drawing a stamp has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption)
                End If
            Else
                MessageBox.Show("The BeginXObjectForm() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption)
            End If
        Else
            MessageBox.Show("Adding font has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption)
        End If
    Else
        MessageBox.Show("The new document can't be created. Status: " + gdpicturePDF.GetStat().ToString(), caption)
    End If
End Using

string caption = "Example: DrawXObjectForm";
using (GdPicturePDF gdpicturePDF = new GdPicturePDF())
{
    if ((gdpicturePDF.NewPDF(PdfConformance.PDF_UA_1) == GdPictureStatus.OK) &&
        (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) == GdPictureStatus.OK) &&
        (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) == GdPictureStatus.OK) &&
        (gdpicturePDF.NewPage(PdfPageSizes.PdfPageSizeA4) == GdPictureStatus.OK))
    {
        gdpicturePDF.SelectPage(1);
        string fontResName = gdpicturePDF.AddTrueTypeFontU("Arial", false, false, false);
        if (gdpicturePDF.GetStat() == GdPictureStatus.OK)
        {
            gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft);
            string xObjResName = gdpicturePDF.BeginXObjectForm(120, 40);
            if (gdpicturePDF.GetStat() == GdPictureStatus.OK)
            {
                if ((gdpicturePDF.SetFillColor(Color.Red) == GdPictureStatus.OK) &&
                    (gdpicturePDF.SetTextSize(12) == GdPictureStatus.OK) &&
                    (gdpicturePDF.DrawText(fontResName, 15, 20, "GdPicture SDK") == GdPictureStatus.OK) &&
                    (gdpicturePDF.SetTextSize(8) == GdPictureStatus.OK) &&
                    (gdpicturePDF.DrawText(fontResName, 15, 30, "used as reusable stamp") == GdPictureStatus.OK) &&
                    (gdpicturePDF.SetLineColor(Color.Red) == GdPictureStatus.OK) &&
                    (gdpicturePDF.DrawRectangle(0, 0, 120, 40, false, true) == GdPictureStatus.OK))
                {
                    if (gdpicturePDF.EndXObjectForm() == GdPictureStatus.OK)
                    {
                        if ((gdpicturePDF.DrawXObjectForm(xObjResName, 50, 100, 1, 1) == GdPictureStatus.OK) &&
                            (gdpicturePDF.SelectPage(2) == GdPictureStatus.OK) &&
                            (gdpicturePDF.DrawXObjectForm(xObjResName, 50, 300, 2, 2) == GdPictureStatus.OK) &&
                            (gdpicturePDF.SelectPage(3) == GdPictureStatus.OK) &&
                            (gdpicturePDF.DrawXObjectForm(xObjResName, 50, 400, 0.5F, 0.5F) == GdPictureStatus.OK))
                        {
                            if (gdpicturePDF.SaveToFile("XObject_test.pdf") == GdPictureStatus.OK)
                                MessageBox.Show("Your PDF document with form XObject has been successfully created.", caption);
                            else
                                MessageBox.Show("The file can't be saved. Status: " + gdpicturePDF.GetStat().ToString(), caption);
                        }
                        else
                            MessageBox.Show("Drawing a newly created XObject has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption);
                    }
                    else
                        MessageBox.Show("The EndXObjectForm() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption);
                }
                else
                    MessageBox.Show("Drawing a stamp has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption);
            }
            else
                MessageBox.Show("The BeginXObjectForm() method has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption);
        }
        else
            MessageBox.Show("Adding font has failed with the status: " + gdpicturePDF.GetStat().ToString(), caption);
    }
    else
        MessageBox.Show("The new document can't be created. Status: " + gdpicturePDF.GetStat().ToString(), caption);
}

Reference

GdPicturePDF Class
GdPicturePDF Members
BeginXObjectForm Method
EndXObjectForm Method