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 &lt;.

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.

Copyright eTutorials.org 2008-2024. All rights reserved.