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

Inheritance

object

Element

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.MemberwiseClone()

Namespace: pdftron.PDF

Assembly: PDFNet.dll

Syntax

public class Element

Methods

DeleteObject(IntPtr)

Declaration

public static extern bool DeleteObject(IntPtr hObject)

Parameters

Type	Name	Description
IntPtr	hObject

Returns

Type	Description
bool

GetBBox(Rect)

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.

Declaration

public bool GetBBox(Rect bbox)

Parameters

Type	Name	Description
Rect	bbox	(Filled by the method) A reference to 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 (i.e. the method returns false) the bounding box is undefined.

Returns

Type

Description

bool

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetBitmap()

Gets Bitmap

Declaration

public Bitmap GetBitmap()

Returns

Type	Description
Bitmap	GDI+ bitmap from this image. PDFNet creates a GDI+ bitmap that closely matches the original image in terms of the image depth and the number of color channels. PDF color spaces that do not have a counterpart in GDI+ are converted to RGB.

GetBitmapSource()

Gets Bitmap

Declaration

public BitmapSource GetBitmapSource()

Returns

Type	Description
BitmapSource	BitmapSource from this image. PDFNet creates a GDI+ bitmap that closely matches the original image in terms of the image depth and the number of color channels. PDF color spaces that do not have a counterpart in GDI+ are converted to RGB. Then convert into BitmapSource.

GetBitsPerComponent()

Gets the bits per component.

Declaration

public int GetBitsPerComponent()

Returns

Type	Description
int	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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetCTM()

Gets the cTM.

Declaration

public Matrix2D GetCTM()

Returns

Type	Description
Matrix2D	current transformation matrix (ctm) that maps coordinates to the initial user space.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetCharIterator()

Gets the char iterator.

Declaration

public CharIterator GetCharIterator()

Returns

Type	Description
CharIterator	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.

Remarks

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;
}

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?".

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetComponentNum()

Gets the component number.

Declaration

public int GetComponentNum()

Returns

Type	Description
int	the number of color components per sample.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetDecodeArray()

Gets the decode array.

Declaration

public Obj GetDecodeArray()

Returns

Type

Description

Obj

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetGState()

Gets the g state.

Declaration

public GState GetGState()

Returns

Type	Description
GState	GState of this Element

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetImageColorSpace()

Gets the image color space.

Declaration

public ColorSpace GetImageColorSpace()

Returns

Type	Description
ColorSpace	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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetImageData()

Gets the image data.

Declaration

public Filter GetImageData()

Returns

Type	Description
Filter	A stream (filter) containing decoded image data

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetImageDataSize()

Gets the image data size.

Declaration

public int GetImageDataSize()

Returns

Type	Description
int	the size of image data in bytes

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetImageHeight()

Gets the image height.

Declaration

public int GetImageHeight()

Returns

Type	Description
int	the height of the image, in samples.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetImageRenderingIntent()

Gets the image rendering intent.

Declaration

public GState.RenderingIntent GetImageRenderingIntent()

Returns

Type	Description
GState.RenderingIntent	The color rendering intent to be used in rendering the image.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetImageWidth()

Gets the image width.

Declaration

public int GetImageWidth()

Returns

Type	Description
int	the width of the image, in samples.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetMCPropertyDict()

Gets the mC property dict.

Declaration

public Obj GetMCPropertyDict()

Returns

Type	Description
Obj	a dictionary containing the property list or NULL if property dictionary is not present.

Remarks

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetMCTag()

Gets the mC tag.

Declaration

public Obj GetMCTag()

Returns

Type	Description
Obj	a tag is a name object indicating the role or significance of the marked content point/sequence.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetMask()

Gets the mask.

Declaration

public Obj GetMask()

Returns

Type	Description
Obj	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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetNewTextLineOffset(ref double, ref double)

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

Declaration

public void GetNewTextLineOffset(ref double out_x, ref double out_y)

Parameters

Type	Name	Description
double	out_x	x coordinate of the text line offset
double	out_y	y coordinate of the text line offset

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetParentStructElement()

Gets the parent logical structure element

Declaration

public SElement GetParentStructElement()

Returns

Type	Description
SElement	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).

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetPathData()

Get the PathData stored by the path element.

Declaration

public PathData GetPathData()

Returns

Type	Description
PathData	The PathData which contains the operators and corresponding point data.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetPosAdjustment()

Gets the pos adjustment.

Declaration

public double GetPosAdjustment()

Returns

Type	Description
double	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.

Remarks

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetShading()

Gets the shading.

Declaration

public Shading GetShading()

Returns

Type	Description
Shading	the SDF object of the Shading object.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetStructMCID()

Gets the struct MCID.

Declaration

public int GetStructMCID()

Returns

Type	Description
int	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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetTextData()

Gets the text data.

Declaration

public byte[] GetTextData()

Returns

Type	Description
byte[]	a pointer to the internal text buffer for this text element.

Remarks

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. Most of the time GetTextString() is what you are looking for instead.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetTextDataSize()

Gets the size of the internal text buffer returned in GetTextData().

Declaration

public int GetTextDataSize()

Returns

Type	Description
int	the size of the internal text buffer returned in GetTextData().

GetTextLength()

Gets the text length.

Declaration

public double GetTextLength()

Returns

Type	Description
double	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.

Remarks

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetTextMatrix()

Gets the text matrix.

Declaration

public Matrix2D GetTextMatrix()

Returns

Type	Description
Matrix2D	a reference to the current text matrix (Tm).

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetTextString()

Gets the text string.

Declaration

public string GetTextString()

Returns

Type	Description
string	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).

Remarks

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.

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.

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetType()

Gets the type.

Declaration

public Element.Type GetType()

Returns

Type	Description
Element.Type	the current element type.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

GetXObject()

Gets the x object.

Declaration

public Obj GetXObject()

Returns

Type	Description
Obj	the SDF object of the Image/Form object.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

HasTextMatrix()

Checks for text matrix.

Declaration

public bool HasTextMatrix()

Returns

Type	Description
bool	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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsClipWindingFill()

Checks if is clip winding fill.

Declaration

public bool IsClipWindingFill()

Returns

Type	Description
bool	true if the current clip path is using non-zero winding rule, or false for even-odd rule.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsClippingPath()

Checks if is clipping path.

Declaration

public bool IsClippingPath()

Returns

Type	Description
bool	true if the current path element is a clipping path and should be added to clipping path stack.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsFilled()

Checks if is filled.

Declaration

public bool IsFilled()

Returns

Type	Description
bool	true if the current path element should be filled

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsImageInterpolate()

Checks if is image interpolate.

Declaration

public bool IsImageInterpolate()

Returns

Type	Description
bool	a boolean indicating whether image interpolation is to be performed.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsImageMask()

Checks if is image mask.

Declaration

public bool IsImageMask()

Returns

Type	Description
bool	a boolean indicating whether the inline image is to be treated as an image mask.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsOCVisible()

Checks if is oC visible.

Declaration

public bool IsOCVisible()

Returns

Type

Description

bool

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 SetOCGContext() method to select an OC context.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsStroked()

Checks if is stroked.

Declaration

public bool IsStroked()

Returns

Type	Description
bool	true if the current path element should be stroked

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

IsWindingFill()

Checks if is winding fill.

Declaration

public bool IsWindingFill()

Returns

Type

Description

bool

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.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetClipWindingFill(bool)

Sets clipping path's fill rule.

Declaration

public void SetClipWindingFill(bool winding_rule)

Parameters

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetNewTextLineOffset(double, double)

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

Declaration

public void SetNewTextLineOffset(double dx, double dy)

Parameters

Type	Name	Description
double	dx	the dx
double	dy	the dy

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetPathClip(bool)

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

Declaration

public void SetPathClip(bool clip)

Parameters

Type	Name	Description
bool	clip	the new path clip

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetPathData(PathData)

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

Declaration

public void SetPathData(PathData data)

Parameters

Type	Name	Description
PathData	data	The new path data.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetPathFill(bool)

Indicate whether the path should be filled.

Declaration

public void SetPathFill(bool fill)

Parameters

Type	Name	Description
bool	fill	the new path fill

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetPathStroke(bool)

Indicate whether the path should be stroked.

Declaration

public void SetPathStroke(bool stroke)

Parameters

Type	Name	Description
bool	stroke	the new path stroke

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetPosAdjustment(double)

Sets the pos adjustment.

Declaration

public void SetPosAdjustment(double adjust)

Parameters

Type	Name	Description
double	adjust	the new pos adjustment

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetTextData(byte[], int)

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.

Declaration

public void SetTextData(byte[] text_data, int text_data_size)

Parameters

Type	Name	Description
byte[]	text_data	a pointer to a buffer containing text.
int	text_data_size	size of the cli::array

Remarks

the buffer owner is the current element (i.e. ElementReader or ElementBuilder). Set the text data for the current e_text Element.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetTextMatrix(double, double, double, double, double, double)

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.

Declaration

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

Parameters

Type	Name	Description
double	a	horizontal 'scaling' component of the new text matrix.
double	b	'rotation' component of the new text matrix.
double	c	'rotation' component of the new text matrix.
double	d	vertical 'scaling' component of the new text matrix.
double	h	horizontal translation component of the new text matrix.
double	v	vertical translation component of the new text matrix.

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetTextMatrix(Matrix2D)

Sets the text matrix for a text element.

Declaration

public void SetTextMatrix(Matrix2D mtx)

Parameters

Type	Name	Description
Matrix2D	mtx	The new text matrix for this text element

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

SetWindingFill(bool)

Sets path's fill rule.

Declaration

public void SetWindingFill(bool winding_rule)

Parameters

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

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception

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.

Declaration

public void UpdateTextMetrics()

Exceptions

Type	Condition
PDFNetException	PDFNetException the PDFNet exception