PD_Layer.PDPageLabel (Acrobat)

	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
	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.
	PDPageLabel PDPageLabelFromCosObj(CosObj cosLabel) Creates a type cast of the CosObj to a PDPageLabel object.
	CosObj PDPageLabelGetCosObj(PDPageLabel pdl) 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.
	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.
	ASInt32 PDPageLabelGetStart(PDPageLabel pgLabel) Gets the starting number of a given page label.
	ASAtom PDPageLabelGetStyle(PDPageLabel pgLabel) Returns an ASAtom for the style of the label.
	ASBool PDPageLabelIsValid(PDPageLabel pgLabel) 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).

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

PDPageLabelIsValid

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

PDPageLabelGetCosObj

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

PDPageLabelFromCosObj

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

PDPageLabelGetStart
PDPageLabelGetStyle

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.

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.

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

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

PDPageLabelEqual

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.

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.

Exceptions

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

Since

PI_PDMODEL_VERSION >= 0x00080000

File: PDProcs.h

Line: 11651

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
PDPageLabel	Typedefs \| Methods

Layer	PD_Layer
Object	PDPageLabel