764 lines
42 KiB
HTML
764 lines
42 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
<title>Migrating from GTK+ 2.x to GTK+ 3: GTK+ 3 Reference Manual</title>
|
||
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
||
<link rel="home" href="index.html" title="GTK+ 3 Reference Manual">
|
||
<link rel="up" href="migrating.html" title="Part V. Migrating from Previous Versions of GTK+">
|
||
<link rel="prev" href="migrating.html" title="Part V. Migrating from Previous Versions of GTK+">
|
||
<link rel="next" href="ch26s02.html" title="Changes that need to be done at the time of the switch">
|
||
<meta name="generator" content="GTK-Doc V1.32.1 (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="5"><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="migrating.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
|
||
<td><a accesskey="p" href="migrating.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
|
||
<td><a accesskey="n" href="ch26s02.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
|
||
</tr></table>
|
||
<div class="chapter">
|
||
<div class="titlepage"><div><div><h2 class="title">
|
||
<a name="gtk-migrating-2-to-3"></a>Migrating from GTK+ 2.x to GTK+ 3</h2></div></div></div>
|
||
<div class="toc"><dl class="toc">
|
||
<dt><span class="section"><a href="gtk-migrating-2-to-3.html#id-1.6.3.3">Preparation in GTK+ 2.x</a></span></dt>
|
||
<dd><dl>
|
||
<dt><span class="section"><a href="gtk-migrating-2-to-3.html#id-1.6.3.3.3">Do not include individual headers</a></span></dt>
|
||
<dt><span class="section"><a href="gtk-migrating-2-to-3.html#id-1.6.3.3.4">Do not use deprecated symbols</a></span></dt>
|
||
<dt><span class="section"><a href="gtk-migrating-2-to-3.html#id-1.6.3.3.5">Use accessor functions instead of direct access</a></span></dt>
|
||
<dt><span class="section"><a href="gtk-migrating-2-to-3.html#id-1.6.3.3.6">Replace GDK_<keyname> with GDK_KEY_<keyname></a></span></dt>
|
||
<dt><span class="section"><a href="gtk-migrating-2-to-3.html#id-1.6.3.3.7">Use GIO for launching applications</a></span></dt>
|
||
<dt><span class="section"><a href="gtk-migrating-2-to-3.html#id-1.6.3.3.8">Use cairo for drawing</a></span></dt>
|
||
</dl></dd>
|
||
<dt><span class="section"><a href="ch26s02.html">Changes that need to be done at the time of the switch</a></span></dt>
|
||
<dd><dl>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.3">Replace size_request by get_preferred_width/height</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.4">Replace GdkRegion by cairo_region_t</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.5">Replace GdkPixmap by cairo surfaces</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.6">Replace GdkColormap by GdkVisual</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.7">GdkDrawable is gone</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.8">Event filtering</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.9">Backend-specific code</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.10">GtkPlug and GtkSocket</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.11">The GtkWidget::draw signal</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.12">GtkProgressBar orientation</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.13">Check your expand and fill flags</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.14">Scrolling changes</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.15">GtkObject is gone</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.16">GtkEntryCompletion signal parameters</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.17">Resize grips</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.18">Prevent mixed linkage</a></span></dt>
|
||
<dt><span class="section"><a href="ch26s02.html#id-1.6.3.4.19">Install GTK+ modules in the right place</a></span></dt>
|
||
</dl></dd>
|
||
</dl></div>
|
||
<p>
|
||
GTK+ 3 is a major new version of GTK+ that breaks both API and ABI
|
||
compared to GTK+ 2.x, which has remained API- and ABI-stable for a
|
||
long time. Thankfully, most of the changes are not hard to adapt to
|
||
and there are a number of steps that you can take to prepare your
|
||
GTK+ 2.x application for the switch to GTK+ 3. After that, there's
|
||
a small number of adjustments that you may have to do when you actually
|
||
switch your application to build against GTK+ 3.
|
||
</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||
<a name="id-1.6.3.3"></a>Preparation in GTK+ 2.x</h2></div></div></div>
|
||
<p>
|
||
The steps outlined in the following sections assume that your
|
||
application is working with GTK+ 2.24, which is the final stable
|
||
release of GTK+ 2.x. It includes all the necessary APIs and tools
|
||
to help you port your application to GTK+ 3. If you are still using
|
||
an older version of GTK+ 2.x, you should first get your application
|
||
to build and work with 2.24.
|
||
</p>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="id-1.6.3.3.3"></a>Do not include individual headers</h3></div></div></div>
|
||
<p>
|
||
With GTK+ 2.x it was common to include just the header files for
|
||
a few widgets that your application was using, which could lead
|
||
to problems with missing definitions, etc. GTK+ 3 tightens the
|
||
rules about which header files you are allowed to include directly.
|
||
The allowed header files are are
|
||
</p>
|
||
<div class="variablelist"><table border="0" class="variablelist">
|
||
<colgroup>
|
||
<col align="left" valign="top">
|
||
<col>
|
||
</colgroup>
|
||
<tbody>
|
||
<tr>
|
||
<td><p><span class="term"><code class="filename">gtk/gtk.h</code></span></p></td>
|
||
<td>for GTK</td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="filename">gtk/gtkx.h</code></span></p></td>
|
||
<td>for the X-specfic widgets <a class="link" href="GtkSocket.html" title="GtkSocket"><span class="type">GtkSocket</span></a> and <a class="link" href="GtkPlug.html" title="GtkPlug"><span class="type">GtkPlug</span></a>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="filename">gtk/gtkunixprint.h</code></span></p></td>
|
||
<td>for low-level, UNIX-specific printing functions</td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="filename">gdk/gdk.h</code></span></p></td>
|
||
<td>for GDK</td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="filename">gdk/gdkx.h</code></span></p></td>
|
||
<td>for GDK functions that are X11-specific</td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><span class="term"><code class="filename">gdk/gdkwin32.h</code></span></p></td>
|
||
<td>for GDK functions that are Windows-specific</td>
|
||
</tr>
|
||
</tbody>
|
||
</table></div>
|
||
<p>
|
||
(these relative paths are assuming that you are using the include
|
||
paths that are specified in the gtk+-2.0.pc file, as returned by
|
||
<code class="literal">pkg-config --cflags gtk+-2.0.pc</code>.)
|
||
</p>
|
||
<p>
|
||
To check that your application only includes the allowed headers,
|
||
you can use defines to disable inclusion of individual headers,
|
||
as follows:
|
||
</p>
|
||
<pre class="programlisting">
|
||
make CFLAGS+="-DGTK_DISABLE_SINGLE_INCLUDES"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="id-1.6.3.3.4"></a>Do not use deprecated symbols</h3></div></div></div>
|
||
<p>
|
||
Over the years, a number of functions, and in some cases, entire
|
||
widgets have been deprecated. These deprecations are clearly spelled
|
||
out in the API reference, with hints about the recommended replacements.
|
||
The API reference for GTK+ 2 also includes an
|
||
<a class="ulink" href="https://developer.gnome.org/gtk2/2.24/api-index-deprecated.html" target="_top">index</a> of all deprecated symbols.
|
||
</p>
|
||
<p>
|
||
To verify that your program does not use any deprecated symbols,
|
||
you can use defines to remove deprecated symbols from the header files,
|
||
as follows:
|
||
</p>
|
||
<pre class="programlisting">
|
||
make CFLAGS+="-DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
Note that some parts of our API, such as enumeration values, are
|
||
not well covered by the deprecation warnings. In most cases, using
|
||
them will require you to also use deprecated functions, which will
|
||
trigger warnings. But some things, like the <code class="literal">GTK_DIALOG_NO_SEPARATOR</code>
|
||
flag that has disappeared in GTK+ 3, may not.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="id-1.6.3.3.5"></a>Use accessor functions instead of direct access</h3></div></div></div>
|
||
<p>
|
||
GTK+ 3 removes many implementation details and struct members from
|
||
its public headers.
|
||
</p>
|
||
<p>
|
||
To ensure that your application does not have problems with this, you
|
||
define the preprocessor symbol <code class="literal">GSEAL_ENABLE</code> while
|
||
building your application against GTK+ 2.x. This will make the compiler
|
||
catch all uses of direct access to struct fields so that you can go
|
||
through them one by one and replace them with a call to an accessor
|
||
function instead.
|
||
</p>
|
||
<pre class="programlisting">
|
||
make CFLAGS+="-DGSEAL_ENABLE"
|
||
</pre>
|
||
<p>
|
||
</p>
|
||
<p>
|
||
While it may be painful to convert, this helps us keep API and ABI
|
||
compatibility when we change internal interfaces. As a quick example,
|
||
when adding GSEAL_ENABLE, if you see an error like:
|
||
</p>
|
||
<pre class="programlisting">
|
||
error: 'GtkToggleButton' has no member named 'active'
|
||
</pre>
|
||
<p>
|
||
this means that you are accessing the public structure of
|
||
GtkToggleButton directly, perhaps with some code like:
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="k">static</span> <span class="kt">void</span>
|
||
<span class="nf">on_toggled</span> <span class="p">(</span><span class="n">GtkToggleButton</span> <span class="o">*</span><span class="n">button</span><span class="p">)</span>
|
||
<span class="p">{</span>
|
||
<span class="k">if</span> <span class="p">(</span><span class="n">button</span><span class="o">-></span><span class="n">active</span><span class="p">)</span>
|
||
<span class="n">frob_active</span> <span class="p">();</span>
|
||
<span class="k">else</span>
|
||
<span class="n">frob_inactive</span> <span class="p">();</span>
|
||
<span class="p">}</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
</p>
|
||
<p>
|
||
In most cases, this can easily be replaced with the correct accessor
|
||
method. The main rule is that if you have code like the above which
|
||
accesses the "active" field of a "GtkToggleButton", then the accessor
|
||
method becomes "gtk_toggle_button_get_active":
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="k">static</span> <span class="kt">void</span>
|
||
<span class="nf">on_toggled</span> <span class="p">(</span><span class="n">GtkToggleButton</span> <span class="o">*</span><span class="n">button</span><span class="p">)</span>
|
||
<span class="p">{</span>
|
||
<span class="k">if</span> <span class="p">(</span><span class="n">gtk_toggle_button_get_active</span> <span class="p">(</span><span class="n">button</span><span class="p">))</span>
|
||
<span class="n">frob_active</span> <span class="p">();</span>
|
||
<span class="k">else</span>
|
||
<span class="n">frob_inactive</span> <span class="p">();</span>
|
||
<span class="p">}</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
</p>
|
||
<p>
|
||
In the case of setting field members directly, there's usually
|
||
a corresponding setter method.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="id-1.6.3.3.6"></a>Replace GDK_<keyname> with GDK_KEY_<keyname></h3></div></div></div>
|
||
<p>
|
||
Key constants have gained a <code class="literal">_KEY_</code> infix.
|
||
For example, <code class="literal">GDK_a</code> is now
|
||
<code class="literal">GDK_KEY_a</code>. In GTK+ 2, the old names continue
|
||
to be available. In GTK+ 3 however, the old names will require
|
||
an explicit include of the <code class="literal">gdkkeysyms-compat.h</code> header.
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="id-1.6.3.3.7"></a>Use GIO for launching applications</h3></div></div></div>
|
||
<p>
|
||
The <code class="literal">gdk_spawn</code> family of functions has been
|
||
deprecated in GDK 2.24 and removed from GDK 3. Various replacements
|
||
exist; the best replacement depends on the circumstances:
|
||
</p>
|
||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||
<li class="listitem">If you are opening a document or URI by launching a command
|
||
like <code class="literal">firefox http://my-favourite-website.com</code> or
|
||
<code class="literal">gnome-open ghelp:epiphany</code>, it is best to just use
|
||
<a class="link" href="gtk3-Filesystem-utilities.html#gtk-show-uri-on-window" title="gtk_show_uri_on_window ()"><code class="function">gtk_show_uri_on_window()</code></a>; as an added benefit, your application will
|
||
henceforth respect the users preference for what application to use and
|
||
correctly open links in sandboxed applications.</li>
|
||
<li class="listitem">If you are launching a regular, installed application that
|
||
has a desktop file, it is best to use GIOs <span class="type">GAppInfo</span> with a suitable
|
||
launch context.
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8
|
||
9
|
||
10
|
||
11
|
||
12
|
||
13
|
||
14
|
||
15
|
||
16</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="n">GAppInfo</span> <span class="o">*</span><span class="n">info</span><span class="p">;</span>
|
||
<span class="n">GAppLaunchContext</span> <span class="o">*</span><span class="n">context</span><span class="p">;</span>
|
||
<span class="n">GError</span> <span class="o">*</span><span class="n">error</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
|
||
|
||
<span class="n">info</span> <span class="o">=</span> <span class="p">(</span><span class="n">GAppInfo</span><span class="o">*</span><span class="p">)</span> <span class="n">g_desktop_app_info_new</span> <span class="p">(</span><span class="s">"epiphany.desktop"</span><span class="p">);</span>
|
||
<span class="n">context</span> <span class="o">=</span> <span class="p">(</span><span class="n">GAppLaunchContext</span><span class="o">*</span><span class="p">)</span> <span class="n">gdk_display_get_app_launch_context</span> <span class="p">(</span><span class="n">display</span><span class="p">);</span>
|
||
<span class="n">g_app_info_launch</span> <span class="p">(</span><span class="n">info</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> <span class="n">context</span><span class="p">,</span> <span class="o">&</span><span class="n">error</span><span class="p">);</span>
|
||
|
||
<span class="k">if</span> <span class="p">(</span><span class="n">error</span><span class="p">)</span>
|
||
<span class="p">{</span>
|
||
<span class="n">g_warning</span> <span class="p">(</span><span class="s">"Failed to launch epiphany: %s"</span><span class="p">,</span> <span class="n">error</span><span class="o">-></span><span class="n">message</span><span class="p">);</span>
|
||
<span class="n">g_error_free</span> <span class="p">(</span><span class="n">error</span><span class="p">);</span>
|
||
<span class="p">}</span>
|
||
|
||
<span class="n">g_object_unref</span> <span class="p">(</span><span class="n">info</span><span class="p">);</span>
|
||
<span class="n">g_object_unref</span> <span class="p">(</span><span class="n">context</span><span class="p">);</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
Remember that you have to include
|
||
<code class="filename">gio/gdesktopappinfo.h</code>
|
||
and use the <code class="filename">gio-unix-2.0</code> pkg-config file
|
||
when using <code class="function">g_desktop_app_info_new()</code>.
|
||
</li>
|
||
<li class="listitem">If you are launching a custom commandline, you can
|
||
still use <code class="function">g_app_info_launch()</code> with a GAppInfo that is constructed
|
||
with <code class="function">g_app_info_create_from_commandline()</code>, or you can use the
|
||
more lowlevel <code class="literal">g_spawn</code> family of functions
|
||
(e.g. <code class="function">g_spawn_command_line_async()</code>), and pass <code class="envar">DISPLAY</code>
|
||
in the environment. <code class="function">gdk_screen_make_display_name()</code> can be
|
||
used to find the right value for the <code class="envar">DISPLAY</code>
|
||
environment variable.
|
||
</li>
|
||
</ul></div>
|
||
<p>
|
||
</p>
|
||
</div>
|
||
<div class="section">
|
||
<div class="titlepage"><div><div><h3 class="title">
|
||
<a name="id-1.6.3.3.8"></a>Use cairo for drawing</h3></div></div></div>
|
||
<p>
|
||
In GTK+ 3, the GDK drawing API (which closely mimics the X
|
||
drawing API, which is itself modeled after PostScript) has been
|
||
removed. All drawing in GTK+ 3 is done via cairo.
|
||
</p>
|
||
<p>
|
||
The <span class="type">GdkGC</span> and <span class="type">GdkImage</span> objects, as well as all the functions using
|
||
them, are gone. This includes the <code class="literal">gdk_draw</code> family
|
||
of functions like <code class="function">gdk_draw_rectangle()</code> and <code class="function">gdk_draw_drawable()</code>. As
|
||
<span class="type">GdkGC</span> is roughly equivalent to <a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-t"><span class="type">cairo_t</span></a> and <span class="type">GdkImage</span> was used for
|
||
drawing images to GdkWindows, which cairo supports automatically,
|
||
a transition is usually straightforward.
|
||
</p>
|
||
<p>
|
||
The following examples show a few common drawing idioms used by
|
||
applications that have been ported to use cairo and how the code
|
||
was replaced.
|
||
</p>
|
||
<div class="example">
|
||
<a name="id-1.6.3.3.8.5"></a><p class="title"><b>Example 38. Drawing a GdkPixbuf onto a GdkWindow</b></p>
|
||
<div class="example-contents">
|
||
<p>
|
||
Drawing a pixbuf onto a drawable used to be done like this:
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8
|
||
9</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="n">gdk_draw_pixbuf</span> <span class="p">(</span><span class="n">window</span><span class="p">,</span>
|
||
<span class="n">gtk_widget_get_style</span> <span class="p">(</span><span class="n">widget</span><span class="p">)</span><span class="o">-></span><span class="n">black_gc</span><span class="p">,</span>
|
||
<span class="n">pixbuf</span><span class="p">,</span>
|
||
<span class="mi">0</span><span class="p">,</span> <span class="mi">0</span>
|
||
<span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span>
|
||
<span class="n">gdk_pixbuf_get_width</span> <span class="p">(</span><span class="n">pixbuf</span><span class="p">),</span>
|
||
<span class="n">gdk_pixbuf_get_height</span> <span class="p">(</span><span class="n">pixbuf</span><span class="p">),</span>
|
||
<span class="n">GDK_RGB_DITHER_NORMAL</span><span class="p">,</span>
|
||
<span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
Doing the same thing with cairo:
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="n">cairo_t</span> <span class="o">*</span><span class="n">cr</span> <span class="o">=</span> <span class="n">gdk_cairo_create</span> <span class="p">(</span><span class="n">window</span><span class="p">);</span>
|
||
<span class="n">gdk_cairo_set_source_pixbuf</span> <span class="p">(</span><span class="n">cr</span><span class="p">,</span> <span class="n">pixbuf</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
|
||
<span class="n">cairo_paint</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span>
|
||
<span class="n">cairo_destroy</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
Note that very similar code can be used when porting code
|
||
using GdkPixmap to <a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-surface-t.html#cairo-surface-t"><span class="type">cairo_surface_t</span></a> by calling
|
||
<a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-set-source-surface"><code class="function">cairo_set_source_surface()</code></a> instead of
|
||
<a href="https://developer.gnome.org/gdk4/gdk4-Cairo-Interaction.html#gdk-cairo-set-source-pixbuf"><code class="function">gdk_cairo_set_source_pixbuf()</code></a>.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<br class="example-break"><div class="example">
|
||
<a name="id-1.6.3.3.8.6"></a><p class="title"><b>Example 39. Drawing a tiled GdkPixmap to a GdkWindow</b></p>
|
||
<div class="example-contents">
|
||
<p>
|
||
Tiled pixmaps are often used for drawing backgrounds.
|
||
Old code looked something like this:
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8
|
||
9
|
||
10
|
||
11
|
||
12
|
||
13
|
||
14</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="n">GdkGCValues</span> <span class="n">gc_values</span><span class="p">;</span>
|
||
<span class="n">GdkGC</span> <span class="o">*</span><span class="n">gc</span><span class="p">;</span>
|
||
|
||
<span class="cm">/* setup */</span>
|
||
<span class="n">gc</span> <span class="o">=</span> <span class="n">gtk_widget_get_style</span> <span class="p">(</span><span class="n">widget</span><span class="p">)</span><span class="o">-></span><span class="n">black_gc</span><span class="p">;</span>
|
||
<span class="n">gdk_gc_set_tile</span> <span class="p">(</span><span class="n">gc</span><span class="p">,</span> <span class="n">pixmap</span><span class="p">);</span>
|
||
<span class="n">gdk_gc_set_fill</span> <span class="p">(</span><span class="n">gc</span><span class="p">,</span> <span class="n">GDK_TILED</span><span class="p">);</span>
|
||
<span class="n">gdk_gc_set_ts_origin</span> <span class="p">(</span><span class="n">gc</span><span class="p">,</span> <span class="n">x_origin</span><span class="p">,</span> <span class="n">y_origin</span><span class="p">);</span>
|
||
<span class="cm">/* use */</span>
|
||
<span class="n">gdk_draw_rectangle</span> <span class="p">(</span><span class="n">window</span><span class="p">,</span> <span class="n">gc</span><span class="p">,</span> <span class="n">TRUE</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">width</span><span class="p">,</span> <span class="n">height</span><span class="p">);</span>
|
||
<span class="cm">/* restore */</span>
|
||
<span class="n">gdk_gc_set_tile</span> <span class="p">(</span><span class="n">gc</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span>
|
||
<span class="n">gdk_gc_set_fill</span> <span class="p">(</span><span class="n">gc</span><span class="p">,</span> <span class="n">GDK_SOLID</span><span class="p">);</span>
|
||
<span class="n">gdk_gc_set_ts_origin</span> <span class="p">(</span><span class="n">gc</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
The equivalent cairo code to draw a tiled surface looks
|
||
like this:
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8
|
||
9
|
||
10</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="n">cairo_t</span> <span class="o">*</span><span class="n">cr</span><span class="p">;</span>
|
||
<span class="n">cairo_surface_t</span> <span class="o">*</span><span class="n">surface</span><span class="p">;</span>
|
||
|
||
<span class="n">surface</span> <span class="o">=</span> <span class="p">...</span>
|
||
<span class="n">cr</span> <span class="o">=</span> <span class="n">gdk_cairo_create</span> <span class="p">(</span><span class="n">window</span><span class="p">);</span>
|
||
<span class="n">cairo_set_source_surface</span> <span class="p">(</span><span class="n">cr</span><span class="p">,</span> <span class="n">surface</span><span class="p">,</span> <span class="n">x_origin</span><span class="p">,</span> <span class="n">y_origin</span><span class="p">);</span>
|
||
<span class="n">cairo_pattern_set_extend</span> <span class="p">(</span><span class="n">cairo_get_source</span> <span class="p">(</span><span class="n">cr</span><span class="p">),</span> <span class="n">CAIRO_EXTEND_REPEAT</span><span class="p">);</span>
|
||
<span class="n">cairo_rectangle</span> <span class="p">(</span><span class="n">cr</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">width</span><span class="p">,</span> <span class="n">height</span><span class="p">);</span>
|
||
<span class="n">cairo_fill</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span>
|
||
<span class="n">cairo_destroy</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
The surface here can be either an image surface or a X surface,
|
||
and can either be created on the spot or kept around for caching purposes.
|
||
Another alternative is to use pixbufs instead of surfaces with
|
||
<a href="https://developer.gnome.org/gdk4/gdk4-Cairo-Interaction.html#gdk-cairo-set-source-pixbuf"><code class="function">gdk_cairo_set_source_pixbuf()</code></a> instead of <a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-set-source-surface"><code class="function">cairo_set_source_surface()</code></a>.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<br class="example-break"><div class="example">
|
||
<a name="id-1.6.3.3.8.7"></a><p class="title"><b>Example 40. Drawing a PangoLayout to a clipped area</b></p>
|
||
<div class="example-contents">
|
||
<p>
|
||
Drawing layouts clipped is often used to avoid overdraw or to
|
||
allow drawing selections. Code would have looked like this:
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8
|
||
9</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="n">GdkGC</span> <span class="o">*</span><span class="n">gc</span><span class="p">;</span>
|
||
|
||
<span class="cm">/* setup */</span>
|
||
<span class="n">gc</span> <span class="o">=</span> <span class="n">gtk_widget_get_style</span> <span class="p">(</span><span class="n">widget</span><span class="p">)</span><span class="o">-></span><span class="n">text_gc</span><span class="p">[</span><span class="n">state</span><span class="p">];</span>
|
||
<span class="n">gdk_gc_set_clip_rectangle</span> <span class="p">(</span><span class="n">gc</span><span class="p">,</span> <span class="o">&</span><span class="n">area</span><span class="p">);</span>
|
||
<span class="cm">/* use */</span>
|
||
<span class="n">gdk_draw_layout</span> <span class="p">(</span><span class="n">drawable</span><span class="p">,</span> <span class="n">gc</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">layout</span><span class="p">);</span>
|
||
<span class="cm">/* restore */</span>
|
||
<span class="n">gdk_gc_set_clip_rectangle</span> <span class="p">(</span><span class="n">gc</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
With cairo, the same effect can be achieved using:
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8
|
||
9
|
||
10
|
||
11
|
||
12
|
||
13
|
||
14
|
||
15
|
||
16
|
||
17
|
||
18</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="n">GtkStyleContext</span> <span class="o">*</span><span class="n">context</span><span class="p">;</span>
|
||
<span class="n">GtkStateFlags</span> <span class="n">flags</span><span class="p">;</span>
|
||
<span class="n">GdkRGBA</span> <span class="n">rgba</span><span class="p">;</span>
|
||
<span class="n">cairo_t</span> <span class="o">*</span><span class="n">cr</span><span class="p">;</span>
|
||
|
||
<span class="n">cr</span> <span class="o">=</span> <span class="n">gdk_cairo_create</span> <span class="p">(</span><span class="n">drawable</span><span class="p">);</span>
|
||
<span class="cm">/* clip */</span>
|
||
<span class="n">gdk_cairo_rectangle</span> <span class="p">(</span><span class="n">cr</span><span class="p">,</span> <span class="o">&</span><span class="n">area</span><span class="p">);</span>
|
||
<span class="n">cairo_clip</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span>
|
||
<span class="cm">/* set the correct source color */</span>
|
||
<span class="n">context</span> <span class="o">=</span> <span class="n">gtk_widget_get_style_context</span> <span class="p">(</span><span class="n">widget</span><span class="p">));</span>
|
||
<span class="n">state</span> <span class="o">=</span> <span class="n">gtk_widget_get_state_flags</span> <span class="p">(</span><span class="n">widget</span><span class="p">);</span>
|
||
<span class="n">gtk_style_context_get_color</span> <span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">state</span><span class="p">,</span> <span class="o">&</span><span class="n">rgba</span><span class="p">);</span>
|
||
<span class="n">gdk_cairo_set_source_rgba</span> <span class="p">(</span><span class="n">cr</span><span class="p">,</span> <span class="o">&</span><span class="n">rgba</span><span class="p">);</span>
|
||
<span class="cm">/* draw the text */</span>
|
||
<span class="n">cairo_move_to</span> <span class="p">(</span><span class="n">cr</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">);</span>
|
||
<span class="n">pango_cairo_show_layout</span> <span class="p">(</span><span class="n">cr</span><span class="p">,</span> <span class="n">layout</span><span class="p">);</span>
|
||
<span class="n">cairo_destroy</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
Clipping using <a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-clip"><code class="function">cairo_clip()</code></a> is of course not restricted to text
|
||
rendering and can be used everywhere where GC clips were used.
|
||
And using <code class="function">gdk_cairo_set_source_color()</code> with style colors should
|
||
be used in all the places where a style’s GC was used to achieve
|
||
a particular color.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<br class="example-break"><div class="section">
|
||
<div class="titlepage"><div><div><h4 class="title">
|
||
<a name="id-1.6.3.3.8.8"></a>What should you be aware of ?</h4></div></div></div>
|
||
<p><b>No more stippling. </b>
|
||
Stippling is the usage of a bi-level mask, called a <span class="type">GdkBitmap</span>.
|
||
It was often used to achieve a checkerboard effect. You can use
|
||
<a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-mask"><code class="function">cairo_mask()</code></a> to achieve this effect. To get a checkerbox mask,
|
||
you can use code like this:
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8
|
||
9
|
||
10
|
||
11
|
||
12
|
||
13
|
||
14
|
||
15
|
||
16
|
||
17
|
||
18
|
||
19
|
||
20</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="k">static</span> <span class="n">cairo_pattern_t</span> <span class="o">*</span>
|
||
<span class="nf">gtk_color_button_get_checkered</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span>
|
||
<span class="p">{</span>
|
||
<span class="cm">/* need to respect pixman's stride being a multiple of 4 */</span>
|
||
<span class="k">static</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="n">data</span><span class="p">[</span><span class="mi">8</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span> <span class="mh">0xFF</span><span class="p">,</span> <span class="mh">0x00</span><span class="p">,</span> <span class="mh">0x00</span><span class="p">,</span> <span class="mh">0x00</span><span class="p">,</span>
|
||
<span class="mh">0x00</span><span class="p">,</span> <span class="mh">0xFF</span><span class="p">,</span> <span class="mh">0x00</span><span class="p">,</span> <span class="mh">0x00</span> <span class="p">};</span>
|
||
<span class="n">cairo_surface_t</span> <span class="o">*</span><span class="n">surface</span><span class="p">;</span>
|
||
<span class="n">cairo_pattern_t</span> <span class="o">*</span><span class="n">pattern</span><span class="p">;</span>
|
||
|
||
<span class="n">surface</span> <span class="o">=</span> <span class="n">cairo_image_surface_create_for_data</span> <span class="p">(</span><span class="n">data</span><span class="p">,</span>
|
||
<span class="n">CAIRO_FORMAT_A8</span><span class="p">,</span>
|
||
<span class="mi">2</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span>
|
||
<span class="mi">4</span><span class="p">);</span>
|
||
<span class="n">pattern</span> <span class="o">=</span> <span class="n">cairo_pattern_create_for_surface</span> <span class="p">(</span><span class="n">surface</span><span class="p">);</span>
|
||
<span class="n">cairo_surface_destroy</span> <span class="p">(</span><span class="n">surface</span><span class="p">);</span>
|
||
<span class="n">cairo_pattern_set_extend</span> <span class="p">(</span><span class="n">pattern</span><span class="p">,</span> <span class="n">CAIRO_EXTEND_REPEAT</span><span class="p">);</span>
|
||
<span class="n">cairo_pattern_set_filter</span> <span class="p">(</span><span class="n">pattern</span><span class="p">,</span> <span class="n">CAIRO_FILTER_NEAREST</span><span class="p">);</span>
|
||
|
||
<span class="k">return</span> <span class="n">pattern</span><span class="p">;</span>
|
||
<span class="p">}</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
Note that stippling looks very outdated in UIs, and is rarely
|
||
used in modern applications. All properties that made use of
|
||
stippling have been removed from GTK+ 3. Most prominently,
|
||
stippling is absent from text rendering, in particular <a class="link" href="GtkTextTag.html" title="GtkTextTag"><span class="type">GtkTextTag</span></a>.
|
||
</p>
|
||
<p><b>Using the target also as source or mask. </b>
|
||
The <code class="function">gdk_draw_drawable()</code> function allowed using the same drawable
|
||
as source and target. This was often used to achieve a scrolling
|
||
effect. Cairo does not allow this yet. You can however use
|
||
<a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-push-group"><code class="function">cairo_push_group()</code></a> to get a different intermediate target that
|
||
you can copy to. So you can replace this code:
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="n">gdk_draw_drawable</span> <span class="p">(</span><span class="n">pixmap</span><span class="p">,</span>
|
||
<span class="n">gc</span><span class="p">,</span>
|
||
<span class="n">pixmap</span><span class="p">,</span>
|
||
<span class="n">area</span><span class="p">.</span><span class="n">x</span> <span class="o">+</span> <span class="n">dx</span><span class="p">,</span> <span class="n">area</span><span class="p">.</span><span class="n">y</span> <span class="o">+</span> <span class="n">dy</span><span class="p">,</span>
|
||
<span class="n">area</span><span class="p">.</span><span class="n">x</span><span class="p">,</span> <span class="n">area</span><span class="p">.</span><span class="n">y</span><span class="p">,</span>
|
||
<span class="n">area</span><span class="p">.</span><span class="n">width</span><span class="p">,</span> <span class="n">area</span><span class="p">.</span><span class="n">height</span><span class="p">);</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
By using this code:
|
||
</p>
|
||
<div class="informalexample">
|
||
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
|
||
<tbody>
|
||
<tr>
|
||
<td class="listing_lines" align="right"><pre>1
|
||
2
|
||
3
|
||
4
|
||
5
|
||
6
|
||
7
|
||
8
|
||
9
|
||
10
|
||
11
|
||
12
|
||
13</pre></td>
|
||
<td class="listing_code"><pre class="programlisting"><span class="n">cairo_t</span> <span class="o">*</span><span class="n">cr</span> <span class="o">=</span> <span class="n">cairo_create</span> <span class="p">(</span><span class="n">surface</span><span class="p">);</span>
|
||
<span class="cm">/* clipping restricts the intermediate surface's size, so it's a good idea</span>
|
||
<span class="cm"> * to use it. */</span>
|
||
<span class="n">gdk_cairo_rectangle</span> <span class="p">(</span><span class="n">cr</span><span class="p">,</span> <span class="o">&</span><span class="n">area</span><span class="p">);</span>
|
||
<span class="n">cairo_clip</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span>
|
||
<span class="cm">/* Now push a group to change the target */</span>
|
||
<span class="n">cairo_push_group</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span>
|
||
<span class="n">cairo_set_source_surface</span> <span class="p">(</span><span class="n">cr</span><span class="p">,</span> <span class="n">surface</span><span class="p">,</span> <span class="n">dx</span><span class="p">,</span> <span class="n">dy</span><span class="p">);</span>
|
||
<span class="n">cairo_paint</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span>
|
||
<span class="cm">/* Now copy the intermediate target back */</span>
|
||
<span class="n">cairo_pop_group_to_source</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span>
|
||
<span class="n">cairo_paint</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span>
|
||
<span class="n">cairo_destroy</span> <span class="p">(</span><span class="n">cr</span><span class="p">);</span></pre></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
<p>
|
||
The surface here can be either an image surface or a X surface,
|
||
and can either be created on the spot or kept around for caching purposes.
|
||
Another alternative is to use pixbufs instead of surfaces with
|
||
<a href="https://developer.gnome.org/gdk4/gdk4-Cairo-Interaction.html#gdk-cairo-set-source-pixbuf"><code class="function">gdk_cairo_set_source_pixbuf()</code></a> instead of <a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-set-source-surface"><code class="function">cairo_set_source_surface()</code></a>.
|
||
|
||
The cairo developers plan to add self-copies in the future to allow
|
||
exactly this effect, so you might want to keep up on cairo
|
||
development to be able to change your code.
|
||
</p>
|
||
<p><b>Using pango_cairo_show_layout() instead of gdk_draw_layout_with_colors(). </b>
|
||
GDK provided a way to ignore the color attributes of text and use
|
||
a hardcoded text color with the <code class="function">gdk_draw_layout_with_colors()</code>
|
||
function. This is often used to draw text shadows or selections.
|
||
Pango’s cairo support does not yet provide this functionality. If
|
||
you use Pango layouts that change colors, the easiest way to achieve
|
||
a similar effect is using <a href="https://developer.gnome.org/pango/pango-Cairo-Rendering.html#pango-cairo-layout-path"><code class="function">pango_cairo_layout_path()</code></a> and <a href="/usr/share/gtk-doc/html/cairo/cairo-cairo-t.html#cairo-fill"><code class="function">cairo_fill()</code></a>
|
||
instead of <code class="function">gdk_draw_layout_with_colors()</code>. Note that this results in
|
||
a slightly uglier-looking text, as subpixel anti-aliasing is not
|
||
supported.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="footer">
|
||
<hr>Generated by GTK-Doc V1.32.1</div>
|
||
</body>
|
||
</html> |