AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-12-27 22:20:24 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'migration-docs-fix' into 'main'

Browse Source 
docs: Fix various minor typos and improve formatting in the 4-to-5 migration guide

See merge request GNOME/gtk!7637
This commit is contained in:
Matthias Clasen 2024-08-21 15:17:59 +00:00
commit 2a7541342c
1 changed files with 38 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
docs/reference/gtk/migrating-4to5.md
View File

@ -24,36 +24,36 @@ 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
“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
In GTK 4, replacement widgets for `GtkTreeView`, `GtkIconView` and
`GtkComboBox` have appeared: [class@Gtk.ListView], [class@Gtk.ColumnView], [class@Gtk.GridView]
and [class@Gtk.DropDown]. 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_render_frame()` or `gtk_render_check()` have not been used by
GTK itself even in later GTK 3, but they have been kept around
for the benefit of "external drawing" users - applications that
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())
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().
in GTK 5, together with their more modern [class@Gtk.Snapshot] 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.
use a [class@Gtk.Label].
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
@ -62,28 +62,28 @@ get the current style foreground color, using
## Local stylesheets are going away
The cascading part of GTK's CSS implementation is complicated by
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
`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())
GTK 5 will no longer provide this functionality. The recommendation
is to use a global stylesheet (i.e. [func@Gtk.StyleContext.add_provider_for_display])
and rely on style classes to make your CSS apply only where desired.
## Non-standard CSS extensions are going away
GTK's CSS machinery has a some non-standard extensions around colors:
named colors with \@define-color and color functions: lighter(), darker(),
shade(), alpha(), mix().
GTK’s CSS machinery has a some non-standard extensions around colors:
named colors with `@define-color` and color functions: `lighter()`, `darker()`,
`shade()`, `alpha()`, `mix()`.
GTK now implements equivalent functionality from the CSS specs.
### \@define-color is going away
### `@define-color` is going away
\@define-color should be replaced by custom properties in the :root scope.
`@define-color` should be replaced by custom properties in the `:root` scope.
Instead of
@ -117,9 +117,9 @@ spec.
### Color expressions are going away
The color functions can all be replaced by combinations of calc() and color-mix().
The color functions can all be replaced by combinations of `calc()` and `color-mix()`.
ligher(c) and darker(c) are just shade(c, 1.3) or shade(c, 0.7), respectively, and
`lighter(c)` and `darker(c)` are just `shade(c, 1.3)` or `shade(c, 0.7)`, respectively, and
thus can be handled the same way as shade in the examples below.
Replace
@ -164,7 +164,7 @@ d {
Variations of these replacements are possible.
Note that GTK has historically computed mix() and shade() values in the SRGB and HSL
Note that GTK has historically computed `mix()` and `shade()` values in the SRGB and HSL
colorspaces, but using OKLAB instead might yield slightly better results.
For more information about color-mix(), see the
@ -172,32 +172,32 @@ For more information about color-mix(), see the
## Chooser interfaces are going away
The GtkColorChooser, GtkFontChooser, GtkFileChooser and GtkAppChooser
The `GtkColorChooser`, `GtkFontChooser`, `GtkFileChooser` and `GtkAppChooser`
interfaces and their implementations as dialogs, buttons and widgets
are phased out. The are being replaced by a new family of async APIs
that will be more convenient to use from language bindings, in particular
for languages that have concepts like promises. The new APIs are
[class@Gtk.ColorDialog], [class@Gtk.FontDialog] and [class@Gtk.FileDialog],
There are also equivalents for some of the 'button' widgets:
There are also equivalents for some of the “button” widgets:
[class@Gtk.ColorDialogButton], [class@Gtk.FontDialogButton].
## GtkMessageDialog is going away
Like the Chooser interfaces, GtkMessageDialog has been replaced by
Like the Chooser interfaces, `GtkMessageDialog` has been replaced by
a new async API that will be more convenient, in particular for
language binding. The new API is [class@Gtk.AlertDialog].
## GtkDialog is going away
After gtk_dialog_run() was removed, the usefulness of GtkDialog
is much reduced, and it has awkward, archaice APIs. Therefore,
After `gtk_dialog_run()` was removed, the usefulness of `GtkDialog`
is much reduced, and it has awkward, archaic APIs. Therefore,
it is dropped. The recommended replacement is to just create
your own window and add buttons as required, either in the header
or elsewhere.
## GtkInfoBar is going away
GtkInfoBar had a dialog API, and with dialogs going away, it was time to
`GtkInfoBar` had a dialog API, and with dialogs going away, it was time to
retire it. If you need such a widget, it is relatively trivial to create one
using a [class@Gtk.Revealer] with labels and buttons.
@ -205,11 +205,11 @@ Other libraries, such as libadwaita, may provide replacements as well.
## gtk_show_uri is being replaced
Instead of gtk_show_uri(), you should use GtkUriLauncher or GtkFileLauncher.
Instead of `gtk_show_uri()`, you should use [class@Gtk.UriLauncher]or [class@Gtk.FileLauncher].
## GtkStatusbar is going away
This is an oldfashioned widget that does not do all that much anymore, since
This is an old fashioned widget that does not do all that much any more, since
it no longer has a resize handle for the window.
## GtkLockButton and GtkVolumeButton are going away
@ -217,22 +217,22 @@ it no longer has a resize handle for the window.
These are very specialized widgets that should better live with the application
where they are used.
## Widget size api changes
## Widget size API changes
The functions gtk_widget_get_allocated_width() and gtk_widget_get_allocated_height()
The functions `gtk_widget_get_allocated_width()` and `gtk_widget_get_allocated_height()`
are going away. In most cases, [method@Gtk.Widget.get_width] and [method@Gtk.Widget.get_height]
are suitable replacements. Note that the semantics are slightly different though:
the old functions return the size of the CSS border area, while the new functions return
the size of the widgets content area. In places where this difference matters, you can
use `gtk_widget_compute_bounds (widget, widget, &bounds)` instead.
The function gtk_widget_get_allocation() is also going away. It does not have a direct
The function `gtk_widget_get_allocation()` is also going away. It does not have a direct
replacement, but the previously mentioned alternatives can be used for it too.
The function gtk_widget_get_allocated_baseline() has been renamed to [method@Gtk.Widget.get_baseline].
The function `gtk_widget_get_allocated_baseline()` has been renamed to [method@Gtk.Widget.get_baseline].
## Stop using GdkPixbuf
GTK is moving away from GdkPixbuf as the primary API for transporting image data, in favor
of GdkTexture. APIs that are accepting or returning GdkPixbufs are being replaced by equivalent
APIs using GdkTexture or GdkPaintable objects.
GTK is moving away from `GdkPixbuf` as the primary API for transporting image data, in favor
of [class@Gdk.Texture]. APIs that are accepting or returning `GdkPixbuf`s are being replaced by equivalent
APIs using `GdkTexture` or [iface@Gdk.Paintable] objects.