Page Editing Objects and Elements

Objects described in this Section provide easy access to PDF page contents. With this group of objects, you can treat a page's contents as a list of objects rather than having to manipulate the content stream's PDF marking operators. PDE objects are meant to be used in conjunction with the General and Base Object methods for manipulating PDF documents.

The PDE objects are split in two groups: PDE elements and PDE objects. A page display list is represented as a PDE object that contains PDE elements. The page's content is usually treated as a list of PDE elements. Each PDE element is a path, text, image, form, or a marked content place or container of PDE Elements. Using the PDE Objects and functions you can add or remove objects inside a PDE Object. You can also change attributes of Elements in a PDE Object, such as a bounding box, a text font, or a clipping path.

The PDE objects are used to create the PDE elements and provide specific information for the elements. For example, PDE Image, which is an element, usually has or is created based on a PDE ColorSpace, which is an object. PDE text, which is an element, usually has or is created based on a PDE Font, which is an object.

This API is meant to be used in conjunction with basic and general objects.

The following table contains the objects and their descriptions supported by the ImageGear PDF component:

Page Editing Objects and Elements
HIG_PDE_OBJECT	Object - base interface for all the PDE objects.
HIG_PDE_CONTENT	Content - modifiable content of a PDF page, which contains elements. Content may be obtained from an existing page or from a Form XObject.
HIG_PDE_COLORSPACE	ColorSpace - a reference to a color space used on a page in a PDF file. The color space is part of the graphics state attributes of a PDE Element.
HIG_PDE_FONT	Font - A reference to a font used on a page in a PDF file. It may be equated with a font in the system.
HIG_PDE_ELEMENT	Element - base interface for the elements of a page display list (PDE content) and for clip objects. The general PDE element methods allow you to get and set general element properties.
HIG_PDE_CLIP	Clip - a list of elements containing a list of Paths and Texts that describe a clip state. Clips can be created and built up with PDE Clip methods. Any PDE Element object can have Clip associated with it. Clip objects can contain PDE Containers and PDE Groups to an arbitrary level of nesting. This allows PDE Containers to be used to mark clip objects. PDE Groups inside PDE Clips that contain at least one PDE Text and no PDE Paths have a special meaning. All PDE Text objects contained in such a PDE Group are considered to be part of the same BT/ET block. This means that the union of these PDE Texts makes up a single clipping path-as opposed to the intersection of the PDE Texts. See Section 5.3 in the PDF reference for more information about BT/ET block.
HIG_PDE_CONTAINER	Container - a group of elements on a page in a PDF file. In the PDF file, containers are delimited by Marked Content BMC/EMC or BDC/EMC pairs. Every container 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 container corresponding to a BDC/EMC pair also has a property list dictionary associated with it. See Section 10.5 in the PDF reference for more information about Marked Content operators.
HIG_PDE_FORM	Form - an element that corresponds to an instance of XObject Form on a page (or other containing stream such as another XObject Form or annotation form). The context associated with this instance includes the actual stream that represents the XObject Form and the initial conditions of the graphics state. The latter consists of the transformation matrix, initial color values, and so forth. It is possible to have two Forms that refer to the same XObject Form. The forms will exist at different places on the same page, depending on the transformation matrix. They may also have different colors or line stroking parameters. In the case of a transparency group, the opacity is specified in the gstate. Within a Form, each element has its own gstate (or is a container, place, or group object). These gstates are independent of the parent Form gstate. Form elements may have their own opacity. Content may be obtained from a Form to edit the form's display list.
HIG_PDE_GROUP	Group - an in-memory representation of objects in Content. It has no state and is not represented in any way in a content stream (that is, Content). When used in a Clip, this object is used to associate Text objects into a single clipping object.
HIG_PDE_IMAGE	Image - an element that contains an Image XObject or in-line image. You can associate data or a stream with an image.
HIG_PDE_PATH	Path - an element that contains a path. Path objects can be stroked, filled, and/or serve as a clipping path.
HIG_PDE_PLACE	Place - an element that marks a place on a page in a PDF file. In a PDF file, a place is represented by the MP or DP Marked Content operators. Marked content is useful for adding structure information to a PDF file. For instance, a drawing program may want to mark a point with information, such as the start of a path of a certain type. Marked content provides a way to retain this information in the PDF file. A DP operator functions the same as the MP operator and, in addition, allows a property list dictionary to be associated with a place.
HIG_PDE_POSTSCRIPT	PostScript - an element representing in-line or XObject pass-through PostScript object. XObject PostScripts are listed in page XObject resources.
HIG_PDE_SOFTMASK	SoftMask - an object for creating and manipulating a soft mask in a PDF file.
HIG_PDE_SHADING	Shading - an element that represents smooth shading.
HIG_PDE_TEXT	Text - an element representing text. It is a container for text as show strings or as individual characters. Each sub-element may have different graphics state properties. However, the same clip applies to all sub-elements of a Text. Also, the char path of a Text can be used to represent a clip.
HIG_PDE_TEXTITEM	TextItem - a PDE element representing a text object.
HIG_PDE_XGROUP	XGroup - a transparency (XGroup) resource.
HIG_PDE_XOBJECT	XObject - an element representing an arbitrary XObject.