* Porting Emacs to GTK 4
  GTK 4 is a new major release of the GTK toolkit, which brings
  faster and better rendering, improved broadway support, and
  massive restructuring and modernization to GTK.

  This documents the effort being undertaken to port Emacs to
  GTK 4.
** Important issues that should be addressed
*** gtk_main_iteration () has been removed
    ~gtk_main_iteration ()~ has been removed. This means all
    occurrences of ~gtk_main_iteration ()~ must be replaced
    with ~g_main_context_iteration ()~, like:
    #+NAME: GTK event loop iteration
    #+BEGIN_SRC C
#include <gtk/gtk.h>

int main (void)
  {
    g_main_context_iteration (NULL, false);
  }

    #+END_SRC

*** Menus need to be implemented from scratch.
    GTK 4 removes ~~GtkMenuShell~~, and associated classes.
    GtkPopovers are a far more modern replacement, but require
    a rewrite of the menu handling system.

*** GdkScreen is gone.
    Emacs makes heavy usage of the deprecated obsolete APIs in
    GdkScreen, which need to be replaced.

** What has been done
*** gtkutil.c has been removed
    ~~gtkutil.c~~ is obsolete and will no longer be used for GTK 4
    builds. GTK-related procedures for GTK 4 have been moved or
    rewritten, and are now placed in ~~pgtksubr.c~~.

*** All object files now compile without errors
    Several functions are not yet implemented, and cause the
    executable to fail to link.
*** Emacs now compiles without errors
*** The configure scripts now detect and use GTK 4.
** What will be done
   Everything in this section will be completed sooner or later
*** DONE Make it build
    Emacs now compiles without errors.
*** DONE Make basic functionality, such as window creation and drawing work
    Emacs successfully draws to the GtkDrawingArea widget.
*** DONE Make event handling work
    So far this hasn't happened yet.
*** DONE Make input method handling work
    Input methods are now fully functional on GTK 4 builds.
*** DONE Port tooltips to GTK 4
    +We rely on adding a GtkFixed to the frame overlay widget,+
    +as you can no longer intercept tooltip windows as they+
    +are being displayed.+
    +We now rely on setting the drawing area tool-tip, and manually+
    +positioning it once it is displayed.+
    We now create a fake tooltip-styled popover.
*** DONE Make kill ring <-> GTK integration work again
    Clipboard management in GTK has been moved to GDK,
    and the behaviour has been changed to better
    reflect modern display technologies. The concepts
    of "ownership", secondary selections and cut
    buffers have been abolished. This requires a
    rewrite of the selection handling code.
*** DONE Port the frame HeaderBar to GTK 4
**** DONE Implement HeaderBar tool items
     Tool items are now implemented.
**** DONE Implement header bar menus.
     Header bar (and popup menus) are not yet implemented.
*** DONE Port window pop-up menus to GTK 4
    +This will probably involve some tricks, as the new GTK popover widget+
    +does not play very well with manual event handling.+
    Popup menus have been implemented.
*** DONE Implement child frame handling for GTK 4
    ~~gtk_window_move~~ has been removed, and changes to subsurface
    handling have occurred. This means child frames will have to be
    re-implemented from scratch.
    Child frames have now been implemented. They can only be
    displayed within the bounds of the parent frame.
*** DONE Use only public APIs
    Emacs currently relies on many unstable and undocumented private
    GTK 4 interfaces in order to function. This should be eliminated.
**** DONE Extending ~~GtkEventController~~
     +Emacs does manual event handling, and reimplements much of the+
     +logic in ~~GtkGesture~~. One cannot manually handle events+
     +this way on GTK 4 without relying on private APIs.+
     Emacs now uses a ~~GtkEventControllerLegacy~~.
**** DONE Accessing ~~GdkEvent~~ fields
     Emacs relies on accessing certain private undocumented GdkEvent
     fields in order to work around certain GTK bugs. This should be
     eliminated.
**** DONE Accessing private GtkScrollbar fields
     We rely on manually retrieving the GtkRange
     associated to the GtkScrollbar.
*** DONE Implement toolkit scroll bars
    Toolkit scroll bars are now implemented. They are displayed in
    the frame overlay.
*** DONE Implement toolkit tool-bars
    Toolkit tool-bars are now implemented.
** What *won't* be done
   Functionality in this category is either made redundant by
   work done to port Emacs to GTK 4, or is obsolete anyways.