All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
pdftron::PDF::PageLabel Class Reference

#include <PageLabel.h>

+ Inheritance diagram for pdftron::PDF::PageLabel:

Public Types

enum  Style {
  e_decimal, e_roman_uppercase, e_roman_lowercase, e_alphabetic_uppercase,
  e_alphabetic_lowercase, e_none
}
 

Public Member Functions

 PageLabel (SDF::Obj l=0, int first_page=-1, int last_page=-1)
 
 PageLabel (const PageLabel &d)
 
PageLabeloperator= (const PageLabel &d)
 
bool operator== (const PageLabel &d)
 
bool IsValid () const
 
UString GetLabelTitle (int page_num)
 
void SetStyle (Style style)
 
Style GetStyle () const
 
UString GetPrefix () const
 
void SetPrefix (const UString &prefix)
 
int GetStart () const
 
void SetStart (int start_at)
 
int GetFirstPageNum ()
 
int GetLastPageNum ()
 
SDF::Obj GetSDFObj () const
 

Static Public Member Functions

static PageLabel Create (SDF::SDFDoc &doc, Style style, const UString &prefix="", int start_at=1)
 

Detailed Description

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.
doc.SetPageLabel(7, L3);
// Read page labels from an existing PDF document.
PageLabel label;
for (int i=1; i<=doc.GetPageCount(); ++i) {
label = doc.GetPageLabel(i);
if (label.IsValid()) {
UString title = label.GetLabelTitle(i);
}

Definition at line 87 of file PageLabel.h.

Member Enumeration Documentation

Enumerator
e_decimal 

Decimal Arabic numerals.

e_roman_uppercase 

Uppercase Roman numerals.

e_roman_lowercase 

Lowercase Roman numerals.

e_alphabetic_uppercase 

Uppercase letters (A to Z for the first 26 pages, AA to ZZ for the next 26, and so on)

e_alphabetic_lowercase 

Lowercase letters (a to z for the first 26 pages, aa to zz for the next 26, and so on)

e_none 

No numeric portion in the label.

Definition at line 92 of file PageLabel.h.

Constructor & Destructor Documentation

pdftron::PDF::PageLabel::PageLabel ( SDF::Obj  l = 0,
int  first_page = -1,
int  last_page = -1 
)

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

Note
The constructor does not copy any data, but is instead the logical equivalent of a type cast.
pdftron::PDF::PageLabel::PageLabel ( const PageLabel d)

Copy constructor

Member Function Documentation

static PageLabel pdftron::PDF::PageLabel::Create ( SDF::SDFDoc doc,
Style  style,
const UString prefix = "",
int  start_at = 1 
)
static

Creates a new PageLabel.

Parameters
docA document to which the page label is added.
styleThe numbering style for the label.
prefixThe string used to prefix the numeric portion of the page label.
start_atthe 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.
int pdftron::PDF::PageLabel::GetFirstPageNum ( )
Returns
the first page in the range associated with this label or -1 if the label is not associated with any page.
UString pdftron::PDF::PageLabel::GetLabelTitle ( int  page_num)
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.
int pdftron::PDF::PageLabel::GetLastPageNum ( )
Returns
the last page in the range associated with this label or -1 if the label is not associated with any page.
UString pdftron::PDF::PageLabel::GetPrefix ( ) const
Returns
the string used to prefix the numeric portion of the page label
SDF::Obj pdftron::PDF::PageLabel::GetSDFObj ( ) const
Returns
The pointer to the underlying SDF/Cos object.
int pdftron::PDF::PageLabel::GetStart ( ) const
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.
Style pdftron::PDF::PageLabel::GetStyle ( ) const
Returns
page numbering style.
bool pdftron::PDF::PageLabel::IsValid ( ) const
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.
PageLabel& pdftron::PDF::PageLabel::operator= ( const PageLabel d)

Assignment operator

bool pdftron::PDF::PageLabel::operator== ( const PageLabel 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.

void pdftron::PDF::PageLabel::SetPrefix ( const UString prefix)
Parameters
prefixthe string used to prefix the numeric portion of the page label.
void pdftron::PDF::PageLabel::SetStart ( int  start_at)
Parameters
start_atthe value to use when generating the numeric portion of the first label in this range; must be greater than or equal to 1.
void pdftron::PDF::PageLabel::SetStyle ( Style  style)

Sets the numbering style for the label.

Parameters
stylethe 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)
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.

The documentation for this class was generated from the following file: