Move GtkSelection docs inline

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

1 files changed, 71 insertions, 85 deletions

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