AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Merge branch 'mcatanzaro/gtkbuilder-docs' into 'master'

Browse Source 
Improve GtkBuilder documentation

See merge request GNOME/gtk!3055
This commit is contained in:
Matthias Clasen 2021-01-07 18:00:19 +00:00
commit 4e7ce9edcf
2 changed files with 28 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
docs/reference/gtk/migrating-3to4.md
View File

@ -523,6 +523,25 @@ option. You should always review the resulting changes.
The <requires> tag now supports for the 'lib' attribute the
'gtk' value only, instead of the 'gtk+' one previously.
## Adapt to GtkBuilder API changes
gtk_builder_connect_signals() no longer exists. Instead, signals are
always connected automatically. If you need to add user data to your
signals, gtk_builder_set_current_object() must be called. An important
caveat is that you have to do this before loading any XML. This means if
you need to use gtk_builder_set_current_object(), you can no longer use
gtk_builder_new_from_file(), gtk_builder_new_from_resource(), or
gtk_builder_new_from_string(). Instead, you must use vanilla gtk_builder_new(),
then call gtk_builder_set_current_object(), then load the XML using
gtk_builder_add_from_file(), gtk_builder_add_from_resource(), or
gtk_builder_add_from_string(). You must check the return value for
failure and manually abort with g_error() if something went wrong.
You only have to worry about this if you were previously using
gtk_builder_connect_signals(). If you are using templates, then
gtk_widget_init_template() will call gtk_builder_set_current_object()
for you, so templates work like before.
### Adapt to event controller API changes
A few changes to the event controller and #GtkGesture APIs

15
gtk/gtkbuilder.c
View File

@ -1153,9 +1153,6 @@ gtk_builder_create_bindings (GtkBuilder *builder,
* or gtk_builder_add_from_string() in order to merge multiple UI
* descriptions into a single builder.
*
* Most users will probably want to use gtk_builder_new_from_file(),
* gtk_builder_new_from_resource() or gtk_builder_new_from_string().
*
* Returns: a new (empty) #GtkBuilder object
**/
GtkBuilder *
@ -1173,7 +1170,9 @@ gtk_builder_new (void)
* Parses a file containing a [GtkBuilder UI definition][BUILDER-UI]
* and merges it with the current contents of @builder.
*
* Most users will probably want to use gtk_builder_new_from_file().
* This function is useful if you need to call gtk_builder_set_current_object()
* to add user data to callbacks before loading GtkBuilder UI.
* Otherwise, you probably want gtk_builder_new_from_file() instead.
*
* If an error occurs, 0 will be returned and @error will be assigned a
* #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_FILE_ERROR
@ -1367,7 +1366,9 @@ gtk_builder_extend_with_template (GtkBuilder *builder,
* Parses a resource file containing a [GtkBuilder UI definition][BUILDER-UI]
* and merges it with the current contents of @builder.
*
* Most users will probably want to use gtk_builder_new_from_resource().
* This function is useful if you need to call gtk_builder_set_current_object()
* to add user data to callbacks before loading GtkBuilder UI.
* Otherwise, you probably want gtk_builder_new_from_resource() instead.
*
* If an error occurs, 0 will be returned and @error will be assigned a
* #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_RESOURCE_ERROR
@ -1517,7 +1518,9 @@ gtk_builder_add_objects_from_resource (GtkBuilder *builder,
* Parses a string containing a [GtkBuilder UI definition][BUILDER-UI]
* and merges it with the current contents of @builder.
*
* Most users will probably want to use gtk_builder_new_from_string().
* This function is useful if you need to call gtk_builder_set_current_object()
* to add user data to callbacks before loading GtkBuilder UI.
* Otherwise, you probably want gtk_builder_new_from_string() instead.
*
* Upon errors %FALSE will be returned and @error will be assigned a
* #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or