Document child-notify and drag-data-received signals. Owen, we need to

2003-06-12  Matthias Clasen  <maclas@gmx.de>

	* gtk/gtkwidget.c: Document child-notify and drag-data-received
	signals. Owen, we need to figure out where the best place for
	these comments in the source is. I currently put them in front of
	the signals enum.

1 files changed, 71 insertions, 0 deletions

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 6eb4ab6b8..c3e132395 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -55,6 +55,77 @@
 #define WIDGET_CLASS(w)	 GTK_WIDGET_GET_CLASS (w)
 #define	INIT_PATH_SIZE	(512)
 
+/**
+ * GtkWidget::child-notify:
+ * @widget: the object which received the signal.
+ * @pspec: the #GParamSpec of the changed child property.
+ * @user_data: user data set when the signal handler was connected.
+ *
+ * The ::child-notify signal is emitted for each child property that has 
+ * changed on an object. The signal's detail holds the property name. 
+ */
+
+/**
+ * GtkWidget::drag-data-received:
+ * @widget: the object which received the signal.
+ * @drag_context: the drag context
+ * @x: where the drop happened
+ * @y: where the drop happened
+ * @data: the received data
+ * @info: the info that has been registered with the target in the 
+ *        #GtkTargetList.
+ * @time: the timestamp at which the data was received
+ * @user_data: user data set when the signal handler was connected.
+ *
+ * The ::drag-data-received signal is emitted on the drop site when the drop 
+ * happens and the data has been received. A handler for this signal is 
+ * expected to process the received data and then call gtk_drag_finish(), 
+ * setting the <literal>success</literal> parameter depending on whether the 
+ * data was processed successfully. 
+ * 
+ * The handler may inspect and modify <literal>context-&gt;action</literal> 
+ * before calling gtk_drag_finish(), e.g. to implement %GTK_ACTION_ASK as 
+ * shown in the following example:
+ * <informalexample><programlisting>
+ * void  
+ * drag_data_received (GtkWidget          *widget,
+ *                     GdkDragContext     *context,
+ *                     gint                x,
+ *                     gint                y,
+ *                     GtkSelectionData   *data,
+ *                     guint               info,
+ *                     guint               time)
+ * {
+ *   if ((data->length >= 0) && (data->format == 8))
+ *     {
+ *       if (context->action == GDK_ACTION_ASK) 
+ *         {
+ *           GtkWidget *dialog;
+ *           gint response;
+ *           
+ *           dialog = gtk_message_dialog_new (NULL,
+ *                                            GTK_DIALOG_MODAL | 
+ *                                            GTK_DIALOG_DESTROY_WITH_PARENT,
+ *                                            GTK_MESSAGE_INFO,
+ *                                            GTK_BUTTONS_YES_NO,
+ *                                            "Move the data ?\n");
+ *           response = gtk_dialog_run (GTK_DIALOG (dialog));
+ *           gtk_widget_destroy (dialog);
+ *             
+ *           if (response == GTK_RESPONSE_YES)
+ *             context->action = GDK_ACTION_MOVE;
+ *           else
+ *             context->action = GDK_ACTION_COPY;
+ *          }
+ *          
+ *       gtk_drag_finish (context, TRUE, FALSE, time);
+ *       return;
+ *     }
+ *       
+ *    gtk_drag_finish (context, FALSE, FALSE, time);
+ *  }
+ * </programlisting></informalexample>
+ */
 
 enum {
   SHOW,