PDFlib 8 Windows COM/.NET Tutorial

Direct Paths. Using the path functions moveto( ), lineto( ), rect( ) etc. you can construct a
direct path which will immediately be written to the current page or another content
stream (e.g. a template or Type 3 glyph description). Immediately after constructing the
path it must be processed with one of stroke ( ), fill( ), clip( ) and related functions. These
functions will consume and delete the path. The only way to use a path multiply is with
save( ) and restore( ).
It is an error to construct a direct path without applying any of the above operations to
it. PDFlib’s scoping system ensures that clients obey to this restriction. If you want to set
any appearance properties (e.g. color, line width) of a path you must do so before starting
any drawing operations. These rules can be summarized as »don’t change the appearance
within a path description«.
Merely constructing a path doesn’t result in anything showing up on the page; you
must either fill or stroke the path in order to get visible results:
p.setcolor("stroke", "rgb", 1, 0, 0, 0);
p.moveto(100, 100);
p.lineto(200, 100);
p.stroke();
Most graphics functions make use of the concept of a current point, which can be
thought of as the location of the pen used for drawing.
Cookbook A full code sample can be found in the Cookbook topic graphics/starter_graphics.
Path objects. Path objects are more convenient and powerful alternative to direct
paths. Path objects encapsulate all drawing operations for constructing the path. Path
objects can be created with add_path_point( ) or extracted from an image file which includes
an image clipping path (see below). add_path_point( ) supports several convenience
options to facilitate path construction. Once a path object has been created it can
be used for different purposes:
> The path object can be used on the page description with draw_path( ), i.e. filled,
stroked, or used as a clipping path.
> Path objects can be used as wrap shapes for Textflow: the text will be formatted so
that it wraps inside or outside of an arbitrary shape (see Section 8.2.10, »Wrapping
Text around Paths and Images«, page 223).
> Text can also be placed on a path, i.e. the characters follow the lines and curves of the
path (see Section 8.1.7, »Text on a Path«, page 205).
> Path objects can be placed in table cells.
Unlike direct paths, path objects can be used multiply until they are explicitly destroyed
with delete_path( ). Information about a path can be retrieved with info_path( ).
The following code fragment creates a simple path shape with a circle, strokes it at two
different locations on the page, and finally deletes it:
path = p.add_path_point( -1, 0, 100, "move", "");
path = p.add_path_point(path, 200, 100, "control", "");
path = p.add_path_point(path, 0, 100, "circular", "");
p.draw_path(path, 0, 0, "stroke");
p.draw_path(path, 400, 500, "stroke");
p.delete_path(path);
72 Chapter 3: Creating PDF Documents (Edition for COM, .NET, and REALbasic)