RubyGems - cairo - Versions diffs - 1.8.3-x86-mingw32 → 1.8.4-x86-mingw32 - Mend

cairo 1.8.3-x86-mingw32 → 1.8.4-x86-mingw32

Potentially problematic release.

This version of cairo might be problematic. Click here for more details.

Files changed (126) hide show

data/home/kou/work/ruby/rcairo.win32/vendor/local/share/gtk-doc/html/cairo/bindings-errors.html ADDED Viewed

@@ -0,0 +1,132 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Error handling</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<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-streams.html" title="Streams and File I/O">
+<link rel="next" href="bindings-patterns.html" title="Patterns">
+<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="chapter" href="cairo-drawing.html" title="Drawing">
+<link rel="chapter" href="cairo-fonts.html" title="Fonts">
+<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
+<link rel="chapter" href="cairo-support.html" title="Utilities">
+<link rel="index" href="index-all.html" title="Index">
+<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
+<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
+<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
+<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
+<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+</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="2"><tr valign="middle">
+<td><a accesskey="p" href="bindings-streams.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
+<td><a accesskey="n" href="bindings-patterns.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Error handling">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bindings-errors"></a>Error handling</h2></div></div></div>
+<p>
+      The error handling approach in C for Cairo has multiple
+      elements:
+    </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>
+	  When a method on an object fails, the object is put into
+	  an error state. Subsequent operations on the object do
+	  nothing. The status of the object can be queried with
+	  a function like <a class="link" href="cairo-context.html#cairo-status" title="cairo_status ()"><code class="function">status()</code></a>.
+      </p></li>
+<li class="listitem">
+<p>
+	  Constructors, rather than
+	  returning <code class="constant">NULL</code> on out-of-memory failure,
+	  return a special singleton object on which all
+	  operations do nothing. Retrieving the status of the
+	  singleton object returns <code class="constant">CAIRO_STATUS_NO_MEMORY</code>
+	  </p>
+<p class="remark"><i><span class="remark">
+	    Is this going to apply to
+	  <span class="type">cairo_surface_t</span> as well?
+	</span></i></p>
+<p class="remark"><i><span class="remark">
+	  What about cairo_copy_path_data()? It's probably going to
+	  have to return <code class="constant">NULL</code>.
+	</span></i></p>
+</li>
+<li class="listitem"><p>
+	  Errors propagate from object to object. Setting a pattern
+	  in an out-of-memory state as the source of a
+	  <span class="type">cairo_t</span> puts the type into an error state.
+      </p></li>
+</ul></div>
+<p class="remark"><i><span class="remark">Much of the above is not yet implemented at the time of
+      this writing</span></i></p>
+<p>
+      A language binding could copy the C approach, and for a
+      language without exceptions, this is likely the right thing
+      to do. However, for a language with exceptions, exposing
+      a completely different style of error handling for cairo
+      would be strange. So, instead, status should be checked
+      after every call to cairo, and exceptions thrown as necessary.
+    </p>
+<p>
+      One problem that can arise with this, in languages
+      where handling exceptions is mandatory (like Java), is that almost
+      every cairo function can result in a status being set,
+      usually because of an out-of-memory condition. This could make
+      cairo hard to use. To resolve this problem, let's classify then
+      cairo status codes:
+    </p>
+<pre class="programlisting">
+/* Memory */
+CAIRO_STATUS_NO_MEMORY,
+/* Programmer error */
+CAIRO_STATUS_INVALID_RESTORE
+CAIRO_STATUS_INVALID_POP_GROUP
+CAIRO_STATUS_NO_CURRENT_POINT
+CAIRO_STATUS_INVALID_MATRIX
+CAIRO_STATUS_NO_TARGET_SURFACE
+CAIRO_STATUS_INVALID_STRING
+CAIRO_STATUS_SURFACE_FINISHED
+CAIRO_STATUS_BAD_NESTING
+/* Language binding implementation */
+CAIRO_STATUS_NULL_POINTER
+CAIRO_STATUS_INVALID_PATH_DATA
+CAIRO_STATUS_SURFACE_TYPE_MISMATCH
+/* Other */
+CAIRO_STATUS_READ_ERROR
+CAIRO_STATUS_WRITE_ERROR
+</pre>
+<p>
+      If we look at these, the
+      <code class="constant">CAIRO_STATUS_NO_MEMORY</code>
+      should map to the native out-of-memory exception, which could
+      happen at any point in any case. Most of the others indicate
+      programmer error, and handling them in user code would be
+      silly. These should be mapped into whatever the language uses
+      for assertion failures, rather than errors that are normally
+      handled. (In Java, a subclass of Error rather than Exception,
+      perhaps.) And <code class="constant">CAIRO_STATUS_READ_ERROR</code>,
+      and <code class="constant">CAIRO_STATUS_WRITE_ERROR</code> can occur
+      only in very specific places. (In fact, as described
+      in <a class="xref" href="bindings-streams.html" title="Streams and File I/O">the section called “Streams and File I/O”</a>, these errors may be
+      mapped into the language's native I/O error types.)
+      So, there really aren't exceptions that the programmer must
+      handle at most points in the Cairo API.
+    </p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.11</div>
+</body>
+</html>

data/home/kou/work/ruby/rcairo.win32/vendor/local/share/gtk-doc/html/cairo/bindings-fonts.html ADDED Viewed

@@ -0,0 +1,63 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Fonts</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<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-surfaces.html" title="Surfaces">
+<link rel="next" href="bindings-path.html" title="cairo_path_t">
+<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="chapter" href="cairo-drawing.html" title="Drawing">
+<link rel="chapter" href="cairo-fonts.html" title="Fonts">
+<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
+<link rel="chapter" href="cairo-support.html" title="Utilities">
+<link rel="index" href="index-all.html" title="Index">
+<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
+<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
+<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
+<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
+<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+</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="2"><tr valign="middle">
+<td><a accesskey="p" href="bindings-surfaces.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
+<td><a accesskey="n" href="bindings-path.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Fonts">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bindings-fonts"></a>Fonts</h2></div></div></div>
+<p>
+      Fonts are once more an area where there is a hierarchy of types:
+    </p>
+<pre class="programlisting">
+cairo_font_face_t
+   cairo_ft_font_face_t
+   cairo_win32_font_face_t
+cairo_scaled_font_t
+   cairo_ft_scaled_font_t
+   cairo_win32_scaled_font_t
+</pre>
+<p>
+      The methods on the subtypes are, however, not useful without
+      bindings for fontconfig and FreeType or for the Win32 GDI,
+      so most language bindings will choose not to bind these
+      types.
+    </p>
+<p>
+      The <a class="link" href="cairo-font-face.html#cairo-font-face-set-user-data" title="cairo_font_face_set_user_data ()"><code class="function">cairo_font_face_set_user_data()</code></a>,
+      and <a class="link" href="cairo-font-face.html#cairo-font-face-get-user-data" title="cairo_font_face_get_user_data ()"><code class="function">cairo_font_face_get_user_data()</code></a>
+      methods are provided for use in language bindings, and should
+      not be directly exposed to applications.
+    </p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.11</div>
+</body>
+</html>

data/home/kou/work/ruby/rcairo.win32/vendor/local/share/gtk-doc/html/cairo/bindings-memory.html ADDED Viewed

@@ -0,0 +1,133 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Memory management</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<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="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+<link rel="next" href="bindings-return-values.html" title="Multiple return values">
+<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="chapter" href="cairo-drawing.html" title="Drawing">
+<link rel="chapter" href="cairo-fonts.html" title="Fonts">
+<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
+<link rel="chapter" href="cairo-support.html" title="Utilities">
+<link rel="index" href="index-all.html" title="Index">
+<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
+<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
+<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
+<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
+<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+</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="2"><tr valign="middle">
+<td><a accesskey="p" href="language-bindings.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
+<td><a accesskey="n" href="bindings-return-values.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Memory management">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bindings-memory"></a>Memory management</h2></div></div></div>
+<p>
+      The objects in cairo can roughly be divided into two types:
+      reference-counted, opaque types like
+      <a class="link" href="cairo-surface.html#cairo-surface-t" title="cairo_surface_t"><span class="type">cairo_surface_t</span></a>
+      and plain structures like
+      <a class="link" href="cairo-text.html#cairo-glyph-t" title="cairo_glyph_t"><span class="type">cairo_glyph_t</span></a>.
+      <a class="link" href="cairo-paths.html#cairo-path-t" title="cairo_path_t"><span class="type">cairo_path_t</span></a>
+      and
+      <a class="link" href="cairo-paths.html#cairo-path-data-t" title="union cairo_path_data_t"><span class="type">cairo_path_data_t</span></a>
+      are special cases and are treated separately in this appendix.
+    </p>
+<p>
+      Refcounted opaque types all have a
+      <code class="function">..._reference()</code>
+      function to increase the refcount by one and a
+      <code class="function">..._destroy()</code> to decrease the refcount
+      by one. These should not be exposed to the user of the language
+      binding, but rather used to implement memory management within
+      the language binding. The simplest way to do memory management
+      for a language binding is to treat the language binding object
+      as a simple handle to the cairo object. The language binding
+      object references the cairo object, and unreferences it when
+      finalized. This is the recommended method, though there are
+      a couple of caveats to be noted:
+    </p>
+<div class="itemizedlist"><ul class="itemizedlist" type="disc">
+<li class="listitem"><p>
+	  Equality won't work as expected. You can have two language
+	  objects for the same cairo and they won't necessarily
+	  compare equal. If the language allows customizing the
+	  equality operation, then this is fixable by comparing
+	  the underlying pointers. It also can be fixed by creating
+	  at most one language object per cairo object, and
+	  uniquifying via a <em class="firstterm">pin table</em> (a hash
+	  table that goes from cairo object to language object).
+	  For <span class="type">cairo_surface_t</span> you can use also
+	  <a class="link" href="cairo-surface.html#cairo-surface-set-user-data" title="cairo_surface_set_user_data ()"><code class="function">cairo_surface_set_user_data()</code></a>
+	  instead of a separate pin table.
+	</p></li>
+<li class="listitem">
+<p>
+	  Derivation from the language object doesn't work because
+	  you can lose the language object while keeping the Cairo
+	  object. Code like:
+	</p>
+<pre class="programlisting">
+public class MySurface (ImageSurface) {
+   public MySurface (width, height) {
+      super (Format.ARGB32, width, height);
+   }
+   public int get42 () {
+      return 42;
+   }
+}
+   cr = Cairo(MySurface(width, height));
+   surface = cr.getTarget();
+</pre>
+<p>
+	  Can result in <code class="varname">surface</code> containing an
+	  <code class="classname">ImageSurface</code> not a <code class="classname">MySurface</code>.
+	  This is not easily fixable without creating memory leaks,
+	  and it's probably best to simply forbid deriving from the
+	  language objects.
+	</p>
+</li>
+</ul></div>
+<p>
+      When a plain structure is used as a return value from cairo,
+      this is done by passing it as a “out parameter”.
+    </p>
+<pre class="programlisting">
+cairo_font_extents_t extents;
+cairo_font_extents (cr, &amp;extents);</pre>
+<p>
+      In a language binding, this should typically be treated
+      as a return value:
+    </p>
+<pre class="programlisting">
+FontExtents extents = cr.fontExtents ();</pre>
+<p>
+      A language binding has a choice in how it implements the
+      language objects for plain structures. It can use a pure
+      language object with fields corresponding to those of the C
+      structure, and convert from and to the C structure when calling
+      cairo functions or converting cairo return values. Or it
+      can keep a pointer to the C structure internally and wrap
+      it inside a language object much like occurs for refcounted
+      objects. The choice should be invisible to the user: they should
+      be able to imagine that it is implemented as a pure language
+      object.
+    </p>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.11</div>
+</body>
+</html>

data/home/kou/work/ruby/rcairo.win32/vendor/local/share/gtk-doc/html/cairo/bindings-overloading.html ADDED Viewed

@@ -0,0 +1,131 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Overloading and optional arguments</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<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-return-values.html" title="Multiple return values">
+<link rel="next" href="bindings-streams.html" title="Streams and File I/O">
+<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+<link rel="chapter" href="cairo-drawing.html" title="Drawing">
+<link rel="chapter" href="cairo-fonts.html" title="Fonts">
+<link rel="chapter" href="cairo-surfaces.html" title="Surfaces">
+<link rel="chapter" href="cairo-support.html" title="Utilities">
+<link rel="index" href="index-all.html" title="Index">
+<link rel="index" href="index-1.2.html" title="Index of new symbols in 1.2">
+<link rel="index" href="index-1.4.html" title="Index of new symbols in 1.4">
+<link rel="index" href="index-1.6.html" title="Index of new symbols in 1.6">
+<link rel="index" href="index-1.8.html" title="Index of new symbols in 1.8">
+<link rel="appendix" href="language-bindings.html" title="Appendix A. Creating a language binding for cairo">
+</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="2"><tr valign="middle">
+<td><a accesskey="p" href="bindings-return-values.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="language-bindings.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">Cairo: A Vector Graphics Library</th>
+<td><a accesskey="n" href="bindings-streams.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr></table>
+<div class="sect1" title="Overloading and optional arguments">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="bindings-overloading"></a>Overloading and optional arguments</h2></div></div></div>
+<p>
+      Function overloading (having a several variants of a function
+      with the same name and different arguments) is a language
+      feature available in many languages but not in C.
+    </p>
+<p>
+      In general, language binding authors should use restraint in
+      combining functions in the cairo API via function
+      overloading. What may seem like an obvious overload now may
+      turn out to be strange with future additions to cairo.
+      It might seem logical to make
+      <a class="link" href="cairo-context.html#cairo-set-source-rgb" title="cairo_set_source_rgb ()"><code class="function">cairo_set_source_rgb()</code></a>
+	an overload of <code class="function">cairo_set_source()</code>, but future plans to add
+	<code class="function">cairo_set_source_rgb_premultiplied()</code>,
+      which will also take three doubles make this a bad idea. For
+      this reason, only the following pairs of functions should
+      be combined via overloading
+    </p>
+<pre class="programlisting">
+void
+cairo_set_source (cairo_t *cr, cairo_pattern_t *source);
+void
+cairo_set_source_surface (cairo_t          *cr,
+                          cairo_surface_t  *source,
+                          double            surface_x,
+                          double            surface_y);
+void
+cairo_mask (cairo_t         *cr,
+	    cairo_pattern_t *pattern);
+void
+cairo_mask_surface (cairo_t         *cr,
+		    cairo_surface_t *surface,
+		    double           surface_x,
+		    double           surface_y);
+cairo_surface_t *
+cairo_image_surface_create (cairo_format_t	format,
+			    int			width,
+			    int			height);
+cairo_surface_t *
+cairo_image_surface_create_for_data (unsigned char	       *data,
+				     cairo_format_t		format,
+				     int			width,
+				     int			height,
+				     int			stride);
+cairo_status_t
+cairo_surface_write_to_png (cairo_surface_t	*surface,
+			    const char		*filename);
+cairo_status_t
+cairo_surface_write_to_png_stream (cairo_surface_t	*surface,
+				   cairo_write_func_t	write_func,
+				   void			*closure);
+cairo_surface_t *
+cairo_image_surface_create_from_png (const char	*filename);
+cairo_surface_t *
+cairo_image_surface_create_from_png_stream (cairo_read_func_t	read_func,
+					    void		*closure);
+    </pre>
+<p>
+      Note that there are cases where all constructors for a type
+      aren't overloaded together. For example
+      <a class="link" href="cairo-png-functions.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>
+      should <span class="emphasis"><em>not</em></span> be overloaded together with
+      <a class="link" href="cairo-image-surface.html#cairo-image-surface-create" title="cairo_image_surface_create ()"><code class="function">cairo_image_surface_create()</code></a>.
+      In such cases, the remaining constructors will typically need to
+      be bound as static methods. In Java, for example, we might have:
+    </p>
+<pre class="programlisting">
+Surface surface1 = ImageSurface(Format.RGB24, 100, 100);
+Surface surface2 = ImageSurface.createFromPNG("camera.png");</pre>
+<p>
+      Some other overloads that add combinations not found in C may be
+      convenient for users for language bindings that provide
+      <span class="type">cairo_point_t</span> and <span class="type">cairo_rectangle_t</span>
+      types, for example:
+    </p>
+<pre class="programlisting">
+void
+cairo_move_to (cairo_t       *cr,
+               cairo_point_t *point);
+void
+cairo_rectangle (cairo_t           *cr,
+                 cairo_rectangle_t *rectangle);
+    </pre>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.11</div>
+</body>
+</html>