[gtk/wip/hadess/window-present-docs: 4/5] window: Warn when gtk_window_present_with_time() is passed 0

[Bastien Nocera <hadess src gnome org>]

commit 14890fad4702d79bbc81ecc747234de5af27c434
Author: Bastien Nocera <hadess hadess net>
Date:   Wed Jul 25 17:43:02 2018 +0200

    window: Warn when gtk_window_present_with_time() is passed 0
    
    When 0 or GDK_CURRENT_TIME is passed to gtk_window_present_with_time(),
    print a warning so that the application developer knows that this isn't
    a supported use of the function, but carry on working for now.

 gtk/gtkwindow.c | 10 ++++++++++
 1 file changed, 10 insertions(+)
---
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 3da5073c08..c5b55ffd71 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -8780,6 +8780,7 @@ gtk_window_present_with_time (GtkWindow *window,
   GtkWindowPrivate *priv = gtk_window_get_instance_private (window);
   GtkWidget *widget;
   GdkSurface *surface;
+  static gsize warned_current_time = FALSE;
 
   g_return_if_fail (GTK_IS_WINDOW (window));
 
@@ -8796,6 +8797,15 @@ gtk_window_present_with_time (GtkWindow *window,
       /* Translate a timestamp of GDK_CURRENT_TIME appropriately */
       if (timestamp == GDK_CURRENT_TIME)
         {
+         if (g_once_init_enter (&warned_current_time))
+           {
+             gboolean warned = TRUE;
+             g_warning ("gtk_window_present_with_time() should not be called with 0, or "
+                        "GDK_CURRENT_TIME as a timestamp, the timestamp should instead be "
+                        "gathered at the time the user initiated the request for the window "
+                        "to be shown");
+             g_once_init_leave (&warned_current_time, warned);
+           }
 #ifdef GDK_WINDOWING_X11
          if (GDK_IS_X11_SURFACE(surface))
            {