GNOME.org
 

[gtk+] Give the GDK docs some love

commit 1f4bb70bac14f69edc69336627008c37a1c47f4c
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Feb 9 01:32:24 2011 -0500

    Give the GDK docs some love
    
    Reorganize some sections, drop the largely redundant multihead
    section, add some more information about multiple backends.

 docs/reference/gdk/Makefile.am    |    3 +-
 docs/reference/gdk/gdk-docs.sgml  |   15 +++--
 docs/reference/gdk/multihead.sgml |  128 -------------------------------------
 gdk/gdk.c                         |   26 ++------
 gdk/gdkdevice.c                   |    4 +-
 gdk/gdkdisplay.c                  |   34 ++++++----
 gdk/gdkdisplaymanager.c           |   43 ++++++++++++-
 gdk/gdkscreen.c                   |   17 +++--
 8 files changed, 87 insertions(+), 183 deletions(-)
---
diff --git a/docs/reference/gdk/Makefile.am b/docs/reference/gdk/Makefile.am
index 6eeffdb..8a70de8 100644
--- a/docs/reference/gdk/Makefile.am
+++ b/docs/reference/gdk/Makefile.am
@@ -51,8 +51,7 @@ MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=gdk
 
 # Extra SGML files that are included by DOC_MAIN_SGML_FILE
 content_files = 		\
-	version.xml		\
-	multihead.sgml
+	version.xml
 
 # Images to copy into HTML directory
 HTML_IMAGES = 				\
diff --git a/docs/reference/gdk/gdk-docs.sgml b/docs/reference/gdk/gdk-docs.sgml
index 7be6660..765d26c 100644
--- a/docs/reference/gdk/gdk-docs.sgml
+++ b/docs/reference/gdk/gdk-docs.sgml
@@ -8,21 +8,24 @@
   <bookinfo>
     <title>GDK Reference Manual</title>
     <releaseinfo>
-      for GDK &version;
-      The latest version of this documentation can be found on-line at
+      This document is for the GDK 3 library, version &version;
+      The latest version can be found online at
       <ulink role="online-location" url="http://library.gnome.org/devel/gdk/unstable/";>http://library.gnome.org/devel/gdk/unstable/</ulink>.
+      If you are looking for the older GDK 2 series of libraries,
+      they can be found under their version numbers; for example,
+      2.22 is available at
+      <ulink role="online-location" url="http://library.gnome.org/devel/gdk/2.22/";>http://library.gnome.org/devel/gdk/2.22/</ulink>.
     </releaseinfo>
   </bookinfo>
 
   <reference id="reference">
     <title>API Reference</title>
     <xi:include href="xml/general.xml" />
-    <xi:include href="multihead.sgml" />
-    <xi:include href="xml/gdkdisplay.xml" />
     <xi:include href="xml/gdkdisplaymanager.xml" />
-    <xi:include href="xml/gdkdevice.xml" />
-    <xi:include href="xml/gdkdevicemanager.xml" />
+    <xi:include href="xml/gdkdisplay.xml" />
     <xi:include href="xml/gdkscreen.xml" />
+    <xi:include href="xml/gdkdevicemanager.xml" />
+    <xi:include href="xml/gdkdevice.xml" />
     <xi:include href="xml/regions.xml" />
     <xi:include href="xml/pixbufs.xml" />
     <xi:include href="xml/colors.xml" />
diff --git a/gdk/gdk.c b/gdk/gdk.c
index 5182d72..e65f68b 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -54,27 +54,7 @@
  * The #GDK_WINDOWING_X11 macro is defined if the X11 backend
  * is supported.
  *
- * Use this macro to guard code that is specific to the X11-backend.
- * Since GDK may be configured with multiple backends, an additional
- * runtime check for the used backend is recommended:
- *
- * |[
- * #ifdef GDK_WINDOWING_X11
- *   if (GDK_IS_X11_DISPLAY (display))
- *     {
- *       /&ast; make X11-specific calls here &ast;/
- *     }
- *   else
- * #endif
- * #ifdef GDK_WINDOWING_QUARTZ
- *   if (GDK_IS_QUARTZ_DISPLAY (display))
- *     {
- *       /&ast; make Quartz-specific calls here &ast/
- *     }
- *   else
- * #endif
- *   g_error ("Unsupported GDK backend");
- * ]|
+ * Use this macro to guard code that is specific to the X11 backend.
  */
 
 /**
@@ -82,6 +62,8 @@
  *
  * The #GDK_WINDOWING_WIN32 macro is defined if the Win32 backend
  * is supported.
+ *
+ * Use this macro to guard code that is specific to the Win32 backend.
  */
 
 /**
@@ -89,6 +71,8 @@
  *
  * The #GDK_WINDOWING_QUARTZ macro is defined if the Quartz backend
  * is supported.
+ *
+ * Use this macro to guard code that is specific to the Quartz backend.
  */
 
 typedef struct _GdkPredicate  GdkPredicate;
diff --git a/gdk/gdkdevice.c b/gdk/gdkdevice.c
index 2cc3ea8..8106bea 100644
--- a/gdk/gdkdevice.c
+++ b/gdk/gdkdevice.c
@@ -32,7 +32,8 @@
  * @Title: GdkDevice
  * @See_also: #GdkDeviceManager
  *
- * The #GdkDevice object represents a single input device.
+ * The #GdkDevice object represents a single input device, such
+ * as a keyboard, a mouse, a touchpad, etc.
  *
  * See the #GdkDeviceManager documentation for more information
  * about the various kinds of master and slave devices, and their
@@ -48,7 +49,6 @@ struct _GdkAxisInfo
 
   gdouble min_axis;
   gdouble max_axis;
-
   gdouble min_value;
   gdouble max_value;
   gdouble resolution;
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index ad520b6..f3c4f0e 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -38,26 +38,32 @@
 
 /**
  * SECTION:gdkdisplay
- * @Short_description: Controls the keyboard/mouse pointer grabs and a set of <type>GdkScreen</type>s
+ * @Short_description: Controls a set of GdkScreens and their associated input devices
  * @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>
+ * <listitem>
+ *   To manage and provide information about input devices (pointers
+ *   and keyboards)
+ * </listitem>
+ * <listitem>
+ *   To manage and provide information about the available #GdkScreens
+ * </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.
+ * GdkDisplay objects are the GDK representation of an 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 instantiated by the application. It is also used to
+ * access the keyboard(s) and mouse pointer(s) of the display.
+ *
+ * Most of the input device handling has been factored out into
+ * the separate #GdkDeviceManager object. Every display has a
+ * device manager, which you can obtain using
+ * gdk_display_get_device_manager().
  */
 
 
diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c
index 160404d..508d609 100644
--- a/gdk/gdkdisplaymanager.c
+++ b/gdk/gdkdisplaymanager.c
@@ -56,6 +56,43 @@
  * The purpose of the #GdkDisplayManager singleton object is to offer
  * notification when displays appear or disappear or the default display
  * changes.
+ *
+ * You can use gdk_display_manager_get() to obtain the GdkDisplayManager
+ * singleton, but that should be rarely necessary. Typically, initializing
+ * GTK+ opens a display that you can work with without ever accessing the
+ * GdkDisplayManager.
+ *
+ * The GDK library can be built with support for multiple backends.
+ * The GdkDisplayManager object determines which backend is used
+ * at runtime.
+ *
+ * When writing backend-specific code that is supposed to work with
+ * multiple GDK backends, you have to consider both compile time and
+ * runtime. At compile time, use the #GDK_WINDOWING_X11, #GDK_WINDOWING_WIN32
+ * macros, etc. to find out which backends are present in the GDK library
+ * you are building your application against. At runtime, use type-check
+ * macros like GDK_IS_X11_DISPLAY() to find out which backend is in use:
+ *
+ * <example id="backend-specific">
+ * <title>Backend-specific code</title>
+ * <programlisting>
+ * #ifdef GDK_WINDOWING_X11
+ *   if (GDK_IS_X11_DISPLAY (display))
+ *     {
+ *       /&ast; make X11-specific calls here &ast;/
+ *     }
+ *   else
+ * #endif
+ * #ifdef GDK_WINDOWING_QUARTZ
+ *   if (GDK_IS_QUARTZ_DISPLAY (display))
+ *     {
+ *       /&ast; make Quartz-specific calls here &ast;/
+*     }
+ *   else
+ * #endif
+ *   g_error ("Unsupported GDK backend");
+ * </programlisting>
+ * </example>
  */
 
 
@@ -168,9 +205,9 @@ gdk_display_manager_get_property (GObject      *object,
  * Gets the singleton #GdkDisplayManager object.
  *
  * When called for the first time, this function consults the
- * <envar>GDK_BACKEND</envar> to find out which of the supported
- * GDK backends to use (in case GDK has been compiled with multiple
- * backends).
+ * <envar>GDK_BACKEND</envar> environment variable to find out which
+ * of the supported GDK backends to use (in case GDK has been compiled
+ * with multiple backends).
  *
  * Returns: (transfer none): The global #GdkDisplayManager singleton;
  *     gdk_parse_args(), gdk_init(), or gdk_init_check() must have
diff --git a/gdk/gdkscreen.c b/gdk/gdkscreen.c
index 4dd9164..ebdf2c6 100644
--- a/gdk/gdkscreen.c
+++ b/gdk/gdkscreen.c
@@ -34,14 +34,17 @@
  * @Short_description: Object representing a physical screen
  * @Title: GdkScreen
  *
- * #GdkScreen objects are the GDK representation of a physical screen. It is used
- * throughout GDK and GTK+ to specify which screen the top level windows
- * are to be displayed on.
- * It is also used to query the screen specification and default settings such as
- * the screen width (gdk_screen_get_width()), etc.
- *
- * Note that a screen may consist of multiple monitors which are merged to
- * form a large screen area.
+ * #GdkScreen objects are the GDK representation of the screen on
+ * which windows can be displayed and on which the pointer moves.
+ * X originally identified screens with physical screens, but
+ * nowadays it is more common to have a single #GdkScreen which
+ * combines several physical monitors (see gdk_screen_get_n_monitors()).
+ *
+ * GdkScreen is used throughout GDK and GTK+ to specify which screen
+ * the top level windows are to be displayed on. it is also used to
+ * query the screen specification and default settings such as
+ * the default visual (gdk_screen_get_system_visual()), the dimensions
+ * of the physical monitors (gdk_screen_get_monitor_geometry()), etc.
  */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]