# Tutorial: iText by Example

## Colors

Device Color spaces:
In the chapter on Graphics, we already discussed methods such as setRGBColorFill/Stroke (Red-Green-Blue), setCMYKColorFill/Stroke (Cyan-Magenta-Yellow-Black) and setGrayFill/Stroke (grayscale). With those methods, you can change to color that is used to fill or stroke paths. Those methods also change the color space automatically to DeviceRGB, DeviceCMYK or DeviceGray. These are device color spaces; they directly specify colors or shades of gray that the output device is to produce.
In PDF, a lot of other color spaces are possible. Not all of the PDF functionality is supported in iText. If you need a more specialized feature and you don't find it here, you should post a question to the mailing-list to see if it's already implemented in iText. If you need functionality such as transparancy, spotcolor, pantone, patterns or shading, just scroll down this page and you'll find lots of examples.
Go to top of the page
Separation Color Spaces:
PDF Reference Manual p234:

> Color output devices produce full color by combining primary or process colorants in varying amounts. On an additive color device such as a display, the primary colorants consist of red, green, and blue phosphors; on a subtractive device such as a printer, they typically consist of cyan, magenta, yellow, and sometimes black inks. In addition some devices can apply special colorants, often called spot colorants, to produce effects that can not be achieved with the standard process colorants alone. Examples include metallic and fluorescent colors and special textures.
> When printing a page, most devices produce a single composite page on which all process colorants (and spot colorants, if any) are combined. However, some devices, such as imagesetters, produce a separate, monochromatic rendition of the page, called a separation, for each colorant. When the separations are later combined - on a printing process, for example - and the proper inks or colorants are applied to them, the result is a full-color page.
> A separation color space provides a means for specifying the use of additional colorants or for isolating the control of individual color components of a device color space for a subtractive device. When such a space is the current color space, the current color is a single-component value, called a tint, that controls the application of the given colorant or color components only.

In iText, you can create SpotColors with the PdfSpotColor class. You need to give a name to the color, a tint and an alternative color space value. For this last parameter, the class ExtendedColor was created. It extends java.awt.Color. If you want to create a PdfSpotColor with RGB as alternative color space, use java.awt.Color. If you want CMYK, use CMYKColor which extends ExtendedColor. Use GrayColor if you want grayscale.
These PdfSpotColors can be used with the PdfContentByte.setColorFill/Stroke methods. If you want to use a PdfSpotColor for high level objects, you have to use the SpotColor class.
Example: java com.lowagie.examples.directcontent.colors.SpotColors
Using spotcolors.: see spotcolor.pdf
Go to top of the page
Patterns:
When stroking or filling a path, we always used a single color. However, it is also possible to apply paint that consists of a repeating graphical figure or a smoothly varying color gradient instead of a simple color. Such a repeating figure or smooth gradient is called a pattern.
Tiling patterns
See PDF Reference Manual version 1.6 section 4.6.2 (p261)

> A tiling pattern consists of a small graphical figure called a pattern cell. Painting with the pattern replicates the cell at fixed horizontal and vertical intervals to fill an area. The effect is as if the figure were painted on the surface of a clear glass tile, identical copies of which were then laid down in an array covering the area and trimmed to its boundaries. This process is called tiling the area.

We distinguish two kinds of tiling patterns: colored tiling patterns and uncolored tiling patterns.
A colored tiling pattern is a pattern who's color is self-contained. When the content stream begins, the current color is the one that was initially in effect in the pattern's parent content stream. In the course of painting the pattern cell, the pattern's content stream explicitly sets the color of each graphical element it paints (a pattern cell can contain elements that are painted in different colors).
An uncolored tiling pattern is a pattern that has no inherent color: the color must be specified separately whenever the pattern is used. The content stream describes a stencil through which the color is to be poured.
In iText, you create a PdfPatternPainter with one of the differen createPattern methods in PdfContentByte. When you specify a default color, the pattern is automatically a 'stencil' pattern. As an uncolored tiling pattern has no color of its own, so you have to define a default color. This color may be null if you plan to define the color each time you invoke setPatternFill.
In short, these are the methods you are going to use to create a PdfPatternPainter: createPattern(float, float) (colored pattern, just defining a width and a height, the horizontal and vertical intervals are equal to width and height), createPattern(float, float, java.awt.Color) (uncolored pattern, defining a width and a height and the default color for the uncolored pattern), createPattern(float, float, float, float) (colored pattern, defining a width, a height and the horizontal/vertical interval) and createPattern(float, float, float, float, java.awt.Color) (uncolored pattern).
Once you have a PdfPatternPainter object, you can use it in the different setPatternFill/setPatternStroke methods. As was the case with spot colors, you can also use a class extending ExtendedColor to use a pattern as color for high level objects: PatternColor.
Example: java com.lowagie.examples.directcontent.colors.Pattern
A stencil example (you define a shape and a default color).: see pattern.pdf
Example: java com.lowagie.examples.directcontent.colors.Patterns
Colored patterns.: see patterns.pdf
External resources for this example: pngnow.png
Shading patterns
See PDF Reference Manual version 1.6 section 4.6.3 (p272)

> Shading patterns provide a smooth transition between colors and across an area to be painted, independent of the resolution of any particular output device and without specifying the number of steps in the color transition.

There are different types of shading. Check the API of PdfShading if you want to know how to construct a Shading object that can be used to paint a path with method paintShading(com.lowagie.text.pdf.PdfShading) (this paints the path, so you don't have to call fill() or stroke()).
Example: java com.lowagie.examples.directcontent.colors.Shading
Shading.: see shading.pdf
You can also create a PdfShadingPattern. This can be used to paint a path (paintShading(com.lowagie.text.pdf.PdfShadingPattern)), but also to set a fill or stroke color: setShadingFill(com.lowagie.text.pdf.PdfShadingPattern)/setShadingStroke(com.lowagie.text.pdf.PdfShadingPattern).
Example: java com.lowagie.examples.directcontent.colors.ShadingPattern
Shading pattern.: see shading_pattern.pdf
Again there's a class extending ExtendedColor to use a shading pattern as color for high level objects: ShadingColor.
Go to top of the page
Transparency:
There's a complete chapter on Transparency in the PDF Reference manual (Chapter 7, p483). If you take a look at the iText approach of adding content, you see you can add content to a top layer to cover content in a lower layer or vice-versa. Since PDF 1.4 however, overlapping content doesn't necessarily mean covering the content that is below (covering in the sense of making it disappear). With version 1.4 of the PDF specs, the Transparent Imaging Model was introduced, which means you can now have all of the 'layers' contributing to what is actually shown on a page.
The following image was copied from the PDF Reference Manual (p1053):
As you can see, there are 4 squares with a half in gray and a half in white. This is called the backdrop (the stack of all objects that have been specified previously). After adding these squares, some colored circles were added. In the first square, they were added without using any transparency. The blue circle covers the yellow one, which covers the red one.
In the second square, we changed the fill opacity to 0.5. Now you see the circles are blending. You also see the backdrop shining through.
In the third square, the circles are in the same transparency group. Within their group, the objects are painted with the default opacity (1 = no opacity). The group is painted with opacity 0.5. So as you see, the blue circle covers, the yellow one, which covers the red one; but when they are adding above the square, the gray half is blended with the group of circles.
In the fourth square, the circles in the group have an opacity of 0.5, so the colors composite with each other. The group is added on top of the backdrop with an opacity of 1, but in a different blend mode.
Example: java com.lowagie.examples.directcontent.colors.Transparency
Reproducing PLATE 16 on p1053 in the PDF Reference Manual: see transparency.pdf
Chapter 7 in the PDF Reference Manual gives you all the different blend modes (in iText, you can set them by using the PdfGState.setBlendMode; see also the chapter on the Graphics State, where you will find a list of all the available blendmodes). Transparancy groups settings are set with PdfTransparencyGroup.setIsolated (determining the initial backdrop against which its stack is composited) and PdfTransparencyGroup.setKnockout (determining whether the objects within the stack are composited with one another or only with the group's backdrop.).
Example: java com.lowagie.examples.directcontent.colors.Groups
Making images transparent.: see groups.pdf
Another nice example of applying the Transparent Imaging Model, is the use of an Image as soft mask.
Example: java com.lowagie.examples.directcontent.colors.SoftMask
Making images transparent.: see softmask.pdf
External resources for this example: otsoe.jpg
Go to top of the page
Amazon books:
amazon.co.uk-link