|
Adobe Portable Document Format (PDF) files are made of a number
of objects. Objects may describe a page, a resource, a sequence
of drawing operations an image or many other components as required
by the document.
Every object has a unique Object ID numbered from one upwards. The ID zero refers to the Empty
Object which is an object required internally within ABCpdf. ID
-1 refers to the document trailer. The root of the document hierarchy can be accessed using the Doc.Root property or the ObjectSoup.Catalog.
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] |
The asterisk is a delimiter. Each of 'Hex',
'NoBreak', and 'Byte' is optional. For example,
you can specify "/MyEntry:Text[Hex]".
The 'Hex' specifier indicates that the text should
be hex-encoded. The 'NoBreak' specifier indicates that there
should be no line breaks. Also available
is the 'Byte' specifier, which indicates that characters should
be interpreted as a string of bytes rather than a Unicode string.
These settings are used infrequently, and in general, you will not
need them. |
| :String |
This only works for string atoms.
If the string atom contains a value it returns that value.
If there is no value, or the atom is of the wrong type, it returns the special string.
"string_is_null\0ABCpdf" |
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")
|
