Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/gtk-doc/html/cairo/bindings-path.html @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
jpayne@68 2 <html>
jpayne@68 3 <head>
jpayne@68 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
jpayne@68 5 <title>cairo_path_t: Cairo: A Vector Graphics Library</title>
jpayne@68 6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
jpayne@68 7 <link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
jpayne@68 8 <link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
jpayne@68 9 <link rel="prev" href="bindings-fonts.html" title="Fonts">
jpayne@68 10 <meta name="generator" content="GTK-Doc V1.27 (XML mode)">
jpayne@68 11 <link rel="stylesheet" href="style.css" type="text/css">
jpayne@68 12 </head>
jpayne@68 13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
jpayne@68 14 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
jpayne@68 15 <td width="100%" align="left" class="shortcuts"></td>
jpayne@68 16 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
jpayne@68 17 <td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
jpayne@68 18 <td><a accesskey="p" href="bindings-fonts.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
jpayne@68 19 <td><img src="right-insensitive.png" width="16" height="16" border="0"></td>
jpayne@68 20 </tr></table>
jpayne@68 21 <div class="sect1">
jpayne@68 22 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
jpayne@68 23 <a name="bindings-path"></a>cairo_path_t</h2></div></div></div>
jpayne@68 24 <p>
jpayne@68 25 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
jpayne@68 26 area in which most language bindings will differ significantly
jpayne@68 27 from the C API. The C API for <span class="type">cairo_path_t</span> is
jpayne@68 28 designed for efficiency and to avoid auxiliary objects that
jpayne@68 29 would be have to be manually memory managed by the
jpayne@68 30 application. However,
jpayne@68 31 a language binding should not present <span class="type">cairo_path_t</span> as an
jpayne@68 32 array, but rather as an opaque that can be iterated
jpayne@68 33 over. Different languages have quite different conventions for
jpayne@68 34 how iterators work, so it is impossible to give an exact
jpayne@68 35 specification for how this API should work, but the type names
jpayne@68 36 and methods should be similar to the language's mapping of the following:
jpayne@68 37 </p>
jpayne@68 38 <pre class="programlisting">
jpayne@68 39 typedef struct cairo_path_iterator cairo_path_iterator_t;
jpayne@68 40 typedef struct cairo_path_element cairo_path_element_t;
jpayne@68 41
jpayne@68 42 cairo_path_iterator_t *
jpayne@68 43 cairo_path_get_iterator (cairo_path_t *path);
jpayne@68 44
jpayne@68 45 cairo_bool_t
jpayne@68 46 cairo_path_iterator_has_next (cairo_path_iterator_t *iterator);
jpayne@68 47
jpayne@68 48 cairo_path_element_t *
jpayne@68 49 cairo_path_iterator_next (cairo_path_iterator_t *iterator);
jpayne@68 50
jpayne@68 51 cairo_path_element_type_t
jpayne@68 52 cairo_path_element_get_type (cairo_path_element_t *element);
jpayne@68 53
jpayne@68 54 void
jpayne@68 55 cairo_path_element_get_point (cairo_path_element_t *element,
jpayne@68 56 int index,
jpayne@68 57 double *x,
jpayne@68 58 double *y);
jpayne@68 59 </pre>
jpayne@68 60 <p>
jpayne@68 61 The above is written using the Java conventions for
jpayne@68 62 iterators. To illustrate how the API for PathIterator might
jpayne@68 63 depend on the native iteration conventions of the API, examine
jpayne@68 64 three versions of the loop, first written in a hypothetical Java
jpayne@68 65 binding:
jpayne@68 66 </p>
jpayne@68 67 <pre class="programlisting">
jpayne@68 68 PathIterator iter = cr.copyPath().iterator();
jpayne@68 69 while (cr.hasNext()) {
jpayne@68 70 PathElement element = iter.next();
jpayne@68 71 if (element.getType() == PathElementType.MOVE_TO) {
jpayne@68 72 Point p = element.getPoint(0);
jpayne@68 73 doMoveTo (p.x, p.y);
jpayne@68 74 }
jpayne@68 75 }</pre>
jpayne@68 76 <p>
jpayne@68 77 And then in a hypothetical C++ binding:
jpayne@68 78 </p>
jpayne@68 79 <pre class="programlisting">
jpayne@68 80 Path path = cr.copyPath();
jpayne@68 81 for (PathIterator iter = path.begin(); iter != path.end(); iter++) {
jpayne@68 82 PathElement element = *iter;
jpayne@68 83 if (element.getType() == PathElementType.MOVE_TO) {
jpayne@68 84 Point p = element.getPoint(0);
jpayne@68 85 doMoveTo (p.x, p.y);
jpayne@68 86 }
jpayne@68 87 }</pre>
jpayne@68 88 <p>
jpayne@68 89 And then finally in a Python binding:
jpayne@68 90 </p>
jpayne@68 91 <pre class="programlisting">
jpayne@68 92 for element in cr.copy_path():
jpayne@68 93 if element.getType == cairo.PATH_ELEMENT_MOVE_TO:
jpayne@68 94 (x, y) = element.getPoint(0)
jpayne@68 95 doMoveTo (x, y);</pre>
jpayne@68 96 <p>
jpayne@68 97 While many of the API elements stay the same in the three
jpayne@68 98 examples, the exact iteration mechanism is quite different, to
jpayne@68 99 match how users of the language would expect to iterate over
jpayne@68 100 a container.
jpayne@68 101 </p>
jpayne@68 102 <p>
jpayne@68 103 You should not present an API for mutating or for creating new
jpayne@68 104 <span class="type">cairo_path_t</span> objects. In the future, these
jpayne@68 105 guidelines may be extended to present an API for creating a
jpayne@68 106 <span class="type">cairo_path_t</span> from scratch for use with
jpayne@68 107 <a class="link" href="cairo-Paths.html#cairo-append-path" title="cairo_append_path ()"><code class="function">cairo_append_path()</code></a>
jpayne@68 108 but the current expectation is that <code class="function">cairo_append_path()</code> will
jpayne@68 109 mostly be used with paths from
jpayne@68 110 <a class="link" href="cairo-Paths.html#cairo-append-path" title="cairo_append_path ()"><code class="function">cairo_copy_path()</code></a>.
jpayne@68 111 </p>
jpayne@68 112 </div>
jpayne@68 113 <div class="footer">
jpayne@68 114 <hr>Generated by GTK-Doc V1.27</div>
jpayne@68 115 </body>
jpayne@68 116 </html>