]> Pileus Git - ~andy/gtk/blobdiff - gdk/gdk.c
Fix up for newer draft of wm-spec
[~andy/gtk] / gdk / gdk.c
index 003ad3484757731b635fcc59942a935de3ac3662..babe08028d6b3a108105546642349d3bb65073a9 100644 (file)
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -8,13 +8,11 @@
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.         See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  */
 
 /*
@@ -26,6 +24,8 @@
 
 #include "config.h"
 
+#define GDK_DISABLE_DEPRECATION_WARNINGS 1
+
 #include "gdkmain.h"
 
 #include "gdkinternals.h"
  * @Title: General
  *
  * This section describes the GDK initialization functions and miscellaneous
- * utility functions.
+ * utility functions, as well as deprecation facilities.
+ *
+ * The GDK and GTK+ headers annotate deprecated APIs in a way that produces
+ * compiler warnings if these deprecated APIs are used. The warnings
+ * can be turned off by defining the macro %GDK_DISABLE_DEPRECATION_WARNINGS
+ * before including the glib.h header.
+ *
+ * GDK and GTK+ also provide support for building applications against
+ * defined subsets of deprecated or new APIs. Define the macro
+ * %GDK_VERSION_MIN_REQUIRED to specify up to what version
+ * you want to receive warnings about deprecated APIs. Define the
+ * macro %GDK_VERSION_MAX_ALLOWED to specify the newest version
+ * whose API you want to use.
  */
 
+/**
+ * GDK_WINDOWING_X11:
+ *
+ * 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.
+ */
+
+/**
+ * GDK_WINDOWING_WIN32:
+ *
+ * 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.
+ */
+
+/**
+ * GDK_WINDOWING_QUARTZ:
+ *
+ * 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.
+ */
+
+/**
+ * GDK_DISABLE_DEPRECATION_WARNINGS:
+ *
+ * A macro that should be defined before including the gdk.h header.
+ * If it is defined, no compiler warnings will be produced for uses
+ * of deprecated GDK APIs.
+ */
 
 typedef struct _GdkPredicate  GdkPredicate;
 
@@ -69,50 +115,45 @@ struct _GdkThreadsDispatch
 
 /* Private variable declarations
  */
-static int gdk_initialized = 0;                            /* 1 if the library is initialized,
-                                                    * 0 otherwise.
-                                                    */
+static int gdk_initialized = 0;                     /* 1 if the library is initialized,
+                                                     * 0 otherwise.
+                                                     */
 
 static gchar  *gdk_progclass = NULL;
 
-static GMutex *gdk_threads_mutex = NULL;            /* Global GDK lock */
+static GMutex gdk_threads_mutex;
 
 static GCallback gdk_threads_lock = NULL;
 static GCallback gdk_threads_unlock = NULL;
 
 #ifdef G_ENABLE_DEBUG
 static const GDebugKey gdk_debug_keys[] = {
-  {"events",       GDK_DEBUG_EVENTS},
-  {"misc",         GDK_DEBUG_MISC},
-  {"dnd",          GDK_DEBUG_DND},
-  {"xim",          GDK_DEBUG_XIM},
+  {"events",        GDK_DEBUG_EVENTS},
+  {"misc",          GDK_DEBUG_MISC},
+  {"dnd",           GDK_DEBUG_DND},
+  {"xim",           GDK_DEBUG_XIM},
   {"nograbs",       GDK_DEBUG_NOGRABS},
-  {"colormap",     GDK_DEBUG_COLORMAP},
-  {"input",        GDK_DEBUG_INPUT},
-  {"cursor",       GDK_DEBUG_CURSOR},
-  {"multihead",            GDK_DEBUG_MULTIHEAD},
-  {"xinerama",     GDK_DEBUG_XINERAMA},
-  {"draw",         GDK_DEBUG_DRAW},
-  {"eventloop",            GDK_DEBUG_EVENTLOOP}
+  {"input",         GDK_DEBUG_INPUT},
+  {"cursor",        GDK_DEBUG_CURSOR},
+  {"multihead",     GDK_DEBUG_MULTIHEAD},
+  {"xinerama",      GDK_DEBUG_XINERAMA},
+  {"draw",          GDK_DEBUG_DRAW},
+  {"eventloop",     GDK_DEBUG_EVENTLOOP},
+  {"frames",        GDK_DEBUG_FRAMES}
 };
 
-static const int gdk_ndebug_keys = G_N_ELEMENTS (gdk_debug_keys);
-
-#endif /* G_ENABLE_DEBUG */
-
-#ifdef G_ENABLE_DEBUG
 static gboolean
 gdk_arg_debug_cb (const char *key, const char *value, gpointer user_data, GError **error)
 {
   guint debug_value = g_parse_debug_string (value,
-                                           (GDebugKey *) gdk_debug_keys,
-                                           gdk_ndebug_keys);
+                                            (GDebugKey *) gdk_debug_keys,
+                                            G_N_ELEMENTS (gdk_debug_keys));
 
   if (debug_value == 0 && value != NULL && strcmp (value, "") != 0)
     {
-      g_set_error (error, 
-                  G_OPTION_ERROR, G_OPTION_ERROR_FAILED,
-                  _("Error parsing option --gdk-debug"));
+      g_set_error (error,
+                   G_OPTION_ERROR, G_OPTION_ERROR_FAILED,
+                   _("Error parsing option --gdk-debug"));
       return FALSE;
     }
 
@@ -125,14 +166,14 @@ static gboolean
 gdk_arg_no_debug_cb (const char *key, const char *value, gpointer user_data, GError **error)
 {
   guint debug_value = g_parse_debug_string (value,
-                                           (GDebugKey *) gdk_debug_keys,
-                                           gdk_ndebug_keys);
+                                            (GDebugKey *) gdk_debug_keys,
+                                            G_N_ELEMENTS (gdk_debug_keys));
 
   if (debug_value == 0 && value != NULL && strcmp (value, "") != 0)
     {
-      g_set_error (error, 
-                  G_OPTION_ERROR, G_OPTION_ERROR_FAILED,
-                  _("Error parsing option --gdk-no-debug"));
+      g_set_error (error,
+                   G_OPTION_ERROR, G_OPTION_ERROR_FAILED,
+                   _("Error parsing option --gdk-no-debug"));
       return FALSE;
     }
 
@@ -168,9 +209,6 @@ static const GOptionEntry gdk_args[] = {
   { "display",      0, G_OPTION_FLAG_IN_MAIN, G_OPTION_ARG_STRING,   &_gdk_display_name,
     /* Description of --display=DISPLAY in --help output */    N_("X display to use"),
     /* Placeholder in --display=DISPLAY in --help output */    N_("DISPLAY") },
-  { "screen",       0, 0, G_OPTION_ARG_INT,      &_gdk_screen_number,
-    /* Description of --screen=SCREEN in --help output */      N_("X screen to use"),
-    /* Placeholder in --screen=SCREEN in --help output */      N_("SCREEN") },
 #ifdef G_ENABLE_DEBUG
   { "gdk-debug",    0, 0, G_OPTION_ARG_CALLBACK, gdk_arg_debug_cb,  
     /* Description of --gdk-debug=FLAGS in --help output */    N_("GDK debugging flags to set"),
@@ -185,20 +223,21 @@ static const GOptionEntry gdk_args[] = {
 /**
  * gdk_add_option_entries_libgtk_only:
  * @group: An option group.
- * 
+ *
  * Appends gdk option entries to the passed in option group. This is
  * not public API and must not be used by applications.
- **/
+ */
 void
 gdk_add_option_entries_libgtk_only (GOptionGroup *group)
 {
   g_option_group_add_entries (group, gdk_args);
-  g_option_group_add_entries (group, _gdk_windowing_args);
 }
 
 void
 gdk_pre_parse_libgtk_only (void)
 {
+  const char *rendering_mode;
+
   gdk_initialized = TRUE;
 
   /* We set the fallback program class here, rather than lazily in
@@ -213,31 +252,38 @@ gdk_pre_parse_libgtk_only (void)
     gchar *debug_string = getenv("GDK_DEBUG");
     if (debug_string != NULL)
       _gdk_debug_flags = g_parse_debug_string (debug_string,
-                                             (GDebugKey *) gdk_debug_keys,
-                                             gdk_ndebug_keys);
+                                              (GDebugKey *) gdk_debug_keys,
+                                              G_N_ELEMENTS (gdk_debug_keys));
   }
-#endif /* G_ENABLE_DEBUG */
+#endif  /* G_ENABLE_DEBUG */
 
   if (getenv ("GDK_NATIVE_WINDOWS"))
     {
-      _gdk_native_windows = TRUE;
-      /* Ensure that this is not propagated
-        to spawned applications */
+      g_warning ("The GDK_NATIVE_WINDOWS environment variable is not supported in GTK3.\n"
+                 "See the documentation for gdk_window_ensure_native() on how to get native windows.");
       g_unsetenv ("GDK_NATIVE_WINDOWS");
     }
 
-  g_type_init ();
+  rendering_mode = g_getenv ("GDK_RENDERING");
+  if (rendering_mode)
+    {
+      if (g_str_equal (rendering_mode, "similar"))
+        _gdk_rendering_mode = GDK_RENDERING_MODE_SIMILAR;
+      else if (g_str_equal (rendering_mode, "image"))
+        _gdk_rendering_mode = GDK_RENDERING_MODE_IMAGE;
+      else if (g_str_equal (rendering_mode, "recording"))
+        _gdk_rendering_mode = GDK_RENDERING_MODE_RECORDING;
+    }
 
-  /* Do any setup particular to the windowing system
-   */
-  _gdk_windowing_init ();  
+  /* Do any setup particular to the windowing system */
+  gdk_display_manager_get ();
 }
 
   
 /**
  * gdk_parse_args:
  * @argc: the number of command line arguments.
- * @argv: the array of command line arguments.
+ * @argv: (inout) (array length=argc): the array of command line arguments.
  * 
  * Parse command line arguments, and store for future
  * use by calls to gdk_display_open().
@@ -252,7 +298,7 @@ gdk_pre_parse_libgtk_only (void)
  **/
 void
 gdk_parse_args (int    *argc,
-               char ***argv)
+                char ***argv)
 {
   GOptionContext *option_context;
   GOptionGroup *option_group;
@@ -262,15 +308,14 @@ gdk_parse_args (int    *argc,
     return;
 
   gdk_pre_parse_libgtk_only ();
-  
+
   option_context = g_option_context_new (NULL);
   g_option_context_set_ignore_unknown_options (option_context, TRUE);
   g_option_context_set_help_enabled (option_context, FALSE);
   option_group = g_option_group_new (NULL, NULL, NULL, NULL, NULL);
   g_option_context_set_main_group (option_context, option_group);
-  
+
   g_option_group_add_entries (option_group, gdk_args);
-  g_option_group_add_entries (option_group, _gdk_windowing_args);
 
   if (!g_option_context_parse (option_context, argc, argv, &error))
     {
@@ -282,7 +327,7 @@ gdk_parse_args (int    *argc,
   GDK_NOTE (MISC, g_message ("progname: \"%s\"", g_get_prgname ()));
 }
 
-/** 
+/**
  * gdk_get_display_arg_name:
  *
  * Gets the display name specified in the command line arguments passed
@@ -293,29 +338,24 @@ gdk_parse_args (int    *argc,
  *
  * Since: 2.2
  */
-G_CONST_RETURN gchar *
+const gchar *
 gdk_get_display_arg_name (void)
 {
   if (!_gdk_display_arg_name)
-    {
-      if (_gdk_screen_number >= 0)
-       _gdk_display_arg_name = _gdk_windowing_substitute_screen_number (_gdk_display_name, _gdk_screen_number);
-      else
-       _gdk_display_arg_name = g_strdup (_gdk_display_name);
-   }
+    _gdk_display_arg_name = g_strdup (_gdk_display_name);
 
    return _gdk_display_arg_name;
 }
 
 /**
  * gdk_display_open_default_libgtk_only:
- * 
+ *
  * Opens the default display specified by command line arguments or
  * environment variables, sets it as the default display, and returns
  * it.  gdk_parse_args must have been called first. If the default
  * display has previously been set, simply returns that. An internal
  * function that should not be used by applications.
- * 
+ *
  * Return value: (transfer none): the default display, if it could be
  *   opened, otherwise %NULL.
  **/
@@ -325,25 +365,13 @@ gdk_display_open_default_libgtk_only (void)
   GdkDisplay *display;
 
   g_return_val_if_fail (gdk_initialized, NULL);
-  
+
   display = gdk_display_get_default ();
   if (display)
     return display;
 
   display = gdk_display_open (gdk_get_display_arg_name ());
 
-  if (!display && _gdk_screen_number >= 0)
-    {
-      g_free (_gdk_display_arg_name);
-      _gdk_display_arg_name = g_strdup (_gdk_display_name);
-      
-      display = gdk_display_open (_gdk_display_name);
-    }
-  
-  if (display)
-    gdk_display_manager_set_default_display (gdk_display_manager_get (),
-                                            display);
-  
   return display;
 }
 
@@ -352,20 +380,20 @@ gdk_display_open_default_libgtk_only (void)
  * @argc: (inout): the number of command line arguments.
  * @argv: (array length=argc) (inout): the array of command line arguments.
  *
- * Initializes the GDK library and connects to the X server, returning %TRUE on
- * success.
+ * Initializes the GDK library and connects to the windowing system,
+ * returning %TRUE on success.
  *
- * Any arguments used by GDK are removed from the array and @argc and @argv are
- * updated accordingly.
+ * Any arguments used by GDK are removed from the array and @argc and @argv
+ * are updated accordingly.
  *
- * GTK+ initializes GDK in gtk_init() and so this function is not usually needed
- * by GTK+ applications.
+ * GTK+ initializes GDK in gtk_init() and so this function is not usually
+ * needed by GTK+ applications.
  *
  * Returns: %TRUE if initialization succeeded.
  */
 gboolean
 gdk_init_check (int    *argc,
-               char ***argv)
+                char ***argv)
 {
   gdk_parse_args (argc, argv);
 
@@ -378,15 +406,15 @@ gdk_init_check (int    *argc,
  * @argc: (inout): the number of command line arguments.
  * @argv: (array length=argc) (inout): the array of command line arguments.
  *
- * Initializes the GDK library and connects to the X server.
+ * Initializes the GDK library and connects to the windowing system.
  * If initialization fails, a warning message is output and the application
  * terminates with a call to <literal>exit(1)</literal>.
  *
- * Any arguments used by GDK are removed from the array and @argc and @argv are
- * updated accordingly.
+ * Any arguments used by GDK are removed from the array and @argc and @argv
+ * are updated accordingly.
  *
- * GTK+ initializes GDK in gtk_init() and so this function is not usually needed
- * by GTK+ applications.
+ * GTK+ initializes GDK in gtk_init() and so this function is not usually
+ * needed by GTK+ applications.
  */
 void
 gdk_init (int *argc, char ***argv)
@@ -419,17 +447,13 @@ gdk_init (int *argc, char ***argv)
  * which protects all use of GTK+. That is, only one thread can use GTK+
  * at any given time.
  *
- * Unfortunately the above holds with the X11 backend only. With the
- * Win32 backend, GDK calls should not be attempted from multiple threads
- * at all.
+ * You must call gdk_threads_init() before executing any other GTK+ or
+ * GDK functions in a threaded GTK+ program.
  *
- * You must call g_thread_init() and gdk_threads_init() before executing
- * any other GTK+ or GDK functions in a threaded GTK+ program.
- *
- * Idles, timeouts, and input functions from GLib, such as g_idle_add(), are
- * executed outside of the main GTK+ lock.
- * So, if you need to call GTK+ inside of such a callback, you must surround
- * the callback with a gdk_threads_enter()/gdk_threads_leave() pair or use
+ * Idles, timeouts, and input functions from GLib, such as g_idle_add(),
+ * are executed outside of the main GTK+ lock. So, if you need to call
+ * GTK+ inside of such a callback, you must surround the callback with
+ * a gdk_threads_enter()/gdk_threads_leave() pair or use
  * gdk_threads_add_idle_full() which does this for you.
  * However, event dispatching from the mainloop is still executed within
  * the main GTK+ lock, so callback functions connected to event signals
@@ -459,7 +483,6 @@ gdk_init (int *argc, char ***argv)
  * {
  *   GtkWidget *window;
  *
- *   g_thread_init (NULL);
  *   gdk_threads_init (<!-- -->);
  *   gdk_threads_enter (<!-- -->);
  *
@@ -549,28 +572,28 @@ gdk_init (int *argc, char ***argv)
  *       say_something = (yes_or_no != data->what);
  *
  *       if(say_something)
- *     {
- *       /<!---->* set the variable *<!---->/
- *       yes_or_no = data->what;
- *     }
+ *      {
+ *        /<!---->* set the variable *<!---->/
+ *        yes_or_no = data->what;
+ *      }
  *
  *       /<!---->* Unlock the yes_or_no variable *<!---->/
  *       G_UNLOCK (yes_or_no);
  *
  *       if (say_something)
- *     {
- *       /<!---->* get GTK thread lock *<!---->/
- *       gdk_threads_enter (<!-- -->);
- *
- *       /<!---->* set label text *<!---->/
- *       if(data->what == YES_IT_IS)
- *         gtk_label_set_text (GTK_LABEL (data->label), "O yes, it is!");
- *       else
- *         gtk_label_set_text (GTK_LABEL (data->label), "O no, it isn't!");
- *
- *       /<!---->* release GTK thread lock *<!---->/
- *       gdk_threads_leave (<!-- -->);
- *     }
+ *      {
+ *        /<!---->* get GTK thread lock *<!---->/
+ *        gdk_threads_enter (<!-- -->);
+ *
+ *        /<!---->* set label text *<!---->/
+ *        if(data->what == YES_IT_IS)
+ *          gtk_label_set_text (GTK_LABEL (data->label), "O yes, it is!");
+ *        else
+ *          gtk_label_set_text (GTK_LABEL (data->label), "O no, it isn't!");
+ *
+ *        /<!---->* release GTK thread lock *<!---->/
+ *        gdk_threads_leave (<!-- -->);
+ *      }
  *     }
  *
  *   return NULL;
@@ -584,7 +607,6 @@ gdk_init (int *argc, char ***argv)
  *   pthread_t no_tid, yes_tid;
  *
  *   /<!---->* init threads *<!---->/
- *   g_thread_init (NULL);
  *   gdk_threads_init (<!-- -->);
  *   gdk_threads_enter (<!-- -->);
  *
@@ -626,16 +648,34 @@ gdk_init (int *argc, char ***argv)
  * }
  * </programlisting>
  * </informalexample>
+ *
+ * Unfortunately, all of the above documentation holds with the X11
+ * backend only. With the Win32 backend, GDK and GTK+ calls should not
+ * be attempted from multiple threads at all. Combining the GDK lock
+ * with other locks such as the Python global interpreter lock can be
+ * complicated.
+ *
+ * For these reason, the threading support has been deprecated in
+ * GTK+ 3.6. Instead of calling GTK+ directly from multiple threads,
+ * it is recommended to use g_idle_add(), g_main_context_invoke()
+ * and similar functions to make these calls from the main thread
+ * instead. The main thread is the thread which has called gtk_init()
+ * and is running the GTK+ mainloop. GTK+ itself will continue to
+ * use the GDK lock internally as long as the deprecated functionality
+ * is still available, and other libraries should probably do the same.
  */
 
 
 /**
  * gdk_threads_enter:
  *
- * This macro marks the beginning of a critical section in which GDK and
- * GTK+ functions can be called safely and without causing race
- * conditions.  Only one thread at a time can be in such a critial
+ * This function marks the beginning of a critical section in which
+ * GDK and GTK+ functions can be called safely and without causing race
+ * conditions. Only one thread at a time can be in such a critial
  * section.
+ *
+ * Deprecated:3.6: All GDK and GTK+ calls should be made from the main
+ *     thread
  */
 void
 gdk_threads_enter (void)
@@ -648,6 +688,9 @@ gdk_threads_enter (void)
  * gdk_threads_leave:
  *
  * Leaves a critical region begun with gdk_threads_enter().
+ *
+ * Deprecated:3.6: All GDK and GTK+ calls should be made from the main
+ *     thread
  */
 void
 gdk_threads_leave (void)
@@ -659,15 +702,13 @@ gdk_threads_leave (void)
 static void
 gdk_threads_impl_lock (void)
 {
-  if (gdk_threads_mutex)
-    g_mutex_lock (gdk_threads_mutex);
+  g_mutex_lock (&gdk_threads_mutex);
 }
 
 static void
 gdk_threads_impl_unlock (void)
 {
-  if (gdk_threads_mutex)
-    g_mutex_unlock (gdk_threads_mutex);
+  g_mutex_unlock (&gdk_threads_mutex);
 }
 
 /**
@@ -675,18 +716,16 @@ gdk_threads_impl_unlock (void)
  *
  * Initializes GDK so that it can be used from multiple threads
  * in conjunction with gdk_threads_enter() and gdk_threads_leave().
- * g_thread_init() must be called previous to this function.
  *
  * This call must be made before any use of the main loop from
  * GTK+; to be safe, call it before gtk_init().
- **/
+ *
+ * Deprecated:3.6: All GDK and GTK+ calls should be made from the main
+ *     thread
+ */
 void
 gdk_threads_init (void)
 {
-  if (!g_thread_supported ())
-    g_error ("g_thread_init() must be called before gdk_threads_init()");
-
-  gdk_threads_mutex = g_mutex_new ();
   if (!gdk_threads_lock)
     gdk_threads_lock = gdk_threads_impl_lock;
   if (!gdk_threads_unlock)
@@ -694,7 +733,7 @@ gdk_threads_init (void)
 }
 
 /**
- * gdk_threads_set_lock_functions:
+ * gdk_threads_set_lock_functions: (skip)
  * @enter_fn:   function called to guard GDK
  * @leave_fn: function called to release the guard
  *
@@ -720,14 +759,17 @@ gdk_threads_init (void)
  * This method must be called before gdk_threads_init(), and cannot
  * be called multiple times.
  *
+ * Deprecated:3.6: All GDK and GTK+ calls should be made from the main
+ *     thread
+ *
  * Since: 2.4
  **/
 void
 gdk_threads_set_lock_functions (GCallback enter_fn,
-                               GCallback leave_fn)
+                                GCallback leave_fn)
 {
   g_return_if_fail (gdk_threads_lock == NULL &&
-                   gdk_threads_unlock == NULL);
+                    gdk_threads_unlock == NULL);
 
   gdk_threads_lock = enter_fn;
   gdk_threads_unlock = leave_fn;
@@ -739,12 +781,12 @@ gdk_threads_dispatch (gpointer data)
   GdkThreadsDispatch *dispatch = data;
   gboolean ret = FALSE;
 
-  GDK_THREADS_ENTER ();
+  gdk_threads_enter ();
 
   if (!g_source_is_destroyed (g_main_current_source ()))
     ret = dispatch->func (dispatch->data);
 
-  GDK_THREADS_LEAVE ();
+  gdk_threads_leave ();
 
   return ret;
 }
@@ -764,7 +806,7 @@ gdk_threads_dispatch_free (gpointer data)
 /**
  * gdk_threads_add_idle_full:
  * @priority: the priority of the idle source. Typically this will be in the
- *            range btweeen #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE
+ *            range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE
  * @function: function to call
  * @data:     data to pass to @function
  * @notify: (allow-none):   function to call when the idle is removed, or %NULL
@@ -774,7 +816,7 @@ gdk_threads_dispatch_free (gpointer data)
  * removed from the list of event sources and will not be called again.
  *
  * This variant of g_idle_add_full() calls @function with the GDK lock
- * held. It can be thought of a MT-safe version for GTK+ widgets for the 
+ * held. It can be thought of a MT-safe version for GTK+ widgets for the
  * following use case, where you have to worry about idle_callback()
  * running in thread A and accessing @self after it has been finalized
  * in thread B:
@@ -814,12 +856,13 @@ gdk_threads_dispatch_free (gpointer data)
  * Return value: the ID (greater than 0) of the event source.
  *
  * Since: 2.12
+ * Rename to: gdk_threads_add_idle
  */
 guint
 gdk_threads_add_idle_full (gint           priority,
-                          GSourceFunc    function,
-                          gpointer       data,
-                          GDestroyNotify notify)
+                           GSourceFunc    function,
+                           gpointer       data,
+                           GDestroyNotify notify)
 {
   GdkThreadsDispatch *dispatch;
 
@@ -837,7 +880,7 @@ gdk_threads_add_idle_full (gint           priority,
 }
 
 /**
- * gdk_threads_add_idle:
+ * gdk_threads_add_idle: (skip)
  * @function: function to call
  * @data:     data to pass to @function
  *
@@ -852,7 +895,7 @@ gdk_threads_add_idle_full (gint           priority,
  */
 guint
 gdk_threads_add_idle (GSourceFunc    function,
-                     gpointer       data)
+                      gpointer       data)
 {
   return gdk_threads_add_idle_full (G_PRIORITY_DEFAULT_IDLE,
                                     function, data, NULL);
@@ -894,7 +937,7 @@ gdk_threads_add_idle (GSourceFunc    function,
  *    
  *    self->timeout_id = 0;
  *    
- *    return FALSE;
+ *    return G_SOURCE_REMOVE;
  * }
  *  
  * static void some_widget_do_stuff_later (SomeWidget *self)
@@ -916,6 +959,7 @@ gdk_threads_add_idle (GSourceFunc    function,
  * Return value: the ID (greater than 0) of the event source.
  * 
  * Since: 2.12
+ * Rename to: gdk_threads_add_timeout
  */
 guint
 gdk_threads_add_timeout_full (gint           priority,
@@ -941,7 +985,7 @@ gdk_threads_add_timeout_full (gint           priority,
 }
 
 /**
- * gdk_threads_add_timeout:
+ * gdk_threads_add_timeout: (skip)
  * @interval: the time between calls to the function, in milliseconds
  *             (1/1000ths of a second)
  * @function: function to call
@@ -973,15 +1017,16 @@ gdk_threads_add_timeout (guint       interval,
  * @interval: the time between calls to the function, in seconds
  * @function: function to call
  * @data:     data to pass to @function
- * @notify: (allow-none):   function to call when the timeout is removed, or %NULL
+ * @notify: (allow-none): function to call when the timeout is removed, or %NULL
  *
- * A variant of gdk_threads_add_timout_full() with second-granularity.
+ * A variant of gdk_threads_add_timeout_full() with second-granularity.
  * See g_timeout_add_seconds_full() for a discussion of why it is
  * a good idea to use this function if you don't need finer granularity.
  *
  *  Return value: the ID (greater than 0) of the event source.
  * 
  * Since: 2.14
+ * Rename to: gdk_threads_add_timeout_seconds
  */
 guint
 gdk_threads_add_timeout_seconds_full (gint           priority,
@@ -1007,7 +1052,7 @@ gdk_threads_add_timeout_seconds_full (gint           priority,
 }
 
 /**
- * gdk_threads_add_timeout_seconds:
+ * gdk_threads_add_timeout_seconds: (skip)
  * @interval: the time between calls to the function, in seconds
  * @function: function to call
  * @data:     data to pass to @function
@@ -1040,7 +1085,7 @@ gdk_threads_add_timeout_seconds (guint       interval,
  *
  * Returns: the program class.
  */
-G_CONST_RETURN char *
+const char *
 gdk_get_program_class (void)
 {
   return gdk_progclass;
@@ -1063,24 +1108,24 @@ gdk_set_program_class (const char *program_class)
 }
 
 /**
- * gdk_enable_multidevice:
+ * gdk_disable_multidevice:
  *
- * Enables multidevice support in GDK. This call must happen prior
+ * Disables multidevice support in GDK. This call must happen prior
  * to gdk_display_open(), gtk_init(), gtk_init_with_args() or
  * gtk_init_check() in order to take effect.
  *
- * Note that individual #GdkWindow<!-- -->s still need to explicitly
- * enable multidevice awareness through gdk_window_set_support_multidevice().
- *
- * This function must be called before initializing GDK.
+ * Most common GTK+ applications won't ever need to call this. Only
+ * applications that do mixed GDK/Xlib calls could want to disable
+ * multidevice support if such Xlib code deals with input devices in
+ * any way and doesn't observe the presence of XInput 2.
  *
  * Since: 3.0
- **/
+ */
 void
-gdk_enable_multidevice (void)
+gdk_disable_multidevice (void)
 {
   if (gdk_initialized)
     return;
 
-  _gdk_enable_multidevice = TRUE;
+  _gdk_disable_multidevice = TRUE;
 }