pdftron::PDF::Element Class Reference

Element is the abstract interface used to access graphical elements used to build the display list. More...

#include <Element.h>

List of all members.

Public Types

enum  Type {
  e_null, e_path, e_text_begin, e_text,
  e_text_new_line, e_text_end, e_image, e_inline_image,
  e_shading, e_form, e_group_begin, e_group_end,
  e_marked_content_begin, e_marked_content_end, e_marked_content_point
}
enum  PathSegmentType {
  e_moveto = 1, e_lineto, e_cubicto, e_conicto,
  e_rect, e_closepath
}

Public Member Functions

 Element ()
 Element (const Element &c)
Elementoperator= (const Element &c)
 operator bool ()
Type GetType ()
GState GetGState ()
Common::Matrix2D GetCTM ()
bool GetBBox (Rect &out_bbox)
 Obtains the bounding box for a graphical element.
Struct::SElement GetParentStructElement ()
int GetStructMCID ()
bool IsOCVisible ()
bool IsClippingPath ()
bool IsStroked ()
bool IsFilled ()
bool IsWindingFill ()
bool IsClipWindingFill ()
const char * GetPathTypes ()
 Returns this path's array of path segment types.
int GetPathTypesCount ()
const double * GetPathPoints ()
 Returns the array of points stored by the Path element.
int GetPointCount ()
void SetPathClip (bool clip)
 Indicate whether the path is a clipping path or non-clipping path.
void SetPathStroke (bool stroke)
 Indicate whether the path should be stroked.
void SetPathFill (bool fill)
 Indicate whether the path should be filled.
void SetWindingFill (bool winding_rule)
 Sets path's fill rule.
void SetClipWindingFill (bool winding_rule)
 Sets clipping path's fill rule.
void SetPathPoints (const double *in_points, int count)
 Sets the array of points stored by the Path element.
void SetPathTypes (const char *in_seg_types, int count)
 Sets this path's array of path segment types.
SDF::Obj GetXObject ()
Filters::Filter GetImageData () const
int GetImageDataSize () const
Gdiplus::Bitmap * GetBitmap () const
 Convert PDF image to GDI+ Bitmap.
ColorSpace GetImageColorSpace () const
int GetImageWidth () const
int GetImageHeight () const
SDF::Obj GetDecodeArray () const
int GetBitsPerComponent () const
int GetComponentNum () const
bool IsImageMask () const
bool IsImageInterpolate () const
SDF::Obj GetMask () const
GState::RenderingIntent GetImageRenderingIntent () const
const UStringGetTextString ()
const UCharGetTextData ()
UInt32 GetTextDataSize ()
Common::Matrix2D GetTextMatrix ()
CharIterator GetCharIterator ()
double GetTextLength ()
double GetPosAdjustment ()
void GetNewTextLineOffset (double &out_x, double &out_y)
 Returns the offset (out_x, out_y) to the start of the current line relative to the beginning of the previous line.
bool HasTextMatrix ()
void SetTextData (const UChar *text_data, int text_data_size)
 Set the text data for the current e_text Element.
void SetTextMatrix (Common::Matrix2D &mtx)
 Sets the text matrix for a text element.
void SetTextMatrix (double a, double b, double c, double d, double h, double v)
 Sets the text matrix for a text element.
void SetPosAdjustment (double adjust)
void UpdateTextMetrics ()
 Recompute the character positioning information (i.e.
void SetNewTextLineOffset (double dx, double dy)
 Sets the offset (dx, dy) to the start of the current line relative to the beginning of the previous line.
Shading GetShading ()
SDF::Obj GetMCPropertyDict ()
SDF::Obj GetMCTag ()
 ~Element ()


Detailed Description

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


Member Enumeration Documentation

Enumerator:
e_null 
e_path 
e_text_begin 
e_text 
e_text_new_line 
e_text_end 
e_image 
e_inline_image 
e_shading 
e_form 
e_group_begin 
e_group_end 
e_marked_content_begin 
e_marked_content_end 
e_marked_content_point 

Enumerator:
e_moveto 
e_lineto 
e_cubicto 
e_conicto 
e_rect 
e_closepath 


Constructor & Destructor Documentation

pdftron::PDF::Element::Element (  ) 

pdftron::PDF::Element::Element ( const Element c  ) 

pdftron::PDF::Element::~Element (  )  [inline]


Member Function Documentation

Element& pdftron::PDF::Element::operator= ( const Element c  ) 

pdftron::PDF::Element::operator bool (  )  [inline]

Type pdftron::PDF::Element::GetType (  ) 

Returns:
the current element type.

GState pdftron::PDF::Element::GetGState (  ) 

Returns:
GState of this Element

Common::Matrix2D pdftron::PDF::Element::GetCTM (  ) 

Returns:
Current Transformation Matrix (CTM) that maps coordinates to the initial user space.

bool pdftron::PDF::Element::GetBBox ( Rect out_bbox  ) 

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:
true if this is a graphical element and the bounding box can be calculated; false for non-graphical elements which don't have bounding box.
Parameters:
out_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.

Struct::SElement pdftron::PDF::Element::GetParentStructElement (  ) 

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

int pdftron::PDF::Element::GetStructMCID (  ) 

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.

bool pdftron::PDF::Element::IsOCVisible (  ) 

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

bool pdftron::PDF::Element::IsClippingPath (  ) 

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

bool pdftron::PDF::Element::IsStroked (  ) 

Returns:
true if the current path element should be stroked

bool pdftron::PDF::Element::IsFilled (  ) 

Returns:
true if the current path element should be filled

bool pdftron::PDF::Element::IsWindingFill (  ) 

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.

bool pdftron::PDF::Element::IsClipWindingFill (  ) 

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

const char* pdftron::PDF::Element::GetPathTypes (  ) 

Returns this path's array of path segment types.

Returns:
an array of PathSegmentType identifiers used to identify path data points returned by GetPathPoints(). You can call the GetPathTypesCount() method to determine the size of returned array.

int pdftron::PDF::Element::GetPathTypesCount (  ) 

Returns:
the number of path segment identifiers in this path's array of path segment ids.

const double* pdftron::PDF::Element::GetPathPoints (  ) 

Returns the array of points stored by the Path element.

Returns:
an array containing the path data points. A point may be on or off (off points are control points). The meaning of a point depends on associated id (or segment type) in the path segment type array. You can call the GetPointCount() method to determine the size of returned array.

int pdftron::PDF::Element::GetPointCount (  ) 

Returns:
the number of points in this path's array of data points.

void pdftron::PDF::Element::SetPathClip ( bool  clip  ) 

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

void pdftron::PDF::Element::SetPathStroke ( bool  stroke  ) 

Indicate whether the path should be stroked.

void pdftron::PDF::Element::SetPathFill ( bool  fill  ) 

Indicate whether the path should be filled.

void pdftron::PDF::Element::SetWindingFill ( bool  winding_rule  ) 

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

void pdftron::PDF::Element::SetClipWindingFill ( bool  winding_rule  ) 

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

void pdftron::PDF::Element::SetPathPoints ( const double *  in_points,
int  count 
)

Sets the array of points stored by the Path element.

Parameters:
in_points an array containing the path data points. A point may be on or off (i.e. off points are control points). The meaning of a point depends on associated id (or segment type) in the path segment type array.
count the size of the array of doubles.

void pdftron::PDF::Element::SetPathTypes ( const char *  in_seg_types,
int  count 
)

Sets this path's array of path segment types.

Parameters:
in_seg_types an array of PathSegmentType identifiers used to identify path data points that are set using SetPathPoints().
count the size of in_seg_types array.

SDF::Obj pdftron::PDF::Element::GetXObject (  ) 

Returns:
the SDF object of the Image/Form object.

Filters::Filter pdftron::PDF::Element::GetImageData (  )  const

Returns:
A stream (filter) containing decoded image data

int pdftron::PDF::Element::GetImageDataSize (  )  const

Returns:
the size of image data in bytes

Gdiplus::Bitmap* pdftron::PDF::Element::GetBitmap (  )  const

Convert PDF image to GDI+ Bitmap.

Returns:
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.
Note:
This method is available only on Windows platforms.

ColorSpace pdftron::PDF::Element::GetImageColorSpace (  )  const

Returns:
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.

int pdftron::PDF::Element::GetImageWidth (  )  const

Returns:
the width of the image, in samples.

int pdftron::PDF::Element::GetImageHeight (  )  const

Returns:
the height of the image, in samples.

SDF::Obj pdftron::PDF::Element::GetDecodeArray (  )  const

Returns:
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 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.

int pdftron::PDF::Element::GetBitsPerComponent (  )  const

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.

int pdftron::PDF::Element::GetComponentNum (  )  const

Returns:
the number of color components per sample.

bool pdftron::PDF::Element::IsImageMask (  )  const

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

bool pdftron::PDF::Element::IsImageInterpolate (  )  const

Returns:
a boolean indicating whether image interpolation is to be performed.

SDF::Obj pdftron::PDF::Element::GetMask (  )  const

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.

GState::RenderingIntent pdftron::PDF::Element::GetImageRenderingIntent (  )  const

Returns:
The color rendering intent to be used in rendering the image.

const UString* pdftron::PDF::Element::GetTextString (  ) 

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

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

const UChar* pdftron::PDF::Element::GetTextData (  ) 

Returns:
a pointer to the internal text buffer for this text element.
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.

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.

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

UInt32 pdftron::PDF::Element::GetTextDataSize (  ) 

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

Common::Matrix2D pdftron::PDF::Element::GetTextMatrix (  ) 

Returns:
a reference to the current text matrix (Tm).

CharIterator pdftron::PDF::Element::GetCharIterator (  ) 

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.

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

within 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 interface to access character information.

double pdftron::PDF::Element::GetTextLength (  ) 

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.

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.

double pdftron::PDF::Element::GetPosAdjustment (  ) 

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.
Note:
because CharIterator positioning information already accounts for TJ adjustments this method is rarely used.

void pdftron::PDF::Element::GetNewTextLineOffset ( double &  out_x,
double &  out_y 
)

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.

bool pdftron::PDF::Element::HasTextMatrix (  ) 

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.

void pdftron::PDF::Element::SetTextData ( const UChar text_data,
int  text_data_size 
)

Set the text data for the current e_text Element.

Parameters:
text_data a pointer to a buffer containing text.
text_data_size the size of the internal text buffer

void pdftron::PDF::Element::SetTextMatrix ( Common::Matrix2D mtx  ) 

Sets the text matrix for a text element.

Parameters:
mtx The new text matrix for this text element

void pdftron::PDF::Element::SetTextMatrix ( double  a,
double  b,
double  c,
double  d,
double  h,
double  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:
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.

void pdftron::PDF::Element::SetPosAdjustment ( double  adjust  ) 

Returns:
Set the horizontal adjustment factor (i.e. a number value within TJ array)
Note:
Positive values move the current text element backwards (along text direction). Negative values move the current text element forward (along text direction).

void pdftron::PDF::Element::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.

void pdftron::PDF::Element::SetNewTextLineOffset ( double  dx,
double  dy 
)

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

Shading pdftron::PDF::Element::GetShading (  ) 

Returns:
the SDF object of the Shading object.

SDF::Obj pdftron::PDF::Element::GetMCPropertyDict (  ) 

Returns:
a dictionary containing the property list or NULL if property dictionary is not present.
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.

SDF::Obj pdftron::PDF::Element::GetMCTag (  ) 

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


© 2002-2010 PDFTron Systems Inc.