forked from AuroraMiddleware/gtk
858 lines
32 KiB
XML
858 lines
32 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 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.24, 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 using
|
|
an older version of GTK 3.x, you should first get your application
|
|
to build and work with the latest minor release in the 3.24 series.
|
|
</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.24/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>Enable diagnostic warnings</title>
|
|
<para>
|
|
Deprecations of properties and signals cannot be caught at compile
|
|
time, as both properties and signals are installed and used after
|
|
types have been instantiated. In order to catch deprecations and
|
|
changes in the run time components, you should use the
|
|
<envar>G_ENABLE_DIAGNOSTIC</envar> environment variable when
|
|
running your application, e.g.:
|
|
<programlisting>
|
|
G_ENABLE_DIAGNOSTIC=1 ./your-app
|
|
</programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Do not use widget style properties</title>
|
|
<para>
|
|
Style properties do not exist in GTK 4. You should stop using them in
|
|
your custom CSS and in your code.
|
|
</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
|
|
<literal>gdk_window_set_visual (gdk_screen_get_rgba_visual ())</literal>
|
|
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>
|
|
<para>
|
|
At the same time, you should stop using GdkVisual APIs, this object
|
|
not longer exist in GTK 4. Most of its APIs are deprecated already
|
|
and not useful when dealing with RGBA visuals.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GtkBox:padding, GtkBox:fill and GtkBox:expand</title>
|
|
<para>
|
|
GTK 4 removes these #GtkBox child properties, so you should not use them.
|
|
You can replace GtkBox:padding using the #GtkWidget:margin properties
|
|
on your #GtkBox child widgets.
|
|
</para>
|
|
<para>
|
|
The fill child property can be replaced by setting appropriate values
|
|
for the #GtkWidget:halign and #GtkWidget:valign properties of the child
|
|
widgets. If you previously set the fill child property to %TRUE, you can
|
|
achieve the same effect by setting the halign or valign properties to
|
|
%GTK_ALIGN_FILL, depending on the parent box -- halign for a horizontal
|
|
box, valign for a vertical one.
|
|
</para>
|
|
<para>
|
|
#GtkBox also uses the expand child property. It can be replaced by setting
|
|
#GtkWidget:hexpand or #GtkWidget:vexpand on the child widgets. To match the
|
|
old behavior of the #GtkBox's expand child property, you need to set
|
|
#GtkWidget:hexpand on the child widgets of a horizontal #GtkBox and
|
|
#GtkWidget:vexpand on the child widgets of a vertical #GtkBox.
|
|
</para>
|
|
<para>
|
|
Note that there's a subtle but important difference between #GtkBox's
|
|
expand and fill child properties and the ones in #GtkWidget: setting
|
|
#GtkWidget:hexpand or #GtkWidget:vexpand to %TRUE will propagate up
|
|
the widget hierarchy, so a pixel-perfect port might require you to reset
|
|
the expansion flags to %FALSE in a parent widget higher up the hierarchy.
|
|
</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. You should update all callers to pass
|
|
the current state.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using gdk_pixbuf_get_from_window() and gdk_cairo_set_source_surface()</title>
|
|
<para>
|
|
These functions are not supported in GTK 4. Instead, either use backend-specific
|
|
APIs, or render your widgets using gtk_widget_render().
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GtkButton's image-related API</title>
|
|
<para>
|
|
The functions and properties related to automatically add a GtkImage
|
|
to a GtkButton, and using a GtkSetting to control its visibility, are
|
|
not supported in GTK 4. Instead, you can just pack a GtkImage inside
|
|
a GtkButton, and control its visibility like you would for any other
|
|
widget. If you only want to add a named icon to a GtkButton, you can
|
|
use gtk_button_set_icon_name().
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GtkWidget event signals</title>
|
|
<para>
|
|
Event controllers and #GtkGestures replace event signals in GTK 4.
|
|
They have been backported to GTK 3.x so you can prepare for this change.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Set a proper application ID</title>
|
|
<para>
|
|
In GTK 4 we want the application's #GApplication
|
|
'application-id' (and therefore the D-Bus name), the desktop
|
|
file basename and Wayland's xdg-shell app_id to match. In
|
|
order to achieve this with GTK 3.x call g_set_prgname() with the same
|
|
application ID you passed to #GtkApplication. Rename your
|
|
desktop files to match the application ID if needed.
|
|
</para>
|
|
<para>
|
|
The call to g_set_prgname() can be removed once you fully migrated
|
|
to GTK 4.
|
|
</para>
|
|
<para>
|
|
You should be aware that changing the application ID makes your
|
|
application appear as a new, different app to application installers.
|
|
You should consult the appstream documentation for best practices
|
|
around renaming applications.
|
|
</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>Convert your ui files</title>
|
|
|
|
<para>
|
|
A number of the changes outlined below affect .ui files. The
|
|
gtk4-builder-tool simplify command can perform many of the
|
|
necessary changes automatically, when called with the --3to4
|
|
option. You should always review the resulting changes.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GdkScreen</title>
|
|
<para>
|
|
The GdkScreen object has been removed in GTK 4. Most of its APIs already
|
|
had replacements in GTK 3 and were deprecated, a few remaining replacements
|
|
have been added to GdkDisplay.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using the root window</title>
|
|
<para>
|
|
The root window is an X11-centric concept that is no longer exposed in the
|
|
backend-neutral GDK API. gdk_surface_get_parent() will return %NULL for toplevel
|
|
windows. If you need to interact with the X11 root window, you can use
|
|
gdk_x11_display_get_xrootwindow() to get its XID.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GdkVisual</title>
|
|
<para>
|
|
This object is not useful with current GTK drawing APIs and has been removed
|
|
without replacement.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GdkDeviceManager</title>
|
|
<para>
|
|
The GdkDeviceManager object has been removed in GTK 4. Most of its APIs already
|
|
had replacements in GTK 3 and were deprecated in favor of GdkSeat.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to GdkWindow API changes</title>
|
|
<para>
|
|
GdkWindow has been renamed to GdkSurface.
|
|
</para>
|
|
<para>
|
|
The gdk_window_new() function has been replaced by a number of more
|
|
specialized constructors: gdk_surface_new_toplevel(), gdk_surface_new_popup(),
|
|
gdk_surface_new_temp(), gdk_wayland_surface_new_subsurface().
|
|
Use the appropriate ones to create your windows.
|
|
</para>
|
|
<para>
|
|
Native and foreign subwindows are no longer supported. These concepts were
|
|
complicating the code and could not be supported across backends.
|
|
</para>
|
|
<para>
|
|
gdk_window_reparent() is no longer available.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop accessing GdkEvent fields</title>
|
|
<para>
|
|
Direct access to GdkEvent structs is no longer possible in GTK 4. Some
|
|
frequently-used fields already had accessors in GTK 3, and the remaining
|
|
fields have gained accessors in GTK 4.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using gdk_surface_set_event_compression</title>
|
|
<para>
|
|
Event compression is now always enabled. If you need to see the uncoalesced
|
|
motion history, use gdk_event_get_motion_history().
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using gdk_pointer_warp()</title>
|
|
<para>
|
|
Warping the pointer is disorienting and unfriendly to users.
|
|
GTK 4 does not support it. In special circumstances (such as when
|
|
implementing remote connection UIs) it can be necessary to
|
|
warp the pointer; in this case, use platform APIs such as XWarpPointer
|
|
directly.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to coordinate API changes</title>
|
|
<para>
|
|
A number of coordinate APIs in GTK 3 had _double variants:
|
|
gdk_device_get_position(), gdk_device_get_surface_at_position(),
|
|
gdk_surface_get_device_position(). These have been changed to use
|
|
doubles, and the _double variants have been removed. Update your
|
|
code accordingly.
|
|
</para>
|
|
<para>
|
|
Any APIs that deal with global (or root) coordinates have been
|
|
removed in GTK4, since not all backends support them. You should
|
|
replace your use of such APIs with surface-relative equivalents.
|
|
Examples of this are gdk_surfae_get_origin(), gdk_surface_move()
|
|
or gdk_event_get_root_coords().
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to GdkKeymap API changes</title>
|
|
<para>
|
|
The way to get a keymap has changed slightly. gdk_keymap_get_for_display() has
|
|
been renamed to gdk_display_get_keymap().
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to event controller API changes</title>
|
|
<para>
|
|
A few changes to the event controller and #GtkGesture APIs
|
|
did not make it back to GTK3, and have to be taken into account
|
|
when moving to GTK4. One is that the
|
|
#GtkEventControllerMotion::enter,
|
|
#GtkEventControllerMotion::leave,
|
|
#GtkEventControllerKey::focus-in and
|
|
#GtkEventControllerKey::focus-out signals
|
|
have gained new arguments. Another is that #GtkGestureMultiPress
|
|
has been renamed to #GtkGestureClick.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GtkEventBox</title>
|
|
<para>
|
|
GtkEventBox is no longer needed and has been removed.
|
|
All widgets receive all events.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GtkButtonBox</title>
|
|
<para>
|
|
GtkButtonBox has been removed. Use a GtkBox instead.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to GtkButton API changes</title>
|
|
<para>
|
|
GtkBox no longer has pack-start and -end. Pack your widgets in the
|
|
correct order, or reorder them as necessary.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to GtkHeaderBar and GtkActionBar API changes</title>
|
|
<para>
|
|
The gtk_header_bar_set_show_close_button() function has been renamed to
|
|
the more accurate name gtk_header_bar_set_show_title_buttons(). The corresponding
|
|
getter and the property itself have also been renamed.
|
|
</para>
|
|
<para>
|
|
The ::pack-type child properties of GtkHeaderBar and GtkActionBar have
|
|
been removed. If you need to programmatically place children, use the
|
|
pack_start() and pack_end() APIs. In ui files, use the type attribute
|
|
on the child element.
|
|
</para>
|
|
<para>
|
|
gtk4-builder-tool can help with this conversion, with the --3to4 option
|
|
of the simplify command.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to GtkStack, GtkAssistant and GtkNotebook API changes</title>
|
|
<para>
|
|
The child properties of GtkStack, GtkAssistant and GtkNotebook have been
|
|
converted into child meta objects.
|
|
Instead of gtk_container_child_set (stack, child, …), you can now use
|
|
g_object_set (gtk_stack_get_page (stack, child), …). In .ui files, the
|
|
GtkStackPage objects must be created explicitly, and take the child widget
|
|
as property. GtkNotebook and GtkAssistant are similar.
|
|
</para>
|
|
<para>
|
|
gtk4-builder-tool can help with this conversion, with the --3to4 option
|
|
of the simplify command.
|
|
</para>
|
|
</section>
|
|
|
|
<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>
|
|
<title>Adapt to GtkCssProvider API changes</title>
|
|
<para>
|
|
In GTK 4, the various #GtkCssProvider load functions have lost
|
|
their #GError argument. If you want to handle CSS loading errors,
|
|
use the #GtkCssProvider::parsing-error signal instead.
|
|
</para>
|
|
<para>
|
|
gtk_css_provider_get_named() has been replaced by
|
|
gtk_css_provider_load_named().
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GtkContainer::border-width</title>
|
|
<para>
|
|
GTK 4 has removed the #GtkContainer::border-width property.
|
|
Use other means to influence the spacing of your containers,
|
|
such as the CSS margin and padding properties on child widgets.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to GtkWidget's size request changes</title>
|
|
<para>
|
|
GTK 3 used five different virtual functions in GtkWidget to
|
|
implement size requisition, namely the gtk_widget_get_preferred_width()
|
|
family of functions. To simplify widget implementations, GTK 4 uses
|
|
only one virtual function, GtkWidgetClass::measure() that widgets
|
|
have to implement.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to GtkWidget's size allocation changes</title>
|
|
<para>
|
|
The #GtkWidget::size-allocate signal now takes the baseline as an
|
|
argument, so you no longer need to call gtk_widget_get_allocated_baseline()
|
|
to get it.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Switch to GtkWidget's children APIs</title>
|
|
<para>
|
|
Instead of the GtkContainer subclass, in GTK 4, any widget can
|
|
have children, and there is new API to navigate the widget tree:
|
|
gtk_widget_get_first_child(), gtk_widget_get_last_child(),
|
|
gtk_widget_get_next_sibling(), gtk_widget_get_prev_sibling().
|
|
The GtkContainer API still works, but if you are implementing
|
|
your own widgets, you should consider using the new APIs.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Don't use -gtk-gradient in your CSS</title>
|
|
<para>
|
|
GTK now supports standard CSS syntax for both linear and radial
|
|
gradients, just use those.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Don't use -gtk-icon-effect in your CSS</title>
|
|
<para>
|
|
GTK now supports a more versatile -gtk-icon-filter instead. Replace
|
|
-gtk-icon-effect: dim; with -gtk-icon-filter: opacity(0.5); and
|
|
-gtk-icon-effect: hilight; with -gtk-icon-filter: brightness(1.2);.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Use gtk_widget_measure</title>
|
|
<para>
|
|
gtk_widget_measure() replaces the various gtk_widget_get_preferred_ functions
|
|
for querying sizes.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to drawing model changes</title>
|
|
<para>
|
|
This area has seen the most radical changes in the transition from GTK 3
|
|
to GTK 4. Widgets no longer use a draw() function to render their contents
|
|
to a cairo surface. Instead, they have a snapshot() function that creates
|
|
one or more GskRenderNodes to represent their content. Third-party widgets
|
|
that use a draw() function or a #GtkWidget::draw signal handler for custom
|
|
drawing will need to be converted to use gtk_snapshot_append_cairo().
|
|
</para>
|
|
<para>
|
|
The auxiliary #GtkSnapshot object has APIs to help with creating render
|
|
nodes.
|
|
</para>
|
|
<para>
|
|
If you are using a #GtkDrawingArea for custom drawing, you need to switch
|
|
to using gtk_drawing_area_set_draw_func() to set a draw function instead
|
|
of connnecting a handler to the #GtkWidget::draw signal.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using APIs to query GdkSurfaces</title>
|
|
<para>
|
|
A number of APIs for querying special-purpose windows have been removed,
|
|
since these windows are no longer publically available:
|
|
gtk_tree_view_get_bin_window(), gtk_viewport_get_bin_window(),
|
|
gtk_viewport_get_view_window().
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Widgets are now visible by default</title>
|
|
<para>
|
|
The default value of #GtkWidget::visible in GTK 4 is %TRUE, so you no
|
|
longer need to explicitly show all your widgets. On the flip side, you
|
|
need to hide widgets that are not meant to be visible from the start.
|
|
</para>
|
|
<para>
|
|
A convenient way to remove unnecessary property assignments like this
|
|
from ui files it run the command <command>gtk4-builder-tool simplify --replace</command>
|
|
on them.
|
|
</para>
|
|
<para>
|
|
The function gtk_widget_show_all(), the #GtkWidget::no-show-all property
|
|
and its getter and setter have been removed in GTK 4, so you should stop using them.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to changes in animated hiding and showing of widgets</title>
|
|
<para>
|
|
Widgets that appear and disappear with an animation, such as GtkPopover,
|
|
GtkInfoBar, GtkRevealer no longer use gtk_widget_show() and gtk_widget_hide()
|
|
for this, but have gained dedicated APIs for this purpose that you should
|
|
use.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop passing commandline arguments to gtk_init</title>
|
|
<para>
|
|
The gtk_init() and gtk_init_check() functions no longer accept commandline
|
|
arguments. Just call them without arguments. Other initialization functions
|
|
that were purely related to commandline argument handling, such as
|
|
gtk_parse_args() and gtk_get_option_group(), are gone. The APIs to
|
|
initialize GDK separately are also gone, but it is very unlikely
|
|
that you are affected by that.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>GdkPixbuf is deemphasized</title>
|
|
<para>
|
|
A number of #GdkPixbuf-based APIs have been removed. The available replacements
|
|
are either using #GIcon, or the newly introduced #GdkTexture or #GdkPaintable
|
|
classes instead.
|
|
</para>
|
|
<para>
|
|
If you are dealing with pixbufs, you can use gdk_texture_new_for_pixbuf()
|
|
to convert them to texture objects where needed.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>GtkWidget event signals are removed</title>
|
|
<para>
|
|
Event controllers and #GtkGestures have already been introduced in GTK 3 to handle
|
|
input for many cases. In GTK 4, the traditional widget signals for handling input,
|
|
such as #GtkWidget::motion-event or #GtkWidget::event have been removed.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Invalidation handling has changed</title>
|
|
<para>
|
|
Only gtk_widget_queue_draw() is left to mark a widget as needing redraw.
|
|
Variations like gtk_widget_queue_draw_rectangle() or gtk_widget_queue_draw_region()
|
|
are no longer available.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using GtkWidget::draw</title>
|
|
<para>
|
|
The #GtkWidget::draw signal has been removed. Widgets need to implement the
|
|
#GtkWidget::snapshot function now. Connecting draw signal handlers is no longer possible.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Window content observation has changed</title>
|
|
<para>
|
|
Observing widget contents and widget size is now done by using the
|
|
#GtkWidgetPaintable object instead of connecting to widget signals.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>The gtk_window_fullscreen_on_monitor API has changed</title>
|
|
<para>
|
|
Instead of a monitor number, gtk_window_fullscreen_on_monitor() now takes a
|
|
#GdkMonitor argument.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to cursor API changes</title>
|
|
<para>
|
|
Use the new gtk_widget_set_cursor() function to set cursors, instead of
|
|
setting the cursor on the underlying window directly. This is necessary
|
|
because most widgets don't have their own window anymore, turning any
|
|
such calls into global cursor changes.
|
|
</para>
|
|
<para>
|
|
For creating standard cursors, gdk_cursor_new_for_display() has been removed,
|
|
you have to use cursor names instead of GdkCursorType. For creating custom cursors,
|
|
use gdk_cursor_new_from_texture(). The ability to get cursor images has been removed.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to icon size API changes</title>
|
|
<para>
|
|
Instead of the existing extensible set of symbolic icon sizes, GTK now only
|
|
supports normal and large icons with the #GtkIconSize enumeration. The actual sizes
|
|
can be defined by themes via the CSS property -gtk-icon-size.
|
|
</para>
|
|
<para>
|
|
GtkImage setters like gtk_image_set_from_icon_name() no longer take a #GtkIconSize
|
|
argument. You can use the separate gtk_image_set_icon_size() setter if you need
|
|
to override the icon size.
|
|
</para>
|
|
<para>
|
|
The ::stock-size property of GtkCellRendererPixbuf has been renamed to
|
|
#GtkCellRendererPixbuf:icon-size.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Convert .ui files</title>
|
|
<para>
|
|
The simplify command of gtk4-builder-tool has gained a --3to4 option, which
|
|
can help with some of the required changes in .ui files, such as converting
|
|
child properties to child meta objects.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to changes in the GtkAssistant API</title>
|
|
<para>
|
|
The ::has-padding property is gone, and GtkAssistant no longer adds padding
|
|
to pages. You can easily do that yourself.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to changes in the API of GtkEntry, GtkSearchEntry and GtkSpinButton</title>
|
|
<para>
|
|
The GtkEditable has been made more useful, and the core functionality of
|
|
GtkEntry has been broken out as a GtkText widget. GtkEntry, GtkSearchEntry,
|
|
GtkSpinButton and the new GtkPasswordEntry now use a GtkText widget internally
|
|
and implement GtkEditable. In particular, this means that it is no longer
|
|
possible to use GtkEntry API such as gtk_entry_grab_focus_without_selecting()
|
|
on a search entry.
|
|
</para>
|
|
<para>
|
|
Use GtkEditable API for editable functionality, and widget-specific APIs for
|
|
things that go beyond the common interface. For password entries, use
|
|
GtkPasswordEntry. As an example, gtk_spin_button_set_max_width_chars()
|
|
has been removed in favor of gtk_editable_set_max_width_chars().
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to changes in GtkOverlay API</title>
|
|
<para>
|
|
The GtkOverlay::pass-through child property has been replaced by the
|
|
GtkWidget::can-pick property. Note that they have the opposite sense:
|
|
pass-through == !can-pick.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Use GtkFixed instead of GtkLayout</title>
|
|
<para>
|
|
Since GtkScrolledWindow can deal with widgets that do not implement
|
|
the GtkScrollable interface by automatically wrapping them into a
|
|
GtkViewport, GtkLayout is redundant, and has been removed in favor
|
|
of the existing GtkFixed container widget.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Adapt to search entry changes</title>
|
|
<para>
|
|
The way search entries are connected to global events has changed;
|
|
gtk_search_entry_handle_event() has been dropped and replaced by
|
|
gtk_search_entry_set_key_capture_widget() and
|
|
gtk_event_controller_key_forward().
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using child properties</title>
|
|
<para>
|
|
GtkContainer no longer provides facilities for defining and using
|
|
child properties. If you have custom widgets using child properties,
|
|
they will have to be converted either to layout properties provided
|
|
by a layout manager (if they are layout-related), or handled in
|
|
some other way. One possibility is to use child meta objects,
|
|
as seen with GtkAssistantPage, GtkStackPage and the like.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using tabular menus</title>
|
|
<para>
|
|
Tabular menus were rarely used and complicated the menu code,
|
|
so they have been removed. If you need complex layout in menu-like
|
|
popups, consider using a #GtkPopover instead.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using gtk_menu_set_display()</title>
|
|
<para>
|
|
This function has been removed. Menus should always be
|
|
attached to a widget and get their display that way.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using gtk_window_activate_default()</title>
|
|
<para>
|
|
The handling of default widgets has been changed, and activating
|
|
the default now works by calling gtk_widget_activate_default()
|
|
on the widget that caused the activation.
|
|
</para>
|
|
<para>
|
|
If you have a custom widget that wants to override the default
|
|
handling, you can provide an implementation of the default.activate
|
|
action in your widgets' action groups.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop setting ::has-default and ::has-focus in .ui files</title>
|
|
<para>
|
|
The special handling for the ::has-default and ::has-focus properties
|
|
has been removed. If you want to define the initial focus or the
|
|
the default widget in a .ui file, set the ::default-widget or
|
|
::focus-widget properties of the toplevel window.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Stop using the GtkWidget::display-changed signal</title>
|
|
<para>
|
|
To track the current display, use the GtkWidget::root property
|
|
instead.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>GtkPopover::modal has been renamed to autohide</title>
|
|
<para>
|
|
The modal property has been renamed to autohide.
|
|
gtk-builder-tool can assist with the rename in ui files.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>gtk_widget_get_surface has been removed</title>
|
|
<para>
|
|
gtk_widget_get_surface() has been removed.
|
|
Use gtk_native_get_surface() in combination with
|
|
gtk_widget_get_native() instead.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>gtk_widget_is_toplevel has been removed</title>
|
|
<para>
|
|
gtk_widget_is_toplevel() has been removed.
|
|
Use GTK_IS_ROOT, GTK_IS_NATIVE or GTK_IS_WINDOW
|
|
instead, as appropriate.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>gtk_widget_get_toplevel has been removed</title>
|
|
<para>
|
|
gtk_widget_get_toplevel() has been removed.
|
|
Use gtk_widget_get_root() or gtk_widget_get_native()
|
|
instead, as appropriate.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>GtkEntryBuffer ::deleted-text has changed</title>
|
|
<para>
|
|
To allow signal handlers to access the deleted text before it
|
|
has been deleted #GtkEntryBuffer::deleted-text has changed from
|
|
%G_SIGNAL_RUN_FIRST to %G_SIGNAL_RUN_LAST. The default handler
|
|
removes the text from the #GtkEntryBuffer.
|
|
</para>
|
|
<para>
|
|
To adapt existing code, use g_signal_connect_after() or
|
|
%G_CONNECT_AFTER when using g_signal_connect_data() or
|
|
g_signal_connect_object().
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>The "iconified" window state has been renamed to "minimized"</title>
|
|
<para>
|
|
The <literal>GDK_SURFACE_STATE_ICONIFIED</literal> value of the
|
|
#GdkSurfaceState enumeration is now %GDK_SURFACE_STATE_MINIMIZED.
|
|
</para>
|
|
<para>
|
|
The #GdkSurface functions <function>gdk_surface_iconify()</function>
|
|
and <function>gdk_surface_deiconify()</function> have been renamed to
|
|
gdk_surface_minimize() and gdk_surface_unminimize(), respectively.
|
|
</para>
|
|
<para>
|
|
The corresponding #GtkWindow functions <function>gtk_window_iconify()</function>
|
|
and <function>gtk_window_deiconify()</function> have been renamed
|
|
to gtk_window_minimize() and gtk_window_unminimize(), respectively.
|
|
</para>
|
|
<para>
|
|
The behavior of the minimization and unminimization operations have
|
|
not been changed, and they still require support from the underlying
|
|
windowing system.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
|