com.qoppa.pdf

Class TextPosition

java.lang.Object

com.qoppa.pdf.TextPosition

All Implemented Interfaces:

TextSelection

Direct Known Subclasses:

TextPositionWithContext

public class TextPosition
extends Object
implements TextSelection

Object that holds information about the location of a text string in a PDF file. This information is returned by the library when text information is needed by the host application. The information includes the text position, its angle and its list of enclosing "quadrilaterals". Each quadrilateral is an array of four points that enclose some portion of the text. Typically, a TextPosition for a single word, or a contiguous list of words on a single line will have a single quadrilateral. But if the text is not contiguous, is composed of multiple pdf show text commands, or spans multiple lines, then multiple quadrilaterals are required. The enclosing quadrilaterals and Shape for a TextPosition are available in either View space coordinates or PDF space coordinates. The difference is simply that the page crop and rotation, if any, has been applied to the View space coordinates. If the page is not cropped and no page level rotation is set then the View space is equivalent to PDF space. Essentially the View space version of the methods are convenience methods so you don't need to apply a transform to the PDF space coordinates when View space coordinates are needed. It is probably more common to use the PDF space quadrilaterals and Shape than the View space transformations as pdf page content and annotations work in PDF space, but of course that depends. Methods should specify whether they work with either PDF space or View space except for historical reasons other terms are frequently used. "Media box" coordinates is PDF space and "display" coordinates and "Crop box" coordinates mean View space.

Author:

Qoppa Software

Constructor Summary

Constructors

Constructor and Description
TextPosition(String text, Shape textShape, double angle, AffineTransform pageTransform, int pageNumber, List<Point2D[]> pdfQuads2)

Method Summary

Modifier and Type	Method and Description
double	getAngle() Returns the angle that this text is displayed at on the page.
Shape	getEnclosingShape() Deprecated. This method is redundant. Replaced by get by getViewSelectionShape().
int	getPageNumber() Indicates on which page of the document the TextPosition's text is located.
Point2D[]	getPDFQuadrilateral() Deprecated. replaced by getPDFQuadrilaterals().
Vector<Point2D[]>	getPDFQuadrilaterals() Returns a list of quadrilaterals that will enclose the text elements in this object.
Shape	getPDFSelectionShape() Returns the entire shape that encloses all text in this selection.
Point2D[]	getQuadrilateral() Deprecated. replaced by getViewQuadrilaterals().
Vector<Point2D[]>	getQuadrilaterals() Deprecated. replaced with getViewQuadrilaterals().
Shape	getSelectionShape() Deprecated. replaced by getViewSelectionShape().
String	getText() Returns the text string.
String	getText(boolean lineBreaks) Returns a string containing all the selected text.
Point2D[]	getViewQuadrilateral() Deprecated. replaced by getViewQuadrilaterals().
Vector<Point2D[]>	getViewQuadrilaterals() Returns a list of quadrilaterals that will enclose the text elements in this object.
Shape	getViewSelectionShape() Returns the entire shape that encloses all text in this selection.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TextPosition

public TextPosition(String text,
                    Shape textShape,
                    double angle,
                    AffineTransform pageTransform,
                    int pageNumber,
                    List<Point2D[]> pdfQuads2)

Method Detail

getPageNumber

public int getPageNumber()

Indicates on which page of the document the TextPosition's text is located.

Returns:

The page number of the page the TextPosition's text is located on.

getEnclosingShape

public Shape getEnclosingShape()

Deprecated. This method is redundant. Replaced by get by getViewSelectionShape().

Returns a shape that encloses the text on the page. The shape's coordinate system is in 'display' coordinates: The origin of the coordinates are page.getCropBox().getX() and page.getCropBox().getY().

Returns:

The shape that encloses the text on the screen

getText

public String getText()

Returns the text string.

Specified by:

getText in interface TextSelection

Returns:

The text.

getText

public String getText(boolean lineBreaks)

Description copied from interface: TextSelection

Returns a string containing all the selected text.

Specified by:

getText in interface TextSelection

Parameters:

lineBreaks - If set to true, lines within paragraphs will be split into separate lines. If set to false, lines within paragraphs will be separated with spaces.

Returns:

A string containing all the selected text.

getQuadrilateral

public Point2D[] getQuadrilateral()

Deprecated. replaced by getViewQuadrilaterals().

Returns a quadrilateral with the four corners for this text string. The coordinates of the quadrilateral is in 'display' coordinates: The origin of the coordinates are page.getCropBox().getX() and page.getCropBox().getY().

Returns:

An array of 4 Point2D object. The points in can be connected by lines in the array order to form the quadrilateral enclosing the text.

getViewQuadrilateral

public Point2D[] getViewQuadrilateral()

Deprecated. replaced by getViewQuadrilaterals().

Returns a quadrilateral with the four corners for this text string. The coordinates of the quadrilateral is in 'display' coordinates: The origin of the coordinates are page.getCropBox().getX() and page.getCropBox().getY().

Returns:

An array of 4 Point2D object. The points in can be connected by lines in the array order to form the quadrilateral enclosing the text. Note: A TextPosition may be enclosed by a list of a quadrilaterals and this method only returns the first quadrilateral in the list.

getPDFQuadrilateral

public Point2D[] getPDFQuadrilateral()

Deprecated. replaced by getPDFQuadrilaterals().

Returns a quadrilateral with the four corners for this text string. The coordinates of the quadrilateral is Media box coordinates.

Returns:

An array of 4 Point2D object. The points in can be connected by lines in the array order to form the quadrilateral enclosing the text. Note: A TextPosition may be enclosed by a list of a quadrilaterals and this method only returns the first quadrilateral in the list.

getAngle

public double getAngle()

Returns the angle that this text is displayed at on the page.

Returns:

The angle of the text in radians and in Media box coordinate space.

getQuadrilaterals

public Vector<Point2D[]> getQuadrilaterals()

Deprecated. replaced with getViewQuadrilaterals().

Returns a list of quadrilaterals that will enclose the text elements in this object. The coordinates of the list of quadrilaterals is in 'display' coordinates: The origin of the coordinates are page.getCropBox().getX() and page.getCropBox().getY().

Specified by:

getQuadrilaterals in interface TextSelection

Returns:

A list of quadrilaterals

getViewQuadrilaterals

public Vector<Point2D[]> getViewQuadrilaterals()

Returns a list of quadrilaterals that will enclose the text elements in this object. The coordinates of the list of quadrilaterals is in View space (aka display space and Cropbox space coordinates: The origin of the coordinates are page.getCropBox().getX() and page.getCropBox().getY().

Specified by:

getViewQuadrilaterals in interface TextSelection

Returns:

A list of one quadrilaterals In general you probably would use getPDFQuadrilaterals() rather than this method as methods and objects that use quadrilaterals are typically used in PDF/"Media box" coordinate space, such as Annotation creation. When working in View space it is probably more common to use getViewSelectionShape().

getPDFQuadrilaterals

public Vector<Point2D[]> getPDFQuadrilaterals()

Returns a list of quadrilaterals that will enclose the text elements in this object. The coordinates of the list of quadrilaterals is in PDF space coordinates (aka Media box coordinates).

Specified by:

getPDFQuadrilaterals in interface TextSelection

Returns:

A list of one quadrilaterals Note: When creating annotations that require quadrilaterals such as text highlighting or redactions, this is the method you should use as they operate in PDF space, AKA "Media box", coordinates.

getSelectionShape

@Deprecated
public Shape getSelectionShape()

Deprecated. replaced by getViewSelectionShape().

Returns a shape that encloses the text on the page. The shape's coordinate system is in 'display' coordinates: The origin of the coordinates are page.getCropBox().getX() and page.getCropBox().getY(). This method fulfills the TextSelection interface.

Specified by:

getSelectionShape in interface TextSelection

Returns:

The shape that encloses the text on the screen

getPDFSelectionShape

public Shape getPDFSelectionShape()

Returns the entire shape that encloses all text in this selection. The shape's coordinate system is in PDF space, aka MediaBox coordinates. PDF space is the coordinate space of a PDF page without the crop or page rotation applied. Page content and annotations work in PDF space.

Specified by:

getPDFSelectionShape in interface TextSelection

Returns:

A Shape, that holds all the selection area. Generally the Shape is a composite of all the quadrilaterals returned by getPDFQuadrilaterals()

getViewSelectionShape

public Shape getViewSelectionShape()

Returns the entire shape that encloses all text in this selection. The shape's coordinate system is in View space (aka display and/or Cropbox) coordinates: The origin of the coordinates are page.getCropBox().getX() and page.getCropBox().getY().

Specified by:

getViewSelectionShape in interface TextSelection

Returns:

A Shape, possibly composed of a number of subshapes, that holds all the selection area. The coordinate space of this shape differs from getPDFSelectionShape() by applying a transform that takes into account the cropbox of the document and the page's rotation. This coordinate space can be useful when working with methods that take coordinates in View space (aka display or Cropbox) coordinates.