This is an old revision of the document!


Adding a new object type

There are many object types in the PDF specification and only some are defined in the library yet. This page explains in detail how to add a new object type to the library and why you should do so.

Why bother to define a type? The usual objects are dictionaries which can be processed and viewed as they are.

PDFExplorer with an untyped object

The attribute /BS of an /FreeText has an untyped dictionary.

To make it nice in the PDFExplorer!

PDFExplorer with a BorderStyle object

Adding an object type allows for a customized presentation with a printString, an icon, attribute documentation and order etc. (see below for all the details).

Attribute /W in the BorderStyle object

The attribute /W of a /BorderStyle object shows its documentation.

Usually, you inspect a PDF with the PDFExplorer and find some object which is not documented. To define an object type it is important to have an example open in the PDFExplorer so that you can see the changes. In our example this is the object in the attribute /BS in a /FreeText annotation object.

In order to find out what the object is about, the relevant piece of documentation should be found in the PDF Specification. In our case this is a border style dictionary described in chapter “12.5.4 Border Styles” on page 386.

The new class can be defined with the class definition editor:  The ClassCreationDialog for BorderStyle

Choose a class name

Choose the package

Choose the namespace

Choose the superclass

Firstly, a new class need to be defined. For this you need to choose:

  • a name
  • a package
  • a namespace (which should be Graphics.PDF)
  • a superclass which may be Dictionary, TypedDictionary if the object has an attribute /Type, or someting else (see later).

As name for this example, I use /BorderStyle. Ideally the name should be the same as used in the specification. The package is [PDF Document], because it is related to /Annot which is defined there. The superclass is TypedDictionary, because the specification defines a /Type entry in the border style dictionary.

As class comment, the first paragraph of the description in the specificatiopn is copied. Also the reference to the specification should be included as first line:

PDF border style dictionary as defined in PDF 32000_2008.pdf, section 12.5.4, pp. 386.

An annotation may optionally be surrounded by a border when displayed or printed. If present, the border shall be drawn completely inside the annotation rectangle. In PDF 1.1, the characteristics of the border shall be specified by the Border entry in the annotation dictionary (see Table 164). Beginning with PDF 1.2, the border characteristics for some types of annotations may instead be specified in a border style dictionary designated by the annotation’s BS entry. Such dictionaries may also be used to specify the width and dash pattern for the lines drawn by line, square, circle, and ink annotations. Table 166 summarizes the contents of the border style dictionary. If neither the Border nor the BS entry is present, the border shall be drawn as a solid line with a width of 1 point.

I usually edit this text to add line breaks after sentences and remove any cross references to other parts of the specification:

PDF border style dictionary as defined in PDF 32000_2008.pdf, section 12.5.4, pp. 386.

An annotation may optionally be surrounded by a border when displayed or printed.
If present, the border shall be drawn completely inside the annotation rectangle.
In PDF 1.1, the characteristics of the border shall be specified by the Border entry in the annotation dictionary.
Beginning with PDF 1.2, the border characteristics for some types of annotations may instead be specified in a border style dictionary designated by the annotation’s BS entry.
Such dictionaries may also be used to specify the width and dash pattern for the lines drawn by line, square, circle, and ink annotations.
If neither the Border nor the BS entry is present, the border shall be drawn as a solid line with a width of 1 point.

Two more bits of information should be added as methods on the class side:

documentationPlace
	^#(12 5 4)

This is a recent addition intended to be able to jump directly to the corresponding place in the specification PDF. This has not been done yet and most objects don't have this method, but for new objects, I want to have it.

version
	^2

This notes the minor part of the PDF version in which this feature first occurred, allowing for computing the minimal version for a PDF.

Since a new type is defined, the object types have to be reset with PDF resetObjecttypes so that the new type can be found.

The new type can now be used. Therefore, the type of the attribute which contains the object should be set to the new type. In the example, in the method BS of class FreeText, the type: pragma should be changed from

BS
	<type: #Dictionary>
	<version: 6>
	<attribute: 9 documentation: 'A border style dictionary specifying the line width and dash pattern that shall be used in drawing the annotation’s border.
The annotation dictionary’s AP entry, if present, takes precedence over the BS entry'>
	^self objectAt: #BS ifAbsent: [Dictionary empty]

to

BS
	<type: #BorderStyle>
	<version: 6>
	<attribute: 9 documentation: 'A border style dictionary specifying the line width and dash pattern that shall be used in drawing the annotation’s border.
The annotation dictionary’s AP entry, if present, takes precedence over the BS entry'>
	^self objectAt: #BS ifAbsent: [BorderStyle empty]

The result looks like this in the PDFExplorer (after hitting F5 for refresh): the style is recognized as BorderStyle and it shows the right version (PDF-1.2), but the required field Type is red (error) and the W field is pink (not known).

new object type /BorderStyle

add attribute method

add pragmas

copy and edit comment

docs, icon, string, attributes (docs, type, order, version, required)

  • extending.1458808358.txt.gz
  • Last modified: 2016/03/24 09:32
  • by christian