LayerPDFEdit_Layer
ObjectPDEContainer

A group of PDEElements on a page in a PDF file. In the PDF file, containers are delimited by Marked Content BMC/EMC or BDC/EMC pairs. Every PDEContainer has a Marked Content tag associated with it. In addition to grouping a set of elements, a BDC/EMC pair specifies a property list to be associated with the grouping. Thus a PDEContainer corresponding to a BDC/EMC pair also has a property list dictionary associated with it.

PDEBeginContainer and PDEEndContainer can be used to build a stream, and must be paired together.

A PDEContainer contains a group of PDEElement objects on a page. In the PDF file, containers are delimited by the Marked Content operator pairs BMC/EMC or BDC/EMC. Every PDEContainer has a Marked Content tag associated with it. In addition to grouping a set of elements, a BDC/EMC pair specifies a property list to be associated with the grouping. Thus a PDEContainer corresponding to a BDC/EMC operator pair also has a property list dictionary associated with it.

For example, the following PDF marking operators would correspond to a PDEContainer that contains several paths and has the tag PathABC:

\PathABC BMC

1 g

84.96 745.2 449.28 -9.596 ref

1 g

427.957 153.071 m

435.4 153.071 441.436 159.107 441.436 166.549

c

441.436 173.993 435.4 180.028 427.957 180.028

c

420.514 180.028 414.479 173.993 414.479

166.549 c

414.479 159.107 420.514 153.071 427.957

153.071 c

b

EMC

A PDEContainer is itself a PDEElement, so a PDEContainer can contain other PDEContainer objects, which would reflect nested marked content operator pairs.

Marked content is useful for adding structure information to a PDF file. For instance, a text processing program may have font and style information associated with a paragraph. You may want to retain this information in the PDF file, and marked content provides a means to do so.

See Section 10.5, Marked Content, in the PDF Reference, for information on marked content and property lists.

A PDEPlace object allows marking a single point in a PDF file with information rather than marking a group of objects.



Typedef Summary
 Typedef
 PDEBeginContainer
The PDFEdit representation of the opening bracket of a marked-content sequence. Elements of this type must be paired with elements of type PDEEndContainer.
 PDEContainer
A group of PDEElement objects on a page in a PDF file. In the PDF file, containers are delimited by Marked Content BMC/EMC or BDC/EMC pairs. Every PDEContainer has a Marked Content tag associated with it. In addition to grouping a set of elements, a BDC/EMC pair specifies a property list to be associated with the grouping. Thus, a PDEContainer corresponding to a BDC/EMC pair also has a property list dictionary associated with it.
 PDEEndContainer
The PDFEdit representation of the closing bracket of a marked-content sequence. Elements of this type must be paired with elements of type PDEBeginContainer.
Callback Summary
 Callback
 PDEContainerXAPMetadataDidChangeProc
Receives the notification that the XMP metadata describing a marked content sequence has changed.
Method Summary
 Method
 
PDEBeginContainer PDEBeginContainerCreate(INASAtom mcTag, INCosObj* cosObjP, INASBool isInline)
Creates a new PDEBeginContainer object. Call PDERelease to dispose of the returned PDEBeginContainer object when finished with it.
 
ASBool PDEBeginContainerGetDict(INPDEBeginContainer pdeBeginContainer, OUTCosObj* dictP, OUTASBool* isInlineP)
Gets the property list dictionary associated with a PDEBeginContainer object. The property list is stored in a Cos dictionary.
 
ASAtom PDEBeginContainerGetMCTag(INPDEBeginContainer pdeBeginContainer)
Gets the marked content tag associated with a PDEBeginContainer object.
 
void PDEBeginContainerSetDict(INPDEBeginContainer pdeBeginContainer, INCosObj* pdeBeginContainerDictP, INASBool isInline)
Sets the property list for a PDEBeginContainer. The property list is passed as a Cos dictionary that can be emitted inline or referenced from the \Properties key in the \Resources dictionary of the containing stream.
 
void PDEBeginContainerSetMCTag(INPDEBeginContainer pdeBeginContainer, INASAtom mcTag)
Sets the marked content tag for a PDEBeginContainer.
 
PDEContainer PDEContainerCreate(INASAtom mcTag, INCosObj* cosObjP, INASBool isInline)
Creates a container object.
 
PDEContent PDEContainerGetContent(INPDEContainer pdeContainer)
Gets the PDEContent for a PDEContainer.
 
ASBool PDEContainerGetDict(INPDEContainer pdeContainer, OUTCosObj* placeDictP, OUTASBool* isInline)
Gets the Marked Content dictionary for a container.
 
ASAtom PDEContainerGetMCTag(INPDEContainer pdeContainer)
Gets the Marked Content tag for a container.
 
ASBool PDEContainerGetXAPMetadata(INPDEContainer pdeContainer, OUTASText* metadataASText)
Gets the XMP metadata associated with a PDEContainer. If there is XMP metadata, it is returned as an ASText in the output parameter metadataASText. The ASText returned becomes the property of the client, which is free to alter or destroy it.
 
void PDEContainerSetContent(INPDEContainer pdeContainer, INPDEContent pdeContent)
Sets the content for a container. The existing PDEContent is released by this method.
 
void PDEContainerSetDict(INPDEContainer pdeContainer, INCosObj* placeDictP, INASBool isInline)
Sets the Marked Content dictionary for a PDEContainer. The dictionary can be emitted inline or referenced from the \Properties key in the \Resources dictionary of the containing stream.
 
void PDEContainerSetMCTag(INPDEContainer pdeContainer, INASAtom mcTag)
Sets the Marked Content tag for a PDEContainer.
 
void PDEContainerSetXAPMetadata(INPDEContainer pdeContainer, INPDDoc pdDoc, INASText metadataASText)
Sets the XMP metadata associated with a PDEContainer. Replaces the XMP metadata associated with pdeContainer with the XMP metadata stored in metadataASText. The contents of metadataASText must be well-formed XML and Resource Description Format (RDF), as defined by the W3C (see http://www.w3.org/RDF), that also forms valid XMP. PDEContainerSetXAPMetadtata() will not destroy metadataASText or alter its text.
 
PDEEndContainer PDEEndContainerCreate()
Creates a new PDEEndContainer object. Call PDERelease to dispose of the returned PDEEndContainer object when finished with it.

Typedefs Detail
PDEBeginContainer 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef struct _t_PDEBeginContainer* PDEBeginContainer;

The PDFEdit representation of the opening bracket of a marked-content sequence. Elements of this type must be paired with elements of type PDEEndContainer.

See Also


File: PEExpT.h
Line: 270
PDEContainer 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef struct _t_PDEContainer* PDEContainer;

A group of PDEElement objects on a page in a PDF file. In the PDF file, containers are delimited by Marked Content BMC/EMC or BDC/EMC pairs. Every PDEContainer has a Marked Content tag associated with it. In addition to grouping a set of elements, a BDC/EMC pair specifies a property list to be associated with the grouping. Thus, a PDEContainer corresponding to a BDC/EMC pair also has a property list dictionary associated with it.

See Also

Examples

go to source arrow PDEContainer pdeContainer = PDEContainerCreate(ASAtomFromString( "Watermark" ), NULL, false);

File: PEExpT.h
Line: 245
PDEEndContainer 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

typedef struct _t_PDEEndContainer* PDEEndContainer;

The PDFEdit representation of the closing bracket of a marked-content sequence. Elements of this type must be paired with elements of type PDEBeginContainer.

See Also


File: PEExpT.h
Line: 278


Callbacks Detail
PDEContainerXAPMetadataDidChangeProc 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void (*PDEContainerXAPMetadataDidChangeProc)(PDEContainer container, ASText newMetadata, void *data)

Receives the notification that the XMP metadata describing a marked content sequence has changed.

Notifications

PDEContainerXAPMetadataDidChange

File: PDMetadataExpT.h
Line: 92

Method Detail
PDEBeginContainerCreate()
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDEBeginContainer PDEBeginContainerCreate(INASAtom mcTag, INCosObj* cosObjP, INASBool isInline)

Creates a new PDEBeginContainer object. Call PDERelease to dispose of the returned PDEBeginContainer object when finished with it.

Call PDERelease() to dispose of the returned PDEBeginContainer object when finished with it.

Parameters

mcTag — 

IN/OUT The tag name for the marked-content sequence.

 
cosObjP — 

IN/OUT (May be NULL) A CosDict object containing the property list for the sequence.

 
isInline — 

If true, it emits the container's dictionary into the content stream inline. If false, then the dictionary is emitted outside of the content stream and referenced by name. See the Property Lists section in the PDF Reference for more details.

Returns

The newly created object.

Since


File: PEWProcs.h
Line: 1831
PDEBeginContainerGetDict() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDEBeginContainerGetDict(INPDEBeginContainer pdeBeginContainer, OUTCosObj* dictP, OUTASBool* isInlineP)

Gets the property list dictionary associated with a PDEBeginContainer object. The property list is stored in a Cos dictionary.

Parameters

pdeBeginContainer — 

IN/OUT A PDEBeginContainer object.

 
dictP — 

IN/OUT (Filled by the method) The property list associated with the PDEBeginContainer.

 
isInlineP — 

IN/OUT (Filled by the method) If true, the dictionary is emitted into the page content stream inline.

Returns

true if dictP points to a Cos dictionary; false otherwise.

Exceptions

peErrWrongPDEObjectType if pdeBeginContainer is NULL or not the right type.

Since

Note

Either dictP or isInlineP may be NULL if that information is not required.

File: PERProcs.h
Line: 2080
PDEBeginContainerGetMCTag() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASAtom PDEBeginContainerGetMCTag(INPDEBeginContainer pdeBeginContainer)

Gets the marked content tag associated with a PDEBeginContainer object.

Parameters

pdeBeginContainer — 

IN/OUT A PDEBeginContainer object.

Returns

The mark content tag.

See Also

Exceptions

peErrWrongPDEObjectType if pdeBeginContainer is NULL or not the right type.

Since


File: PERProcs.h
Line: 2057
PDEBeginContainerSetDict() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDEBeginContainerSetDict(INPDEBeginContainer pdeBeginContainer, INCosObj* pdeBeginContainerDictP, INASBool isInline)

Sets the property list for a PDEBeginContainer. The property list is passed as a Cos dictionary that can be emitted inline or referenced from the \Properties key in the \Resources dictionary of the containing stream.

Parameters

pdeBeginContainer — 

IN/OUT The PDEBeginContainer object.

 
pdeBeginContainerDictP — 

IN/OUT (May be NULL) The Cos dictionary containing the property list.

 
isInline — 

If true, it emits the container's dictionary into the content stream inline. If false, then the dictionary is emitted outside of the content stream and referenced by name. See the Property Lists section in the PDF Reference for more details.

Exceptions

peErrWrongPDEObjectType is raised if pdeBeginContainer is NULL or not the right type.

Since

Note

If cosObjP is NULL, the property list is cleared.

File: PEWProcs.h
Line: 1869
PDEBeginContainerSetMCTag() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDEBeginContainerSetMCTag(INPDEBeginContainer pdeBeginContainer, INASAtom mcTag)

Sets the marked content tag for a PDEBeginContainer.

Parameters

pdeBeginContainer — 

IN/OUT The PDEBeginContainer object.

 
mcTag — 

IN/OUT The tag name.

Exceptions

peErrWrongPDEObjectType if pdeBeginContainer is NULL or is not the right type.

Since


File: PEWProcs.h
Line: 1845
PDEContainerCreate() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDEContainer PDEContainerCreate(INASAtom mcTag, INCosObj* cosObjP, INASBool isInline)

Creates a container object.

Call PDERelease() to dispose of the returned container object when finished with it.

Parameters

mcTag — 

IN/OUT The tag name for the container.

 
cosObjP — 

IN/OUT An optional Marked Content dictionary for the container.

 
isInline — 

If true, it emits the container's dictionary into the content stream inline. If false, then the dictionary is emitted outside of the content stream and referenced by name. See the Property Lists section in the PDF Reference for more details.

Returns

The newly created container object.

See Also

Exceptions

pdErrOpNotPermitted

Since

Examples

go to source arrow PDEContainer pdeContainer = PDEContainerCreate(ASAtomFromString( "Watermark" ), NULL, false);

File: PEWProcs.h
Line: 1313
PDEContainerGetContent() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDEContent PDEContainerGetContent(INPDEContainer pdeContainer)

Gets the PDEContent for a PDEContainer.

Parameters

pdeContainer — 

IN/OUT The container whose content is obtained.

Returns

The PDEContent for the pdeContainer.

See Also

Exceptions

pdErrOpNotPermitted
peErrWrongPDEObjectType

Since

Note

This method does not change the reference count of the returned PDEContent.

File: PERProcs.h
Line: 1593
PDEContainerGetDict() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDEContainerGetDict(INPDEContainer pdeContainer, OUTCosObj* placeDictP, OUTASBool* isInline)

Gets the Marked Content dictionary for a container.

Parameters

pdeContainer — 

IN/OUT A container.

 
placeDictP — 

IN/OUT (Filled by the method) The Marked Content dictionary for pdeContainer. NULL if pdeContainer has no Marked Content dictionary.

 
isInline — 

IN/OUT (Filled by the method) true if the dictionary is inline, false otherwise. It is undefined if pdeContainer has no Marked Content dictionary.

Returns

true if pdeContainer has a Marked Content dictionary, false otherwise.

See Also

Exceptions

peErrWrongPDEObjectType
cosErrInvalidObj

Since


File: PERProcs.h
Line: 1576
PDEContainerGetMCTag() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASAtom PDEContainerGetMCTag(INPDEContainer pdeContainer)

Gets the Marked Content tag for a container.

Parameters

pdeContainer — 

IN/OUT A container.

Returns

The Marked Content tag of pdeContainer. It returns ASAtomNull if pdeContainer has no Marked Content tag.

See Also

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since


File: PERProcs.h
Line: 1554
PDEContainerGetXAPMetadata() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool PDEContainerGetXAPMetadata(INPDEContainer pdeContainer, OUTASText* metadataASText)

Gets the XMP metadata associated with a PDEContainer. If there is XMP metadata, it is returned as an ASText in the output parameter metadataASText. The ASText returned becomes the property of the client, which is free to alter or destroy it.

Parameters

pdeContainer — 

The container whose metadata is retrieved.

 
metadataASText — 

(Filled by the method) If there is XMP metadata, it is returned as an ASText object in this parameter. The ASText object returned becomes the property of the client, which is free to alter or destroy it.

Returns

true exactly when the pdeContainer has XMP metadata.

See Also

Exceptions

ErrSysPDModel
pdMetadataErrCouldntCreateMetaXAP
peErrWrongPDEObjectType
cosErrInvalidObj

Since

PI_PDMETADATA_VERSION >= 0x00050000

Note

The term XAP refers to an early internal code name for Adobe's Extensible Metadata Platform (XMP). For more information on this protocol, see the Adobe XMP specification.

File: PDMetadataProcs.h
Line: 310
PDEContainerSetContent() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDEContainerSetContent(INPDEContainer pdeContainer, INPDEContent pdeContent)

Sets the content for a container. The existing PDEContent is released by this method.

Parameters

pdeContainer — 

IN/OUT A container.

 
pdeContent — 

IN/OUT The content of pdeContainer.

See Also

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since

Note

This method decrements the reference count of the previous content of the container and increments the reference count of the new PDEContent.

Examples

go to source arrow PDEContainerSetContent( pdeContainer, textContent );

File: PEWProcs.h
Line: 1370
PDEContainerSetDict() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDEContainerSetDict(INPDEContainer pdeContainer, INCosObj* placeDictP, INASBool isInline)

Sets the Marked Content dictionary for a PDEContainer. The dictionary can be emitted inline or referenced from the \Properties key in the \Resources dictionary of the containing stream.

Parameters

pdeContainer — 

The container whose dictionary is changed.

 
placeDictP — 

The Marked Content dictionary being set into pdeContainer.

 
isInline — 

If true, it emits the container's dictionary into the content stream inline. If false, then the dictionary is emitted outside of the content stream and referenced by name. See the Property Lists section in the PDF Reference for more details.

See Also

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since


File: PEWProcs.h
Line: 1351
PDEContainerSetMCTag() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDEContainerSetMCTag(INPDEContainer pdeContainer, INASAtom mcTag)

Sets the Marked Content tag for a PDEContainer.

Parameters

pdeContainer — 

IN/OUT The container to tag.

 
mcTag — 

IN/OUT The Marked Content tag.

See Also

Exceptions

peErrWrongPDEObjectType
genErrBadParm

Since


File: PEWProcs.h
Line: 1328
PDEContainerSetXAPMetadata() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

void PDEContainerSetXAPMetadata(INPDEContainer pdeContainer, INPDDoc pdDoc, INASText metadataASText)

Sets the XMP metadata associated with a PDEContainer. Replaces the XMP metadata associated with pdeContainer with the XMP metadata stored in metadataASText. The contents of metadataASText must be well-formed XML and Resource Description Format (RDF), as defined by the W3C (see ), that also forms valid XMP. PDEContainerSetXAPMetadtata() will not destroy metadataASText or alter its text.

Parameters

pdeContainer — 

The container whose metadata is set.

 
pdDoc — 

The document containing pdeContainer.

 
metadataASText — 

Well-formed XML and RDF that also forms valid XMP.

See Also

Exceptions

ErrSysPDModel
peErrWrongPDEObjectType
cosErrInvalidObj

Notifications

PDEContainerXAPMetadataDidChange

Since

PI_PDMETADATA_VERSION >= 0x00050000

Note

The term XAP refers to an early internal code name for Adobe's Extensible Metadata Platform (XMP). For more information on this protocol, see the Adobe XMP specification.

File: PDMetadataProcs.h
Line: 339
PDEEndContainerCreate() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

PDEEndContainer PDEEndContainerCreate()

Creates a new PDEEndContainer object. Call PDERelease to dispose of the returned PDEEndContainer object when finished with it.

Call PDERelease() to dispose of the returned PDEEndContainer object when finished with it.

Returns

The newly created object.

Since


File: PEWProcs.h
Line: 2210