[gtk+/treeview-refactor: 229/257] docs: Move documentation to inline comments: gdkdisplay

[Tristan Van Berkom <tvb src gnome org>]

commit 236f15c3a908c1240b3c0be098d5f11fc0889f40
Author: Javier Jardón <jjardon gnome org>
Date:   Mon Nov 15 03:37:21 2010 +0100

    docs: Move documentation to inline comments: gdkdisplay

 docs/reference/gdk/tmpl/.gitignore      |    1 +
 docs/reference/gdk/tmpl/gdkdisplay.sgml |  502 -------------------------------
 gdk/gdkdisplay.c                        |   26 ++
 gdk/gdkdisplay.h                        |   22 ++
 4 files changed, 49 insertions(+), 502 deletions(-)
---
diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore
index a05bd1c..3914941 100644
--- a/docs/reference/gdk/tmpl/.gitignore
+++ b/docs/reference/gdk/tmpl/.gitignore
@@ -2,6 +2,7 @@ cairo_interaction.sgml
 colors.sgml
 dnd.sgml
 gdkapplaunchcontext.sgml
+gdkdisplay.sgml
 pixbufs.sgml
 regions.sgml
 windows.sgml
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index 2f30509..1dab470 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -34,6 +34,32 @@
 #include <glib.h>
 #include <math.h>
 
+
+/**
+ * SECTION:gdkdisplay
+ * @Short_description: Controls the keyboard/mouse pointer grabs and a set of <type>GdkScreen</type>s
+ * @Title: GdkDisplay
+ *
+ * #GdkDisplay objects purpose are two fold:
+ * <itemizedlist>
+ * <listitem><para>
+ *   To grab/ungrab keyboard focus and mouse pointer
+ * </para></listitem>
+ * <listitem><para>
+ *   To manage and provide information about the #GdkScreen(s)
+ *   available for this #GdkDisplay
+ * </para></listitem>
+ * </itemizedlist>
+ *
+ * #GdkDisplay objects are the GDK representation of the X Display which can be
+ * described as <emphasis>a workstation consisting of a keyboard a pointing
+ * device (such as a mouse) and one or more screens</emphasis>.
+ * It is used to open and keep track of various #GdkScreen objects currently
+ * instanciated by the application. It is also used to grab and release the keyboard
+ * and the mouse pointer.
+ */
+
+
 enum {
   OPENED,
   CLOSED,
diff --git a/gdk/gdkdisplay.h b/gdk/gdkdisplay.h
index 1b11b69..17afa4b 100644
--- a/gdk/gdkdisplay.h
+++ b/gdk/gdkdisplay.h
@@ -132,6 +132,28 @@ struct _GdkDisplayClass
 		  gboolean    is_error);
 };
 
+/**
+ * GdkDisplayPointerHooks:
+ * @get_pointer: Obtains the current pointer position and modifier state.
+ *  The position is given in coordinates relative to the screen containing
+ *  the pointer, which is returned in @screen.
+ * @window_get_pointer: Obtains the window underneath the mouse pointer.
+ *  Current pointer position and modifier state are returned in @x, @y and
+ *  @mask. The position is given in coordinates relative to @window.
+ * @window_at_pointer: Obtains the window underneath the mouse pointer,
+ *  returning the location of that window in @win_x, @win_y. Returns %NULL
+ *  if the window under the mouse pointer is not known to GDK (for example,
+ *  belongs to another application).
+ *
+ * A table of pointers to functions for getting quantities related to
+ * the current pointer position. Each #GdkDisplay has a table of this type,
+ * which can be set using gdk_display_set_pointer_hooks().
+ *
+ * This is only useful for such low-level tools as an event recorder.
+ * Applications should never have any reason to use this facility
+ *
+ * Since: 2.2
+ */
 struct _GdkDisplayPointerHooks
 {
   void (*get_pointer)              (GdkDisplay      *display,