gtk2/docs/reference/gtk/migrating-3to4.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>
      <title>Stop using gtk_main() and related APIs</title>

      <para>
        GTK4 removes the gtk_main_ family of APIs. The recommended replacement
        is GtkApplication, but you can also iterate the GLib mainloop directly,
        using GMainContext APIs.
      </para>
      <para>
        The replacement for gtk_events_pending() is g_main_context_pending(),
        the replacement for gtk_main_iteration() is g_main_context_iteration().
      </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>Stop using grabs</title>
      <para>
        GTK 4 no longer provides the gdk_device_grab() or gdk_seat_grab() apis.
      </para>
      <para>
        If you need to dismiss a popup when the user clicks outside (a common
        use for grabs), you can use the GdkSurface #GdkSurface:autohide property instead.
        GtkPopover also has a #GtkPopover:autohide property.
      </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 GtkBox 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 interface 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-target property. Note that they have the opposite sense:
        pass-through == !can-target.
      </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>
      <title>GtkMenu, GtkMenuBar and GtkMenuItem are gone</title>
      <para>
        These widgets were heavily relying on X11-centric concepts such as
        override-redirect windows and grabs, and were hard to adjust to other
        windowing systems.
      </para>
      <para>
        Menus can already be replaced using GtkPopoverMenu in GTK 3. Additionally,
        GTK 4 introduces GtkPopoverMenuBar to replace menubars. These new widgets
        can only be constructed from menu models, so the porting effort involves
        switching to menu models and actions.
      </para>
      <para>
        Since menus are gone, GtkMenuButton also lost its ability to show menus,
        and needs to be used with popovers in GTK 4.
      </para>
    </section>

    <section>
      <title>GtkToolbar has been removed</title>
      <para>
        Toolbars were using outdated concepts such as requiring special toolitem
        widgets.
      </para>
      <para>
        Toolbars should be replaced by using a GtkBox with regular widgets instead.
      </para>
    </section>

    <section>
      <title>Stop using custom tooltip windows</title>
      <para>
        Tooltips no longer use GtkWindows in GTK 4, and it is no longer
        possible to provide a custom window for tooltips. Replacing the content
        of the tooltip with a custom widget is still possible, with
        gtk_tooltip_set_custom().
      </para>
    </section>

    <section>
      <title>Switch to the new DND api</title>
      <para>
        The source-side DND apis in GTK 4 have been changed to use an event controller, #GtkDragSource.
      </para>
      <para>
        Instead of calling gtk_drag_source_set() and connecting to #GtkWidget signals, you create
        a #GtkDragSource object, attach it to the widget with gtk_widget_add_controller(), and connect
        to #GtkDragSource signals. Instead of calling gtk_drag_begin() on a widget to start a drag
        manually, call gdk_drag_begin().
      </para>
      <para>
        The ::drag-data-get signal has been replaced by the #GtkDragSource::prepare signal, which
        returns a #GdkContentProvider for the drag operation.
      </para>
      <para>
        The destination-side DND apis in GTK 4 have also been changed to use and event controller,
        #GTkDropTarget.
      </para>
      <para>
        Instead of calling gtk_drag_dest_set() and connecting to #GtkWidget signals, you create
        a #GtkDropTarget object, attach it to the widget with gtk_widget_add_controller(), and
        connect to #GtkDropTarget signals.
      </para>
      <para>
        The ::drag-motion signal has been renamed to #GtkDragSource::accept, and instead of
        ::drag-data-received, you need to use async read methods on the #GdkDrop object, such
        as gdk_drop_read_value_async() or gdk_drop_read_text_async().
      </para>
    </section>

    <section>
      <title>Update to GtkFileChooser API changes</title>
      <para>
        GtkFileChooser moved to a GFile-based API. If you need to convert a
        path or a URI, use g_file_new_for_path(), g_file_new_for_commandline_arg(),
        or g_file_new_for_uri(); similarly, if you need to get a path or a URI
        from a GFile, use g_file_get_path(), or g_file_get_uri(). With the
        removal or path and URI-based functions, the "local-only" property has
        been removed; GFile can be used to access non-local as well as local
        resources.
      </para>
      <para>
        The GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER action has been removed. Use
        %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER, instead. If a new folder is needed,
        the user can create one.
      </para>
      <para>
        The "confirm-overwrite" signal, and the "do-overwrite-confirmation"
        property have been removed from GtkFileChooser. The file chooser widgets
        will automatically handle the confirmation of overwriting a file when
        using GTK_FILE_CHOOSER_ACTION_SAVE.
      </para>
      <para>
        GtkFileChooser does not support a custom extra widget any more. If you
        need to add extra widgets, use gtk_file_chooser_add_choice() instead.
      </para>
      <para>
        GtkFileChooser does not support a custom preview widget any more. If
        you need to show a custom preview, you can create your own GtkDialog
        with a GtkFileChooserWidget and your own preview widget that you
        update whenever the #GtkFileChooser::selection-changed signal is
        emitted.
      </para>
    </section>
  </section>
</chapter>