PDF Syntax:
PDF Syntax looks like this:
All these methods are described in this chapter.
Go to top of the page0.3 g 15.000 27.000 m 7.947 5.292 l 26.413 18.708 l 3.587 18.708 l 22.053 5.292 l f 45.000 57.000 m 37.947 35.292 l 56.413 48.708 l 33.587 48.708 l 52.053 35.292 l f 0.7 g 15.000 57.000 m 7.947 35.292 l 26.413 48.708 l 3.587 48.708 l 22.053 35.292 l f 45.000 27.000 m 37.947 5.292 l 56.413 18.708 l 33.587 18.708 l 52.053 5.292 l fThe example above draws 4 little stars in 2 different grayscales in the lower left corner of your page. You could write all this syntax by hand, there's even some methods PdfContentByte.setLiteral that allow you to do this in iText, but trust me: that's not an easy job. If you want to write a complete PDF file from scratch, you also need to know a lot about the byte position of every object. I have set compression to false in the first example, so you can read the PDF file with a plain text editor, just to convince you, you really shouldn't start writing PDFs manually.
Example: java
com.lowagie.examples.directcontent.graphics.Literal
Writing PDF Syntax directly to iText: see literal.pdf
The PDF syntax of the example can be generated using simple iText methods such as
setGrayFill(float) (the lines ending with g),
moveTo(float, float) (the lines ending with m),
lineTo(float, float) (the lines ending with l)
and fill() (the f).Writing PDF Syntax directly to iText: see literal.pdf
All these methods are described in this chapter.
Graphics State:
The graphics state is initialized at the beginning of each page.
All parameters, such as current color (one for filling and one for stroking),
current line width, current dash pattern,... have default values.
When using iText, you can change most of these defaults with methods in class
PdfContentByte.
Some of the parameters can only be changed with the
PdfGState object,
which is a special PdfDictionary
(the Graphics State dictionary).
The Graphics State is stored in a stack. If you need to change the Graphics State, you can save the current state with PdfContentByte.saveState() and return to that state later on with PdfContentByte.restoreState().
The next example shows you how to use the PdfGState object to change the state.
Go to top of the pageThe Graphics State is stored in a stack. If you need to change the Graphics State, you can save the current state with PdfContentByte.saveState() and return to that state later on with PdfContentByte.restoreState().
Example: java
com.lowagie.examples.directcontent.graphics.State
Changing the Graphics State with saveState and restoreState: see state.pdf
In the example, we first draw a circle with a radius of 250pts and
we see how the default fill-color is black.
Changing the Graphics State with saveState and restoreState: see state.pdf
cb.circle(260.0f, 500.0f, 250.0f); cb.fill();We save this state and change the fill-color to red.
cb.saveState(); cb.setColorFill(Color.red); cb.circle(260.0f, 500.0f, 200.0f); cb.fill();The circle with a radius of 200pts is drawn in red. We save this second state and change the fill-color to blue.
cb.saveState(); cb.setColorFill(Color.blue); cb.circle(260.0f, 500.0f, 150.0f); cb.fill();The circle with radius 150pts is drawn in red. We restore the state to the second state (with fill-color red).
cb.restoreState(); cb.circle(260.0f, 500.0f, 100.0f); cb.fill();As you can see, the circle with radius 100pts is drawn in red. Than we restore the original state and the circle with radius 50pts is drawn in black.
cb.restoreState(); cb.circle(260.0f, 500.0f, 50.0f); cb.fill();Remark that the saveState and restoreState must be balanced. An exception will be thrown if you try to restore a graphics state before you have called saveState.
The next example shows you how to use the PdfGState object to change the state.
Example: java
com.lowagie.examples.directcontent.graphics.GState
Changing the Graphics State with setGState: see gstate.pdf
Changing the Graphics State with setGState: see gstate.pdf
Methods to change the parameters:
Tables 4.2 and 4.3 in the PDF Reference Manual (section 4.3) give you all the available graphic
state parameters. In the following tables, I sum up all these parameters and I'll
add the methods that can be used in iText to change their values (if such
a method is available).
Go to top of the pageDevice-independent graphics state parameters
CTM | When you are adding an Image or a PdfTemplate, you will in some cases also add the (a, b, c, d, e, f) values for the transformation matrix. The meaning of these values will be explained elsewhere in this tutorial. |
clipping path | Methods clip() and eoClip() can be used to clip output. |
color space | setDefaultColorspace(com.lowagie.text.pdf.PdfName, com.lowagie.text.pdf.PdfObject) Remark that the different setColor methods change the colorspace automatically. Please go to the chapter on colors for more info and some examples. |
color |
RGB colors (device dependent!): These methods change the color space to DeviceRGB automatically: setRGBColorFill(int, int, int), setRGBColorFillF(float, float, float), resetRGBColorFill(), setRGBColorStroke(int, int, int), setRGBColorStrokeF(float, float, float) and resetRGBColorStroke() Methods that take integers as parameter, usually expect a value between 0x00 and 0xFF. Methods that take a float, expect a value between 0f and 1f. (default = black) CMYK colors (device dependent): These methods change the color space to DeviceCMYK automatically: setCMYKColorFill(int, int, int, int), setCMYKColorFillF(float, float, float, float), resetCMYKColorFill(), setCMYKColorStroke(int, int, int, int), setCMYKColorStrokeF(float, float, float, float) and resetCMYKColorStroke() Grayfill: These methods change the color space to DeviceGray automatically (= the default): setGrayFill(float) and resetGrayFill(). setGrayStroke(float) and resetGrayStroke(). float is a value between 0 (black) and 1 (white) Spotcolors (device independent): setColorFill(com.lowagie.text.pdf.PdfSpotColor, float) and setColorStroke(com.lowagie.text.pdf.PdfSpotColor, float) Extended Color: setColorFill(java.awt.Color) and setColorStroke(java.awt.Color) Please go to the chapter on colors for more info and some examples. |
text state | See the chapter on text. |
line width | setLineWidth(float) The parameter represents the thickness of the line (default = 1). |
line cap | setLineCap(int) The parameter can be PdfContentByte.LINE_CAP_BUTT (default), PdfContentByte.LINE_CAP_ROUND or PdfContentByte.LINE_CAP_PROJECTING_SQUARE. |
line join | setLineJoin(int) The parameter can be PdfContentByte.LINE_JOIN_MITER (default), PdfContentByte.LINE_JOIN_ROUND or PdfContentByte.LINE_JOIN_BEVEL. |
miter limit | setMiterLimit(float) The parameter is a limit for joining lines, when exceeded, the join is converted from a miter to a bevel. |
dash pattern | setLineDash(float),
setLineDash(float[], float),
setLineDash(float, float) or
setLineDash(float, float, float). The parameters describe a dash pattern (default = a solid line). |
rendering intent | Used internally when rendering PNG Images. |
stroke adjustment | not implemented in iText |
blend mode | setBlendMode(com.lowagie.text.pdf.PdfName) PdfGState.BM_NORMAL, PdfGState.BM_COMPATIBLE, PdfGState.BM_MULTIPLY, PdfGState.BM_SCREEN, PdfGState.BM_OVERLAY, PdfGState.BM_DARKEN, PdfGState.BM_LIGHTEN, PdfGState.BM_COLORDODGE, PdfGState.BM_COLORBURN, PdfGState.BM_HARDLIGHT, PdfGState.BM_SOFTLIGHT, PdfGState.BM_DIFFERENCE or PdfGState.BM_EXCLUSION |
soft mask | Image.makeMask() and Image.setImageMask(com.lowagie.text.Image) |
alpha constant | setFillOpacity(float) and setStrokeOpacity(float) |
alpha source | setAlphaIsShape(boolean) |
Device-dependent graphics state parameters
overprint | setOverPrintStroking(boolean) and setOverPrintNonStroking(boolean) |
overprint mode | not implemented |
black generation | not implemented |
undercolor removal | not implemented |
transfer | not implemented |
halftone | not implemented |
flatness | setFlatness(float) The parameter is a distance in device pixels. |
smootness | not implemented |
Path construction and painting:
construction
Section 4.4 of the PDF Reference Manual deals with paths (p194):
Paths define shapes, trajectories and regions of all sorts. They are used to draw lines, define the shapes of filled areas, and specify boundaries for clipping other graphics.Table 4.9 in the reference manual gives you an overview of the path construction operators. In the following table, I sum up all these operators with their corresponding method in the iText class PdfContentByte.
For ease of use, some extra methods were added in iText:
- circle(float, float, float), ellipse(float, float, float, float) and arc(float, float, float, float, float, float) allow you to draw some specific curves.
- rectangle(com.lowagie.text.Rectangle) not only draws
the rectangle as is done with rectangle(float, float, float, float),
but also fills it with colors and takes into account some other attributes of class com.lowagie.text.Rectangle.
The same goes for variableRectangle(com.lowagie.text.Rectangle)
painting
It is very important to understand that constructing a path doesn't paint the path!
When you construct a path, the PDF interpreter doesn't know what you plan to do with it.
If you want to paint it, you will have to use a path painting operator.
These operators are listed in Table 4.10 of the Reference manual.
Again I will sum them up with their corresponding iText method.
S | stroke() |
s | closePathStroke() |
f | fill() |
F | not used (as described in the reference manual). |
f* | eoFill() |
B | fillStroke() |
B* | eoFillStroke() |
b | closePathFillStroke() |
b* | closePathEoFillStroke() |
n | newPath() |
Using PdfContentByte
These are some simple examples demonstrating some of the methods mentioned above:
Example: java
com.lowagie.examples.directcontent.graphics.Circles
Draws some concentric circles: see circles.pdf
Draws some concentric circles: see circles.pdf