Tutorial: iText by Example

Drawing objects make it possible to add arbitrary shapes to the RTF document. Shapes in RTF are represented as a few basic settings and then an arbitrary list of properties that represent all other aspects of the shape. Only for the most core properties are constants defined. For all further properties, please refer to the RTF Specification 1.6.

The basic class for creating drawing objects is the RtfShape. It is made up out of an RtfShapePosition, that defines the position of the the drawing object on the page and a list of RtfShapePropertys, that specify all other properties that define the drawing object.

The constructor for the RtfShape takes the type of shape and an RtfShapePosition. The RtfShapePosition defines the extent of the drawing object (Important: These extents are in in Twips) and also properties such as the z-order of the drawing object and whether the shape is above or below the main text.
To this the RtfShapeProperty objects are added to define drawing object properties such as the line colour or fill colour.

// Create a new RtfShape of the type RECTANGLE.
// The position defines the extent of the shape in the page (in Twips)
RtfShape shape = new RtfShape(RtfShape.SHAPE_RECTANGLE,
        new RtfShapePosition(1000, 2000, 3000, 2000));

// Set the line colour to red
shape.setProperty(new RtfShapeProperty(RtfShapeProperty.PROPERTY_LINE_COLOR,
        Color.RED));

// Set the fill colour to cyan
shape.setProperty(new RtfShapeProperty(RtfShapeProperty.PROPERTY_FILL_COLOR,
        Color.CYAN));

// Add the shape to the document
document.add(shape);
    	  

By default the drawing object is anchored to the page, so that the values in the RtfShapePosition are applied relative to the top, left corner of the page. Other anchorings that are possible are:

• Horizontal anchoring
  • RtfShapePosition.POSITION_X_RELATIVE_PAGE: The default, anchored to the page.
  • RtfShapePosition.POSTIION_X_RELATIVE_MARGIN: The horizontal position is relative to the margin of the page.
  • RtfShapePosition.POSITION_X_RELATIVE_COLUMN: The horizontal position is relative to the current column the shape is in.
• Vertical anchoring
  • RtfShapePosition.POSITION_Y_RELATIVE_PAGE: The default, anchored to the page.
  • RtfShapePosition.POSTIION_Y_RELATIVE_MARGIN: The horizontal position is relative to the margin of the page.
  • RtfShapePosition.POSITION_Y_RELATIVE_PARAGRAPH: The horizontal position is relative to the paragraph the shape is in. If the paragraph moves, the drawing object is moved with it.

As an example the POSITION_Y_RELATIVE_PARAGRAPH anchoring can be used to create a horizontal line, separating two pieces of text.

// Construct a new RtfShapePosition that covers the whole page horizontally 
RtfShapePosition position = new RtfShapePosition(150, 0, 10400, 150);

// The horizontal position is relative to the margins of the page
position.setXRelativePos(RtfShapePosition.POSITION_X_RELATIVE_MARGIN);

// The vertical position is relative to the paragraph
position.setYRelativePos(RtfShapePosition.POSITION_Y_RELATIVE_PARAGRAPH);
            
// Create a new line drawing object
RtfShape shape = new RtfShape(RtfShape.SHAPE_LINE, position);
            
// Add the shape to the paragraph, so that it is anchored to the
// correct paragraph
Paragraph par = new Paragraph();
par.add(shape);
document.add(par);
    	  

By default RtfShapes are positioned above the text and the text does not wrap around them, but flow under them. Using the RtfShape.setWrapping, RtfShapePosition.setBelowText and RtfShapePosition.setZOrder methods you can change these defaults.

Wrapping defines how the text flows around the drawing object. The following wrapping modes are supported:

• SHAPE_WRAP_NONE: The default. Text flows under or over the drawing object.
• SHAPE_WRAP_BOTH: Text is wrapped around both sides of the drawing object, if there is space.
• SHAPE_WRAP_LEFT: Text is wrapped around the left side of the drawing object, if there is space.
• SHAPE_WRAP_RIGHT: Text is wrapped around the right side of the drawing object, if there is space.
• SHAPE_WRAP_LARGEST: Text is wrapped around the largest free side of the drawing object.
• SHAPE_WRAP_THROUGH: Text is wrapped through the drawing object.
• SHAPE_WRAP_TOP_BOTTOM: No text will be placed to the left or right of the drawing object.
• SHAPE_WRAP_TIGHT_BOTH: As SHAPE_WRAP_BOTH, but with less space between the text and the drawing object.
• SHAPE_WRAP_TIGHT_LEFT: As SHAPE_WRAP_LEFT, but with less space between the text and the drawing object.
• SHAPE_WRAP_TIGHT_RIGHT: As SHAPE_WRAP_RIGHT, but with less space between the text and the drawing object.
• SHAPE_WRAP_TIGHT_LARGETS: As SHAPE_WRAP_LARGEST, but with less space between the text and the drawing object.

// Create an elliptical RtfShape, around which text will only wrap on the left side
position = new RtfShapePosition(3000, 6000, 10500, 4500);
shape = new RtfShape(RtfShape.SHAPE_ELLIPSE, position);
shape.setWrapping(RtfShape.SHAPE_WRAP_LEFT);
    	  

Using the RtfShapePosition.setBelowText method, you can define whether the text is above or below the drawing object, if no wrapping is set. If text wrapping is set, then this has no effect.

// Create a rounded rectangle RtfShape and position it below the text
position = new RtfShapePosition(4000, 1500, 4500, 5000);
position.setShapeBelowText(true);
shape = new RtfShape(RtfShape.SHAPE_ROUND_RECTANGLE, position);
    	  

Finally the RtfShapePosition.setZOrder defines the z-order of the drawing objects, allowing you to stack shapes. The higher the z-order the further on top the stack the drawing object will be placed.

// Create a circular RtfShape and set its z-order to 1
position = new RtfShapePosition(5850, 6800, 8200, 7250);
position.setZOrder(1);
shape = new RtfShape(RtfShape.SHAPE_ELLIPSE, position);
document.add(shape);

// Create a star RtfShape and set its z-order to 2, above the circle
// defined above
position = new RtfShapePosition(6000, 7000, 8000, 7000);
position.setZOrder(2);
    	  

You can place text within the drawing objects using the RtfShape.setShapeText method. This only allows placement of very simple text and does not support any formatting.

// Set the text to display in the drawing object
shape.setShapeText("This text will appear in the drawing object.");
    	  

The RtfShape provides a number of predefined shapes, but sometimes it is useful to be able to draw something more flexible.

In this case the RtfShape is created with the shape type SHAPE_FREEFORM. In the second step the internal coordinate system is defined and finally the points of the shape are specified. For the internal coordinate system it is only necessary to specify the right and bottom values, as top and left default to 0. In the example these values are set to the width and height of the drawing object in Twips, but any values may be used and they will automatically be scaled to the size of the drawing object. The vertices of the drawing object are defined as an array of Point objects. It is important to remember that the coordinates of the points are defined within the internal coordinate system and not the external one defined in the RtfShapePosition constructor.

// Create a new rectangle RtfShape using the SHAPE_FREEFORM constant.
RtfShapePosition position = new RtfShapePosition(1000, 1000, 4000, 4000);
RtfShape shape = new RtfShape(RtfShape.SHAPE_FREEFORM, position);

// Set the bottom and right extents of the drawing object.
shape.setProperty(new RtfShapeProperty(RtfShapeProperty.PROPERTY_GEO_RIGHT, 3000));
shape.setProperty(new RtfShapeProperty(RtfShapeProperty.PROPERTY_GEO_BOTTOM, 3000));

// Define the vertices that make up the drawing object.
// This list draws a basic table shape.
shape.setProperty(new RtfShapeProperty(RtfShapeProperty.PROPERTY_VERTICIES,
    new Point[]{
        new Point(100, 100),
        new Point(2900, 100),
        new Point(2900, 200),
        new Point(2600, 200),
        new Point(2600, 1500),
        new Point(2520, 1500),
        new Point(2520, 200),
        new Point(480, 200),
        new Point(480, 1500),
        new Point(400, 1500),
        new Point(400, 200),
        new Point(100, 200)
    }));
    	  

Page Updated: 2008-05-16 18:35:34 Copyright © 1999-2005 Mark Hall
iText is a Free Java-Pdf library by Bruno Lowagie and Paulo Soares.