Move GtkSelection docs inline

At the same time, move private selection API to gtkselectionprivate.h

6 files changed, 137 insertions, 87 deletions

diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 9a3b0314fa..799db27935 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -122,7 +122,7 @@
 #include "gtkmodules.h"
 #include "gtkrc.h"
 #include "gtkrecentmanager.h"
-#include "gtkselection.h"
+#include "gtkselectionprivate.h"
 #include "gtksettingsprivate.h"
 #include "gtkwidgetprivate.h"
 #include "gtkwindowprivate.h"
diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c
index 06aa14678a..4063bb2d05 100644
--- a/gtk/gtkselection.c
+++ b/gtk/gtkselection.c
@@ -51,6 +51,32 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/**
+ * SECTION:gtkselection
+ * @Title: Selections
+ * @Short_description: Functions for handling inter-process communication
+ *     via selections
+ * @See_also: #GtkWidget - Much of the operation of selections happens via
+ *     signals for #GtkWidget. In particular, if you are using the functions
+ *     in this section, you may need to pay attention to
+ *     #GtkWidget::selection-get, #GtkWidget::selection-received and
+ *     #GtkWidget::selection-clear-event signals
+ *
+ * The selection mechanism provides the basis for different types
+ * of communication between processes. In particular, drag and drop and
+ * #GtkClipboard work via selections. You will very seldom or
+ * never need to use most of the functions in this section directly;
+ * #GtkClipboard provides a nicer interface to the same functionality.
+ *
+ * Some of the datatypes defined this section are used in
+ * the #GtkClipboard and drag-and-drop API's as well. The
+ * #GtkTargetEntry structure and #GtkTargetList objects represent
+ * lists of data types that are supported when sending or
+ * receiving data. The #GtkSelectionData object is used to
+ * store a chunk of data along with the data type and other
+ * associated information.
+ */
+
 #include "config.h"
 
 #include "gtkselection.h"
diff --git a/gtk/gtkselection.h b/gtk/gtkselection.h
index 6b409bb8a0..bb3337da35 100644
--- a/gtk/gtkselection.h
+++ b/gtk/gtkselection.h
@@ -31,19 +31,39 @@
 #ifndef __GTK_SELECTION_H__
 #define __GTK_SELECTION_H__
 
-
 #include <gtk/gtkwidget.h>
 #include <gtk/gtktextiter.h>
 
-
 G_BEGIN_DECLS
 
-typedef struct _GtkTargetList    GtkTargetList;
-typedef struct _GtkTargetEntry   GtkTargetEntry;
+/**
+ * GtkTargetList:
+ *
+ * A #GtkTargetList structure is a reference counted list
+ * of #GtkTargetPair. It is used to represent the same
+ * information as a table of #GtkTargetEntry, but in
+ * an efficient form. This structure should be treated as
+ * opaque.
+ */
+typedef struct _GtkTargetList  GtkTargetList;
+typedef struct _GtkTargetEntry GtkTargetEntry;
 
 #define GTK_TYPE_SELECTION_DATA (gtk_selection_data_get_type ())
 #define GTK_TYPE_TARGET_LIST    (gtk_target_list_get_type ())
 
+/**
+ * GtkTargetEntry:
+ * @target: a string representation of the target type
+ * @flags: #GtkTargetFlags for DND
+ * @info: an application-assigned integer ID which will
+ *     get passed as a parater to e.g the #GtkWiget::selection-get
+ *     signal. It allows the application to identify the target
+ *     type without extensive string compares.
+ *
+ * A #GtkTargetEntry structure represents a single type of
+ * data than can be supplied for by a widget for a selection
+ * or for supplied or received during drag-and-drop.
+ */
 struct _GtkTargetEntry
 {
   gchar *target;
@@ -51,32 +71,15 @@ struct _GtkTargetEntry
   guint  info;
 };
 
-/* These structures not public, and are here only for the convenience of
- * gtkdnd.c
- */
-
-typedef struct _GtkTargetPair GtkTargetPair;
-
-/* This structure is a list of destinations, and associated guint id's */
-struct _GtkTargetList {
-  GList *list;
-  guint ref_count;
-};
-
-struct _GtkTargetPair {
-  GdkAtom   target;
-  guint     flags;
-  guint     info;
-};
-
+GType          gtk_target_list_get_type  (void) G_GNUC_CONST;
 GtkTargetList *gtk_target_list_new       (const GtkTargetEntry *targets,
-					  guint                 ntargets);
+                                          guint                 ntargets);
 GtkTargetList *gtk_target_list_ref       (GtkTargetList  *list);
 void           gtk_target_list_unref     (GtkTargetList  *list);
 void           gtk_target_list_add       (GtkTargetList  *list,
-				  	  GdkAtom         target,
-					  guint           flags,
-					  guint           info);
+                                          GdkAtom         target,
+                                          guint           flags,
+                                          guint           info);
 void           gtk_target_list_add_text_targets      (GtkTargetList  *list,
                                                       guint           info);
 void           gtk_target_list_add_rich_text_targets (GtkTargetList  *list,
@@ -89,43 +92,42 @@ void           gtk_target_list_add_image_targets     (GtkTargetList  *list,
 void           gtk_target_list_add_uri_targets       (GtkTargetList  *list,
                                                       guint           info);
 void           gtk_target_list_add_table (GtkTargetList        *list,
-					  const GtkTargetEntry *targets,
-					  guint                 ntargets);
+                                          const GtkTargetEntry *targets,
+                                          guint                 ntargets);
 void           gtk_target_list_remove    (GtkTargetList  *list,
-					  GdkAtom         target);
+                                          GdkAtom         target);
 gboolean       gtk_target_list_find      (GtkTargetList  *list,
-					  GdkAtom         target,
-					  guint          *info);
+                                          GdkAtom         target,
+                                          guint          *info);
 
 GtkTargetEntry * gtk_target_table_new_from_list (GtkTargetList  *list,
                                                  gint           *n_targets);
 void             gtk_target_table_free          (GtkTargetEntry *targets,
                                                  gint            n_targets);
 
-/* Public interface */
-
 gboolean gtk_selection_owner_set             (GtkWidget  *widget,
-					      GdkAtom     selection,
-					      guint32     time_);
+                                              GdkAtom     selection,
+                                              guint32     time_);
 gboolean gtk_selection_owner_set_for_display (GdkDisplay *display,
-					      GtkWidget  *widget,
-					      GdkAtom     selection,
-					      guint32     time_);
+                                              GtkWidget  *widget,
+                                              GdkAtom     selection,
+                                              guint32     time_);
 
 void     gtk_selection_add_target    (GtkWidget            *widget,
-				      GdkAtom               selection,
-				      GdkAtom               target,
-				      guint                 info);
+                                      GdkAtom               selection,
+                                      GdkAtom               target,
+                                      guint                 info);
 void     gtk_selection_add_targets   (GtkWidget            *widget,
-				      GdkAtom               selection,
-				      const GtkTargetEntry *targets,
-				      guint                 ntargets);
+                                      GdkAtom               selection,
+                                      const GtkTargetEntry *targets,
+                                      guint                 ntargets);
 void     gtk_selection_clear_targets (GtkWidget            *widget,
-				      GdkAtom               selection);
+                                      GdkAtom               selection);
 gboolean gtk_selection_convert       (GtkWidget            *widget,
-				      GdkAtom               selection,
-				      GdkAtom               target,
-				      guint32               time_);
+                                      GdkAtom               selection,
+                                      GdkAtom               target,
+                                      guint32               time_);
+void     gtk_selection_remove_all    (GtkWidget             *widget);
 
 GdkAtom       gtk_selection_data_get_selection (const GtkSelectionData *selection_data);
 GdkAtom       gtk_selection_data_get_target    (const GtkSelectionData *selection_data);
@@ -140,68 +142,52 @@ const guchar *gtk_selection_data_get_data_with_length
 GdkDisplay   *gtk_selection_data_get_display   (const GtkSelectionData *selection_data);
 
 void     gtk_selection_data_set      (GtkSelectionData     *selection_data,
-				      GdkAtom               type,
-				      gint                  format,
-				      const guchar         *data,
-				      gint                  length);
+                                      GdkAtom               type,
+                                      gint                  format,
+                                      const guchar         *data,
+                                      gint                  length);
 gboolean gtk_selection_data_set_text (GtkSelectionData     *selection_data,
-				      const gchar          *str,
-				      gint                  len);
+                                      const gchar          *str,
+                                      gint                  len);
 guchar * gtk_selection_data_get_text (const GtkSelectionData     *selection_data);
 gboolean gtk_selection_data_set_pixbuf   (GtkSelectionData  *selection_data,
-				          GdkPixbuf         *pixbuf);
+                                          GdkPixbuf         *pixbuf);
 GdkPixbuf *gtk_selection_data_get_pixbuf (const GtkSelectionData  *selection_data);
 gboolean gtk_selection_data_set_uris (GtkSelectionData     *selection_data,
-				      gchar               **uris);
+                                      gchar               **uris);
 gchar  **gtk_selection_data_get_uris (const GtkSelectionData     *selection_data);
 
 gboolean gtk_selection_data_get_targets          (const GtkSelectionData  *selection_data,
-						  GdkAtom          **targets,
-						  gint              *n_atoms);
+                                                  GdkAtom          **targets,
+                                                  gint              *n_atoms);
 gboolean gtk_selection_data_targets_include_text (const GtkSelectionData  *selection_data);
 gboolean gtk_selection_data_targets_include_rich_text (const GtkSelectionData *selection_data,
                                                        GtkTextBuffer    *buffer);
 gboolean gtk_selection_data_targets_include_image (const GtkSelectionData  *selection_data,
-						   gboolean           writable);
+                                                   gboolean           writable);
 gboolean gtk_selection_data_targets_include_uri  (const GtkSelectionData  *selection_data);
 gboolean gtk_targets_include_text                (GdkAtom       *targets,
-						  gint           n_targets);
+                                                  gint           n_targets);
 gboolean gtk_targets_include_rich_text           (GdkAtom       *targets,
-						  gint           n_targets,
+                                                  gint           n_targets,
                                                   GtkTextBuffer *buffer);
 gboolean gtk_targets_include_image               (GdkAtom       *targets,
-						  gint           n_targets,
-						  gboolean       writable);
+                                                  gint           n_targets,
+                                                  gboolean       writable);
 gboolean gtk_targets_include_uri                 (GdkAtom       *targets,
-						  gint           n_targets);
+                                                  gint           n_targets);
 
-/* Called when a widget is destroyed */
-
-void gtk_selection_remove_all      (GtkWidget *widget);
-
-/* Event handlers */
-gboolean _gtk_selection_clear		  (GtkWidget 	     *widget,
-					   GdkEventSelection *event);
-gboolean _gtk_selection_request		  (GtkWidget  	     *widget,
-					   GdkEventSelection *event);
-gboolean _gtk_selection_incr_event	  (GdkWindow         *window,
-					   GdkEventProperty  *event);
-gboolean _gtk_selection_notify		  (GtkWidget         *widget,
-					   GdkEventSelection *event);
-gboolean _gtk_selection_property_notify	  (GtkWidget         *widget,
-					   GdkEventProperty  *event);
 
 GType             gtk_selection_data_get_type (void) G_GNUC_CONST;
 GtkSelectionData *gtk_selection_data_copy     (const GtkSelectionData *data);
-void		  gtk_selection_data_free     (GtkSelectionData *data);
+void              gtk_selection_data_free     (GtkSelectionData *data);
 
 GType             gtk_target_entry_get_type    (void) G_GNUC_CONST;
-
-GtkTargetEntry   *gtk_target_entry_new        (const char *target, guint flags, guint info);
+GtkTargetEntry   *gtk_target_entry_new        (const gchar    *target,
+                                               guint           flags,
+                                               guint           info);
 GtkTargetEntry   *gtk_target_entry_copy       (GtkTargetEntry *data);
-void		  gtk_target_entry_free       (GtkTargetEntry *data);
-
-GType             gtk_target_list_get_type    (void) G_GNUC_CONST;
+void              gtk_target_entry_free       (GtkTargetEntry *data);
 
 G_END_DECLS
 
diff --git a/gtk/gtkselectionprivate.h b/gtk/gtkselectionprivate.h
index 831753fd33..0b965f508e 100644
--- a/gtk/gtkselectionprivate.h
+++ b/gtk/gtkselectionprivate.h
@@ -28,6 +28,13 @@
  * sent.
  */
 
+#ifndef __GTK_SELECTIONPRIVATE_H__
+#define __GTK_SELECTIONPRIVATE_H__
+
+#include "gtkselection.h"
+
+G_BEGIN_DECLS
+
 struct _GtkSelectionData
 {
   GdkAtom       selection;
@@ -38,3 +45,33 @@ struct _GtkSelectionData
   gint          length;
   GdkDisplay   *display;
 };
+
+struct _GtkTargetList
+{
+  GList *list;
+  guint ref_count;
+ };
+
+typedef struct _GtkTargetPair GtkTargetPair;
+struct _GtkTargetPair
+{
+  GdkAtom   target;
+  guint     flags;
+  guint     info;
+};
+
+
+gboolean _gtk_selection_clear           (GtkWidget         *widget,
+                                         GdkEventSelection *event);
+gboolean _gtk_selection_request         (GtkWidget         *widget,
+                                         GdkEventSelection *event);
+gboolean _gtk_selection_incr_event      (GdkWindow         *window,
+                                         GdkEventProperty  *event);
+gboolean _gtk_selection_notify          (GtkWidget         *widget,
+                                         GdkEventSelection *event);
+gboolean _gtk_selection_property_notify (GtkWidget         *widget,
+                                         GdkEventProperty  *event);
+
+G_END_DECLS
+
+#endif /* __GTK_SELECTIONPRIVATE_H__ */
diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index 5bbd28c3a2..f06250c406 100644
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -40,6 +40,7 @@
 #include "gtkmenuitem.h"
 #include "gtkseparatormenuitem.h"
 #include "gtksettings.h"
+#include "gtkselectionprivate.h"
 #include "gtkstock.h"
 #include "gtktextbufferrichtext.h"
 #include "gtktextdisplay.h"
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 45b548a054..7be064828a 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -42,7 +42,7 @@
 #include "gtkmainprivate.h"
 #include "gtkmarshalers.h"
 #include "gtkrc.h"
-#include "gtkselection.h"
+#include "gtkselectionprivate.h"
 #include "gtksettingsprivate.h"
 #include "gtksizegroup-private.h"
 #include "gtkwidget.h"