JagPDF
Prev Up Home Next

4.3.  Classes

Class Canvas
Class Document
Class DocumentOutline
Class Font
Class Image
Class ImageDef
Class Page
Class Profile
Description

Canvas is a class which allows describing the appearance of pages and other graphical elements.

Synopsis
class Canvas
{
public:
  void alpha(Char const* op, Double alpha);
  void arc(Double cx, Double cy, Double rx, Double ry, Double start_angle, Double sweep_angle);
  void arc_to(Double x, Double y, Double rx, Double ry, Double angle, Int large_arc_flag,
              Int sweep_flag);
  void bezier_to(Double x1, Double y1, Double x2, Double y2, Double x3, Double y3);
  void bezier_to_1st_ctrlpt(Double x1, Double y1, Double x3, Double y3);
  void bezier_to_2nd_ctrlpt(Double x2, Double y2, Double x3, Double y3);
  void circle(Double x, Double y, Double radius);
  void color(Char const* op, Double ch1);
  void color(Char const* op, Double ch1, Double ch2, Double ch3);
  void color(Char const* op, Double ch1, Double ch2, Double ch3, Double ch4);
  void color_space(Char const* op, ColorSpace cs);
  void color_space_pattern(Char const* op);
  void color_space_pattern_uncolored(Char const* op, ColorSpace cs);
  void image(Image img, Double x, Double y);
  void line_cap(LineCapStyle style);
  void line_dash(UInt const* array_in, UInt length, UInt phase);
  void line_join(LineJoinStyle style);
  void line_miter_limit(Double limit);
  void line_to(Double x, Double y);
  void line_width(Double width);
  void move_to(Double x, Double y);
  void path_close();
  void path_paint(Char const* cmd);
  void pattern(Char const* op, Pattern patt);
  void pattern(Char const* op, Pattern patt, Double ch1);
  void pattern(Char const* op, Pattern patt, Double ch1, Double ch2, Double ch3);
  void pattern(Char const* op, Pattern patt, Double ch1, Double ch2, Double ch3, Double ch4);
  void rectangle(Double x, Double y, Double width, Double height);
  void rotate(Double alpha);
  void scale(Double sx, Double sy);
  void shading_apply(Pattern pattern);
  void skew(Double alpha, Double beta);
  void state_restore();
  void state_save();
  void text(Char const* start, Char const* end);
  void text(Char const* start, Char const* end, Double const* offsets, UInt offsets_length,
            Int const* positions, UInt positions_length);
  void text(Char const* txt_u);
  void text(Char const* txt_u, Double const* offsets, UInt offsets_length, Int const* positions,
            UInt positions_length);
  void text(Double x, Double y, Char const* start, Char const* end);
  void text(Double x, Double y, Char const* start, Char const* end, Double const* offsets,
            UInt offsets_length, Int const* positions, UInt positions_length);
  void text(Double x, Double y, Char const* txt_u);
  void text(Double x, Double y, Char const* txt_u, Double const* offsets, UInt offsets_length,
            Int const* positions, UInt positions_length);
  void text_character_spacing(Double spacing);
  void text_end();
  void text_font(Font font);
  void text_glyphs(Double x, Double y, UInt16 const* array_in, UInt length);
  void text_glyphs(Double x, Double y, UInt16 const* array_in, UInt length, Double const* offsets,
                   UInt offsets_length, Int const* positions, UInt positions_length);
  void text_horizontal_scaling(Double scaling);
  void text_rendering_mode(Char const* mode);
  void text_rise(Double rise);
  void text_start(Double x, Double y);
  void text_translate_line(Double tx, Double ty);
  void transform(Double a, Double b, Double c, Double d, Double e, Double f);
  void translate(Double tx, Double ty);
};
Methods

Canvas::alpha

[py]   alpha(op, alpha)
[c++]  void alpha(Char const* op, Double alpha);
[c]    jag_error jag_Canvas_alpha(jag_Canvas hobj, jag_Char const* op, jag_Double alpha);
[java] void alpha(String op, double alpha);
Effect: Sets the constant opacity. This value is stored in the graphics state and used in the transparent imaging model. Initial value: 1.0.

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations
alpha

constant opacity value

PDF version: 1.4

See: the PDF Reference, chapter Transparency | Specifying Transparency in PDF | Specifying Shape and Opacity | Constant Shape and Opacity

Canvas::arc

[py]   arc(cx, cy, rx, ry, start_angle, sweep_angle)
[c++]  void arc(Double cx, Double cy, Double rx, Double ry, Double start_angle,
                Double sweep_angle);
[c]    jag_error jag_Canvas_arc(jag_Canvas hobj, jag_Double cx, jag_Double cy,
                                jag_Double rx, jag_Double ry, jag_Double start_angle,
                                jag_Double sweep_angle);
[java] void arc(double cx, double cy, double rx, double ry, double start_angle,
                double sweep_angle);
Effect: Appends an elliptical arc to the current path. Begins a new subpath.

Parameters:

cx

the x center coordinate

cy

the y center coordinate

rx

the x radius

ry

the y radius

start_angle

start angle

sweep_angle

sweep angle

JagPDF version: 1.1

Canvas::arc_to

[py]   arc_to(x, y, rx, ry, angle, large_arc_flag, sweep_flag)
[c++]  void arc_to(Double x, Double y, Double rx, Double ry, Double angle,
                   Int large_arc_flag, Int sweep_flag);
[c]    jag_error jag_Canvas_arc_to(jag_Canvas hobj, jag_Double x, jag_Double y,
                                   jag_Double rx, jag_Double ry, jag_Double angle,
                                   jag_Int large_arc_flag, jag_Int sweep_flag);
[java] void arc_to(double x, double y, double rx, double ry, double angle,
                   int large_arc_flag, int sweep_flag);
Effect: Appends an elliptical arc to the current path. The arc extends from the current point to point (x, y).

Parameters:

x

the x endpoint coordinate

y

the y endpoint coordinate

rx

the x radius

ry

the y radius

angle

angle from the x-axis of the current coordinate system to the x-axis of the ellipse

large_arc_flag

0 - an arc spanning less than or equal to 180 degrees is chosen, or 1 - an arc spanning greater than 180 degrees is chosen

sweep_flag

0 - the line joining center to arc sweeps through decreasing angles, or 1 - it sweeps through increasing angles

JagPDF version: 1.1

Canvas::bezier_to

[py]   bezier_to(x1, y1, x2, y2, x3, y3)
[c++]  void bezier_to(Double x1, Double y1, Double x2, Double y2, Double x3, Double y3);
[c]    jag_error jag_Canvas_bezier_to(jag_Canvas hobj, jag_Double x1, jag_Double y1,
                                      jag_Double x2, jag_Double y2, jag_Double x3,
                                      jag_Double y3);
[java] void bezier_to(double x1, double y1, double x2, double y2, double x3, double y3);
Effect: Appends a cubic Bezier curve to the current path. The curve extends from the current point to point (x3, y3), using (x1, y1) and (x2, y2) as the Bezier control points. The new current point is (x3, y3).

See:

Canvas::bezier_to_1st_ctrlpt

[py]   bezier_to_1st_ctrlpt(x1, y1, x3, y3)
[c++]  void bezier_to_1st_ctrlpt(Double x1, Double y1, Double x3, Double y3);
[c]    jag_error jag_Canvas_bezier_to_1st_ctrlpt(jag_Canvas hobj, jag_Double x1,
                                                 jag_Double y1, jag_Double x3,
                                                 jag_Double y3);
[java] void bezier_to_1st_ctrlpt(double x1, double y1, double x3, double y3);
Effect: Appends a cubic Bezier curve to the current path. The curve extends from the current point to point (x3, y3), using (x1, y1) and (x3, y3) as the Bezier control points. The new current point is (x3, y3).

See:

Canvas::bezier_to_2nd_ctrlpt

[py]   bezier_to_2nd_ctrlpt(x2, y2, x3, y3)
[c++]  void bezier_to_2nd_ctrlpt(Double x2, Double y2, Double x3, Double y3);
[c]    jag_error jag_Canvas_bezier_to_2nd_ctrlpt(jag_Canvas hobj, jag_Double x2,
                                                 jag_Double y2, jag_Double x3,
                                                 jag_Double y3);
[java] void bezier_to_2nd_ctrlpt(double x2, double y2, double x3, double y3);
Effect: Appends a cubic Bezier curve to the current path. The curve extends from the current point to point (x3, y3), using the current point and (x2, y2) as the Bezier control points. The new current point is (x3, y3).

See:

Canvas::circle

[py]   circle(x, y, radius)
[c++]  void circle(Double x, Double y, Double radius);
[c]    jag_error jag_Canvas_circle(jag_Canvas hobj, jag_Double x, jag_Double y,
                                   jag_Double radius);
[java] void circle(double x, double y, double radius);
Effect: Appends a circle to the current path. Begins a new subpath.

Parameters:

x

the x coordinate of the circle center

y

the y coordinate of the circle center

radius

circle radius (user space units)

See: the PDF Reference, chapter Graphics | Path Construction and Painting

Canvas::color

[py]   color(op, ch1)
[c++]  void color(Char const* op, Double ch1);
[c]    jag_error jag_Canvas_color1(jag_Canvas hobj, jag_Char const* op, jag_Double ch1);
[java] void color(String op, double ch1);
Effect: Sets the current color for painting operations.

Precondition: The current color space has one color component (e.g. DeviceGray, CalGray, Indexed).

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations
ch1

color value

See:

Canvas::color

[py]   color(op, ch1, ch2, ch3)
[c++]  void color(Char const* op, Double ch1, Double ch2, Double ch3);
[c]    jag_error jag_Canvas_color3(jag_Canvas hobj, jag_Char const* op, jag_Double ch1,
                                   jag_Double ch2, jag_Double ch3);
[java] void color(String op, double ch1, double ch2, double ch3);
Effect: Sets the current color for painting operations.

Precondition: The current color space has three color components (e.g. DeviceRGB, CalRGB, Lab).

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations
ch1

value of the 1st color component

ch2

value of the 2nd color component

ch3

value of the 3rd color component

See:

Canvas::color

[py]   color(op, ch1, ch2, ch3, ch4)
[c++]  void color(Char const* op, Double ch1, Double ch2, Double ch3, Double ch4);
[c]    jag_error jag_Canvas_color4(jag_Canvas hobj, jag_Char const* op, jag_Double ch1,
                                   jag_Double ch2, jag_Double ch3, jag_Double ch4);
[java] void color(String op, double ch1, double ch2, double ch3, double ch4);
Effect: Sets the current color for painting operations.

Precondition: The current color space has four color components (e.g. DeviceCMYK).

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations
ch1

value of the 1st color component

ch2

value of the 2nd color component

ch3

value of the 3rd color component

ch4

value of the 4th color component

See:

Canvas::color_space

[py]   color_space(op, cs)
[c++]  void color_space(Char const* op, ColorSpace cs);
[c]    jag_error jag_Canvas_color_space(jag_Canvas hobj, jag_Char const* op,
                                        jag_ColorSpace cs);
[java] void color_space(String op, ColorSpace cs);
Effect: Sets the current color space. The current color space is maintained in the graphics state.

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations
cs

it can be either one of the predefined color spaces:

  • CS_DEVICE_GRAY
  • CS_DEVICE_RGB
  • CS_DEVICE_CMYK

or a color space registered by color_space_load()

See: the PDF Reference, chapter Graphics | Color Spaces

Canvas::color_space_pattern

[py]   color_space_pattern(op)
[c++]  void color_space_pattern(Char const* op);
[c]    jag_error jag_Canvas_color_space_pattern(jag_Canvas hobj, jag_Char const* op);
[java] void color_space_pattern(String op);
Effect: Sets the pattern color space as the current color space. Can be used for colored tiling patterns or shading patterns.

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations

JagPDF version: 1.1

See:

Canvas::color_space_pattern_uncolored

[py]   color_space_pattern_uncolored(op, cs)
[c++]  void color_space_pattern_uncolored(Char const* op, ColorSpace cs);
[c]    jag_error jag_Canvas_color_space_pattern_uncolored(jag_Canvas hobj,
                                                          jag_Char const* op,
                                                          jag_ColorSpace cs);
[java] void color_space_pattern_uncolored(String op, ColorSpace cs);
Effect: Sets the pattern color space as the current color space. Can be used for uncolored tiling patterns.

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations
cs

the underlying color space

JagPDF version: 1.1

See:

Canvas::image

[py]   image(img, x, y)
[c++]  void image(Image img, Double x, Double y);
[c]    jag_error jag_Canvas_image(jag_Canvas hobj, jag_Image img, jag_Double x,
                                  jag_Double y);
[java] void image(Image img, double x, double y);
Effect: Paints an image. An image handle can be obtained by registering an image.

Parameters:

img

image

x

the x coordinate of lower-left corner

y

the y coordinate of lower-left corner

See:

Canvas::line_cap

[py]   line_cap(style)
[c++]  void line_cap(LineCapStyle style);
[c]    jag_error jag_Canvas_line_cap(jag_Canvas hobj, jag_LineCapStyle style);
[java] void line_cap(LineCapStyle style);
Effect: Specifies the shape to be used at the end of open subpaths. Initial value: LINE_CAP_BUTT.

Parameters:

style
  • LINE_CAP_BUTT
  • LINE_CAP_ROUND
  • LINE_CAP_SQUARE

See: the PDF Reference, chapter Graphics | Graphics State | Details of Graphics State Parameters | Line Cap Style

Canvas::line_dash

[py]   line_dash(array_in, phase)
[c++]  void line_dash(UInt const* array_in, UInt length, UInt phase);
[c]    jag_error jag_Canvas_line_dash(jag_Canvas hobj, jag_UInt const* array_in,
                                      jag_UInt length, jag_UInt phase);
[java] void line_dash(long[] array_in, long length, long phase);
Effect: Controls the pattern of dashes and gaps used to stroke paths. Initial value: a solid line.

Parameters:

array_in

dash array

length

length of the dash array

phase

dash phase

See: the PDF Reference, chapter Graphics | Graphics State | Details of Graphics State Parameters | Line Dash Pattern

Canvas::line_join

[py]   line_join(style)
[c++]  void line_join(LineJoinStyle style);
[c]    jag_error jag_Canvas_line_join(jag_Canvas hobj, jag_LineJoinStyle style);
[java] void line_join(LineJoinStyle style);
Effect: Specifies the shape to be used at corners of the paths that are stroked. Initial value: LINE_JOIN_MITTER.

Parameters:

style
  • LINE_JOIN_MITER
  • LINE_JOIN_ROUND
  • LINE_JOIN_BEVEL

See: the PDF Reference, chapter Graphics | Graphics State | Details of Graphics State Parameters | Line Join Style

Canvas::line_miter_limit

[py]   line_miter_limit(limit)
[c++]  void line_miter_limit(Double limit);
[c]    jag_error jag_Canvas_line_miter_limit(jag_Canvas hobj, jag_Double limit);
[java] void line_miter_limit(double limit);
Effect: Sets the mitter for line joins. Initial value: 10.0, for a miter cutoff below approximately 11.5 degrees.

See: the PDF Reference, chapter Graphics | Graphics State | Details of Graphics State Parameters | Miter Limit

Canvas::line_to

[py]   line_to(x, y)
[c++]  void line_to(Double x, Double y);
[c]    jag_error jag_Canvas_line_to(jag_Canvas hobj, jag_Double x, jag_Double y);
[java] void line_to(double x, double y);
Effect: Appends a straight line segment from the current point to the point (x, y). The new current point is (x, y).

Precondition: Path construction has already started.

See: the PDF Reference, chapter Graphics | Path Construction and Painting

Canvas::line_width

[py]   line_width(width)
[c++]  void line_width(Double width);
[c]    jag_error jag_Canvas_line_width(jag_Canvas hobj, jag_Double width);
[java] void line_width(double width);
Effect: Sets the thickness of a line used to stroke a path. Initial value: 1.0.

Parameters:

width

non-negative number expressed in user space units

See: the PDF Reference, chapter Graphics | Graphics State | Details of Graphics State Parameters | Line Width

Canvas::move_to

[py]   move_to(x, y)
[c++]  void move_to(Double x, Double y);
[c]    jag_error jag_Canvas_move_to(jag_Canvas hobj, jag_Double x, jag_Double y);
[java] void move_to(double x, double y);
Effect: Begins a new subpath. Moves the current point to coordinates (x, y), omits any connecting line segment. If the previous path construction operator was also move_to(), the new move_to() overrides it.

See: the PDF Reference, chapter Graphics | Path Construction and Painting

Canvas::path_close

[py]   path_close()
[c++]  void path_close();
[c]    jag_error jag_Canvas_path_close(jag_Canvas hobj);
[java] void path_close();
Effect: Closes the current subpath by appending a straight line segment. The segment starts in the current point and ends in the starting point of the subpath. If the current subpath is already closed, path_close() does nothing. This method terminates the current subpath.

Appending another segment to the current path begins a new subpath,even if the new segment begins at the endpoint reached by path_close().

See: the PDF Reference, chapter Graphics | Path Construction and Painting

Canvas::path_paint

[py]   path_paint(cmd)
[c++]  void path_paint(Char const* cmd);
[c]    jag_error jag_Canvas_path_paint(jag_Canvas hobj, jag_Char const* cmd);
[java] void path_paint(String cmd);
Effect:

Ends the current path. The manner in which is the current path ended is specified by a string comprising of a meaningful combination of the following letters:

  • 's' stroke
  • 'f' fill - nonzero winding
  • 'F' fill - even odd
  • 'c' close
  • 'w' clip - nonzero winding
  • 'W' clip - even odd

An empty string discards the current path.

If a clipping operation is specified along with a painting operation, it does not alter the clipping path for the painting operation. After the path has been painted, the clipping path in the graphics state is set to the intersection of the current clipping path and the newly constructed path.

See: the PDF Reference, chapter Graphics | Path Construction and Painting

Canvas::pattern

[py]   pattern(op, patt)
[c++]  void pattern(Char const* op, Pattern patt);
[c]    jag_error jag_Canvas_pattern(jag_Canvas hobj, jag_Char const* op, jag_Pattern patt);
[java] void pattern(String op, Pattern patt);
Effect: Sets the current pattern for painting operations. Either a shading pattern or a colored tiling pattern can be set with this function.

Precondition: The current color space was established by color_space_pattern().

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations
patt

shading pattern or colored tiling pattern

JagPDF version: 1.1

See:

Canvas::pattern

[py]   pattern(op, patt, ch1)
[c++]  void pattern(Char const* op, Pattern patt, Double ch1);
[c]    jag_error jag_Canvas_pattern1(jag_Canvas hobj, jag_Char const* op, jag_Pattern patt,
                                     jag_Double ch1);
[java] void pattern(String op, Pattern patt, double ch1);
Effect: Sets the current pattern for painting operations. Only an uncolored tiling pattern can be set with this function.

Precondition: The current color space was established by color_space_pattern_uncolored() with the underlying color space having one color component.

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations
patt

uncolored tiling pattern

ch1

value of the first color component

JagPDF version: 1.1

See:

Canvas::pattern

[py]   pattern(op, patt, ch1, ch2, ch3)
[c++]  void pattern(Char const* op, Pattern patt, Double ch1, Double ch2, Double ch3);
[c]    jag_error jag_Canvas_pattern3(jag_Canvas hobj, jag_Char const* op, jag_Pattern patt,
                                     jag_Double ch1, jag_Double ch2, jag_Double ch3);
[java] void pattern(String op, Pattern patt, double ch1, double ch2, double ch3);
Effect: Sets the current pattern for painting operations. Only an uncolored tiling pattern can be set with this function.

Precondition: The current color space was established by color_space_pattern_uncolored() with the underlying color space having three color components.

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations
patt

uncolored tiling pattern

ch1

value of the first color component

ch2

value of the second color component

ch3

value of the third color component

JagPDF version: 1.1

See:

Canvas::pattern

[py]   pattern(op, patt, ch1, ch2, ch3, ch4)
[c++]  void pattern(Char const* op, Pattern patt, Double ch1, Double ch2, Double ch3,
                    Double ch4);
[c]    jag_error jag_Canvas_pattern4(jag_Canvas hobj, jag_Char const* op, jag_Pattern patt,
                                     jag_Double ch1, jag_Double ch2, jag_Double ch3,
                                     jag_Double ch4);
[java] void pattern(String op, Pattern patt, double ch1, double ch2, double ch3,
                    double ch4);
Effect: Sets the current pattern for painting operations. Only an uncolored tiling pattern can be set with this function.

Precondition: The current color space was established by color_space_pattern_uncolored() with the underlying color space having four color components.

Parameters:

op

specifies painting operations

  • 'f' use for filling operations
  • 's' use for stroking operations
patt

uncolored tiling pattern

ch1

value of the first color component

ch2

value of the second color component

ch3

value of the third color component

ch4

value of the fourth color component

JagPDF version: 1.1

See:

Canvas::rectangle

[py]   rectangle(x, y, width, height)
[c++]  void rectangle(Double x, Double y, Double width, Double height);
[c]    jag_error jag_Canvas_rectangle(jag_Canvas hobj, jag_Double x, jag_Double y,
                                      jag_Double width, jag_Double height);
[java] void rectangle(double x, double y, double width, double height);
Effect: Appends a rectangle to the current path as a complete subpath. Begins a new subpath.

Parameters:

x

the x coordinate of lower-left corner

y

the y coordinate of lower-left corner

width

rectangle width (user space units)

height

rectangle height (user space units)

See: the PDF Reference, chapter Graphics | Path Construction and Painting

Canvas::rotate

[py]   rotate(alpha)
[c++]  void rotate(Double alpha);
[c]    jag_error jag_Canvas_rotate(jag_Canvas hobj, jag_Double alpha);
[java] void rotate(double alpha);
Effect: Rotates the canvas coordinate space axes counterclockwise around the origin. This is the same as transform(cos(a), sin(a), -sin(a), cons(a), 0, 0).

Parameters:

alpha

angle in radians

See: the PDF Reference, chapter Graphics | Coordinate Systems | Common Transformations

Canvas::scale

[py]   scale(sx, sy)
[c++]  void scale(Double sx, Double sy);
[c]    jag_error jag_Canvas_scale(jag_Canvas hobj, jag_Double sx, jag_Double sy);
[java] void scale(double sx, double sy);
Effect: Scales the units of the canvas coordinate space by (sx, sy). This is the same as transform(sx, 0, 0, sy, 0, 0).

See: the PDF Reference, chapter Graphics | Coordinate Systems | Common Transformations

Canvas::shading_apply

[py]   shading_apply(pattern)
[c++]  void shading_apply(Pattern pattern);
[c]    jag_error jag_Canvas_shading_apply(jag_Canvas hobj, jag_Pattern pattern);
[java] void shading_apply(Pattern pattern);
Effect: Applies the shading pattern to the current clipping path. Uses the current user space as the pattern space, the pattern matrix is ignored. It does not alter the current graphics state in any way.

Parameters:

pattern

shading pattern

PDF version: 1.3

JagPDF version: 1.1

See:

Canvas::skew

[py]   skew(alpha, beta)
[c++]  void skew(Double alpha, Double beta);
[c]    jag_error jag_Canvas_skew(jag_Canvas hobj, jag_Double alpha, jag_Double beta);
[java] void skew(double alpha, double beta);
Effect: Skews canvas coordinate system axes. This is the same as transform(1, tan(a), tan(b), 1, 0, 0).

Parameters:

alpha

skews the x axis

beta

skews the y axis

See: the PDF Reference, chapter Graphics | Coordinate Systems | Common Transformations

Canvas::state_restore

[py]   state_restore()
[c++]  void state_restore();
[c]    jag_error jag_Canvas_state_restore(jag_Canvas hobj);
[java] void state_restore();
Effect: Restores the graphics state.

Precondition: The graphics state was previously saved with state_save().

See: the PDF Reference, chapter Graphics | Graphics State | Graphics State Stack.

Canvas::state_save

[py]   state_save()
[c++]  void state_save();
[c]    jag_error jag_Canvas_state_save(jag_Canvas hobj);
[java] void state_save();
Effect: Saves the current graphics state. Can be restored later by calling state_restore(). For each state_save() there must be a matching state_restore(). The graphics stack can be saved/restored hierarchically.

See: the PDF Reference, chapter Graphics | Graphics State | Graphics State Stack.

Canvas::text

[py]   n/a
[c++]  void text(Char const* start, Char const* end);
[c]    jag_error jag_Canvas_text_r(jag_Canvas hobj, jag_Char const* start,
                                   jag_Char const* end);
[java] n/a
Effect: Shows a text. Available only in C/C++.

Precondition: A text object has been started.

Parameters:

start

points to the first byte of the string

end

points one byte past the last byte of the string

Canvas::text

[py]   n/a
[c++]  void text(Char const* start, Char const* end, Double const* offsets,
                 UInt offsets_length, Int const* positions, UInt positions_length);
[c]    jag_error jag_Canvas_text_ro(jag_Canvas hobj, jag_Char const* start,
                                    jag_Char const* end, jag_Double const* offsets,
                                    jag_UInt offsets_length, jag_Int const* positions,
                                    jag_UInt positions_length);
[java] n/a
Effect: Shows a text. Available only in C/C++.

Precondition: A text object has been started.

Parameters:

start

points to the first byte of the string

end

points one byte past the last byte of the string

offsets

glyph offsets expressed in glyph space (i.e. in thousandths of a unit of text space).

offsets_length

number of offsets

positions

associates glyph offsets with indices in txt_u

positions_length

number of positions

Canvas::text

[py]   text(txt_u)
[c++]  void text(Char const* txt_u);
[c]    jag_error jag_Canvas_text(jag_Canvas hobj, jag_Char const* txt_u);
[java] void text(String txt_u);
Effect: Shows a text.

Precondition: A text object has been started.

Parameters:

txt_u

zero terminated string

Canvas::text

[py]   text(txt_u, offsets, positions)
[c++]  void text(Char const* txt_u, Double const* offsets, UInt offsets_length,
                 Int const* positions, UInt positions_length);
[c]    jag_error jag_Canvas_text_o(jag_Canvas hobj, jag_Char const* txt_u,
                                   jag_Double const* offsets, jag_UInt offsets_length,
                                   jag_Int const* positions, jag_UInt positions_length);
[java] void text(String txt_u, double[] offsets, long offsets_length,
                 int[] positions, long positions_length);
Effect: Shows a text with custom positioned glyphs.

Precondition: A text object has been started.

Parameters:

txt_u

zero terminated string

offsets

glyph offsets expressed in glyph space (i.e. in thousandths of a unit of text space).

offsets_length

number of offsets

positions

associates glyph offsets with glyph indices in txt_u

positions_length

number of positions

Canvas::text

[py]   n/a
[c++]  void text(Double x, Double y, Char const* start, Char const* end);
[c]    jag_error jag_Canvas_text_simple_r(jag_Canvas hobj, jag_Double x, jag_Double y,
                                          jag_Char const* start, jag_Char const* end);
[java] n/a
Effect: Shows a text. Available only in C/C++.

Precondition: A text object has not been started.

Parameters:

x

the x baseline coordinate

y

the y baseline coordinate

start

points to the first byte of the string

end

points one byte past the last byte of the string

Canvas::text

[py]   n/a
[c++]  void text(Double x, Double y, Char const* start, Char const* end,
                 Double const* offsets, UInt offsets_length, Int const* positions,
                 UInt positions_length);
[c]    jag_error jag_Canvas_text_simple_ro(jag_Canvas hobj, jag_Double x, jag_Double y,
                                           jag_Char const* start, jag_Char const* end,
                                           jag_Double const* offsets,
                                           jag_UInt offsets_length,
                                           jag_Int const* positions,
                                           jag_UInt positions_length);
[java] n/a
Effect: Shows a text. Available only in C/C++.

Precondition: A text object has not been started.

Parameters:

x

the x baseline coordinate

y

the y baseline coordinate

start

points to the first byte of the string

end

points one byte past the last byte of the string

offsets

glyph offsets expressed in glyph space (i.e. in thousandths of a unit of text space).

offsets_length

number of offsets

positions

associates glyph offsets with indices in txt_u

positions_length

number of positions

Canvas::text

[py]   text(x, y, txt_u)
[c++]  void text(Double x, Double y, Char const* txt_u);
[c]    jag_error jag_Canvas_text_simple(jag_Canvas hobj, jag_Double x, jag_Double y,
                                        jag_Char const* txt_u);
[java] void text(double x, double y, String txt_u);
Effect: Shows a text.

Precondition: A text object has not been started.

Parameters:

x

the x baseline coordinate

y

the y baseline coordinate

txt_u

zero terminated string

Canvas::text

[py]   text(x, y, txt_u, offsets, positions)
[c++]  void text(Double x, Double y, Char const* txt_u, Double const* offsets,
                 UInt offsets_length, Int const* positions, UInt positions_length);
[c]    jag_error jag_Canvas_text_simple_o(jag_Canvas hobj, jag_Double x, jag_Double y,
                                          jag_Char const* txt_u, jag_Double const* offsets,
                                          jag_UInt offsets_length,
                                          jag_Int const* positions,
                                          jag_UInt positions_length);
[java] void text(double x, double y, String txt_u, double[] offsets,
                 long offsets_length, int[] positions, long positions_length);
Effect: Shows a text with custom positioned glyphs.

Precondition: A text object has not been started.

Parameters:

x

the x baseline coordinate

y

the y baseline coordinate

txt_u

zero terminated string

offsets

glyph offsets expressed in glyph space (i.e. in thousandths of a unit of text space).

offsets_length

number of offsets

positions

associates glyph offsets with glyph indices in txt_u

positions_length

number of positions

Canvas::text_character_spacing

[py]   text_character_spacing(spacing)
[c++]  void text_character_spacing(Double spacing);
[c]    jag_error jag_Canvas_text_character_spacing(jag_Canvas hobj, jag_Double spacing);
[java] void text_character_spacing(double spacing);
Effect: Sets the character spacing. It is a number expressed in unscaled text space units. Initial value: 0.

See: the PDF Reference, chapter Text | Text State Parameters and Operators | Character Spacing

Canvas::text_end

[py]   text_end()
[c++]  void text_end();
[c]    jag_error jag_Canvas_text_end(jag_Canvas hobj);
[java] void text_end();
Effect: Ends a text object.

Precondition: A text object has been started.

See: Text Object

Canvas::text_font

[py]   text_font(font)
[c++]  void text_font(Font font);
[c]    jag_error jag_Canvas_text_font(jag_Canvas hobj, jag_Font font);
[java] void text_font(Font font);
Effect: Sets the current font used for showing text. It is reset to a default value at the beginning of each page.

Canvas::text_glyphs

[py]   text_glyphs(x, y, array_in)
[c++]  void text_glyphs(Double x, Double y, UInt16 const* array_in, UInt length);
[c]    jag_error jag_Canvas_text_glyphs(jag_Canvas hobj, jag_Double x, jag_Double y,
                                        jag_UInt16 const* array_in, jag_UInt length);
[java] void text_glyphs(double x, double y, int[] array_in, long length);
Effect: Shows a text specified by glyph indices.

Precondition: A text object has not been started.

Parameters:

x

the x baseline coordinate

y

the y baseline coordinate

array_in

array of glyph indices

length

number of glyphs to show

JagPDF version: 1.4

Canvas::text_glyphs

[py]   text_glyphs(x, y, array_in, offsets, positions)
[c++]  void text_glyphs(Double x, Double y, UInt16 const* array_in, UInt length,
                        Double const* offsets, UInt offsets_length, Int const* positions,
                        UInt positions_length);
[c]    jag_error jag_Canvas_text_glyphs_o(jag_Canvas hobj, jag_Double x, jag_Double y,
                                          jag_UInt16 const* array_in, jag_UInt length,
                                          jag_Double const* offsets,
                                          jag_UInt offsets_length,
                                          jag_Int const* positions,
                                          jag_UInt positions_length);
[java] void text_glyphs(double x, double y, int[] array_in, long length,
                        double[] offsets, long offsets_length, int[] positions,
                        long positions_length);
Effect: Shows a text specified by glyph indices.

Precondition: A text object has not been started.

Parameters:

x

the x baseline coordinate

y

the y baseline coordinate

array_in

array of glyph indices

length

number of glyphs to show

offsets

glyph offsets expressed in glyph space (i.e. in thousandths of a unit of text space).

offsets_length

number of offsets

positions

associates glyph offsets with glyphs in array_in

positions_length

number of positions

JagPDF version: 1.4

Canvas::text_horizontal_scaling

[py]   text_horizontal_scaling(scaling)
[c++]  void text_horizontal_scaling(Double scaling);
[c]    jag_error jag_Canvas_text_horizontal_scaling(jag_Canvas hobj, jag_Double scaling);
[java] void text_horizontal_scaling(double scaling);
Effect: Sets the text horizontal scaling. It is a number specifying the percentage of the normal width of the glyphs. Initial value: 100 (normal width).

See: the PDF Reference, chapter Text | Text State Parameters and Operators | Horizontal Scaling

Canvas::text_rendering_mode

[py]   text_rendering_mode(mode)
[c++]  void text_rendering_mode(Char const* mode);
[c]    jag_error jag_Canvas_text_rendering_mode(jag_Canvas hobj, jag_Char const* mode);
[java] void text_rendering_mode(String mode);
Effect: Sets the text rendering mode.

Parameters:

mode

A meaningful combination of the following letters:

  • 's' stroke
  • 'f' fill
  • 'c' clip
  • 'i' invisible

Initial value: 'f'

See: the PDF Reference, chapter Text | Text State Parameters and Operators | Text Rendering Mode

Canvas::text_rise

[py]   text_rise(rise)
[c++]  void text_rise(Double rise);
[c]    jag_error jag_Canvas_text_rise(jag_Canvas hobj, jag_Double rise);
[java] void text_rise(double rise);
Effect: Sets the text rise. It is a number expressed in unscaled text units. Initial value: 0

See: the PDF Reference, chapter Text | Text State Parameters and Operators | Text Rise

Canvas::text_start

[py]   text_start(x, y)
[c++]  void text_start(Double x, Double y);
[c]    jag_error jag_Canvas_text_start(jag_Canvas hobj, jag_Double x, jag_Double y);
[java] void text_start(double x, double y);
Effect: Starts a text object.

Precondition: A text object has not been started.

See: Text Object

Canvas::text_translate_line

[py]   text_translate_line(tx, ty)
[c++]  void text_translate_line(Double tx, Double ty);
[c]    jag_error jag_Canvas_text_translate_line(jag_Canvas hobj, jag_Double tx,
                                                jag_Double ty);
[java] void text_translate_line(double tx, double ty);
Effect: Moves to the start of the next line. Offsets from the start of the current line by (tx, ty). tx and ty are numbers expressed in scaled text space units. More precisely, this operation performs the following assignment

text_matrix = text_line_matrix = [1 0 0 1 tx ty * text_line_matrix]

Precondition: A text object has been started.

Canvas::transform

[py]   transform(a, b, c, d, e, f)
[c++]  void transform(Double a, Double b, Double c, Double d, Double e, Double f);
[c]    jag_error jag_Canvas_transform(jag_Canvas hobj, jag_Double a, jag_Double b,
                                      jag_Double c, jag_Double d, jag_Double e,
                                      jag_Double f);
[java] void transform(double a, double b, double c, double d, double e, double f);
Effect: Transforms the canvas coordinate space. This is a most general transformation. Parameters a-f represents a transformation matrix.

See: the PDF Reference, chapter Graphics | Coordinate Systems | Common Transformations

Canvas::translate

[py]   translate(tx, ty)
[c++]  void translate(Double tx, Double ty);
[c]    jag_error jag_Canvas_translate(jag_Canvas hobj, jag_Double tx, jag_Double ty);
[java] void translate(double tx, double ty);
Effect: Translates the origin of the canvas coordinate space by (tx, ty). This is the same as transform(1, 0, 0, 1, tx, ty).

See: the PDF Reference, chapter Graphics | Coordinate Systems | Common Transformations

Description

Represents a PDF document. Instances of this class are reference counted.

Synopsis
class Document
{
public:
  Canvas canvas_create() const;
  ColorSpace color_space_load(Char const* spec);
  Destination destination_define(Char const* dest);
  void destination_define_reserved(Destination id, Char const* dest);
  Destination destination_reserve();
  void finalize();
  Font font_load(Char const* fspec);
  Function function_2_load(Char const* fun);
  Function function_3_load(Char const* fun, Function const* array_in, UInt length);
  Function function_4_load(Char const* fun);
  ImageDef image_definition() const;
  Image image_load(ImageDef image);
  Image image_load_file(Char const* image_file_path, ImageFormat image_format=IMAGE_FORMAT_AUTO);
  DocumentOutline outline();
  Page page();
  void page_end();
  Int page_number() const;
  void page_start(Double width, Double height);
  Pattern shading_pattern_load(Char const* pattern, ColorSpace color_space, Function func);
  Pattern shading_pattern_load(Char const* pattern, ColorSpace cs, Function const* array_in,
                               UInt length);
  Pattern tiling_pattern_load(Char const* pattern, Canvas canvas);
  Int version() const;
};
Methods

Document::canvas_create

[py]   canvas_create()
[c++]  Canvas canvas_create() const;
[c]    jag_Canvas jag_Document_canvas_create(jag_Document hobj);
[java] Canvas canvas_create();
Effect: Creates a blank canvas.

JagPDF version: 1.1

Document::color_space_load

[py]   color_space_load(spec)
[c++]  ColorSpace color_space_load(Char const* spec);
[c]    jag_ColorSpace jag_Document_color_space_load(jag_Document hobj,
                                                    jag_Char const* spec);
[java] ColorSpace color_space_load(String spec);
Effect: Loads a color space. Upon loading the color space can be set by color_space().

Parameters:

spec

follows the options string format. Specifies the color space type and its parameters. Supported color space types are:

  • 'rgb' - DeviceRGB
  • 'gray' - DeviceGray
  • 'cmyk' - DeviceCMYK
  • 'calgray' - CalGray
  • 'calrgb' - CalRGB
  • 'cielab' - CIELab
  • 'icc' - ICC based
  • 'srgb' - sRGB color space
  • 'adobe-rgb' - AdobeRGB color space
  • 'by-id' - already registered color space

Based on the color space type the following options are recognized:

  • 'white'
    • diffuse white point, values X and Z
    • example: 'calrgb; white=0.9505, 1.0890'
    • required for: 'calgray', 'calrgb', 'cielab'
  • 'black'
    • diffuse black point, values X, Y and Z
    • default: 0, 0, 0
    • example: 'calrgb; black=0.4084, 1.0208, 0.7113; ...'
    • applicable to: 'calgray', 'calrgb', 'cielab'
  • 'range'
    • four numbers Amin, Amax, Bmin, Bmax specifying the range of valid values for the a* and b* components of the color space
    • default: -100, 100, -100, 100
    • example: 'cielab; range=-75, 75, -75, 75; ...'
    • applicable to: 'cielab'
  • 'gamma'
    • one ('calgray') or three ('calrgb') numbers specifying gamma
    • default: 1.0 for all components of the color
    • example: 'calrgb; gamma=2.2, 2.2, 2.2; ...'
  • 'matrix'
    • nine numbers specifying the linear interpolation of the decoded A, B and C components of the color space with respect to the final XYZ representation
    • default: the identity matrix
    • example: 'calrgb; matrix=0.4497, 0.2446, 0.0252, 0.3163, 0.6720, 0.1412, 0.1845, 0.0833, 0.9227; ...'
    • applicable to: 'calrgb'
  • 'profile'
    • path to a file with an ICC profile
    • example: 'icc; profile=/path/to/icc; ...'
    • required for: 'icc'
  • 'components'
    • number of color components of the color space defined by an ICC profile
    • example: 'icc; components=3; ...'
    • required for: 'icc'
  • 'palette'
    • defines Indexed color space
      • up to m x 256 values, where m is the number of color components in the base color space
      • each value is an unsigned integer in range 0 to 255 that is scaled to the range of the corresponding color component in the base color space
    • example: 'gray; palette=0, 127, 255;'
    • applicable for: any color space type
  • 'id'
    • valid color space id, useful for Indexed color space
    • example: 'by-id; id=34; ...'
    • required for: 'by-id'

See:

Document::destination_define

[py]   destination_define(dest)
[c++]  Destination destination_define(Char const* dest);
[c]    jag_Destination jag_Document_destination_define(jag_Document hobj,
                                                       jag_Char const* dest);
[java] Destination destination_define(String dest);
Effect: Defines a destination.

Parameters:

dest

destination (see Destination Syntax)

Document::destination_define_reserved

[py]   destination_define_reserved(id, dest)
[c++]  void destination_define_reserved(Destination id, Char const* dest);
[c]    jag_error jag_Document_destination_define_reserved(jag_Document hobj,
                                                          jag_Destination id,
                                                          jag_Char const* dest);
[java] void destination_define_reserved(Destination id, String dest);
Effect: Defines a previously reserved destination.

Parameters:

id

destination ID retrieved from destination_reserve()

dest

destination (see Destination Syntax)

Document::destination_reserve

[py]   destination_reserve()
[c++]  Destination destination_reserve();
[c]    jag_Destination jag_Document_destination_reserve(jag_Document hobj);
[java] Destination destination_reserve();
Effect: Reserves a destination that can be used immediately, but defined later. The reserved destination must be defined by destination_define_reserved() before invoking finalize().

Document::finalize

[py]   finalize()
[c++]  void finalize();
[c]    jag_error jag_Document_finalize(jag_Document hobj);
[java] void finalize_doc();
Effect:

Finalizes the document. Upon returning from this function:

  • The PDF document is fully written to the destination (file, stream).
  • All resources associated with the document are released (including this object).
  • No further operations are allowed on the document.

Document::font_load

[py]   font_load(fspec)
[c++]  Font font_load(Char const* fspec);
[c]    jag_Font jag_Document_font_load(jag_Document hobj, jag_Char const* fspec);
[java] Font font_load(String fspec);
Effect: Loads a font. Upon loading the font can be set by text_font().

Parameters:

fspec

follows the options string format. Specifies the font to load. Recognizes the following options:

Document::function_2_load

[py]   function_2_load(fun)
[c++]  Function function_2_load(Char const* fun);
[c]    jag_Function jag_Document_function_2_load(jag_Document hobj, jag_Char const* fun);
[java] Function function_2_load(String fun);
Effect: Loads a Type 2 (Exponential Interpolation) function. Type 2 functions are 1-in, n-out interpolation functions.

Parameters:

fun

Specifies the function. Follows the options string format. Recognizes the following options (all optional):

  • 'domain' - the function domain; an array of 2 numbers, default value: 0.0, 1.0
  • 'range' - the function range; an array of 2 * n numbers, n is the number of output values
  • 'c0' - an array of n numbers; the function result when x = 0.0, default value: 0.0
  • 'c1' - an array of n numbers; the function result when x = 1.0, default value: 1.0
  • 'exponent' - the interpolation exponent, default value: 1

PDF version: 1.3

JagPDF version: 1.1

See:

Document::function_3_load

[py]   function_3_load(fun, array_in)
[c++]  Function function_3_load(Char const* fun, Function const* array_in, UInt length);
[c]    jag_Function jag_Document_function_3_load(jag_Document hobj, jag_Char const* fun,
                                                 jag_Function const* array_in,
                                                 jag_UInt length);
[java] Function function_3_load(String fun, Function[] array_in, long length);
Effect: Loads a Type 3 (Stitching) function. Type 3 functions combine k 1-in functions into a single 1-in function.

Parameters:

fun

Specifies the function. Follows the options string format. Recognizes the following options:

  • 'domain' - (optional) the function domain; an array of 2 numbers, default value: 0.0, 1.0
  • 'range' - (optional) the function range; an array of 2 * n numbers, n is the number of output values
  • 'bounds' - (required) an array of k - 1 numbers; defines the intervals to which each function applies
  • 'encode' - (required) an array of 2 * k numbers, the individual pairs map each domain subset defined by domain and range to the domain of the corresponding function
array_in

an array of 1-in functions to combine

length

number of functions

PDF version: 1.3

JagPDF version: 1.1

See:

Document::function_4_load

[py]   function_4_load(fun)
[c++]  Function function_4_load(Char const* fun);
[c]    jag_Function jag_Document_function_4_load(jag_Document hobj, jag_Char const* fun);
[java] Function function_4_load(String fun);
Effect: Loads a Type 4 (PostScript Calculator) function.

Parameters:

fun

Specifies the function. Follows the options string format. Recognizes the following options (all required):

  • 'domain' - the function domain; an array of 2 * m numbers, m is the number of input values
  • 'range' - the function range; an array of 2 * n' numbers, n is the number of output values
  • 'func' - code written in a subset of the PostScript language

PDF version: 1.3

JagPDF version: 1.1

See:

  • the PDF Reference, chapter Syntax | Functions | Type 4 (PostScript Calculator) Functions
  • allowed operators in the PDF Reference, chapter Syntax | Functions | Type 4 (PostScript Calculator) Functions, table Operators in type 4 functions
  • see section Functions

Document::image_definition

[py]   image_definition()
[c++]  ImageDef image_definition() const;
[c]    jag_ImageDef jag_Document_image_definition(jag_Document hobj);
[java] ImageDef image_definition();
Effect: Provides an empty image definition object. After the image has been defined it can be loaded with image_load() and after that the image can be painted with image().

The definition object can be used only for definition of a single image. It cannot be reused after the image has been loaded with image_load().

Document::image_load

[py]   image_load(image)
[c++]  Image image_load(ImageDef image);
[c]    jag_Image jag_Document_image_load(jag_Document hobj, jag_ImageDef image);
[java] Image image_load(ImageDef image);
Effect: Loads an image. Upon loading the image can be painted with image().

Parameters:

image

image definition; its lifetime ends here and cannot be used further

See: image_definition()

Document::image_load_file

[py]   image_load_file(image_file_path [, image_format])
[c++]  Image image_load_file(Char const* image_file_path,
                             ImageFormat image_format=IMAGE_FORMAT_AUTO);
[c]    jag_Image jag_Document_image_load_file(jag_Document hobj,
                                              jag_Char const* image_file_path,
                                              jag_ImageFormat image_format);
[java] Image image_load_file(String image_file_path [, ImageFormat image_format]);
Effect: Loads an image from a file. Upon registering, the registered image can be painted with image().

Parameters:

image_file_path

path to an image file

image_format
  • IMAGE_FORMAT_AUTO, automatically recognizes the image format
  • IMAGE_FORMAT_JPEG
  • IMAGE_FORMAT_PNG

Document::outline

[py]   outline()
[c++]  DocumentOutline outline();
[c]    jag_DocumentOutline jag_Document_outline(jag_Document hobj);
[java] DocumentOutline outline();
Effect: Retrieves document outline.

Document::page

[py]   page()
[c++]  Page page();
[c]    jag_Page jag_Document_page(jag_Document hobj);
[java] Page page();
Effect: Retrieves the current page. Lifetime of the returned page instance ends when page_end() is called. Using the instance after page_end() has been called results in undefined behavior.

Precondition: There is an active page, i.e between page_start() and page_end().

Document::page_end

[py]   page_end()
[c++]  void page_end();
[c]    jag_error jag_Document_page_end(jag_Document hobj);
[java] void page_end();
Effect: Ends the current page.

Precondition: A page has been started with page_start()

Document::page_number

[py]   page_number()
[c++]  Int page_number() const;
[c]    jag_Int jag_Document_page_number(jag_Document hobj);
[java] int page_number();
Effect:

Retrieves the current page number (zero-based).

Document::page_start

[py]   page_start(width, height)
[c++]  void page_start(Double width, Double height);
[c]    jag_error jag_Document_page_start(jag_Document hobj, jag_Double width,
                                         jag_Double height);
[java] void page_start(double width, double height);
Effect: Starts a new page. Use page_end() to close the page.

Precondition: There is no opened page at the moment.

Parameters:

width

page width (in default user space units)

height

height (in default user space units)

Document::shading_pattern_load

[py]   shading_pattern_load(pattern, color_space, func)
[c++]  Pattern shading_pattern_load(Char const* pattern, ColorSpace color_space,
                                    Function func);
[c]    jag_Pattern jag_Document_shading_pattern_load(jag_Document hobj,
                                                     jag_Char const* pattern,
                                                     jag_ColorSpace color_space,
                                                     jag_Function func);
[java] Pattern shading_pattern_load(String pattern, ColorSpace color_space, Function func);
Effect: Loads a shading pattern.

Parameters:

pattern

Specifies the shading pattern. Follows the options string format. The following shading pattern types are recognized:

  • 'function' - Type 1 (function-based) shadings
  • 'axial' - Type 2 (axial) shadings
  • 'radial' - Type 3 (radial) shadings

The following options (all optional) are common for all shading types:

  • 'matrix' - the pattern matrix, determines the pattern coordinate space, default value: the identity matrix
  • 'bbox' - the shading pattern's bounding box in the pattern coordinate space; expressed as four values: left, bottom, right, top
  • 'background' - an array of color components defining a single background color value

Based on the shading type these options can be specified:

  • function-based
    • 'domain' - (optional) an array of 4 numbers specifying the function domain
    • 'matrix_fun' - (optional) an array of 6 numbers, maps domain into the shading's target coordinate space; default value: the identity matrix
  • axial
    • 'coords' - (required) an array of four numbers [x0, y0, x1, y1], the axis extends from (x0, y0) to (x1, y1), expressed in the shading's target coordinate space
    • 'domain' - (optional) an array of two limiting values of a parametric variable, default value: 0.0, 1.0
    • 'extend' - (optional) an array of two values specifying whether to extend the shading beyond the starting and ending points of the axis, respectively; default value: 0, 0
  • radial
    • 'coords' - (required) an array of six numbers [x0, y0, r0, x1, y1, r1] specifying the centers and radii of the starting and ending circles, expressed in the shading's target coordinate space.
    • 'domain' - (optional) an array of two limiting values of a parametric variable, default value: 0.0, 1.0
    • 'extend' - (optional) an array of two values specifying whether to extend the shading beyond the starting and ending circles, respectively; default value: 0, 0
color_space

color space in which color values are expressed

func
  • function-based
    • 2-in, n-out function
  • axial, radial
    • 1-in, n-out function

in both cases, n is the number of color components of color_space

PDF version: 1.3

JagPDF version: 1.1

See:

Document::shading_pattern_load

[py]   shading_pattern_load(pattern, cs, array_in)
[c++]  Pattern shading_pattern_load(Char const* pattern, ColorSpace cs,
                                    Function const* array_in, UInt length);
[c]    jag_Pattern jag_Document_shading_pattern_load_n(jag_Document hobj,
                                                       jag_Char const* pattern,
                                                       jag_ColorSpace cs,
                                                       jag_Function const* array_in,
                                                       jag_UInt length);
[java] Pattern shading_pattern_load(String pattern, ColorSpace cs,
                                    Function[] array_in, long length);
Effect: Loads a shading pattern.

Parameters:

pattern

see description of pattern argument in shading_pattern_load()

color_space

color space in which color values are expressed

array_in
  • function-based
    • n 2-in, 1-out functions
  • axial, radial
    • n 1-in, 1-out functions

in both cases, n is the number of color components of color_space

length

PDF version: 1.3

JagPDF version: 1.1

See:

Document::tiling_pattern_load

[py]   tiling_pattern_load(pattern, canvas)
[c++]  Pattern tiling_pattern_load(Char const* pattern, Canvas canvas);
[c]    jag_Pattern jag_Document_tiling_pattern_load(jag_Document hobj,
                                                    jag_Char const* pattern,
                                                    jag_Canvas canvas);
[java] Pattern tiling_pattern_load(String pattern, Canvas canvas);
Effect: Loads a tiling pattern.

Parameters:

pattern

Specifies the pattern properties. Follows the options string format. Recognizes the following options:

  • 'step' - (required) an array of two numbers, defines spacing between pattern cells in horizontal and vertical directions
  • 'matrix' - (optional) the pattern matrix, determines the pattern coordinate space, default value: the identity matrix
  • 'bbox' - (optional) the pattern cell's bounding box in the pattern coordinate space; expressed as four values: left, bottom, right, top
canvas

the pattern cell; upon finishing this function the canvas can't be used for further operations

JagPDF version: 1.1

See:

Document::version

[py]   version()
[c++]  Int version() const;
[c]    jag_Int jag_Document_version(jag_Document hobj);
[java] int version();
Effect: Retrieves the PDF version.
Description

Represents a document outline.

Synopsis
class DocumentOutline
{
public:
  void color(Double red, Double green, Double blue);
  void item(Char const* title);
  void item(Char const* title, Char const* dest);
  void item(Char const* title, Destination dest);
  void level_down();
  void level_up();
  void state_restore();
  void state_save();
  void style(Int val);
};
Methods

DocumentOutline::color

[py]   color(red, green, blue)
[c++]  void color(Double red, Double green, Double blue);
[c]    jag_error jag_DocumentOutline_color(jag_DocumentOutline hobj, jag_Double red,
                                           jag_Double green, jag_Double blue);
[java] void color(double red, double green, double blue);
Effect: Specifies DeviceRGB color of the outline item's text. The specified color is used for the following outline items. The default value is 0.0, 0.0, 0.0.

Parameters:

red

red component

green

green component

blue

blue component

PDF version: 1.4

DocumentOutline::item

[py]   item(title)
[c++]  void item(Char const* title);
[c]    jag_error jag_DocumentOutline_item(jag_DocumentOutline hobj, jag_Char const* title);
[java] void item(String title);
Effect: Creates an outline item associated with the current page. Clicking the item displays the upper-left corner of the current page positioned at the upper-left corner of the window.

Precondition: Can be used only between page_start() and page_end()

Parameters:

title

UTF-8 text to be displayed

DocumentOutline::item

[py]   item(title, dest)
[c++]  void item(Char const* title, Char const* dest);
[c]    jag_error jag_DocumentOutline_item_destination(jag_DocumentOutline hobj,
                                                      jag_Char const* title,
                                                      jag_Char const* dest);
[java] void item(String title, String dest);
Effect: Creates an outline entry associated with a destination. Clicking the item changes the view of a document according to the destination.

The page option can be omitted in the destination specification if this method is used between page_start() and page_end(). The current page is used in such case.

Parameters:

title

UTF-8 text to be displayed

dest

destination specification (see Destination Syntax)

DocumentOutline::item

[py]   item(title, dest)
[c++]  void item(Char const* title, Destination dest);
[c]    jag_error jag_DocumentOutline_item_destination_obj(jag_DocumentOutline hobj,
                                                          jag_Char const* title,
                                                          jag_Destination dest);
[java] void item(String title, Destination dest);
Effect: Creates an outline entry associated with a destination. Clicking the item changes the view of a document according to the destination.

Parameters:

title

UTF-8 text to be displayed

dest

destination id

See:

DocumentOutline::level_down

[py]   level_down()
[c++]  void level_down();
[c]    jag_error jag_DocumentOutline_level_down(jag_DocumentOutline hobj);
[java] void level_down();
Effect: Goes one level down in the outline hierarchy.

Precondition: There already must be at least one outline item.

DocumentOutline::level_up

[py]   level_up()
[c++]  void level_up();
[c]    jag_error jag_DocumentOutline_level_up(jag_DocumentOutline hobj);
[java] void level_up();
Effect: Goes one level up in the outline hierarchy.

Precondition: Corresponding level_down() was called previously.

DocumentOutline::state_restore

[py]   state_restore()
[c++]  void state_restore();
[c]    jag_error jag_DocumentOutline_state_restore(jag_DocumentOutline hobj);
[java] void state_restore();
Effect: Restores the state (outline items' color and style).

Precondition: The state was previously saved with state_save().

DocumentOutline::state_save

[py]   state_save()
[c++]  void state_save();
[c]    jag_error jag_DocumentOutline_state_save(jag_DocumentOutline hobj);
[java] void state_save();
Effect: Saves the current state (outline items' color and style). Can be restored later by calling state_restore().

DocumentOutline::style

[py]   style(val)
[c++]  void style(Int val);
[c]    jag_error jag_DocumentOutline_style(jag_DocumentOutline hobj, jag_Int val);
[java] void style(int val);
Effect: Specifies the style of the outline entry's text. The specified style is used for the following outline items. The default style is 0.

Parameters:

val

combination of flags

  • 1 .. italic
  • 2 .. bold

PDF version: 1.4

Description

Represents a font. Uniquely identifies a font and provides information about the font.

Synopsis
class Font
{
public:
  Double advance(Char const* txt_u) const;
  Double ascender() const;
  Double bbox_xmax() const;
  Double bbox_xmin() const;
  Double bbox_ymax() const;
  Double bbox_ymin() const;
  Double descender() const;
  Char const* family_name() const;
  Double glyph_width(UInt16 glyph_index) const;
  Double height() const;
  Int is_bold() const;
  Int is_italic() const;
  Double size() const;
};
Methods

Font::advance

[py]   advance(txt_u)
[c++]  Double advance(Char const* txt_u) const;
[c]    jag_Double jag_Font_advance(jag_Font hobj, jag_Char const* txt_u);
[java] double advance(String txt_u);
Effect: Retrieves width of the passed string in user space units. If kerning is turned on then the kerning offsets are counted in.

Font::ascender

[py]   ascender()
[c++]  Double ascender() const;
[c]    jag_Double jag_Font_ascender(jag_Font hobj);
[java] double ascender();
Effect: Retrieves ascender in user space units.

Font::bbox_xmax

[py]   bbox_xmax()
[c++]  Double bbox_xmax() const;
[c]    jag_Double jag_Font_bbox_xmax(jag_Font hobj);
[java] double bbox_xmax();
Effect: Retrieves the horizontal maximum (right-most) in user space units.

Font::bbox_xmin

[py]   bbox_xmin()
[c++]  Double bbox_xmin() const;
[c]    jag_Double jag_Font_bbox_xmin(jag_Font hobj);
[java] double bbox_xmin();
Effect: Retrieves the horizontal minimum (left-most) in user space units.

Font::bbox_ymax

[py]   bbox_ymax()
[c++]  Double bbox_ymax() const;
[c]    jag_Double jag_Font_bbox_ymax(jag_Font hobj);
[java] double bbox_ymax();
Effect: Retrieves the vertical maximum (top-most) in user space units.

Font::bbox_ymin

[py]   bbox_ymin()
[c++]  Double bbox_ymin() const;
[c]    jag_Double jag_Font_bbox_ymin(jag_Font hobj);
[java] double bbox_ymin();
Effect: Retrieves the vertical minimum (bottom-most) in user space units.

Font::descender

[py]   descender()
[c++]  Double descender() const;
[c]    jag_Double jag_Font_descender(jag_Font hobj);
[java] double descender();
Effect: Retrieves descender in user space units.

Font::family_name

[py]   family_name()
[c++]  Char const* family_name() const;
[c]    jag_Char const* jag_Font_family_name(jag_Font hobj);
[java] String family_name();
Effect: Retrieves font family.

Font::glyph_width

[py]   glyph_width(glyph_index)
[c++]  Double glyph_width(UInt16 glyph_index) const;
[c]    jag_Double jag_Font_glyph_width(jag_Font hobj, jag_UInt16 glyph_index);
[java] double glyph_width(int glyph_index);
Effect: Retrieves width of the given glyph.

JagPDF version: 1.4

Font::height

[py]   height()
[c++]  Double height() const;
[c]    jag_Double jag_Font_height(jag_Font hobj);
[java] double height();
Effect: Retrieves baseline distance in user space units.

Font::is_bold

[py]   is_bold()
[c++]  Int is_bold() const;
[c]    jag_Int jag_Font_is_bold(jag_Font hobj);
[java] int is_bold();
Effect: Returns non-zero value if the font is bold.

Font::is_italic

[py]   is_italic()
[c++]  Int is_italic() const;
[c]    jag_Int jag_Font_is_italic(jag_Font hobj);
[java] int is_italic();
Effect: Returns non-zero value if the font is italic.

Font::size

[py]   size()
[c++]  Double size() const;
[c]    jag_Double jag_Font_size(jag_Font hobj);
[java] double size();
Effect: Retrieves font size in user space units.
Description

Represents an image. Uniquely identifies a image and provides information about the image

Synopsis
class Image
{
public:
  UInt bits_per_component() const;
  Double dpi_x() const;
  Double dpi_y() const;
  UInt height() const;
  UInt width() const;
};
Methods

Image::bits_per_component

[py]   bits_per_component()
[c++]  UInt bits_per_component() const;
[c]    jag_UInt jag_Image_bits_per_component(jag_Image hobj);
[java] long bits_per_component();
Effect: Retrieves number of bits per color component.

Image::dpi_x

[py]   dpi_x()
[c++]  Double dpi_x() const;
[c]    jag_Double jag_Image_dpi_x(jag_Image hobj);
[java] double dpi_x();
Effect: Retrieves horizontal resolution in DPI.

Image::dpi_y

[py]   dpi_y()
[c++]  Double dpi_y() const;
[c]    jag_Double jag_Image_dpi_y(jag_Image hobj);
[java] double dpi_y();
Effect: Retrieves vertical resolution in DPI.

Image::height

[py]   height()
[c++]  UInt height() const;
[c]    jag_UInt jag_Image_height(jag_Image hobj);
[java] long height();
Effect: Retrieves height of the image in pixels.

Image::width

[py]   width()
[c++]  UInt width() const;
[c]    jag_UInt jag_Image_width(jag_Image hobj);
[java] long width();
Effect: Retrieves width of the image in pixels.
Description

Specifies an image to be loaded. Besides the standard formats, it is also possible to supply image data in a PDF native format. Note that in such case the 16-bit samples must be big-endian ordered.

See section Images.

Synopsis
class ImageDef
{
public:
  void alternate_for_printing(Image image);
  void bits_per_component(UInt bpc);
  void color_key_mask(UInt const* array_in, UInt length);
  void color_space(ColorSpace cs);
  void data(Byte const* array_in, UInt length);
  void decode(Double const* array_in, UInt length);
  void dimensions(UInt width, UInt height);
  void dpi(Double xdpi, Double ydpi);
  void file_name(Char const* file_name);
  void format(ImageFormat format);
  void gamma(Double val);
  void interpolate(Int flag);
};
Methods

ImageDef::alternate_for_printing

[py]   alternate_for_printing(image)
[c++]  void alternate_for_printing(Image image);
[c]    jag_error jag_ImageDef_alternate_for_printing(jag_ImageDef hobj, jag_Image image);
[java] void alternate_for_printing(Image image);
Effect: Specifies an image alternative designed for printing. The alternative representation of the image may differ, for example, in resolution or in color space. The primary goal is to reduce the need to maintain separate versions of a PDF document for low-resolution on-screen viewing and high-resolution printing.

PDF version: 1.3

ImageDef::bits_per_component

[py]   bits_per_component(bpc)
[c++]  void bits_per_component(UInt bpc);
[c]    jag_error jag_ImageDef_bits_per_component(jag_ImageDef hobj, jag_UInt bpc);
[java] void bits_per_component(long bpc);
Effect: Specifies number of bits per color component. Mandatory for the native format except it has an indexed color space. Has no effect for other image formats.

Parameters:

bpc

allowed values: 1, 2, 4, 8 and (in PDF 1.5) 16

ImageDef::color_key_mask

[py]   color_key_mask(array_in)
[c++]  void color_key_mask(UInt const* array_in, UInt length);
[c]    jag_error jag_ImageDef_color_key_mask(jag_ImageDef hobj, jag_UInt const* array_in,
                                             jag_UInt length);
[java] void color_key_mask(long[] array_in, long length);
Effect: Specifies the color mask applied to the image. Can be specified for all image formats. For formats other than the native it overrides the intrinsic mask.

Parameters:

array_in

color key mask values

length

number of values (must be twice the number of color components)

See: the PDF Reference, chapter Graphics | Images | Masked Images | Color Key Masking.

ImageDef::color_space

[py]   color_space(cs)
[c++]  void color_space(ColorSpace cs);
[c]    jag_error jag_ImageDef_color_space(jag_ImageDef hobj, jag_ColorSpace cs);
[java] void color_space(ColorSpace cs);
Effect: Specifies the image color space. Mandatory for the native format. Can be set for other image formats as well providing that the number of color components matches the image.

ImageDef::data

[py]   data(array_in)
[c++]  void data(Byte const* array_in, UInt length);
[c]    jag_error jag_ImageDef_data(jag_ImageDef hobj, jag_Byte const* array_in,
                                   jag_UInt length);
[java] void data(byte[] array_in, long length);
Effect: Specifies image data in memory. Either this method or file_name() is mandatory.

Parameters:

array_in

image data

length

image data byte size

ImageDef::decode

[py]   decode(array_in)
[c++]  void decode(Double const* array_in, UInt length);
[c]    jag_error jag_ImageDef_decode(jag_ImageDef hobj, jag_Double const* array_in,
                                     jag_UInt length);
[java] void decode(double[] array_in, long length);
Effect: Maps image samples into the specified range. Can be used for all image formats.

There is a special case when JagPDF uses the decode array itself: Image samples in CMYK JPEGs are inverted and the decode function is used for inverting them back.

Parameters:

array_in

decode values

length

number of values (must be twice the number of color components)

See: the PDF Reference, chapter Graphics | Images | Image Dictionaries | Decode Arrays.

ImageDef::dimensions

[py]   dimensions(width, height)
[c++]  void dimensions(UInt width, UInt height);
[c]    jag_error jag_ImageDef_dimensions(jag_ImageDef hobj, jag_UInt width,
                                         jag_UInt height);
[java] void dimensions(long width, long height);
Effect: Specifies the image dimensions. Has effect only for the native format.

ImageDef::dpi

[py]   dpi(xdpi, ydpi)
[c++]  void dpi(Double xdpi, Double ydpi);
[c]    jag_error jag_ImageDef_dpi(jag_ImageDef hobj, jag_Double xdpi, jag_Double ydpi);
[java] void dpi(double xdpi, double ydpi);
Effect: Specifies the image resolution in DPI. If not specified then the value of images.default_dpi profile option is used for the native format. For other image formats it overrides the image's intrinsic DPI.

ImageDef::file_name

[py]   file_name(file_name)
[c++]  void file_name(Char const* file_name);
[c]    jag_error jag_ImageDef_file_name(jag_ImageDef hobj, jag_Char const* file_name);
[java] void file_name(String file_name);
Effect: Specifies a path to an image file. Either this method or data() is mandatory.

ImageDef::format

[py]   format(format)
[c++]  void format(ImageFormat format);
[c]    jag_error jag_ImageDef_format(jag_ImageDef hobj, jag_ImageFormat format);
[java] void format(ImageFormat format);
Effect: Specifies the image format. If not specified then JagPDF attempts to automatically recognize the image format.

Parameters:

format
  • IMAGE_FORMAT_NATIVE
  • IMAGE_FORMAT_PNG
  • IMAGE_FORMAT_JPEG

ImageDef::gamma

[py]   gamma(val)
[c++]  void gamma(Double val);
[c]    jag_error jag_ImageDef_gamma(jag_ImageDef hobj, jag_Double val);
[java] void gamma(double val);
Effect: Specifies the gamma correction applied to the image. The default value is 1. Can be specified for all image formats. For formats other than the native it overrides the intrinsic gamma value.

Parameters:

val

gamma value for all color components (must be>0)

ImageDef::interpolate

[py]   interpolate(flag)
[c++]  void interpolate(Int flag);
[c]    jag_error jag_ImageDef_interpolate(jag_ImageDef hobj, jag_Int flag);
[java] void interpolate(int flag);
Effect: Specifies whether to interpolate the image. If not specified then the value of images.interpolated profile option is used. Note that interpolation may increase the time required to render the image.

Parameters:

flag

non-zero value enables interpolation

See: the PDF Reference, chapter Graphics | Images | Image Dictionaries | Image Interpolation.

Description

Represents a page of a PDF document.

Synopsis
class Page
{
public:
  void annotation_goto(Double x, Double y, Double width, Double height, Char const* dest,
                       Char const* style=0);
  void annotation_goto(Double x, Double y, Double width, Double height, Destination dest,
                       Char const* style=0);
  void annotation_uri(Double x, Double y, Double width, Double height, Char const* uri,
                      Char const* style=0);
  Canvas canvas();
};
Methods

Page::annotation_goto

[py]   annotation_goto(x, y, width, height, dest [, style])
[c++]  void annotation_goto(Double x, Double y, Double width, Double height,
                            Char const* dest, Char const* style=0);
[c]    jag_error jag_Page_annotation_goto(jag_Page hobj, jag_Double x, jag_Double y,
                                          jag_Double width, jag_Double height,
                                          jag_Char const* dest, jag_Char const* style);
[java] void annotation_goto(double x, double y, double width, double height, String dest [,
                            String style]);
Effect: Creates a link annotation associated with a destination. The annotation rectangle is specified in the default user space units.

Parameters:

x

lower-left x of the annotation rectangle

y

lower-left y of the annotation rectangle

width

width of the annotation rectangle

height

height of the annotation rectangle

dest

destination string (see Destination Syntax)

style

reserved, must be 0

Page::annotation_goto

[py]   annotation_goto(x, y, width, height, dest [, style])
[c++]  void annotation_goto(Double x, Double y, Double width, Double height,
                            Destination dest, Char const* style=0);
[c]    jag_error jag_Page_annotation_goto_obj(jag_Page hobj, jag_Double x, jag_Double y,
                                              jag_Double width, jag_Double height,
                                              jag_Destination dest, jag_Char const* style);
[java] void annotation_goto(double x, double y, double width, double height,
                            Destination dest [, String style]);
Effect: Creates a link annotation associated with a destination. The annotation rectangle is specified in the default user space units.

Parameters:

x

lower-left x of the annotation rectangle

y

lower-left y of the annotation rectangle

width

width of the annotation rectangle

height

height of the annotation rectangle

dest

destination

style

reserved, must be 0

See:

Page::annotation_uri

[py]   annotation_uri(x, y, width, height, uri [, style])
[c++]  void annotation_uri(Double x, Double y, Double width, Double height,
                           Char const* uri, Char const* style=0);
[c]    jag_error jag_Page_annotation_uri(jag_Page hobj, jag_Double x, jag_Double y,
                                         jag_Double width, jag_Double height,
                                         jag_Char const* uri, jag_Char const* style);
[java] void annotation_uri(double x, double y, double width, double height, String uri [,
                           String style]);
Effect: Creates a link annotation associated with a URI action. The annotation rectangle is specified in the default user space units.

Parameters:

x

lower-left x of the annotation rectangle

y

lower-left y of the annotation rectangle

width

width of the annotation rectangle

height

height of the annotation rectangle

uri

URI in 7-bit ASCII

style

reserved, must be 0

Page::canvas

[py]   canvas()
[c++]  Canvas canvas();
[c]    jag_Canvas jag_Page_canvas(jag_Page hobj);
[java] Canvas canvas();
Effect: Retrieves the current page canvas. Lifetime of the canvas instance returned from this function is the same as that of the page instance that issued it.

See: page()

Description

Maintains options which affect the resulting PDF. Instances of this class are reference counted.

Synopsis
class Profile
{
public:
  void save_to_file(Char const* fname) const;
  void set(Char const* option, Char const* value);
};
Methods

Profile::save_to_file

[py]   save_to_file(fname)
[c++]  void save_to_file(Char const* fname) const;
[c]    jag_error jag_Profile_save_to_file(jag_Profile hobj, jag_Char const* fname);
[java] void save_to_file(String fname);
Effect: Saves the profile to a file.

Profile::set

[py]   set(option, value)
[c++]  void set(Char const* option, Char const* value);
[c]    jag_error jag_Profile_set(jag_Profile hobj, jag_Char const* option,
                                 jag_Char const* value);
[java] void set(String option, String value);
Effect: Sets a profile option.
Prev Up Home Next