forked from AuroraMiddleware/gtk
422 lines
16 KiB
XML
422 lines
16 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-x-to-y">
|
|
<title>Migrating from one GTK+ 3 release to another</title>
|
|
|
|
<para>
|
|
GTK+ 3 has seen considerable development over multiple stable releases.
|
|
While we try to maintain compatibility as far as possible, some minor
|
|
adjustments may be necessary when moving an application from one release
|
|
of GTK+ 3 to the next.
|
|
</para>
|
|
|
|
<para>
|
|
The following sections list noteworthy changes in GTK+ 3.x release that
|
|
may or may not require applications to be updated.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.2</title>
|
|
|
|
<para>
|
|
The accessible implementations for GTK+ widgets have been integrated
|
|
into libgtk itself, and the gail module does not exist anymore. This
|
|
change should not affect applications very much.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.4</title>
|
|
|
|
<para>
|
|
Scroll events have been separated from button events, and smooth
|
|
scrolling has been added with a separate event mask. Widgets now
|
|
need to have either GDK_SCROLL_MASK or GDK_SMOOTH_SCROLL_MASK in
|
|
their event mask to receive scroll events. In addition, the
|
|
GdkScrollDirection enumeration has gained a new member,
|
|
GDK_SCROLL_SMOOTH, so switch statements will have to be amended
|
|
to cover this case.
|
|
</para>
|
|
|
|
<para>
|
|
GTK+ now uses <Primary> instead of <Control> in keyboard
|
|
accelerators, for improved cross-platform handling. This should not
|
|
affect applications, unless they parse or create these accelerator
|
|
manually.
|
|
</para>
|
|
|
|
<para>
|
|
The tacit assumption that the Alt key corresponds to the MOD1
|
|
modifier under X11 is now a hard requirement.
|
|
</para>
|
|
|
|
<para>
|
|
The beagle search backend for the file chooser has been dropped.
|
|
Tracker is the only supported search backend on Linux now.
|
|
</para>
|
|
|
|
<para>
|
|
GtkNotebook has been changed to destroy its action widgets when
|
|
it gets destroyed itself. If your application is using action
|
|
widgets in notebooks, you may have to adjust your code to take
|
|
this into account.
|
|
</para>
|
|
|
|
<para>
|
|
GtkApplication no longer uses the gtk_ mainloop wrappers, so
|
|
it is no longer possible to use gtk_main_quit() to stop it.
|
|
</para>
|
|
|
|
<para>
|
|
The -uninstalled variants of the pkg-config files have been dropped.
|
|
</para>
|
|
|
|
<para>
|
|
Excessive dependencies have been culled from Requires: lines
|
|
in .pc files. Dependent modules may have to declare dependencies
|
|
that there were getting 'for free' in the past.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.6</title>
|
|
|
|
<para>
|
|
The accessibility bridge code that exports accessible objects
|
|
on the bus is now used by default; atk-bridge has been converted
|
|
into a library that GTK+ links against. To void the linking,
|
|
pass --without-atk-bridge when configuring GTK+.
|
|
</para>
|
|
|
|
<para>
|
|
GDK threading support has been deprecated. It is recommended to
|
|
use g_idle_add(), g_main_context_invoke() and similar funtions
|
|
to make all GTK+ calls from the main thread.
|
|
</para>
|
|
|
|
<para>
|
|
GTK+ now follows the XDG Base Directory specification for
|
|
user configuration and data files. In detail,
|
|
<itemizedlist>
|
|
<listitem>$XDG_CONFIG_HOME/gtk-3.0/custom-papers is the new location
|
|
for $HOME/.gtk-custom-papers</listitem>
|
|
<listitem>$XDG_CONFIG_HOME/gtk-3.0/bookmarks is the new location
|
|
for $HOME/.gtk-bookmarks</listitem>
|
|
<listitem>$XDG_DATA_HOME/themes is preferred over $HOME/.themes</listitem>
|
|
<listitem>$XDG_DATA_HOME/icons is preferred over $HOME/.icons.</listitem>
|
|
</itemizedlist>
|
|
Existing files from the old location will still be read
|
|
if the new location does not exist.
|
|
</para>
|
|
|
|
<para>
|
|
$HOME/.gtk-3.0 is no longer in the default module load path.
|
|
If you want to load modules from there, add it to the GTK_PATH
|
|
environment variable.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.8</title>
|
|
|
|
<para>
|
|
GtkIconInfo has changed from being a boxed type to a GObject.
|
|
This is technically an ABI change, but basically all existing code
|
|
will keep working if its used as a boxed type, and it is not
|
|
possible to instantiate GtkIconInfos outside GTK+, so this is
|
|
not expected to be a big problem.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.10</title>
|
|
|
|
<para>
|
|
GDK has been changed to allow only a single screen per display.
|
|
Only the X11 backend had multiple screens before, and multi-screen
|
|
setups (not multi-monitor!) are very rare nowadays. If you really
|
|
need multiple X screens, open them as separate displays.
|
|
</para>
|
|
|
|
<para>
|
|
The behavior of GtkBox::expand has been changed to never propagate
|
|
up. Previously, this was happening inconsistently. If you want the
|
|
expand to propagate, use the GtkWidget h/v expand properties.
|
|
If you experience sizing problems with widgets in ported code,
|
|
carefully check the expand and fill flags of your boxes.
|
|
</para>
|
|
|
|
<para>
|
|
GtkBin no longer provides default implementations for
|
|
get_height_for_width, subclasses now have to provide their own
|
|
implementation if they need height-for-width functionality.
|
|
</para>
|
|
|
|
<para>
|
|
Widget state propagation has been changed. Historically, all of
|
|
active, prelight, selected, insensitive, inconsistent and backdrop
|
|
have been propagated to children. This has now been restricted
|
|
to just the insensitive and backdrop states. This mostly affects
|
|
theming.
|
|
</para>
|
|
|
|
<para>
|
|
The way widget drawing happens has changed. Earlier versions handled
|
|
one expose event per GdkWindow, each with a separate cairo_t. Now we
|
|
only handle the expose event on the toplevel and reuse the same
|
|
cairo_t (with the right translation and clipping) for the entire
|
|
widget hierarchy, recursing down via the GtkWidget::draw signal.
|
|
Having all rendering in the same call tree allows effects like
|
|
opacity and offscreen rendering of entire widget sub-hierarchies.
|
|
Generally this should not require any changes in widgets, but
|
|
code looking at e.g. the current expose event may see different
|
|
behavior than before.
|
|
</para>
|
|
|
|
<para>
|
|
The Gtk+ scrolling implementation has changed. gdk_window_scroll()
|
|
and gdk_window_move_region() no longer copy the region on the
|
|
window, but rather invalidate the entire scrolled region. This is
|
|
slightly slower, but allowed us to implement a offscreen surface
|
|
scrolling method which better fits modern hardware. Most scrolling
|
|
widgets in Gtk+ have been converted to use this model for scrolling,
|
|
but external widgets implementing scrolling using GdkWindow may see
|
|
some slowdown.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.12</title>
|
|
|
|
<para>
|
|
GtkWidget had a hack where if opacity is 0.999 we set up an opacity
|
|
group when rendering the widget. This is no longer needed in 3.10,
|
|
and GtkStack doesn't use it anymore. It has been removed in 3.12.
|
|
GdStack is using it, so applications should be ported from GdStack
|
|
to GtkStack in 3.12.
|
|
</para>
|
|
|
|
<para>
|
|
GtkHeaderBar in 3.10 was not ordering its pack-end children in
|
|
the right way. This has been fixed in 3.12. Applications which
|
|
pack multiple widgets at the end of a headerbar will have to
|
|
be updated.
|
|
</para>
|
|
|
|
<para>
|
|
gtk_text_view_add_child_in_window has changed behaviour a bit.
|
|
It now always positions the child in buffer coordinates, where
|
|
it used to inconsistently scroll with the buffer but then go
|
|
reposition to a window-relative position on redraw.
|
|
</para>
|
|
|
|
<para>
|
|
A number of container widgets have been made more compliant with
|
|
the uniform CSS rendering model by making them render backgrounds
|
|
and borders. This may require some adjustments in applications that
|
|
were making assumptions about containers never rendering backgrounds.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.14</title>
|
|
|
|
<para>
|
|
A new state, GTK_STATE_FLAG_CHECKED, has been added for checked states
|
|
of radio and check buttons and menuitems. Applications that are using
|
|
GTK+ styles without widgets will need adjustments.
|
|
</para>
|
|
|
|
<para>
|
|
Adwaita is now the default theme on all platforms.
|
|
</para>
|
|
|
|
<para>
|
|
The icon theme code has become a little pickier about sizes and is not
|
|
automatically scaling icons beyond the limits defined in the icon theme
|
|
unless explicitly asked to do so with GTK_ICON_LOOKUP_FORCE_SIZE.
|
|
</para>
|
|
|
|
<para>
|
|
GTK+ now includes an interactive debugger which can be activated with
|
|
the keyboard shortcuts Ctrl-Shift-d or Ctrl-Shift-i. If these shortcuts
|
|
interfere with application keybindings, they can be disabled with the
|
|
setting org.gtk.Settings.Debug.enable-inspector-keybinding.
|
|
</para>
|
|
|
|
<para>
|
|
Most widgets have been ported to use the new gesture framework internally
|
|
for event handling. Traditional event handlers in derived widgets are still
|
|
being called.
|
|
</para>
|
|
|
|
<para>
|
|
Using GTK+ under X11 without the X Render extension has been observed
|
|
to be problematic. This combination is using code paths in cairo and
|
|
graphics drivers which are rarely tested and likely buggy.
|
|
</para>
|
|
|
|
<para>
|
|
GtkTextView is now using a pixel-cache internally, and is drawing
|
|
a background underneath the text. This can cause problems for applications
|
|
which assumed that they could draw things below and above the text
|
|
by chaining up in the ::draw implementation of their GtkTextView subclass.
|
|
As a short-term workaround, you can make the application apply a
|
|
custom theme to the text view with a transparent background. For
|
|
a proper fix, use the new ::draw_layer vfunc.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.16</title>
|
|
|
|
<para>
|
|
GTK+ now includes an OpenGL rendering widget. To support GL on various
|
|
platforms, GTK+ uses libepoxy.
|
|
</para>
|
|
|
|
<para>
|
|
GTK+ no longer uses gtk-update-icon-cache during its build. The
|
|
--enable-gtk2-dependency configure option has been removed.
|
|
</para>
|
|
|
|
<para>
|
|
The introspection annotations for the x and y parameters of
|
|
GtkMenuPositionFunc have been corrected from 'out' to 'inout'.
|
|
If you are using such a function from language-bindings, this
|
|
may require adjustments.
|
|
</para>
|
|
|
|
<para>
|
|
The lookup order for actions that are activated via keyboard
|
|
accelerators has been changed to start at the currently focused
|
|
widget. If your application is making use fo nested action groups
|
|
via gtk_widget_insert_action_group, you may want to check that
|
|
this change does not upset your accelerators.
|
|
</para>
|
|
|
|
<para>
|
|
The GtkScrollable interface has gained a new vfunc, get_border,
|
|
that is used to position overshoot and undershoot indications that
|
|
are drawn over the content by GtkScrolledWindow. Unless your scrollable
|
|
has non-scrolling parts similar to treeview headers, there is no need
|
|
to implement this vfunc.
|
|
</para>
|
|
|
|
<para>
|
|
The GtkSearchEntry widget has gained a number of new signals that
|
|
are emitted when certain key sequences are seen. In particular, it
|
|
now handles the Escape key and emits ::stop-search. Applications that
|
|
expect to handle Escape themselves will need to be updated.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.18</title>
|
|
|
|
<para>
|
|
The GtkListBox model support that was introduced in 3.16 has been
|
|
changed to no longer call gtk_widget_show_all on rows created by
|
|
the create_widget_func. You need to manage the visibility of child
|
|
widgets yourself in your create_widget_func.
|
|
</para>
|
|
|
|
<para>
|
|
The alpha component of foreground colors that are applied to
|
|
GtkCellRendererText is no longer ignored. If you don't want your
|
|
text to be translucent, use opaque colors.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.20</title>
|
|
|
|
<para>
|
|
The way theming works in GTK+ has been reworked fundamentally, to
|
|
implement many more CSS features and make themes more expressive.
|
|
As a result, custom CSS that is shipped with applications and third-party
|
|
themes will need adjustments. Widgets now use element names much more
|
|
than style classes; type names are no longer used in style matching.
|
|
Every widget now documents the element names it has and the style classes
|
|
it uses. The GTK+ inspector can also help with finding this information.
|
|
</para>
|
|
|
|
<para>
|
|
GTK+ now uses internal subobjects (also known as gadgets) for allocating
|
|
and drawing widget parts. Applications that subclass GTK+ widgets may see
|
|
warnings if they override the size_allocate vfunc and don't chain up.
|
|
The proper way to subclass is to chain up in size_allocate. If you do not
|
|
want to do that for some reason, you have to override the draw vfunc as
|
|
well.
|
|
</para>
|
|
|
|
<para>
|
|
Several fixes for window sizing and window placement with client-side
|
|
decorations may affect applications that are saving and restoring window
|
|
sizes. The recommended best practice for this which is known to work with
|
|
client-side and server-side decorations and with older and newer versions
|
|
of GTK+ is to use gtk_window_get_size() to save window sizes and
|
|
gtk_window_set_default_size() to restore it.
|
|
See https://wiki.gnome.org/HowDoI/SaveWindowState for a detailed example.
|
|
</para>
|
|
|
|
<para>
|
|
Geometry handling in GtkWindow has been removed. If you are using the
|
|
functions gtk_window_resize_to_geometry, gtk_window_set_default_geometry,
|
|
gtk_window_parse_geometry or gtk_window_set_geometry_hints, you may need
|
|
to make some changes to your code.
|
|
</para>
|
|
|
|
<para>
|
|
GtkDrawingArea used to implicitly render the theme background before
|
|
calling the ::draw handler. This is no longer the case. If you rely
|
|
on having a theme-provided background, call gtk_render_background()
|
|
from your ::draw handler.
|
|
</para>
|
|
|
|
<para>
|
|
The GtkFileChooser interface prerequisite changed from GtkWidget
|
|
to GObject, allowing non-widget implementations of this interface.
|
|
This is a minor change in ABI, as applications are no longer guaranteed
|
|
that a GtkFileChooser also supports all GtkWidget methods. However, all
|
|
previously existing implementations still derive from GtkWidget, so no
|
|
existing code should break.
|
|
</para>
|
|
|
|
<para>
|
|
The way in which GtkLevelBar determines the offset to apply was a bit
|
|
inconsistent in the past; this has been fixed. Applications that are using
|
|
custom offsets should double-check that their levels look as expected.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Changes in GTK+ 3.22</title>
|
|
|
|
<para>
|
|
The CSS parser has gotten a bit more selective in what it accepts as
|
|
valid values for the font: shorthand. Following the CSS specification,
|
|
at least a size and a family name are required now. If you want to
|
|
change an individual facet of the font, like the weight, use the
|
|
individual CSS properties: font-weight, font-size, font-family, etc.
|
|
</para>
|
|
|
|
<para>
|
|
The CSS parser now warns about some more constructs that are not according
|
|
to the CSS spec, such as gradients with a single color stop. Instead,
|
|
you can just use image(<color>).
|
|
</para>
|
|
|
|
<para>
|
|
The #GtkSizeGroup:ignore-hidden property has not been working properly
|
|
for a long time, and we've not documented it as broken and deprecated.
|
|
The recommended alternative for reserving space of widgets that are not
|
|
currently shown in the UI is to use a #GtkStack (with some 'filler'
|
|
widget, e.g. an empty #GtkBox, in another page).
|
|
</para>
|
|
</section>
|
|
</chapter>
|