Class PageLabel

PDF page labels can be used to describe a page. This is used to allow for non-sequential page numbering or the addition of arbitrary labels for a page (such as the inclusion of Roman numerals at the beginning of a book). PDFNet PageLabel object can be used to specify the numbering style to use (for example, upper- or lower-case Roman, decimal, and so forth), the starting number for the first page, and an arbitrary prefix to be pre-appended to each number (for example, "A-" to generate "A-1", "A-2", "A-3", and so forth.)

PageLabel corresponds to the PDF Page Label object (Section 8.3.1, 'Page Labels' in the PDF Reference Manual.

Each page in a PDF document is identified by an integer page index that expresses the page’s relative position within the document. In addition, a document may optionally define page labels to identify each page visually on the screen or in print. Page labels and page indices need not coincide: the indices are fixed, running consecutively through the document starting from 1 for the first page, but the labels can be specified in any way that is appropriate for the particular document. For example, if the document begins with 12 pages of front matter numbered in roman numerals and the remainder of the document is numbered in Arabic, the first page would have a page index of 1 and a page label of i, the twelfth page would have index 12 and label xii, and the thirteenth page would have index 13 and label 1.

For purposes of page labeling, a document can be divided into labeling ranges, each of which is a series of consecutive pages using the same numbering system. Pages within a range are numbered sequentially in ascending order. A page's label consists of a numeric portion based on its position within its labeling range, optionally preceded by a label prefix denoting the range itself. For example, the pages in an appendix might be labeled with decimal numeric portions prefixed with the string "A-" and the resulting page labels would be "A-1", "A-2",

There is no default numbering style; if no 'S' (Style) entry is present, page labels consist solely of a label prefix with no numeric portion. For example, if the 'P' entry (Prefix) specifies the label prefix "Appendix", each page is simply labeled "Appendix" with no page number. If the 'P' entry is also missing or empty, the page label is an empty string.

Sample code (See PableLabelsTest sample project for examples):

Create a page labeling scheme that starts with the first page in the document (page 1) and is using uppercase roman numbering style.

 doc.SetPageLabel(1, PageLabel::Create(doc, PageLabel::e_roman_uppercase, "My Prefix ", 1)); 

Create a page labeling scheme that starts with the fourth page in the document and is using decimal arabic numbering style. Also the numeric portion of the first label should start with number 4 (otherwise the first label would be "My Prefix 1").

PageLabel L2 = PageLabel::Create(doc, PageLabel::e_decimal, "My Prefix ", 4);
doc.SetPageLabel(4, L2);

Create a page labeling scheme that starts with the seventh page in the document and is using alphabetic numbering style. The numeric portion of the first label should start with number 1.

PageLabel L3 = PageLabel::Create(doc, PageLabel::e_alphabetic_uppercase, "My Prefix ", 1);
doc.SetPageLabel(7, L3);

Read page labels from an existing PDF document.

PageLabel label = new PageLabel();
for (int i=1; i<=doc.GetPageCount(); ++i) {
label = doc.GetPageLabel(i);
if (label.IsValid()) {
string title = label.GetLabelTitle(i);
}

Inheritance

System.Object

PageLabel

Implements

System.IDisposable

Inherited Members

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: pdftron.PDF

Assembly: PDFNet.dll

Syntax

public class PageLabel : IDisposable

Constructors

PageLabel(Obj)

Instantiates a new page label.

Declaration

public PageLabel(Obj obj)

Parameters

Type	Name	Description
Obj	obj	the l

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Methods

Create(SDFDoc, PageLabel.Style, String, Int32)

Creates a new PageLabel.

Declaration

public static PageLabel Create(SDFDoc doc, PageLabel.Style style, string prefix, int start_at)

Parameters

Type	Name	Description
SDFDoc	doc	A document to which the page label is added.
PageLabel.Style	style	The numbering style for the label.
System.String	prefix	page label prefix
System.Int32	start_at	start at position

Returns

Type	Description
PageLabel	newly created PageLabel object.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Dispose()

Releases all resources used by the PageLabel

Declaration

public override sealed void Dispose()

Dispose(Boolean)

Declaration

[HandleProcessCorruptedStateExceptions]
protected virtual void Dispose(bool A_0)

Parameters

Type	Name	Description
System.Boolean	A_0

Finalize()

Allows a PageLabel to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.

Declaration

protected void Finalize()

GetFirstPageNum()

Gets the first page num.

Declaration

public int GetFirstPageNum()

Returns

Type	Description
System.Int32	the first page in the range associated with this label or -1 if the label is not associated with any page.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetLabelTitle(Int32)

Gets full tittle of the page label

Declaration

public string GetLabelTitle(int page_num)

Parameters

Type	Name	Description
System.Int32	page_num	page number

Returns

Type	Description
System.String	the full label title that is in effect for the given page. If there is no label object in effect, this method returns an empty string.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetLastPageNum()

Gets the last page num.

Declaration

public int GetLastPageNum()

Returns

Type	Description
System.Int32	the last page in the range associated with this label or -1 if the label is not associated with any page.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetPrefix()

Gets the prefix.

Declaration

public string GetPrefix()

Returns

Type	Description
System.String	the string used to prefix the numeric portion of the page label

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetSDFObj()

Gets the sDF obj.

Declaration

public Obj GetSDFObj()

Returns

Type	Description
Obj	The pointer to the underlying SDF/Cos object.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetStart()

Gets the start.

Declaration

public int GetStart()

Returns

Type	Description
System.Int32	the value to use when generating the numeric portion of the first label in this range; must be greater than or equal to 1.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetStyle()

Gets the style.

Declaration

public PageLabel.Style GetStyle()

Returns

Type	Description
PageLabel.Style	page numbering style.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsValid()

Checks if is valid.

Declaration

public bool IsValid()

Returns

Type	Description
System.Boolean	whether this is a valid (non-null) PageLabel. If the function returns false the underlying SDF/Cos object is null or is not valid and the PageLabel object should be treated as null as well.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetPrefix(String)

Sets the prefix.

Declaration

public void SetPrefix(string prefix)

Parameters

Type	Name	Description
System.String	prefix	the string used to prefix the numeric portion of the page label.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetStart(Int32)

Sets the start.

Declaration

public void SetStart(int start_at)

Parameters

Type	Name	Description
System.Int32	start_at	the value to use when generating the numeric portion of the first label in this range; must be greater than or equal to 1.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetStyle(PageLabel.Style)

Sets the numbering style for the label.

Declaration

public void SetStyle(PageLabel.Style style)

Parameters

Type	Name	Description
PageLabel.Style	style	the numbering style for the label.

Remarks

You may use label style to customize the page numbering schemes used throughout a document. There are three numbering formats:

There is no default numbering style; if no 'S' (Style) entry is present, page labels consist solely of a label prefix with no numeric portion.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

Implements

System.IDisposable