From 0c94db71475df5bf709ef727f07042b9bac79ee2 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 12 Oct 2022 16:38:18 -0400 Subject: [PATCH] Start a migration guide for GTK 5 No need to panic, GTK 5 is still years away! But it is good to write this material down while it is fresh in mind. --- docs/reference/gtk/migrating-4to5.md | 74 ++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/reference/gtk/migrating-4to5.md diff --git a/docs/reference/gtk/migrating-4to5.md b/docs/reference/gtk/migrating-4to5.md new file mode 100644 index 0000000000..2f2b5c211a --- /dev/null +++ b/docs/reference/gtk/migrating-4to5.md @@ -0,0 +1,74 @@ +Title: Preparing for GTK 5 +Slug: gtk-migrating-4-to-5 + +GTK 5 will be a major new version of GTK that breaks both API and +ABI compared to GTK 4.x. GTK 5 does not exist yet, so we cannot +be entirely sure what will be involved in a migration from GTK 4 +to GTK 5. But we can already give some preliminary hints about +the likely changes, and how to prepare for them in code that is +using GTK 4. + +### Do not use deprecated symbols + +As always, functions and types that are known to go away in the +next major version of GTK are being marked as deprecated in GTK 4. + +Removing the use of deprecated APIs is the most important step +to prepare your code for the next major version of GTK. Often, +deprecation notes will include hints about replacement APIs to +help you with this. + +Sometimes, it is helpful to have some background information about +the motivation and goals of larger API changes. + +## Cell renderers are going away + +Cell renderers were introduced in GTK 2 to support rendering of +"big data" UIs, in particular treeviews. Over the years, more +"data-like" widgets have started to use them, and cell renderers +have grown into a shadowy, alternative rendering infrastructure +that duplicates much of what widgets do, while duplicating the +code and adding their own dose of bugs. + +In GTK 4, replacement widgets for GtkTreeView, GtkIconView and +GtkComboBox have appeared: GtkListView, GtkColumnView, GtkGridView +and GtkDropDown. For GTK 5, we will take the next step and remove +all cell renderer-based widgets. + +## Themed rendering APIs are going away + +The old GTK 2 era rendering APIs for theme components like +gtk_render_frame() or gtk_render_check() have not been used by +GTK itself even in later GTK 3, but they have been kepy around +for the benefit of "external drawing" users - applications that +want their controls to look like GTK without using widgets. + +Supporting this is increasingly getting in the way of making +the GTK CSS machinery fast and correct. One notable problem is +that temporary style changes (using gtk_style_context_save()) +is breaking animations. Therefore, these APIs will be going away +in GTK 5, together with their more modern GtkSnapshot variants +like gtk_snapshot_render_background() or gtk_snapshot_render_focus(). + +The best way to render parts of your widget using CSS styling +is to use subwidgets. For example, to show a piece of text with +fonts, effects and shadows according to the current CSS style, +use a GtkLabel. + +If you have a need for custom drawing that fits into the current +(dark or light) theme, e.g. for rendering a graph, you can still +get the current style foreground color, using +[method@Gtk.Widget.get_style_color]. + +## Local stylesheets are going away + +The cascading part of GTK's CSS implementation is complicated by +the existence of local stylesheets (i.e. those added with +gtk_style_context_add_provider()). And local stylesheets are +unintuitive in that they do not apply to the whole subtree of +widgets, but just to the one widget where the stylesheet was +added. + +GTK 5 will no longer provide this functionality. The recommendations +is to use a global stylesheet (i.e. gtk_style_context_add_provider_for_display()) +and rely on style classes to make your CSS apply only where desired. -- 2.30.2