PD_Layer.PDCollection (PDFL)

	Typedef
	PDCollection A PDCollection represents a collection dictionary in a PDF file.
	PDCollectionFieldRec
	PDCollectionSchema An opaque pointer to a collection schema object.
	PDCollectionSchemaSortPairRec
	PDCollectionViewDataRec

	Enumeration
	`PDCollectionSplitType` Collection split types.
	`PDCollectionViewType` Collection view types.

	Structure
	_t_PDCollectionField A structure corresponding to a field in the collection schema.
	_t_PDCollectionSchemaSortPair The name of a field in a collection sort dictionary, and its associated value for ascending.
	_t_PDCollectionViewDataRec Collection view data record.

	Method
	PDFolder PDCollectionCreateFolder(PDCollection collection, ASConstText path) Creates a new folder.
	PDFolder PDCollectionGetFolder(PDCollection collection, ASConstText path) Gets an existing folder.
	ASBool PDCollectionGetInitialStyle(PDCollection collection, ASCab style) Gets the initial style dictionary for the collection.
	ASArraySize PDCollectionGetSortOrder(PDCollection collection, PDCollectionSchemaSortPairRec* pairs, ASArraySize arrayLen) Gets the contents of the collection sort dictionary.
	void PDCollectionGetViewData(PDCollection collection, PDCollectionViewDataRec* data) Gets the view data for the collection.
	ASBool PDCollectionIsValid(PDCollection collection) Determines if a collection is valid.
	void PDCollectionRemoveFolder(PDCollection collection, ASConstText path) Removes a folder and its descendant folders and associated file attachments.
	void PDCollectionRemoveInitialStyle(PDCollection collection) Removes the initial style dictionary from a collect, if present
	PDCollectionSchema PDCollectionSchemaAcquire(PDCollection collection) Acquires the PDCollectionSchema object for a collection.
	void PDCollectionSchemaDestroy(PDCollectionSchema schema) Destroys a PDCollectionSchema object.
	ASBool PDCollectionSchemaGetField(PDCollectionSchema schema, PDCollectionFieldRec* field) Gets a field by name or position. The caller must set field.size to sizeof(PDCollectionFieldRec). To look up a field by name, set field.fieldName to the appropriate name. To look up a field by position, set field.fieldName to ASAtomNull, and set field.index to the position. The caller owns (and must destroy) field.fieldText if it is not NULL.
	ASArraySize PDCollectionSchemaGetLength(PDCollectionSchema schema) Gets the number of fields in the schema.
	void PDCollectionSchemaRemoveField(PDCollectionSchema schema, ASAtom fieldName) Removes a field from the collection schema.
	void PDCollectionSchemaSetField(PDCollectionSchema schema, const PDCollectionFieldRec* field) Sets a field with new values. The target field is identified by the field.fieldName member. If the target field exists, it is overwritten; otherwise a new field is added. The caller must set field.size to sizeof(PDCollectionFieldRec). Specifying a new value for field.index will affect other field values as necessary to maintain the correct overall ordering. See PDCollectionSchema for information about ordering.
	void PDCollectionSetInitialStyle(PDCollection collection, ASConstCab style) Sets the initial style dictionary for the collection.
	void PDCollectionSetSortOrder(PDCollection collection, const PDCollectionSchemaSortPairRec* pairs, ASArraySize arrayLen) Set the contents of the collection sort dictionary.
	void PDCollectionSetViewData(PDCollection collection, const PDCollectionViewDataRec* data) Set the view data for the collection.

Typedefs Detail

PDCollection

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef OPAQUE_64_BITS PDCollection;

A PDCollection represents a collection dictionary in a PDF file.

Collection view types and split types are unusual due to the way the PDF Reference is written. A straight mapping of the View key and the Split key would result in the key/value of /View/H being part of the view type enumeration, but that would result in ambiguity when setting View to H and Split to N (/View/H maps to "preview" in Acrobat 8, but /Split/N is documented to map to "no split, show navigator" in Acrobat 9. Because of this, and the fact that /View/H is really interpreted as a kind of split rather than a style of navigator, Preview was moved to the split type enumeration in the API. This interacts with the underlying file as follows: when a /View/H value is read it is mapped to "Tile" and "Preview" for the navigator style and split position. When the Tile/Preview combination is written out, it is recorded back to /View/H for consistency with Acrobat 8.

File: PDExpT.h

Line: 6783

PDCollectionFieldRec

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_PDCollectionField PDCollectionFieldRec;

File: PDExpT.h

Line: 6866

PDCollectionSchema

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef struct CPDCollectionSchema* PDCollectionSchema;

An opaque pointer to a collection schema object.

A PDCollectionSchema is ordered with the following considerations. The PDCollectionSchema has characteristics of both a collection of named fields and an array. Field names are guaranteed to be unique. Indexing is guaranteed to be 0-based, in ascending order, with no gaps. When repositioning a field by changing its index, the schema will be re-indexed as necessary to conform to this convention. If a field is assigned an out-of-bound index, the index is adjusted to be in bounds rather than raising an error.

File: PDExpT.h

Line: 6848

PDCollectionSchemaSortPairRec

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_PDCollectionSchemaSortPair PDCollectionSchemaSortPairRec;

File: PDExpT.h

Line: 6789

PDCollectionViewDataRec

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_PDCollectionViewDataRec PDCollectionViewDataRec;

File: PDExpT.h

Line: 6834

Enumeration Detail

PDCollectionSplitType

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

enum PDCollectionSplitType {

  kCollectionSplitDefault = 0x2000,


 


  kCollectionSplitHorizontal,


 


  kCollectionSplitVertical,


 


  kCollectionSplitNone,


 


  kCollectionSplitPreview

}

File: PDExpT.h

Line: 6806

Elements

	kCollectionSplitDefault	Default split based on view.

	kCollectionSplitHorizontal	Split vertical.

	kCollectionSplitVertical	Split horizontal.

	kCollectionSplitNone	No split; show the navigator.

	kCollectionSplitPreview	No split; show the preview.

PDCollectionViewType

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

enum PDCollectionViewType {

  kCollectionViewTile = 0x1000,


 


  kCollectionViewDetails,


 


  kCollectionViewCustom

}

File: PDExpT.h

Line: 6795

Elements

	kCollectionViewTile	Tile navigator.

	kCollectionViewDetails	Details navigator.

	kCollectionViewCustom	Custom navigator.

Structure Detail

_t_PDCollectionField

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

struct _t_PDCollectionField {

  ASSize_t size;  


 


  ASAtom fieldName;  


 


  ASInt32 index;  


 


  ASAtom subtype;  


 


  ASText fieldText;  


 


  ASBool visible;  


 


  ASBool canEdit;  

}

A structure corresponding to a field in the collection schema.

File: PDExpT.h

Line: 6851

Elements

	size	The size of the `PDCollectionFieldRec`.

	fieldName	The ID of the field.

	index	The 0-based index of the field in the `PDCollectionSchema`.

	subtype	The subtype of the field. For example `/N` represents a number and `/S` represents a string.

	fieldText	The name to use in the user interface.

	visible	Default visibility.

_t_PDCollectionSchemaSortPair

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

struct _t_PDCollectionSchemaSortPair {

  ASAtom fieldName;  


 


  ASBool ascending;  

}

The name of a field in a collection sort dictionary, and its associated value for ascending.

File: PDExpT.h

Line: 6786

_t_PDCollectionViewDataRec

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax

struct _t_PDCollectionViewDataRec {

  ASSize_t size;  


 


  PDCollectionViewType view;  


 


  PDNavigator navigator;  


 


  PDCollectionSplitType split;  


 


  ASInt32 splitPos;  

}

Collection view data record.

File: PDExpT.h

Line: 6821

Elements

	size	The size of the `PDCollectionViewDataRec`.

	view	The view type of the collection.

	navigator	The navigator to use with the collection. This is ignored if `view != custom`.

	split	The split type of the collection.

	splitPos	A percentage from `0-100`. It is ignored if the position is not a split view. If the position is a split view, `-1` indicates an application-defined position.

Method Detail

PDCollectionCreateFolder

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDFolder PDCollectionCreateFolder(PDCollection collection, ASConstText path)

Creates a new folder.

Parameters

	`collection` —	The collection that will be associated with the new folder.

	`path` —	The path and name of the folder. The path syntax for folders takes the form `[parent/]folder`, where the mandatory `parent/` section may be repeated as necessary to provide a complete path to the new folder. The path is always interpreted as being relative to the root level of the folder hierarchy. Paths that specify simply a new folder name are located in the root folder. The character set for folder names is subject to the limitations imposed by the PDF Reference: folders may not contain any of the characters in the set `/ \ : ? * " < > \|` and may not end with a `.` (period). Please note that a folder name cannot consist entirely of spaces. To specify the root folder itself, assign a value of `"/"`.

Returns

The new folder object.

File: PDProcs.h

Line: 12305

PDCollectionGetFolder

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDFolder PDCollectionGetFolder(PDCollection collection, ASConstText path)

Gets an existing folder.

Parameters

	`collection` —	The collection associated with the folder to be obtained.

	`path` —	The path to the folder. To specify the root folder itself, assign a value of `"/"`. The path syntax for folders takes the form `[parent/]folder`, where the mandatory `parent/` section may be repeated as necessary to provide a complete path to the new folder.

Returns

The specified folder. If the folder does not exist, the returned folder is invalid.

File: PDProcs.h

Line: 12323

PDCollectionGetInitialStyle

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool PDCollectionGetInitialStyle(PDCollection collection, ASCab style)

Gets the initial style dictionary for the collection.

Parameters

	`collection` —	The collection object.

	`style` —	Dictionary to set

Returns

true if the dictionary is present, if false the passed cabinet is unchanged

File: PDProcs.h

Line: 12337

PDCollectionGetSortOrder

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASArraySize PDCollectionGetSortOrder(PDCollection collection, PDCollectionSchemaSortPairRec* pairs, ASArraySize arrayLen)

Gets the contents of the collection sort dictionary.

Parameters

	`collection` —	The collection object.

	`pairs` —	The array of pairs. It may be `NULL`.

	`arrayLen`

Returns

If pairs is NULL, the number of items in the collection sort dictionary is returned; otherwise, the number of items stored in the pairs array is returned.

File: PDProcs.h

Line: 12215

PDCollectionGetViewData

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDCollectionGetViewData(PDCollection collection, PDCollectionViewDataRec* data)

Gets the view data for the collection.

Parameters

	`collection` —	The collection object.

	`data` —	The collection view data.

File: PDProcs.h

Line: 12228

PDCollectionIsValid

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool PDCollectionIsValid(PDCollection collection)

Determines if a collection is valid.

Parameters

collection —

The collection

Returns

true if the collection is valid, false otherwise.

File: PDProcs.h

Line: 12188

PDCollectionRemoveFolder

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDCollectionRemoveFolder(PDCollection collection, ASConstText path)

Removes a folder and its descendant folders and associated file attachments.

Parameters

	`collection` —	The collection associated with the folder that will be removed.

	`path` —	The path to the folder.

File: PDProcs.h

Line: 12313

PDCollectionRemoveInitialStyle

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDCollectionRemoveInitialStyle(PDCollection collection)

Removes the initial style dictionary from a collect, if present

Parameters

collection —

The collection object.

File: PDProcs.h

Line: 12342

PDCollectionSchemaAcquire

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





PDCollectionSchema PDCollectionSchemaAcquire(PDCollection collection)

Acquires the PDCollectionSchema object for a collection.

Parameters

collection —

The collection object.

Returns

The collection object.

File: PDProcs.h

Line: 12240

PDCollectionSchemaDestroy

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDCollectionSchemaDestroy(PDCollectionSchema schema)

Destroys a PDCollectionSchema object.

Parameters

schema —

The collection object.

File: PDProcs.h

Line: 12246

PDCollectionSchemaGetField

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASBool PDCollectionSchemaGetField(PDCollectionSchema schema, PDCollectionFieldRec* field)

Gets a field by name or position. The caller must set field.size to sizeof(PDCollectionFieldRec). To look up a field by name, set field.fieldName to the appropriate name. To look up a field by position, set field.fieldName to ASAtomNull, and set field.index to the position. The caller owns (and must destroy) field.fieldText if it is not NULL.

Parameters

	`schema` —	The collection schema object.

	`field` —	The field to be obtained.

Returns

true if the field was found, false otherwise.

File: PDProcs.h

Line: 12264

PDCollectionSchemaGetLength

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





ASArraySize PDCollectionSchemaGetLength(PDCollectionSchema schema)

Gets the number of fields in the schema.

Parameters

schema —

The collection object.

Returns

The number of fields in the schema.

File: PDProcs.h

Line: 12252

PDCollectionSchemaRemoveField

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDCollectionSchemaRemoveField(PDCollectionSchema schema, ASAtom fieldName)

Removes a field from the collection schema.

Parameters

	`schema` —	The collection schema.

	`fieldName` —	The name of the field to remove from the collection schema.

File: PDProcs.h

Line: 12283

PDCollectionSchemaSetField

()

Product availability: PDFL

Platform availability: Macintosh, Windows, UNIX

Syntax





void PDCollectionSchemaSetField(PDCollectionSchema schema, const PDCollectionFieldRec* field)

Sets a field with new values. The target field is identified by the field.fieldName member. If the target field exists, it is overwritten; otherwise a new field is added. The caller must set field.size to sizeof(PDCollectionFieldRec). Specifying a new value for field.index will affect other field values as necessary to maintain the correct overall ordering. See PDCollectionSchema for information about ordering.

Parameters

	`schema` —	The collection schema object.

	`field` —	The field to add or modify in the collection schema.

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
PDCollection	Typedefs \| Enumerations \| Structures \| Methods

	kCollectionSplitDefault = 0x2000,

	kCollectionSplitHorizontal,

	kCollectionSplitVertical,

	kCollectionSplitNone,

	kCollectionSplitPreview

	ASSize_t size;

	ASAtom fieldName;

	ASInt32 index;

	ASAtom subtype;

	ASText fieldText;

	ASBool visible;

	ASBool canEdit;

	ASSize_t size;

	PDCollectionViewType view;

	PDNavigator navigator;

	PDCollectionSplitType split;

	ASInt32 splitPos;

	kCollectionViewTile = 0x1000,

	kCollectionViewDetails,

	kCollectionViewCustom

Layer	PD_Layer
Object	PDCollection