Class: Element

PDFNet. Element


new Element()

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).

Methods


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:

A rectangle specifying the bounding box of Element (a rectangle that surrounds the entire element). 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, the bounding box is undefined.


getBitsPerComponent()

Returns:

A promise that resolves to 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.

Type
number

getCharIterator()

Returns:

A promise that resolves to 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.

Type
PDFNet.Iterator

getComponentNum()

Returns:

A promise that resolves to the number of color components per sample.

Type
number

getCTM()

Returns:

A promise that resolves to current Transformation Matrix (CTM) that maps coordinates to the initial user space.

Type
PDFNet.matrix2d

getDecodeArray()

Returns:

A promise that resolves to decode array or NULL if the parameter 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 color space of the image. 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.

Type
PDFNet.Obj

getGState()

Returns:

A promise that resolves to gState of this Element

Type
PDFNet.GState

getImageColorSpace()

Returns:

A promise that resolves to the SDF object representing the color space in which image are specified or NULL if the image is an image mask

The returned color space may be any type of color space except Pattern.

Type
PDFNet.ColorSpace

getImageData()

Returns:

A promise that resolves to a stream (filter) containing decoded image data

Type
PDFNet.Filter

getImageDataSize()

Returns:

A promise that resolves to the size of image data in bytes

Type
number

getImageHeight()

Returns:

A promise that resolves to the height of the image, in samples.

Type
number

getImageRenderingIntent()

Returns:

A promise that resolves to the color rendering intent to be used in rendering the image.

Type
number
Example
Return value enum:
<pre>
PDFNet.GState.RenderingIntent = {
	e_absolute_colorimetric : 0
	e_relative_colorimetric : 1
	e_saturation : 2
	e_perceptual : 3
}
</pre>

getImageWidth()

Returns:

A promise that resolves to the width of the image, in samples.

Type
number

getMask()

Returns:

A promise that resolves to 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.

Type
PDFNet.Obj

getMCPropertyDict()

Returns:

A promise that resolves to a dictionary containing the property list or NULL if property dictionary is not present.

Type
PDFNet.Obj

getMCTag()

Returns:

A promise that resolves to a tag is a name object indicating the role or significance of the marked content point/sequence.

Type
PDFNet.Obj

getNewTextLineOffset()

returns 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.


getParentStructElement()

Returns:

A promise that resolves to 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).

Type
PDFNet.selement

getPosAdjustment()

Returns:

A promise that resolves to 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.

Type
number

getShading()

Returns:

A promise that resolves to the SDF object of the Shading object.

Type
PDFNet.Shading

getStructMCID()

Returns:

A promise that resolves to 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.

Type
number

getTextData()

Returns:

A promise that resolves to a pointer to the internal text buffer for this text element.

Type
number

getTextLength()

Returns:

A promise that resolves to 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.

Type
number

getTextMatrix()

Returns:

A promise that resolves to a reference to the current text matrix (Tm).

Type
PDFNet.matrix2d

getTextString()

Returns:

A promise that resolves to 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).

Type
string

getType()

Returns:

A promise that resolves to the current element type.

Type
number
Example
Return value enum:
<pre>
PDFNet.Element.Type = {
	e_null : 0
	e_path : 1
	e_text_begin : 2
	e_text : 3
	e_text_new_line : 4
	e_text_end : 5
	e_image : 6
	e_inline_image : 7
	e_shading : 8
	e_form : 9
	e_group_begin : 10
	e_group_end : 11
	e_marked_content_begin : 12
	e_marked_content_end : 13
	e_marked_content_point : 14
}
</pre>

getXObject()

Returns:

A promise that resolves to the SDF object of the Image/Form object.

Type
PDFNet.Obj

hasTextMatrix()

Returns:

A promise that resolves to 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.

Type
boolean

isClippingPath()

Returns:

A promise that resolves to true if the current path element is a clipping path and should be added to clipping path stack.

Type
boolean

isClipWindingFill()

Returns:

A promise that resolves to true if the current clip path is using non-zero winding rule, or false for even-odd rule.

Type
boolean

isFilled()

Returns:

A promise that resolves to true if the current path element should be filled

Type
boolean

isImageInterpolate()

Returns:

A promise that resolves to a boolean indicating whether image interpolation is to be performed.

Type
boolean

isImageMask()

Returns:

A promise that resolves to a boolean indicating whether the inline image is to be treated as an image mask.

Type
boolean

isOCVisible()

Returns:

A promise that resolves to 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 PDFView class to render PDF pages use PDFDraw::SetOCGContext() method to select an OC context.

Type
boolean

isStroked()

Returns:

A promise that resolves to true if the current path element should be stroked

Type
boolean

isWindingFill()

Returns:

A promise that resolves to 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.

Type
boolean

setClipWindingFill(winding_rule)

sets clipping path's fill rule.

Parameters:
Name Type Description
winding_rule boolean

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


setNewTextLineOffset(dx, dy)

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

Parameters:
Name Type Description
dx number

horizontal offset to the start of the curret line

dy number

vertical offset to the start of the current line


setPathClip(clip)

indicate whether the path is a clipping path or non-clipping path

Parameters:
Name Type Description
clip boolean

true to set path to clipping path. False for non-clipping path.


setPathFill(fill)

indicate whether the path should be filled

Parameters:
Name Type Description
fill boolean

true to set path to be filled. False for no fill path.


setPathStroke(stroke)

indicate whether the path should be stroked

Parameters:
Name Type Description
stroke boolean

true to set path to be stroked. False for no stroke path.


setPathTypes(in_seg_types, count)

Parameters:
Name Type Description
in_seg_types string
count number

setPosAdjustment(adjust)

Parameters:
Name Type Description
adjust number

number to set the horizontal adjustment to


setTextData(buf_text_data)

set the text data for the current e_text Element.

Parameters:
Name Type Description
buf_text_data Array

a pointer to a buffer containing text.


setTextMatrix(mtx)

Sets the text matrix for a text element.

Parameters:
Name Type Description
mtx PDFNet.matrix2d

The new text matrix for this text element


setTextMatrixEntries(a, b, c, d, h, v)

Sets 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:
Name Type Description
a number

horizontal 'scaling' component of the new text matrix.

b number

'rotation' component of the new text matrix.

c number

'rotation' component of the new text matrix.

d number

vertical 'scaling' component of the new text matrix.

h number

horizontal translation component of the new text matrix.

v number

vertical translation component of the new text matrix.


setWindingFill(winding_rule)

sets path's fill rule.

Parameters:
Name Type Description
winding_rule boolean

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


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.