LayerPD_Layer
ObjectPDCollection

PDF file collection dictionary object.



Typedef Summary
 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 Summary
 Enumeration
  PDCollectionSplitType
Collection split types.
  PDCollectionViewType
Collection view types.
Structure Summary
 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 Summary
 Method
 
Creates a new folder.
 
Gets an existing folder.
 
Gets the initial style dictionary for the collection.
 
Gets the contents of the collection sort dictionary.
 
Gets the view data for the collection.
 
Determines if a collection is valid.
 
Removes a folder and its descendant folders and associated file attachments.
 
Removes the initial style dictionary from a collect, if present
 
PDCollectionSchema PDCollectionSchemaAcquire(PDCollection collection)
Acquires the PDCollectionSchema object for a collection.
 
Destroys a PDCollectionSchema object.
 
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.
 
Gets the number of fields in the schema.
 
Removes a field from the collection schema.
 
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.
 
Sets the initial style dictionary for the collection.
 
Set the contents of the collection sort dictionary.
 
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.

See Also


File: PDExpT.h
Line: 6780
PDCollectionFieldRec 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_PDCollectionField PDCollectionFieldRec;

File: PDExpT.h
Line: 6863
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: 6845
PDCollectionSchemaSortPairRec 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_PDCollectionSchemaSortPair PDCollectionSchemaSortPairRec;

File: PDExpT.h
Line: 6786
PDCollectionViewDataRec 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef _t_PDCollectionViewDataRec PDCollectionViewDataRec;

File: PDExpT.h
Line: 6831

Enumeration Detail
PDCollectionSplitType
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax


File: PDExpT.h
Line: 6803

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: 6792

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: 6848

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: 6783

_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: 6818

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: 12304
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: 12322
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: 12336
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: 12214
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: 12227
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: 12187
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: 12312
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: 12341
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: 12239
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: 12245
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: 12263
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: 12251
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: 12282
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.

See Also


File: PDProcs.h
Line: 12276
PDCollectionSetInitialStyle() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDCollectionSetInitialStyle(PDCollection collection, ASConstCab style)

Sets the initial style dictionary for the collection.

Parameters

collection — 

The collection object.

 
style — 

Dictionary to fill


File: PDProcs.h
Line: 12329
PDCollectionSetSortOrder() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDCollectionSetSortOrder(PDCollection collection, const PDCollectionSchemaSortPairRec* pairs, ASArraySize arrayLen)

Set the contents of the collection sort dictionary.

Parameters

collection — 

The collection object.

 
pairs — 

The array of pairs. If it is NULL, the collection sort dictionary is removed.

 
arrayLen


File: PDProcs.h
Line: 12221
PDCollectionSetViewData() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDCollectionSetViewData(PDCollection collection, const PDCollectionViewDataRec* data)

Set the view data for the collection.

Parameters

collection — 

The collection object.

 
data — 

The collection view data.


File: PDProcs.h
Line: 12233