public class

Element

extends Object
java.lang.Object
   ↳ com.pdftron.pdf.Element

Class Overview

Element is the abstract interface used to access graphical elements used to build the display list. Just like many other classes in PDFNet (e.g. ColorSpace, Font, Annot, etc), Element class follows the composite design pattern. This means that all Elements are accessed through the same interface, but depending on the Element type (that can be obtained using GetType()), only methods related to that type can be called. For example, if GetType() returns e_image, it is illegal to call a method specific to another Element type (i.e. a call to a text specific GetTextData() will throw an Exception).

Summary

Constants
int e_form The Constant e_form.
int e_group_begin The Constant e_group_begin.
int e_group_end The Constant e_group_end.
int e_image The Constant e_image.
int e_inline_image The Constant e_inline_image.
int e_marked_content_begin The Constant e_marked_content_begin.
int e_marked_content_end The Constant e_marked_content_end.
int e_marked_content_point The Constant e_marked_content_point.
int e_null The Constant e_null.
int e_path The Constant e_path.
int e_shading The Constant e_shading.
int e_text The Constant e_text.
int e_text_begin The Constant e_text_begin.
int e_text_end The Constant e_text_end.
int e_text_new_line The Constant e_text_new_line.
Public Methods
Rect getBBox()
Obtains the bounding box for a graphical element.
int getBitsPerComponent()
Get the bits per component.
Matrix2D getCTM()
Get the current transformation matrix.
CharIterator getCharIterator()
Get the char iterator.
int getComponentNum()
Get the number of color components per sample.
Obj getDecodeArray()
Get the decode array.
GState getGState()
Get the GState.
ColorSpace getImageColorSpace()
Get the image color space.
Filter getImageData()
Get the image data.
int getImageDataSize()
Get the image data size.
int getImageHeight()
Get the image height.
int getImageRenderingIntent()
Get the image rendering intent.
int getImageWidth()
Get the image width.
Obj getMCPropertyDict()
Get the dictionary contains property list.
Obj getMCTag()
Get the marked content tag.
Obj getMask()
Get the image mask.
double[] getNewTextLineOffset()
Get the offset (out_x, out_y) to the start of the current line relative to the beginning of the previous line.
SElement getParentStructElement()
Get the parent struct element.
PathData getPathData()
Returns the PathData stored by the path element.
double getPosAdjustment()
Get the pos adjustment.
Shading getShading()
Get the shading.
int getStructMCID()
Get the Marked Content Identifier.
byte[] getTextData()
Get the text data.
double getTextLength()
Get the text length.
Matrix2D getTextMatrix()
Get the text matrix.
String getTextString()
Get the text string.
int getType()
Get the element type.
Obj getXObject()
Get the SDF object of the Image/Form object.
boolean hasTextMatrix()
Checks for text matrix.
boolean isClipWindingFill()
Checks if current element is clip winding fill.
boolean isClippingPath()
Checks if current element is a clipping path.
boolean isFilled()
Checks if current path element is filled.
boolean isImageInterpolate()
Checks if current element is image interpolate.
boolean isImageMask()
Checks if current element is image mask.
boolean isOCVisible()
Checks if current element is visible in optional-content context.
boolean isStroked()
Checks if path current element is stroked.
boolean isWindingFill()
Checks if current element is winding fill.
void setClipWindingFill(boolean winding_rule)
Set clipping path's fill rule.
void setNewTextLineOffset(double dx, double dy)
Set the offset (dx, dy) to the start of the current line relative to the beginning of the previous line.
void setPathClip(boolean clip)
Indicate whether the path is a clipping path or non-clipping path.
void setPathData(PathData data)
Set the PathData of this element.
void setPathFill(boolean fill)
Indicate whether the path should be filled.
void setPathStroke(boolean stroke)
Indicate whether the path should be stroked.
void setPosAdjustment(double adjust)
Set the position adjustment.
void setTextData(byte[] text_data)
Set the text data for the current e_text Element.
void setTextMatrix(double a, double b, double c, double d, double h, double v)
Set the text matrix for a text element.
void setTextMatrix(Matrix2D mtx)
Set the text matrix for a text element.
void setWindingFill(boolean winding_rule)
Set path's fill rule.
void updateTextMetrics()
Recompute the character positioning information (i.e.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int e_form

The Constant e_form.

Constant Value: 9 (0x00000009)

public static final int e_group_begin

The Constant e_group_begin.

Constant Value: 10 (0x0000000a)

public static final int e_group_end

The Constant e_group_end.

Constant Value: 11 (0x0000000b)

public static final int e_image

The Constant e_image.

Constant Value: 6 (0x00000006)

public static final int e_inline_image

The Constant e_inline_image.

Constant Value: 7 (0x00000007)

public static final int e_marked_content_begin

The Constant e_marked_content_begin.

Constant Value: 12 (0x0000000c)

public static final int e_marked_content_end

The Constant e_marked_content_end.

Constant Value: 13 (0x0000000d)

public static final int e_marked_content_point

The Constant e_marked_content_point.

Constant Value: 14 (0x0000000e)

public static final int e_null

The Constant e_null.

Constant Value: 0 (0x00000000)

public static final int e_path

The Constant e_path.

Constant Value: 1 (0x00000001)

public static final int e_shading

The Constant e_shading.

Constant Value: 8 (0x00000008)

public static final int e_text

The Constant e_text.

Constant Value: 3 (0x00000003)

public static final int e_text_begin

The Constant e_text_begin.

Constant Value: 2 (0x00000002)

public static final int e_text_end

The Constant e_text_end.

Constant Value: 5 (0x00000005)

public static final int e_text_new_line

The Constant e_text_new_line.

Constant Value: 4 (0x00000004)

Public Methods

public Rect getBBox ()

Obtains the bounding box for a graphical element. Calculates the bounding box for a graphical element (i.e. an Element that belongs to one of following types: e_path, e_text, e_image, e_inline_image, e_shading e_form). The returned bounding box is guaranteed to encompass the Element, but is not guaranteed to be the smallest box that could contain the element. For example, for Bezier curves the bounding box will enclose all control points, not just the curve itself.

Returns
  • Rect if this is a graphical element and the bounding box can be calculated; null for non-graphical elements which don't have bounding box. The coordinates are represented in the default PDF page coordinate system and are using units called points ( 1 point = 1/72 inch = 2.54 /72 centimeter). The bounding box already accounts for the effects of current transformation matrix (CTM), text matrix, font size, and other properties in the graphics state. If this is a non-graphical element (i.e. the method returns false) the bounding box is undefined.
Throws
PDFNetException

public int getBitsPerComponent ()

Get the bits per component.

Returns
  • the number of bits used to represent each color component. Only a single value may be specified; the number of bits is the same for all color components. Valid values are 1, 2, 4, and 8.
Throws
PDFNetException

public Matrix2D getCTM ()

Get the current transformation matrix.

Returns
  • current transformation matrix (ctm) that maps coordinates to the initial user space.
Throws
PDFNetException

public CharIterator getCharIterator ()

Get the char iterator.

Note: CharIterator follows the standard STL forward-iterator interface. An example of how to use CharIterator. 

 
 for (CharIterator itr = element.GetCharIterator(); itr.HasNext(); itr.Next()) {
         unsigned int char_code = itr.Current().char_code;
         double char_pos_x = itr.Current().x;
         double char_pos_y = itr.Current().y;
     
 }

* Note: Character positioning information (x, y) is represented in text space. In order to get the positioning in the user space, the returned value should be scaled using the text matrix (GetTextMatrix()) and the current transformation matrix (GetCTM()). See section 4.2 'Other Coordinate Spaces' in PDF Reference Manual for details and PDFNet FAQ - "How do I get absolute/relative text and character positioning".

* Note: whithin a text run a character may occupy more than a single byte (e.g. in case of composite/Type0 fonts). The role of CharIterator/CharData is to provide a uniform and easy to use inteface to access character information.

Returns
  • a CharIterator addressing the first CharData element in the text run. CharIterator points to CharData. CharData is a data structure that contains the char_code number (used to retrieve glyph outlines, to map to Unicode, etc.), character positioning information (x, y), and the number of bytes taken by the character within the text buffer.
Throws
PDFNetException

public int getComponentNum ()

Get the number of color components per sample.

Returns
  • the number of color components per sample.
Throws
PDFNetException

public Obj getDecodeArray ()

Get the decode array.

Returns
  • Decode array or NULL if the paramter is not specified. A decode object is an array of numbers describing how to map image samples into the range of values appropriate for the image's color space . If ImageMask is true, the array must be either [0 1] or [1 0]; otherwise, its length must be twice the number of color components required by ColorSpace. Default value depends on the color space, See Table 4.36 in PDF Ref. Manual.
Throws
PDFNetException

public GState getGState ()

Get the GState.

Returns
  • GState of this Element
Throws
PDFNetException

public ColorSpace getImageColorSpace ()

Get the image color space.

Returns
  • The SDF object representing the color space in which image are specified or NULL if: - the image is an image mask - or is compressed using JPXDecode with missing ColorSpace entry in image dictionary. The returned color space may be any type of color space except Pattern.
Throws
PDFNetException

public Filter getImageData ()

Get the image data.

Returns
  • A stream (filter) containing decoded image data
Throws
PDFNetException

public int getImageDataSize ()

Get the image data size.

Returns
  • the size of image data in bytes
Throws
PDFNetException

public int getImageHeight ()

Get the image height.

Returns
  • the height of the image, in samples.
Throws
PDFNetException

public int getImageRenderingIntent ()

Get the image rendering intent.

Returns
  • The color rendering intent to be used in rendering the image.
Throws
PDFNetException

public int getImageWidth ()

Get the image width.

Returns
  • the width of the image, in samples.
Throws
PDFNetException

public Obj getMCPropertyDict ()

Get the dictionary contains property list.

Note: the function automatically looks under Properties sub-dictionary of the current resource dictionary if the dictionary is not in-line. Therefore you can assume that returned Obj is dictionary if it is not NULL.

Returns
  • a dictionary containing the property list or NULL if property dictionary is not present.
Throws
PDFNetException

public Obj getMCTag ()

Get the marked content tag.

Returns
  • a tag is a name object indicating the role or significance of the marked content point/sequence.
Throws
PDFNetException

public Obj getMask ()

Get the image mask.

Returns
  • an image XObject defining an image mask to be applied to this image (See 'Explicit Masking', 4.8.5), or an array specifying a range of colors to be applied to it as a color key mask (See 'Color Key Masking'). If IsImageMask() return true, this method will return NULL.
Throws
PDFNetException

public double[] getNewTextLineOffset ()

Get the offset (out_x, out_y) to the start of the current line relative to the beginning of the previous line. out_x and out_y are numbers expressed in unscaled text space units. The returned numbers correspond to the arguments of 'Td' operator.

Returns
  • the new text line offset
Throws
PDFNetException

public SElement getParentStructElement ()

Get the parent struct element.

Returns
  • Parent logical structure element (such as 'span' or 'paragraph'). If the Element is not associated with any structure element, the returned SElement will not be valid (i.e. selem.IsValid() -> false).
Throws
PDFNetException

public PathData getPathData ()

Returns the PathData stored by the path element.

Returns
  • The PathData which contains the operators and corresponding point data.
Throws
PDFNetException

public double getPosAdjustment ()

Get the pos adjustment.

Note: because CharIterator positioning information already accounts for TJ adjustments this method is rarely used.

Returns
  • The number used to adjust text matrix in horizontal direction when drawing text. The number is expressed in thousandths of a unit of text space. The returned number corresponds to a number value within TJ array. For 'Tj' text strings the returned value is always 0.
Throws
PDFNetException

public Shading getShading ()

Get the shading.

Returns
  • the SDF object of the Shading object.
Throws
PDFNetException

public int getStructMCID ()

Get the Marked Content Identifier.

Returns
  • Marked Content Identifier (MCID) for this Element or a negative number if the element is not assigned an identifier/MCID. Marked content identifier can be used to associate an Element with logical structure element that refers to the Element.
Throws
PDFNetException

public byte[] getTextData ()

Get the text data.

Note: GetTextData() returns the raw text data and not a Unicode string. In PDF text can be encoded using various encoding schemes so it is necessary to consider Font encoding while processing the content of this buffer.

Note: Most of the time GetTextString() is what you are looking for instead. GetTextString() maps the raw text directly into Unicode (as specified by Adobe Glyph List (AGL) ). Even if you would prefer to decode text yourself it is more convenient to use CharIterators returned by CharBegin()/CharEnd() and PDF::Font code mapping methods.

Note: the buffer owner is the current element (i.e. ElementReader or ElementBuilder).

Returns
  • a pointer to the internal text buffer for this text element.
Throws
PDFNetException

public double getTextLength ()

Get the text length.

Note: Computed text length is represented in text space. In order to get the length of the text run in the user space, the returned value should be scaled using the text matrix (GetTextMatrix()) and the current transformation matrix (GetCTM()). See section 4.2 'Other Coordinate Spaces' in PDF Reference Manual for details.

Returns
  • The text advance distance in text space. The total sum of all of the advance values from rendering all of the characters within this element, including the advance value on the glyphs, the effect of properties such as 'char-spacing', 'word-spacing' and positioning adjustments on 'TJ' elements.
Throws
PDFNetException

public Matrix2D getTextMatrix ()

Get the text matrix.

Returns
  • a reference to the current text matrix (Tm).
Throws
PDFNetException

public String getTextString ()

Get the text string.

Note: In PDF text can be encoded using various encoding schemes and in some cases it is not possible to extract Unicode encoding. If it is not possible to map charcode to Unicode the function will map a character to undefined code, 0xFFFD. This code is defined in private Unicode range.

Note: If you would like to map raw text to Unicode (or some other encoding) yourself use CharIterators returned by CharBegin()/CharEnd() and PDF::Font code mapping methods.

Note: The string owner is the current element (i.e. ElementReader or ElementBuilder).

Returns
  • a pointer to Unicode string for this text Element. The function maps character codes to Unicode array defined by Adobe Glyph List (http://partners.adobe.com/asn/developer/type/glyphlist.txt).
Throws
PDFNetException

public int getType ()

Get the element type.

Returns
  • the current element type.
Throws
PDFNetException

public Obj getXObject ()

Get the SDF object of the Image/Form object.

Returns
  • the SDF object of the Image/Form object.
Throws
PDFNetException

public boolean hasTextMatrix ()

Checks for text matrix.

Returns
  • true if this element is directly associated with a text matrix (that is Tm operator is just before this text element) or false if the text matrix is default or is inherited from previous text elements.
Throws
PDFNetException

public boolean isClipWindingFill ()

Checks if current element is clip winding fill.

Returns
  • true if the current clip path is using non-zero winding rule, or false for even-odd rule.
Throws
PDFNetException

public boolean isClippingPath ()

Checks if current element is a clipping path.

Returns
  • true if the current path element is a clipping path and should be added to clipping path stack.
Throws
PDFNetException

public boolean isFilled ()

Checks if current path element is filled.

Returns
  • true if the current path element should be filled
Throws
PDFNetException

public boolean isImageInterpolate ()

Checks if current element is image interpolate.

Returns
  • a boolean indicating whether image interpolation is to be performed.
Throws
PDFNetException

public boolean isImageMask ()

Checks if current element is image mask.

Returns
  • a boolean indicating whether the inline image is to be treated as an image mask.
Throws
PDFNetException

public boolean isOCVisible ()

Checks if current element is visible in optional-content context.

Returns
  • true if this element is visible in the optional-content context (OCG::Context). The method considers the context's current OCMD stack, the group ON-OFF states, the non-OC drawing status, the drawing and enumeration mode, and the intent. When enumerating page content, OCG::Context can be passed as a parameter in ElementReader.Begin() method. When using PDFDraw, PDFRasterizer, or PDFViewCtrl class to render PDF pages use PDFDraw::SetOCGContext() method to select an OC context.
Throws
PDFNetException

public boolean isStroked ()

Checks if path current element is stroked.

Returns
  • true if the current path element should be stroked
Throws
PDFNetException

public boolean isWindingFill ()

Checks if current element is winding fill.

Returns
  • true if the current path should be filled using non-zero winding rule, or false if the path should be filled using even-odd rule. According non-zero winding rule, you can determine whether a test point is inside or outside a closed curve as follows: Draw a line from a test point to a point that is distant from the curve. Count the number of times the curve crosses the test line from left to right, and count the number of times the curve crosses the test line from right to left. If those two numbers are the same, the test point is outside the curve; otherwise, the test point is inside the curve. According to even-odd rule, you can determine whether a test point is inside or outside a closed curve as follows: Draw a line from the test point to a point that is distant from the curve. If that line crosses the curve an odd number of times, the test point is inside the curve; otherwise, the test point is outside the curve.
Throws
PDFNetException

public void setClipWindingFill (boolean winding_rule)

Set clipping path's fill rule.

Parameters
winding_rule if winding_rule is true clipping should use non-zero winding rule, or false for even-odd rule.
Throws
PDFNetException

public void setNewTextLineOffset (double dx, double dy)

Set the offset (dx, dy) to the start of the current line relative to the beginning of the previous line.

Parameters
dx the x coordinate
dy the y coordinate
Throws
PDFNetException

public void setPathClip (boolean clip)

Indicate whether the path is a clipping path or non-clipping path.

Parameters
clip the new path clip
Throws
PDFNetException

public void setPathData (PathData data)

Set the PathData of this element. The PathData contains the array of points stored by the element and the array of path segment types.

Throws
PDFNetException

public void setPathFill (boolean fill)

Indicate whether the path should be filled.

Parameters
fill the new path fill
Throws
PDFNetException

public void setPathStroke (boolean stroke)

Indicate whether the path should be stroked.

Parameters
stroke the new path stroke
Throws
PDFNetException

public void setPosAdjustment (double adjust)

Set the position adjustment.

Parameters
adjust the new position adjustment
Throws
PDFNetException

public void setTextData (byte[] text_data)

Set the text data for the current e_text Element.

Parameters
text_data a pointer to a buffer containing text.
Throws
PDFNetException

public void setTextMatrix (double a, double b, double c, double d, double h, double v)

Set the text matrix for a text element. This method accepts text transformation matrix components directly. A transformation matrix in PDF is specified by six numbers, usually in the form of an array containing six elements. In its most general form, this array is denoted [a b c d h v]; it can represent any linear transformation from one coordinate system to another. For more information about PDF matrices please refer to section 4.2.2 'Common Transformations' in PDF Reference Manual, and to documentation for Matrix2D class.

Parameters
a - horizontal 'scaling' component of the new text matrix.
b - 'rotation' component of the new text matrix.
c - 'rotation' component of the new text matrix.
d - vertical 'scaling' component of the new text matrix.
h - horizontal translation component of the new text matrix.
v - vertical translation component of the new text matrix.
Throws
PDFNetException

public void setTextMatrix (Matrix2D mtx)

Set the text matrix for a text element.

Parameters
mtx The new text matrix for this text element
Throws
PDFNetException

public void setWindingFill (boolean winding_rule)

Set path's fill rule.

Parameters
winding_rule if winding_rule is true path will be filled using non-zero winding fill rule, otherwise even-odd fill will be used.
Throws
PDFNetException

public void updateTextMetrics ()

Recompute the character positioning information (i.e. CharIterator-s) and text length. Element objects caches text length and character positioning information. If the user modifies the text data or graphics state the cached information is not correct. UpdateTextMetrics() can be used to recalculate the correct positioning and length information.

Throws
PDFNetException