PD Layer: PDPageLabel

PDPageLabel Typedefs

PDPageLabel

Header: PDExpT.h:5551

Description

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

Syntax

typedef OPAQUE_64_BITS PDPageLabel;

Returned From

Used By

PDPageLabel Functions

PDPageLabelEqual: - Compares two page labels to see if they are equivalent.
PDPageLabelFromCosObj: - Creates a type cast of the CosObj to a PDPageLabel object.
PDPageLabelGetCosObj: - Creates a type cast of the page label object to a Cos object.
PDPageLabelGetPrefix: - Returns the prefix string for the label.
PDPageLabelGetPrefixASText: - Returns the prefix string for the label as an ASText object.
PDPageLabelGetStart: - Gets the starting number of a given page label.
PDPageLabelGetStyle: - Returns an ASAtom for the style of the label.
PDPageLabelIsValid: - Determines whether a page label is valid.
PDPageLabelNew: - Constructs a new label object in the document with the specified style, prefix, and starting page number.
PDPageLabelNewASText: - Constructs a new label object in the document with the specified style, prefix, and starting page number.

PDPageLabelEqual

Header: PDProcs.h:7160

Description

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.

Related Methods

PDPageLabelIsValid

Syntax

ASBool PDPageLabelEqual(PDPageLabel pdlOne, PDPageLabel pdlTwo);

Parameters

`pdlOne`	A page label.
`pdlTwo`	Another page label.

Returns

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

PDPageLabelFromCosObj

Header: PDProcs.h:7187

Description

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

Related Methods

PDPageLabelGetCosObj

Syntax

PDPageLabel PDPageLabelFromCosObj(CosObj cosLabel);

Parameters

cosLabel

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

Returns

The page label representation of cosLabel.

Exceptions

pdErrBadBaseObj

is raised if cosLabel is not a valid page label.

PDPageLabelGetCosObj

Header: PDProcs.h:7173

Description

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

Related Methods

PDPageLabelFromCosObj

Syntax

CosObj PDPageLabelGetCosObj(PDPageLabel pdl);

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.

PDPageLabelGetPrefix

Header: PDProcs.h:7217

Description

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

Syntax

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

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.

PDPageLabelGetPrefixASText

Header: PDProcs.h:11845

Description

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

Syntax

void PDPageLabelGetPrefixASText(PDPageLabel pgLabel, ASText prefix);

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.

PDPageLabelGetStart

Header: PDProcs.h:7230

Description

Gets the starting number of a given page label.

Syntax

ASInt32 PDPageLabelGetStart(PDPageLabel pgLabel);

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.

PDPageLabelGetStyle

Header: PDProcs.h:7202

Description

Returns an ASAtom for the style of the label.

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

Syntax

ASAtom PDPageLabelGetStyle(PDPageLabel pgLabel);

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

PDPageLabelIsValid

Header: PDProcs.h:7145

Description

Determines whether a page label is valid.

A page label is valid if its values correspond to the specification for page label dictionaries. See the description of Page labels in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 12.4.2, page 374.

You can find this document on the web store of the International Standards Organization (ISO).

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

Related Methods

PDPageLabelEqual

Syntax

ASBool PDPageLabelIsValid(PDPageLabel pgLabel);

Parameters

pgLabel

The page label whose validity is determined.

Returns

true if the label is valid, false otherwise.

PDPageLabelNew

Header: PDProcs.h:7290

Description

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

Syntax

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

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 `None`, the labels for this range will not have a numeric portion. None is specified by providing ASAtomFromString("None") as the style parameter.
`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.

Exceptions

pdErrBadBaseObj

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

PDPageLabelNewASText

Header: PDProcs.h:11830

Description

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

Syntax

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

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 None, the labels for this range will not have a numeric portion. None is specified by providing ASAtomFromString("None") as the style parameter.

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.

Exceptions

pdErrBadBaseObj

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