summaryrefslogtreecommitdiff
path: root/doc/public/html/bindings-path.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/public/html/bindings-path.html')
-rw-r--r--doc/public/html/bindings-path.html117
1 files changed, 117 insertions, 0 deletions
diff --git a/doc/public/html/bindings-path.html b/doc/public/html/bindings-path.html
new file mode 100644
index 000000000..5810b39bb
--- /dev/null
+++ b/doc/public/html/bindings-path.html
@@ -0,0 +1,117 @@
+<!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: cairo_path_t</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-fonts.html" title="Fonts">
+<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-fonts.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
+<td><img src="right-insensitive.png" width="16" height="16" border="0"></td>
+</tr></table>
+<div class="sect1">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bindings-path"></a>cairo_path_t</h2></div></div></div>
+<p>
+ The <a class="link" href="cairo-Paths.html#cairo-path-t" title="cairo_path_t"><span class="type">cairo_path_t</span></a> type is one
+ area in which most language bindings will differ significantly
+ from the C API. The C API for <span class="type">cairo_path_t</span> is
+ designed for efficiency and to avoid auxiliary objects that
+ would be have to be manually memory managed by the
+ application. However,
+ a language binding should not present <span class="type">cairo_path_t</span> as an
+ array, but rather as an opaque that can be iterated
+ over. Different languages have quite different conventions for
+ how iterators work, so it is impossible to give an exact
+ specification for how this API should work, but the type names
+ and methods should be similar to the language's mapping of the following:
+ </p>
+<pre class="programlisting">
+typedef struct cairo_path_iterator cairo_path_iterator_t;
+typedef struct cairo_path_element cairo_path_element_t;
+
+cairo_path_iterator_t *
+cairo_path_get_iterator (cairo_path_t *path);
+
+cairo_bool_t
+cairo_path_iterator_has_next (cairo_path_iterator_t *iterator);
+
+cairo_path_element_t *
+cairo_path_iterator_next (cairo_path_iterator_t *iterator);
+
+cairo_path_element_type_t
+cairo_path_element_get_type (cairo_path_element_t *element);
+
+void
+cairo_path_element_get_point (cairo_path_element_t *element,
+ int index,
+ double *x,
+ double *y);
+ </pre>
+<p>
+ The above is written using the Java conventions for
+ iterators. To illustrate how the API for PathIterator might
+ depend on the native iteration conventions of the API, examine
+ three versions of the loop, first written in a hypothetical Java
+ binding:
+ </p>
+<pre class="programlisting">
+PathIterator iter = cr.copyPath().iterator();
+while (cr.hasNext()) {
+ PathElement element = iter.next();
+ if (element.getType() == PathElementType.MOVE_TO) {
+ Point p = element.getPoint(0);
+ doMoveTo (p.x, p.y);
+ }
+}</pre>
+<p>
+ And then in a hypothetical C++ binding:
+ </p>
+<pre class="programlisting">
+Path path = cr.copyPath();
+for (PathIterator iter = path.begin(); iter != path.end(); iter++) {
+ PathElement element = *iter;
+ if (element.getType() == PathElementType.MOVE_TO) {
+ Point p = element.getPoint(0);
+ doMoveTo (p.x, p.y);
+ }
+}</pre>
+<p>
+ And then finally in a Python binding:
+ </p>
+<pre class="programlisting">
+for element in cr.copy_path():
+ if element.getType == cairo.PATH_ELEMENT_MOVE_TO:
+ (x, y) = element.getPoint(0)
+ doMoveTo (x, y);</pre>
+<p>
+ While many of the API elements stay the same in the three
+ examples, the exact iteration mechanism is quite different, to
+ match how users of the language would expect to iterate over
+ a container.
+ </p>
+<p>
+ You should not present an API for mutating or for creating new
+ <span class="type">cairo_path_t</span> objects. In the future, these
+ guidelines may be extended to present an API for creating a
+ <span class="type">cairo_path_t</span> from scratch for use with
+ <a class="link" href="cairo-Paths.html#cairo-append-path" title="cairo_append_path ()"><code class="function">cairo_append_path()</code></a>
+ but the current expectation is that <code class="function">cairo_append_path()</code> will
+ mostly be used with paths from
+ <a class="link" href="cairo-Paths.html#cairo-append-path" title="cairo_append_path ()"><code class="function">cairo_copy_path()</code></a>.
+ </p>
+</div>
+<div class="footer">
+<hr>
+ Generated by GTK-Doc V1.20</div>
+</body>
+</html> \ No newline at end of file