diff options
Diffstat (limited to 'doc/public/html/bindings-return-values.html')
-rw-r--r-- | doc/public/html/bindings-return-values.html | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/doc/public/html/bindings-return-values.html b/doc/public/html/bindings-return-values.html new file mode 100644 index 000000000..1b48308dc --- /dev/null +++ b/doc/public/html/bindings-return-values.html @@ -0,0 +1,120 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>Cairo: A Vector Graphics Library: Multiple return values</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> +<link rel="home" href="index.html" title="Cairo: A Vector Graphics Library"> +<link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo"> +<link rel="prev" href="bindings-memory.html" title="Memory management"> +<link rel="next" href="bindings-overloading.html" title="Overloading and optional arguments"> +<meta name="generator" content="GTK-Doc V1.20 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="10"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"></td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="bindings-memory.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="bindings-overloading.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="sect1"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="bindings-return-values"></a>Multiple return values</h2></div></div></div> +<p> + There are a number of functions in the cairo API that have + multiple <em class="firstterm">out parameters</em> or + <em class="firstterm">in-out parameters</em>. In some languages + these can be translated into multiple return values. In Python, + what is: + </p> +<pre class="programlisting"> +cairo_user_to_device (cr, &x, &y);</pre> +<p> + can by mapped to: + </p> +<pre class="programlisting"> +(x, y) = cr.user_to_device (cr, x, y);</pre> +<p> + but many languages don't have provisions for multiple return + values, so it is necessary to introduce auxiliary types. + Most of the functions that require the auxiliary types + require a type that would, in C, look like + </p> +<pre class="programlisting"> +typedef struct _cairo_point cairo_point_t; +struct _cairo_point { + double x; + double y; +}</pre> +<p> + The same type should be used both for functions that use a pair + of coordinates as an absolute position, and functions that use + a pair of coordinates as a displacement. While an argument could + be made that having a separate “distance” type is more correct, + it is more likely just to confuse users. + </p> +<pre class="programlisting"> +void +cairo_user_to_device (cairo_t *cr, double *x, double *y); + +void +cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy); + +void +cairo_device_to_user (cairo_t *cr, double *x, double *y); + +void +cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy); + +void +cairo_matrix_transform_distance (cairo_matrix_t *matrix, double *dx, double *dy); + +void +cairo_matrix_transform_point (cairo_matrix_t *matrix, double *x, double *y); + +void +cairo_get_current_point (cairo_t *cr, double *x, double *y); + </pre> +<p> + There are also a couple of functions that return four values + representing a rectangle. These should be mapped to a + “rectangle” type that looks like: + </p> +<pre class="programlisting"> +typedef struct _cairo_rectangle cairo_rectangle_t; +struct _cairo_rectangle { + double x; + double y; + double width; + double height; +}</pre> +<p> + The C function returns the rectangle as a set of two points to + facilitate rounding to integral extents, but this isn't worth + adding a “box” type to go along with the more obvious + “rectangle” representation. + </p> +<p class="remark"><em><span class="remark"> + Q: Would it make sense here to define a standard + <code class="function">cairo_rectangle_round()</code> method + that language bindings should map? + </span></em></p> +<pre class="programlisting"> +void +cairo_stroke_extents (cairo_t *cr, + double *x1, double *y1, + double *x2, double *y2); + +void +cairo_fill_extents (cairo_t *cr, + double *x1, double *y1, + double *x2, double *y2); + </pre> +</div> +<div class="footer"> +<hr> + Generated by GTK-Doc V1.20</div> +</body> +</html>
\ No newline at end of file |