forked from AuroraMiddleware/gtk
128 lines
4.7 KiB
XML
128 lines
4.7 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
|
|
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
|
|
]>
|
|
<chapter id="gtk-migrating-3-to-4">
|
|
<title>Migrating from GTK+ 3.x to GTK+ 4</title>
|
|
|
|
<para>
|
|
GTK+ 4 is a major new version of GTK+ that breaks both API and ABI
|
|
compared to GTK+ 3.x. 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+ 3.x application for the switch to GTK+ 4. 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+ 4.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Preparation in GTK+ 3.x</title>
|
|
|
|
<para>
|
|
The steps outlined in the following sections assume that your
|
|
application is working with GTK+ 3.22, which is the final stable
|
|
release of GTK+ 3.x. It includes all the necessary APIs and tools
|
|
to help you port your application to GTK+ 4. If you are still using
|
|
an older version of GTK+ 3.x, you should first get your application
|
|
to build and work with 3.22.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Do not use deprecated symbols</title>
|
|
<para>
|
|
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+ 3 also includes an
|
|
<ulink url="https://developer.gnome.org/gtk3/3.22/api-index-deprecated.html">index</ulink> of all deprecated symbols.
|
|
</para>
|
|
<para>
|
|
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:
|
|
<programlisting>
|
|
make CFLAGS+="-DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED"
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Review your window creation flags</title>
|
|
<para>
|
|
GTK+ 4 removes the GDK_WA_CURSOR flag. Instead, just use
|
|
gdk_window_set_cursor() to set a cursor on the window after
|
|
creating it.
|
|
</para>
|
|
<para>
|
|
GTK+ 4 also removes the GDK_WA_VISUAL flag, and always uses
|
|
an RGBA visual for windows. To prepare your code for this,
|
|
use gdk_window_set_visual (gdk_screen_get_rgba_visual ()) after
|
|
creating your window.
|
|
</para>
|
|
<para>
|
|
GTK+ 4 also removes the GDK_WA_WMCLASS flag. If you need this
|
|
X11-specific functionality, use XSetClassHint() directly.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using non-RGBA visuals</title>
|
|
<para>
|
|
GTK+ 4 always uses RGBA visuals for its windows; you should make
|
|
sure that your code works with that.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GtkBox::padding</title>
|
|
<para>
|
|
GTK+ 4 removes the #GtkBox::padding child property, so you should
|
|
use other ways to influence the layout of your boxes.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using the state argument of GtkStyleContext getters</title>
|
|
<para>
|
|
The getters in the GtkStyleContext API, such as
|
|
gtk_style_context_get_property(), gtk_style_context_get(),
|
|
or gtk_style_context_get_color() only accept the context's current
|
|
state for their state argument. Update all callers to pass the current
|
|
state.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes that need to be done at the time of the switch</title>
|
|
|
|
<para>
|
|
This section outlines porting tasks that you need to tackle when
|
|
you get to the point that you actually build your application against
|
|
GTK+ 4. Making it possible to prepare for these in GTK+ 3 would
|
|
have been either impossible or impractical.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Adapt to GtkStyleContext API changes</title>
|
|
<para>
|
|
The getters in the GtkStyleContext API, such as
|
|
gtk_style_context_get_property(), gtk_style_context_get(),
|
|
or gtk_style_context_get_color() have lost their state argument,
|
|
and always use the context's current state. Update all callers
|
|
to omit the state argument.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
|