Foxit PDF SDK
foxit::pdf::PageLabels Class Reference
Inheritance diagram for foxit::pdf::PageLabels:
foxit::Base

Public Types

enum  Style {
  e_None = 0, e_DecimalNums = 1, e_UpperRomanNums = 2, e_LowerRomanNums = 3,
  e_UpperLetters = 4, e_LowerLetters = 5
}
 Enumeration for page label style. More...
 

Public Member Functions

 PageLabels (const PDFDoc &document)
 Constructor, from a PDF document object. More...
 
 PageLabels (const PageLabels &other)
 Constructor, with another page labels object. More...
 
 ~PageLabels ()
 Destructor.
 
objects::PDFNumberTree GetNumberTree ()
 Get the page labels number tree. More...
 
WString GetPageLabelPrefix (int page_index) const
 Get the label prefix string in the page label (as numbering format) of a specified page index. More...
 
int GetPageLabelStart (int page_index) const
 Get the value of the numeric portion for the first page label in the page label (as numbering format) of a specified page index. More...
 
Style GetPageLabelStyle (int page_index) const
 Get the numbering style to be used for the numeric portion in the page label (as numbering format) of a specified page index. More...
 
WString GetPageLabelTitle (int page_index) const
 Get the full page label title for a page specified by page index. More...
 
bool HasPageLabel (int page_index)
 Check if there is a page label (as numbering format) defined with specified page index. More...
 
bool IsEmpty () const
 Check whether current object is empty or not. More...
 
bool operator != (const PageLabels &other) const
 Not equal operator. More...
 
PageLabelsoperator= (const PageLabels &other)
 Assign operator. More...
 
bool operator== (const PageLabels &other) const
 Equal operator. More...
 
void RemoveAll ()
 Remove all page labels. More...
 
void RemovePageLabel (int page_index)
 Remove a page label (as numbering format) defined with a specified page index. More...
 
void SetPageLabel (int page_index, Style label_style, int first_label_number, const WString &prefix_string=WString())
 Set a page label (as numbering format) defined with a page index which is the starting page index of the range. More...
 
- Public Member Functions inherited from foxit::Base
FS_HANDLE Handle () const
 Get the handle of current object. More...
 

Detailed Description

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 (PDF 1.3) to identify each page visually on the screen or in print. Page label titles and page indices need not coincide: the indexes are fixed, running consecutively through the document starting from 0 for the first page, but the label titles 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 0 and a page label title of i, the twelfth page would have index 11 and label title xii, and the thirteenth page would have index 12 and label title 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 (as numbering format), 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-; the resulting page labels would be A-1, A-2, and so on. Please refer to Section 8.3.1 "Page Labels" in <PDF Reference 1.7> for more details.
This class can be used to get page label full title directly, get information of a page label (as numbering format), set or add a new page label, and so on.

Member Enumeration Documentation

◆ Style

Enumeration for page label style.

Values of this enumeration should be used alone.

Enumerator
e_None 

Page label style: no numbering style.

This means page labels consist solely of a label prefix with no numeric portion.

e_DecimalNums 

Page label style: decimal Arabic numerals.

e_UpperRomanNums 

Page label style: uppercase roman numerals.

e_LowerRomanNums 

Page label style: lowercase roman numerals.

e_UpperLetters 

Page label style: uppercase letters.

If this style is used, A to Z will be used for the first 26 pages, AA to ZZ will be used for the next 26, and so on.

e_LowerLetters 

Page label style: lowercase letters.

If this style is used, a to z will be used for the first 26 pages, aa to zz will be used for the next 26, and so on.

Constructor & Destructor Documentation

◆ PageLabels() [1/2]

foxit::pdf::PageLabels::PageLabels ( const PDFDoc document)
explicit

Constructor, from a PDF document object.

If there exists page labeling range information in the specified PDF document, this function is just to construct a page labels object to be associated with these information. If there is no such information in the specified PDF document, the constructed page labels object can be used to set page labeling range information to PDF document.

Parameters
[in]documentA valid PDF document object.

◆ PageLabels() [2/2]

foxit::pdf::PageLabels::PageLabels ( const PageLabels other)

Constructor, with another page labels object.

Parameters
[in]otherAnother page labels object.

Member Function Documentation

◆ GetNumberTree()

objects::PDFNumberTree foxit::pdf::PageLabels::GetNumberTree ( )

Get the page labels number tree.

Returns
The page labels number tree.

◆ GetPageLabelPrefix()

WString foxit::pdf::PageLabels::GetPageLabelPrefix ( int  page_index) const

Get the label prefix string in the page label (as numbering format) of a specified page index.

This function is only useful when input page index has a page label – that means the page index is the starting page index of a page labeling range. Function PageLabels::HasPageLabel can be used to check if the page index has a page label. If input page index does not have page label, this function will return empty string.

Parameters
[in]page_indexThe page index which is the starting page index of a page labeling range. Valid range: from 0 to (count-1). count is the page count of related PDF document, and can be retrieved by function PDFDoc::GetPageCount.
Returns
The label prefix string. Empty string means no prefix string is used or input page index does not have page label. Function PageLabels::HasPageLabel can be used to check if input page index has a page label.

◆ GetPageLabelStart()

int foxit::pdf::PageLabels::GetPageLabelStart ( int  page_index) const

Get the value of the numeric portion for the first page label in the page label (as numbering format) of a specified page index.

Subsequent pages are numbered sequentially from this value until the next page labeling range appears. This value must be greater than or equal to 1.
This function is only useful when input page index has a page label – that means the page index is the starting page index of a page labeling range. Function PageLabels::HasPageLabel can be used to check if the page index has a page label. If input page index does not have page label, this function will return -1.

Parameters
[in]page_indexThe page index which is the starting page index of a page labeling range. Valid range: from 0 to (count-1). count is the page count of related PDF document, and can be retrieved by function PDFDoc::GetPageCount.
Returns
The value of the numeric portion for the first page label in specified labeling range, which would be greater than or equal to 1. -1 means no first label number is defined or input page index does not have page label. Function PageLabels::HasPageLabel can be used to check if input page index has a page label.

◆ GetPageLabelStyle()

Style foxit::pdf::PageLabels::GetPageLabelStyle ( int  page_index) const

Get the numbering style to be used for the numeric portion in the page label (as numbering format) of a specified page index.

This function is only useful when input page index has a page label – that means the page index is the starting page index of a page labeling range. Function PageLabels::HasPageLabel can be used to check if the page index has a page label. If input page index does not have page label, this function will return -1.

Parameters
[in]page_indexThe page index which is the starting page index of a page labeling range. Valid range: from 0 to (count-1). count is the page count of related PDF document, and can be retrieved by function PDFDoc::GetPageCount.
Returns
The numbering style. Please refer to values starting from PageLabels::e_None and this would be one of these values.
-1 means input page index does not have page label.

◆ GetPageLabelTitle()

WString foxit::pdf::PageLabels::GetPageLabelTitle ( int  page_index) const

Get the full page label title for a page specified by page index.

This function can help to get the full page label title of a specified page index directly, and user does not need to take care about which page labeling range this page belongs to.
Only when related PDF document does not have any page labeling range information, this function would return empty string for each valid page index.

Parameters
[in]page_indexA page index. Valid range: from 0 to (count-1). count is the page count of related PDF document, and can be retrieved by function PDFDoc::GetPageCount.
Returns
The page label full title string.

◆ HasPageLabel()

bool foxit::pdf::PageLabels::HasPageLabel ( int  page_index)

Check if there is a page label (as numbering format) defined with specified page index.

For each page labeling range, the page label (as numbering format) is defined with its starting page index.

Parameters
[in]page_indexA page index. Valid range: from 0 to (count-1). count is the page count of related PDF document, and can be retrieved by function PDFDoc::GetPageCount.
Returns
true means there exists a page label defined with input page index, while false means there is no page label defined with input page index.

◆ IsEmpty()

bool foxit::pdf::PageLabels::IsEmpty ( ) const

Check whether current object is empty or not.

When the current object is empty, that means current object is useless.

Returns
true means current object is empty, while false means not.

◆ operator !=()

bool foxit::pdf::PageLabels::operator != ( const PageLabels other) const

Not equal operator.

Parameters
[in]otherAnother page labels object. This function will check if current object is not equal to this one.
Returns
true means not equal, while false means equal.

◆ operator=()

PageLabels& foxit::pdf::PageLabels::operator= ( const PageLabels other)

Assign operator.

Parameters
[in]otherAnother page labels object, whose value would be assigned to current object.
Returns
Reference to current object itself.

◆ operator==()

bool foxit::pdf::PageLabels::operator== ( const PageLabels other) const

Equal operator.

Parameters
[in]otherAnother page labels object. This function will check if current object is equal to this one.
Returns
true means equal, while false means not equal.

◆ RemoveAll()

void foxit::pdf::PageLabels::RemoveAll ( )

Remove all page labels.

Returns
None.

◆ RemovePageLabel()

void foxit::pdf::PageLabels::RemovePageLabel ( int  page_index)

Remove a page label (as numbering format) defined with a specified page index.

After the specified page label is removed, the related labeling range will be merged to the previous page labeling range sequence.
As required in Section 8.3.1 "Page Labels" in <PDF reference 1.7>, a page label defined with page index 0 is required. So user is recommended not to remove the page label of page index 0 singly.

Parameters
[in]page_indexThe page index which is the starting page index of a page labeling range. Valid range: from 0 to (count-1). count is the page count of related PDF document, and can be retrieved by function PDFDoc::GetPageCount. Not recommend to remove the page label defined with page index 0 singly as required in Section 8.3.1 "Page Labels" in <PDF reference 1.7>,
Returns
None.

◆ SetPageLabel()

void foxit::pdf::PageLabels::SetPageLabel ( int  page_index,
Style  label_style,
int  first_label_number,
const WString prefix_string = WString() 
)

Set a page label (as numbering format) defined with a page index which is the starting page index of the range.

  • If no any page labeling range in the related PDF document, this function will set input page index as the starting page of a new page labeling range and use input values as page label (as numbering format) for this new range. Pages following the specified page will be in the same labeling range, until the next page labeling range appears. Specially, in this case, if input page index is not 0, this function will also add a new page label for index 0, with no label style, no prefix, first label number = 1, by default – this is required in Section 8.3.1 "Page Labels" in <PDF reference 1.7>.
  • If these is no page label for input page index, this function will set input page index as the starting page of a new page labeling range and use input values as page label (as numbering format) for this new range. Pages following the specified page will be in the same labeling range, until the next page labeling range appears.
  • If there exists a page label for input page index, this function will replace the old page label (as numbering format) with input values.
Parameters
[in]page_indexThe page index which is the starting page index of a page labeling range. Valid range: from 0 to (count-1). count is the page count of related PDF document, and can be retrieved by function PDFDoc::GetPageCount.
[in]label_styleThe numbering style to be used for the numeric portion in the page labeling range. Please refer to values starting from PageLabels::e_None and this should be one of these values.
[in]first_label_numberThe value of the numeric portion for the first page label in the page labeling range. It should be greater than or equal to 1. If the input value is invalid, Foxit PDF SDK will use 1 by default.
[in]prefix_stringThe label prefix string for page labels in the labeling range. This can be an empty string which means not use prefix string. Default value : an empty string.
Returns
None.