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