LayerPD_Layer
ObjectPDPageLabel

A PDPageLabel represents a page label. These labels allow 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).

A PDPageLabel specifies:



Typedef Summary
 Typedef
 PDPageLabel
A label 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). A PDPageLabel specifies the numbering style to use (for example, upper-case or lower-case Roman, decimal, and so on), the starting number for the first page, and an arbitrary prefix to be preappended to each number (for example, "A-" is used to generate "A-1", "A-2", "A-3", and so on).
Method Summary
 Method
 
Compares two page labels to see if they are equivalent. Two labels are equivalent if they have the same style, starting number (the numeric value of the first page associated with the label), and prefix strings which are the same byte-for-byte.
 
PDPageLabel PDPageLabelFromCosObj(CosObj cosLabel)
Creates a type cast of the CosObj to a PDPageLabel object.
 
Creates a type cast of the page label object to a Cos object.
 
const char* PDPageLabelGetPrefix(PDPageLabel pgLabel, ASInt32* prefixLen)
Returns the prefix string for the label. The prefix string is transitory and should be copied immediately.
 
Returns the prefix string for the label as an ASText object. The prefix string is transitory and should be copied immediately.
 
Gets the starting number of a given page label.
 
Returns an ASAtom for the style of the label.
 
Determines whether a page label is valid.
 
PDPageLabel PDPageLabelNew(PDDoc pdDoc, ASAtom style, const char* prefix, ASInt32 prefixLen, ASInt32 startAt)
Constructs a new label object in the document with the specified style, prefix, and starting page number.
 
PDPageLabel PDPageLabelNewASText(PDDoc pdDoc, ASAtom style, const ASText prefix, ASInt32 startAt)
Constructs a new label object in the document with the specified style, prefix, and starting page number.

Typedefs Detail
PDPageLabel 
Product availability: All
Platform availability: All

Syntax

typedef OPAQUE_64_BITS PDPageLabel;

A label 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). A PDPageLabel specifies the numbering style to use (for example, upper-case or lower-case Roman, decimal, and so on), the starting number for the first page, and an arbitrary prefix to be preappended to each number (for example, "A-" is used to generate "A-1", "A-2", "A-3", and so on).

See Also


File: PDExpT.h
Line: 5468



Method Detail
PDPageLabelEqual()
Product availability: All
Platform availability: All

Syntax

ASBool PDPageLabelEqual(PDPageLabel pdlOne, PDPageLabel pdlTwo)

Compares two page labels to see if they are equivalent. Two labels are equivalent if they have the same style, starting number (the numeric value of the first page associated with the label), and prefix strings which are the same byte-for-byte.

Parameters

pdlOne — 

A page label.

 
pdlTwo — 

Another page label.

Returns

true if the two labels are valid and equivalent, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6980
PDPageLabelFromCosObj() 
Product availability: All
Platform availability: All

Syntax

PDPageLabel PDPageLabelFromCosObj(CosObj cosLabel)

Creates a type cast of the CosObj to a PDPageLabel object.

Parameters

cosLabel — 

IN/OUT The Cos object level representation of a page label.

Returns

The page label representation of cosLabel.

See Also

Exceptions

pdErrBadBaseObj is raised if cosLabel is not a valid page label.

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 7007
PDPageLabelGetCosObj() 
Product availability: All
Platform availability: All

Syntax

CosObj PDPageLabelGetCosObj(PDPageLabel pdl)

Creates a type cast of the page label object to a Cos object.

Parameters

pdl — 

IN/OUT A PDPageLabel representation of a page label.

Returns

A CosObj representation of pdl if the page label is valid, NULL CosObj otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6993
PDPageLabelGetPrefix() 
Product availability: All
Platform availability: All

Syntax

const char* PDPageLabelGetPrefix(PDPageLabel pgLabel, ASInt32* prefixLen)

Returns the prefix string for the label. The prefix string is transitory and should be copied immediately.

Parameters

pgLabel — 

The label for the page whose prefix is desired.

 
prefixLen — 

(Filled by the method) The length, in bytes, of the prefix string. It is zero if the page label is not valid.

Returns

The prefix string for the label, or NULL if none is specified.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 7037
PDPageLabelGetPrefixASText() 
Product availability: All
Platform availability: All

Syntax

void PDPageLabelGetPrefixASText(PDPageLabel pgLabel, ASText prefix)

Returns the prefix string for the label as an ASText object. The prefix string is transitory and should be copied immediately.

Parameters

pgLabel — 

The label for the page whose prefix is desired.

 
prefix — 

(Filled by the method) The text object containing the prefix string. The client must pass a valid ASText object title. The routine does not allocate it.

See Also

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h
Line: 11666
PDPageLabelGetStart() 
Product availability: All
Platform availability: All

Syntax

ASInt32 PDPageLabelGetStart(PDPageLabel pgLabel)

Gets the starting number of a given page label.

Parameters

pgLabel — 

The page label for the page whose starting number is desired.

Returns

The starting number of the page label; that is, the numeric value of the first page associated with the label. It returns 1 if the page label is not valid or unknown.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 7050
PDPageLabelGetStyle() 
Product availability: All
Platform availability: All

Syntax

ASAtom PDPageLabelGetStyle(PDPageLabel pgLabel)

Returns an ASAtom for the style of the label.

It raises an exception if storage is exhausted or file access fails.

Parameters

pgLabel — 

IN/OUT The page label whose style is desired.

Returns

An ASAtom for the label style. If no style is specified, it returns ASAtomFromString(" None").

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 7022
PDPageLabelIsValid() 
Product availability: All
Platform availability: All

Syntax

ASBool PDPageLabelIsValid(PDPageLabel pgLabel)

Determines whether a page label is valid.

A page label is valid if its values correspond to the specification for page label dictionaries in Table 8.6 in the PDF Reference.

It raises an exception if storage is exhausted or file access fails.

Parameters

pgLabel — 

The page label whose validity is determined.

Returns

true if the label is valid, false otherwise.

See Also

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 6965
PDPageLabelNew() 
Product availability: Acrobat, PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDPageLabel PDPageLabelNew(PDDoc pdDoc, ASAtom style, const char* prefix, ASInt32 prefixLen, ASInt32 startAt)

Constructs a new label object in the document with the specified style, prefix, and starting page number.

Parameters

pdDoc — 

The document that contains the new page label.

 
style — 

The numbering system to use for the numeric portion of each label in this range of pages. The possible values are D for decimal numbers, R for upper-case Roman numbers, r for lower-case Roman numbers, A for upper-case alphabetic numbers, or a for lower-case alphabetic numbers. If it is NULL, the labels for this range will not have a numeric portion.

 
prefix — 

A string to prefix to the numeric portion of the page label. It may be a NULL string.

 
prefixLen — 

The length in bytes of the prefix string.

 
startAt — 

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

Returns

The newly created page label.

See Also

Exceptions

pdErrBadBaseObj is raised if the base pages object is missing or invalid.

Since

PI_PDMODEL_VERSION >= 0x00040000

File: PDProcs.h
Line: 7111
PDPageLabelNewASText() 
Product availability: All
Platform availability: All

Syntax

PDPageLabel PDPageLabelNewASText(PDDoc pdDoc, ASAtom style, const ASText prefix, ASInt32 startAt)

Constructs a new label object in the document with the specified style, prefix, and starting page number.

Parameters

pdDoc — 

The document that contains the new page label.

 
style — 

The numbering system to use for the numeric portion of each label in this range of pages. The possible values are:

Value

Description

D

Decimal numbers.

R

Upper-case Roman numbers.

r

Lower-case Roman numbers.

A

Upper-case alphabetic numbers.

a

Lower-case alphabetic numbers.

If it is NULL, the labels for this range will not have a numeric portion.

 
prefix — 

The text object containing the string to prefix to the numeric portion of the page label.

 
startAt — 

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

Returns

The newly created page label.

See Also

Exceptions

pdErrBadBaseObj is raised if the base pages object is missing or invalid.

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h
Line: 11651