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

planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>Overloading and optional arguments: Cairo: A Vector Graphics Library</title>
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="index.html" title="Cairo: A Vector Graphics Library">
8 <link rel="up" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
9 <link rel="prev" href="bindings-return-values.html" title="Multiple return values">
10 <link rel="next" href="bindings-streams.html" title="Streams and File I/O">
11 <meta name="generator" content="GTK-Doc V1.27 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
13 </head>
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
16 <td width="100%" align="left" class="shortcuts"></td>
17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
18 <td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
19 <td><a accesskey="p" href="bindings-return-values.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
20 <td><a accesskey="n" href="bindings-streams.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
21 </tr></table>
22 <div class="sect1">
23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
24 <a name="bindings-overloading"></a>Overloading and optional arguments</h2></div></div></div>
25 <p>
26 Function overloading (having a several variants of a function
27 with the same name and different arguments) is a language
28 feature available in many languages but not in C.
29 </p>
30 <p>
31 In general, language binding authors should use restraint in
32 combining functions in the cairo API via function
33 overloading. What may seem like an obvious overload now may
34 turn out to be strange with future additions to cairo.
35 It might seem logical to make
36 <a class="link" href="cairo-cairo-t.html#cairo-set-source-rgb" title="cairo_set_source_rgb ()"><code class="function">cairo_set_source_rgb()</code></a>
37 an overload of <code class="function">cairo_set_source()</code>, but future plans to add
38 <code class="function">cairo_set_source_rgb_premultiplied()</code>,
39 which will also take three doubles make this a bad idea. For
40 this reason, only the following pairs of functions should
41 be combined via overloading
42 </p>
43 <pre class="programlisting">
44 void
45 cairo_set_source (cairo_t *cr, cairo_pattern_t *source);
46
47 void
48 cairo_set_source_surface (cairo_t *cr,
49 cairo_surface_t *source,
50 double surface_x,
51 double surface_y);
52
53 void
54 cairo_mask (cairo_t *cr,
55 cairo_pattern_t *pattern);
56
57 void
58 cairo_mask_surface (cairo_t *cr,
59 cairo_surface_t *surface,
60 double surface_x,
61 double surface_y);
62
63 cairo_surface_t *
64 cairo_image_surface_create (cairo_format_t format,
65 int width,
66 int height);
67 cairo_surface_t *
68 cairo_image_surface_create_for_data (unsigned char *data,
69 cairo_format_t format,
70 int width,
71 int height,
72 int stride);
73
74 cairo_status_t
75 cairo_surface_write_to_png (cairo_surface_t *surface,
76 const char *filename);
77
78 cairo_status_t
79 cairo_surface_write_to_png_stream (cairo_surface_t *surface,
80 cairo_write_func_t write_func,
81 void *closure);
82
83 cairo_surface_t *
84 cairo_image_surface_create_from_png (const char *filename);
85
86 cairo_surface_t *
87 cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func,
88 void *closure);
89 </pre>
90 <p>
91 Note that there are cases where all constructors for a type
92 aren't overloaded together. For example
93 <a class="link" href="cairo-PNG-Support.html#cairo-image-surface-create-from-png" title="cairo_image_surface_create_from_png ()"><code class="function">cairo_image_surface_create_from_png()</code></a>
94 should <span class="emphasis"><em>not</em></span> be overloaded together with
95 <a class="link" href="cairo-Image-Surfaces.html#cairo-image-surface-create" title="cairo_image_surface_create ()"><code class="function">cairo_image_surface_create()</code></a>.
96 In such cases, the remaining constructors will typically need to
97 be bound as static methods. In Java, for example, we might have:
98 </p>
99 <pre class="programlisting">
100 Surface surface1 = ImageSurface(Format.RGB24, 100, 100);
101 Surface surface2 = ImageSurface.createFromPNG("camera.png");</pre>
102 <p>
103 Some other overloads that add combinations not found in C may be
104 convenient for users for language bindings that provide
105 <span class="type">cairo_point_t</span> and <span class="type">cairo_rectangle_t</span>
106 types, for example:
107 </p>
108 <pre class="programlisting">
109 void
110 cairo_move_to (cairo_t *cr,
111 cairo_point_t *point);
112 void
113 cairo_rectangle (cairo_t *cr,
114 cairo_rectangle_t *rectangle);
115 </pre>
116 </div>
117 <div class="footer">
118 <hr>Generated by GTK-Doc V1.27</div>
119 </body>
120 </html>