[gtk+] Move GtkSelection docs inline
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk+] Move GtkSelection docs inline
- Date: Sat, 15 Jan 2011 00:21:24 +0000 (UTC)
commit abc8ac1a8bccf1ad187b55e35e81de1f9eae4785
Author: Matthias Clasen <mclasen redhat com>
Date: Fri Jan 14 19:20:56 2011 -0500
Move GtkSelection docs inline
At the same time, move private selection API to gtkselectionprivate.h
docs/reference/gtk/tmpl/.gitignore | 1 +
docs/reference/gtk/tmpl/gtkselection.sgml | 542 -----------------------------
gtk/gtkmain.c | 2 +-
gtk/gtkselection.c | 26 ++
gtk/gtkselection.h | 156 ++++-----
gtk/gtkselectionprivate.h | 37 ++
gtk/gtktextview.c | 1 +
gtk/gtkwidget.c | 2 +-
8 files changed, 138 insertions(+), 629 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 9f14331..dc9c131 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -60,6 +60,7 @@ gtkscale.sgml
gtkscalebutton.sgml
gtkscrollbar.sgml
gtkscrolledwindow.sgml
+gtkselection.sgml
gtkseparator.sgml
gtkseparatormenuitem.sgml
gtkseparatortoolitem.sgml
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 9a3b031..799db27 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 06aa146..4063bb2 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 6b409bb..bb3337d 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 831753f..0b965f5 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 5bbd28c..f06250c 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 45b548a..7be0648 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"
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
