Custom Page Elements can be used to output PDF code to a page or can utilize other already existing Page Element objects.

PageElement API

All Page Elements must inherit from the PageElement base class and override its draw method. This method accepts a PageWriter object. When the Page Element is added to the page this method is called. PDF operators can then be added to the page using the methods of the PageWriter object. You will need to use the setXXXX (i.e. setLeading, setColor, setGraphicsMode, etc.) methods to set the state on page. You can then use the write_XX (i.e. write_l_, write_m_, write_re) methods to add the PDF graphic or text operators to the page. Most of the PDF operators have a write_XXXX method associated with them. If the operator only differs by case, the lower case operator has a trailing "_" character, this is done just to avoid confusion.

A RotatingPageElement base class is also included. You can inherit from this to automatically provide support for rotating your page element.

When working with Page Elements, you do not have to be concerned with compression, encryption or PDF object numbering. This is all handled internally by Generator for Java.

Custom PageElement Guidelines

1. Always use the setXXXX method to set graphics and text states. This allows the minimum amount of PDF code to be output to the page and allows the next Page Element that is called to properly set the state that it needs. If you are not going to use these methods you will need to use the "q" and "Q" operators to store the current state and then restore it before leaving the draw method.
2. Always use a top margin to bottom margin and left margin to right margin coordinate system for the properties of your Page Element. Remember that PDF uses a bottom edge to top edge and left edge to right edge coordinate system that is complex and confusing to most users. This complexity should be hidden from the user of your Page Element. The getPdfX, getPdfY methods are provided on the PageWriters Dimensions property to help with this translation.
3. Use the X, Y, Width, and Height properties where applicable.
4. Use the built-in Color, LineStyle, and Font objects wherever possible. This makes your Page Element function in the same fashion as the built-in Page Elements and makes it easier for users to use them.

Development Tips

When developing custom Page Elements, set the document's compression level to zero and don't use security or encryption. Create a simple application that adds one page to the PDF document and adds your custom Page Element to that page. This makes it possible for you to output the PDF document to a file and view the PDF output from your Page Element in a text editor.

PDF Resources

An excellent resource for PDF development is  "PDF Reference" published by Adobe. This can be downloaded free of charge from the Adobe site. This resource includes documentation of all of the PDF graphic and text operators.