# Tutorial: iText by Example

## Graphics State

PDF Syntax:
PDF Syntax looks like this:

    0.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
    f

The 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).
All these methods are described in this chapter.
Go to top of the page
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().
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.

    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
Go to top of the page
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).
Device-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

Go to top of the page
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.

m | moveTo(float, float)
l | lineTo(float, float)
c | curveTo(float, float, float, float, float float)
v | curveTo(float, float, float, float)
y | curveFromTo(float, float, float, float)
h | closePath()
re | rectangle(float, float, float, float)

For more info on these methods (especially the curveTo-ones), please read the PDF Reference Manual section 4.4.1 or consult the API documentation.
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.Shapes
Draws some shapes: see shapes.pdf
Example: java com.lowagie.examples.directcontent.graphics.Circles
Draws some concentric circles: see circles.pdf
Go to top of the page
Amazon books:
amazon.co.uk-link