Object Paths    

 

You can use the GetInfo and SetInfo methods to directly manipulate any PDF object in your document. However, this is not advisable unless you are reasonably familiar with the Adobe PDF Specification.

Under normal situations, ABCpdf ensures that your documents are internally consistent. Using the SetInfo method with Dictionaries, Values or Paths allows great flexibility in modifying documents but also allows you to create invalid or corrupt documents.

Dictionaries

If your object is a dictionary, you can specify a particular dictionary entry for replacement or insertion (dictionary entries always begin with a slash '/' character). So if you wanted to change the type of an annotation, you might use the following code:

theDoc.SetInfo theID, "/Subtype", "(Stamp)"

Values

Alternatively, you can use the 'Value' selector to specify a replacement for the entire object. However, if you do this, you must ensure that the type of your new object is the same as the type of your old one - you cannot replace a number with a string. For example.

theDoc.SetInfo theID, "Value", "<</Font /Helvetica /Size 10>>"

Paths

Specifications can be chained together to form complete paths. Dictionary entries are specified by preceding the entry name with a slash. Array items are specified using square brackets containing the index of the item you wish to reference (starting at zero).

For example, the code below would return the first item in the MediaBox array.

theDoc.GetInfo(theID, "/MediaBox[0]")

And the code below would return the count entry of the parent of the object.

theDoc.GetInfo(theID, "/Parent/Count")

References

Sometimes, you may wish to find a reference to a particular object. Sometimes, you may wish to skip through the reference and jump straight into the object itself.

You can do this using an asterisk to de-reference an object within a path. If the object is a reference, it will be de-referenced; if it is not, then the operator will be ignored.

For example, the code below might be used to return the content stream of the first page of a document.

theDoc.GetInfo(theDoc.Root, "/Pages*/Kids*[0]*/Contents")

SetInfo

You can use SetInfo to insert values specified by paths. You can specify the type of object to be inserted by appending an identifier to the path.

Object Type Description
:Bool

A boolean value.
:Name

A name value.
:Num

A numeric value
:Text

A string value.
:Ref

An indirect reference to an object.
:Rect

A rectangle. Internally rectangles are held as arrays of numbers but this provides a convenient shortcut.
:Del

This is a special entry. It does not insert an object. Instead it ensures that the object specified by the path is deleted.
:Text[Hex*NoBreak*Byte]

The asterisk is a delimiter. Each of "Hex", "NoBreak", and "Byte" is optional. For example, you can specify "/MyEntry:Text[Hex]".

"Hex" indicates that the text will be written in hexadecimal string to PDF content. "NoBreak" indicates that the (long) string is not broken into multiple lines when written to PDF content. "Byte" indicates that the text is not encoded in Unicode and the least significant octets of code point values of the characters are written as bytes to PDF content. You will not need to specify these output formats under normal uses.

Suppose you wanted to insert an annotation into the page annotations array. The following code will find the page entry named "/Annots" (or it will create it if it doesn't exist). It will then ensure that this entry references an array, and it will insert a reference atom at the beginning (item zero) of the array.

theDoc.SetInfo theDoc.Page, "/Annots[0]:Ref", theID

Alternatively, if you want to insert your annotation at the end of the array, just leave out the array index:

theDoc.SetInfo theDoc.Page, "/Annots[]:Ref", theID

You can also locate items in an array from the end. Use -1 for the last item, -2 for the second last item, and so on.

theDoc.GetInfo(theDoc.Page, "/Annots[-1]:Ref")

Insertions can be complex. The next example gets the entry called "/Font" which contains a dictionary. This dictionary includes an element called "/Names" which contains an array. The call inserts the Name object "/Helvetica" at the start of this array.

theDoc.SetInfo theID, "/Font/Names[0]:Name", "Helvetica"

GetInfo

You can use GetInfo to query values specified by paths. The format of the return value is exactly the same as would be output to your PDF file. You can specify an alternative format by appending an identifier to the string.

Format Name Description
:ID

The Object ID associated with an object reference.

Normally, object references are returned in an extended format (e.g. 23 0 R). However, if you are only interested in the Object ID, then you use this format specifier to get only the Object ID (e.g. 23).
:Obj

The object value.

This is used to ensure that all indirect references are resolved before the value of the object is returned. This ensures you always get an object value rather than an object reference.
:Text

The text of a name or string.

Names and strings may be encoded in a number of ways before output to PDF. The text format specifier ensures that the unencoded value is returned.
:Num

The value of a number.

If the object referred to is not a number then no value is returned.
:Rect

The rect string for a rectangle object.

Rects are typically represented as an array. By specifying the rect format, you will get a string value you can place directly into the XRect object.
:Count

The number of items in an array.

The count specifier is a special directive which returns the number of items in an array rather than an item from that array.
:KeyCount

The number of items in a dictionary.

The keycount specifier is a special directive which returns the number of items in a dictionary rather than an item from that dictionary.
:Keys

The keys for a dictionary.

The keys specifier is a special directive which returns a comma delimited list of the names of the entries in the dictionary.

For example, the code below could return the rect of the page CropBox.

theDoc.GetInfo(theID, "/CropBox:Rect")