mail-boxes-etc / lib / dompdf / src / Canvas.php

Canvas.php in MBE eShip trunk, at lib/dompdf/src/Canvas.php

478 lines 14.2 KB

Raw Download Zip

1	<?php
2	/**
3	* @package dompdf
4	* @link https://github.com/dompdf/dompdf
5	* @license http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License
6	*/
7	namespace Dompdf;
8
9	/**
10	* Main rendering interface
11	*
12	* Currently {@link Dompdf\Adapter\CPDF}, {@link Dompdf\Adapter\PDFLib}, and {@link Dompdf\Adapter\GD}
13	* implement this interface.
14	*
15	* Implementations should measure x and y increasing to the left and down,
16	* respectively, with the origin in the top left corner. Implementations
17	* are free to use a unit other than points for length, but I can't
18	* guarantee that the results will look any good.
19	*
20	* @package dompdf
21	*/
22	interface Canvas
23	{
24	/**
25	* @param string\|float[] $paper The paper size to use as either a standard paper size (see {@link Dompdf\Adapter\CPDF::$PAPER_SIZES})
26	* or an array of the form `[x1, y1, x2, y2]` (typically `[0, 0, width, height]`).
27	* @param string $orientation The paper orientation, either `portrait` or `landscape`.
28	* @param Dompdf $dompdf The Dompdf instance.
29	*/
30	public function __construct($paper = "letter", $orientation = "portrait", ?Dompdf $dompdf = null);
31
32	/**
33	* @return Dompdf
34	*/
35	function get_dompdf();
36
37	/**
38	* Returns the current page number
39	*
40	* @return int
41	*/
42	function get_page_number();
43
44	/**
45	* Returns the total number of pages in the document
46	*
47	* @return int
48	*/
49	function get_page_count();
50
51	/**
52	* Sets the total number of pages
53	*
54	* @param int $count
55	*/
56	function set_page_count($count);
57
58	/**
59	* Draws a line from x1,y1 to x2,y2
60	*
61	* See {@link Cpdf::setLineStyle()} for a description of the format of the
62	* $style and $cap parameters (aka dash and cap).
63	*
64	* @param float $x1
65	* @param float $y1
66	* @param float $x2
67	* @param float $y2
68	* @param array $color Color array in the format `[r, g, b, "alpha" => alpha]`
69	* where r, g, b, and alpha are float values between 0 and 1
70	* @param float $width
71	* @param array $style
72	* @param string $cap `butt`, `round`, or `square`
73	*/
74	function line($x1, $y1, $x2, $y2, $color, $width, $style = [], $cap = "butt");
75
76	/**
77	* Draws an arc
78	*
79	* See {@link Cpdf::setLineStyle()} for a description of the format of the
80	* $style and $cap parameters (aka dash and cap).
81	*
82	* @param float $x X coordinate of the arc
83	* @param float $y Y coordinate of the arc
84	* @param float $r1 Radius 1
85	* @param float $r2 Radius 2
86	* @param float $astart Start angle in degrees
87	* @param float $aend End angle in degrees
88	* @param array $color Color array in the format `[r, g, b, "alpha" => alpha]`
89	* where r, g, b, and alpha are float values between 0 and 1
90	* @param float $width
91	* @param array $style
92	* @param string $cap `butt`, `round`, or `square`
93	*/
94	function arc($x, $y, $r1, $r2, $astart, $aend, $color, $width, $style = [], $cap = "butt");
95
96	/**
97	* Draws a rectangle at x1,y1 with width w and height h
98	*
99	* See {@link Cpdf::setLineStyle()} for a description of the format of the
100	* $style and $cap parameters (aka dash and cap).
101	*
102	* @param float $x1
103	* @param float $y1
104	* @param float $w
105	* @param float $h
106	* @param array $color Color array in the format `[r, g, b, "alpha" => alpha]`
107	* where r, g, b, and alpha are float values between 0 and 1
108	* @param float $width
109	* @param array $style
110	* @param string $cap `butt`, `round`, or `square`
111	*/
112	function rectangle($x1, $y1, $w, $h, $color, $width, $style = [], $cap = "butt");
113
114	/**
115	* Draws a filled rectangle at x1,y1 with width w and height h
116	*
117	* @param float $x1
118	* @param float $y1
119	* @param float $w
120	* @param float $h
121	* @param array $color Color array in the format `[r, g, b, "alpha" => alpha]`
122	* where r, g, b, and alpha are float values between 0 and 1
123	*/
124	function filled_rectangle($x1, $y1, $w, $h, $color);
125
126	/**
127	* Starts a clipping rectangle at x1,y1 with width w and height h
128	*
129	* @param float $x1
130	* @param float $y1
131	* @param float $w
132	* @param float $h
133	*/
134	function clipping_rectangle($x1, $y1, $w, $h);
135
136	/**
137	* Starts a rounded clipping rectangle at x1,y1 with width w and height h
138	*
139	* @param float $x1
140	* @param float $y1
141	* @param float $w
142	* @param float $h
143	* @param float $tl
144	* @param float $tr
145	* @param float $br
146	* @param float $bl
147	*/
148	function clipping_roundrectangle($x1, $y1, $w, $h, $tl, $tr, $br, $bl);
149
150	/**
151	* Starts a clipping polygon
152	*
153	* @param float[] $points
154	*/
155	public function clipping_polygon(array $points): void;
156
157	/**
158	* Ends the last clipping shape
159	*/
160	function clipping_end();
161
162	/**
163	* Processes a callback on every page.
164	*
165	* The callback function receives the four parameters `int $pageNumber`,
166	* `int $pageCount`, `Canvas $canvas`, and `FontMetrics $fontMetrics`, in
167	* that order.
168	*
169	* This function can be used to add page numbers to all pages after the
170	* first one, for example.
171	*
172	* @param callable $callback The callback function to process on every page
173	*/
174	public function page_script($callback): void;
175
176	/**
177	* Writes text at the specified x and y coordinates on every page.
178	*
179	* The strings '{PAGE_NUM}' and '{PAGE_COUNT}' are automatically replaced
180	* with their current values.
181	*
182	* @param float $x
183	* @param float $y
184	* @param string $text The text to write
185	* @param string $font The font file to use
186	* @param float $size The font size, in points
187	* @param array $color Color array in the format `[r, g, b, "alpha" => alpha]`
188	* where r, g, b, and alpha are float values between 0 and 1
189	* @param float $word_space Word spacing adjustment
190	* @param float $char_space Char spacing adjustment
191	* @param float $angle Angle to write the text at, measured clockwise starting from the x-axis
192	*/
193	public function page_text($x, $y, $text, $font, $size, $color = [0, 0, 0], $word_space = 0.0, $char_space = 0.0, $angle = 0.0);
194
195	/**
196	* Draws a line at the specified coordinates on every page.
197	*
198	* @param float $x1
199	* @param float $y1
200	* @param float $x2
201	* @param float $y2
202	* @param array $color Color array in the format `[r, g, b, "alpha" => alpha]`
203	* where r, g, b, and alpha are float values between 0 and 1
204	* @param float $width
205	* @param array $style
206	*/
207	public function page_line($x1, $y1, $x2, $y2, $color, $width, $style = []);
208
209	/**
210	* Save current state
211	*/
212	function save();
213
214	/**
215	* Restore last state
216	*/
217	function restore();
218
219	/**
220	* Rotate
221	*
222	* @param float $angle angle in degrees for counter-clockwise rotation
223	* @param float $x Origin abscissa
224	* @param float $y Origin ordinate
225	*/
226	function rotate($angle, $x, $y);
227
228	/**
229	* Skew
230	*
231	* @param float $angle_x
232	* @param float $angle_y
233	* @param float $x Origin abscissa
234	* @param float $y Origin ordinate
235	*/
236	function skew($angle_x, $angle_y, $x, $y);
237
238	/**
239	* Scale
240	*
241	* @param float $s_x scaling factor for width as percent
242	* @param float $s_y scaling factor for height as percent
243	* @param float $x Origin abscissa
244	* @param float $y Origin ordinate
245	*/
246	function scale($s_x, $s_y, $x, $y);
247
248	/**
249	* Translate
250	*
251	* @param float $t_x movement to the right
252	* @param float $t_y movement to the bottom
253	*/
254	function translate($t_x, $t_y);
255
256	/**
257	* Transform
258	*
259	* @param float $a
260	* @param float $b
261	* @param float $c
262	* @param float $d
263	* @param float $e
264	* @param float $f
265	*/
266	function transform($a, $b, $c, $d, $e, $f);
267
268	/**
269	* Draws a polygon
270	*
271	* The polygon is formed by joining all the points stored in the $points
272	* array. $points has the following structure:
273	* ```
274	* array(0 => x1,
275	* 1 => y1,
276	* 2 => x2,
277	* 3 => y2,
278	* ...
279	* );
280	* ```
281	*
282	* See {@link Cpdf::setLineStyle()} for a description of the format of the
283	* $style parameter (aka dash).
284	*
285	* @param array $points
286	* @param array $color Color array in the format `[r, g, b, "alpha" => alpha]`
287	* where r, g, b, and alpha are float values between 0 and 1
288	* @param float $width
289	* @param array $style
290	* @param bool $fill Fills the polygon if true
291	*/
292	function polygon($points, $color, $width = null, $style = [], $fill = false);
293
294	/**
295	* Draws a circle at $x,$y with radius $r
296	*
297	* See {@link Cpdf::setLineStyle()} for a description of the format of the
298	* $style parameter (aka dash).
299	*
300	* @param float $x
301	* @param float $y
302	* @param float $r
303	* @param array $color Color array in the format `[r, g, b, "alpha" => alpha]`
304	* where r, g, b, and alpha are float values between 0 and 1
305	* @param float $width
306	* @param array $style
307	* @param bool $fill Fills the circle if true
308	*/
309	function circle($x, $y, $r, $color, $width = null, $style = [], $fill = false);
310
311	/**
312	* Add an image to the pdf.
313	*
314	* The image is placed at the specified x and y coordinates with the
315	* given width and height.
316	*
317	* @param string $img The path to the image
318	* @param float $x X position
319	* @param float $y Y position
320	* @param float $w Width
321	* @param float $h Height
322	* @param string $resolution The resolution of the image
323	*/
324	function image($img, $x, $y, $w, $h, $resolution = "normal");
325
326	/**
327	* Writes text at the specified x and y coordinates
328	*
329	* @param float $x
330	* @param float $y
331	* @param string $text The text to write
332	* @param string $font The font file to use
333	* @param float $size The font size, in points
334	* @param array $color Color array in the format `[r, g, b, "alpha" => alpha]`
335	* where r, g, b, and alpha are float values between 0 and 1
336	* @param float $word_space Word spacing adjustment
337	* @param float $char_space Char spacing adjustment
338	* @param float $angle Angle to write the text at, measured clockwise starting from the x-axis
339	*/
340	function text($x, $y, $text, $font, $size, $color = [0, 0, 0], $word_space = 0.0, $char_space = 0.0, $angle = 0.0);
341
342	/**
343	* Add a named destination (similar to <a name="foo">...</a> in html)
344	*
345	* @param string $anchorname The name of the named destination
346	*/
347	function add_named_dest($anchorname);
348
349	/**
350	* Add a link to the pdf
351	*
352	* @param string $url The url to link to
353	* @param float $x The x position of the link
354	* @param float $y The y position of the link
355	* @param float $width The width of the link
356	* @param float $height The height of the link
357	*/
358	function add_link($url, $x, $y, $width, $height);
359
360	/**
361	* Add meta information to the PDF.
362	*
363	* @param string $label Label of the value (Creator, Producer, etc.)
364	* @param string $value The text to set
365	*/
366	public function add_info(string $label, string $value): void;
367
368	/**
369	* Calculates text size, in points
370	*
371	* @param string $text The text to be sized
372	* @param string $font The font file to use
373	* @param float $size The font size, in points
374	* @param float $word_spacing Word spacing, if any
375	* @param float $char_spacing Char spacing, if any
376	*
377	* @return float
378	*/
379	function get_text_width($text, $font, $size, $word_spacing = 0.0, $char_spacing = 0.0);
380
381	/**
382	* Calculates font height, in points
383	*
384	* @param string $font The font file to use
385	* @param float $size The font size, in points
386	*
387	* @return float
388	*/
389	function get_font_height($font, $size);
390
391	/**
392	* Returns the font x-height, in points
393	*
394	* @param string $font The font file to use
395	* @param float $size The font size, in points
396	*
397	* @return float
398	*/
399	//function get_font_x_height($font, $size);
400
401	/**
402	* Calculates font baseline, in points
403	*
404	* @param string $font The font file to use
405	* @param float $size The font size, in points
406	*
407	* @return float
408	*/
409	function get_font_baseline($font, $size);
410
411	/**
412	* Returns the PDF's width in points
413	*
414	* @return float
415	*/
416	function get_width();
417
418	/**
419	* Returns the PDF's height in points
420	*
421	* @return float
422	*/
423	function get_height();
424
425	/**
426	* Sets the opacity
427	*
428	* @param float $opacity
429	* @param string $mode
430	*/
431	public function set_opacity(float $opacity, string $mode = "Normal"): void;
432
433	/**
434	* Sets the default view
435	*
436	* @param string $view
437	* 'XYZ' left, top, zoom
438	* 'Fit'
439	* 'FitH' top
440	* 'FitV' left
441	* 'FitR' left,bottom,right
442	* 'FitB'
443	* 'FitBH' top
444	* 'FitBV' left
445	* @param array $options
446	*/
447	function set_default_view($view, $options = []);
448
449	/**
450	* @param string $code
451	*/
452	function javascript($code);
453
454	/**
455	* Starts a new page
456	*
457	* Subsequent drawing operations will appear on the new page.
458	*/
459	function new_page();
460
461	/**
462	* Streams the PDF to the client.
463	*
464	* @param string $filename The filename to present to the client.
465	* @param array $options Associative array: 'compress' => 1 or 0 (default 1); 'Attachment' => 1 or 0 (default 1).
466	*/
467	function stream($filename, $options = []);
468
469	/**
470	* Returns the PDF as a string.
471	*
472	* @param array $options Associative array: 'compress' => 1 or 0 (default 1).
473	*
474	* @return string
475	*/
476	function output($options = []);
477	}
478