If you are paying attention to GTK’s git repository, you may have noticed a change in the last weeks.
We have a directory gtk/deprecations, which is destined to contain source files that implement deprecated APIs and will be dropped in the next major release. For the 4.0 release, we emptied it out, and it has been empty ever since. But recently, it started to accumulate files again.
This is a good opportunity to remind folks how we are using deprecations in GTK. But first, lets take a look at the details.
The details, part 1: cell renderers
In GTK 4, we introduced a new family of list and grid widgets that are based around list models: GtkListView, GtkColumnView, GtkGridView. There is also a new combo box implementation using list models, called GtkDropDown. Taken together, these are meant to provide replacements for everything you can do with cell renderers in GTK 3.
The ultimate goal was to remove cell renderers, since they are a whole separate rendering and layout system that tends to interfere with GTK’s CSS and layout machinery, and makes everything more complicated.
But we did not quite get to the finish line for 4.0, mainly because we still had significant uses of treeviews in GTK itself. First and foremost, the file chooser. Since the filechooser is getting ported to use a GtkColumnView in 4.10, now is the right time to deprecate the cell renderer machinery and all the widgets that use them.
This is a significant amount of code, more than 75.000 lines.
The details, part 2: dialogs
In GTK 4, we dropped gtk_main() and gtk_dialog_run(), since recursive mainloops are best avoided. Again, we did not get to the finish line and could not remove GtkDialog itself, since it is used as the base class for all our complex dialogs.
GTK 4.10 introduces replacement APIs for our ‘Chooser’ dialogs. The new APIs follow the gio async pattern. Here is an example:
GtkFileDialog * gtk_file_dialog_new (void);
void gtk_file_dialog_open (GtkFileDialog *self,
GtkWindow *parent,
GFile *current_file,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
GFile * gtk_file_dialog_open_finish (GtkFileDialog *self,
GAsyncResult *result,
GError **error);
This may look a bit unwieldy in C, but it translates very nicely to languages that have a concept of promises and exceptions:
try {
const file = await dialog.open(parent, ...);
...
} catch (e) {
...
};
To learn more about the new APIs, you can look at their online docs: GtkColorDialog, GtkFontDialog, GtkFileDialog, GtkAlertDialog.
With these replacements in place, we could deprecate the Chooser interfaces, their widget implementations, and their base class GtkDialog.
No need to panic
Deprecations in GTK are an early outlook at changes that will appear in the next major release that is breaking API compatibility. But the eventual GTK 5 release is still far away. We have not even made a plan for it yet.
There is absolutely no need to rush towards ‘deprecation cleanup’. You only need to remove all uses of deprecations when you want to port to GTK 5 – which does not exist yet.
There are still things you can do, though. We are introducing deprecations in 4.10 as a way to give our users time to adapt, and to provide feedback on our ideas. If you want to do so, you can file an issue in gitlab, start a discussion in discourse, or find us on matrix.
In the meantime…
Deprecation warnings can be annoying, but thankfully there are easy ways to turn them off. For the occasional call to a deprecated function, it is best to just wrap it in G_GNUC_BEGIN/END_IGNORE_DEPRECATIONS:
G_GNUC_BEGIN_IGNORE_DEPRECATIONS gtk_dialog_add_button (dialog, "Apply", GTK_RESPONSE_APPLY); G_GNUC_END_IGNORE_DEPRECATIONS
If you are sure that you never ever want to see any deprecation warnings, you can also just pass -Wno-deprecated-declarations to gcc.