[gtkmm] Update the generated GTK+ documentation.

[Murray Cumming <murrayc src gnome org>]

commit 5a3e6c0e6f4dfad2d3cb406c7402e22bc94802de
Author: Murray Cumming <murrayc murrayc com>
Date:   Wed Apr 3 18:31:45 2013 +0200

    Update the generated GTK+ documentation.
    
        * gtk/src/gtk_docs.xml: Regenerate.

 ChangeLog            |    6 +
 gtk/src/gtk_docs.xml |  294 +++++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 250 insertions(+), 50 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 789f350..7970c46 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2013-04-03  Murray Cumming  <murrayc murrayc com>
+
+       Update the generated GTK+ documentation.
+       
+       * gtk/src/gtk_docs.xml: Regenerate.
+
 2013-04-01  Murray Cumming  <murrayc murrayc com>
 
        Gtk::IconInfo: Add async methods.
diff --git a/gtk/src/gtk_docs.xml b/gtk/src/gtk_docs.xml
index 811a322..69437be 100644
--- a/gtk/src/gtk_docs.xml
+++ b/gtk/src/gtk_docs.xml
@@ -710,7 +710,7 @@ Describes how the border of a UI element should be rendered.
 </parameter_description>
 </parameter>
 <parameter name="GTK_BORDER_STYLE_DOUBLE">
-<parameter_description> Two parrallel lines with some space between them
+<parameter_description> Two parallel lines with some space between them
 </parameter_description>
 </parameter>
 <parameter name="GTK_BORDER_STYLE_GROOVE">
@@ -2348,11 +2348,18 @@ Ctrl-v and Shift-Insert.
 
 <signal name="GtkEntry::populate-popup">
 <description>
-The ::populate-popup signal gets emitted before showing the 
-context menu of the entry. 
+The ::populate-popup signal gets emitted before showing the
+context menu of the entry.
 
 If you need to add items to the context menu, connect
-to this signal and append your menuitems to the @menu.
+to this signal and append your items to the @widget, which
+will be a #GtkMenu in this case.
+
+If #GtkEntry::populate-all is %TRUE, this signal will
+also be emitted to populate touch popups. In this case,
+ widget will be a different container, e.g. a #GtkToolbar.
+The signal handler should not make assumptions about the
+type of @widget.
 
 </description>
 <parameters>
@@ -2360,8 +2367,8 @@ to this signal and append your menuitems to the @menu.
 <parameter_description> The entry on which the signal is emitted
 </parameter_description>
 </parameter>
-<parameter name="menu">
-<parameter_description> the menu that is being populated
+<parameter name="popup">
+<parameter_description> the container that is being populated
 </parameter_description>
 </parameter>
 </parameters>
@@ -2962,9 +2969,9 @@ Since: 2.4
 <return></return>
 </signal>
 
-<signal name="GtkFontChooserWidget::font-activated">
+<signal name="GtkFontChooser::font-activated">
 <description>
-Emitted when a font is activated from the widget's list.
+Emitted when a font is activated.
 This usually happens when the user double clicks an item,
 or an item is selected and the user presses one of the keys
 Space, Shift+Space, Return or Enter.
@@ -4220,7 +4227,7 @@ The type of message being displayed in the dialog.
 </parameter_description>
 </parameter>
 <parameter name="GTK_MESSAGE_WARNING">
-<parameter_description> Nonfatal warning message
+<parameter_description> Non-fatal warning message
 </parameter_description>
 </parameter>
 <parameter name="GTK_MESSAGE_QUESTION">
@@ -4519,7 +4526,7 @@ Return: %TRUE if the @allocation has been filled
 
 <enum name="GtkPackDirection">
 <description>
-Determines how widgets should be packed insided menubars
+Determines how widgets should be packed inside menubars
 and menuitems contained in menubars.
 
 </description>
@@ -6238,10 +6245,6 @@ key to select between the focus and the child pointed to.
 Some widgets may also allow Click-drag to select a range of elements.
 </parameter_description>
 </parameter>
-<parameter name="GTK_SELECTION_EXTENDED">
-<parameter_description> Deprecated, behaves identical to %GTK_SELECTION_MULTIPLE.
-</parameter_description>
-</parameter>
 </parameters>
 </enum>
 
@@ -6351,7 +6354,7 @@ width-for-height geometry management.
 </parameter_description>
 </parameter>
 <parameter name="GTK_SIZE_REQUEST_CONSTANT_SIZE">
-<parameter_description> Dont trade height-for-width or width-for-height
+<parameter_description> Don't trade height-for-width or width-for-height
 </parameter_description>
 </parameter>
 </parameters>
@@ -7643,11 +7646,20 @@ Ctrl-v and Shift-Insert.
 
 <signal name="GtkTextView::populate-popup">
 <description>
-The ::populate-popup signal gets emitted before showing the 
+The ::populate-popup signal gets emitted before showing the
 context menu of the text view.
 
 If you need to add items to the context menu, connect
-to this signal and append your menuitems to the @menu.
+to this signal and append your items to the @popup, which
+will be a #GtkMenu in this case.
+
+If #GtkEntry::populate-toolbar is %TRUE, this signal will
+also be emitted to populate touch popups. In this case,
+ popup will be a different container, e.g. a #GtkToolbar.
+
+The signal handler should not make assumptions about the
+type of @widget, but check whether @popup is a #GtkMenu
+or #GtkToolbar or another kind of container.
 
 </description>
 <parameters>
@@ -7655,8 +7667,8 @@ to this signal and append your menuitems to the @menu.
 <parameter_description> The text view on which the signal is emitted
 </parameter_description>
 </parameter>
-<parameter name="menu">
-<parameter_description> the menu that is being populated
+<parameter name="popup">
+<parameter_description> the container that is being populated
 </parameter_description>
 </parameter>
 </parameters>
@@ -11944,7 +11956,7 @@ of times.
 
 Note that locking of individual accelerator paths is independent from 
 locking the #GtkAccelGroup containing them. For runtime accelerator
-changes to be possible both the accelerator path and its #GtkAccelGroup
+changes to be possible, both the accelerator path and its #GtkAccelGroup
 have to be unlocked. 
 
 Since: 2.4
@@ -17806,12 +17818,6 @@ Since: 2.12
 Add @object to the @builder object pool so it can be referenced just like any
 other object built by builder.
 
-To make this function even more useful a new special entry point element
-&lt;external-object&gt; is defined. It is similar to &lt;object&gt; but has 
-to reference an external object exposed with this function.
-This way you can change properties and even add children to an
-external object using builder, not just reference it.
-
 Since: 3.8
 
 </description>
@@ -19799,12 +19805,12 @@ Since: 3.0
 <description>
 Fetches the #GtkCellArea this @context was created by.
 
-This is generally unneeded by layouting widgets; however
+This is generally unneeded by layouting widgets; however,
 it is important for the context implementation itself to
 fetch information about the area it is being used for.
 
 For instance at #GtkCellAreaContextClass.allocate() time
-its important to know details about any cell spacing
+it's important to know details about any cell spacing
 that the #GtkCellArea is configured with in order to
 compute a proper allocation.
 
@@ -20452,8 +20458,8 @@ The returned list is internal and should not be freed.
 <description>
 Retrieves a cell area's initial minimum and natural height.
 
- area will store some geometrical information in @context along the way,
-when requesting sizes over an arbitrary number of rows, its not important
+ area will store some geometrical information in @context along the way;
+when requesting sizes over an arbitrary number of rows, it's not important
 to check the @minimum_height and @natural_height of this call but rather to
 consult gtk_cell_area_context_get_preferred_height() after a series of
 requests.
@@ -20539,8 +20545,8 @@ Since: 3.0
 <description>
 Retrieves a cell area's initial minimum and natural width.
 
- area will store some geometrical information in @context along the way,
-when requesting sizes over an arbitrary number of rows, its not important
+ area will store some geometrical information in @context along the way;
+when requesting sizes over an arbitrary number of rows, it's not important
 to check the @minimum_width and @natural_width of this call but rather to
 consult gtk_cell_area_context_get_preferred_width() after a series of
 requests.
@@ -22369,8 +22375,8 @@ Since: 2.6
 
 <function name="gtk_cell_view_new_with_pixbuf">
 <description>
-Creates a new #GtkCellView widget, adds a #GtkCellRendererPixbuf 
-to it, and makes its show @pixbuf. 
+Creates a new #GtkCellView widget, adds a #GtkCellRendererPixbuf
+to it, and makes it show @pixbuf.
 
 Since: 2.6
 
@@ -22389,7 +22395,7 @@ Since: 2.6
 <function name="gtk_cell_view_new_with_text">
 <description>
 Creates a new #GtkCellView widget, adds a #GtkCellRendererText 
-to it, and makes its show @text.
+to it, and makes it show @text.
 
 Since: 2.6
 
@@ -27432,6 +27438,34 @@ to @sizes.
 
 <function name="gtk_drag_begin">
 <description>
+Initiates a drag on the source side. The function
+only needs to be used when the application is
+starting drags itself, and is not needed when
+gtk_drag_source_set() is used.
+
+The @event is used to retrieve the timestamp that will be used internally to
+grab the pointer.  If @event is #NULL, then GDK_CURRENT_TIME will be used.
+However, you should try to pass a real event in all cases, since that can be
+used by GTK+ to get information about the start position of the drag, for
+example if the @event is a %GDK_MOTION_NOTIFY.
+
+Generally there are three cases when you want to start a drag by hand by
+calling this function:
+
+1. During a #GtkWidget::button-press-event handler, if you want to start a drag
+immediately when the user presses the mouse button.  Pass the @event
+that you have in your #GtkWidget::button-press-event handler.
+
+2. During a #GtkWidget::motion-notify-event handler, if you want to start a drag
+when the mouse moves past a certain threshold distance after a button-press.
+Pass the @event that you have in your #GtkWidget::motion-notify-event handler.
+
+3. During a timeout handler, if you want to start a drag after the mouse
+button is held down for some time.  Try to save the last event that you got
+from the mouse, using gdk_event_copy(), and pass it to this function
+(remember to free the event with gdk_event_free() when you are done).
+If you can really not pass a real event, pass #NULL instead.
+
 
 </description>
 <parameters>
@@ -27457,11 +27491,16 @@ source can provide the data.
 </parameter_description>
 </parameter>
 </parameters>
-<return></return>
+<return> the context for this drag.
+</return>
 </function>
 
 <function name="gtk_drag_check_threshold">
 <description>
+Checks to see if a mouse drag starting at (@start_x, @start_y) and ending
+at (@current_x, @current_y) has passed the GTK+ drag threshold, and thus
+should trigger the beginning of a drag-and-drop operation.
+
 
 </description>
 <parameters>
@@ -27486,11 +27525,19 @@ source can provide the data.
 </parameter_description>
 </parameter>
 </parameters>
-<return></return>
+<return> %TRUE if the drag threshold has been passed.
+</return>
 </function>
 
 <function name="gtk_drag_dest_add_image_targets">
 <description>
+Add the image targets supported by #GtkSelection to
+the target list of the drag destination. The targets
+are added with @info = 0. If you need another value, 
+use gtk_target_list_add_image_targets() and
+gtk_drag_dest_set_target_list().
+
+Since: 2.6
 
 </description>
 <parameters>
@@ -27504,6 +27551,13 @@ source can provide the data.
 
 <function name="gtk_drag_dest_add_text_targets">
 <description>
+Add the text targets supported by #GtkSelection to
+the target list of the drag destination. The targets
+are added with @info = 0. If you need another value, 
+use gtk_target_list_add_text_targets() and
+gtk_drag_dest_set_target_list().
+
+Since: 2.6
 
 </description>
 <parameters>
@@ -27517,6 +27571,13 @@ source can provide the data.
 
 <function name="gtk_drag_dest_add_uri_targets">
 <description>
+Add the URI targets supported by #GtkSelection to
+the target list of the drag destination. The targets
+are added with @info = 0. If you need another value, 
+use gtk_target_list_add_uri_targets() and
+gtk_drag_dest_set_target_list().
+
+Since: 2.6
 
 </description>
 <parameters>
@@ -27530,6 +27591,14 @@ source can provide the data.
 
 <function name="gtk_drag_dest_find_target">
 <description>
+Looks for a match between the supported targets of @context and the
+ dest_target_list, returning the first matching target, otherwise
+returning %GDK_NONE. @dest_target_list should usually be the return
+value from gtk_drag_dest_get_target_list(), but some widgets may
+have different valid targets for different parts of the widget; in
+that case, they will have to implement a drag_motion handler that
+passes the correct target list to this function.
+
 
 </description>
 <parameters>
@@ -27547,11 +27616,16 @@ gtk_drag_dest_get_target_list (@widget).
 </parameter_description>
 </parameter>
 </parameters>
-<return></return>
+<return> first target that the source offers
+and the dest can accept, or %GDK_NONE
+</return>
 </function>
 
 <function name="gtk_drag_dest_get_target_list">
 <description>
+Returns the list of targets this widget can accept from
+drag-and-drop.
+
 
 </description>
 <parameters>
@@ -27560,11 +27634,16 @@ gtk_drag_dest_get_target_list (@widget).
 </parameter_description>
 </parameter>
 </parameters>
-<return></return>
+<return> the #GtkTargetList, or %NULL if none
+</return>
 </function>
 
 <function name="gtk_drag_dest_get_track_motion">
 <description>
+Returns whether the widget has been configured to always
+emit #GtkWidget::drag-motion signals.
+
+Since: 2.10
 
 </description>
 <parameters>
@@ -27573,11 +27652,53 @@ gtk_drag_dest_get_target_list (@widget).
 </parameter_description>
 </parameter>
 </parameters>
-<return></return>
+<return> %TRUE if the widget always emits
+#GtkWidget::drag-motion events
+
+</return>
 </function>
 
 <function name="gtk_drag_dest_set">
 <description>
+Sets a widget as a potential drop destination, and adds default behaviors.
+
+The default behaviors listed in @flags have an effect similar
+to installing default handlers for the widget's drag-and-drop signals
+(#GtkWidget::drag-motion, #GtkWidget::drag-drop, ...). They all exist
+for convenience. When passing #GTK_DEST_DEFAULT_ALL for instance it is
+sufficient to connect to the widget's #GtkWidget::drag-data-received
+signal to get primitive, but consistent drag-and-drop support.
+
+Things become more complicated when you try to preview the dragged data,
+as described in the documentation for #GtkWidget::drag-motion. The default
+behaviors described by @flags make some assumptions, that can conflict
+with your own signal handlers. For instance #GTK_DEST_DEFAULT_DROP causes
+invokations of gdk_drag_status() in the context of #GtkWidget::drag-motion,
+and invokations of gtk_drag_finish() in #GtkWidget::drag-data-received.
+Especially the later is dramatic, when your own #GtkWidget::drag-motion
+handler calls gtk_drag_get_data() to inspect the dragged data.
+
+There's no way to set a default action here, you can use the
+#GtkWidget::drag-motion callback for that. Here's an example which selects
+the action to use depending on whether the control key is pressed or not:
+|[
+static void
+drag_motion (GtkWidget *widget,
+GdkDragContext *context,
+gint x,
+gint y,
+guint time)
+{
+GdkModifierType mask;
+
+gdk_window_get_pointer (gtk_widget_get_window (widget),
+NULL, NULL, &amp;mask);
+if (mask &amp; GDK_CONTROL_MASK)
+gdk_drag_status (context, GDK_ACTION_COPY, time);
+else
+gdk_drag_status (context, GDK_ACTION_MOVE, time);
+}
+]|
 
 </description>
 <parameters>
@@ -27610,6 +27731,7 @@ and gtk_drag_dest_find_target().
 
 <function name="gtk_drag_dest_set_proxy">
 <description>
+Sets this widget as a proxy for drops to another window.
 
 </description>
 <parameters>
@@ -27638,6 +27760,9 @@ subwindow.
 
 <function name="gtk_drag_dest_set_target_list">
 <description>
+Sets the target types that this widget can accept from drag-and-drop.
+The widget must first be made into a drag destination with
+gtk_drag_dest_set().
 
 </description>
 <parameters>
@@ -27655,6 +27780,14 @@ subwindow.
 
 <function name="gtk_drag_dest_set_track_motion">
 <description>
+Tells the widget to emit #GtkWidget::drag-motion and
+#GtkWidget::drag-leave events regardless of the targets and the
+%GTK_DEST_DEFAULT_MOTION flag.
+
+This may be used when a widget wants to do generic
+actions regardless of the targets that the source offers.
+
+Since: 2.10
 
 </description>
 <parameters>
@@ -27672,6 +27805,9 @@ subwindow.
 
 <function name="gtk_drag_dest_unset">
 <description>
+Clears information about a drop destination set with
+gtk_drag_dest_set(). The widget will no longer receive
+notification of drags.
 
 </description>
 <parameters>
@@ -27685,6 +27821,8 @@ subwindow.
 
 <function name="gtk_drag_finish">
 <description>
+Informs the drag source that the drop is finished, and
+that the data of the drag will no longer be required.
 
 </description>
 <parameters>
@@ -27711,6 +27849,14 @@ original data. (This should be %TRUE for a move)
 
 <function name="gtk_drag_get_data">
 <description>
+Gets the data associated with a drag. When the data
+is received or the retrieval fails, GTK+ will emit a
+#GtkWidget::drag-data-received signal. Failure of the retrieval
+is indicated by the length field of the @selection_data
+signal parameter being negative. However, when gtk_drag_get_data()
+is called implicitely because the %GTK_DEST_DEFAULT_DROP was set,
+then the widget will not receive notification of failed
+drops.
 
 </description>
 <parameters>
@@ -27739,6 +27885,8 @@ or #GtkWidget::drag-drop&quot; signal.
 
 <function name="gtk_drag_get_source_widget">
 <description>
+Determines the source widget for a drag.
+
 
 </description>
 <parameters>
@@ -27747,11 +27895,18 @@ or #GtkWidget::drag-drop&quot; signal.
 </parameter_description>
 </parameter>
 </parameters>
-<return></return>
+<return> if the drag is occurring
+within a single application, a pointer to the source widget.
+Otherwise, %NULL.
+</return>
 </function>
 
 <function name="gtk_drag_highlight">
 <description>
+Draws a highlight around a widget. This will attach
+handlers to #GtkWidget::draw, so the highlight
+will continue to be displayed until gtk_drag_unhighlight()
+is called.
 
 </description>
 <parameters>
@@ -27955,6 +28110,13 @@ signal and destroy it yourself.
 
 <function name="gtk_drag_source_add_image_targets">
 <description>
+Add the writable image targets supported by #GtkSelection to
+the target list of the drag source. The targets
+are added with @info = 0. If you need another value, 
+use gtk_target_list_add_image_targets() and
+gtk_drag_source_set_target_list().
+
+Since: 2.6
 
 </description>
 <parameters>
@@ -27988,6 +28150,13 @@ Since: 2.6
 
 <function name="gtk_drag_source_add_uri_targets">
 <description>
+Add the URI targets supported by #GtkSelection to
+the target list of the drag source.  The targets
+are added with @info = 0. If you need another value, 
+use gtk_target_list_add_uri_targets() and
+gtk_drag_source_set_target_list().
+
+Since: 2.6
 
 </description>
 <parameters>
@@ -28001,6 +28170,10 @@ Since: 2.6
 
 <function name="gtk_drag_source_get_target_list">
 <description>
+Gets the list of targets this widget can provide for
+drag-and-drop.
+
+Since: 2.4
 
 </description>
 <parameters>
@@ -28009,11 +28182,15 @@ Since: 2.6
 </parameter_description>
 </parameter>
 </parameters>
-<return></return>
+<return> the #GtkTargetList, or %NULL if none
+
+</return>
 </function>
 
 <function name="gtk_drag_source_set">
 <description>
+Sets up a widget so that GTK+ will start a drag operation when the user
+clicks and drags on the widget. The widget must have a window.
 
 </description>
 <parameters>
@@ -28086,6 +28263,9 @@ Since: 2.8
 
 <function name="gtk_drag_source_set_icon_pixbuf">
 <description>
+Sets the icon that will be used for drags from a particular widget
+from a #GdkPixbuf. GTK+ retains a reference for @pixbuf and will 
+release it when it is no longer needed.
 
 </description>
 <parameters>
@@ -28122,6 +28302,11 @@ to a stock icon.
 
 <function name="gtk_drag_source_set_target_list">
 <description>
+Changes the target types that this widget offers for drag-and-drop.
+The widget must first be made into a drag source with
+gtk_drag_source_set().
+
+Since: 2.4
 
 </description>
 <parameters>
@@ -28139,6 +28324,7 @@ to a stock icon.
 
 <function name="gtk_drag_source_unset">
 <description>
+Undoes the effects of gtk_drag_source_set().
 
 </description>
 <parameters>
@@ -28152,6 +28338,8 @@ to a stock icon.
 
 <function name="gtk_drag_unhighlight">
 <description>
+Removes a highlight set by gtk_drag_highlight() from
+a widget.
 
 </description>
 <parameters>
@@ -32365,7 +32553,9 @@ Since: 2.4
 </parameter>
 </parameters>
 <return> The currently selected URI, or %NULL
-if no file is selected. Free with g_free()
+if no file is selected. If gtk_file_chooser_set_local_only() is set to %TRUE
+(the default) a local URI will be returned for any FUSE locations.
+Free with g_free()
 
 </return>
 </function>
@@ -33003,6 +33193,10 @@ needs to worry about the filename functions in
 rather than the URI functions like
 gtk_file_chooser_get_uri(),
 
+On some systems non-native files may still be
+available using the native filesystem via a userspace
+filesystem (FUSE).
+
 Since: 2.4
 
 </description>
@@ -62414,7 +62608,7 @@ providing an invalid value.
 <function name="gtk_spin_button_set_update_policy">
 <description>
 Sets the update behavior of a spin button.
-This determines wether the spin button is always updated
+This determines whether the spin button is always updated
 or only when a valid value is set.
 
 </description>
@@ -67314,7 +67508,7 @@ Since: 2.14
 </parameter_description>
 </parameter>
 </parameters>
-<return> wether all actions neccessary for the button click simulation were carried out successfully.
+<return> whether all actions neccessary for the button click simulation were carried out successfully.
 
 </return>
 </function>
@@ -67387,7 +67581,7 @@ Since: 2.14
 </parameter_description>
 </parameter>
 </parameters>
-<return> wether all actions neccessary for the button click simulation were carried out successfully.
+<return> whether all actions neccessary for the button click simulation were carried out successfully.
 
 </return>
 </function>
@@ -67419,7 +67613,7 @@ Since: 2.14
 </parameter_description>
 </parameter>
 </parameters>
-<return> wether all actions neccessary for the key event simulation were carried out successfully.
+<return> whether all actions neccessary for the key event simulation were carried out successfully.
 
 </return>
 </function>
@@ -86981,8 +87175,8 @@ Since: 2.20
 
 <function name="gtk_widget_get_receives_default">
 <description>
-Determines whether @widget is alyways treated as default widget
-withing its toplevel when it has the focus, even if another widget
+Determines whether @widget is always treated as the default widget
+within its toplevel when it has the focus, even if another widget
 is the default.
 
 See gtk_widget_set_receives_default().
@@ -86996,7 +87190,7 @@ Since: 2.18
 </parameter_description>
 </parameter>
 </parameters>
-<return> %TRUE if @widget acts as default widget when focussed,
+<return> %TRUE if @widget acts as the default widget when focussed,
 %FALSE otherwise
 
 </return>