لطفا منتظر باشید ...
13.3 PDF-PHP Reference
This section describes the methods
that are available in the two classes that comprise the pdf-php
library (version 009). The first section describes the EZPDF class
extension that provides easy-to-use methods to create a PDF document,
control basic formatting, and add text, tables, columns, and images.
The second section lists the methods in the base class that can be
used for more complex tasks, including drawing shapes and controlling
fonts.
We recommend always using the
EZPDF class in preference to the base
class because it allows you to access all of the base class methods
as well as all of the advanced features that simplify producing
documents. For this reason, we've omitted PDF base
class methods from our discussion that are a subset of the
corresponding EZPDF methods. For example, we don't
discuss the PDF base class constructor, because the EZPDF constructor
has the same functionality and additional features. In addition,
we've omitted discussion of using callback functions
to add additional functionality; more details on this topic is in the
final section of the pdf-php class manual.
13.3.1 EZPDF Class
void Cezpdf::Cezpdf([mixed
paper[, string orientation]])
This
is the class constructor. Without parameters, it creates a new PDF
document using A4 paper size with portrait orientation. It sets all
margins on the page to 30 points (around 0.4 inches or just over 1
centimeter) and then defines the point at which the text starts to be
the top-left corner of the margined page.
The first parameter defines an optional
paper size and it can be either a string
that represents a standard size (a full list is provided next), an
array of two elements that contains the page width and depth in
centimeters expressed as floats (for example,
array(21.0,29.7) for an A4 page), or an array of
four elements that defines the top-left and bottom-right positions on
the page as two sets of (X,Y) coordinates, measured in points (for
example, array(0,0,595.28,841.89) for an A4
page).
The second parameter defines the orientation. It can be set to
'landscape', otherwise portrait is assumed.
The complete list of possible paper sizes is '4A0', '2A0',
'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7',
'A8', 'A9', 'A10', 'B0', 'B1', 'B2', 'B3', 'B4', 'B5', 'B6', 'B7',
'B8', 'B9', 'B10', 'C0', 'C1', 'C2', 'C3', 'C4', 'C5', 'C6', 'C7',
'C8', 'C9', 'C10', 'RA0', 'RA1', 'RA2', 'RA3', 'RA4', 'SRA0', 'SRA1',
'SRA2', 'SRA3', 'SRA4', 'LETTER', 'LEGAL', 'EXECUTIVE', or
'FOLIO'.
void Cezpdf::ezColumnsStart([array options])
Switches output into multi-column mode. By default, the text that
follows the method call is output in two columns per page, with a gap
of 10 points between the columns. An array
of options can be provided as a parameter containing either or both
of the associative keys num and
gap that define the number of columns and gap
between the columns respectively. For example,
ezColumnsStart("num"=>3,"gap"=>5)
switches output to 3 columns per page with a gap of 5 points between
each column.
void Cezpdf::ezColumnsStop( )
Switches output back to one column per page mode and restores margins
prior to the call to ezColumnsStart( ). It is
recommended that you start a new page by calling ezNewPage(
) immediately after a call to ezColumnsStop(
).
void Cezpdf::ezImage(string
image_file[, int padding [, int width [, string resize [, string justification [, array border]]]]])
Inserts an image_file of type JPEG or PNG
into the document at the current position. The
image_file parameter can include a path,
and must include the full filename of the image. By default, the
image is centered, and resized to the width of the current column (if
in multi-column mode) or page (if not in multi-column mode) less a
spacing of five points on each side of the image.
The optional padding parameter is used to
alter the spacing on each side of the image from the default of 5
pixels.
The width and
resize parameters are related as follows:
If resize is set to 'none ' and width is provided
The image is resized to a width of width
pixels unless it is too wide for the current page or column.
If resize is set to 'none ' and width is omitted
The image is not resized at all.
If resize is set to 'width '
The width parameter is ignored and the
image is resized to fit the width of the current column or page
(minus the padding).
If resize is set to 'full '
The width parameter is ignored and the
image is resized to fit the width of the current column or page
(minus the padding). Then, if the image doesn't fit
vertically within the column or page, it is resized down
proportionally until it does.
The width parameter defaults to the width
of the image in pixels. The resize parameter defaults to
'full'. As discussed, this causes the
'width' parameter to be overridden.
The justification parameter defines where
the image sits in the current column or page, and it can be set to
'center', 'left', or
'right'. It has meaning only if the image is
smaller in width than the column or page (that is, it has not been
resized using the width or
resize parameters so that it spans the
whole column or page). The default is 'center'.
The border array defines a border for the
image. The array can have up to four associatively-indexed elements:
'width' that defines the width of the border in
pixels (the default is 1); 'cap' that specifies
the line cap type (the default is 'round', and the
entry for Cpdf::setLineStyle( ) defines this in
more detail); 'join' that specifies the join type
(the default is 'round', and the entry for
Cpdf::setLineStyle( ) defines this in more
detail); and, 'color' which defines the line color
and itself has three elements that can be set to intensities of red,
blue, and green respectively (the default is half intensity for all,
and the options are discussed further in
Cpdf::setStrokeColor( )). The following array
defines a border of two pixels in width
with a bright red color:
$border = array("width" => 2, "color" => array(1.0, 0.0, 0.0));void Cezpdf::ezInsertMode([int
status [, int page [, string where]]])
Controls whether new pages are inserted into a document rather than
appended to the end. The default is a
status value of 1, which turns on the
insert mode that inserts pages into the document. A
status value of 0 turns off insert mode
and from then pages are added to the end.
When status is set to 1, the optional
page parameter defines the page number
where new pages should be inserted (the default is 1) and the
where parameter defines if the pages
should be inserted 'before' or
'after' that page number (the default is
'before').
void Cezpdf::ezNewPage( )
Ends the current page and begins a new page. If you are using the
EZPDF class, use this method in preference to the base
class's Cpdf::newpage( ) (which
is not discussed in this chapter).
string Cezpdf::ezOutput([int
option])
Returns the PDF document as a string. This allows you to save it to a
file or store it in a database (if, for example,
you're delivering the same file multiple times and
want to save processing costs). The option
parameter is set to 0 by default (no option), but it can also be set
to 1 which prevents compression and thus allows the content to be
viewed in a text editor for debugging purposes.
void Cezpdf::ezSetCmMargins(float
top, float bottom, float left, float right)
Sets the top,
bottom, left,
and right margins in centimeters.
void Cezpdf::ezSetDy(int
points [, string force])
Moves the drawing point by a relative vertical space
points measured in points. A negative
value is down the page, and a positive value is towards the top. If
the drawing point moves below the bottom margin, a new page is
started and the drawing point is set to the top margin.
If the optional force parameter is set to
'makespace', the space created will always be
points in size even if it spans multiple
pages. This is designed to allow you to create a space that you later
use for drawing.
void Cezpdf::ezSetMargins(float
top, float bottom, float left, float right)
Sets the top,
bottom, left,
and right margins in points.
void Cezpdf::ezSetY(int
position)
Moves the drawing point to the vertical point
position, where the point 0 is the bottom
of the page. If the new position is below the bottom margin, a new
page is begun.
int Cezpdf::ezStartPageNumbers(float
x, float y, int size [, string position [, string pattern [, int set_number]]])
Starts page numbering on the current page and displays the page
number at coordinates x and
y with the requested font
size. The bottom-left corner of the page
is coordinate X=0, Y=0, and font used is the current font as set by
Cpdf::selectFont( ).
The optional position can be set to 'left' or
'right' (the default is 'left')
to indicate whether the text should be displayed to the left or right
of coordinate x.
The string pattern defines how the page
numbering is displayed. Two placeholders can be used in specifying
the numbering: {PAGENUM} and
{TOTALPAGENUM}. and these represent the current
page and total pages respectively. For examples, the
pattern 'Total pages:
{TOTALPAGENUM}. This page: {PAGENUM}' displays strings such
as `Total pages: 10. This page:
4'. The default display string is
`{PAGENUM} of
{TOTALPAGENUM}'.
The return value can be used to implement several concurrent
numbering schemes in the same document and is used with the optional
set_number parameter.
It's unlikely you'll need this in
practice, and we don't discuss it in detail here;
more details and an example can be found in the pdf-php class manual.
void Cezpdf::ezStopPageNumbers([int
stop_total [, int stop_when [, int set_number]]])
Stops numbering of pages. If stop_total is
set to 0 (the default), the total number of pages that is reported
stops as well; if it's set to 1, the reported total
is the actual total number of pages. If the
stop_when parameter is set to 0 (the
default) numbering stops on the current page; if
it's set to 1, numbering stops on the next page.
The set_number parameter is used to start
and stop multiple numbering schemes within one document.
It's unlikely you'll need this in
practice, and we don't discuss it in detail here;
more details and an example can be found in the pdf-php class manual.
void Cezpdf::ezStream([array
options])
Outputs the PDF document to the web browser after finalizing EZPDF
class processing.
The options array can be used to control
three HTTP headers: first, you can set
options['Content-Disposition'] to a
filename that the user's browser should respect in
saving the file (the default is file.pdf);
second, you can set
options['Accept-Ranges'] to 0 (off) or 1
(on) to indicate whether your server can handle retrieval of a range
of bytes from the file (the default is 0); and, you can set
options['compress'] to 0 (off) or 1 (on)
to compress the document content (the default is 1).
float Cezpdf::ezTable(array
data [, array columns [, string title [, array options]]])
Creates a table that displays an array of
data. The return value is the Y coordinate
in points of the writing point on the page after the table has been
output (where the bottom of the page is the point Y=0).
The data array should contain one or more
elements that are arrays, where each such element is a row of data in
the table. These row arrays should all have the same number of
elements, and the elements should be in the same order in each row
array (unless the optional columns
parameter is supplied) and have the same associative labels. The
following is an example of a data array
with two rows and two columns:
$table = array(
array("Col A" => "Row 1, Col A data", "Col B" => "Row 1, Col B data"),
array("Col A" => "Row 2, Col A data", "Col B" => "Row 2, Col B data")
);
By default, columns have headings set to the associative labels used
in the row arrays; in the above example, the columns are headed
'Col A' and 'Col B'. In
addition, by default, the table has a line border, alternate lines
are shaded gray, and the table can wrap over multiple pages (with the
column headings redisplaying on each page). Example 13-5 uses the $table array and
default parameters to create a table and its output is shown in Figure 13-6.
Example 13-5. Producing a simple table with ezTable( )
<?php
require "class.ezpdf.php";
$doc =& new Cezpdf( );
$table = array(
array("Col A" => "Row 1, Col A data", "Col B" => "Row 1, Col B data"),
array("Col A" => "Row 2, Col A data", "Col B" => "Row 2, Col B data")
);
$doc->ezTable($table);
$doc->ezStream( );
?>
Figure 13-6. The output of Example 13-5
The columns parameter is an optional
associative array that redefines headings for the columns and the
display order of the columns. It can also be used to select only some
columns from the data array. The
associative keys of columns should be
associative keys from the data array, and
the associative values are the new names of the columns. The order in
which elements are listed in columns
defines the display order. For example, to replace the 'Col
A' and 'Col B' headings in our previous
example with 'Column A' and 'Column
B' and reverse their display order, we could provide the
following columns array:
$columns = array("Col B" => "Column B", "Col A" => "Column A")The optional title parameter is a title to
display at the beginning of the table. The script in Example 13-6 shows an extended version of Example 13-5 that renames the columns using the
$columns array and includes a title. Its output is
shown in Figure 13-7.
Example 13-6. Renaming columns and including a title with ezTable( )
<?php
require "class.ezpdf.php";
$doc =& new Cezpdf( );
$table = array(
array("Col A" => "Row 1, Col A data", "Col B" => "Row 1, Col B data"),
array("Col A" => "Row 2, Col A data", "Col B" => "Row 2, Col B data")
);
$columns = array("Col B" => "Column B", "Col A" => "Column A");
$doc->ezTable($table, $columns, "The Table with Columns!");
$doc->ezStream( );
?>
Figure 13-7. The output of Example 13-6
The options array is an associative array
that can be used to define a wide range of table options. Valid
options include:
options['colGap']
The gap in points to use between the data and the column lines in the
table. The default is 5.
options['cols']
An array that contains the column_name
associative keys from the data array (not
the columns array!) and is used to set
properties for each column. Each
column_name element itself has two
optional elements. First, justification defines
the justification of column_name and is
set to 'left', 'right', or
'center'; the default is
'left'. Second, width defines
the column width in points and is set to a float value; text wraps
within the cell when it exceeds the column width.
For example, to set the width of 'Col A' to 100
points and its alignment to center, and the width of 'Col
B' to 50 points and to right alignment, use the
options parameter shown in Example 13-7. The output is shown in Figure 13-8.
Example 13-7. Defining column properties with an options array for ezTable( )
<?php
require "class.ezpdf.php";
$doc =& new Cezpdf( );
$table = array(
array("Col A" => "Row 1, Col A data", "Col B" => "Row 1, Col B data"),
array("Col A" => "Row 2, Col A data", "Col B" => "Row 2, Col B data")
);
$columns = array("Col B" => "Column B", "Col A" => "Column A");
$options = array('cols' =>
array('Col A' => array('width'=>100, 'justification' => 'center'),
'Col B' => array('width'=>50, 'justification' => 'right')
)
);
$doc->ezTable($table, $columns, "The Table with Columns!", $options);
$doc->ezStream( );
?>
Figure 13-8. The output of Example 13-7
options['fontsize']
The font size to use in the body of the table. The default is 10.
options['innerLineThickness']
The width of lines inside the table body measured in points. It
defaults to 1.
options['lineCol']
The color of the lines to use in the table specified as a
three-element array of red, green, and blue values expressed as
floats in the range 0 to 1. The default is black, that is,
options['lineCol'] = array(0,0,0).
options['maxWidth']
Defines the maximum width of the table in points; cell widths are
adjusted if necessary to stay within this width.
options['outerLineThickness']
The width of lines bordering the table body measured in points. It
defaults to 1.
options['protectRows']
The number of rows from the first page to reproduce at the beginning
of each subsequent page.
options['rowGap']
The gap in points to use between the data and the row lines in the
table. The default is 2.
options['shadeCol']
An array of three float elements that represent the intensity of red,
blue, and green to use when shading rows. The range is 0 to 1, and
the default is options['shadeCol'] = array(0.8, 0.8,
0.8).
options['shadeCol2']
The same as options['shadeCol'] except it is used
for alternate rows when options['shaded'] is set
to 2. The default is options['shadeCol'] =
array(0.7, 0.7, 0.7).
options['shaded']
Can be set to 0 (no shading), 1 (shade alternate rows in the color
defined by shadeCol), or 2 (shade alternate rows
in the colors defined by shadeCol and
shadeCol2). The default is 1.
options['showHeadings']
Can be set to 0 (do not show column headings) or 1 (show column
headings, the default).
options['showLines']
Can be set to 0 (no borders), 1 (show the borders, the default), or 2
(show borders and lines between rows).
options['textcol']
The color of the text to use in the table specified as a
three-element array of red, green, and blue values expressed as
floats in the range 0 to 1. The default is black, that is,
options['textcol'] = array(0,0,0).
options['titlefontSize']
The font size to use for the optional
title. The default is 12.
options['width']
Defines the width of the table in points and, if used, the cell
widths will be adjusted to give this total width.
options['xOrientation']
A string that defines the position of the table relative to
options['xPos']. It can be set to
'left', 'right', or
'center'.
options['xPos']
Defines the horizontal alignment of the table on the page, and can be
set to a string of 'left',
'right', or 'center' (the
default is 'center'). It can alternatively be set
to a float value that is an X coordinate. It is used in conjunction
with options['xOrientation'].
Bool Cezpdf::ezText(string text [, int size [, array options [, int overflow]]])
Writes text into a document including any
carriage returns present in the string. By default, the font size is
12 or the last font size used if different; this can be overridden by
providing the size parameter.
The options parameter is an array that can
have one or more of seven associatively-accessed elements:
'left' is a float that is a gap in points to leave
from the left margin; 'right' is a float that is a
gap in points to leave from the right margin;
'aleft' is a float that is a gap in points to
leave from the left of the page (ignoring the left margin);
'aright' is a float that is a gap in points to
leave from the right of the page (ignoring the right margin);
'leading' is a float that defines the height of
the line and is independent of the font size (it used to create
spacing); and, 'spacing' is a float that defines
the line spacing in word-processor style as 1.0 (single), 1.5, 2.0
(double), or any other desired value.
For example, to output a string in 14 point font size between the
absolute X coordinate points 100 and 150 and using 1.5 spacing, you
can use:
$pdf->ezText("This is a text string that is output between 100 and 150",
14, array('aleft'=>100, 'aright'=>150, 'spacing'=>1.5));Using both 'left' and 'aleft',
or 'right' and 'aright', or
'leading' and 'spacing' does
not make sense.
The overflow parameter is 0 by default. If
it is set to 1, text is not actually output to the document. Instead,
the method returns true if adding the
text would cause a new page to be created
and false if the text
fits on the current page.
inline codes
There are three inline codes that can be used within the text passed
as a parameter to the ezText( ) method. These
are:
<u> and </u>
Produce underlined text. For example,
ezText("<u>hello</u>")
produces hello.
<c:alink> and </c:alink>
Create a link to a URL, marking text in the same way as the HTML
<a> element. For example,
ezTest("<c:alink:http://www.webdatabasebook.com/>web
database book website</c:alink>")
produces an underlined link web database book web
site that when clicked will load the web site http://www.webdatabasebook.com/ in a browser.
<c:ilink> and </c:ilink>
Link internally to a destination within a document. For example,
ezText("<c:ilink:page1>Jump to Page
1</c:ilink>") produces an
underlined link Jump to Page 1 that links to the
destination marker page1. Adding a destination is
described in Cpdf::addDestination( ) in the next
section.
13.3.2 Base Class
void Cpdf::addDestination(string
label, string style [, float a [, float b, float c]])
Creates a destination
label within a document (see also the
inline codes defined at the conclusion of the previous section).
Labels must be unique within a document.
The style parameter defines what happens
when the user visits the destination by clicking on an inline link.
It can be set to several different values, and the value defines
whether no additional parameters are needed, whether parameter
a is supplied, or whether parameters
a, b, and
c are supplied. The options for
style are as follows (for all options, the
coordinate X=0, Y=0 is the bottom-left corner of the page):
'Fit'
Opens the page containing the label resized to the PDF viewer. It has
no additional parameters.
'FitB'
Opens the page containing the label resized so that its bounding box
fits the PDF viewer. It has no additional parameters.
'FitBH'
Opens the page containing the label at the coordinate
Y=a and horizontally fitted so that its
bounding box fits the PDF viewer.
'FitBV'
Opens the page containing the label at the coordinate
X=a and vertically fitted so that its
bounding box fits the PDF viewer.
'FitH'
Opens the page containing the label at the coordinate
Y=a and horizontally fitted to the PDF
viewer.
'FitV'
Opens the page containing the label at the coordinate
X=a and vertically fitted to the PDF
viewer.
'XYZ'
Opens the page containing the label at coordinates
X=a, Y=b, and
with a zoom factor of c. For example, the
following call sets a label myTable that when
visited opens the page containing myTable at
coordinates X=100 and Y=150 with a zoom factor of 2 (that is, the
display is twice the normal size):
$doc->addDestination("myTable", "XYZ", 100, 150, 2);void Cpdf::addInfo(mixed
tag [, string value])
Adds information to the document. The tag
parameter is either: first, the name of a tag, in which case the
value parameter is used to supply the
value; or, second, an associative array of tag name keys and value
pairs (in which case, value is not used).
The valid tags are: Title,
Author, Subject,
Keywords, Creator,
Producer, CreationDate,
ModDate, and Trapped; the
Creator and CreationDate are
automatically set (to the class name and to today respectively) but
may be overridden.
For example to set the author and title of a document, use:
$doc->addInfo(array("Author" => "Hugh W.", "Title" => "My document"));void Cpdf::addInternalLink(string
label, float topX, float topY, float bottomX, float bottomY)
Adds a clickable link within a document that points to a destination
label that has been defined with
Cpdf::addDestination( ). The parameters
topX and topY
define the top-left corner of the clickable area. The parameters
bottomX and
bottomY define the bottom-right corner of
the clickable area. All coordinates are point values represented as
floats, and the point X=0 and Y=0 is the bottom left corner of the
page.
This is an alternative to the simpler inline code
<c:ilink> described in the previous section.
void Cpdf::addJpegFromFile(string
image_file, float X, float Y, [, float width [, float height]])
Adds the JPEG image stored in the file
image_file to the PDF document at
coordinates X and
Y. An optional image
width and
height may be provided. The coordinate
X=0, Y=0 is the bottom left of the page, and all coordinates are
point values. The method does not require the installation of any
libraries.
This is a simpler alternative to Cezpdf::ezImage(
).
void Cpdf::addLink(string
URL, float topX, float topY, float bottomX, float bottomY )
Adds a clickable link within a document that points to a
URL. The parameters
topX and topY
define the top left corner of the clickable area. The parameters
bottomX and
bottomY define the bottom right corner of
the clickable area. All coordinates are point values represented as
floats, and the point X=0 and Y=0 is the bottom-left corner of the
page.
This is a simpler alternative to the inline code
<c:alink> described in the previous section.
Cpdf::addObject(int
identifier [, string where])
Adds an object referenced by identifier to
the current page in the document. The identifier is a value returned
from Cpdf::openObject( ) or another method that
returns a page identifier. See Cpdf::openObject(
) for a discussion of objects.
The optional parameter where can be set to
control where the object is added and can have the following values:
'add' to add to the current page (the default
value); 'all' to add to all pages from the current
page onwards; 'odd' to add to all odd-numbered
pages from the current page onwards; 'even' to add
to all even-numbered pages from the current page onwards;
'next' to add to only the next page;
'nextodd' to add to all odd-numbered pages from
the next page onwards; or, 'nexteven' to add to
all even-numbered pages from the next page onwards.
void Cpdf::addPngFromFile(string
image_file, float X, float Y, [, float width [, float height]])
Adds the PNG image stored in the file
image_file to the PDF document at
coordinates X and
Y. An optional image
width and
height may be provided. The coordinate
X=0, Y=0 is the bottom left of the page, and all coordinates are
point values. The method does not require the installation of any
libraries.
This is a simpler alternative to Cezpdf::ezImage(
).
void Cpdf::addText(float
X, float Y, int size, string text [, float angle [, float space_adjust]])
Adds text to the document beginning at
coordinate X and
Y in the font
size. The coordinate X=0, Y=0 is the
bottom left of the page, and coordinates are point values.
An optional angle in degrees can be
provided (by default it is 0) and causes the text to be output at a
counterclockwise angle relative to the bottom of the page. Unless you
need an angle, use Cezpdf::ezText( ) instead as
it supports justification and line wrapping.
The adjust option adds space, measured in
points, to whitespace such as space characters. This is used by the
Cezpdf::AddText( ) method for full
justification. Negative values remove space.
The method supports basic HTML-like markup for the fonts that are
distributed with the class (see Cpdf::selectFont(
) for details). You can use <b>
and </b> to begin and end bold text, and
<i> and </i> to
begin and end italics. You can output the <
character using the entity reference <.
void Cpdf::closeObject( )
Closes the current object. All future writes then go to the document.
See Cpdf::openObject( ) for a discussion of
objects.
void Cpdf::curve(float
X0, float Y0, float X1, float Y1, float X2, float Y2, float X3, float Y3)
Draws a Bezier curve between the points
X0, Y0 and
X3, Y3, using
the points X1,
Y1, and X2,
Y2 to define the shape. The coordinate
X=0, Y=0 is the bottom left of the page, and coordinates are point
values.
void Cpdf::ellipse(float
X, float Y, float radius1 [, float radius2 [, float angle [, int curves]]])
Draws an ellipse or circle centered at the point
X, Y with a
horizontal radius of radius1 and an
optional vertical radius of radius2; if
radius2 is omitted, a circle is drawn. The
coordinate X=0, Y=0 is the bottom left of the page, and coordinates
are point values.
An optional angle in degrees can be
provided (by default it is 0) and this causes the ellipse to be
output at a counterclockwise angle relative to the bottom of the
page. The optional curves parameter is the
number of Bezier curves to use to draw the ellipse; the default is 8,
and this works well.
void Cpdf::filledRectangle(float
X, float Y, float width, float height)
Draws a color-filled rectangle with the bottom-left corner defined by
coordinates X and
Y and with a
width and
height. The coordinate X=0, Y=0 is the
bottom left of the page, and coordinates and dimensions are point
values.
float Cpdf::getFontDecender(int
size)
Returns the distance in negative points that the font descender (such
as the lower part of a g, y, or q) goes below the baseline for the
font size.
float Cpdf::getFontHeight(int
size)
Returns the distance in points of the font height for the font
size from the base of the font descender
(such as the lower pixel of a g, y, or q) to the top of a capitalized
character.
float Cpdf::getTextWidth(int
size, string text)
Returns the length in points of the text
for the font size.
void Cpdf::line(float
X0, float Y0, float X1, float Y1)
Draws a line from point X0,
Y0 to X1,
Y1. The coordinate X=0, Y=0 is the bottom
left of the page, and coordinates are point values.
void Cpdf::openHere(string
style [, float a [, float b, float c]])
Causes the document to begin at a specific page when it is opened;
the page that is used is the current page in the document when the
method is called. The style and other
parameters are described in Cpdf::addDestination(
).
int Cpdf::openObject( )
Starts an object and returns an identifier representing the object;
the return value must be saved in a variable for later use.
Having objects allows you to randomly access pages to add content.
Using this, you can complete earlier pages in the document after
writing later pages. For example, this is used internally by the page
numbering schemes described in the previous section to add the total
number of pages to each page.
When an object is started, all future writing to the PDF document
goes to this object rather than to the document itself until another
object is selected or the current object is closed. Several objects
may be open at once, and you can select a different object to write
to using Cpdf::reopenObject( ). Objects are
closed using Cpdf::closeObject( ) and after this
all future writes will go to the document (until another object is
selected or opened).
The Cpdf::addObject( ) method is used to add an
object to the document, and this allows you to add the object to more
than one page. You can call Cpdf::stopObject( )
to stop the adding of an object to the document and this allows you
to alter range of pages.
void Cpdf::partEllipse(float
X, float Y, angle A1, angle A2, float radius1 [, float radius2 [, float angle [, int curves]]])
Draws a partial ellipse or circle centered at the point
X, Y with a
horizontal radius of radius1 and an
optional vertical radius of radius2; if
radius2 is omitted, a circle is drawn. The
ellipse begins at a counterclockwise angle
A1 relative to the bottom of the page and
ends at angle A2.
The coordinate X=0, Y=0 is the bottom left of the page, and
coordinates are point values.
An optional angle in degrees can be
provided (by default it is 0) and this causes the ellipse to be
output at that counterclockwise angle relative to the bottom of the
page. The optional curves parameter is the
number of Bezier curves to use to draw the ellipse; the default is 8,
and this works well.
void Cpdf::polygon(array
points, int count [, int fill])
Draws a polygon using count pairs of
ordered coordinates from the array points.
For example, if the array points is defined as
array(10,10,10,40,20,40,20,10), four lines are
drawn to form a rectangle with its bottom-left corner at X=10, Y=10
and with a width of 10 and a height of 30. The optional
fill parameter can be set to 0 (no fill,
the default) or 1 (fill).
void Cpdf::rectangle(float
X, float Y, float width, float height)
Draws an unfilled rectangle with the bottom left corner defined by
coordinates X and
Y and with a
width and
height. The coordinate X=0, Y=0 is the
bottom left of the page, and coordinates and dimensions are point
values.
void Cpdf::reopenObject(int identifier)
Reopens or selects the object associated with
identifier that has previously been
created with Cpdf::addObject( ). The selected
object will then be used for all future output until it is either
closed or another object is selected. See
"Cpdf::openObject(
)" for a discussion of objects.
void Cpdf::selectFont(string
font_file [, mixed encoding])
Selects the font found in the file
font_file. The
font_file can be a relative or absolute
directory path, and must include the full filename of the fonts,
which must end in .afm. Both PostScript
Type 1 and TrueType fonts are supported.
The fonts Courier, Helvetica, php_Courier, php_Helvetica, php_Symbol,
php_Times, php_ZapfDingbats, Symbol, Times, Times-Roman, and
ZapfDingbats are distributed with the base class in the subdirectory
fonts. Without additional configuration (which
we do not discuss here), only the fonts provided with the class can
be used with the <b> and
<i> HTML-like markup in
Cpdf::addText( ).
The encoding parameter is used to change
the number-to-character mapping for a font. We do not discuss this
here, but more details on this experimental setting can be found in
the class manual.
void Cpdf::setColor(float
red, float green, float blue [, int force])
Sets the fill color to that defined by
red, green, and
blue. These parameters are values in the
range 0.0 to 1.0, where a setting of 0.0 for all three is black and a
setting of 1.0 for all three is white.
When set to 1, the force option causes the
color setting to be written into the PDF document even if it is the
same as the current fill color setting; the default of 0 has the
opposite behavior.
void Cpdf::setEncryption([string
user_password [, string author_password [, array options]])
Encrypts the document so that it cannot be printed, and so the user
cannot use cut (or copy) and paste and cannot alter the document.
This is the default behavior with no parameters.
If a user_password is provided, the user
must provide this before the document is displayed but they will
still be unable to carry out the selected actions. If an
owner_password is provided, the user must
provide this before the document is displayed and they will then be
able to use (edit and print) the document as usual.
The optional options array allows you to
define what actions the user can take on the document. For example,
an array
array(`print')
allows the user to print (if there is no password required, or after
providing the user_password). The options
are 'print', 'modify',
'copy', and 'add'.
void Cpdf::setLineStyle([int
width [, string cap [, string join [, array dash [, int phase]]]]])
Sets a new line drawing style for use with all drawing functions (for
ellipses, lines, curves, polygons, and rectangles). Without any
parameters, the method does nothing.
The width defines the width in points, and
the default is 1. The cap defines the end
type of the line and can be set to 'butt',
'round', or 'square'; the
default is 'butt'. The
join defines how lines are joined and can
be set to 'miter', 'round', or
'bevel'; the default is
'miter'.
The dash parameter is used to define a
dashed line and is an array that contains lengths of the dashes and
gaps between them in points; the default is no dashing. For example,
a dash parameter of
array(4,2,2,2) defines that a dash of length 4
is followed by a gap of length 4, and then a dash of length 2 is
followed by a gap of length 2, and then the sequence repeats. The
phase parameter defines where in the dash
array to start the processing of dashes; the default is at element 0.
If you want to change one or more parameters but not others, you can
leave out the other parameters that follow the parameter you want to
change, or set the previous parameters to '' for a
string or array parameter, and 0 for the
width parameter. For example, to change
the cap type to 'butt' without changing the other
parameters, use:
$doc->setLineStyle(0,'cap');
void Cpdf::setPreferences(mixed
label [, string value])
Sets document viewing preferences. If
label is a string, the
value parameter for that label is
required. If label is an array, it should
contain associative key labels and values for each of those labels.
To turn a label on, set the value to 1; to turn it off, set it to 0.
The possible labels are 'HideToolbar',
'HideMenuBar', 'HideWindowUI',
'FitWindow', 'CenterWindow',
'NonFullScreenPageMode', and
'Direction'.
For example, to hide the browser window user interface, use:
$doc->setPreferences(array('HideWindowUI' => 1));It is up to the browser to obey these settings (xpdf, for example,
ignores them).
Cpdf::setStrokeColor(float
red, float green, float blue [, int force])
Sets the line (stroke) color to that defined by
red, green, and
blue. These parameters are values in the
range 0.0 to 1.0, where a setting of 0.0 for all three is black and a
setting of 1.0 for all three is white.
When set to 1, the force option causes the
color setting to be written into the PDF document even if it is the
same as the current line color setting; the default of 0 has the
opposite behavior.
void Cpdf::stopObject(int
identifier)
Stop an object from appearing from the next page onwards. This allows
you to define an endpoint for the Cpdf::addObject(
) behavior during processing. Objects are discussed
further in the entry for Cpdf::openObject( ).
void Cpdf::transaction(string
action)
Allows you to treat a block in a PDF document as an indivisible unit,
in much the same way as the database transactions described in Chapter 15. The aim of this is to allow you try
different layouts until you find one that fits desirably on the page
or pages by, for example, varying table spacing or font sizes in
Cezpdf::ezTable( ).
To mark the beginning of output that you want to treat as a unit, you
start a transaction by providing 'start' as the
action.
To complete a transaction, and write it to the current document or
object, you provide 'commit' as the
action. This ends the most-recent
'start'.
To go back to the start point and begin again, use the
'rewind' option. To give up completely, use the
'abort' option. These affect the most recent
'start'.
Commands may be nested; that is, you can have
subtransactions.
