1 <?php

     2 /**

     3  * Zend Framework

     4  *

     5  * LICENSE

     6  *

     7  * This source file is subject to the new BSD license that is bundled

     8  * with this package in the file LICENSE.txt.

     9  * It is also available through the world-wide-web at this URL:

    10  * http://framework.zend.com/license/new-bsd

    11  * If you did not receive a copy of the license and are unable to

    12  * obtain it through the world-wide-web, please send an email

    13  * to license@zend.com so we can send you a copy immediately.

    14  *

    15  * @category   Zend

    16  * @package    Zend_Pdf

    17  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    18  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    19  * @version    $Id: Style.php 20096 2010-01-06 02:05:09Z bkarwin $

    20  */

    21 

    22 

    23 /**

    24  * Canvas is an abstract rectangle drawing area which can be dropped into

    25  * page object at specified place.

    26  *

    27  * @package    Zend_Pdf

    28  * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

    29  * @license    http://framework.zend.com/license/new-bsd     New BSD License

    30  */

    31 interface Zend_Pdf_Canvas_Interface

    32 {

    33     /**

    34      * Returns dictionaries of used resources.

    35      *

    36      * Used for canvas implementations interoperability

    37      *

    38      * Structure of the returned array:

    39      * array(

    40      *   <resTypeName> => array(

    41      *                      <resName> => <Zend_Pdf_Resource object>,

    42      *                      <resName> => <Zend_Pdf_Resource object>,

    43      *                      <resName> => <Zend_Pdf_Resource object>,

    44      *                      ...

    45      *                    ),

    46      *   <resTypeName> => array(

    47      *                      <resName> => <Zend_Pdf_Resource object>,

    48      *                      <resName> => <Zend_Pdf_Resource object>,

    49      *                      <resName> => <Zend_Pdf_Resource object>,

    50      *                      ...

    51      *                    ),

    52      *   ...

    53      *   'ProcSet' => array()

    54      * )

    55      *

    56      * where ProcSet array is a list of used procedure sets names (strings).

    57      * Allowed procedure set names: 'PDF', 'Text', 'ImageB', 'ImageC', 'ImageI'

    58      *

    59      * @internal

    60      * @return array

    61      */

    62     public function getResources();

    63 

    64     /**

    65      * Get drawing instructions stream

    66      *

    67      * It has to be returned as a PDF stream object to make it reusable.

    68      *

    69      * @internal

    70      * @returns Zend_Pdf_Resource_ContentStream

    71      */

    72     public function getContents();

    73 

    74     /**

    75      * Return canvas height.

    76      *

    77      * @return float

    78      */

    79     public function getHeight();

    80 

    81     /**

    82      * Return canvas width.

    83      *

    84      * @return float

    85      */

    86     public function getWidth();

    87 

    88     /**

    89      * Draw a canvas at the specified location

    90      *

    91      * If upper right corner is not specified then canvas heght and width

    92      * are used.

    93      *

    94      * @param Zend_Pdf_Canvas_Interface $canvas

    95      * @param float $x1

    96      * @param float $y1

    97      * @param float $x2

    98      * @param float $y2

    99      * @return Zend_Pdf_Canvas_Interface

   100      */

   101     public function drawCanvas(Zend_Pdf_Canvas_Interface $canvas, $x1, $y1, $x2 = null, $y2 = null);

   102 

   103     /**

   104      * Set fill color.

   105      *

   106      * @param Zend_Pdf_Color $color

   107      * @return Zend_Pdf_Canvas_Interface

   108      */

   109     public function setFillColor(Zend_Pdf_Color $color);

   110 

   111     /**

   112      * Set line color.

   113      *

   114      * @param Zend_Pdf_Color $color

   115      * @return Zend_Pdf_Canvas_Interface

   116      */

   117     public function setLineColor(Zend_Pdf_Color $color);

   118 

   119     /**

   120      * Set line width.

   121      *

   122      * @param float $width

   123      * @return Zend_Pdf_Canvas_Interface

   124      */

   125     public function setLineWidth($width);

   126 

   127     /**

   128      * Set line dashing pattern

   129      *

   130      * Pattern is an array of floats: array(on_length, off_length, on_length, off_length, ...)

   131      * or Zend_Pdf_Page::LINE_DASHING_SOLID constant

   132      * Phase is shift from the beginning of line.

   133      *

   134      * @param mixed $pattern

   135      * @param array $phase

   136      * @return Zend_Pdf_Canvas_Interface

   137      */

   138     public function setLineDashingPattern($pattern, $phase = 0);

   139 

   140     /**

   141      * Set current font.

   142      *

   143      * @param Zend_Pdf_Resource_Font $font

   144      * @param float $fontSize

   145      * @return Zend_Pdf_Canvas_Interface

   146      */

   147     public function setFont(Zend_Pdf_Resource_Font $font, $fontSize);

   148 

   149     /**

   150      * Set the style to use for future drawing operations on this page

   151      *

   152      * @param Zend_Pdf_Style $style

   153      * @return Zend_Pdf_Canvas_Interface

   154      */

   155     public function setStyle(Zend_Pdf_Style $style);

   156 

   157     /**

   158      * Get current font.

   159      *

   160      * @return Zend_Pdf_Resource_Font $font

   161      */

   162     public function getFont();

   163 

   164     /**

   165      * Get current font size

   166      *

   167      * @return float $fontSize

   168      */

   169     public function getFontSize();

   170 

   171     /**

   172      * Return the style, applied to the page.

   173      *

   174      * @return Zend_Pdf_Style|null

   175      */

   176     public function getStyle();

   177 

   178     /**

   179      * Save the graphics state of this page.

   180      * This takes a snapshot of the currently applied style, position, clipping area and

   181      * any rotation/translation/scaling that has been applied.

   182      *

   183      * @throws Zend_Pdf_Exception    - if a save is performed with an open path

   184      * @return Zend_Pdf_Page

   185      */

   186     public function saveGS();

   187 

   188     /**

   189      * Set the transparancy

   190      *

   191      * $alpha == 0  - transparent

   192      * $alpha == 1  - opaque

   193      *

   194      * Transparency modes, supported by PDF:

   195      * Normal (default), Multiply, Screen, Overlay, Darken, Lighten, ColorDodge, ColorBurn, HardLight,

   196      * SoftLight, Difference, Exclusion

   197      *

   198      * @param float $alpha

   199      * @param string $mode

   200      * @throws Zend_Pdf_Exception

   201      * @return Zend_Pdf_Canvas_Interface

   202      */

   203     public function setAlpha($alpha, $mode = 'Normal');

   204 

   205     /**

   206      * Intersect current clipping area with a circle.

   207      *

   208      * @param float $x

   209      * @param float $y

   210      * @param float $radius

   211      * @param float $startAngle

   212      * @param float $endAngle

   213      * @return Zend_Pdf_Canvas_Interface

   214      */

   215     public function clipCircle($x, $y, $radius, $startAngle = null, $endAngle = null);

   216 

   217     /**

   218      * Intersect current clipping area with a polygon.

   219      *

   220      * Method signatures:

   221      * drawEllipse($x1, $y1, $x2, $y2);

   222      * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);

   223      *

   224      * @todo process special cases with $x2-$x1 == 0 or $y2-$y1 == 0

   225      *

   226      * @param float $x1

   227      * @param float $y1

   228      * @param float $x2

   229      * @param float $y2

   230      * @param float $startAngle

   231      * @param float $endAngle

   232      * @return Zend_Pdf_Canvas_Interface

   233      */

   234     public function clipEllipse($x1, $y1, $x2, $y2, $startAngle = null, $endAngle = null);

   235 

   236     /**

   237      * Intersect current clipping area with a polygon.

   238      *

   239      * @param array $x  - array of float (the X co-ordinates of the vertices)

   240      * @param array $y  - array of float (the Y co-ordinates of the vertices)

   241      * @param integer $fillMethod

   242      * @return Zend_Pdf_Canvas_Interface

   243      */

   244     public function clipPolygon($x, $y, $fillMethod = Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING);

   245 

   246     /**

   247      * Intersect current clipping area with a rectangle.

   248      *

   249      * @param float $x1

   250      * @param float $y1

   251      * @param float $x2

   252      * @param float $y2

   253      * @return Zend_Pdf_Canvas_Interface

   254      */

   255     public function clipRectangle($x1, $y1, $x2, $y2);

   256 

   257     /**

   258      * Draw a circle centered on x, y with a radius of radius.

   259      *

   260      * Method signatures:

   261      * drawCircle($x, $y, $radius);

   262      * drawCircle($x, $y, $radius, $fillType);

   263      * drawCircle($x, $y, $radius, $startAngle, $endAngle);

   264      * drawCircle($x, $y, $radius, $startAngle, $endAngle, $fillType);

   265      *

   266      *

   267      * It's not a really circle, because PDF supports only cubic Bezier curves.

   268      * But _very_ good approximation.

   269      * It differs from a real circle on a maximum 0.00026 radiuses

   270      * (at PI/8, 3*PI/8, 5*PI/8, 7*PI/8, 9*PI/8, 11*PI/8, 13*PI/8 and 15*PI/8 angles).

   271      * At 0, PI/4, PI/2, 3*PI/4, PI, 5*PI/4, 3*PI/2 and 7*PI/4 it's exactly a tangent to a circle.

   272      *

   273      * @param float $x

   274      * @param float $y

   275      * @param float $radius

   276      * @param mixed $param4

   277      * @param mixed $param5

   278      * @param mixed $param6

   279      * @return Zend_Pdf_Canvas_Interface

   280      */

   281     public function  drawCircle($x, $y, $radius, $param4 = null, $param5 = null, $param6 = null);

   282 

   283     /**

   284      * Draw an ellipse inside the specified rectangle.

   285      *

   286      * Method signatures:

   287      * drawEllipse($x1, $y1, $x2, $y2);

   288      * drawEllipse($x1, $y1, $x2, $y2, $fillType);

   289      * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle);

   290      * drawEllipse($x1, $y1, $x2, $y2, $startAngle, $endAngle, $fillType);

   291      *

   292      * @todo process special cases with $x2-$x1 == 0 or $y2-$y1 == 0

   293      *

   294      * @param float $x1

   295      * @param float $y1

   296      * @param float $x2

   297      * @param float $y2

   298      * @param mixed $param5

   299      * @param mixed $param6

   300      * @param mixed $param7

   301      * @return Zend_Pdf_Canvas_Interface

   302      */

   303     public function drawEllipse($x1, $y1, $x2, $y2, $param5 = null, $param6 = null, $param7 = null);

   304 

   305     /**

   306      * Draw an image at the specified position on the page.

   307      *

   308      * @param Zend_Pdf_Image $image

   309      * @param float $x1

   310      * @param float $y1

   311      * @param float $x2

   312      * @param float $y2

   313      * @return Zend_Pdf_Canvas_Interface

   314      */

   315     public function drawImage(Zend_Pdf_Resource_Image $image, $x1, $y1, $x2, $y2);

   316 

   317     /**

   318      * Draw a LayoutBox at the specified position on the page.

   319      *

   320      * @internal (not implemented now)

   321      *

   322      * @param Zend_Pdf_Element_LayoutBox $box

   323      * @param float $x

   324      * @param float $y

   325      * @return Zend_Pdf_Canvas_Interface

   326      */

   327     public function drawLayoutBox($box, $x, $y);

   328 

   329     /**

   330      * Draw a line from x1,y1 to x2,y2.

   331      *

   332      * @param float $x1

   333      * @param float $y1

   334      * @param float $x2

   335      * @param float $y2

   336      * @return Zend_Pdf_Canvas_Interface

   337      */

   338     public function drawLine($x1, $y1, $x2, $y2);

   339 

   340     /**

   341      * Draw a polygon.

   342      *

   343      * If $fillType is Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE or

   344      * Zend_Pdf_Page::SHAPE_DRAW_FILL, then polygon is automatically closed.

   345      * See detailed description of these methods in a PDF documentation

   346      * (section 4.4.2 Path painting Operators, Filling)

   347      *

   348      * @param array $x  - array of float (the X co-ordinates of the vertices)

   349      * @param array $y  - array of float (the Y co-ordinates of the vertices)

   350      * @param integer $fillType

   351      * @param integer $fillMethod

   352      * @return Zend_Pdf_Canvas_Interface

   353      */

   354     public function drawPolygon($x, $y,

   355                                 $fillType = Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE,

   356                                 $fillMethod = Zend_Pdf_Page::FILL_METHOD_NON_ZERO_WINDING);

   357     /**

   358      * Draw a rectangle.

   359      *

   360      * Fill types:

   361      * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fill rectangle and stroke (default)

   362      * Zend_Pdf_Page::SHAPE_DRAW_STROKE      - stroke rectangle

   363      * Zend_Pdf_Page::SHAPE_DRAW_FILL        - fill rectangle

   364      *

   365      * @param float $x1

   366      * @param float $y1

   367      * @param float $x2

   368      * @param float $y2

   369      * @param integer $fillType

   370      * @return Zend_Pdf_Canvas_Interface

   371      */

   372     public function drawRectangle($x1, $y1, $x2, $y2, $fillType = Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE);

   373 

   374     /**

   375      * Draw a rounded rectangle.

   376      *

   377      * Fill types:

   378      * Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE - fill rectangle and stroke (default)

   379      * Zend_Pdf_Page::SHAPE_DRAW_STROKE      - stroke rectangle

   380      * Zend_Pdf_Page::SHAPE_DRAW_FILL        - fill rectangle

   381      *

   382      * radius is an integer representing radius of the four corners, or an array

   383      * of four integers representing the radius starting at top left, going

   384      * clockwise

   385      *

   386      * @param float $x1

   387      * @param float $y1

   388      * @param float $x2

   389      * @param float $y2

   390      * @param integer|array $radius

   391      * @param integer $fillType

   392      * @return Zend_Pdf_Canvas_Interface

   393      */

   394     public function drawRoundedRectangle($x1, $y1, $x2, $y2, $radius,

   395                                          $fillType = Zend_Pdf_Page::SHAPE_DRAW_FILL_AND_STROKE);

   396 

   397     /**

   398      * Draw a line of text at the specified position.

   399      *

   400      * @param string $text

   401      * @param float $x

   402      * @param float $y

   403      * @param string $charEncoding (optional) Character encoding of source text.

   404      *   Defaults to current locale.

   405      * @throws Zend_Pdf_Exception

   406      * @return Zend_Pdf_Canvas_Interface

   407      */

   408     public function drawText($text, $x, $y, $charEncoding = '');

   409 

   410      /**

   411      * Close the path by drawing a straight line back to it's beginning.

   412      *

   413      * @internal (needs implementation)

   414      *

   415      * @throws Zend_Pdf_Exception    - if a path hasn't been started with pathMove()

   416      * @return Zend_Pdf_Canvas_Interface

   417      */

   418     public function pathClose();

   419 

   420     /**

   421      * Continue the open path in a straight line to the specified position.

   422      *

   423      * @internal (needs implementation)

   424      *

   425      * @param float $x  - the X co-ordinate to move to

   426      * @param float $y  - the Y co-ordinate to move to

   427      * @return Zend_Pdf_Canvas_Interface

   428      */

   429     public function pathLine($x, $y);

   430 

   431     /**

   432      * Start a new path at the specified position. If a path has already been started,

   433      * move the cursor without drawing a line.

   434      *

   435      * @internal (needs implementation)

   436      *

   437      * @param float $x  - the X co-ordinate to move to

   438      * @param float $y  - the Y co-ordinate to move to

   439      * @return Zend_Pdf_Canvas_Interface

   440      */

   441     public function pathMove($x, $y);

   442 

   443     /**

   444      * Rotate the page.

   445      *

   446      * @param float $x  - the X co-ordinate of rotation point

   447      * @param float $y  - the Y co-ordinate of rotation point

   448      * @param float $angle - rotation angle

   449      * @return Zend_Pdf_Canvas_Interface

   450      */

   451     public function rotate($x, $y, $angle);

   452 

   453     /**

   454      * Scale coordination system.

   455      *

   456      * @param float $xScale - X dimention scale factor

   457      * @param float $yScale - Y dimention scale factor

   458      * @return Zend_Pdf_Canvas_Interface

   459      */

   460     public function scale($xScale, $yScale);

   461 

   462     /**

   463      * Translate coordination system.

   464      *

   465      * @param float $xShift - X coordinate shift

   466      * @param float $yShift - Y coordinate shift

   467      * @return Zend_Pdf_Canvas_Interface

   468      */

   469     public function translate($xShift, $yShift);

   470 

   471     /**

   472      * Translate coordination system.

   473      *

   474      * @param float $x  - the X co-ordinate of axis skew point

   475      * @param float $y  - the Y co-ordinate of axis skew point

   476      * @param float $xAngle - X axis skew angle

   477      * @param float $yAngle - Y axis skew angle

   478      * @return Zend_Pdf_Canvas_Interface

   479      */

   480     public function skew($x, $y, $xAngle, $yAngle);

   481 

   482     /**

   483      * Writes the raw data to the page's content stream.

   484      *

   485      * Be sure to consult the PDF reference to ensure your syntax is correct. No

   486      * attempt is made to ensure the validity of the stream data.

   487      *

   488      * @param string $data

   489      * @param string $procSet (optional) Name of ProcSet to add.

   490      * @return Zend_Pdf_Canvas_Interface

   491      */

   492     public function rawWrite($data, $procSet = null);

   493 }