diff --git a/docs/reference/gtk/question_index.xml b/docs/reference/gtk/question_index.xml
index b083211ef7..c6da3c8f9a 100644
--- a/docs/reference/gtk/question_index.xml
+++ b/docs/reference/gtk/question_index.xml
@@ -37,8 +37,10 @@ How do I get started with GTK?
The GTK website offers some
tutorials and other
-documentation (most of it about GTK 2.x, but mostly still applicable).
-More documentation ranging from whitepapers to online books can be found at
+documentation (most of it about GTK 2.x, but still somewhat applicable). This
+reference manual also contains a introductory
+Getting Started part.
+More documentation ranging from whitepapers to online books can be found at
the GNOME developer's site.
After studying these materials you should be well prepared to come back to
this reference manual for details.
@@ -70,13 +72,9 @@ How do I port from one GTK version to another?
See .
-You may also find useful information in the documentation for
-specific widgets and functions.
-
-
-
-If you have a question not covered in the manual, feel free to
-ask on the mailing lists and please file a bug report
against the documentation.
@@ -108,6 +106,11 @@ undocumented exception to the rules, please
file a bug report.
+
+The transfer annotations for gobject-introspection that are part of the
+documentation can provide useful hints for memory handling semantics as well.
+
+
@@ -126,24 +129,23 @@ If GtkFoo isn't a toplevel window, then
foo = gtk_foo_new ();
g_object_unref (foo);
-is a memory leak, because no one assumed the initial floating
-reference. If you are using a widget and you aren't immediately
-packing it into a container, then you probably want standard
-reference counting, not floating reference counting.
+is a memory leak, because no one assumed the initial floating reference
+(you will get a warning about this too). If you are using a widget and
+you aren't immediately packing it into a container, then you probably
+want standard reference counting, not floating reference counting.
To get this, you must acquire a reference to the widget and drop the
-floating reference (ref and sink in GTK parlance) after
+floating reference (ref and sink in GObject parlance) after
creating it:
foo = gtk_foo_new ();
g_object_ref_sink (foo);
-When you immediately add a widget to a container, it takes care of
-assuming the initial floating reference and you don't have to worry
-about reference counting at all ... just call gtk_container_remove()
-to get rid of the widget.
+When you immediately add a widget to a container, it takes care of assuming
+the initial floating reference and you don't have to worry about reference
+counting at all ... just remove the widget from the container to get rid of it.
@@ -156,9 +158,13 @@ How do I use GTK with threads?
-This is covered in the GDK threads
-documentation. See also the GThread
-documentation for portable threading primitives.
+GTK requires that all GTK API calls are made from the same thread in which
+gtk_init() was called (the main thread).
+
+If you want to take advantage of multi-threading in a GTK application,
+it is usually best to send long-running tasks to worker threads, and feed
+the results back to the main thread using g_idle_add() or GAsyncQueue. GIO
+offers useful tools for such an approach such as GTask.
@@ -178,9 +184,9 @@ or Linux system with gettext installed, type info gettext
to read the documentation.
-The short checklist on how to use gettext is: call bindtextdomain() so
+The short checklist on how to use gettext is: call bindtextdomain() so
gettext can find the files containing your translations, call textdomain()
-to set the default translation domain, call bind_textdomain_codeset() to
+to set the default translation domain, call bind_textdomain_codeset() to
request that all translated strings are returned in UTF-8, then call
gettext() to look up each string to be translated in the default domain.
@@ -352,7 +358,7 @@ g_free (text);
If you are using gettext() to localize your application, you need to
-call bind_textdomain_codeset() to ensure that translated strings are
+call bind_textdomain_codeset() to ensure that translated strings are
returned in UTF-8 encoding.
@@ -425,19 +431,9 @@ How do I load an image or animation from a file?
To load an image file straight into a display widget, use
-gtk_image_new_from_file() If the file load fails,
-gtk_image_new_from_file() will display no image graphic — to detect
-a failed load yourself, use gdk_pixbuf_new_from_file() directly, then
-gtk_image_new_from_pixbuf()..
-To load an image for another purpose, use gdk_pixbuf_new_from_file(). To
-load an animation, use gdk_pixbuf_animation_new_from_file().
-gdk_pixbuf_animation_new_from_file() can also load non-animated images, so
-use it in combination with gdk_pixbuf_animation_is_static_image() to load a
-file of unknown type.
-
-
-To load an image or animation file asynchronously (without blocking), use
-#GdkPixbufLoader.
+gtk_image_new_from_file(). To load an image for another purpose, use
+gdk_texture_new_from_file(). To load a video from a file, use
+gtk_media_file_new_for_file().
@@ -450,7 +446,8 @@ How do I draw text ?
-To draw a piece of text, use a Pango layout and pango_cairo_show_layout().
+To draw a piece of text onto a cairo surface, use a Pango layout and
+pango_cairo_show_layout().
layout = gtk_widget_create_pango_layout (widget, text);
@@ -468,6 +465,11 @@ See also the
Cairo Rendering
section of Pango manual.
+
+
+To draw a piece of text in a widget snapshot() implementation, use
+gtk_snapshot_append_layout().
+
@@ -513,10 +515,10 @@ macro ?
-The GTK_TYPE_BLAH macros are defined as calls to
-gtk_blah_get_type(), and the _get_type()
-functions are declared as %G_GNUC_CONST which allows the compiler to optimize
-the call away if it appears that the value is not being used.
+The %GTK_TYPE_BLAH macros are defined as calls to gtk_blah_get_type(), and
+the _get_type() functions are declared as %G_GNUC_CONST which allows
+the compiler to optimize the call away if it appears that the value is not
+being used.
@@ -606,6 +608,18 @@ Both can display images in just about any format GTK understands.
You can also use #GtkDrawingArea if you need to do something more complex,
such as draw text or graphics over the top of the image.
+
+Both GtkImage and GtkPicture can display animations and videos as well.
+To show an webm file, load it with the GtkMediaFile API and then use
+it as a paintable:
+
+
+mediafile = gtk_media_file_new_for_filename ("example.webm");
+picture = gtk_picture_new_for_paintable (GDK_PAINTABLE (mediafile));
+
+
+
+
@@ -618,9 +632,7 @@ would use a combo box?
With GTK, a #GtkComboBox is the recommended widget to use for this use case.
-This widget looks like either a combo box or the current option menu, depending
-on the current theme. If you need an editable text entry, use the
-#GtkComboBox:has-entry property.
+If you need an editable text entry, use the #GtkComboBox:has-entry property.
@@ -638,7 +650,8 @@ How do I change the color of a widget?
The background color of a widget is determined by the CSS style that applies
to it. To change that, you can set style classes on the widget, and provide
custom CSS to change the appearance. Such CSS can be loaded with
-gtk_css_provider_load_from_file() and its variants. See gtk_style_context_add_provider().
+gtk_css_provider_load_from_file() and its variants.
+See gtk_style_context_add_provider().
@@ -912,8 +925,8 @@ How do I use cairo to draw in GTK applications ?
-Use gtk_snapshot_append_cairo() in your #GtkWidgetClass.snapshot() vfunc to optain
-a cairo context and draw with that.
+Use gtk_snapshot_append_cairo() in your #GtkWidgetClass.snapshot() vfunc
+to obtain a cairo context and draw with that.