pdftron::PDF::GState Class Reference

GState is a class that keeps track of a number of style attributes used to visually define graphical Elements. More...

#include <GState.h>

List of all members.

Public Types
enum	GStateAttribute {   e_transform = 0, e_rendering_intent, e_stroke_cs, e_stroke_color,   e_fill_cs, e_fill_color, e_line_width, e_line_cap,   e_line_join, e_flatness, e_miter_limit, e_dash_pattern,   e_char_spacing, e_word_spacing, e_horizontal_scale, e_leading,   e_font, e_font_size, e_text_render_mode, e_text_rise,   e_text_knockout, e_text_pos_offset, e_blend_mode, e_opacity_fill,   e_opacity_stroke, e_alpha_is_shape, e_soft_mask, e_smoothnes,   e_auto_stoke_adjust, e_stroke_overprint, e_fill_overprint, e_overprint_mode,   e_transfer_funct, e_BG_funct, e_UCR_funct, e_halftone,   e_null }
enum	LineCap { e_butt_cap = 0, e_round_cap, e_square_cap }
enum	LineJoin { e_miter_join = 0, e_round_join, e_bevel_join }
enum	TextRenderingMode {   e_fill_text = 0, e_stroke_text, e_fill_stroke_text, e_invisible_text,   e_fill_clip_text, e_stroke_clip_text, e_fill_stroke_clip_text, e_clip_text }
enum	RenderingIntent { e_absolute_colorimetric, e_relative_colorimetric, e_saturation, e_perceptual }
enum	BlendMode {   e_bl_compatible = 0, e_bl_normal, e_bl_multiply, e_bl_screen,   e_bl_difference, e_bl_darken, e_bl_lighten, e_bl_color_dodge,   e_bl_color_burn, e_bl_exclusion, e_bl_hard_light, e_bl_overlay,   e_bl_soft_light, e_bl_luminosity, e_bl_hue, e_bl_saturation,   e_bl_color }
Public Member Functions
	GState ()
	GState (const GState &c)
GState &	operator= (const GState &c)
Common::Matrix2D	GetTransform ()
	Returns: the transformation matrix for this element.
ColorSpace	GetStrokeColorSpace ()
	Returns: color space used for stroking
ColorSpace	GetFillColorSpace ()
	Returns: color space used for filling
ColorPt	GetStrokeColor ()
	Returns: a color value/point represented in the current stroke color space
SDF::Obj	GetStrokePattern ()
	Returns: the SDF pattern object of currently selected PatternColorSpace used for stroking.
ColorPt	GetFillColor ()
	Returns: a color value/point represented in the current fill color space
SDF::Obj	GetFillPattern ()
	Returns: the SDF pattern object of currently selected PatternColorSpace used for filling.
double	GetFlatness () const
	Returns: current value of flatness tolerance
LineCap	GetLineCap () const
	Returns: currently selected LineCap style
LineJoin	GetLineJoin () const
	Returns: currently selected LineJoin style
double	GetLineWidth () const
	Returns: the thickness of the line used to stroke a path.
double	GetMiterLimit () const
	Returns: current value of miter limit.
void	GetDashes (std::vector< double > &dashes) const
	Returns: The method fills the vector with an array of numbers representing the dash pattern
double	GetPhase () const
	Returns: the phase of the currently selected dash pattern.
double	GetCharSpacing () const
	Returns: currently selected character spacing.
double	GetWordSpacing () const
	Returns: currently selected word spacing
double	GetHorizontalScale () const
	Returns: currently selected horizontal scale
double	GetLeading () const
	Returns: currently selected leading parameter
Font	GetFont () const
	Returns: currently selected font
double	GetFontSize () const
	Returns: the font size
TextRenderingMode	GetTextRenderMode () const
	Returns: current text rendering mode.
double	GetTextRise () const
	Returns: current value of text rise
bool	IsTextKnockout () const
	Returns: a boolean flag that determines the text element is considered elementary objects for purposes of color compositing in the transparent imaging model.
RenderingIntent	GetRenderingIntent () const
	Returns: The color intent to be used for rendering the Element
BlendMode	GetBlendMode ()
	Returns: the current blend mode to be used in the transparent imaging model.
double	GetFillOpacity () const
	Returns: the opacity value for painting operations other than stroking.
double	GetStrokeOpacity () const
	Returns: opacity value for stroke painting operations for paths and glyph outlines.
bool	GetAISFlag () const
	Returns: the alpha source flag ('alpha is shape'), specifying whether the current soft mask and alpha constant are to be interpreted as shape values (true) or opacity values (false).
SDF::Obj	GetSoftMask ()
	Returns: Associated soft mask.
bool	GetStrokeOverprint () const
	Returns: whether overprint is enabled for stroke painting operations.
bool	GetFillOverprint () const
	Returns: whether overprint is enabled for fill painting operations.
int	GetOverprintMode () const
	Returns: the overprint mode used by this graphics state.
bool	GetAutoStrokeAdjust () const
	Returns: a flag specifying whether stroke adjustment is enabled in the graphics state.
double	GetSmoothnessTolerance () const
	Returns: the smoothness tolerance used to control the quality of smooth shading.
SDF::Obj	GetTransferFunct ()
	Returns: currently selected transfer function (NULL by default) used during color conversion process.
SDF::Obj	GetBlackGenFunct ()
	Returns: currently selected black-generation function (NULL by default) used during conversion between DeviceRGB and DeviceCMYK.
SDF::Obj	GetUCRFunct ()
	Returns: currently selected undercolor-removal function (NULL by default) used during conversion between DeviceRGB and DeviceCMYK.
SDF::Obj	GetHalftone ()
	Returns: currently selected halftone dictionary or stream (NULL by default).
void	SetTransform (const Common::Matrix2D &mtx)
	Set the transformation matrix associated with this element.
void	SetTransform (double a, double b, double c, double d, double h, double v)
	Sets the transformation matrix for this element.
void	Concat (const Common::Matrix2D &mtx)
	Concatenate the given matrix to the transformation matrix of this element.
void	Concat (double a, double b, double c, double d, double h, double v)
void	SetStrokeColorSpace (ColorSpace cs)
	Sets the color space used for stroking operations.
void	SetFillColorSpace (ColorSpace cs)
	Sets the color space used for filling operations.
void	SetStrokeColor (const ColorPt &c)
	Sets the color value/point used for stroking operations.
void	SetStrokeColor (SDF::Obj pattern)
	Set the stroke color to the given tiling pattern.
void	SetStrokeColor (SDF::Obj pattern, const ColorPt &c)
	Set the stroke color to the given uncolored tiling pattern.
void	SetFillColor (const ColorPt &c)
	Sets the color value/point used for filling operations.
void	SetFillColor (SDF::Obj pattern)
	Set the fill color to the given tiling pattern.
void	SetFillColor (SDF::Obj pattern, const ColorPt &c)
	Set the fill color to the given uncolored tiling pattern.
void	SetFlatness (double flatness)
	Sets the value of flatness tolerance.
void	SetLineCap (LineCap cap)
	Sets LineCap style property.
void	SetLineJoin (LineJoin join)
	Sets LineJoin style property.
void	SetLineWidth (double width)
	Sets the thickness of the line used to stroke a path.
void	SetMiterLimit (double miter_limit)
	Sets miter limit.
void	SetDashPattern (const std::vector< double > &dash_array, double phase)
	Sets the dash pattern used to stroke paths.
void	SetCharSpacing (double char_spacing)
	Sets character spacing.
void	SetWordSpacing (double word_spacing)
	Sets word spacing.
void	SetHorizontalScale (double hscale)
	Sets horizontal scale.
void	SetLeading (double leading)
	Sets the leading parameter.
void	SetFont (Font font, double font_sz)
	Sets the font and font size used to draw text.
void	SetTextRenderMode (TextRenderingMode rmode)
	Sets text rendering mode.
void	SetTextRise (double rise)
	Sets text rise.
void	SetTextKnockout (bool knockout)
	Mark the object as elementary for purposes of color compositing in the transparent imaging model.
void	SetRenderingIntent (RenderingIntent intent)
	Sets the color intent to be used for rendering the Element.
void	SetBlendMode (BlendMode BM)
	Sets the current blend mode to be used in the transparent imaging model.
void	SetFillOpacity (double ca)
	Sets the opacity value for painting operations other than stroking.
void	SetStrokeOpacity (double CA)
	Sets opacity value for stroke painting operations for paths and glyph outlines.
void	SetAISFlag (bool AIS)
	Specifies if the alpha is to be interpreted as a shape or opacity mask.
void	SetSoftMask (SDF::Obj SM)
	Sets the soft mask of the extended graphics state.
void	SetStrokeOverprint (bool OP)
	Specifies if overprint is enabled for stroke operations.
void	SetFillOverprint (bool op)
	Specifies if overprint is enabled for fill operations.
void	SetOverprintMode (int OPM)
	Sets the overprint mode.
void	SetAutoStrokeAdjust (bool SA)
	Specify whether to apply automatic stroke adjustment.
void	SetSmoothnessTolerance (double SM)
	Sets the smoothness tolerance used to control the quality of smooth shading.
void	SetBlackGenFunct (SDF::Obj BG)
	Sets black-generation function used during conversion between DeviceRGB and DeviceCMYK.
void	SetUCRFunct (SDF::Obj UCR)
	Sets undercolor-removal function used during conversion between DeviceRGB and DeviceCMYK.
void	SetTransferFunct (SDF::Obj TR)
	Sets transfer function used during color conversion process.
void	SetHalftone (SDF::Obj HT)
	Returns: currently selected halftone dictionary or stream (NULL by default).
Static Public Member Functions
static RenderingIntent	GetRenderingIntentType (const char *name)
	A utility function that maps a string representing a rendering intent to RenderingIntent type.

---

Detailed Description

GState is a class that keeps track of a number of style attributes used to visually define graphical Elements.

Each PDF::Element has an associated GState that can be used to query or set various graphics properties.

Note:

current clipping path is not tracked in the graphics state for efficiency reasons. In most cases tracking of the current clipping path is best left to the client.

---

Member Enumeration Documentation

enum pdftron::PDF::GState::GStateAttribute

Enumerator:

e_transform
e_rendering_intent
e_stroke_cs
e_stroke_color
e_fill_cs
e_fill_color
e_line_width
e_line_cap
e_line_join
e_flatness
e_miter_limit
e_dash_pattern
e_char_spacing
e_word_spacing
e_horizontal_scale
e_leading
e_font
e_font_size
e_text_render_mode
e_text_rise
e_text_knockout
e_text_pos_offset
e_blend_mode
e_opacity_fill
e_opacity_stroke
e_alpha_is_shape
e_soft_mask
e_smoothnes
e_auto_stoke_adjust
e_stroke_overprint
e_fill_overprint
e_overprint_mode
e_transfer_funct
e_BG_funct
e_UCR_funct
e_halftone
e_null

enum pdftron::PDF::GState::LineCap

Enumerator:

e_butt_cap
e_round_cap
e_square_cap

enum pdftron::PDF::GState::LineJoin

Enumerator:

e_miter_join
e_round_join
e_bevel_join

enum pdftron::PDF::GState::TextRenderingMode

Enumerator:

e_fill_text
e_stroke_text
e_fill_stroke_text
e_invisible_text
e_fill_clip_text
e_stroke_clip_text
e_fill_stroke_clip_text
e_clip_text

enum pdftron::PDF::GState::RenderingIntent

Enumerator:

e_absolute_colorimetric
e_relative_colorimetric
e_saturation
e_perceptual

enum pdftron::PDF::GState::BlendMode

Enumerator:

e_bl_compatible
e_bl_normal
e_bl_multiply
e_bl_screen
e_bl_difference
e_bl_darken
e_bl_lighten
e_bl_color_dodge
e_bl_color_burn
e_bl_exclusion
e_bl_hard_light
e_bl_overlay
e_bl_soft_light
e_bl_luminosity
e_bl_hue
e_bl_saturation
e_bl_color

---

Constructor & Destructor Documentation

pdftron::PDF::GState::GState

(

)

pdftron::PDF::GState::GState

(

const GState &

c

)

---

Member Function Documentation

GState& pdftron::PDF::GState::operator=

(

const GState &

c

)

Common::Matrix2D pdftron::PDF::GState::GetTransform

(

)

Returns:

the transformation matrix for this element.

Note:

If you are looking for a matrix that maps coordinates to the initial user space see Element::GetCTM().

ColorSpace pdftron::PDF::GState::GetStrokeColorSpace

(

)

Returns:

color space used for stroking

ColorSpace pdftron::PDF::GState::GetFillColorSpace

(

)

Returns:

color space used for filling

ColorPt pdftron::PDF::GState::GetStrokeColor

(

)

Returns:

a color value/point represented in the current stroke color space

SDF::Obj pdftron::PDF::GState::GetStrokePattern

(

)

Returns:

the SDF pattern object of currently selected PatternColorSpace used for stroking.

ColorPt pdftron::PDF::GState::GetFillColor

(

)

Returns:

a color value/point represented in the current fill color space

SDF::Obj pdftron::PDF::GState::GetFillPattern

(

)

Returns:

the SDF pattern object of currently selected PatternColorSpace used for filling.

double pdftron::PDF::GState::GetFlatness

(

)

const

Returns:

current value of flatness tolerance

Flatness is a number in the range 0 to 100; a value of 0 specifies the output device’s default flatness tolerance.

The flatness tolerance controls the maximum permitted distance in device pixels between the mathematically correct path and an approximation constructed from straight line segments.

LineCap pdftron::PDF::GState::GetLineCap

(

)

const

Returns:

currently selected LineCap style

The line cap style specifies the shape to be used at the ends of open sub-paths (and dashes, if any) when they are stroked.

LineJoin pdftron::PDF::GState::GetLineJoin

(

)

const

Returns:

currently selected LineJoin style

The line join style specifies the shape to be used at the corners of paths that are stroked.

double pdftron::PDF::GState::GetLineWidth

(

)

const

Returns:

the thickness of the line used to stroke a path.

Note:

A line width of 0 denotes the thinnest line that can be rendered at device resolution: 1 device pixel wide.

double pdftron::PDF::GState::GetMiterLimit

(

)

const

Returns:

current value of miter limit.

The miter limit imposes a maximum on the ratio of the miter length to the line width. When the limit is exceeded, the join is converted from a miter to a bevel.

void pdftron::PDF::GState::GetDashes

(

std::vector< double > &

dashes

)

const

Returns:

The method fills the vector with an array of numbers representing the dash pattern

The line dash pattern controls the pattern of dashes and gaps used to stroke paths. It is specified by a dash array and a dash phase. The dash array’s elements are numbers that specify the lengths of alternating dashes and gaps; the dash phase specifies the distance into the dash pattern at which to start the dash. The elements of both the dash array and the dash phase are expressed in user space units.

double pdftron::PDF::GState::GetPhase

(

)

const

Returns:

the phase of the currently selected dash pattern.

dash phase is expressed in user space units.

double pdftron::PDF::GState::GetCharSpacing

(

)

const

Returns:

currently selected character spacing.

The character spacing parameter is a number specified in unscaled text space units. When the glyph for each character in the string is rendered, the character spacing is added to the horizontal or vertical component of the glyph’s displacement, depending on the writing mode. See Section 5.2.1 in PDF Reference Manual for details.

double pdftron::PDF::GState::GetWordSpacing

(

)

const

Returns:

currently selected word spacing

Word spacing works the same way as character spacing, but applies only to the space character (char code 32). See Section 5.2.2 in PDF Reference Manual for details.

double pdftron::PDF::GState::GetHorizontalScale

(

)

const

Returns:

currently selected horizontal scale

The horizontal scaling parameter adjusts the width of glyphs by stretching or compressing them in the horizontal direction. Its value is specified as a percentage of the normal width of the glyphs, with 100 being the normal width. The scaling always applies to the horizontal coordinate in text space, independently of the writing mode. See Section 5.2.3 in PDF Reference Manual for details.

double pdftron::PDF::GState::GetLeading

(

)

const

Returns:

currently selected leading parameter

The leading parameter is measured in unscaled text space units. It specifies the vertical distance between the baselines of adjacent lines of text. See Section 5.2.4 in PDF Reference Manual for details.

Font pdftron::PDF::GState::GetFont

(

)

const

Returns:

currently selected font

double pdftron::PDF::GState::GetFontSize

(

)

const

Returns:

the font size

TextRenderingMode pdftron::PDF::GState::GetTextRenderMode

(

)

const

Returns:

current text rendering mode.

The text rendering mode determines whether showing text causes glyph outlines to be stroked, filled, used as a clipping boundary, or some combination of the three. See Section 5.2.5 in PDF Reference Manual for details..

double pdftron::PDF::GState::GetTextRise

(

)

const

Returns:

current value of text rise

Text rise specifies the distance, in unscaled text space units, to move the baseline up or down from its default location. Positive values of text rise move the baseline up

bool pdftron::PDF::GState::IsTextKnockout

(

)

const

Returns:

a boolean flag that determines the text element is considered elementary objects for purposes of color compositing in the transparent imaging model.

RenderingIntent pdftron::PDF::GState::GetRenderingIntent

(

)

const

Returns:

The color intent to be used for rendering the Element

static RenderingIntent pdftron::PDF::GState::GetRenderingIntentType

(

const char *

name

)

[static]

A utility function that maps a string representing a rendering intent to RenderingIntent type.

Returns:

The color rendering intent type matching the specified string

BlendMode pdftron::PDF::GState::GetBlendMode

(

)

Returns:

the current blend mode to be used in the transparent imaging model.

Corresponds to the /BM key within the ExtGState's dictionary.

double pdftron::PDF::GState::GetFillOpacity

(

)

const

Returns:

the opacity value for painting operations other than stroking.

Returns the value of the /ca key in the ExtGState dictionary. If the value is not found, the default value of 1 is returned.

double pdftron::PDF::GState::GetStrokeOpacity

(

)

const

Returns:

opacity value for stroke painting operations for paths and glyph outlines.

Returns the value of the /CA key in the ExtGState dictionary. If the value is not found, the default value of 1 is returned.

bool pdftron::PDF::GState::GetAISFlag

(

)

const

Returns:

the alpha source flag ('alpha is shape'), specifying whether the current soft mask and alpha constant are to be interpreted as shape values (true) or opacity values (false).

SDF::Obj pdftron::PDF::GState::GetSoftMask

(

)

Returns:

Associated soft mask.

NULL if the soft mask is not selected or SDF dictionary representing the soft mask otherwise.

bool pdftron::PDF::GState::GetStrokeOverprint

(

)

const

Returns:

whether overprint is enabled for stroke painting operations.

Corresponds to the /OP key within the ExtGState's dictionary.

bool pdftron::PDF::GState::GetFillOverprint

(

)

const

Returns:

whether overprint is enabled for fill painting operations.

Corresponds to the /op key within the ExtGState's dictionary.

int pdftron::PDF::GState::GetOverprintMode

(

)

const

Returns:

the overprint mode used by this graphics state.

Corresponds to the /OPM key within the ExtGState's dictionary.

bool pdftron::PDF::GState::GetAutoStrokeAdjust

(

)

const

Returns:

a flag specifying whether stroke adjustment is enabled in the graphics state.

Corresponds to the /SA key within the ExtGState's dictionary.

double pdftron::PDF::GState::GetSmoothnessTolerance

(

)

const

Returns:

the smoothness tolerance used to control the quality of smooth shading.

Corresponds to the /SM key within the ExtGState's dictionary. The allowable error (or tolerance) is expressed as a fraction of the range of the color component, from 0.0 to 1.0.

SDF::Obj pdftron::PDF::GState::GetTransferFunct

(

)

Returns:

currently selected transfer function (NULL by default) used during color conversion process.

A transfer function adjusts the values of color components to compensate for nonlinear response in an output device and in the human eye. Corresponds to the /TR key within the ExtGState's dictionary.

SDF::Obj pdftron::PDF::GState::GetBlackGenFunct

(

)

Returns:

currently selected black-generation function (NULL by default) used during conversion between DeviceRGB and DeviceCMYK.

Corresponds to the /BG key within the ExtGState's dictionary.

SDF::Obj pdftron::PDF::GState::GetUCRFunct

(

)

Returns:

currently selected undercolor-removal function (NULL by default) used during conversion between DeviceRGB and DeviceCMYK.

Corresponds to the /UCR key within the ExtGState's dictionary.

SDF::Obj pdftron::PDF::GState::GetHalftone

(

)

Returns:

currently selected halftone dictionary or stream (NULL by default).

Corresponds to the /HT key within the ExtGState's dictionary. Halftoning is a process by which continuous-tone colors are approximated on an output device that can achieve only a limited number of discrete colors.

void pdftron::PDF::GState::SetTransform

(

const Common::Matrix2D &

mtx

)

Set the transformation matrix associated with this element.

Parameters:

mtx

The new transformation for this text element.

Note:

in PDF associating a transformation matrix with an element ('cm' operator) will also affect all subsequent elements.

void pdftron::PDF::GState::SetTransform	(	double	a,
		double	b,
		double	c,
		double	d,
		double	h,
		double	v
	)

Sets the transformation matrix for this 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 pdftron::Common::Matrix2D class.

Parameters:

	a	- horizontal 'scaling' component of the new text matrix.
	b	- 'rotation' component of the new text matrix.
	c	- vertical 'scaling' component of the new text matrix.
	d	- 'rotation' 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::GState::Concat

(

const Common::Matrix2D &

mtx

)

Concatenate the given matrix to the transformation matrix of this element.

void pdftron::PDF::GState::Concat	(	double	a,
		double	b,
		double	c,
		double	d,
		double	h,
		double	v
	)

void pdftron::PDF::GState::SetStrokeColorSpace

(

ColorSpace

cs

)

Sets the color space used for stroking operations.

void pdftron::PDF::GState::SetFillColorSpace

(

ColorSpace

cs

)

Sets the color space used for filling operations.

void pdftron::PDF::GState::SetStrokeColor

(

const ColorPt &

c

)

Sets the color value/point used for stroking operations.

The color value must be represented in the currently selected color space used for stroking.

void pdftron::PDF::GState::SetStrokeColor

(

SDF::Obj

pattern

)

Set the stroke color to the given tiling pattern.

Parameters:

pattern

SDF pattern object.

Note:

The currently selected stroke color space must be Pattern color space.

void pdftron::PDF::GState::SetStrokeColor	(	SDF::Obj	pattern,
		const ColorPt &	c
	)

Set the stroke color to the given uncolored tiling pattern.

Parameters:

	SDF	pattern (PatternType = 1 and PaintType = 2) object.
	c	is a color in the pattern’s underlying color space.

Note:

The currently selected stroke color space must be Pattern color space.