Pages

Each page of a document is represented by a page object that includes references to the content and other attributes of a page. GcPdf provides Page class held in GrapeCity.Documents.Pdf assembly to allow you to work with pages. The Page class represents a page in GcPdfDocument. To get started, you need to add a page to your PDF document using NewPage method. When a new page is created, it is added to the page collection which is a collection of document's pages. The collection allows standard collection operations, such as adding, inserting, deleting, and moving elements(pages). These pages can be modified using the following page properties for individual pages while creating a PDF document.

Page orientation: Allows you to set the orientation of the current page using Landscape property. The default orientation of the page is set to portrait.
Boundaries: Allows you to set five boundaries of a page, namely Art box, Bleed box, Crop box, Media box, and Trim box, which are defined below.
- Art box: Defines the area covered by the meaningful content including potential white space.
- Bleed box: Defines the region up to which the page's content shall be cropped when the page is to be printed.
- Crop box: Defines the region up to which the page's content shall be cropped when the page is printed or viewed on a system. This is set as default page boundary.
- Media box: Defines the boundaries of the medium on which the page will be printed.
- Trim box: Defines the intended dimensions of the printable page after trimming.
For more information on page boundaries, see PDF specification 1.7 (Section 14.11.2).
Page size: Allows you to set the size of current page through Size property.
Rotation: Allows you to set the degrees by which a page can be rotated clockwise through Rotate property.
Content stream: Allows you to get the collection of content stream representing content of the page using ContentStreams property. A content stream is a PDF stream object which contains data comprising sequence of instructions, in the form of PDF objects, describing the graphical elements to be drawn on a page.

Insert a Page

To insert an empty page in a PDF document:

Create an object of GcPdfDocument class.

Access the NewPage method of GcDdfDocument class using the GcPdfDocument object.

GcPdfDocument doc = new GcPdfDocument();
// Adds a new blank page
var page = doc.NewPage();

Get a Particular Page

To get a particular page from a document:

Create an instance of PageCollection class that includes all the pages added in a PDF document.

Use the PageCollection object to access any particular page using its index value.

// Load an existing PDF using FileStream
FileStream fileStream = File.OpenRead(args[0].ToString());
GcPdfDocument doc = new GcPdfDocument();
doc.Load(fileStream, null);

// Use the PageCollection object to get page properties
PageCollection pageCollection = doc.Pages;
// Get the owner of the page
Console.WriteLine("Page Owner: {0}", pageCollection[0].Owner);

Get Page Properties

To get page properties:

Create an instance of PageCollection class that includes all the pages added in a PDF document.
Use the PageCollection object to access any particular page using its index value.

Access the properties associated to a particular page through its page index, for example, Size property.

// Load an existing PDF using FileStream
FileStream fileStream = File.OpenRead(args[0].ToString());
GcPdfDocument doc = new GcPdfDocument();
var page = doc.NewPage();
doc.Load(fileStream, null);

// Use the PageCollection object to get a particular page
PageCollection pageCollection = doc.Pages;
// Get the size of first page
Console.WriteLine("Paper Size: {0}", pageCollection[0].Size);

Set Page Properties

To set page properties:

Create an object of GcPdfDocument class.
Access the NewPage method using the GcPdfDocument object.

Use the page object to set a page property, for example, Rotate property.

GcPdfDocument doc = new GcPdfDocument();
// Adds a new blank page
var page = doc.NewPage();

// Set the page property
page.Rotate = 90;

Set PageSize and Orientation

To set a new page size and orientation in a document:

Add a new page in the PDF document using NewPage method of GcPdfDocument class.

Set the PaperKind and Landscape property using the page object.

var doc = new GcPdfDocument();
// The default page size is Letter (8 1/2" x 11") with portrait orientation
var page = doc.NewPage();

// Change the page size and orientation
page.PaperKind = PaperKind.A4;
page.Landscape = true;

Add Page Labels

GcPdf allows to define page labels with meaningful descriptions rather than just page numbers for identifying a page in a PDF document. Page labels allow to subdivide the document into sequences of logically related page ranges. In addition, it allows you to add multiple page labeling ranges in a single PDF document, that do not intersect each other. This can be very helpful when the PDF document contains different sections such as preface, acknowledgment, main body, index etc.

In GcPdf, the PageLabelingRange class represents a page labeling range which helps in defining the page numbering style for the range and a meaningful prefix that denotes the range. To add page labels in a PDF document, use the PageLabelingRanges property provided by the GcPdfDocument class as shown in the code below.

public void CreatePDF()
{
    //Initialize GcPdfDocument 
    var doc = new GcPdfDocument();           

    //Define text layout                      
    var tl = new TextLayout(72);
    tl.MaxWidth = doc.PageSize.Width;
    tl.MaxHeight = doc.PageSize.Height;           
    TextSplitOptions to = new TextSplitOptions(tl)
    {                
        MinLinesInFirstParagraph = 2,
        MinLinesInLastParagraph = 2
    };            
    doc.Pages.Add();
    // Generate random text for the document
    doc.Pages.Last.Graphics.DrawTextLayout(tl, PointF.Empty);
    tl.Clear();
    tl.Append(Common.Util.LoremIpsum(17));
    tl.PerformLayout(true); 
    // Print the random text
    while (true)
    {               
        var splitResult = tl.Split(to, out TextLayout rest);
        doc.Pages.Last.Graphics.DrawTextLayout(tl, PointF.Empty);
        if (splitResult != SplitResult.Split)
            break;
        tl = rest;
        var p = doc.Pages.Add();
    }
    //Define PageLabelingRange for content pages
    //PageLabelingRange uses DecimalArabic NumberingStyle and "Content Page, p. " as pre 
    //of the page label
    doc.PageLabelingRanges.Add(2, new PageLabelingRange($"Content Page, p. ",
    NumberingStyle.DecimalArabic, 1));

    // Done:
    doc.Save("NewPageLabel.pdf");
}

Working with ContentStreams

ContentStream object consists a sequence of instructions describing the graphical elements to be rendered on a page. ContentStream is a useful feature, when you are working with multiple graphical elements in a single PDF document. All the content stream added in a PDF document is stored in PageContentStreamCollection. You can access this class to add or remove items to the content stream.

To use content stream on a page:

Create an object of PageContentStream class.
Add graphic elements to the content stream using the DrawString method of GcPdfGraphics class.

Save the document.

public void CreatePDF(Stream stream)
{
    GcPdfDocument doc = new GcPdfDocument();
    var page = doc.NewPage();
    var g = page.Graphics;
    const float In = 72;
    var tf = new TextFormat()
    {
        Font = StandardFonts.Times,
        FontSize = 12
    };

    // Creating PageContentStream object
    PageContentStream contentStream = new PageContentStream(doc);
    // Adding Graphics to the ContentStream
    contentStream.Doc.Pages[0].Graphics.DrawString(
     "1. Test string. This is a sample string",
     tf, new PointF(In, In));
    // Saving the document
    doc.Save(stream);
}

For more information about implementation of pages using GcPdf, see GcPdf sample browser.

Clone a Page

GcPdf provides ClonePage method in PageCollection class to clone a particular page from a specified index in the PDF file and insert it into a specified index of the same PDF file. ClonePage method also supports two additional boolean type parameters: cloneAnnotations and cloneFields, which enable a user to allow or restrict the cloning of annotations and fields on the page to be cloned.

// Initialize GcPdfDocument.
GcPdfDocument doc = new GcPdfDocument();

// Load the PDF file from the stream.
var fs = new FileStream(Path.Combine("digital-signature-sample.pdf"), FileMode.Open,
             FileAccess.Read);
doc.Load(fs);

// Clone page at index 0 and insert it at index 1, copy fields but skip annotations.
doc.Pages.ClonePage(0, 1, false, true);

// Save the PDF document.
doc.Save("ClonePDFPageWithoutAnnotationsWithFields.pdf");

Note: GcPdf also provides MergeWithDocument method that can be used to copy pages between different PDF files. For more information on merging documents, see Merge Documents.