Summary: Constants | Ctors | Methods | Inherited Methods | [Expand All]
public class

# PageLabel

extends Object
implements AutoCloseable

java.lang.Object
↳ | com.pdftron.pdf.PageLabel

## Class Overview

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",

Note: 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);` } }

## Summary

Constants
int | e_alphabetic_lowercase | The Constant e_alphabetic_lowercase.
int | e_alphabetic_uppercase | The Constant e_alphabetic_uppercase.
int | e_decimal | The Constant e_decimal.
int | e_none | The Constant e_none.
int | e_roman_lowercase | The Constant e_roman_lowercase.
int | e_roman_uppercase | The Constant e_roman_uppercase.

Public Constructors
| PageLabel() Create a default PageLabel.
| PageLabel(Obj l) Create a PageLabel and initialize it using given Cos/SDF object.
| PageLabel(Obj l, int first_page) Instantiates a new page label and initialize it using given Cos/SDF object.
| PageLabel(Obj l, int first_page, int last_page) Instantiates a new page label and initialize it using given Cos/SDF object.

Public Methods
void | close() Frees the native memory of the object.
static PageLabel | create(Doc doc, int style, String prefix) Creates a new PageLabel in given document and in specified style
static PageLabel | create(Doc doc, int style) Creates a new PageLabel in given document and in specified style
static PageLabel | create(Doc doc, int style, String prefix, int start_at) Creates a new PageLabel in given document and in specified style
void | destroy() Frees the native memory of the object.
boolean | equals(Object d) Compares two PageLabel-s for equality.
int | getFirstPageNum() Get the first page number.
String | getLabelTitle(int page_num) Get the label title from given page
int | getLastPageNum() Get the last page number.
String | getPrefix() Get the string prefix of PageLabel
Obj | getSDFObj() Get the SDFObj.
int | getStart() Get the start numeric value
int | getStyle() Get the page number style.
int | hashCode()
boolean | isValid() Checks if PageLabel is valid.
void | setPrefix(String prefix) Set the String prefix to PageLabel
void | setStart(int start_at) Set the start numeric value
void | setStyle(int style) Set the numbering style for the label.

[Expand] Inherited Methods
From class java.lang.Object
boolean | equals(Object arg0)
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()
From interface java.lang.AutoCloseable
abstract void | close()

## Constants

#### public static final int e_alphabetic_lowercase

The Constant e_alphabetic_lowercase.

Constant Value: 4 (0x00000004)

#### public static final int e_alphabetic_uppercase

The Constant e_alphabetic_uppercase.

Constant Value: 3 (0x00000003)

#### public static final int e_decimal

The Constant e_decimal.

Constant Value: 0 (0x00000000)

#### public static final int e_none

The Constant e_none.

Constant Value: 5 (0x00000005)

#### public static final int e_roman_lowercase

The Constant e_roman_lowercase.

Constant Value: 2 (0x00000002)

#### public static final int e_roman_uppercase

The Constant e_roman_uppercase.

Constant Value: 1 (0x00000001)

## Public Constructors

#### public PageLabel ()

Create a default PageLabel.

Note: The constructor does not copy any data, but is instead the logical equivalent of a type cast.

##### Throws

PDFNetException |

#### public PageLabel (Obj l)

Create a PageLabel and initialize it using given Cos/SDF object.

##### Parameters

l | the l

##### Throws

PDFNetException |

#### public PageLabel (Obj l, int first_page)

Instantiates a new page label and initialize it using given Cos/SDF object.

##### Parameters

l | the given Cos/SDF object
first_page | first page

##### Throws

PDFNetException |

#### public PageLabel (Obj l, int first_page, int last_page)

Instantiates a new page label and initialize it using given Cos/SDF object.

##### Parameters

l | the given Cos/SDF object
first_page | first page
last_page | last page

##### Throws

PDFNetException |

## Public Methods

#### public void close ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

##### Throws

PDFNetException |

#### public static PageLabel create (Doc doc, int style, String prefix)

Creates a new PageLabel in given document and in specified style

##### Parameters

doc | A document to which the page label is added.
style | The numbering style for the label.
prefix | tring used to prefix the numeric portion of the page label.

##### Returns

- newly created PageLabel object.

##### Throws

PDFNetException |

#### public static PageLabel create (Doc doc, int style)

Creates a new PageLabel in given document and in specified style

##### Parameters

doc | A document to which the page label is added.
style | The numbering style for the label.

##### Returns

- newly created PageLabel object.

##### Throws

PDFNetException |

#### public static PageLabel create (Doc doc, int style, String prefix, int start_at)

Creates a new PageLabel in given document and in specified style

##### Parameters

doc | A document to which the page label is added.
style | The numbering style for the label.
prefix | string used to prefix the numeric portion of the page label.
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.

##### Returns

- newly created PageLabel object.

##### Throws

PDFNetException |

#### public void destroy ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

##### Throws

PDFNetException |

#### public boolean equals (Object d)

Compares two PageLabel-s for equality. The comparison will return true only if both labels share the same underlying SDF/Cos object. Two labels are also equivalent if they have the same style, starting number (numeric value of the first page associated with the label), and prefix strings which are the same byte-for-byte.

##### Parameters

d | the other PageLabel object

##### Returns

- true, if successful

#### public int getFirstPageNum ()

Get the first page number.

##### Returns

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

##### Throws

PDFNetException |

#### public String getLabelTitle (int page_num)

Get the label title from given page

##### Parameters

page_num | the input page number

##### Returns

- 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.

##### Throws

PDFNetException |

#### public int getLastPageNum ()

Get the last page number.

##### Returns

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

##### Throws

PDFNetException |

#### public String getPrefix ()

Get the string prefix of PageLabel

##### Returns

- the string used to prefix the numeric portion of the page label

##### Throws

PDFNetException |

#### public Obj getSDFObj ()

Get the SDFObj.

##### Returns

- The pointer to the underlying SDF/Cos object.

##### Throws

PDFNetException |

#### public int getStart ()

Get the start numeric value

##### Returns

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

##### Throws

PDFNetException |

#### public int getStyle ()

Get the page number style.

##### Returns

- page numbering style.

##### Throws

PDFNetException |

#### public int hashCode ()

#### public boolean isValid ()

Checks if PageLabel is valid.

##### Returns

- 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.

##### Throws

PDFNetException |

#### public void setPrefix (String prefix)

Set the String prefix to PageLabel

##### Parameters

prefix | the string used to prefix the numeric portion of the page label.

##### Throws

PDFNetException |

#### public void setStart (int start_at)

Set the start numeric value

##### Parameters

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.

##### Throws

PDFNetException |

#### public void setStyle (int style)

Set the numbering style for the label.

Note: 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.

##### Parameters

style | the numbering style for the label. You may use label style to customize the page numbering schemes used throughout a document. There are three numbering formats: - decimal (often used for normal page ranges) - roman (often used for front matter such as a preface) - alphabetic (often used for back matter such as appendices)

##### Throws

PDFNetException |