BeginXObjectForm Method (GdPicturePDF)

In This Topic

Creates and begins to define a new form XObject of the subtype Form, that includes all subsequently specified drawing operations until the adjacent GdPicturePDF.EndXObjectForm call. The resulting form XObject is identified by its resource name, which is meant to be used for each further drawing within the currently loaded PDF document. The newly defined form XObject becomes a part of the currently loaded PDF document's content as well.

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. So you can draw such a form XObject multiple times and it produces the same result on each specified location.

Syntax

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

'Declaration

 

Public Function BeginXObjectForm( _

   ByVal Width As Single, _

   ByVal Height As Single _

) As String

public string BeginXObjectForm( 

   float Width,

   float Height

)

public function BeginXObjectForm( 

    Width: Single;

    Height: Single

): String;

public function BeginXObjectForm( 

   Width : float,

   Height : float

) : String;

public: string* BeginXObjectForm( 

   float Width,

   float Height

)

public:

String^ BeginXObjectForm( 

   float Width,

   float Height

)

Parameters

Width: The width of the XObject's drawing canvas area, expressed in the current units specified by the SetMeasurementUnit method.
Height: The height of the XObject's drawing canvas area, expressed in the current units specified by the SetMeasurementUnit method.

Return Value

Returns a resource name of the newly created form XObject required for the next usage within the PDF document. The GdPicturePDF.GetStat method can be subsequently used to determine if this method has been successful.

This resource name you can subsequently pass to the GdPicturePDF.DrawXObjectForm method.

Remarks

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

Likewise, please avoid changing pages between calling both relevant GdPicturePDF.BeginXObjectForm and GdPicturePDF.EndXObjectForm methods, which causes loss of already specified drawing operations.

Example

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

VB.NET
C#

Dim caption As String = "Example: BeginXObjectForm"

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: BeginXObjectForm";

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
EndXObjectForm Method
DrawXObjectForm Method